chrometools-mcp 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.5.0] - 2026-01-21
+
+### Added
+- **`selectOption` tool** - Select options in HTML dropdown elements with intelligent priority-based selection
+  - Parameters: `selector` (required), `value`, `text`, or `index` (specify at least one)
+  - Selection priority: value → text → index (tries value first, falls back to text, then index)
+  - Automatically triggers `input` and `change` events for React and other frameworks
+  - Returns selected option details (value, text, index)
+  - Location: `index.js:911-979`, schemas in `server/tool-schemas.js:40-45`, definitions in `server/tool-definitions.js:234-247`, tool group in `server/tool-groups.js:10`
+
+- **`drag` tool** - Drag element by mouse (click-hold-move-release) in any direction
+  - Parameters: `selector` (required), `direction` (required: 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right'), `distance` (optional, default: 100), `duration` (optional, default: 500ms)
+  - Emulates real mouse drag: moves to element center, presses button, drags, releases button
+  - Supports 8 directions including 4 diagonal directions for maximum flexibility
+  - Use for: interactive maps (Google Maps, Leaflet), Gantt charts, SVG diagrams, canvas, drag-to-pan interfaces
+  - NOT for: standard overflow scrollbars (use `scrollTo` or `scrollHorizontal` instead)
+  - Location: `index.js:982-1091`, schemas in `server/tool-schemas.js:47-53`, definitions in `server/tool-definitions.js:248-261`, tool group in `server/tool-groups.js:10`
+
+- **`scrollHorizontal` tool** - Scroll element horizontally for tables, carousels, and wide content
+  - Parameters: `selector` (required), `direction` (required: 'left' or 'right'), `amount` (required: pixels or 'full'), `behavior` (optional: 'auto' or 'smooth')
+  - Supports precise pixel-based scrolling or 'full' to scroll to the end
+  - Returns detailed scroll state: position, total width, visible width, and scroll availability (canScrollLeft, canScrollRight)
+  - Uses native `scrollTo` API with smooth/auto behavior options
+  - Location: `index.js:1055-1117`, schemas in `server/tool-schemas.js:55-60`, definitions in `server/tool-definitions.js:262-275`, tool group in `server/tool-groups.js:10`
+
+### Fixed
+- **🔥 CRITICAL: Fixed `drag` tool implementation** - Now correctly emulates mouse drag instead of changing scrollLeft/scrollTop
+  - Problem: Previous implementation used `scrollLeft`/`scrollTop` animation which only works for `overflow: auto/scroll` containers
+  - Impact: **Did not work with custom drag-to-scroll interfaces** like:
+    - ❌ Interactive maps (Google Maps, Leaflet, Mapbox)
+    - ❌ Gantt charts and timeline diagrams (SVG-based)
+    - ❌ Canvas elements with pan/zoom
+    - ❌ Custom drag handlers (React DnD, interact.js)
+  - Solution: Complete rewrite using Puppeteer's `page.mouse` API:
+    1. Finds element center position
+    2. Moves mouse to center (`page.mouse.move`)
+    3. Presses mouse button (`page.mouse.down`)
+    4. Drags to target position with smooth motion (`page.mouse.move` with steps)
+    5. Releases mouse button (`page.mouse.up`)
+  - Result: **Now works with ANY drag-scrollable element** including SVG diagrams, maps, and custom implementations
+  - Location: `index.js:982-1091`, updated description in `README.md:277-285`
+  - Reported by: User testing on Gantt chart with `<svg class="gantt">` element
+
+- **Fixed `analyzePage` crash with `includeAll: true` on SVG elements** - Now handles both HTML and SVG className types
+  - Problem: `className.split is not a function` error when page contains SVG elements
+  - Cause: SVG elements have `className` as `SVGAnimatedString` object (with `.baseVal` property), not a string
+  - Solution: Added type checking - uses `className.baseVal` for SVG elements, direct string for HTML
+  - Location: `index.js:2126-2137`
+
+- **🔥 CRITICAL: Fixed Tailwind CSS selector generation bug** - `getUniqueSelectorInPage` now works correctly with Tailwind/utility-first CSS frameworks
+  - Problem: Generated invalid CSS selectors like `button.hover:bg-blue-700` containing special characters (`:`, `/`, `[]`)
+  - Impact: **ALL AI-powered tools failed** with `SyntaxError: invalid selector` on Tailwind/styled-components apps:
+    - ❌ `analyzePage` - couldn't read page state
+    - ❌ `findElementsByText` - couldn't find elements by text
+    - ❌ `smartFindElement` - couldn't find elements by description
+    - ❌ `getAllInteractiveElements` - couldn't list interactive elements
+  - Solution: Complete rewrite of selector generation logic with intelligent filtering:
+    1. **New priority hierarchy** (most reliable first):
+       - `#id` (ID attribute)
+       - `[data-testid="..."]` (test IDs, very common in modern apps)
+       - `[data-*="..."]` (other data attributes)
+       - `[aria-label="..."]` (accessibility labels)
+       - `[role="..."]` (ARIA roles)
+       - `[name="..."]` (form element names)
+       - `tag.semantic-class` (non-Tailwind classes only)
+       - `tag:nth-of-type(n)` (fallback with path)
+    2. **Tailwind class filtering** - New `isTailwindClass()` function detects and excludes:
+       - Variant classes with `:` (hover:, focus:, md:, lg:, etc.)
+       - Fraction classes with `/` (w-1/2, space-x-1/2)
+       - Arbitrary values with `[]` (bg-[#1da1f2], w-[500px])
+       - 60+ common Tailwind prefixes (bg-, text-, p-, m-, flex-, etc.)
+    3. **CSS.escape() integration** - All selectors properly escaped (with fallback for old browsers)
+    4. **Semantic attribute prioritization** - Prefers stable, meaningful selectors over utility classes
+  - Result: **Unblocks testing of ALL modern apps** using Tailwind, styled-components, CSS modules, Emotion, etc.
+  - Location: `element-finder-utils.js:316-509` (complete rewrite, ~200 lines)
+  - Reported by: AI agent encountering `SyntaxError` on every tool call in React+Tailwind app
+
+### Changed
+- **Improved tool descriptions for better AI agent behavior** - Prevents premature use of `executeScript`
+  - `click` - Emphasized as PRIMARY tool for clicking, works with React/Vue/Angular synthetic events
+  - `type` - Emphasized as PRIMARY tool for input, updates React hooks and Vue reactive data correctly
+  - `executeScript` - ⚠️ Marked as LAST RESORT with strict warnings, never use for clicking/typing/reading
+  - `findElementsByText` - Highlighted as alternative to executeScript for finding elements
+  - `analyzePage` - Emphasized as PRIMARY tool for reading page state, more efficient than executeScript
+  - Location: `server/tool-definitions.js:31,45,162,510,489`
+
+- **Added "Tool Usage Priority" section to README** - Clear hierarchy preventing executeScript abuse
+  - Three workflows: Clicking/Interaction, Filling Forms, Reading Page State
+  - Each shows specialized tools first (click, type, analyzePage), executeScript last
+  - Explains why specialized tools work with React/Vue/Angular while executeScript may fail
+  - Location: `README.md:116-147`
+
+- **`analyzePage` enhancement** - Now detects and reports HTML select elements with all available options
+  - Select fields in forms and inputs sections now include `options` array with value, text, index, selected, and disabled status
+  - Includes `selectedIndex`, `selectedValue`, and `selectedText` for current selection
+  - Enables AI agents to see all dropdown options without additional queries
+  - Makes `selectOption` tool usage more intelligent and reliable
+  - Location: `index.js:1632-1660` (forms), `index.js:1691-1713` (inputs)
+
+- **Tool groups** - Added 3 new tools to `interaction` group: `selectOption`, `dragScroll`, `scrollHorizontal`
+  - Total interaction tools: 8 (was 5)
+  - Total tools in project: 44+ (was 40+)
+  - Location: `server/tool-groups.js:10`
+
+- **`convertFigmaToCode` tool** - Convert Figma designs to React/Tailwind code with AI assistance
+  - Parameters: `figmaToken` (optional), `fileKey` (required), `nodeId` (required), `framework` (optional: 'react', 'react-typescript', 'html'), `includeComments` (optional, default: true)
+  - Fetches design structure (layout, colors, typography, spacing) and rendered image at 2x scale
+  - Returns AI-optimized instruction prompt with simplified JSON structure and framework-specific guidelines
+  - Supports React (JavaScript), React (TypeScript), and pure HTML with Tailwind CSS
+  - Generates clean, semantic code with proper spacing, accessibility, and component structure
+  - Uses existing Figma token mechanism (from parameter or FIGMA_TOKEN env var)
+  - Location: `index.js:1676-1779`, schemas in `server/tool-schemas.js:225-231`, definitions in `server/tool-definitions.js:448-462`, tool group in `server/tool-groups.js:53`, helper in `figma-tools.js:381-499`
+
+- **`simplifyNode` helper** - New function in figma-tools.js for code generation
+  - Recursively extracts essential design properties from Figma node structure
+  - Captures: layout (flexbox), dimensions, padding/gaps, colors (fills/strokes), effects (shadows), typography, border radius
+  - Filters out invisible elements and rounds numeric values for cleaner output
+  - Used by `convertFigmaToCode` to provide AI with actionable design data
+  - Location: `figma-tools.js:381-499`
+
 ## [2.4.2] - 2026-01-05
 
 ### Added

package/README.md

@@ -8,10 +8,10 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 - [Usage](#usage)
 - [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
 - [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
-- [Available Tools](#available-tools) - **40+ Tools Total**
+- [Available Tools](#available-tools) - **44+ Tools Total**
   - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
-  - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo
+  - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, dragScroll, scrollHorizontal
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
   - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
@@ -113,6 +113,39 @@ executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })
 
 ## Available Tools
 
+### ⚠️ Tool Usage Priority
+
+**CRITICAL: Always use specialized tools first. Never jump to `executeScript` as first choice.**
+
+#### For Clicking/Interaction
+1. ✅ **`click()`** - PRIMARY tool for all clicks
+   - Works correctly with React/Vue/Angular synthetic events
+   - Handles button clicks, link navigation, form submissions
+2. ✅ **`findElementsByText()` + action** - When selector is unknown, find by text
+3. ⚠️ **`executeScript()`** - LAST RESORT, only if above failed
+
+#### For Filling Forms
+1. ✅ **`type()`** - PRIMARY tool for all text input
+   - Properly updates React hooks, Vue reactive data
+   - Auto-clears field before typing (configurable)
+2. ⚠️ **`executeScript()`** - LAST RESORT, only if above failed
+
+#### For Reading Page State
+1. ✅ **`analyzePage()`** - PRIMARY tool for reading page content
+   - Gets forms, inputs, buttons, links with current values
+   - Use `refresh: true` after interactions to see updated state
+   - Efficient: 2-5k tokens vs screenshot 15-25k
+2. ✅ **`findElementsByText()`** - Find specific elements by visible text
+3. ✅ **`getElement()`** - Get HTML of specific element
+4. ⚠️ **`executeScript()`** - LAST RESORT, only if above failed
+
+**Why specialized tools matter:**
+- ✅ Trigger proper browser events (click, input, change)
+- ✅ Work with React/Vue/Angular synthetic event systems
+- ✅ Update framework state correctly (React hooks, Vue reactivity)
+- ✅ Handle animations, navigation, and async updates
+- ❌ `executeScript` bypasses framework events and may fail silently
+
 ### AI-Powered Tools
 
 #### smartFindElement ⭐
@@ -229,6 +262,40 @@ Scroll page to bring element into view.
 - **Use case**: Lazy loading, sticky elements, visibility checks
 - **Returns**: Final scroll position
 
+#### selectOption
+Select option in dropdown (HTML select elements). Automatically detected by analyzePage with all available options.
+- **Parameters**:
+  - `selector` (required): CSS selector for select element
+  - `value` (optional): Option value attribute (priority 1)
+  - `text` (optional): Option text content (priority 2)
+  - `index` (optional): Option index, 0-based (priority 3)
+- **Use case**: Form dropdowns, filtering, selection menus
+- **Returns**: Selected option details (value, text, index)
+- **Selection priority**: If multiple parameters specified, tries value → text → index
+- **AI Integration**: Use `analyzePage` to see all available options with their values, text, and indices
+
+#### drag
+Drag element by mouse (click-hold-move-release). Simulates real mouse drag, not scrollbar scrolling.
+- **Parameters**:
+  - `selector` (required): CSS selector for element to drag
+  - `direction` (required): 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right'
+  - `distance` (optional): Distance in pixels (default: 100)
+  - `duration` (optional): Drag duration in milliseconds (default: 500)
+- **Use case**: Interactive maps (Google Maps, Leaflet), Gantt charts, SVG diagrams, canvas elements, sliders, drag-to-pan interfaces
+- **How it works**: Moves mouse to element center, presses mouse button, drags to target position, releases button
+- **NOT for**: Standard overflow scrollbars (use `scrollTo` or `scrollHorizontal` instead)
+- **Returns**: Start/end mouse positions and drag delta
+
+#### scrollHorizontal
+Scroll element horizontally (for tables, carousels, wide content).
+- **Parameters**:
+  - `selector` (required): CSS selector for element to scroll
+  - `direction` (required): 'left' or 'right'
+  - `amount` (required): Number of pixels to scroll, or 'full' to scroll to the end
+  - `behavior` (optional): 'auto' or 'smooth' (default: 'auto')
+- **Use case**: Wide tables, image carousels, horizontally scrollable containers
+- **Returns**: Scroll state (position, total width, visible width, scroll availability)
+
 ### 3. Inspection Tools
 
 #### getElement
@@ -472,6 +539,27 @@ Extract complete color palette with usage statistics.
   - Usage examples (where the color is used)
   - Sorted by usage frequency
 
+#### convertFigmaToCode ⭐ NEW
+Convert Figma designs to React/Tailwind code with AI assistance.
+- **Parameters**:
+  - `figmaToken` (optional): Figma API token
+  - `fileKey` (required): Figma file key
+  - `nodeId` (required): Frame/component ID (formats: '123:456' or '123-456')
+  - `framework` (optional): 'react', 'react-typescript', or 'html' (default: 'react')
+  - `includeComments` (optional): Include code comments (default: true)
+- **Use case**: Rapid prototyping, design-to-code workflow, implementing Figma designs
+- **How it works**:
+  1. Fetches design structure (layout, colors, typography, spacing)
+  2. Gets rendered design image at 2x resolution
+  3. Returns AI-optimized instructions with simplified JSON structure
+  4. AI generates clean React/Tailwind code matching the design
+- **Returns**: Formatted instruction prompt containing:
+  - Design image reference
+  - Simplified JSON structure with layout, styling, text properties
+  - Framework-specific guidelines (React components, TypeScript types, Tailwind classes)
+  - Quality requirements (semantic HTML, accessibility, accurate spacing)
+- **Best for**: UI components, landing pages, card designs, navigation bars
+
 #### getFigmaFrame
 Export and download a Figma frame as PNG/JPG image with automatic compression.
 - **Parameters**:
@@ -997,9 +1085,9 @@ Each tool definition is sent to the AI in every request, consuming context token
 | `debug` | Debugging & network | `getConsoleLogs`, `listNetworkRequests`, `getNetworkRequest`, `filterNetworkRequests` (4) |
 | `advanced` | Advanced automation & AI | `executeScript`, `setStyles`, `setViewport`, `getViewport`, `navigateTo`, `smartFindElement`, `analyzePage`, `getAllInteractiveElements`, `findElementsByText` (9) |
 | `recorder` | Scenario recording | `enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`, `appendScenarioToFile`, `generatePageObject` (9) |
-| `figma` | Figma integration | `getFigmaFrame`, `compareFigmaToElement`, `getFigmaSpecs`, `parseFigmaUrl`, `listFigmaPages`, `searchFigmaFrames`, `getFigmaComponents`, `getFigmaStyles`, `getFigmaColorPalette` (9) |
+| `figma` | Figma integration | `getFigmaFrame`, `compareFigmaToElement`, `getFigmaSpecs`, `parseFigmaUrl`, `listFigmaPages`, `searchFigmaFrames`, `getFigmaComponents`, `getFigmaStyles`, `getFigmaColorPalette`, `convertFigmaToCode` (10) |
 
-**Total:** 43 tools across 7 groups
+**Total:** 44 tools across 7 groups
 
 **Configuration:**
 

package/RELEASE_NOTES_v2.5.0.md

@@ -0,0 +1,109 @@
+# Release v2.5.0 - Major Update: 4 New Tools + Critical Fixes
+
+## 🎉 New Tools (4)
+
+### 1. `selectOption` - Dropdown Selection
+Select options in HTML dropdown elements with intelligent priority-based selection.
+- **Parameters**: `selector`, `value`, `text`, or `index`
+- **Priority**: value → text → index
+- **React/Vue support**: Automatically triggers input/change events
+- Perfect for automated form filling
+
+### 2. `drag` - Mouse Drag Emulation
+Drag elements by mouse (click-hold-move-release) in any direction.
+- **8 directions**: up, down, left, right, + 4 diagonals
+- **Use cases**: Interactive maps, Gantt charts, SVG diagrams, canvas
+- **How it works**: Puppeteer's `page.mouse` API for real drag events
+- **NOT for**: Standard overflow scrollbars (use `scrollTo` instead)
+
+### 3. `scrollHorizontal` - Horizontal Scrolling
+Scroll elements horizontally for tables, carousels, and wide content.
+- **Directions**: left, right
+- **Amount**: Pixels or 'full' to scroll to end
+- **Behavior**: smooth or auto
+- Returns detailed scroll state
+
+### 4. `convertFigmaToCode` ⭐
+Convert Figma designs to React+Tailwind code.
+- **Frameworks**: React, React TypeScript, HTML
+- **Styling**: Tailwind CSS optimized
+- **Input**: Figma file key + node ID
+- **Output**: Clean, semantic component code with AI-generated instructions
+
+## 🔥 Critical Fixes
+
+### Fixed Tailwind CSS Selector Generation Bug
+**Impact**: ALL AI tools failed on Tailwind/styled-components apps with `SyntaxError: invalid selector`
+
+**Affected tools**:
+- ❌ `analyzePage` - couldn't read page state
+- ❌ `findElementsByText` - couldn't find elements
+- ❌ `smartFindElement` - couldn't locate elements
+- ❌ `getAllInteractiveElements` - couldn't list interactive elements
+
+**Solution**:
+- New `isTailwindClass()` function filters utility classes with `:`, `/`, `[]`
+- Smart priority: id → data-testid → aria-label → semantic classes
+- CSS.escape() for all selectors
+- **Result**: ✅ Unblocks testing of ALL modern apps (Tailwind, styled-components, CSS modules, Emotion)
+
+### Fixed `drag` Tool Implementation
+Previously used `scrollLeft`/`scrollTop` which only works with `overflow: auto/scroll` containers.
+
+**Now works with**:
+- ✅ Interactive maps (Google Maps, Leaflet, Mapbox)
+- ✅ Gantt charts and SVG diagrams
+- ✅ Canvas elements with pan/zoom
+- ✅ Custom drag handlers (React DnD, interact.js)
+
+### Fixed `analyzePage` SVG Crash
+Fixed `className.split is not a function` error when page contains SVG elements.
+- Now handles both HTML (string) and SVG (SVGAnimatedString) className types
+
+## 🔧 Improvements
+
+### Better AI Agent Behavior
+- Improved tool descriptions to prevent premature `executeScript` usage
+- `click`, `type`, `analyzePage` emphasized as PRIMARY tools
+- `executeScript` marked as ⚠️ LAST RESORT
+- New "Tool Usage Priority" section in README
+
+### Enhanced `analyzePage`
+- Now detects HTML select elements with all options
+- Returns: value, text, index, selected, disabled status
+- Enables smarter `selectOption` usage
+
+## 📊 Stats
+
+- **Total tools**: 44 (was 40)
+- **Files changed**: 9
+- **Lines added**: +957
+- **Lines removed**: -48
+
+## 🚀 Installation
+
+```bash
+npx chrometools-mcp
+```
+
+Or update in your MCP config:
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "command": "npx",
+      "args": ["chrometools-mcp"]
+    }
+  }
+}
+```
+
+## 🙏 Contributors
+
+Special thanks to users who reported issues:
+- Tailwind CSS selector bug reporter
+- Gantt chart drag testing feedback
+
+---
+
+**Full Changelog**: https://github.com/docentovich/chrometools-mcp/blob/main/CHANGELOG.md

package/element-finder-utils.js

@@ -305,73 +305,181 @@ function isSafeSelectorValue(value) {
   return !/["'\\[\]{}()]/.test(value);
 }
 
+/**
+ * Check if a class name is a Tailwind CSS utility class
+ * Tailwind classes contain special characters that break CSS selectors:
+ * - Colons (:) for variants like hover:, focus:, md:, etc.
+ * - Slashes (/) for fractions like w-1/2
+ * - Brackets ([]) for arbitrary values like bg-[#1da1f2]
+ * - Dots (.) in decimal values
+ */
+function isTailwindClass(className) {
+  if (!className || typeof className !== 'string') return false;
+
+  // Check for special characters that indicate Tailwind variants/utilities
+  if (/[:\/\[\]]/.test(className)) {
+    return true;
+  }
+
+  // Common Tailwind utility prefixes
+  const tailwindPrefixes = [
+    'bg-', 'text-', 'border-', 'rounded-', 'shadow-', 'font-', 'leading-',
+    'flex-', 'grid-', 'p-', 'px-', 'py-', 'pt-', 'pb-', 'pl-', 'pr-',
+    'm-', 'mx-', 'my-', 'mt-', 'mb-', 'ml-', 'mr-', 'space-',
+    'w-', 'h-', 'min-', 'max-', 'gap-', 'inset-', 'top-', 'right-', 'bottom-', 'left-',
+    'justify-', 'items-', 'content-', 'self-', 'place-',
+    'overflow-', 'opacity-', 'cursor-', 'transition-', 'transform-',
+    'duration-', 'ease-', 'delay-', 'animate-', 'scale-', 'rotate-', 'translate-',
+    'z-', 'order-', 'col-', 'row-', 'auto-', 'tracking-', 'select-',
+    'sr-', 'not-', 'pointer-', 'resize-', 'list-', 'appearance-',
+    'underline', 'line-through', 'no-underline', 'uppercase', 'lowercase', 'capitalize',
+    'italic', 'not-italic', 'ordinal', 'slashed-zero', 'lining-nums', 'oldstyle-nums',
+    'proportional-nums', 'tabular-nums', 'diagonal-fractions', 'stacked-fractions',
+    'hidden', 'block', 'inline', 'flex', 'grid', 'table', 'contents',
+    'absolute', 'relative', 'fixed', 'sticky', 'static'
+  ];
+
+  // Check if className starts with known Tailwind prefix
+  return tailwindPrefixes.some(prefix => className.startsWith(prefix));
+}
+
 /**
  * Generate unique CSS selector for an element
+ * Priority: id → data-testid → data-* → aria-label → role → semantic classes → nth-child
+ * Filters out Tailwind CSS classes to avoid invalid selectors
  */
 function getUniqueSelectorInPage(element) {
-  // Try ID first
-  if (element.id) {
-    return `#${element.id}`;
+  const tagName = element.tagName.toLowerCase();
+
+  // 1. Try ID first (highest priority)
+  if (element.id && isSafeSelectorValue(element.id)) {
+    try {
+      return `#${CSS.escape(element.id)}`;
+    } catch (e) {
+      // CSS.escape not available in old browsers, use simple escape
+      return `#${element.id.replace(/[^\w-]/g, '\\$&')}`;
+    }
   }
 
-  // Try unique class combination
-  if (element.className) {
-    const classes = element.className.split(' ').filter(c => c.trim());
-    if (classes.length > 0) {
-      const selector = `${element.tagName.toLowerCase()}.${classes.join('.')}`;
+  // 2. Try data-testid (very common in modern apps)
+  if (element.dataset && element.dataset.testid && isSafeSelectorValue(element.dataset.testid)) {
+    const selector = `[data-testid="${element.dataset.testid}"]`;
+    try {
       if (document.querySelectorAll(selector).length === 1) {
         return selector;
       }
-      // Try with first class only
-      const firstClassSelector = `${element.tagName.toLowerCase()}.${classes[0]}`;
-      if (document.querySelectorAll(firstClassSelector).length === 1) {
-        return firstClassSelector;
+    } catch (e) {
+      // Invalid selector, continue
+    }
+  }
+
+  // 3. Try other data-* attributes (only if values are safe)
+  const dataAttrs = Array.from(element.attributes)
+    .filter(attr => attr.name.startsWith('data-') &&
+                    attr.name !== 'data-testid' &&
+                    isSafeSelectorValue(attr.value))
+    .slice(0, 2);
+
+  for (const attr of dataAttrs) {
+    const selector = `${tagName}[${attr.name}="${attr.value}"]`;
+    try {
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
       }
+    } catch (e) {
+      continue;
     }
   }
 
-  // Try name attribute (only if value is safe)
-  if (element.name && isSafeSelectorValue(element.name)) {
-    const selector = `${element.tagName.toLowerCase()}[name="${element.name}"]`;
+  // 4. Try aria-label
+  const ariaLabel = element.getAttribute('aria-label');
+  if (ariaLabel && isSafeSelectorValue(ariaLabel)) {
+    const selector = `${tagName}[aria-label="${ariaLabel}"]`;
     try {
       if (document.querySelectorAll(selector).length === 1) {
         return selector;
       }
     } catch (e) {
-      // Invalid selector, skip
+      // Invalid selector, continue
     }
   }
 
-  // Try data attributes (only if values are safe)
-  const dataAttrs = Array.from(element.attributes)
-    .filter(attr => attr.name.startsWith('data-') && isSafeSelectorValue(attr.value))
-    .slice(0, 2);
+  // 5. Try role attribute
+  const role = element.getAttribute('role');
+  if (role && isSafeSelectorValue(role)) {
+    const selector = `${tagName}[role="${role}"]`;
+    try {
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
+      }
+    } catch (e) {
+      // Invalid selector, continue
+    }
+  }
 
-  for (const attr of dataAttrs) {
-    const selector = `${element.tagName.toLowerCase()}[${attr.name}="${attr.value}"]`;
+  // 6. Try name attribute (common for form inputs)
+  if (element.name && isSafeSelectorValue(element.name)) {
+    const selector = `${tagName}[name="${element.name}"]`;
     try {
       if (document.querySelectorAll(selector).length === 1) {
         return selector;
       }
     } catch (e) {
-      // Invalid selector, skip
-      continue;
+      // Invalid selector, continue
+    }
+  }
+
+  // 7. Try semantic classes (filter out Tailwind)
+  if (element.className && typeof element.className === 'string') {
+    const classes = element.className.split(' ')
+      .filter(c => c.trim() && !isTailwindClass(c))
+      .slice(0, 3); // Limit to 3 classes max
+
+    if (classes.length > 0) {
+      try {
+        // Try with all filtered classes
+        const escapedClasses = classes.map(c => {
+          try {
+            return CSS.escape(c);
+          } catch (e) {
+            return c.replace(/[^\w-]/g, '\\$&');
+          }
+        });
+        const selector = `${tagName}.${escapedClasses.join('.')}`;
+        if (document.querySelectorAll(selector).length === 1) {
+          return selector;
+        }
+
+        // Try with first class only
+        const firstClassSelector = `${tagName}.${escapedClasses[0]}`;
+        if (document.querySelectorAll(firstClassSelector).length === 1) {
+          return firstClassSelector;
+        }
+      } catch (e) {
+        // Invalid selector, continue to fallback
+      }
     }
   }
 
-  // Fallback: nth-child
+  // 8. Fallback: nth-of-type with path
   let current = element;
   const path = [];
 
   while (current && current.tagName) {
     let selector = current.tagName.toLowerCase();
 
-    if (current.id) {
-      selector = `#${current.id}`;
+    // Stop at element with ID
+    if (current.id && isSafeSelectorValue(current.id)) {
+      try {
+        selector = `#${CSS.escape(current.id)}`;
+      } catch (e) {
+        selector = `#${current.id.replace(/[^\w-]/g, '\\$&')}`;
+      }
       path.unshift(selector);
       break;
     }
 
+    // Calculate nth-of-type
     let sibling = current;
     let nth = 1;
 
@@ -382,7 +490,9 @@ function getUniqueSelectorInPage(element) {
       }
     }
 
-    if (nth > 1) {
+    // Only add nth-of-type if there are multiple siblings of same type
+    if (nth > 1 || (current.parentElement &&
+        Array.from(current.parentElement.children).filter(c => c.tagName === current.tagName).length > 1)) {
       selector += `:nth-of-type(${nth})`;
     }