From d4072d41b61060f9c8bf419e1052f83bc432cf1c Mon Sep 17 00:00:00 2001
From: "Tommy D. Rossi" <beats.by.morse@gmail.com>
Date: Sat, 3 Jan 2026 15:52:02 +0100
Subject: [PATCH] document showAriaRefLabels feature in README

---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 75bae5b..69ebb4f 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,44 @@ await browser.close()
 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'
+
+// Show labels on all visible interactive elements
+const { snapshot, labelCount } = await showAriaRefLabels({ page })
+
+// Take a screenshot - agent sees labeled elements
+const screenshot = await page.screenshot()
+
+// Agent can click using the aria-ref selector
+await page.locator('aria-ref=e5').click()
+
+// Remove labels when done
+await hideAriaRefLabels({ page })
+```
+
+**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
+
+**Color legend:**
+
+| Color | Element Types |
+|-------|---------------|
+| Yellow | Links |
+| Orange | Buttons |
+| Coral | Text inputs (textbox, combobox, searchbox) |
+| Pink | Checkboxes, radios, switches |
+| Peach | Sliders |
+| Salmon | Menu items |
+| Amber | Tabs, options |
+
 ### Environment Variables
 
 #### `PLAYWRITER_AUTO_ENABLE`