playwriter 0.1.0 → 0.3.0

package/src/performance-examples.ts

@@ -0,0 +1,186 @@
+// Example snippets for profiling website performance with Playwriter and CDP.
+
+import { console, getCDPSession, page } from './debugger-examples-types.js'
+
+type PerfMetrics = {
+  paints: Record<string, number>
+  lcp: number
+  cls: number
+}
+
+type ObservedPerfEntry = {
+  name: string
+  startTime: number
+  duration: number
+  hadRecentInput?: boolean
+  value?: number
+  interactionId?: number
+}
+
+type NavigationTimingEntry = {
+  responseStart: number
+  domContentLoadedEventEnd: number
+  loadEventEnd: number
+}
+
+type LongTaskEntry = {
+  startTime: number
+  duration: number
+}
+
+type EventTimingEntry = {
+  name: string
+  duration: number
+  interactionId: number
+}
+
+// Example: Collect navigation timing and basic web vitals from the current page
+async function collectWebVitals() {
+  await page.evaluate(() => {
+    const metrics: PerfMetrics = {
+      paints: {},
+      lcp: 0,
+      cls: 0,
+    }
+
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwPerfMetrics?: PerfMetrics
+    }
+
+    perfGlobal.__pwPerfMetrics = metrics
+
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as ObservedPerfEntry[]) {
+        metrics.paints[entry.name] = entry.startTime
+      }
+    }).observe({ type: 'paint', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries() as ObservedPerfEntry[]
+      const lastEntry = entries[entries.length - 1]
+      if (!lastEntry) {
+        return
+      }
+      metrics.lcp = lastEntry.startTime
+    }).observe({ type: 'largest-contentful-paint', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as ObservedPerfEntry[]) {
+        if (entry.hadRecentInput) {
+          continue
+        }
+        metrics.cls += entry.value || 0
+      }
+    }).observe({ type: 'layout-shift', buffered: true } as never)
+  })
+
+  await page.reload({ waitUntil: 'domcontentloaded' })
+
+  const report = await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwPerfMetrics?: PerfMetrics
+    }
+    const nav = performance.getEntriesByType('navigation' as never)[0] as unknown as
+      | NavigationTimingEntry
+      | undefined
+    const metrics = perfGlobal.__pwPerfMetrics
+
+    return {
+      ttfb: nav?.responseStart || 0,
+      domContentLoaded: nav?.domContentLoadedEventEnd || 0,
+      load: nav?.loadEventEnd || 0,
+      fcp: metrics?.paints['first-contentful-paint'] || 0,
+      lcp: metrics?.lcp || 0,
+      cls: metrics?.cls || 0,
+    }
+  })
+
+  console.log(report)
+}
+
+// Example: Measure the biggest transferred requests with raw CDP network events
+async function collectHeaviestRequests() {
+  const cdp = await getCDPSession({ page })
+  await cdp.send('Network.enable')
+  await cdp.send('Network.setCacheDisabled', { cacheDisabled: true })
+
+  const responses = new Map<string, { url: string; mimeType: string }>()
+  const finished = new Map<string, number>()
+
+  cdp.on('Network.responseReceived', (event) => {
+    responses.set(event.requestId, {
+      url: event.response.url,
+      mimeType: event.response.mimeType,
+    })
+  })
+
+  cdp.on('Network.loadingFinished', (event) => {
+    finished.set(event.requestId, event.encodedDataLength)
+  })
+
+  await page.reload({ waitUntil: 'domcontentloaded' })
+
+  const largest = [...responses.entries()]
+    .map(([requestId, response]) => {
+      return {
+        url: response.url,
+        mimeType: response.mimeType,
+        bytes: finished.get(requestId) || 0,
+      }
+    })
+    .sort((a, b) => b.bytes - a.bytes)
+    .slice(0, 10)
+
+  console.log(largest)
+}
+
+// Example: Check whether interactivity is blocked by long tasks or slow events
+async function measureInteractivity() {
+  await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwLongTasks?: LongTaskEntry[]
+      __pwEventTimings?: EventTimingEntry[]
+    }
+
+    perfGlobal.__pwLongTasks = []
+    perfGlobal.__pwEventTimings = []
+
+    new PerformanceObserver((list) => {
+      perfGlobal.__pwLongTasks?.push(
+        ...(list.getEntries() as ObservedPerfEntry[]).map((entry) => ({
+          startTime: entry.startTime,
+          duration: entry.duration,
+        })),
+      )
+    }).observe({ type: 'longtask', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      perfGlobal.__pwEventTimings?.push(
+        ...(list.getEntries() as ObservedPerfEntry[]).map((entry) => ({
+          name: entry.name,
+          duration: entry.duration,
+          interactionId: entry.interactionId || 0,
+        })),
+      )
+    }).observe({ type: 'event', buffered: true, durationThreshold: 16 } as never)
+  })
+
+  const button = page.getByRole('button').first()
+  await button.click()
+
+  const report = await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwLongTasks?: LongTaskEntry[]
+      __pwEventTimings?: EventTimingEntry[]
+    }
+
+    return {
+      longTasks: (perfGlobal.__pwLongTasks || []).filter((entry) => entry.duration >= 50),
+      events: (perfGlobal.__pwEventTimings || []).filter((entry) => entry.interactionId !== 0),
+    }
+  })
+
+  console.log(report)
+}
+
+export { collectWebVitals, collectHeaviestRequests, measureInteractivity }

package/src/react-source.ts

@@ -11,6 +11,67 @@ export interface ReactSourceLocation {
   componentName: string | null
 }
 
+export type ReactSerializedProp =
+  | string
+  | number
+  | boolean
+  | null
+  | ReactSerializedProp[]
+  | { [key: string]: ReactSerializedProp }
+
+export interface ReactComponentHierarchyItem {
+  componentName: string | null
+  source: Omit<ReactSourceLocation, 'componentName'> | null
+  props: ReactSerializedProp
+}
+
+export interface ReactComponentInfo {
+  componentName: string | null
+  source: Omit<ReactSourceLocation, 'componentName'> | null
+  hierarchy: ReactComponentHierarchyItem[]
+  props: ReactSerializedProp
+}
+
+type ReactInspectableValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | null
+  | undefined
+  | object
+  | ((...args: never[]) => ReactInspectableValue)
+
+type BrowserElement = object
+
+interface BippySourceFrame {
+  fileName?: string | null
+  lineNumber?: number | null
+  columnNumber?: number | null
+  functionName?: string | null
+}
+
+interface BippyFiber {
+  return?: BippyFiber | null
+  type?: ReactInspectableValue
+  memoizedProps?: ReactInspectableValue
+}
+
+interface BippyRuntime {
+  getFiberFromHostInstance(el: BrowserElement): BippyFiber | null
+  getSource(fiber: BippyFiber): Promise<BippySourceFrame | null>
+  getOwnerStack(fiber: BippyFiber): Promise<BippySourceFrame[]>
+  getDisplayName(type: ReactInspectableValue): string | null
+  isCompositeFiber(fiber: BippyFiber): boolean
+  normalizeFileName(fileName: string): string
+  isSourceFile(fileName: string): boolean
+}
+
+declare global {
+  var __bippy: BippyRuntime | undefined
+}
+
 let bippyCode: string | null = null
 
 function getBippyCode(): string {
@@ -23,6 +84,31 @@ function getBippyCode(): string {
   return bippyCode
 }
 
+async function getPageFromTarget(target: Locator | ElementHandle): Promise<Page> {
+  if ('page' in target) {
+    return target.page()
+  }
+
+  const frame = await target.ownerFrame()
+  if (!frame) {
+    throw new Error('Could not get frame from element handle')
+  }
+  return frame.page()
+}
+
+async function ensureBippy({ page, cdp }: { page: Page; cdp: ICDPSession }): Promise<void> {
+  const hasBippy = await page.evaluate(() => {
+    return !!globalThis.__bippy
+  })
+
+  if (hasBippy) {
+    return
+  }
+
+  const code = getBippyCode()
+  await cdp.send('Runtime.evaluate', { expression: code })
+}
+
 export async function getReactSource({
   locator,
   cdp: cdpSession,
@@ -31,25 +117,27 @@ export async function getReactSource({
   cdp: ICDPSession
 }): Promise<ReactSourceLocation | null> {
   const cdp = cdpSession
-  const page: Page = 'page' in locator && typeof locator.page === 'function' ? locator.page() : (locator as any)._page
-
-  if (!page) {
-    throw new Error('Could not get page from locator')
-  }
-
-  const hasBippy = await page.evaluate(() => !!(globalThis as any).__bippy)
-
-  if (!hasBippy) {
-    const code = getBippyCode()
-    await cdp.send('Runtime.evaluate', { expression: code })
-  }
+  const page = await getPageFromTarget(locator)
+  await ensureBippy({ page, cdp })
 
-  const result = await (locator as any).evaluate(async (el: any) => {
-    const bippy = (globalThis as any).__bippy
+  const evaluateReactSource = async (
+    el: BrowserElement,
+  ): Promise<(ReactSourceLocation & { _notFound?: undefined }) | { _notFound: 'fiber' | 'source' }> => {
+    const bippy = globalThis.__bippy
     if (!bippy) {
       throw new Error('bippy not loaded')
     }
 
+    // bippy.normalizeFileName strips "/app-pages-browser/" but not the parenthesized
+    // form "/(app-pages-browser)/" that Next.js webpack actually uses. This strips
+    // all webpack layer prefixes like (app-pages-browser), (ssr), (rsc), etc.
+    const cleanName = (name: string): string => {
+      let f = bippy.normalizeFileName(name)
+      f = f.replace(/^\/?\([-\w]+\)\//, '')
+      f = f.replace(/^\.\//, '')
+      return f
+    }
+
     const fiber = bippy.getFiberFromHostInstance(el)
     if (!fiber) {
       return { _notFound: 'fiber' as const }
@@ -58,7 +146,7 @@ export async function getReactSource({
     const source = await bippy.getSource(fiber)
     if (source) {
       return {
-        fileName: source.fileName ? bippy.normalizeFileName(source.fileName) : null,
+        fileName: source.fileName ? cleanName(source.fileName) : null,
         lineNumber: source.lineNumber ?? null,
         columnNumber: source.columnNumber ?? null,
         componentName: source.functionName ?? bippy.getDisplayName(fiber.type) ?? null,
@@ -69,7 +157,7 @@ export async function getReactSource({
     for (const frame of ownerStack) {
       if (frame.fileName && bippy.isSourceFile(frame.fileName)) {
         return {
-          fileName: bippy.normalizeFileName(frame.fileName),
+          fileName: cleanName(frame.fileName),
           lineNumber: frame.lineNumber ?? null,
           columnNumber: frame.columnNumber ?? null,
           componentName: frame.functionName ?? null,
@@ -78,16 +166,214 @@ export async function getReactSource({
     }
 
     return { _notFound: 'source' as const }
-  })
+  }
+
+  const resolveResult = (
+    result: (ReactSourceLocation & { _notFound?: undefined }) | { _notFound: 'fiber' | 'source' },
+  ): ReactSourceLocation | null => {
+    if (result?._notFound) {
+      if (result._notFound === 'fiber') {
+        console.warn('[getReactSource] no fiber found - is this a React element?')
+      } else {
+        console.warn('[getReactSource] no source location found - is this a React dev build?')
+      }
+      return null
+    }
+
+    return result
+  }
+
+  if ('page' in locator) {
+    return resolveResult(await locator.evaluate(evaluateReactSource))
+  }
+
+  return resolveResult(await locator.evaluate(evaluateReactSource))
+}
+
+export async function getReactComponentInfo({
+  locator,
+  cdp: cdpSession,
+}: {
+  locator: Locator | ElementHandle
+  cdp: ICDPSession
+}): Promise<ReactComponentInfo | null> {
+  const cdp = cdpSession
+  const page = await getPageFromTarget(locator)
+  await ensureBippy({ page, cdp })
+
+  const evaluateReactComponentInfo = async (el: BrowserElement): Promise<ReactComponentInfo | null> => {
+    const bippy = globalThis.__bippy
+    if (!bippy) {
+      throw new Error('bippy not loaded')
+    }
+
+    // bippy.normalizeFileName strips "/app-pages-browser/" but not the parenthesized
+    // form "/(app-pages-browser)/" that Next.js webpack actually uses. This strips
+    // all webpack layer prefixes like (app-pages-browser), (ssr), (rsc), etc.
+    const cleanName = (name: string): string => {
+      let f = bippy.normalizeFileName(name)
+      f = f.replace(/^\/?\([-\w]+\)\//, '')
+      f = f.replace(/^\.\//, '')
+      return f
+    }
+
+    const serializeReactValue = (
+      value: ReactInspectableValue,
+      options: { depth: number; seen: WeakSet<object> },
+    ): ReactSerializedProp => {
+      if (value === null) {
+        return null
+      }
+      if (typeof value === 'string') {
+        return value.length > 300 ? `${value.slice(0, 300)}…[truncated]` : value
+      }
+      if (typeof value === 'number' || typeof value === 'boolean') {
+        return value
+      }
+      if (typeof value === 'undefined') {
+        return '[undefined]'
+      }
+      if (typeof value === 'function') {
+        return '[function]'
+      }
+      if (typeof value === 'symbol') {
+        return '[symbol]'
+      }
+      if (typeof value === 'bigint') {
+        return `${value.toString()}n`
+      }
+      if (typeof value !== 'object') {
+        return `[${typeof value}]`
+      }
+      const objectTag = Object.prototype.toString.call(value)
+      if (objectTag.includes('Element]') || objectTag === '[object Window]' || objectTag === '[object Document]') {
+        return '[dom-node]'
+      }
+      if (options.seen.has(value)) {
+        return '[circular]'
+      }
+      if (options.depth >= 3) {
+        return '[max-depth]'
+      }
+
+      options.seen.add(value)
+
+      if (Array.isArray(value)) {
+        const items = value.slice(0, 20).map((item) => {
+          return serializeReactValue(item, { depth: options.depth + 1, seen: options.seen })
+        })
+        if (value.length > 20) {
+          items.push(`…[${value.length - 20} more]`)
+        }
+        options.seen.delete(value)
+        return items
+      }
+
+      const entries = Object.entries(value).slice(0, 20)
+      const result: { [key: string]: ReactSerializedProp } = Object.fromEntries(
+        entries.map(([key, childValue]) => {
+          return [key, serializeReactValue(childValue, { depth: options.depth + 1, seen: options.seen })]
+        }),
+      )
+      const totalKeys = Object.keys(value).length
+      if (totalKeys > 20) {
+        result['…'] = `[${totalKeys - 20} more keys]`
+      }
+      options.seen.delete(value)
+      return result
+    }
 
-  if (result && '_notFound' in result) {
-    if (result._notFound === 'fiber') {
-      console.warn('[getReactSource] no fiber found - is this a React element?')
-    } else {
-      console.warn('[getReactSource] no source location found - is this a React dev build?')
+    const getSourceForFiber = async (fiber: BippyFiber): Promise<Omit<ReactSourceLocation, 'componentName'> | null> => {
+      try {
+        const source = await bippy.getSource(fiber)
+        if (source?.fileName) {
+          return {
+            fileName: cleanName(source.fileName),
+            lineNumber: source.lineNumber ?? null,
+            columnNumber: source.columnNumber ?? null,
+          }
+        }
+
+        const ownerStack = await bippy.getOwnerStack(fiber)
+        const frame = ownerStack.find((ownerFrame) => {
+          return ownerFrame.fileName ? bippy.isSourceFile(ownerFrame.fileName) : false
+        })
+        if (frame?.fileName) {
+          return {
+            fileName: cleanName(frame.fileName),
+            lineNumber: frame.lineNumber ?? null,
+            columnNumber: frame.columnNumber ?? null,
+          }
+        }
+      } catch {
+        return null
+      }
+
+      return null
+    }
+
+    let fiber: BippyFiber | null = null
+    try {
+      fiber = bippy.getFiberFromHostInstance(el)
+    } catch {
+      return null
+    }
+
+    if (!fiber) {
+      return null
+    }
+
+    const componentFibers: BippyFiber[] = []
+    let current: BippyFiber | null | undefined = fiber
+    while (current && componentFibers.length < 20) {
+      try {
+        if (bippy.isCompositeFiber(current)) {
+          componentFibers.push(current)
+        }
+      } catch {
+        // Ignore malformed or unsupported fibers and keep walking upward.
+      }
+      current = current.return
+    }
+
+    if (componentFibers.length === 0) {
+      return null
     }
-    return null
+
+    const hierarchy = await Promise.all(
+      componentFibers.map(async (componentFiber): Promise<ReactComponentHierarchyItem> => {
+        const componentName = (() => {
+          try {
+            return componentFiber.type ? bippy.getDisplayName(componentFiber.type) : null
+          } catch {
+            return null
+          }
+        })()
+
+        return {
+          componentName,
+          source: await getSourceForFiber(componentFiber),
+          props: serializeReactValue(componentFiber.memoizedProps, { depth: 0, seen: new WeakSet<object>() }),
+        }
+      }),
+    )
+
+    const nearest = hierarchy[0]
+    if (!nearest) {
+      return null
+    }
+
+    return {
+      componentName: nearest.componentName,
+      source: nearest.source,
+      hierarchy,
+      props: nearest.props,
+    }
+  }
+
+  if ('page' in locator) {
+    return await locator.evaluate(evaluateReactComponentInfo)
   }
 
-  return result
+  return await locator.evaluate(evaluateReactComponentInfo)
 }

package/src/relay-client.ts

@@ -39,6 +39,31 @@ export async function getRelayServerVersion(port: number = RELAY_PORT): Promise<
   }
 }
 
+/**
+ * Poll /version until a relay responds or timeout expires.
+ * Used during startup races where a relay may have bound the port
+ * but isn't serving HTTP yet (issue #75).
+ */
+export async function waitForRelayVersion({
+  port = RELAY_PORT,
+  timeoutMs = 2000,
+  intervalMs = 200,
+}: {
+  port?: number
+  timeoutMs?: number
+  intervalMs?: number
+} = {}): Promise<string | null> {
+  const end = Date.now() + timeoutMs
+  while (Date.now() < end) {
+    const version = await getRelayServerVersion(port)
+    if (version) {
+      return version
+    }
+    await sleep(intervalMs)
+  }
+  return null
+}
+
 export async function getExtensionStatus(
   port: number = RELAY_PORT,
 ): Promise<{ connected: boolean; activeTargets: number; playwriterVersion: string | null } | null> {
@@ -196,11 +221,26 @@ export interface EnsureRelayServerOptions {
   env?: Record<string, string>
 }
 
+// Module-level dedup: if ensureRelayServer is called concurrently within the
+// same process (e.g. two MCP tool handlers at once), only one spawn runs.
+let pendingEnsure: Promise<true | undefined> | null = null
+
 /**
  * Ensures the relay server is running. Starts it if not running.
  * Optionally restarts on version mismatch.
+ * Concurrent calls within the same process are deduplicated.
  */
 export async function ensureRelayServer(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
+  if (pendingEnsure) {
+    return pendingEnsure
+  }
+  pendingEnsure = ensureRelayServerImpl(options).finally(() => {
+    pendingEnsure = null
+  })
+  return pendingEnsure
+}
+
+async function ensureRelayServerImpl(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
   const { logger, restartOnVersionMismatch = true, env: additionalEnv } = options
   const serverVersion = await getRelayServerVersion(RELAY_PORT)
 
@@ -227,11 +267,28 @@ export async function ensureRelayServer(options: EnsureRelayServerOptions = {}):
   } else {
     const listeningPids = await getListeningPidsForPort({ port: RELAY_PORT }).catch(() => [])
     if (listeningPids.length > 0) {
-      logger?.log(
-        pc.yellow(
-          `Port ${RELAY_PORT} is already in use (pid(s): ${listeningPids.join(', ')}). Attempting to stop the existing process...`,
-        ),
-      )
+      // Something is on the port but /version didn't respond. It might be a
+      // relay that's still starting (race with another CLI/MCP instance).
+      // Poll /version briefly before deciding to kill it (issue #75).
+      const foundVersion = await waitForRelayVersion({ port: RELAY_PORT })
+      if (foundVersion) {
+        // A relay came up while we waited; use it
+        if (foundVersion === VERSION || compareVersions(foundVersion, VERSION) > 0) {
+          return
+        }
+        if (!restartOnVersionMismatch) {
+          return
+        }
+        logger?.log(
+          pc.yellow(`CDP relay server version mismatch (server: ${foundVersion}, client: ${VERSION}), restarting...`),
+        )
+      } else {
+        logger?.log(
+          pc.yellow(
+            `Port ${RELAY_PORT} is already in use (pid(s): ${listeningPids.join(', ')}). Attempting to stop the existing process...`,
+          ),
+        )
+      }
       await killRelayServer({ port: RELAY_PORT })
     }