playwriter 0.1.0 → 0.2.0

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-session.test.ts

@@ -921,12 +921,24 @@ describe('CDP Session Tests', () => {
             <body>
                 <div id="root"></div>
                 <script>
-                    function MyComponent() {
-                        return React.createElement('button', { id: 'react-btn' }, 'Click me');
+                    function SaveButton(props) {
+                        return React.createElement('button', { id: 'react-btn' }, props.label);
+                    }
+                    function Panel() {
+                        return React.createElement('section', null, React.createElement(SaveButton, {
+                          label: 'Click me',
+                          count: 3,
+                          config: { variant: 'primary' },
+                          onClick: () => {}
+                        }));
+                    }
+                    function App() {
+                        return React.createElement(Panel);
                     }
                     const root = ReactDOM.createRoot(document.getElementById('root'));
-                    root.render(React.createElement(MyComponent));
+                    root.render(React.createElement(App));
                 </script>
+                <button id="plain-btn">Plain</button>
             </body>
             </html>
         `)
@@ -946,40 +958,54 @@ describe('CDP Session Tests', () => {
     const btnCount = await btn.count()
     expect(btnCount).toBe(1)
 
-    const hasBippyBefore = await cdpPage!.evaluate(() => !!(globalThis as any).__bippy)
+    const hasBippyBefore = await cdpPage!.evaluate(() => !!globalThis.__bippy)
     expect(hasBippyBefore).toBe(false)
 
     const wsUrl = getCdpUrl({ port: TEST_PORT })
     const cdpSession = await getCDPSessionForPage({ page: cdpPage! })
 
-    const { getReactSource } = await import('./react-source.js')
+    const { getReactSource, getReactComponentInfo } = await import('./react-source.js')
     const source = await getReactSource({ locator: btn, cdp: cdpSession })
+    const info = await getReactComponentInfo({ locator: btn, cdp: cdpSession })
+    const plainInfo = await getReactComponentInfo({ locator: cdpPage!.locator('#plain-btn'), cdp: cdpSession })
 
-    const hasBippyAfter = await cdpPage!.evaluate(() => !!(globalThis as any).__bippy)
+    const hasBippyAfter = await cdpPage!.evaluate(() => !!globalThis.__bippy)
     expect(hasBippyAfter).toBe(true)
 
     const hasFiber = await btn.evaluate((el) => {
-      const bippy = (globalThis as any).__bippy
+      const bippy = globalThis.__bippy
+      if (!bippy) return false
       const fiber = bippy.getFiberFromHostInstance(el)
       return !!fiber
     })
     expect(hasFiber).toBe(true)
 
     const componentName = await btn.evaluate((el) => {
-      const bippy = (globalThis as any).__bippy
+      const bippy = globalThis.__bippy
+      if (!bippy) return null
       const fiber = bippy.getFiberFromHostInstance(el)
       let current = fiber
       while (current) {
         if (bippy.isCompositeFiber(current)) {
           return bippy.getDisplayName(current.type)
         }
-        current = current.return
+        current = current.return ?? null
       }
       return null
     })
-    expect(componentName).toBe('MyComponent')
+    expect(componentName).toBe('SaveButton')
+    expect(plainInfo).toBe(null)
+    expect(info?.componentName).toBe('SaveButton')
+    expect(info?.hierarchy.map((item) => item.componentName)).toEqual(['SaveButton', 'Panel', 'App'])
+    expect(info?.props).toEqual({
+      label: 'Click me',
+      count: 3,
+      config: { variant: 'primary' },
+      onClick: '[function]',
+    })
 
     console.log('Component name from fiber:', componentName)
+    console.log('React component info:', info)
     console.log('Source location (null for UMD React, works on local dev servers with JSX transform):', source)
 
     await browser.close()

package/src/screen-recording.ts

@@ -18,6 +18,21 @@ import type {
 } from './protocol.js'
 import { GhostCursorController } from './ghost-cursor-controller.js'
 
+/**
+ * Build headers for the relay's privileged /recording/* HTTP endpoints.
+ * Reads PLAYWRITER_TOKEN from env so in-process callers (executor running
+ * inside `playwriter serve --token …`) authenticate against their own relay.
+ * The `serve` command sets the env var at startup.
+ */
+function recordingHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+  const token = process.env.PLAYWRITER_TOKEN
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`
+  }
+  return headers
+}
+
 /**
  * Generate a CLI command that starts a managed Playwriter browser with the
  * bundled extension preloaded. This enables screen recording without a manual
@@ -293,7 +308,7 @@ export async function startRecording(options: StartRecordingOptions): Promise<Re
 
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/start`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({
       sessionId,
       frameRate,
@@ -341,7 +356,7 @@ export async function stopRecording(
 
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/stop`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({ sessionId }),
   })
 
@@ -368,7 +383,8 @@ export async function isRecording(options: {
   if (sessionId) {
     url.searchParams.set('sessionId', sessionId)
   }
-  const response = await fetch(url.toString())
+  // GET request — only the Authorization header matters here
+  const response = await fetch(url.toString(), { headers: recordingHeaders() })
   const result = (await response.json()) as IsRecordingResult
 
   return { isRecording: result.isRecording, startedAt: result.startedAt, tabId: result.tabId }
@@ -386,7 +402,7 @@ export async function cancelRecording(options: {
 
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/cancel`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: recordingHeaders(),
     body: JSON.stringify({ sessionId }),
   })
 

package/src/skill.md

@@ -93,7 +93,7 @@ playwriter -s 1 -e 'await state.page.click("button")'
 playwriter -s 1 -e 'await state.page.title()'
 
 # Take a screenshot
-playwriter -s 1 -e 'await state.page.screenshot({ path: "screenshot.png", scale: "css" })'
+playwriter -s 1 -e 'await state.page.screenshot({ path: "/absolute/path/to/screenshot.png", scale: "css" })'
 
 # Get accessibility snapshot
 playwriter -s 1 -e 'await snapshot({ page: state.page })'
@@ -129,6 +129,16 @@ console.log({ title, url });
 - **Heredoc** (`<<'EOF'`): best for multiline code. The quoted `'EOF'` delimiter disables all bash expansion. Any character works inside, including `$`, backticks, and single quotes.
 - **`$'...'`**: allows `\'` escaping but `\n`, `\t`, `\\` become special — conflicts with JS regex patterns.
 
+### Execute from file
+
+For longer scripts, use `-f` instead of `-e` to execute JavaScript from a file:
+
+```bash
+playwriter -s 1 -f script.js
+```
+
+The file is read from disk and executed in the same sandbox as `-e`. All context variables (`state`, `page`, `context`, etc.) are available. `-e` and `-f` cannot be used together.
+
 ### Debugging playwriter issues
 
 If some internal critical error happens you can read the relay server logs to understand the issue. The log file is located in the user home directory:
@@ -209,6 +219,7 @@ You can collaborate with the user - they can help with captchas, difficult eleme
 - **Wait for load**: use `state.page.waitForLoadState('domcontentloaded')` not `state.page.waitForEvent('load')` - waitForEvent times out if already loaded
 - **Minimize timeouts**: prefer proper waits (`waitForSelector`, `waitForPageLoad`) over `state.page.waitForTimeout()`. Short timeouts (1-2s) are acceptable for non-deterministic events like animations, tab opens, or async UI updates where no specific selector is available
 - **Snapshot before screenshot**: always use `snapshot()` first to understand page state (text-based, fast, cheap). Only use `screenshot` when you specifically need visual/spatial information. Never take a screenshot just to check if a page loaded or to read text content — snapshot gives you that instantly without burning image tokens
+- **Always use absolute file paths for Playwright artifact APIs**: for `page.screenshot({ path })`, `locator.screenshot({ path })`, `elementHandle.screenshot({ path })`, `page.pdf({ path })`, `download.saveAs(path)`, and `video.saveAs(path)`, always pass an absolute path. Relative paths are resolved by Playwright client internals, not the sandboxed `fs`, so they may use the relay server cwd instead of your session cwd.
 - **Snapshot replaces page.evaluate() for inspection**: do NOT write `page.evaluate()` calls to manually query class names, bounding boxes, child counts, or visibility flags. `snapshot()` already shows every interactive element with its text, role, and a ready-to-use locator. If you catch yourself writing `document.querySelector` or `getBoundingClientRect` inside evaluate — stop and use `snapshot()` instead. Reserve `page.evaluate()` for actions that modify page state (e.g., `localStorage.clear()`, scroll manipulation) or extract non-DOM data (e.g., `window.__CONFIG__`)
 
 ## interaction feedback loop
@@ -601,7 +612,7 @@ Instead, use simpler alternatives (single download via `a.click()`, store data i
 
 ```js
 const [download] = await Promise.all([state.page.waitForEvent('download'), state.page.click('button.download')])
-await download.saveAs(`/tmp/${download.suggestedFilename()}`)
+await download.saveAs(`/absolute/path/${download.suggestedFilename()}`)
 ```
 
 **iFrames** - two approaches depending on what you need:
@@ -754,6 +765,19 @@ const source = await getReactSource({ locator: state.page.locator('[data-testid=
 // => { fileName, lineNumber, columnNumber, componentName }
 ```
 
+**getReactComponentInfo** - get best-effort React component info for an element. Returns `null` for non-React elements and never throws just because an element was not rendered by React. Source locations are usually only available in React dev builds. Props are sanitized and truncated so functions, DOM nodes, circular refs, and huge objects do not flood the output.
+
+```js
+const info = await getReactComponentInfo({ locator: state.page.locator('[data-testid="submit-btn"]') })
+// => { componentName, source, hierarchy, props } | null
+```
+
+**inspectPinnedElement** - inspect a Playwriter pinned element and print the element `outerHTML` plus React component info when available. Used by the in-page toolbar and right-click copy flow.
+
+```js
+await inspectPinnedElement('https://example.com', 'globalThis.playwriterPinnedElem1')
+```
+
 **getStylesForLocator** - inspect CSS styles applied to an element, like browser DevTools "Styles" panel. Useful for debugging styling issues, finding where a CSS property is defined (file:line), and checking inherited styles. Returns selector, source location, and declarations for each matching rule. ALWAYS fetch `https://playwriter.dev/resources/styles-api.md` first with curl or webfetch tool.
 
 ```js
@@ -806,7 +830,7 @@ await screenshotWithAccessibilityLabels({ page: state.page })
 
 Labels are color-coded: yellow=links, orange=buttons, coral=inputs, pink=checkboxes, peach=sliders, salmon=menus, amber=tabs.
 
-**resizeImageForAgent** - shrink an image so it consumes fewer tokens when read back into context. The resized image is automatically included in the response (visible to the LLM). `await resizeImageForAgent({ input: './screenshot.png' })`. Also accepts `width`, `height`, `maxDimension`, `quality`, `format` (default: `'png'`), `output`. Alias: `resizeImage`.
+**resizeImageForAgent** - shrink an image so it consumes fewer tokens when read back into context. The resized image is automatically included in the response (visible to the LLM). `await resizeImageForAgent({ input: '/absolute/path/to/screenshot.png' })`. Also accepts `width`, `height`, `maxDimension`, `quality`, `format` (default: `'png'`), `output`. Alias: `resizeImage`.
 
 **recording.start / recording.stop** - record the page as a video at native FPS (30-60fps). Uses `chrome.tabCapture` so **recording survives page navigation**. Auto-overlays a ghost cursor that follows mouse actions. Requires user to have clicked the Playwriter extension icon on the tab. Auto-resizes viewport to 16:9 (override with `aspectRatio: null`). Auto-stops after 15 min (override with `maxDurationMs`).
 
@@ -815,7 +839,7 @@ For demos, use interaction methods (`locator.click()`, `page.mouse.move()`) inst
 ```js
 await recording.start({
   page: state.page,
-  outputPath: './recording.mp4',
+  outputPath: '/absolute/path/to/recording.mp4',
   frameRate: 30, // default
   audio: false, // default (tab audio)
   videoBitsPerSecond: 2500000,
@@ -869,7 +893,7 @@ await el.click()
 Always use `scale: 'css'` to avoid 2-4x larger images on high-DPI displays:
 
 ```js
-await state.page.screenshot({ path: 'shot.png', scale: 'css' })
+await state.page.screenshot({ path: '/absolute/path/to/shot.png', scale: 'css' })
 ```
 
 If you want to read back the image file into context, resize it first so it consumes fewer tokens:
@@ -1048,7 +1072,7 @@ await state.page.setViewportSize({ width: 1280, height: 720 })
 ### region screenshot (zoom equivalent)
 
 ```js
-await state.page.screenshot({ path: 'region.png', scale: 'css', clip: { x: 100, y: 200, width: 400, height: 300 } })
+await state.page.screenshot({ path: '/absolute/path/to/region.png', scale: 'css', clip: { x: 100, y: 200, width: 400, height: 300 } })
 ```
 
 Prefer locator-based actions over coordinates — locators are stable across scroll/resize, auto-wait for elements, and don't require screenshot round-trips that burn ~800 image tokens per cycle.