playwriter 0.0.33 → 0.0.37

package/src/cdp-relay.ts

@@ -41,6 +41,23 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     reject: (error: Error) => void
   }>()
   let extensionMessageId = 0
+  let extensionPingInterval: ReturnType<typeof setInterval> | null = null
+
+  function startExtensionPing() {
+    if (extensionPingInterval) {
+      clearInterval(extensionPingInterval)
+    }
+    extensionPingInterval = setInterval(() => {
+      extensionWs?.send(JSON.stringify({ method: 'ping' }))
+    }, 5000)
+  }
+
+  function stopExtensionPing() {
+    if (extensionPingInterval) {
+      clearInterval(extensionPingInterval)
+      extensionPingInterval = null
+    }
+  }
 
   function logCdpMessage({
     direction,
@@ -176,6 +193,40 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     })
   }
 
+  // Auto-create initial tab when PLAYWRITER_AUTO_ENABLE is set and no targets exist.
+  // This allows Playwright to connect and immediately have a page to work with.
+  async function maybeAutoCreateInitialTab(): Promise<void> {
+    if (!process.env.PLAYWRITER_AUTO_ENABLE) {
+      return
+    }
+    if (!extensionWs) {
+      return
+    }
+    if (connectedTargets.size > 0) {
+      return
+    }
+
+    try {
+      logger?.log(chalk.blue('Auto-creating initial tab for Playwright client'))
+      const result = await sendToExtension({ method: 'createInitialTab', timeout: 10000 }) as {
+        success: boolean
+        tabId: number
+        sessionId: string
+        targetInfo: Protocol.Target.TargetInfo
+      }
+      if (result.success && result.sessionId && result.targetInfo) {
+        connectedTargets.set(result.sessionId, {
+          sessionId: result.sessionId,
+          targetId: result.targetInfo.targetId,
+          targetInfo: result.targetInfo
+        })
+        logger?.log(chalk.blue(`Auto-created tab, now have ${connectedTargets.size} targets, url: ${result.targetInfo.url}`))
+      }
+    } catch (e) {
+      logger?.error('Failed to auto-create initial tab:', e)
+    }
+  }
+
   async function routeCdpCommand({ method, params, sessionId }: { method: string; params: any; sessionId?: string }) {
     switch (method) {
       case 'Browser.getVersion': {
@@ -192,10 +243,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         return {}
       }
 
+      // Target.setAutoAttach is a CDP command Playwright sends on first connection.
+      // We use it as the hook to auto-create an initial tab. If Playwright changes
+      // its initialization sequence in the future, this could be moved to a different command.
       case 'Target.setAutoAttach': {
         if (sessionId) {
           break
         }
+        await maybeAutoCreateInitialTab()
         return {}
       }
 
@@ -331,7 +386,26 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     }
   })
 
+  // Validate Origin header for WebSocket connections to prevent cross-origin attacks.
+  // Browsers always send Origin header for WebSocket connections, but Node.js clients don't.
+  // We reject browser origins (except chrome-extension://) to prevent malicious websites
+  // from connecting to the local WebSocket server.
+  function isAllowedOrigin(origin: string | undefined): boolean {
+    if (!origin) {
+      return true // Node.js clients don't send Origin
+    }
+    if (origin.startsWith('chrome-extension://')) {
+      return true // Chrome extension is allowed
+    }
+    return false // Reject browser origins (http://, https://, etc.)
+  }
+
   app.get('/cdp/:clientId?', (c, next) => {
+    const origin = c.req.header('origin')
+    if (!isAllowedOrigin(origin)) {
+      logger?.log(chalk.red(`Rejecting /cdp WebSocket from origin: ${origin}`))
+      return c.text('Forbidden', 403)
+    }
     if (token) {
       const url = new URL(c.req.url, 'http://localhost')
       const providedToken = url.searchParams.get('token')
@@ -344,15 +418,16 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     const clientId = c.req.param('clientId') || 'default'
 
     return {
-      onOpen(_event, ws) {
+      async onOpen(_event, ws) {
         if (playwrightClients.has(clientId)) {
           logger?.log(chalk.red(`Rejecting duplicate client ID: ${clientId}`))
           ws.close(1000, 'Client ID already connected')
           return
         }
 
+        // Add client first so it can receive Target.attachedToTarget events
         playwrightClients.set(clientId, { id: clientId, ws })
-        logger?.log(chalk.green(`Playwright client connected: ${clientId} (${playwrightClients.size} total)`))
+        logger?.log(chalk.green(`Playwright client connected: ${clientId} (${playwrightClients.size} total) (extension? ${!!extensionWs}) (${connectedTargets.size} pages)`))
       },
 
       async onMessage(event, ws) {
@@ -404,6 +479,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                   waitingForDebugger: false
                 }
               } satisfies CDPEventFor<'Target.attachedToTarget'>
+              if (!target.targetInfo.url) {
+                logger?.error(chalk.red('[Server] WARNING: Target.attachedToTarget sent with empty URL!'), JSON.stringify(attachedPayload))
+              }
               logger?.log(chalk.magenta('[Server] Target.attachedToTarget full payload:'), JSON.stringify(attachedPayload))
               sendToPlaywright({
                 message: attachedPayload,
@@ -424,6 +502,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                   }
                 }
               } satisfies CDPEventFor<'Target.targetCreated'>
+              if (!target.targetInfo.url) {
+                logger?.error(chalk.red('[Server] WARNING: Target.targetCreated sent with empty URL!'), JSON.stringify(targetCreatedPayload))
+              }
               logger?.log(chalk.magenta('[Server] Target.targetCreated full payload:'), JSON.stringify(targetCreatedPayload))
               sendToPlaywright({
                 message: targetCreatedPayload,
@@ -448,6 +529,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
                   waitingForDebugger: false
                 }
               } satisfies CDPEventFor<'Target.attachedToTarget'>
+              if (!target.targetInfo.url) {
+                logger?.error(chalk.red('[Server] WARNING: Target.attachedToTarget (from attachToTarget) sent with empty URL!'), JSON.stringify(attachedPayload))
+              }
               logger?.log(chalk.magenta('[Server] Target.attachedToTarget (from attachToTarget) payload:'), JSON.stringify(attachedPayload))
               sendToPlaywright({
                 message: attachedPayload,
@@ -483,7 +567,14 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
     }
   }))
 
-  app.get('/extension', upgradeWebSocket(() => {
+  app.get('/extension', (c, next) => {
+    const origin = c.req.header('origin')
+    if (!isAllowedOrigin(origin)) {
+      logger?.log(chalk.red(`Rejecting /extension WebSocket from origin: ${origin}`))
+      return c.text('Forbidden', 403)
+    }
+    return next()
+  }, upgradeWebSocket(() => {
     return {
       onOpen(_event, ws) {
         if (extensionWs) {
@@ -504,6 +595,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         }
 
         extensionWs = ws
+        startExtensionPing()
         logger?.log('Extension connected with clean state')
       },
 
@@ -517,7 +609,7 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
           return
         }
 
-        if ('id' in message) {
+        if (message.id !== undefined) {
           const pending = extensionPendingRequests.get(message.id)
           if (!pending) {
             logger?.log('Unexpected response with id:', message.id)
@@ -531,6 +623,8 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
           } else {
             pending.resolve(message.result)
           }
+        } else if (message.method === 'pong') {
+          // Keep-alive response, nothing to do
         } else if (message.method === 'log') {
           const { level, args } = message.params
           const logFn = (logger as any)?.[level] || logger?.log
@@ -558,6 +652,9 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
           if (method === 'Target.attachedToTarget') {
             const targetParams = params as Protocol.Target.AttachedToTargetEvent
 
+            if (!targetParams.targetInfo.url) {
+              logger?.error(chalk.red('[Extension] WARNING: Target.attachedToTarget received with empty URL!'), JSON.stringify({ method, params: targetParams, sessionId }))
+            }
             logger?.log(chalk.yellow('[Extension] Target.attachedToTarget full payload:'), JSON.stringify({ method, params: targetParams, sessionId }))
 
             // Check if we already sent this target to clients (e.g., from Target.setAutoAttach response)
@@ -681,7 +778,8 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
       },
 
       onClose(event, ws) {
-        logger?.log('Extension disconnected')
+        logger?.log(`Extension disconnected: code=${event.code} reason=${event.reason || 'none'}`)
+        stopExtensionPing()
 
         // If this is an old connection closing after we've already established a new one,
         // don't clear the global state

package/src/cdp-session.ts

@@ -3,12 +3,26 @@ import type { Page } from 'playwright-core'
 import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'
 import type { CDPResponseBase, CDPEventBase } from './cdp-types.js'
 
+/**
+ * Common interface for CDP sessions that works with both our CDPSession
+ * and Playwright's CDPSession. Use this type when you want to accept either.
+ *
+ * Uses loose types so Playwright's CDPSession (which uses Protocol.Events)
+ * is assignable to this interface.
+ */
+export interface ICDPSession {
+  send(method: string, params?: object): Promise<unknown>
+  on(event: string, callback: (params: any) => void): unknown
+  off(event: string, callback: (params: any) => void): unknown
+  detach(): Promise<void>
+}
+
 interface PendingRequest {
   resolve: (result: unknown) => void
   reject: (error: Error) => void
 }
 
-export class CDPSession {
+export class CDPSession implements ICDPSession {
   private ws: WebSocket
   private pendingRequests = new Map<number, PendingRequest>()
   private eventListeners = new Map<string, Set<(params: unknown) => void>>()
@@ -90,15 +104,48 @@ export class CDPSession {
     })
   }
 
-  on<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void) {
+  on<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
     if (!this.eventListeners.has(event)) {
       this.eventListeners.set(event, new Set())
     }
     this.eventListeners.get(event)!.add(callback as (params: unknown) => void)
+    return this
+  }
+
+  /** Alias for `on` - matches Playwright's CDPSession interface */
+  addListener<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): this {
+    return this.on(event, callback)
   }
 
-  off<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void) {
+  off<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
     this.eventListeners.get(event)?.delete(callback as (params: unknown) => void)
+    return this
+  }
+
+  /** Alias for `off` - matches Playwright's CDPSession interface */
+  removeListener<K extends keyof ProtocolMapping.Events>(
+    event: K,
+    callback: (params: ProtocolMapping.Events[K][0]) => void,
+  ): this {
+    return this.off(event, callback)
+  }
+
+  /** Listen for an event once, then automatically remove the listener */
+  once<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
+    const onceCallback = (params: ProtocolMapping.Events[K][0]) => {
+      this.off(event, onceCallback)
+      callback(params)
+    }
+    return this.on(event, onceCallback)
+  }
+
+  /** Alias for `close` - matches Playwright's CDPSession interface */
+  detach(): Promise<void> {
+    this.close()
+    return Promise.resolve()
   }
 
   close() {

package/src/debugger.ts

@@ -1,4 +1,4 @@
-import type { CDPSession } from './cdp-session.js'
+import type { ICDPSession, CDPSession } from './cdp-session.js'
 import type { Protocol } from 'devtools-protocol'
 
 export interface BreakpointInfo {
@@ -61,7 +61,8 @@ export class Debugger {
    * Creates a new Debugger instance.
    *
    * @param options - Configuration options
-   * @param options.cdp - A CDPSession instance for sending CDP commands
+   * @param options.cdp - A CDPSession instance for sending CDP commands (works with both
+   *                      our CDPSession and Playwright's CDPSession)
    *
    * @example
    * ```ts
@@ -69,8 +70,9 @@ export class Debugger {
    * const dbg = new Debugger({ cdp })
    * ```
    */
-  constructor({ cdp }: { cdp: CDPSession }) {
-    this.cdp = cdp
+  constructor({ cdp }: { cdp: ICDPSession }) {
+    // Cast to CDPSession for internal type safety - at runtime both are compatible
+    this.cdp = cdp as CDPSession
     this.setupEventListeners()
   }
 

package/src/editor.ts

@@ -1,4 +1,4 @@
-import type { CDPSession } from './cdp-session.js'
+import type { ICDPSession, CDPSession } from './cdp-session.js'
 
 export interface ReadResult {
   content: string
@@ -52,8 +52,9 @@ export class Editor {
   private stylesheets = new Map<string, string>()
   private sourceCache = new Map<string, string>()
 
-  constructor({ cdp }: { cdp: CDPSession }) {
-    this.cdp = cdp
+  constructor({ cdp }: { cdp: ICDPSession }) {
+    // Cast to CDPSession for internal type safety - at runtime both are compatible
+    this.cdp = cdp as CDPSession
     this.setupEventListeners()
   }
 

package/src/index.ts

@@ -1,2 +1,10 @@
 export * from './cdp-relay.js'
 export * from './utils.js'
+export { CDPSession, getCDPSessionForPage } from './cdp-session.js'
+export type { ICDPSession } from './cdp-session.js'
+export { Editor } from './editor.js'
+export type { ReadResult, SearchMatch, EditResult } from './editor.js'
+export { Debugger } from './debugger.js'
+export type { BreakpointInfo, LocationInfo, EvaluateResult, ScriptInfo } from './debugger.js'
+export { getAriaSnapshot, showAriaRefLabels, hideAriaRefLabels } from './aria-snapshot.js'
+export type { AriaRef, AriaSnapshotResult } from './aria-snapshot.js'