flutter_skill

Fix EACCES: ensure native binary has execute permission before spawn

Fix inspect empty text, Flutter 3.38+ URI detection, MCP stdout pollution, Homebrew arm64 on Intel, Windows flutter command

Full Changelog: v0.9.33...v0.9.34

Full Changelog: v0.9.32...v0.9.33

Full Changelog: v0.9.31...v0.9.32

Full Changelog: v0.9.30...v0.9.31

Full Changelog: v0.9.29...v0.9.30

Full Changelog: v0.9.28...v0.9.29

Full Changelog: v0.9.27...v0.9.28

Full Changelog: v0.9.26...v0.9.27

• Added --chrome-port=N as an alias for --cdp-port=N for better compatibility
• Fixed: Parsing of --chrome-port parameter (previously threw FormatException)
• This allows connecting to Chrome instances running on non-default ports (e.g., 18800)

fix coordinate system: filter non-active routes, fix tap(ref: elem_NNN), fix off-screen tap detection

Changes

• TODO: Add your changes here

fix 6 UX issues: DTD error detection, wider port scan, connect_by_pid, stale session cleanup, screenshot save_to_file default

Changes

• TODO: Add your changes here

fix null check crash and stop auto-opening browser on RPC errors from target app

Changes

• TODO: Add your changes here

Support Chrome 146 WebMCP: discover and call navigator.modelContextTesting tools

Changes

• Added Chrome 146+ native WebMCP support to discover_page_tools and call_page_tool
• discover_page_tools now checks navigator.modelContextTesting.getTools() first (source: webmcp-native)
• call_page_tool now routes to navigator.modelContextTesting.executeTool() for WebMCP tools
• Enable via chrome://flags/#enable-webmcp-testing in Chrome 146
• Compatible with all existing tool discovery sources (js-registered, data-mcp-tool, forms, etc.)

Auto-accept Chrome 146 remote debugging consent dialog

Changes

• Chrome 146 consent port shows "Allow remote debugging?" dialog on every connection — user had to manually click Allow each time
• Now auto-clicks the Allow button via macOS Accessibility API (AXSheet + AXButton description="Allow") in parallel with the WebSocket connection
• Users no longer need to manually confirm remote debugging — connect_cdp works seamlessly

Fix Chrome 146 consent port: skip Origin header in WebSocket upgrade

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Support Chrome 146 consent-based remote debugging port

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Session-copy profile: preserve user logins when Chrome 145+ blocks default profile debug port

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Fix Chrome 145+ silently ignoring --remote-debugging-port on default profile

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Remove Chrome for Testing dependency from CDP driver

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Fix Page.enable hang on chrome://newtab; auto-enable remote debugging

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Auto-tick chrome remote debugging checkbox; no Chrome restart

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Restart existing Chrome with debug port; preserve user session

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Auto-enable Chrome remote debugging when connecting via CDP

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

UX fixes: fill tool, press_key iOS fallback, go_back count, coordinate hint

Bug Fixes

• fill tool registered: fill was documented but threw Unknown tool: fill. Now maps to enter_text (clear + set value). Closes user-reported issue.
• press_key on iOS/Android: Added NativeDriver fallback so press_key works in Flutter VM Service mode on simulators/emulators (previously returned unsupported error). Enter key now triggers iOS search without needing CDP mode.
• enter_text without key: When called without key/ref, returns an actionable hint field pointing to inspect_interactive() instead of the confusing No TextField matching key 'null' found error.
• go_back with count: Accepts a count parameter to pop multiple routes in one call with 300 ms pauses between steps — replaces repeated go_back() chains.
• native_screenshot coordinate hint: Response now includes scale_factor and a coordinate_hint field that explains the physical→logical pixel conversion, eliminating manual coordinate guessing.

C++ desktop automation SDK

New SDK

• C++ Bridge SDK (sdks/cpp/): Cross-platform native C++ automation bridge. Embeds a zero-dependency WebSocket server (RFC 6455) + JSON-RPC 2.0 dispatcher in your C++ app so AI agents can control it via the flutter-skill protocol. Closes #22.
  • macOS: CGEvent for input synthesis, screencapture for screenshots, AXUIElement for accessibility inspection
  • Windows: SendInput + GDI+ (screenshots) + GetForegroundWindow
  • Linux: XTest extension + XGetImage/libpng + EWMH
  • No external dependencies — SHA-1, base64, and WebSocket framing are bundled
  • Full CMake build system (CMakeLists.txt) for all three platforms
• Tests: 30 unit tests (JSON-RPC, SHA-1/base64/WebSocket RFC vectors, bridge protocol with mock backend) + 27 real integration tests verified live on macOS (1630 KB PNG screenshot, tap, scroll, all key names, enter_text, inspect, window title)

Multi-flavor app detection, fresh-install UX, Docker/Snap build fixes, CI smoke tests

Bug Fixes

• Multi-flavor app detection (#24): scan_and_connect now accepts flavor and device_id parameters. When multiple flavors run simultaneously, flutter-skill picks the correct instance instead of connecting randomly.
• Fresh-install plugins warning (#23): Removed the Plugins directory not found warning on clean installs — silently skipped instead.
• Docker build: Dockerfile now uses ghcr.io/cirruslabs/flutter:stable so flutter pub get resolves Flutter SDK dependencies correctly.
• Snap build: Added git config --global --add safe.directory /opt/flutter to resolve detected dubious ownership error in snapcraft builds.

CI / Testing

• Smoke test job added to CI: verifies fresh flutter pub global activate install works end-to-end.
• Post-release smoke test in release workflow: installs from pub.dev and npm after publish and confirms server responds.

press_key for Flutter VM Service, pytest plugin, HarmonyOS SDK, CI smoke tests

Bug Fixes

• press_key in Flutter mode: press_key now works when connected via VM Service (not just CDP/bridge). Calls the existing ext.flutter.flutter_skill.pressKey extension that was already registered in the target app but never wired from the CLI side. Fixes #21.

New SDKs

• pytest-flutter-skill (sdks/python/): pytest plugin for AI-driven Flutter/web app automation. Provides a flutter_skill fixture that starts the MCP server and wraps all tools as Python methods with native pytest assertions (assert_visible, assert_text, assert_not_visible, find_element). Closes #14.
• HarmonyOS SDK (sdks/harmonyos/): ArkTS bridge SDK (FlutterSkillAbility.ets) for HarmonyOS apps. Implements screenshot, tap, enter_text, press_key, scroll, go_back, get_current_route, inspect, get_logs over WebSocket on port 18118. Closes #13.

CI / Testing

• Smoke test job added to CI: simulates a new user installing from local source via dart pub global activate, then verifies --version, MCP initialize, and tools/list work correctly.
• Post-release smoke test added to release workflow: installs from pub.dev and npm after each release (with retry for CDN propagation) and verifies the published package serves JSON-RPC correctly.

Shadow DOM deep pierce for tap/snapshot, serve port reuse fix

Changes

• tap text search now uses _dqAll('*') instead of a hardcoded tag list, so custom elements like Reddit's faceplate-button are found by text match
• Snapshot second pass collects button/[role=button]/[type=submit] elements nested inside shadow roots
• serve binds with shared: true (SO_REUSEADDR) to avoid TIME_WAIT "Address already in use" crashes on restart

CLI client commands, GitHub Pages docs, comprehensive platform guide

New Features

• CLI client commands for serve API: nav, snap, screenshot, tap, type, key, eval, title, text, hover, upload, tools, call, wait
• GitHub Pages documentation site: Static docs site at docs/site/ with auto-deploy workflow

Documentation

• Comprehensive IDE/platform integration guide with all supported AI platforms
• CLI client reference (docs/CLI_CLIENT.md) with scripting examples and CI/CD patterns
• Updated IDE setup guide with OpenClaw serve mode and Continue.dev sections

Bug Fixes

• Chrome WebSocket 403 Forbidden: Fixed Origin header handling
• Domain-based tab matching: Never hijack unrelated tabs
• PUT for /json/new: Chrome 145+ requires PUT instead of GET

iOS native automation + React Native support + bridge reliability

New Features

• 6 native P0 tools: native_long_press, native_gesture, native_press_key, native_key_combo, native_button, native_list_simulators
• Video recording: native_video_start / native_video_stop — H.264 MP4 via simctl recordVideo
• Frame capture: native_capture_frames — burst JPEG at configurable FPS
• Hardware buttons: apple_pay and side button support via HID injection
• fs-ios-bridge: Native ObjC HID injector (74KB) using SimulatorKit private APIs — ~1ms latency vs ~1s for osascript
• React Native iOS: Full bridge + native tool support verified (41/42 pass)

Bug Fixes

• Bridge mode null safety: drag coordinate support, edge_swipe defaults, assert_text nullable key
• execute_batch: accepts both actions and commands param names
• native_gesture/key_combo: flexible param types (List and String)
• get_widget_properties: improved error message for missing key
• get_text_value: nullable key support

Test Results

Stats

• 253 MCP tool definitions / 176 in tool registry
• 10 platforms supported
• fs-ios-bridge: tap, long-press, swipe, key, button, gesture, screenshot, key-combo, text, list

inspect_interactive, semantic refs, press_key, 75-test E2E suite

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Release 0.7.8

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Release 0.7.7

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

CI improvements + MCP Registry auto-publish

Changes

• Fixed 403 Forbidden error when connecting to Chrome 146 consent port (port opened via chrome://inspect/#remote-debugging)
• Chrome 146 rejects WebSocket connections that include an Origin header; Dart built-in WebSocket.connect() always adds one
• Added _connectWebSocketNoOrigin(): raw TCP socket WebSocket upgrade that omits the Origin header
• All CDP WebSocket connections now use no-Origin mode when consent port is detected
• Users can now connect to their real Chrome browser without any session-copy workaround

Multi-framework SDK support — 8 platforms, 181/183 E2E tests passing

New Features

• 8 platform SDKs: Flutter (iOS/Web), Electron, Android Native, KMP Desktop, Tauri, .NET, React Native
• Zero-config onboarding: flutter-skill init auto-detects platform and patches entry points
• flutter-skill demo: launches a built-in demo Flutter app for instant testing
• CLI actions: scroll, screenshot, get_text, find_element, wait_for_element, go_back, swipe
• Tauri eval-with-result: solved Tauri v2 fire-and-forget eval via secondary WebSocket result channel
• iOS SDK: SwiftUI view modifiers, FlutterSkillRegistry, WebSocket bridge with full protocol support

E2E Test Results

• Flutter iOS: 21/21 ✅ | Flutter Web: 20/20 ✅ | Electron: 24/24 ✅
• Android Native: 24/24 ✅ | KMP Desktop: 22/22 ✅
• .NET: 23/24 ✅ | Tauri: 23/24 ✅ | React Native: 24/24 ✅

Infrastructure

• Comprehensive E2E test suite (bridge_e2e_test.mjs) covering all 13 bridge protocol actions
• Test apps for each platform in test/e2e/
• Release script now syncs versions across all SDK packages

Release script fix and cleanup

Fixes

• Fixed release script adding duplicate CHANGELOG entries when version entry already exists
• Cleaned up CHANGELOG formatting

Fix type cast errors in get_errors and get_network_requests

Bug Fixes

• Fixed get_errors crashing with type 'String' is not a subtype of type 'int?' when passing limit/offset parameters
• Fixed get_network_requests with same type cast issue for limit parameter
• Used safe int.tryParse pattern instead of direct as int? cast for JSON-RPC params

Bug fixes, screenshot reliability, and new features

Bug Fixes

• Screenshot after navigation: Fixed stale screenshot showing old page after Navigator.push(). Now captures from the RenderView layer instead of first RepaintBoundary, correctly rendering the current visible page
• enter_text without key: Can now enter text into the currently focused TextField without providing a widget key. Tap a field first, then call enter_text(text: "...")
• assert_text on buttons: assert_text now reads child Text widgets from buttons, labels, and other non-TextField elements
• Session auto-switch: connect_app, launch_app, and scan_and_connect now always switch the active session to the newly connected app
• screenshot_region: Added save_to_file support (saves to temp file like regular screenshot)
• get_errors pagination: Added limit and offset parameters to prevent massive responses
• inspect page filter: Added current_page_only parameter to filter out elements from old Navigator routes

New Features

• Network monitoring: 3 new MCP tools (enable_network_monitoring, get_network_requests, clear_network_requests) for tracking HTTP traffic via VM Service profiling
• README rewrite: Clearer positioning as an AI-powered E2E testing tool with better examples and discoverability

Region Screenshot

• screenshot_region now reuses the same RenderView layer capture, fixing the same stale-page issue as regular screenshots

Enhanced developer experience: install scripts, CLI tips, and doctor command

Features

• flutter-skill doctor: New command to check installation and environment health (Flutter/Dart SDK, devices, native tools, IDE config, tool priority rules)
• --version / -v flag: Quick version check from CLI (flutter-skill --version)
• Interactive CLI tips: Running flutter-skill-mcp in terminal shows helpful usage guide with examples instead of hanging
• Auto-config IDE settings: Install script automatically writes MCP config to Claude Code (~/.claude/settings.json) and Cursor (~/.cursor/mcp.json)

Install Script Improvements

• One-click install auto-configures everything (IDE settings, tool priority rules, PATH)
• Safe JSON merging via python3 (preserves existing settings)
• POSIX-compatible output (printf instead of echo -e)
• Removed --force npm warning during updates
• Smart version verification with regex validation
• Added fish shell PATH support
• Windows PowerShell auto-config with ConvertFrom-Json/ConvertTo-Json

New Files

• lib/src/cli/doctor.dart - Environment health checker
• uninstall.sh - Clean uninstall for macOS/Linux
• uninstall.ps1 - Clean uninstall for Windows

Release Script

• scripts/release.sh now auto-syncs Homebrew formula version

Improve pub.dev score

Changes

• Add example/example.dart for pub.dev package scoring
• Widen vm_service dependency to >=14.0.0 <16.0.0 (supports v15)
• Remove unused persistent character fields (fixes 6 analyzer warnings)
• Fix "multiple pubspec.yaml" issue by adding demo_app/ to .pubignore
• Replace Color.withValues() with withOpacity() for Flutter 3.24 compatibility

Native platform interaction tools and VM Service reconnection fix

Features

• Native Platform Interaction: 4 new MCP tools (native_screenshot, native_tap, native_input_text, native_swipe) for interacting with native OS views that are invisible to Flutter's VM Service (photo pickers, permission dialogs, share sheets)
  • iOS Simulator: Uses macOS Accessibility API — no external dependencies
  • Android Emulator: Uses adb shell commands
  • Smart element targeting with scoring system for accurate tap detection
  • Auto-dismissal of iOS paste confirmation dialog

Bug Fixes

• VM Service Reconnection: Fix LateInitializationError crash when VM Service connection breaks. Client now auto-reconnects and retries failed operations transparently

Enhanced smart discovery with parallel port checking and priority-based selection

🚀 Features

• Parallel Port Checking: 6x faster port scanning by checking all ports simultaneously
  • Sequential (old): 6 ports × 500ms = 3000ms
  • Parallel (new): 500ms (returns as soon as first succeeds)
  • Uses Future.any() to race all port checks
• Priority-Based Smart Selection: Intelligent app ranking for zero manual selection
  • Ranks by: exact directory match → device match → recency (lowest PID)
  • Auto-selects correct app based on current working directory
  • Handles multiple apps in same location with device filtering
• Process-Based Discovery: Extract VM Service URI directly from running processes
  • No port scanning needed for most cases
  • Uses ps aux and lsof for instant discovery

⚡ Performance Improvements

• Port scanning: 3000ms → 500ms (6x faster)
• Process discovery: 200ms → 100ms (2x faster)
• Multi-app selection: Manual → Auto (instant)

🌍 Internationalization

• Translated all Chinese comments to English
• Updated documentation to follow project standards
• All user-facing strings now in English

📚 Documentation

• Added docs/SMART_DISCOVERY.md - Complete smart discovery documentation
• Added docs/SMART_SELECTION.md - Smart app selection guide
• Added docs/MULTI_APP_SELECTION.md - Multi-app handling documentation

🧹 Cleanup

• No cache files created (clean filesystem)
• Removed experimental caching system
• Deprecated sequential port checking method

Fix Twitter OAuth authentication

🐛 Bug Fixes

• 🔧 Fixed Twitter OAuth Authentication: Switch from Bearer Token to OAuth 1.0a
  • Twitter API v2 create tweets endpoint requires User Context authentication
  • Bearer Token (App-Only) is not supported for posting tweets
  • Now uses OAuth 1.0a with API Key, API Secret, Access Token, and Access Token Secret
  • Uses nearform-actions/github-action-notify-twitter action for OAuth signing

💡 What Changed

• ✅ Twitter posting now works correctly with User Context authentication
• ✅ Automatic release announcements will be posted to Twitter/X
• ✅ No more "Unsupported Authentication" errors

Add automated Twitter/X posting for release announcements

🤖 CI/CD Improvements

• 🐦 Automated Twitter/X Posting: Release workflow now auto-posts release announcements to Twitter/X
  • Posts tweet with version, installation commands, and release link
  • Uses Twitter API v2 with Bearer Token authentication
  • Includes relevant hashtags (#Flutter #AI #MCP #DartLang)
  • Auto-triggered on every release
  • Non-blocking (won't fail release if Twitter posting fails)

📚 Documentation

• 📖 Added docs/TWITTER_SETUP.md with complete Twitter API configuration guide
  • Step-by-step Bearer Token setup instructions
  • Troubleshooting guide for common errors
  • Security best practices
  • Tweet content customization instructions

💡 Benefits

• ✅ Automatic social media presence for releases
• ✅ Instant community notification
• ✅ Consistent release announcements
• ✅ Zero manual effort required

Add automated Winget PR submission to release workflow

🤖 CI/CD Improvements

• 🚀 Automated Winget Submission: Release workflow now auto-submits PRs to microsoft/winget-pkgs
  • Uses winget-releaser GitHub Action for automatic PR creation
  • Every release will be submitted to Microsoft's official Winget repository
  • Eliminates manual PR submission for Windows package manager

💡 Benefits

• ✅ Windows users can install via winget install AIDashboard.FlutterSkill
• ✅ Automatic version updates in Microsoft's official package repository
• ✅ No more manual PR submissions to winget-pkgs

Critical bug fixes for coordinate detection and JSON serialization

🐛 Bug Fixes (Critical)

• 🔧 Fixed JSON Serialization Error in find_by_type: Added safeRound() helper to handle NaN/Infinity values

  • Previously crashed with "Unsupported object: NaN" or "Unsupported object: Infinity"
  • Now safely converts all coordinate values to finite integers
  • Consistent with inspect() implementation

• 📍 Improved TextField Coordinate Detection: Added reliability detection for widget coordinates

  • New coordinatesReliable flag on all elements
  • Detects when TextFields report false (0,0) coordinates
  • Provides warning message: "Coordinates may be unreliable - use key or text for targeting"
  • Helps AI agents know when to fall back to key/text-based targeting

🔧 Improvements

• 📋 Enhanced MCP Tool Descriptions: Updated inspect and find_by_type documentation
  • Documents coordinatesReliable flag in output format
  • Warns about TextField coordinate issues
  • Guides AI agents to use keys when coordinates are unreliable

💡 Benefits

• ✅ find_by_type no longer crashes on off-screen or animated widgets
• ✅ AI agents can detect unreliable coordinates and adjust targeting strategy
• ✅ Better error messages guide users to use keys instead of coordinates
• ✅ More robust JSON serialization prevents crashes

📝 Migration Guide

No breaking changes. New coordinatesReliable field is optional to check:

// Check coordinate reliability before using coordinates
final elements = await inspect();
for (final element in elements) {
  if (element['coordinatesReliable'] == true) {
    // Safe to use bounds/center coordinates
    tap(x: element['center']['x'], y: element['center']['y']);
  } else {
    // Fall back to key/text targeting
    if (element['key'] != null) {
      tap(key: element['key']);
    }
  }
}

Major usability improvements for screenshots, errors, and logging

🎯 P0 Fixes (Critical)

• 📸 Screenshot Optimization: Now saves to file by default instead of returning base64

  • Returns file path, filename, size, format
  • Dramatically reduces response size
  • save_to_file parameter (default: true)
  • Backward compatible: set save_to_file=false for base64
  • Files saved to temp directory with timestamp

• 🔌 Improved Connection Error Messages: Detailed, actionable error messages

  • Clear status indicators with emojis (📍, 🔧, 💡, ⚠️)
  • 3 connection options with code examples
  • Troubleshooting checklist included
  • Shows VM Service URI in errors for context
  • Better guidance for first-time users

🔧 P1 Improvements

• 📊 Structured Log/Error Responses:
  • get_logs(): Returns logs with summary (total_count, message)
  • get_errors(): Returns errors with summary (has_errors, total_count, message)
  • clear_logs(): Returns structured success response
  • Easier to parse and display in UI

💡 Benefits

• ✅ Smaller response sizes (file paths vs base64 data)
• ✅ Better developer experience with clear error messages
• ✅ Faster problem resolution
• ✅ More structured, parseable responses
• ✅ Files can be opened directly in viewers/editors

📝 Migration Guide

Screenshot:

// New behavior (default)
screenshot()  // Returns: {"file_path": "/tmp/...", "size_bytes": 45678}

// Legacy behavior
screenshot(save_to_file: false)  // Returns: {"image": "base64..."}

Logs/Errors:

// New response format
get_errors()
// Returns: {
//   "errors": [...],
//   "summary": {
//     "total_count": 3,
//     "has_errors": true,
//     "message": "3 error(s) found ⚠️"
//   }
// }

Add visual test indicators for UI automation

✨ New Features

• 🎨 Visual Test Indicators: Real-time visual feedback for all test actions
  • Tap indicator: Expanding circle with fade-out animation
  • Swipe indicator: Arrow with dashed trail showing direction
  • Long press indicator: Filling progress circle
  • Text input indicator: Glowing border with blink effect
• 📢 Action Hints: Top banner displaying current operation ("Tapping 'Submit'", etc.)
• 🎛️ Configurable Styles: Three modes to choose from
  • minimal: Small, fast (200ms), no hints
  • standard: Medium, normal speed (500ms), 1s hints (default)
  • detailed: Large, slow (800ms), 2s hints + debug info
• 🔧 Easy Control: Enable/disable indicators on the fly
  • MCP tool: enable_test_indicators(enabled: true, style: "standard")
  • MCP tool: get_indicator_status()
  • VM Service extensions: enableIndicators, disableIndicators, getIndicatorStatus

🏗️ Architecture

• TestIndicatorOverlay: Manages overlay entry and indicator lifecycle
• TestIndicatorWidget: Renders all visual effects with smooth animations
• Indicator components: TapIndicator, SwipeIndicator, LongPressIndicator, TextInputIndicator, ActionHint
• Uses Flutter Overlay for cross-platform compatibility
• IgnorePointer prevents interaction interference
• Automatic cleanup after animations complete

📖 Benefits

• 🎥 Better Test Videos: All indicators visible in screen recordings
• 🐛 Easier Debugging: See exactly what's being clicked/swiped
• 📱 Works Everywhere: iOS, Android, Web, Desktop
• ⚡ Zero Impact: No performance cost when disabled
• 🔄 Auto-Integration: Automatically shows for all test actions

📝 Usage Example

// Enable indicators
await enable_test_indicators(enabled: true, style: "standard");

// All actions now show visual feedback automatically
await tap(text: "Submit");           // Shows tap ripple + "Tapping 'Submit'"
await swipe(direction: "left");       // Shows swipe arrow + "Swiping left"
await long_press(text: "Menu");       // Shows progress circle + "Long pressing 'Menu'"
await enter_text(key: "email", text: "test@example.com");  // Shows glow + "Entering text"

// Disable when done
await enable_test_indicators(enabled: false);

📚 Documentation

• Design document: docs/TEST_INDICATORS_DESIGN.md
• Includes architecture, configuration options, and future enhancements

Fix screenshot_element null handling and add text parameter

Bug Fixes

• 🐛 Fixed "type 'Null' is not a subtype of type 'String'" error in screenshot_element
• ✅ Added text parameter support (in addition to key) for finding elements by text content
• 🔍 Automatically looks up element key when text parameter is provided
• 🛡️ Added null check for takeElementScreenshot return value
• 📝 Returns descriptive error messages when element not found or screenshot fails

Improvements

• 🎯 screenshot_element now matches behavior of other action tools (tap, long_press, etc.)
• 🔄 Supports both screenshot_element(key: "button_1") and screenshot_element(text: "Submit")

Technical Details

• Queries getInteractiveElements() to find matching text when key not provided
• Returns {"error": "...", "message": "..."} instead of crashing on null

Fix Infinity/NaN crash when inspecting widgets

Bug Fixes

• 🐛 Fixed "Unsupported operation: Infinity or NaN toInt" crash in _findInteractiveElements
• ✅ Added safeRound() helper function to handle invalid numeric values
• 🛡️ Widget bounds calculation now safely handles Infinity and NaN values (returns 0)
• 🔧 Prevents MCP error -32603 when inspecting widgets with problematic layouts
• 📦 Supports edge cases: Positioned.fill, FractionalTranslation, and malformed widget trees

Technical Details

• Checks value.isFinite before calling .round() on position/size values
• Gracefully degrades to {x: 0, y: 0, width: 0, height: 0} for invalid bounds

Auto-update flutter_skill dependency in target projects

Improvements

• 🔄 setup now automatically updates existing flutter_skill dependency to latest version from pub.dev
• ✅ Enhanced flutter pub upgrade flutter_skill checks when dependency already exists
• 📊 Clear status feedback: "✅ updated", "✅ up to date", or "⚠️ failed"
• 🔧 Ensures target projects always use the latest compatible version
• ♻️ Maintains backward compatibility with first-time installations

Behavior Changes

• Previously: Skipped setup if dependency already existed (even if outdated)
• Now: Actively upgrades to latest version when dependency is found

Fix release script to auto-update server.dart version

Bug Fixes

• 🔧 Fixed release script to automatically update _currentVersion in lib/src/cli/server.dart
• 🔄 Ensures version consistency across all release artifacts (pubspec, npm, VSCode, JetBrains, server.dart)
• ✅ Prevents version mismatch errors in MCP server startup

Add MCP auto-fix and diagnostics

Features

• ✨ New diagnose_project MCP tool for comprehensive project diagnostics
• 🔧 Auto-fix capability in connect_app and scan_and_connect tools
• 📁 Optional project_path parameter for automatic configuration
• 🛠️ Diagnostic shell script (scripts/diagnose.sh) for manual troubleshooting

Improvements

• 📊 Enhanced error logging with complete diagnostic output
• 🔍 Automatic detection and repair of missing flutter_skill dependency
• ⚙️ Automatic detection and repair of missing FlutterSkillBinding initialization
• ✅ Backward compatible (all tools work without project_path parameter)

Documentation

• 📖 New AUTO_FIX_IMPROVEMENTS.md guide
• ✅ New test_auto_fix.md testing checklist
• 🔧 Updated TROUBLESHOOTING.md with auto-fix workflows
• 🌍 README.md translated to English