add showAriaRefLabels/hideAriaRefLabels to MCP context

- Functions available in execute tool context
- Auto-hide labels after 5 seconds to prevent stale overlays
- Updated README with MCP usage example
- Example saves screenshot to /tmp

README.md

@@ -95,29 +95,31 @@ server.close()
 
 ### Visual Aria Ref Labels
 
-Playwriter includes Vimium-style visual labels that overlay interactive elements, making it easy for AI agents to identify and click elements from screenshots.
-
-```typescript
-import { showAriaRefLabels, hideAriaRefLabels } from 'playwriter'
+Playwriter includes Vimium-style visual labels that overlay interactive elements, making it easy for AI agents to identify and click elements from screenshots. These functions are available in the MCP context.
 
+```javascript
 // Show labels on all visible interactive elements
 const { snapshot, labelCount } = await showAriaRefLabels({ page })
+console.log(`Showing ${labelCount} labels`)
 
-// Take a screenshot - agent sees labeled elements
-const screenshot = await page.screenshot()
+// Take a screenshot with labels visible
+await page.screenshot({ path: '/tmp/labeled-page.png' })
 
-// Agent can click using the aria-ref selector
+// Use the snapshot to find elements, then interact using aria-ref selector
 await page.locator('aria-ref=e5').click()
 
-// Remove labels when done
+// Labels auto-hide after 5 seconds, or remove manually:
 await hideAriaRefLabels({ page })
 ```
 
+**Important:** Labels auto-hide after 5 seconds to prevent stale labels. If the page HTML changes (navigation, dynamic content), call `showAriaRefLabels()` again to get fresh labels matching the current DOM.
+
 **Features:**
 - **Role filtering** - Only shows labels for interactive elements (buttons, links, inputs, etc.)
-- **Visibility detection** - Skips elements covered by modals or overlays using `elementsFromPoint()`
-- **Overlap prevention** - Greedy algorithm skips labels that would overlap with already-placed ones
-- **Color-coded by type** - Warm color scheme helps distinguish element types at a glance
+- **Visibility detection** - Skips elements covered by modals or overlays
+- **Overlap prevention** - Skips labels that would overlap with already-placed ones
+- **Color-coded by type** - Warm color scheme helps distinguish element types
+- **Auto-hide** - Labels disappear after 5 seconds to prevent stale overlays
 
 **Color legend:**
 

playwriter/src/aria-snapshot.ts

@@ -197,16 +197,19 @@ export async function getAriaSnapshot({ page }: { page: Page }): Promise<AriaSna
  * Labels are yellow badges positioned above each element showing the aria ref (e.g., "e1", "e2").
  * Use with screenshots so agents can see which elements are interactive.
  *
+ * Labels auto-hide after 5 seconds to prevent stale labels remaining on the page.
+ * Call this function again if the page HTML changes to get fresh labels.
+ *
  * By default, only shows labels for truly interactive roles (button, link, textbox, etc.)
  * to reduce visual clutter. Set `interactiveOnly: false` to show all elements with refs.
  *
  * @example
  * ```ts
  * const { snapshot, labelCount } = await showAriaRefLabels({ page })
- * const screenshot = await page.screenshot()
+ * await page.screenshot({ path: '/tmp/screenshot.png' })
  * // Agent sees [e5] label on "Submit" button
  * await page.locator('aria-ref=e5').click()
- * await hideAriaRefLabels({ page })
+ * // Labels auto-hide after 5 seconds, or call hideAriaRefLabels() manually
  * ```
  */
 export async function showAriaRefLabels({ page, interactiveOnly = true }: {
@@ -393,6 +396,12 @@ export async function showAriaRefLabels({ page, interactiveOnly = true }: {
       }
 
       doc.documentElement.appendChild(container)
+
+      // Auto-hide labels after 5 seconds to prevent stale labels
+      win.setTimeout(() => {
+        doc.getElementById(containerId)?.remove()
+      }, 5000)
+
       return count
     },
     {

playwriter/src/assets/aria-labels-google-snapshot.txt

@@ -31,7 +31,7 @@
     - generic [ref=e55]:
       - text: "Google offered in:"
       - link [ref=e56] [cursor=pointer]:
-        - /url: https://www.google.com/setprefs?sig=0_ONtbUSl6RHgXjr8-VtrSj8Fbgus%3D&hl=it&source=homepage&sa=X&ved=0ahUKEwia5cnuzu-RAxVO78kDHZbbBV8Q2ZgBCBU
+        - /url: https://www.google.com/setprefs?sig=0_rBKrQWz6eh9LiHviDdhtYH9CsEc%3D&hl=it&source=homepage&sa=X&ved=0ahUKEwiR9Py10O-RAxWpGDQIHWbZLRoQ2ZgBCBU
         - text: Italiano
     - contentinfo [ref=e58]:
       - generic [ref=e59]: Italy

playwriter/src/mcp.ts

@@ -21,6 +21,7 @@ import { Editor } from './editor.js'
 import { getStylesForLocator, formatStylesAsText, type StylesResult } from './styles.js'
 import { getReactSource, type ReactSourceLocation } from './react-source.js'
 import { ScopedFS } from './scoped-fs.js'
+import { showAriaRefLabels, hideAriaRefLabels } from './aria-snapshot.js'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
@@ -85,6 +86,8 @@ interface VMContext {
   getStylesForLocator: (options: { locator: any }) => Promise<StylesResult>
   formatStylesAsText: (styles: StylesResult) => string
   getReactSource: (options: { locator: any }) => Promise<ReactSourceLocation | null>
+  showAriaRefLabels: (options: { page: Page; interactiveOnly?: boolean }) => Promise<{ snapshot: string; labelCount: number }>
+  hideAriaRefLabels: (options: { page: Page }) => Promise<void>
   require: NodeRequire
   import: (specifier: string) => Promise<any>
 }
@@ -877,6 +880,8 @@ server.tool(
         getStylesForLocator: getStylesForLocatorFn,
         formatStylesAsText,
         getReactSource: getReactSourceFn,
+        showAriaRefLabels,
+        hideAriaRefLabels,
         resetPlaywright: async () => {
           const { page: newPage, context: newContext } = await resetConnection()
 
@@ -896,6 +901,8 @@ server.tool(
             getStylesForLocator: getStylesForLocatorFn,
             formatStylesAsText,
             getReactSource: getReactSourceFn,
+            showAriaRefLabels,
+            hideAriaRefLabels,
             resetPlaywright: vmContextObj.resetPlaywright,
             require: sandboxedRequire,
             // TODO --experimental-vm-modules is needed to make import work in vm