playwriter 0.0.105 → 0.2.0

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,
@@ -833,11 +857,11 @@ state.recordingResult = await recording.stop({ page: state.page })
 // Other: recording.isRecording({ page }), recording.cancel({ page })
 ```
 
-**ghostCursor.show / ghostCursor.hide** - show/hide cursor overlay for screenshots and demos:
+**ghostCursor.show / ghostCursor.hide** - the ghost cursor overlay is always on: the extension injects it on every Playwriter-attached tab and it stays visible at the last spot Playwright clicked or moved. These methods only matter if you want to change the cursor style or temporarily hide it:
 
 ```js
-await ghostCursor.show({ page: state.page, style: 'minimal' }) // 'minimal', 'dot', 'screenstudio'
-await ghostCursor.hide({ page: state.page })
+await ghostCursor.show({ page: state.page, style: 'screenstudio' }) // 'minimal' (default), 'dot', 'screenstudio'
+await ghostCursor.hide({ page: state.page }) // hide until next show() or hard navigation
 ```
 
 **createDemoVideo** - speeds up idle sections (time between execute() calls) while keeping interactions at normal speed. Requires `ffmpeg`/`ffprobe`. Timestamps are tracked automatically during recording and returned by `recording.stop()`. **Timeout**: can take 60–120+ seconds, always pass `--timeout 120000` or higher.
@@ -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.

package/src/snapshots/shadcn-ui-accessibility-full.md

@@ -51,9 +51,9 @@
                     - textbox "Comments" [id="checkout-7j9-optional-comments"]
                   - role=button[name="Submit"]
                   - role=button[name="Cancel"] >> nth=0
-                        - image "@shadcn"
-                        - image "@maxleiter"
-                        - image "@evilrabbit"
+                          - text: "CN"
+                          - text: "LR"
+                          - text: "ER"
                   - text: "No Team Members"
                   - text: "Invite your team to collaborate on this project."
                   - role=button[name="Invite Members"]
@@ -176,5 +176,8 @@
         - role=link[name="GitHub"]
         - text: "."
   - region "Notifications alt+T"
+  - toolbar "Playwriter tools":
+    - role=button[name="Pin element — click any element to copy its Playwriter reference"]
+    - role=button[name="Close Playwriter toolbar"]
 
 use refToLocator({ ref: 'e3' }) to get locators for ref strings.

package/src/snapshots/shadcn-ui-accessibility-interactive.md

@@ -115,5 +115,7 @@
           - role=link[name="Vercel"]
           - role=link[name="GitHub"]
     - region "Notifications alt+T"
+  - role=button[name="Pin element — click any element to copy its Playwriter reference"]
+  - role=button[name="Close Playwriter toolbar"]
 
 use refToLocator({ ref: 'e3' }) to get locators for ref strings.

package/dist/recording-ghost-cursor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recording-ghost-cursor.d.ts","sourceRoot":"","sources":["../src/recording-ghost-cursor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AACnE,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAA;AAE1B,UAAU,0BAA0B;IAClC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CACpC;AAED,UAAU,sBAAsB;IAC9B,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,8BAA8B;IACzC,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA6C;IACvF,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAqC;IAC5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAEvC,OAAO,EAAE;QAAE,MAAM,EAAE,0BAA0B,CAAA;KAAE;IAI3D,0BAA0B,CAAC,OAAO,EAAE;QAClC,OAAO,EAAE,cAAc,CAAA;QACvB,WAAW,EAAE,IAAI,CAAA;QACjB,MAAM,CAAC,EAAE,sBAAsB,CAAA;KAChC,GAAG,IAAI;IAoBF,kBAAkB,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC1D,mBAAmB,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3D,IAAI,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,wBAAwB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtF,IAAI,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAInD"}

package/dist/recording-ghost-cursor.js

@@ -1,79 +0,0 @@
-/**
- * Encapsulates ghost cursor lifecycle for recording sessions.
- * Keeps onMouseAction chaining/restoration isolated from executor logic.
- */
-import { applyGhostCursorMouseAction, disableGhostCursor, enableGhostCursor, } from './ghost-cursor.js';
-export class RecordingGhostCursorController {
-    previousMouseActionByPage = new WeakMap();
-    cursorApplyQueueByPage = new WeakMap();
-    logger;
-    constructor(options) {
-        this.logger = options.logger;
-    }
-    resolveRecordingTargetPage(options) {
-        const { context, defaultPage, target } = options;
-        if (target?.page) {
-            return target.page;
-        }
-        if (target?.sessionId) {
-            const pageForSession = context.pages().find((candidatePage) => {
-                return candidatePage.sessionId() === target.sessionId;
-            });
-            if (pageForSession) {
-                return pageForSession;
-            }
-        }
-        return defaultPage;
-    }
-    async enableForRecording(options) {
-        const { page } = options;
-        try {
-            await enableGhostCursor({ page });
-            if (!this.previousMouseActionByPage.has(page)) {
-                this.previousMouseActionByPage.set(page, page.onMouseAction);
-            }
-            const previousMouseAction = this.previousMouseActionByPage.get(page);
-            page.onMouseAction = async (event) => {
-                const pendingCursorApply = this.cursorApplyQueueByPage.get(page) || Promise.resolve();
-                const nextCursorApply = pendingCursorApply
-                    .then(async () => {
-                    await applyGhostCursorMouseAction({ page, event });
-                })
-                    .catch((error) => {
-                    this.logger.error('[playwriter] Failed to apply ghost cursor action', error);
-                });
-                this.cursorApplyQueueByPage.set(page, nextCursorApply);
-                if (!previousMouseAction) {
-                    return;
-                }
-                await previousMouseAction(event);
-            };
-        }
-        catch (error) {
-            page.onMouseAction = this.previousMouseActionByPage.get(page) ?? null;
-            this.previousMouseActionByPage.delete(page);
-            this.logger.error('[playwriter] Failed to enable ghost cursor', error);
-        }
-    }
-    async disableForRecording(options) {
-        const { page } = options;
-        page.onMouseAction = this.previousMouseActionByPage.get(page) ?? null;
-        this.previousMouseActionByPage.delete(page);
-        this.cursorApplyQueueByPage.delete(page);
-        try {
-            await disableGhostCursor({ page });
-        }
-        catch (error) {
-            this.logger.error('[playwriter] Failed to disable ghost cursor', error);
-        }
-    }
-    async show(options) {
-        const { page, cursorOptions } = options;
-        await enableGhostCursor({ page, cursorOptions });
-    }
-    async hide(options) {
-        const { page } = options;
-        await disableGhostCursor({ page });
-    }
-}
-//# sourceMappingURL=recording-ghost-cursor.js.map

package/dist/recording-ghost-cursor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"recording-ghost-cursor.js","sourceRoot":"","sources":["../src/recording-ghost-cursor.ts"],"names":[],"mappings":"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"}