chrometools-mcp 2.4.2 → 3.1.2

package/CHANGELOG.md

@@ -2,6 +2,546 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.1.2] - 2026-01-26
+
+### Added
+- **Multi-tab scenario recording** — Automatic recording of tab switches during scenario capture
+  - When user switches tabs during recording, an `openTab` action is automatically recorded
+  - Records tab URL, title, and switch reason for accurate playback
+  - Only records if switching to a different tab (ignores same-tab activations)
+  - Location: `extension/background.js` (chrome.tabs.onActivated listener)
+
+### Changed
+- **openTab navigation strategy** — Changed from `networkidle2` to `domcontentloaded` in scenario executor
+  - Prevents timeout errors when opening tabs with continuous ad/tracking loading
+  - Consistent with other navigation improvements in 3.1.1
+  - Location: `recorder/scenario-executor.js:979`
+
+### Fixed
+- **openTab with empty URL uses look-ahead to next action's URL** — Smart URL detection for tab switches
+  - When openTab has empty URL, executor looks at next action's tabUrl
+  - If next action has real URL, uses it for tab opening/switching
+  - Fixes scenarios where new tab was opened but URL loaded immediately after
+  - Empty URLs without look-ahead match are still skipped (prevents about:blank tabs)
+  - Location: `recorder/scenario-executor.js:168-176, 987-990`
+
+- **Added 500ms delay before tab switch** — Prevents race conditions during scenario playback
+  - Allows previous tab's pending processes (navigation, AJAX, form submissions) to complete
+  - Ensures stable state before switching to new tab
+  - Location: `recorder/scenario-executor.js:990-992`
+
+## [3.1.1] - 2026-01-26
+
+### Fixed
+- **Scenario recording and saving flow** — Fixed critical bugs preventing scenario recording
+  - Fixed Extension → Bridge → MCP communication flow for recording control
+  - `startRecording` now properly sends command to Extension via Bridge WebSocket
+  - `stopRecording` correctly retrieves recorded actions from Extension state
+  - `saveScenario` now successfully saves scenarios to correct project directory
+  - Recording state properly synchronized between Extension popup and MCP tools
+  - Location: `index.js` (startRecording/stopRecording/saveScenario handlers)
+
+- **Navigation timeout for slow websites** — Fixed timeout errors on sites with continuous loading
+  - Increased navigation timeout from 30s to 60s
+  - Changed wait strategy from `networkidle2` to `domcontentloaded` (less strict)
+  - Fixes timeout errors on sites like Yahoo that continuously load ads and tracking scripts
+  - Location: `browser/page-manager.js:188-193`
+
+### Changed
+- **Improved WebSocket message handling** — Better error reporting and state management
+  - Bridge now properly forwards recording commands to Extension
+  - MCP server correctly receives recording state updates from Bridge
+  - Clear error messages when Extension is not connected or recording fails
+
+## [3.1.0] - 2026-01-26
+
+### Added
+- **Native Messaging Bridge Architecture** — complete rewrite of Extension ↔ MCP communication
+  - Bridge Service runs as Native Messaging Host (launched by Chrome with Extension)
+  - MCP servers connect as WebSocket clients (not servers)
+  - Supports 0-8 simultaneous MCP clients connecting/disconnecting at any time
+  - Full state (tabs, recordings) sent immediately on client connect
+  - No more scanning delays — instant connection to persistent Bridge
+
+- **CLI commands for Bridge management**
+  - `--install-bridge` — Install Native Messaging Bridge (one-time setup)
+  - `--uninstall-bridge` — Remove Bridge installation
+  - `--check-bridge` — Verify Bridge is installed
+  - `--help` — Show all CLI options
+
+- **Stable Extension ID** via manifest key
+  - Extension ID is now deterministic: `dmehkibmncgphijnigkahhlekgajhpbl`
+  - Required for Native Messaging Host registration
+
+- **New extension icons** — Chrome/robot themed design (16, 48, 128px)
+
+### Changed
+- **Extension is now Event Producer** — sends all events to Bridge, doesn't manage WebSocket connections
+- **MCP is now Event Consumer** — connects to Bridge as client, receives state on demand
+- **Bridge lifecycle** — starts with Chrome Extension, stops when Chrome closes
+- Removed port scanning (9223-9227) — Bridge uses single fixed port 9223
+
+### Architecture
+```
+Chrome Extension (producer) → Native Messaging → Bridge Service (:9223) ← WebSocket ← MCP clients (0-8)
+```
+
+### Migration
+1. Run `npx chrometools-mcp --install-bridge` once
+2. Reload Extension in chrome://extensions
+3. Use normally — MCP auto-connects to Bridge
+
+## [3.0.4] - 2026-01-26
+
+### Added
+- **Smart tab tracking for scenario recording**
+  - Recording automatically follows the active tab
+  - When user switches tabs during recording, an `openTab` action is recorded
+  - When user opens new tab, an `openTab` action is recorded
+  - Actions from non-active tabs are automatically filtered out
+  - `openTab` action ensures tab exists during playback (opens tab with URL if not exists)
+  - Scenario executor supports `openTab` with automatic tab reuse and creation
+- **MCP tools for programmatic recording control**
+  - `startRecording` - Start recording from AI/code
+  - `stopRecording` - Stop and retrieve recorded actions
+  - `getRecorderState` - Query current recording state
+  - `saveScenario` - Save recorded actions as scenario
+  - AI agents can now fully control recording without manual interaction
+
+### Changed
+- Recording now tracks `currentTabId` instead of being locked to `startTabId`
+- Content scripts only send actions when their tab is the active recording target
+- Replaced `switchTab`/`newTab` with unified `openTab` action type
+- `openTab` intelligently checks if tab already exists before creating new one
+- `enableRecorder` now mentions programmatic control tools
+
+## [3.0.3] - 2026-01-25
+
+### Added
+- **Multi-instance MCP server support** via dynamic port allocation
+  - MCP server automatically finds available port from range 9223-9227
+  - Chrome Extension scans for running MCP instances every 20 seconds (port scanning)
+  - Extension connects to multiple MCP servers simultaneously (broadcast pattern)
+  - Enables multiple AI clients (Claude Desktop, Telegram bot, etc.) to work in parallel
+  - Graceful handling of ungraceful shutdowns (kill -9) via WebSocket.onclose
+
+### Changed
+- **Auto-sync active tab when user switches tabs manually**
+  - MCP server now syncs Puppeteer's `lastPage` when extension reports `tab_activated`
+  - Callback pattern avoids circular dependencies between websocket-bridge and page-manager
+  - MCP commands automatically target the user's currently active tab
+
+### Fixed
+- **Input recording deduplication** in Chrome Extension
+  - Extension now records only final text value after blur/Enter or 1.5s pause
+  - Eliminated intermediate keystroke recordings (e.g., "test" → "test1" recorded as one action)
+  - Improved debouncing with `inputStartValues` tracking
+
+## [3.0.2] - 2026-01-25
+
+### Added
+- **Extension installation instructions for AI agents**
+  - `listTabs`, `switchTab`, `enableRecorder` now include install steps when extension not connected
+  - `openBrowser` shows warning when connected to existing Chrome (extension needs manual install)
+  - Clear step-by-step instructions with extension path for manual installation
+  - Alternative fix: close all Chrome windows and restart MCP for auto-install
+
+### Changed
+- Improved extension status reporting with `extensionConnected` flag in responses
+
+## [3.0.1] - 2026-01-25
+
+### Fixed
+- **Multi-tab support** - Fixed extension-based tab switching
+  - `switchTab` now uses Chrome Extension for reliable tab switching
+  - Auto-connects Puppeteer to switched tab (fixes `analyzePage` after tab switch)
+  - `puppeteerConnected: true` in response confirms Puppeteer sync
+
+## [3.0.0] - 2026-01-25
+
+### BREAKING CHANGES
+- **Chrome Extension for Recording** - Scenario recording now requires Chrome Extension
+  - Old HTML-injection recorder (`injectRecorder`) removed
+  - Extension auto-loads when Chrome is started by chrometools-mcp
+  - Recording controlled via Extension popup (click CT icon in toolbar)
+
+### Added
+- **ChromeTools Chrome Extension** (`extension/` folder)
+  - Full tab tracking via Chrome tabs API (catches ALL new tabs including Ctrl+T, context menu)
+  - Scenario recording via content script (works across all domains)
+  - Popup UI for recording control
+  - WebSocket connection to MCP server for real-time communication
+
+- **WebSocket Bridge** (`server/websocket-bridge.js`)
+  - Bidirectional communication between Extension and MCP server
+  - Port 9223 (CHROME_DEBUG_PORT + 1)
+  - Tab state sync, recorder commands, scenario save/list
+
+- **Auto-load Extension** - Chrome launched with `--load-extension` flag
+  - Extension automatically installed when Chrome starts
+  - No manual installation required
+
+### Changed
+- `enableRecorder` tool now checks Extension connection status instead of injecting HTML
+- Tab tracking improved: Extension provides complete tab list including manually opened tabs
+- Recording state persisted in `chrome.storage.local` (survives cross-domain navigation)
+
+### Removed
+- `recorder-script.js` HTML injection functionality (still exists for reference)
+- `pagesWithRecorder` tracking (Extension handles this now)
+- `setupRecorderAutoReinjection` function (Extension handles this now)
+
+## [2.9.0] - 2026-01-25
+
+### Added
+- **Automatic new tab detection** - Tracks tabs opened via `window.open()`, `target="_blank"`, or user actions
+  - New tabs automatically become the active page
+  - Network monitoring, console capture, and recorder auto-injection enabled on new tabs
+  - New tab events queued for AI notification via `listTabs`
+
+- **`listTabs` tool** - List all open browser tabs
+  - Returns: `{ tabs: [{ index, url, title, isActive }], totalCount }`
+  - Includes `newTabsDetected` array when new tabs were opened since last check
+  - Use tab index with `switchTab` to change active tab
+
+- **`switchTab` tool** - Switch between browser tabs
+  - Parameters: `tab` - Tab index (number) or URL pattern (string, partial match)
+  - Makes the specified tab active for subsequent commands
+  - Returns: `{ success, switchedTo: { url, title } }`
+
+### Changed
+- `openPages` Map now tracks all tabs including those opened externally
+- Browser `targetcreated` event handler added for automatic tab tracking
+
+## [2.8.0] - 2026-01-25
+
+### Added
+- **`getElementByApomId` tool** - Get detailed element information by APOM ID
+  - Parameters: `id` (required) - APOM element ID from analyzePage (e.g., `"input_20"`)
+  - Returns: Full element details including bounds, attributes, computed styles, visibility
+  - Use case: Inspect specific elements without re-analyzing entire page
+
+### Changed
+- **APOM format optimization** - ~82% token reduction
+  - Tree-structured output with hierarchical parent-child relationships
+  - Minified JSON output (no pretty printing)
+  - Parent nodes contain only position info (no bounds/metadata)
+  - Interactive elements retain full details (bounds, type, metadata)
+  - Groups section for radio/checkbox groups with options
+
+- **Separate `id` and `selector` parameters** for click, type, hover, selectOption
+  - **PREFERRED**: Use `id` parameter with APOM ID from analyzePage (e.g., `click({ id: "button_45" })`)
+  - **ALTERNATIVE**: Use `selector` parameter with CSS selector (e.g., `click({ selector: ".submit" })`)
+  - Parameters are mutually exclusive (use one or the other)
+  - Makes API clearer: agent knows exactly what it's passing
+  - Updated tool descriptions with PREFERRED/ALTERNATIVE guidance
+
+### Removed
+- **`registerPageObject` tool** - No longer needed
+  - `analyzePage()` now automatically registers elements with unique IDs
+  - Use APOM IDs directly with click/type/hover/selectOption tools
+  - Simplifies workflow: just call `analyzePage()` and use the returned IDs
+
+### Performance
+- APOM token usage reduced from ~31,000 to ~5,684 tokens on typical pages
+- Tree structure eliminates redundant parent information
+- Minified JSON further reduces output size
+
+## [2.7.0] - 2026-01-25
+
+### 🔄 BREAKING CHANGE
+- **`analyzePage` now returns APOM format by default**
+  - Previous default was legacy format, now APOM is default
+  - Use `useLegacyFormat: true` to get old format if needed
+  - Migration: `analyzePage()` now returns APOM instead of legacy
+  - Rationale: APOM is superior - provides unique IDs, better structure, automatic registration
+
+### Added
+- **🎉 Agent Page Object Model (APOM) - Now Default Format**
+  - `analyzePage()` returns structured APOM format (no parameters needed!)
+  - New parameter: `useLegacyFormat` - Return old format (default: false)
+  - Parameter: `registerElements` - Auto-register elements (default: true)
+  - Parameter: `groupBy: 'type' | 'flat'` - Control element grouping
+  - Returns: `{ pageId, url, title, timestamp, elements, groups, metadata }`
+  - Each element gets unique ID: `input_0`, `button_1`, `form_0`, `radio_0`, `checkbox_0`
+  - Elements automatically registered in persistent `window.__ELEMENT_REGISTRY__`
+  - **Use IDs instead of CSS selectors**: `type({ id: "input_0", text: "..." })`
+  - **Backward compatible**: Set `useLegacyFormat: true` for old format
+  - **Tested**: Fully functional with real-world forms
+
+- **New POM Modules**
+  - `pom/element-id-generator.js` (171 lines) - Smart ID generation
+    - Priority: data-testid > id attribute > semantic path + index
+    - Supports: input, button, link, form, textarea, select, radio, checkbox
+  - `pom/apom-converter.js` (294 lines) - Convert analyzePage to APOM
+    - Transforms legacy format to structured model
+    - Groups elements by type (forms, inputs, buttons, links)
+    - Generates pageId, metadata
+
+- **Input Models Architecture** - Modular input handling system
+  - New `models/` directory with specialized input handlers
+  - `BaseInputModel` - Abstract base class with common interface (setValue, getValue, clear, focus)
+  - `TextInputModel` - Default for text-like inputs (text, email, password, search, tel, url)
+  - `TimeInputModel` - Correct handling for `input[type="time"]` via JavaScript value assignment
+  - `DateInputModel` - Handles date, datetime-local, month, week inputs
+  - `ColorInputModel` - Color picker input handling
+  - `RangeInputModel` - Slider/range input handling
+  - `SelectModel` - HTML `<select>` element handling
+  - `CheckboxModel` - Single checkbox toggle
+  - `TextareaModel` - Multi-line text input
+  - `InputModelFactory` - Factory pattern for selecting appropriate model
+  - Fixes issue where keyboard input didn't work for time inputs (only minutes showed)
+
+- **Radio/Checkbox Group Models** - Abstract group-level operations
+  - `RadioGroupModel` - Select single option from radio group by name, value, or label text
+  - `CheckboxGroupModel` - Multi-select from checkbox group with modes:
+    - `set` - Replace all selections
+    - `add` - Check additional values
+    - `remove` - Uncheck specific values
+    - `toggle` - Flip specific values
+
+- **`selectFromGroup` tool** - New MCP tool for radio/checkbox group selection
+  - Parameters: `name` (required), `value`, `values`, `text`, `texts`, `mode`, `by`
+  - Works with radio groups (single selection) and checkbox groups (multi-selection)
+  - Match by value attribute or label text (`by: 'value' | 'text' | 'auto'`)
+  - Example: `selectFromGroup({ name: "size", value: "large" })`
+  - Example: `selectFromGroup({ name: "toppings", values: ["cheese", "bacon"], mode: "add" })`
+
+- **Radio/Checkbox Groups in `analyzePage`**
+  - APOM output now includes `groups` section with radio and checkbox groups
+  - Each group shows: name, all options with values, labels, checked state
+  - Labels extracted from: parent `<label>`, `<label for="id">`, aria-label attribute
+  - Example output:
+    ```json
+    "groups": {
+      "radio": {
+        "size": {
+          "options": [
+            { "value": "small", "label": "Small", "checked": false },
+            { "value": "large", "label": "Large", "checked": true }
+          ]
+        }
+      },
+      "checkbox": { ... }
+    }
+    ```
+
+### Fixed
+- **Critical Bug**: Variable shadowing in analyzePage APOM conversion (commit e1e63e2)
+  - Fixed `const analysis` shadowing in else block causing undefined analysis
+- **Critical Bug**: Element registry not persisting across page.evaluate calls (commit faadd0e)
+  - Changed `const elementRegistry = new Map()` to `window.__ELEMENT_REGISTRY__`
+  - Registry now persists between tool calls
+  - All selector-resolver functions exported to window
+- **API Error**: `oneOf` not supported at top level in tool schemas
+  - Removed `oneOf` blocks from click, type, hover, selectOption tool definitions
+  - Both `id` and `selector` parameters now optional with description indicating one is required
+  - Fixes error: `tools.19.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top level`
+
+### Changed
+- **`analyzePage` enhanced with APOM support**
+  - Now supports both legacy and APOM formats
+  - Cache logic updated to handle generateIds parameter
+  - Elements automatically registered when generateIds=true
+  - Radio/checkbox elements now include label text
+
+- **`utils/selector-resolver.js` updated for persistence**
+  - Registry stored in `window.__ELEMENT_REGISTRY__` instead of local const
+  - All functions (registerElement, resolveSelector, etc.) exported to window
+  - Survives across multiple page.evaluate contexts
+
+- **`navigateTo` auto-opens browser** - No longer throws error when no page is open
+  - Automatically opens browser at specified URL if no page is currently open
+  - Eliminates need to manually call `openBrowser` before navigation
+  - Falls back gracefully with informative message
+
+- **`type` tool uses Input Models** - Automatically selects appropriate model based on input type
+  - Time inputs now correctly set full value (e.g., "18:30" not just "30")
+  - Date inputs work without keyboard simulation issues
+  - All specialized inputs handled by their respective models
+
+### Technical Details
+- APOM conversion happens in browser context via page.evaluate
+- Element IDs remain stable across page refreshes (based on testid/id/structure)
+- Dual selector mode: all tools accept both IDs and CSS selectors
+- Input models use JavaScript value assignment with proper event dispatching
+
+## [2.6.0] - 2026-01-25
+
+### Added
+- **UI Framework Detection** - Automatic detection of UI component libraries (MUI, Ant Design, Chakra UI, Bootstrap, Vuetify, Semantic UI)
+  - New utility: `utils/ui-framework-detector.js`
+  - Detects framework name, version, and component type for each element
+  - Integrated into `analyzePage` - all elements now include `uiFramework` field
+  - Extracts options from both native `<select>` and custom framework dropdowns
+
+- **Enhanced Select/Dropdown Options Extraction** - Smart extraction of dropdown options from various UI libraries
+  - Native HTML `<select>` with `<optgroup>` support
+  - Material-UI (MUI) Select components
+  - Ant Design Select components
+  - Chakra UI, Bootstrap, Vuetify, Semantic UI dropdowns
+  - Options include: value, text, index, selected, disabled, group
+  - Handles cases where options aren't rendered until dropdown opens (with informative notes)
+
+- **Page Object ID Support** - Use element IDs instead of CSS selectors
+  - New utility: `utils/selector-resolver.js` - Registry for Page Object element IDs
+  - New tool: `registerPageObject` - Register elements from Page Object for use with IDs
+  - **Backward compatible**: All interaction tools (click, type, selectOption, hover, etc.) now accept BOTH:
+    - Page Object IDs (e.g., `"login_email_input"`)
+    - CSS selectors (e.g., `"input[name='email']"`)
+  - Element registry persists in page context between tool calls
+
+- **`registerPageObject` tool** - Register Page Object elements for ID-based interaction
+  - Parameters:
+    - `elements` (required) - Array of {id, selector, metadata}
+    - `clearExisting` (optional) - Clear registry before registering
+  - Enables using meaningful IDs instead of fragile CSS selectors
+  - Example: After registering, use `click("login_submit_button")` instead of `click("button[type='submit']")`
+
+- **Enhanced Page Object Generation** - Page Objects now include comprehensive element information
+  - Each element gets unique ID: `{name}_{timestamp}_{random}`
+  - Select elements include full options array with groups
+  - UI framework detection for all elements
+  - Metadata includes: type, label, placeholder, required, validation hints
+
+### Changed
+- **`analyzePage` enhanced with UI framework detection**
+  - All form fields and inputs now include `uiFramework` field
+  - Select elements use smart extraction: works with both vanilla HTML and UI frameworks
+  - Better handling of MUI, Ant Design, and other component libraries
+
+- **All interaction tools now support dual selector mode**
+  - Tools affected: `click`, `type`, `selectOption`, `hover`, `scrollTo`, `drag`, `setStyles`
+  - Automatically resolves Page Object IDs to CSS selectors
+  - Error messages indicate whether identifier was Page Object ID or CSS selector
+  - No breaking changes - existing CSS selector usage works unchanged
+
+### Technical Details
+- Selector resolution happens in page context using injected `selector-resolver.js`
+- UI framework detection uses class names, data attributes, and DOM structure analysis
+- Element registry stored in browser page context (survives navigation within same page)
+- New helper function `resolveSelector(page, identifier)` in `index.js`
+
+## [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