playwriter 0.0.63 → 0.0.89

package/src/relay-state.ts

@@ -0,0 +1,497 @@
+/**
+ * Centralized relay state: one immutable atom for domain state + runtime resources.
+ *
+ * Follows the zustand-centralized-state skill pattern:
+ * - Single Zustand vanilla store holds all relay state
+ * - setState() callbacks remain deterministic data transitions
+ * - Runtime resources (WebSocket/timers/pending callbacks) are co-located on
+ *   each extension entry in the same map
+ *
+ * See docs/plan-centralize-relay-state.md for the full refactor plan.
+ */
+import { createStore, type StoreApi } from 'zustand/vanilla'
+import type { WSContext } from 'hono/ws'
+import type { Protocol } from './cdp-types.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ConnectedTarget = {
+  sessionId: string
+  targetId: string
+  targetInfo: Protocol.Target.TargetInfo
+  frameIds: Set<string>
+}
+
+export type ExtensionInfo = {
+  browser?: string
+  email?: string
+  id?: string
+  /** playwriter package version the extension was built with (sent as ?v= query param) */
+  version?: string
+}
+
+export type ExtensionPendingRequest = {
+  resolve: (result: unknown) => void
+  reject: (error: Error) => void
+}
+
+/**
+ * Single aggregated extension object: domain state + runtime I/O.
+ */
+export type ExtensionEntry = {
+  id: string
+  info: ExtensionInfo
+  stableKey: string
+  connectedTargets: Map<string, ConnectedTarget>
+  // Runtime I/O fields
+  ws: WSContext | null
+  pendingRequests: Map<number, ExtensionPendingRequest>
+  messageId: number
+  pingInterval: ReturnType<typeof setInterval> | null
+}
+
+export type PlaywrightClient = {
+  id: string
+  extensionId: string | null
+  ws: WSContext
+}
+
+export type RelayState = {
+  extensions: Map<string, ExtensionEntry>
+  playwrightClients: Map<string, PlaywrightClient>
+}
+
+// ---------------------------------------------------------------------------
+// Store factory
+// ---------------------------------------------------------------------------
+
+export function createRelayStore(): StoreApi<RelayState> {
+  return createStore<RelayState>(() => ({
+    extensions: new Map(),
+    playwrightClients: new Map(),
+  }))
+}
+
+// ---------------------------------------------------------------------------
+// Derivation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Linear scan over extensions to find one by stableKey. With <10 extensions this is free.
+ * Returns the LAST (newest) match because during reconnect both old and new connections
+ * coexist briefly. Map iteration order is insertion order, so last wins.
+ */
+export function findExtensionByStableKey(state: RelayState, stableKey: string): ExtensionEntry | undefined {
+  let match: ExtensionEntry | undefined
+  for (const ext of state.extensions.values()) {
+    if (ext.stableKey === stableKey) {
+      match = ext
+    }
+  }
+  return match
+}
+
+/** Find which extension owns a CDP tab sessionId (e.g. "pw-tab-1"). */
+export function findExtensionIdByCdpSession(state: RelayState, cdpSessionId: string): string | null {
+  for (const [connectionId, ext] of state.extensions.entries()) {
+    if (ext.connectedTargets.has(cdpSessionId)) {
+      return connectionId
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Pure state transition functions
+//
+// Each takes RelayState + event data and returns a new RelayState.
+// No I/O, no side effects. Testable with data in / data out.
+// ---------------------------------------------------------------------------
+
+/**
+ * Add a new extension connection.
+ * Does NOT remove an existing connection with the same stableKey — that old
+ * connection stays routable until its WebSocket onClose fires and calls
+ * removeExtension(). This preserves in-flight message routing during reconnect.
+ * findExtensionByStableKey() returns the newest match so stableKey lookups
+ * resolve to the new connection immediately.
+ */
+export function addExtension(
+  state: RelayState,
+  {
+    id,
+    info,
+    stableKey,
+    ws,
+  }: {
+    id: string
+    info: ExtensionInfo
+    stableKey: string
+    ws: WSContext | null
+  },
+): RelayState {
+  const newExtensions = new Map(state.extensions)
+
+  newExtensions.set(id, {
+    id,
+    info,
+    stableKey,
+    connectedTargets: new Map(),
+    ws,
+    pendingRequests: new Map(),
+    messageId: 0,
+    pingInterval: null,
+  })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Remove an extension, its targets, and any playwright clients bound to it. */
+export function removeExtension(state: RelayState, { extensionId }: { extensionId: string }): RelayState {
+  if (!state.extensions.has(extensionId)) {
+    return state
+  }
+  const newExtensions = new Map(state.extensions)
+  newExtensions.delete(extensionId)
+
+  // Also remove playwright clients bound to this extension
+  const clientsToRemove = Array.from(state.playwrightClients.values())
+    .filter((client) => client.extensionId === extensionId)
+  if (clientsToRemove.length === 0) {
+    return { ...state, extensions: newExtensions }
+  }
+
+  const newClients = new Map(state.playwrightClients)
+  for (const client of clientsToRemove) {
+    newClients.delete(client.id)
+  }
+  return { ...state, extensions: newExtensions, playwrightClients: newClients }
+}
+
+/** Add a playwright client (state + ws handle co-located). */
+export function addPlaywrightClient(
+  state: RelayState,
+  { id, extensionId, ws }: { id: string; extensionId: string | null; ws: WSContext },
+): RelayState {
+  const newClients = new Map(state.playwrightClients)
+  newClients.set(id, { id, extensionId, ws })
+  return { ...state, playwrightClients: newClients }
+}
+
+/** Remove a playwright client. */
+export function removePlaywrightClient(state: RelayState, { clientId }: { clientId: string }): RelayState {
+  if (!state.playwrightClients.has(clientId)) {
+    return state
+  }
+  const newClients = new Map(state.playwrightClients)
+  newClients.delete(clientId)
+  return { ...state, playwrightClients: newClients }
+}
+
+/** Rebind all clients from one extension id to another. */
+export function rebindClientsToExtension(
+  state: RelayState,
+  { fromExtensionId, toExtensionId }: { fromExtensionId: string; toExtensionId: string },
+): RelayState {
+  if (fromExtensionId === toExtensionId) {
+    return state
+  }
+
+  let updated = false
+  const newClients = new Map(state.playwrightClients)
+  for (const [clientId, client] of newClients) {
+    if (client.extensionId !== fromExtensionId) {
+      continue
+    }
+    newClients.set(clientId, { ...client, extensionId: toExtensionId })
+    updated = true
+  }
+
+  if (!updated) {
+    return state
+  }
+
+  return { ...state, playwrightClients: newClients }
+}
+
+/** Update an extension entry's I/O fields (ws, pingInterval). */
+export function updateExtensionIO(
+  state: RelayState,
+  {
+    extensionId,
+    ws,
+    pingInterval,
+  }: {
+    extensionId: string
+    ws?: WSContext | null
+    pingInterval?: ReturnType<typeof setInterval> | null
+  },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, {
+    ...ext,
+    ...(ws !== undefined ? { ws } : {}),
+    ...(pingInterval !== undefined ? { pingInterval } : {}),
+  })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Add or replace one pending extension request callback pair. */
+export function addExtensionPendingRequest(
+  state: RelayState,
+  {
+    extensionId,
+    requestId,
+    pendingRequest,
+  }: {
+    extensionId: string
+    requestId: number
+    pendingRequest: ExtensionPendingRequest
+  },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+
+  const pendingRequests = new Map(ext.pendingRequests)
+  pendingRequests.set(requestId, pendingRequest)
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, pendingRequests })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Remove one pending extension request callback pair. */
+export function removeExtensionPendingRequest(
+  state: RelayState,
+  { extensionId, requestId }: { extensionId: string; requestId: number },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext || !ext.pendingRequests.has(requestId)) {
+    return state
+  }
+
+  const pendingRequests = new Map(ext.pendingRequests)
+  pendingRequests.delete(requestId)
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, pendingRequests })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Add a target to an extension's connectedTargets. No-op if extension doesn't exist. */
+export function addTarget(
+  state: RelayState,
+  {
+    extensionId,
+    sessionId,
+    targetId,
+    targetInfo,
+    existingFrameIds,
+  }: {
+    extensionId: string
+    sessionId: string
+    targetId: string
+    targetInfo: Protocol.Target.TargetInfo
+    /** Preserve existing frameIds if target already existed (update scenario). */
+    existingFrameIds?: Set<string>
+  },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+
+  const existingTarget = ext.connectedTargets.get(sessionId)
+  const newTargets = new Map(ext.connectedTargets)
+  newTargets.set(sessionId, {
+    sessionId,
+    targetId,
+    targetInfo,
+    frameIds: existingFrameIds ?? existingTarget?.frameIds ?? new Set(),
+  })
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Remove a target by sessionId. No-op if extension or target doesn't exist. */
+export function removeTarget(
+  state: RelayState,
+  { extensionId, sessionId }: { extensionId: string; sessionId: string },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext || !ext.connectedTargets.has(sessionId)) {
+    return state
+  }
+
+  const newTargets = new Map(ext.connectedTargets)
+  newTargets.delete(sessionId)
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Remove a crashed target by targetId (not sessionId). */
+export function removeTargetByCrash(
+  state: RelayState,
+  { extensionId, targetId }: { extensionId: string; targetId: string },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+
+  let found = false
+  const newTargets = new Map(ext.connectedTargets)
+  for (const [sid, target] of newTargets) {
+    if (target.targetId === targetId) {
+      newTargets.delete(sid)
+      found = true
+      break
+    }
+  }
+
+  if (!found) {
+    return state
+  }
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Update targetInfo on a target matched by targetId. */
+export function updateTargetInfo(
+  state: RelayState,
+  { extensionId, targetInfo }: { extensionId: string; targetInfo: Protocol.Target.TargetInfo },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+
+  let updated = false
+  const newTargets = new Map(ext.connectedTargets)
+  for (const [sid, target] of newTargets) {
+    if (target.targetId === targetInfo.targetId) {
+      newTargets.set(sid, { ...target, targetInfo })
+      updated = true
+      break
+    }
+  }
+
+  if (!updated) {
+    return state
+  }
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Add a frameId to a target's frameIds set. */
+export function addFrameId(
+  state: RelayState,
+  { extensionId, sessionId, frameId }: { extensionId: string; sessionId: string; frameId: string },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+  const target = ext.connectedTargets.get(sessionId)
+  if (!target) {
+    return state
+  }
+
+  // Already present — no-op
+  if (target.frameIds.has(frameId)) {
+    return state
+  }
+
+  const newFrameIds = new Set(target.frameIds)
+  newFrameIds.add(frameId)
+
+  const newTargets = new Map(ext.connectedTargets)
+  newTargets.set(sessionId, { ...target, frameIds: newFrameIds })
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+/** Remove a frameId from the target that owns it (scans all targets in the extension). */
+export function removeFrameId(
+  state: RelayState,
+  { extensionId, frameId }: { extensionId: string; frameId: string },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+
+  for (const [sid, target] of ext.connectedTargets) {
+    if (target.frameIds.has(frameId)) {
+      const newFrameIds = new Set(target.frameIds)
+      newFrameIds.delete(frameId)
+
+      const newTargets = new Map(ext.connectedTargets)
+      newTargets.set(sid, { ...target, frameIds: newFrameIds })
+
+      const newExtensions = new Map(state.extensions)
+      newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+      return { ...state, extensions: newExtensions }
+    }
+  }
+
+  return state
+}
+
+/**
+ * Update URL (and optionally title) on a target.
+ * Used by Page.frameNavigated (top-level) and Page.navigatedWithinDocument.
+ */
+export function updateTargetUrl(
+  state: RelayState,
+  {
+    extensionId,
+    sessionId,
+    url,
+    title,
+  }: {
+    extensionId: string
+    sessionId: string
+    url: string
+    title?: string
+  },
+): RelayState {
+  const ext = state.extensions.get(extensionId)
+  if (!ext) {
+    return state
+  }
+  const target = ext.connectedTargets.get(sessionId)
+  if (!target) {
+    return state
+  }
+
+  const newTargetInfo = {
+    ...target.targetInfo,
+    url,
+    ...(title !== undefined ? { title } : {}),
+  }
+
+  const newTargets = new Map(ext.connectedTargets)
+  newTargets.set(sessionId, { ...target, targetInfo: newTargetInfo })
+
+  const newExtensions = new Map(state.extensions)
+  newExtensions.set(extensionId, { ...ext, connectedTargets: newTargets })
+  return { ...state, extensions: newExtensions }
+}
+
+

package/src/resource.md

@@ -1,5 +1,3 @@
-
-
 You can also find `getByRole` to get elements on the page.
 
 ```javascript
@@ -14,9 +12,7 @@ await page.getByRole('link', { name: 'About' }).click()
 await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com')
 
 // For a heading with { "role": "heading", "name": "Welcome to Example.com" }
-const headingText = await page
-    .getByRole('heading', { name: 'Welcome to Example.com' })
-    .textContent()
+const headingText = await page.getByRole('heading', { name: 'Welcome to Example.com' }).textContent()
 console.log('Heading text:', headingText)
 ```
 
@@ -223,17 +219,14 @@ const pageTitle = await page.evaluate(() => document.title)
 
 // Modify page
 await page.evaluate(() => {
-    document.body.style.backgroundColor = 'red'
+  document.body.style.backgroundColor = 'red'
 })
 
 // Pass arguments to page context
 const sum = await page.evaluate(([a, b]) => a + b, [5, 3])
 
 // Work with elements
-const elementText = await page.evaluate(
-    (el) => el.textContent,
-    await page.getByRole('heading'),
-)
+const elementText = await page.evaluate((el) => el.textContent, await page.getByRole('heading'))
 ```
 
 ### Execute JavaScript on Element
@@ -244,8 +237,8 @@ const href = await page.getByRole('link').evaluate((el) => el.href)
 
 // Modify element
 await page.getByRole('button').evaluate((el) => {
-    el.style.backgroundColor = 'green'
-    el.disabled = true
+  el.style.backgroundColor = 'green'
+  el.disabled = true
 })
 
 // Scroll element into view
@@ -261,9 +254,7 @@ await page.getByText('Section').evaluate((el) => el.scrollIntoView())
 await page.getByLabel('Upload file').setInputFiles('/path/to/file.pdf')
 
 // Upload multiple files
-await page
-    .getByLabel('Upload files')
-    .setInputFiles(['/path/to/file1.pdf', '/path/to/file2.pdf'])
+await page.getByLabel('Upload files').setInputFiles(['/path/to/file1.pdf', '/path/to/file2.pdf'])
 
 // Clear file input
 await page.getByLabel('Upload file').setInputFiles([])
@@ -280,8 +271,7 @@ await page.locator('input[type="file"]').setInputFiles('/path/to/file.pdf')
 ```javascript
 // Wait for a specific request to complete and get its response
 const response = await page.waitForResponse(
-    (response) =>
-        response.url().includes('/api/user') && response.status() === 200,
+  (response) => response.url().includes('/api/user') && response.status() === 200,
 )
 
 // Get response data
@@ -295,11 +285,11 @@ console.log('Request method:', request.method())
 
 // Get all resources loaded by the page
 const resources = await page.evaluate(() =>
-    performance.getEntriesByType('resource').map((r) => ({
-        name: r.name,
-        duration: r.duration,
-        size: r.transferSize,
-    })),
+  performance.getEntriesByType('resource').map((r) => ({
+    name: r.name,
+    duration: r.duration,
+    size: r.transferSize,
+  })),
 )
 console.log('Page resources:', resources)
 ```
@@ -314,9 +304,9 @@ console.log('Page resources:', resources)
 
 // To trigger console messages from the page:
 await page.evaluate(() => {
-    console.log('This message will be captured')
-    console.error('This error will be captured')
-    console.warn('This warning will be captured')
+  console.log('This message will be captured')
+  console.error('This error will be captured')
+  console.warn('This warning will be captured')
 })
 
 // Then use the console_logs MCP tool to retrieve all captured messages
@@ -338,10 +328,7 @@ await page.waitForURL(/github\.com.*\/pull/)
 await page.waitForURL(/\/new-org/)
 
 // Wait for text to appear
-await page.waitForFunction(
-    (text) => document.body.textContent.includes(text),
-    'Success!',
-)
+await page.waitForFunction((text) => document.body.textContent.includes(text), 'Success!')
 
 // Wait for navigation
 await page.waitForURL('**/success')
@@ -350,10 +337,7 @@ await page.waitForURL('**/success')
 await waitForPageLoad({ page })
 
 // Wait for specific condition
-await page.waitForFunction(
-    (text) => document.querySelector('.status')?.textContent === text,
-    'Ready',
-)
+await page.waitForFunction((text) => document.querySelector('.status')?.textContent === text, 'Ready')
 ```
 
 ### Wait for Text to Appear or Disappear
@@ -374,30 +358,18 @@ await page.getByText('Success!').first().waitFor({ state: 'visible' })
 console.log('Processing finished and success message appeared')
 
 // Example: Wait for error message to disappear before proceeding
-await page
-    .getByText('Error: Please try again')
-    .first()
-    .waitFor({ state: 'hidden' })
+await page.getByText('Error: Please try again').first().waitFor({ state: 'hidden' })
 await page.getByRole('button', { name: 'Submit' }).click()
 
 // Example: Wait for confirmation text after form submission
 await page.getByRole('button', { name: 'Save' }).click()
-await page
-    .getByText('Your changes have been saved')
-    .first()
-    .waitFor({ state: 'visible' })
+await page.getByText('Your changes have been saved').first().waitFor({ state: 'visible' })
 console.log('Save confirmed')
 
 // Example: Wait for dynamic content to load
 await page.getByRole('button', { name: 'Load More' }).click()
-await page
-    .getByText('Loading more items...')
-    .first()
-    .waitFor({ state: 'visible' })
-await page
-    .getByText('Loading more items...')
-    .first()
-    .waitFor({ state: 'hidden' })
+await page.getByText('Loading more items...').first().waitFor({ state: 'visible' })
+await page.getByText('Loading more items...').first().waitFor({ state: 'hidden' })
 console.log('Additional items loaded')
 ```
 

package/src/scoped-fs.ts

@@ -150,7 +150,9 @@ export class ScopedFS {
     // Verify the real path is also within allowed directories (handles symlinks)
     const realStr = real.toString()
     if (!this.isPathAllowed(realStr)) {
-      const error = new Error(`EPERM: operation not permitted, realpath escapes allowed directories`) as NodeJS.ErrnoException
+      const error = new Error(
+        `EPERM: operation not permitted, realpath escapes allowed directories`,
+      ) as NodeJS.ErrnoException
       error.code = 'EPERM'
       throw error
     }
@@ -168,7 +170,9 @@ export class ScopedFS {
     const linkDir = path.dirname(resolvedLink)
     const resolvedTarget = path.resolve(linkDir, target.toString())
     if (!this.isPathAllowed(resolvedTarget)) {
-      const error = new Error(`EPERM: operation not permitted, symlink target outside allowed directories`) as NodeJS.ErrnoException
+      const error = new Error(
+        `EPERM: operation not permitted, symlink target outside allowed directories`,
+      ) as NodeJS.ErrnoException
       error.code = 'EPERM'
       throw error
     }
@@ -368,7 +372,9 @@ export class ScopedFS {
         const real = await fs.promises.realpath(resolved, options)
         const realStr = real.toString()
         if (!self.isPathAllowed(realStr)) {
-          const error = new Error(`EPERM: operation not permitted, realpath escapes allowed directories`) as NodeJS.ErrnoException
+          const error = new Error(
+            `EPERM: operation not permitted, realpath escapes allowed directories`,
+          ) as NodeJS.ErrnoException
           error.code = 'EPERM'
           throw error
         }