playwriter 0.1.0 → 0.2.0

package/src/cli.ts

@@ -105,12 +105,33 @@ cli
   .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .option('-s, --session <name>', 'Session ID (required for -e, get one with `playwriter session new`)')
   .option('-e, --eval <code>', 'Execute JavaScript code and exit, read https://playwriter.dev/SKILL.md for usage')
+  .option('-f, --file <path>', 'Execute JavaScript from a file and exit')
   .option('--timeout [ms]', z.number().default(10000).describe('Execution timeout in milliseconds'))
   .action(async (options) => {
-    // If -e flag is provided, execute code via relay server
-    if (options.eval) {
+    if (options.eval && options.file) {
+      console.error('Error: -e and -f cannot be used together.')
+      process.exit(1)
+    }
+
+    // If -e or -f flag is provided, execute code via relay server
+    const code = (() => {
+      if (options.eval) {
+        return options.eval
+      }
+      if (options.file) {
+        const filePath = path.resolve(options.file)
+        if (!fs.existsSync(filePath)) {
+          console.error(`Error: File not found: ${filePath}`)
+          process.exit(1)
+        }
+        return fs.readFileSync(filePath, 'utf-8')
+      }
+      return null
+    })()
+
+    if (code) {
       await executeCode({
-        code: options.eval,
+        code,
         timeout: options.timeout || 10000,
         sessionId: options.session,
         host: options.host,
@@ -134,6 +155,20 @@ async function getServerUrl(host?: string): Promise<string> {
   return httpBaseUrl
 }
 
+// Centralized header builder so every CLI subcommand sends the token consistently.
+// Falls back to PLAYWRITER_TOKEN env var when --token is not provided.
+function buildAuthHeaders({ token, json }: { token?: string; json?: boolean }): Record<string, string> {
+  const headers: Record<string, string> = {}
+  if (json) {
+    headers['Content-Type'] = 'application/json'
+  }
+  const effectiveToken = token || process.env.PLAYWRITER_TOKEN
+  if (effectiveToken) {
+    headers['Authorization'] = `Bearer ${effectiveToken}`
+  }
+  return headers
+}
+
 async function fetchExtensionsStatus(host?: string): Promise<ExtensionStatus[]> {
   try {
     const serverUrl = await getServerUrl(host)
@@ -225,12 +260,7 @@ async function executeCode(options: {
   try {
     const response = await fetch(executeUrl, {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...(token || process.env.PLAYWRITER_TOKEN
-          ? { Authorization: `Bearer ${token || process.env.PLAYWRITER_TOKEN}` }
-          : {}),
-      },
+      headers: buildAuthHeaders({ token, json: true }),
       body: JSON.stringify({ sessionId, code, timeout, cwd }),
     })
 
@@ -321,6 +351,7 @@ interface BrowserOption {
 cli
   .command('session new', 'Create a new session and print the session ID')
   .option('--host <host>', 'Remote relay server host')
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .option('--browser <key>', 'Browser key when multiple browsers are available')
   .option('--direct [endpoint]', 'Use direct CDP connection without the extension. Enable debugging first at chrome://inspect/#remote-debugging or launch Chrome with --remote-debugging-port=9222. Auto-discovers instances or accepts an explicit ws:// endpoint')
   .action(async (options) => {
@@ -342,7 +373,7 @@ cli
       }
       await ensureRelayForSessionCreation(isLocal)
       const serverUrl = await getServerUrl(options.host)
-      const result = await createDirectSession({ serverUrl, cdpEndpoint })
+      const result = await createDirectSession({ serverUrl, cdpEndpoint, token: options.token })
       console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
       console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
       return
@@ -372,7 +403,7 @@ cli
       if (instances.length === 1 && !options.browser) {
         const instance = instances[0]
         const serverUrl = await getServerUrl(options.host)
-        const result = await createDirectSession({ serverUrl, cdpEndpoint: instance.wsUrl, browser: instance.browser, profiles: instance.profiles })
+        const result = await createDirectSession({ serverUrl, cdpEndpoint: instance.wsUrl, browser: instance.browser, profiles: instance.profiles, token: options.token })
         const profileLabel = formatInstanceProfiles(instance)
         console.log(
           `Session ${result.id} created (direct CDP, ${instance.browser}${profileLabel}). Use with: playwriter -s ${result.id} -e "..."`,
@@ -396,7 +427,7 @@ cli
           process.exit(1)
         }
         const serverUrl = await getServerUrl(options.host)
-        const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles })
+        const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles, token: options.token })
         console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
         console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
         return
@@ -457,7 +488,7 @@ cli
         const cwd = process.cwd()
         const response = await fetch(`${serverUrl}/cli/session/new`, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: buildAuthHeaders({ token: options.token, json: true }),
           body: JSON.stringify({ extensionId, cwd }),
         })
         if (!response.ok) {
@@ -509,14 +540,14 @@ cli
       try {
         const serverUrl = await getServerUrl(options.host)
         if (selected.type === 'direct') {
-          const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles })
+          const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles, token: options.token })
           console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
           console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
         } else {
           const cwd = process.cwd()
           const response = await fetch(`${serverUrl}/cli/session/new`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: buildAuthHeaders({ token: options.token, json: true }),
             body: JSON.stringify({ extensionId: selected.extensionId, cwd }),
           })
           if (!response.ok) {
@@ -552,16 +583,18 @@ async function createDirectSession({
   cdpEndpoint,
   browser,
   profiles,
+  token,
 }: {
   serverUrl: string
   cdpEndpoint: string
   browser?: string
   profiles?: Array<{ name: string; email: string }>
+  token?: string
 }): Promise<{ id: string }> {
   const cwd = process.cwd()
   const response = await fetch(`${serverUrl}/cli/session/new`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: buildAuthHeaders({ token, json: true }),
     body: JSON.stringify({ cdpEndpoint, cwd, browser, profiles }),
   })
   if (!response.ok) {
@@ -622,6 +655,7 @@ function printBrowserTable(options: BrowserOption[]): void {
 cli
   .command('session list', 'List all active sessions')
   .option('--host <host>', 'Remote relay server host')
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .action(async (options) => {
     if (!options.host && !process.env.PLAYWRITER_HOST) {
       await ensureRelayServer({ logger: console, env: cliRelayEnv })
@@ -639,6 +673,7 @@ cli
 
     try {
       const response = await fetch(`${serverUrl}/cli/sessions`, {
+        headers: buildAuthHeaders({ token: options.token }),
         signal: AbortSignal.timeout(2000),
       })
       if (!response.ok) {
@@ -711,6 +746,7 @@ cli
 cli
   .command('session delete <sessionId>', 'Delete a session and clear its state')
   .option('--host <host>', 'Remote relay server host')
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .action(async (sessionId, options) => {
     const serverUrl = await getServerUrl(options.host)
 
@@ -721,7 +757,7 @@ cli
     try {
       const response = await fetch(`${serverUrl}/cli/session/delete`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: buildAuthHeaders({ token: options.token, json: true }),
         body: JSON.stringify({ sessionId }),
       })
 
@@ -741,6 +777,7 @@ cli
 cli
   .command('session reset <sessionId>', 'Reset the browser connection for a session')
   .option('--host <host>', 'Remote relay server host')
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .action(async (sessionId, options) => {
     const cwd = process.cwd()
     const serverUrl = await getServerUrl(options.host)
@@ -752,7 +789,7 @@ cli
     try {
       const response = await fetch(`${serverUrl}/cli/reset`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: buildAuthHeaders({ token: options.token, json: true }),
         body: JSON.stringify({ sessionId, cwd }),
       })
 
@@ -789,6 +826,14 @@ cli
       process.exit(1)
     }
 
+    // Expose the token to in-process callers (screen-recording.ts, etc.) so
+    // they can attach Authorization: Bearer ... when calling the relay's own
+    // privileged endpoints. Required because we no longer bypass auth for
+    // loopback — see commit history for the tunnel-agent threat model.
+    if (token) {
+      process.env.PLAYWRITER_TOKEN = token
+    }
+
     // Check if server is already running on the port
     const net = await import('node:net')
     const isPortInUse = await new Promise<boolean>((resolve) => {
@@ -872,6 +917,7 @@ cli
 cli
   .command('browser list', 'List all available browsers: extension-connected and direct CDP on port 9222')
   .option('--host <host>', z.string().describe('Remote relay server host'))
+  .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .action(async (options) => {
     const isLocal = !options.host && !process.env.PLAYWRITER_HOST
 
@@ -933,6 +979,7 @@ cli.command('skill', 'Print the full playwriter usage instructions').action(() =
 })
 
 cli.help()
+cli.completions()
 cli.version(VERSION)
 
-cli.parse()
+await cli.parse()

package/src/executor.ts

@@ -3,7 +3,7 @@
  * Used by both MCP and CLI to execute Playwright code with persistent state.
  */
 
-import { Page, Frame, Browser, BrowserContext, chromium, Locator, FrameLocator } from '@xmorse/playwright-core'
+import { Page, Frame, Browser, BrowserContext, chromium, Locator, FrameLocator, ElementHandle } from '@xmorse/playwright-core'
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -21,7 +21,7 @@ import { ICDPSession, getCDPSessionForPage } from './cdp-session.js'
 import { Debugger } from './debugger.js'
 import { Editor } from './editor.js'
 import { getStylesForLocator, formatStylesAsText, type StylesResult } from './styles.js'
-import { getReactSource, type ReactSourceLocation } from './react-source.js'
+import { getReactSource, getReactComponentInfo, type ReactSourceLocation } from './react-source.js'
 import { ScopedFS } from './scoped-fs.js'
 import {
   screenshotWithAccessibilityLabels,
@@ -104,14 +104,14 @@ export function getAutoReturnExpression(code: string): string | null {
     if (
       expr.type === 'AssignmentExpression' ||
       expr.type === 'UpdateExpression' ||
-      (expr.type === 'UnaryExpression' && (expr as acorn.UnaryExpression).operator === 'delete')
+      (expr.type === 'UnaryExpression' && expr.operator === 'delete')
     ) {
       return null
     }
 
     // Don't auto-return sequence expressions that contain assignments
     if (expr.type === 'SequenceExpression') {
-      const hasAssignment = expr.expressions.some((e: acorn.Expression) => e.type === 'AssignmentExpression')
+      const hasAssignment = expr.expressions.some((e) => e.type === 'AssignmentExpression')
       if (hasAssignment) {
         return null
       }
@@ -1043,6 +1043,47 @@ export class PlaywrightExecutor {
         return getReactSource({ locator: options.locator, cdp })
       }
 
+      const getReactComponentInfoFn = async (options: { locator: Locator | ElementHandle }) => {
+        const targetPage = await (async (): Promise<Page | null> => {
+          if ('page' in options.locator) {
+            return options.locator.page()
+          }
+
+          return (await options.locator.ownerFrame())?.page() ?? null
+        })()
+        if (!targetPage) {
+          throw new Error('Could not get page from locator')
+        }
+        const cdp = await getCDPSession({ page: targetPage })
+        return getReactComponentInfo({ locator: options.locator, cdp })
+      }
+
+      const inspectPinnedElement = async (pageUrl: string, elementExpression: string) => {
+        const targetPage = context.pages().find((candidate) => candidate.url() === pageUrl) || context.pages()[0]
+        if (!targetPage) {
+          throw new Error('No Playwright pages are available')
+        }
+
+        this.userState.page = targetPage
+        const handle = (await targetPage.evaluateHandle((expression) => {
+          return Function(`return (${expression})`)()
+        }, elementExpression)).asElement()
+
+        const result = await (async () => {
+          if (!handle) {
+            return { url: targetPage.url(), outerHTML: null, react: null }
+          }
+          return {
+            url: targetPage.url(),
+            outerHTML: await handle.evaluate((el) => el.outerHTML),
+            react: await getReactComponentInfoFn({ locator: handle }),
+          }
+        })()
+
+        console.log(result)
+        return result
+      }
+
       const screenshotCollector: ScreenshotResult[] = []
       // Separate collector for images produced by resizeImageForAgent() calls.
       // These get merged into result.images so the CLI can emit them via Kitty Graphics.
@@ -1146,6 +1187,8 @@ export class PlaywrightExecutor {
         getStylesForLocator: getStylesForLocatorFn,
         formatStylesAsText,
         getReactSource: getReactSourceFn,
+        getReactComponentInfo: getReactComponentInfoFn,
+        inspectPinnedElement,
         screenshotWithAccessibilityLabels: screenshotWithAccessibilityLabelsFn,
         resizeImageForAgent: resizeImageForAgentFn,
         // Backward-compatible alias for resizeImageForAgent

package/src/mcp.ts

@@ -56,9 +56,14 @@ function getLogServerUrl(): string {
 
 async function sendLogToRelayServer(level: string, ...args: any[]) {
   try {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    const token = process.env.PLAYWRITER_TOKEN
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`
+    }
     await fetch(getLogServerUrl(), {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers,
       body: JSON.stringify({ level, args }),
       signal: AbortSignal.timeout(1000),
     })

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 }