devicely 2.2.12 → 2.2.13

package/lib/.logging-backup/intelligentLocatorService.js.backup

@@ -0,0 +1,1541 @@
+/**
+ * 🎯 INTELLIGENT LOCATOR SERVICE - GENIUS SOLUTION
+ * ================================================
+ * 
+ * This service implements a revolutionary locator-based Commander-Follower system:
+ * 1. Caches all screen locators when screen loads
+ * 2. Uses tiny AI models for intelligent locator matching
+ * 3. Converts coordinates to precise locators instantly
+ * 4. 100% accurate cross-device element targeting
+ * 5. Zero-cost, open-source, local processing
+ */
+
+const Logger = require('./logger');
+const axios = require('axios');
+const fs = require('fs').promises;
+const path = require('path');
+const universalSessionManager = require('./universalSessionManager');
+
+class IntelligentLocatorService {
+  constructor(connectedDevices = null) {
+    this.logger = new Logger('IntelligentLocatorService');
+    
+    // Store reference to connected devices
+    this.connectedDevices = connectedDevices;
+    
+    // REVOLUTIONARY: Universal Session Management
+    this.universalSessionManager = universalSessionManager;
+    
+    // Locator Cache Management - BALANCED for reliability and speed
+    this.locatorCache = new Map(); // Map<deviceName, CachedLocators>
+    this.cacheTimestamps = new Map(); // Map<deviceName, timestamp>
+    this.cacheValidityMs = 25000; // BALANCED: 25 seconds cache validity (was 20s, originally 30s)
+    this.refreshingDevices = new Set(); // Track devices currently being refreshed
+    
+    // AI Model for Locator Matching
+    this.aiModel = null; // Will hold local tiny AI model
+    this.modelPath = path.join(__dirname, 'ai', 'locator_model');
+    
+    // Element Similarity Scoring
+    this.similarityThreshold = 0.40; // 40% similarity threshold - more flexible
+    
+    // Performance Metrics
+    this.performanceMetrics = {
+      cacheHits: 0,
+      cacheMisses: 0,
+      accurateMatches: 0,
+      fallbackToCoordinates: 0
+    };
+    
+    this.initializeAIModel();
+  }
+
+  /**
+   * 🔧 Decode HTML entities from text
+   */
+  decodeHtmlEntities(text) {
+    if (!text) return text;
+    
+    return text
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&nbsp;/g, ' ');
+  }
+
+  /**
+   * 🤖 Initialize Local Tiny AI Model for Locator Intelligence
+   * Uses TensorFlow.js with a lightweight model for element classification
+   */
+  async initializeAIModel() {
+    try {
+      // Check if we have TensorFlow.js available
+      let tf;
+      try {
+        tf = require('@tensorflow/tfjs-node');
+      } catch (error) {
+        this.logger.warn('🤖 TensorFlow.js not available, falling back to rule-based matching');
+        this.useRuleBasedMatching = true;
+        return;
+      }
+      
+      // Try to load existing model or create a simple one
+      const modelExists = await this.checkModelExists();
+      
+      if (modelExists) {
+        this.aiModel = await tf.loadLayersModel(`file://${this.modelPath}/model.json`);
+        this.logger.info('🤖 ✅ Loaded existing AI locator model');
+      } else {
+        // Create a simple neural network for element classification
+        this.aiModel = await this.createSimpleLocatorModel(tf);
+        this.logger.info('🤖 ✅ Created new AI locator model');
+      }
+      
+    } catch (error) {
+      this.logger.warn(`🤖 AI model initialization failed: ${error.message}, using rule-based matching`);
+      this.useRuleBasedMatching = true;
+    }
+  }
+
+  /**
+   * 🧠 Create a Simple Locator Classification Model
+   * Lightweight model for element type and text similarity classification
+   */
+  async createSimpleLocatorModel(tf) {
+    // Simple neural network for element feature matching
+    const model = tf.sequential({
+      layers: [
+        tf.layers.dense({ inputShape: [10], units: 16, activation: 'relu' }),
+        tf.layers.dropout({ rate: 0.2 }),
+        tf.layers.dense({ units: 8, activation: 'relu' }),
+        tf.layers.dense({ units: 3, activation: 'softmax' }) // 3 classes: button, text, input
+      ]
+    });
+    
+    model.compile({
+      optimizer: 'adam',
+      loss: 'categoricalCrossentropy',
+      metrics: ['accuracy']
+    });
+    
+    return model;
+  }
+
+  async checkModelExists() {
+    try {
+      await fs.access(path.join(this.modelPath, 'model.json'));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 🎯 MAIN GENIUS METHOD: Convert Click Coordinates to Intelligent Locator
+   */
+  async getIntelligentLocator(deviceName, x, y, forceRefresh = false) {
+    this.logger.info(`🎯 Finding intelligent locator for ${deviceName} at (${x}, ${y})`);
+    
+    try {
+      // Step 1: Ensure we have fresh locator cache - FORCE REFRESH AFTER EVERY ACTION
+      const shouldForceRefresh = forceRefresh || this.shouldForceRefreshCache(deviceName);
+      
+      if (shouldForceRefresh) {
+        this.logger.info(`🔄 FORCING cache refresh for ${deviceName} (forceRefresh=${forceRefresh})`);
+      }
+      
+      const cachedLocators = await this.getCachedLocators(deviceName, shouldForceRefresh);
+      
+      if (!cachedLocators || cachedLocators.length === 0) {
+        this.logger.warn(`❌ No cached locators for ${deviceName}, falling back to coordinates`);
+        this.performanceMetrics.fallbackToCoordinates++;
+        return { method: 'coordinates', x, y };
+      }
+      
+      this.logger.debug(`📦 Using ${cachedLocators.length} cached locators for matching`);
+      
+      // Step 2: Find best matching element using AI/rules
+      const bestMatch = await this.findBestMatchingElement(cachedLocators, x, y);
+      
+      if (bestMatch && bestMatch.confidence > this.similarityThreshold) {
+        this.logger.info(`✅ High-confidence locator match found (${(bestMatch.confidence * 100).toFixed(1)}%)`);
+        this.performanceMetrics.accurateMatches++;
+        
+        return {
+          method: 'locator',
+          locator: bestMatch.locator,
+          confidence: bestMatch.confidence,
+          element: bestMatch.element,
+          fallbackCoords: { x, y } // Always include fallback
+        };
+      }
+      
+      // Step 3: Fallback to coordinate-based if no good match
+      this.logger.warn(`⚠️ Low confidence match (${bestMatch ? (bestMatch.confidence * 100).toFixed(1) : 0}%), using coordinates`);
+      this.performanceMetrics.fallbackToCoordinates++;
+      
+      return { 
+        method: 'coordinates', 
+        x, 
+        y,
+        nearestElement: bestMatch ? bestMatch.element : null
+      };
+      
+    } catch (error) {
+      this.logger.error(`❌ Intelligent locator failed: ${error.message}`);
+      return { method: 'coordinates', x, y, error: error.message };
+    }
+  }
+
+  /**
+   * 🎯 Determine if cache should be forcefully refreshed - OPTIMIZED for speed
+   */
+  shouldForceRefreshCache(deviceName) {
+    const now = Date.now();
+    const lastCached = this.cacheTimestamps.get(deviceName);
+    
+    // PERFORMANCE: More aggressive caching for commander speed
+    // Force refresh only if:
+    // 1. Never cached
+    // 2. Cache is older than 15 seconds (increased from 10s for speed)
+    // 3. Cache was explicitly invalidated
+    
+    if (!lastCached) {
+      this.logger.debug(`🔄 Force refresh: ${deviceName} never cached`);
+      return true;
+    }
+    
+    const cacheAge = now - lastCached;
+    if (cacheAge > 15000) { // OPTIMIZED: Increased from 10s to 15s for better performance
+      this.logger.debug(`🔄 Force refresh: ${deviceName} cache is ${Math.round(cacheAge/1000)}s old`);
+      return true;
+    }
+    
+    // Check if we have actual cached data
+    const cachedData = this.locatorCache.get(deviceName);
+    if (!cachedData || cachedData.length === 0) {
+      this.logger.debug(`🔄 Force refresh: ${deviceName} has no cached data`);
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * 📦 Get or Refresh Cached Locators for Device (ENHANCED)
+   */
+  async getCachedLocators(deviceName, forceRefresh = false) {
+    const cacheKey = deviceName;
+    const now = Date.now();
+    const lastCached = this.cacheTimestamps.get(cacheKey);
+    
+    // Check if cache is valid and not forcing refresh
+    if (!forceRefresh && lastCached && this.locatorCache.has(cacheKey)) {
+      const cacheAge = now - lastCached;
+      if (cacheAge < this.cacheValidityMs) {
+        this.logger.debug(`📦 Using cached locators for ${deviceName} (age: ${Math.round(cacheAge/1000)}s)`);
+        this.performanceMetrics.cacheHits++;
+        return this.locatorCache.get(cacheKey);
+      }
+    }
+    
+    // 🎯 ENHANCED: If cache was recently invalidated, always force fresh fetch
+    const wasRecentlyInvalidated = !lastCached || (now - lastCached) > 60000; // If older than 1 minute, was likely invalidated
+    const effectiveForceRefresh = forceRefresh || wasRecentlyInvalidated;
+    
+    // 🎯 PREVENT DUPLICATE REFRESHES: If already refreshing this device, return cached data quickly
+    if (this.refreshingDevices.has(deviceName)) {
+      this.logger.debug(`⏳ Device ${deviceName} is already being refreshed, using existing cache`);
+      // Don't wait - just return existing cache if available
+      const existingCache = this.locatorCache.get(cacheKey);
+      if (existingCache && existingCache.length > 0) {
+        this.logger.debug(`📦 Using existing ${existingCache.length} locators for ${deviceName}`);
+        return existingCache;
+      }
+    }
+    
+    // Mark as refreshing
+    this.refreshingDevices.add(deviceName);
+    this.logger.debug(`🔄 Marked ${deviceName} as refreshing`);
+    
+    // Refresh cache
+    const ageText = lastCached ? `${Math.round((now - lastCached)/1000)}s` : 'never cached';
+    this.logger.info(`🔄 Refreshing locator cache for ${deviceName} (force: ${effectiveForceRefresh}, age: ${ageText})`);
+    this.performanceMetrics.cacheMisses++;
+    
+    try {
+      const freshLocators = await this.fetchAllLocators(deviceName);
+      
+      if (freshLocators && freshLocators.length > 0) {
+        this.locatorCache.set(cacheKey, freshLocators);
+        this.cacheTimestamps.set(cacheKey, now);
+        this.logger.info(`✅ Cached ${freshLocators.length} locators for ${deviceName}`);
+        return freshLocators;
+      } else {
+        this.logger.warn(`⚠️ No locators found for ${deviceName}`);
+        return [];
+      }
+      
+    } catch (error) {
+      this.logger.error(`❌ Failed to refresh locators for ${deviceName}: ${error.message}`);
+      // Return stale cache if available, but mark it as potentially stale
+      const staleCache = this.locatorCache.get(cacheKey) || [];
+      if (staleCache.length > 0) {
+        this.logger.warn(`⚠️ Using stale cache with ${staleCache.length} locators for ${deviceName}`);
+        return staleCache;
+      } else {
+        // If no cache available, return empty array but don't throw error
+        this.logger.warn(`⚠️ No fallback cache available for ${deviceName}, returning empty cache`);
+        return [];
+      }
+    } finally {
+      // Always remove from refreshing set
+      this.refreshingDevices.delete(deviceName);
+      this.logger.debug(`🔓 Removed ${deviceName} from refreshing set`);
+    }
+  }
+
+  /**
+   * 🔍 Fetch All Locators from Device (Enhanced Direct WDA Method)
+   */
+  async fetchAllLocators(deviceName) {
+    try {
+      // For iOS devices, use direct WDA page source (faster and more reliable)
+      const device = this.connectedDevices?.find(d => d.name === deviceName);
+      if (!device) {
+        throw new Error(`Device ${deviceName} not found in connected devices`);
+      }
+      
+      if (device.platform === 'ios') {
+        return await this.fetchIOSLocatorsDirect(deviceName, device);
+      }
+      
+      // For Android, use the existing API endpoint
+      const response = await axios.post('http://localhost:3001/api/locators', {
+        deviceName: deviceName
+      }, { timeout: 15000 });
+      
+      if (response.data.success && response.data.locators) {
+        const locators = response.data.locators;
+        
+        // Process and enhance locators with our intelligence
+        const enhancedLocators = locators.map(locator => ({
+          ...locator,
+          // Add computed properties for matching
+          centerX: locator.bounds ? (locator.bounds.x + locator.bounds.width / 2) : null,
+          centerY: locator.bounds ? (locator.bounds.y + locator.bounds.height / 2) : null,
+          area: locator.bounds ? (locator.bounds.width * locator.bounds.height) : 0,
+          // Element classification
+          isClickable: this.isElementClickable(locator),
+          elementType: this.classifyElementType(locator),
+          // Text features for matching
+          hasText: !!(locator.text || locator.accessibilityLabel || locator.contentDesc),
+          textLength: (locator.text || locator.accessibilityLabel || locator.contentDesc || '').length,
+          // Priority scoring
+          priority: this.calculateElementPriority(locator)
+        }));
+        
+        // Sort by priority (most likely to be interaction targets first)
+        enhancedLocators.sort((a, b) => b.priority - a.priority);
+        
+        return enhancedLocators;
+      }
+      
+      return [];
+      
+    } catch (error) {
+      this.logger.error(`Failed to fetch locators: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * 📱 Fetch iOS Locators Directly from WDA (NEW METHOD)
+   */
+  async fetchIOSLocatorsDirect(deviceName, device) {
+    const port = device.port || 8100;
+    let attempts = 0;
+    const maxAttempts = 3;
+    
+    while (attempts < maxAttempts) {
+      attempts++;
+      
+      try {
+        // REVOLUTIONARY: Use universal session manager for consistent sessions
+        const sessionId = await this.universalSessionManager.getSessionWithRetry(deviceName, port);
+        if (!sessionId) {
+          throw new Error(`No valid session for iOS device ${deviceName} on attempt ${attempts}`);
+        }
+        
+        this.logger.debug(`📱 Fetching iOS locators directly from WDA for ${deviceName} (session: ${sessionId.substring(0, 8)}..., attempt: ${attempts})`);
+        
+        // Try multiple WDA endpoints for getting page source
+        let response;
+        let pageSource;
+        
+        // Method 1: Standard source endpoint
+        try {
+          response = await axios.get(`http://localhost:${port}/session/${sessionId}/source`, {
+            timeout: 8000
+          });
+          pageSource = response.data?.value;
+        } catch (error) {
+          this.logger.warn(`📱 Standard source endpoint failed: ${error.message}`);
+        }
+        
+        // Method 2: If first method fails, try WDA-specific source endpoint
+        if (!pageSource) {
+          try {
+            response = await axios.get(`http://localhost:${port}/session/${sessionId}/wda/source`, {
+              timeout: 8000
+            });
+            pageSource = response.data?.value;
+          } catch (error) {
+            this.logger.warn(`📱 WDA source endpoint also failed: ${error.message}`);
+          }
+        }
+        
+        // Method 4: Try getting all elements and extracting from that
+        if (!pageSource) {
+          try {
+            response = await axios.get(`http://localhost:${port}/session/${sessionId}/elements`, {
+              timeout: 8000,
+              params: { using: 'xpath', value: '//*' }
+            });
+            
+            if (response.data?.value && Array.isArray(response.data.value)) {
+              // Convert elements array to simple XML-like structure for parsing
+              pageSource = this.convertElementsToPageSource(response.data.value, port, sessionId);
+            }
+          } catch (error) {
+            this.logger.warn(`📱 Elements endpoint also failed: ${error.message}`);
+          }
+        }
+        
+        // Method 5: Fallback to a basic hierarchical page source
+        if (!pageSource) {
+          try {
+            response = await axios.get(`http://localhost:${port}/session/${sessionId}/wda/element/0/tree`, {
+              timeout: 8000
+            });
+            pageSource = JSON.stringify(response.data);
+          } catch (error) {
+            this.logger.warn(`📱 Element tree with root also failed: ${error.message}`);
+          }
+        }
+        
+        if (!pageSource) {
+          if (attempts < maxAttempts) {
+            this.logger.warn(`📱 All source methods failed for ${deviceName}, attempt ${attempts}/${maxAttempts}. Retrying...`);
+            await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1s before retry
+            continue;
+          } else {
+            throw new Error('No page source returned from any WDA endpoint after all attempts');
+          }
+        }
+        
+        const parsedElements = this.parseIOSPageSource(pageSource);
+        
+        this.logger.info(`✅ Parsed ${parsedElements.length} iOS locators directly from WDA (attempt ${attempts})`);
+        
+        return parsedElements;
+        
+      } catch (error) {
+        if (attempts < maxAttempts) {
+          this.logger.warn(`📱 iOS locator fetch attempt ${attempts}/${maxAttempts} failed: ${error.message}. Retrying...`);
+          await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1s before retry
+        } else {
+          throw error;
+        }
+      }
+    }
+    
+    throw new Error(`Failed to fetch iOS locators after ${maxAttempts} attempts`);
+  }
+
+  /**
+   * 📝 Parse iOS Page Source to Extract Locators
+   */
+  parseIOSPageSource(pageSource) {
+    const elements = [];
+    
+    // More comprehensive regex to catch interactive elements
+    const xmlRegex = /<XCUIElementType(Button|TextField|SecureTextField|Switch|Link|StaticText|SearchField|Slider|Stepper|DatePicker|PickerWheel|PageIndicator|SegmentedControl|TabBar|NavigationBar|Cell|Image|TextView|WebView)[^>]*>/g;
+    
+    let match;
+    while ((match = xmlRegex.exec(pageSource)) !== null) {
+      const elementTag = match[0];
+      
+      // Extract attributes with better parsing
+      const attributes = this.parseElementAttributes(elementTag);
+      
+      if (attributes.x !== undefined && attributes.y !== undefined && 
+          attributes.width !== undefined && attributes.height !== undefined) {
+        
+        // More permissive filtering for iOS elements
+        if (attributes.width > 5 && attributes.height > 5 && attributes.enabled) {
+          
+          const elementType = `XCUIElementType${match[1]}`;
+          const isInteractive = this.isInteractiveElement(elementType, attributes);
+          
+          // Include both interactive elements and meaningful text elements
+          if (isInteractive || (attributes.label && attributes.label.length > 0)) {
+            elements.push({
+              type: elementType,
+              text: attributes.label || attributes.name,
+              accessibilityLabel: attributes.label,
+              name: attributes.name,
+              x: Math.round(attributes.x),
+              y: Math.round(attributes.y),
+              width: Math.round(attributes.width),
+              height: Math.round(attributes.height),
+              bounds: {
+                x: Math.round(attributes.x),
+                y: Math.round(attributes.y),
+                width: Math.round(attributes.width),
+                height: Math.round(attributes.height)
+              },
+              centerX: Math.round(attributes.x + attributes.width / 2),
+              centerY: Math.round(attributes.y + attributes.height / 2),
+              enabled: attributes.enabled,
+              visible: attributes.visible,
+              // Enhanced properties for intelligent matching
+              isClickable: this.isInteractiveElement(elementType, attributes),
+              elementType: this.classifyElementType({ type: elementType, text: attributes.label }),
+              hasText: !!(attributes.label || attributes.name),
+              textLength: (attributes.label || attributes.name || '').length,
+              priority: this.calculateElementPriority({
+                type: elementType,
+                text: attributes.label,
+                width: attributes.width,
+                height: attributes.height,
+                enabled: attributes.enabled
+              })
+            });
+          }
+        }
+      }
+    }
+    
+    // Sort by priority (most likely to be interaction targets first)
+    elements.sort((a, b) => b.priority - a.priority);
+    
+    this.logger.debug(`✅ Parsed and sorted ${elements.length} iOS elements by priority`);
+    return elements;
+  }
+
+  /**
+   * 🔧 Parse Element Attributes from XML Tag
+   */
+  parseElementAttributes(elementTag) {
+    const getAttribute = (name) => {
+      const match = elementTag.match(new RegExp(`${name}="([^"]*)"`, 'i'));
+      return match ? match[1] : null;
+    };
+    
+    return {
+      x: parseFloat(getAttribute('x')) || 0,
+      y: parseFloat(getAttribute('y')) || 0,
+      width: parseFloat(getAttribute('width')) || 0,
+      height: parseFloat(getAttribute('height')) || 0,
+      label: getAttribute('label'),
+      name: getAttribute('name'),
+      enabled: getAttribute('enabled') !== 'false',
+      visible: getAttribute('visible') !== 'false',
+      accessible: getAttribute('accessible') === 'true'
+    };
+  }
+
+  /**
+   * 🎯 Check if Element is Interactive
+   */
+  isInteractiveElement(elementType, attributes) {
+    const interactiveTypes = [
+      'Button', 'TextField', 'SecureTextField', 'Switch', 'Link', 
+      'SearchField', 'Slider', 'Stepper', 'DatePicker', 'PickerWheel', 
+      'SegmentedControl', 'Cell'
+    ];
+    
+    const typeMatch = interactiveTypes.some(type => elementType.includes(type));
+    const hasAction = attributes.label && (
+      attributes.label.toLowerCase().includes('button') ||
+      attributes.label.toLowerCase().includes('tap') ||
+      attributes.label.toLowerCase().includes('click')
+    );
+    
+    return typeMatch || hasAction;
+  }
+
+  /**
+   * 🎯 Find Best Matching Element using AI and Geometric Analysis
+   */
+  async findBestMatchingElement(cachedLocators, x, y) {
+    const candidates = [];
+    
+    // PERFORMANCE: Limit search to top priority elements first for speed
+    const maxCandidates = 20; // OPTIMIZED: Process only top 20 elements for speed
+    let candidatesFound = 0;
+    
+    // Step 1: Find elements near the click coordinates - OPTIMIZED
+    for (const locator of cachedLocators) {
+      if (!locator.bounds || !locator.centerX || !locator.centerY) continue;
+      
+      // PERFORMANCE: Break early if we have enough good candidates
+      if (candidatesFound >= maxCandidates) break;
+      
+      // Calculate distance from click point
+      const distance = Math.sqrt(
+        Math.pow(x - locator.centerX, 2) + 
+        Math.pow(y - locator.centerY, 2)
+      );
+      
+      // Check if click is within element bounds (with generous tolerance)
+      const tolerance = 25; // Increased tolerance for mobile UI
+      const isWithinBounds = (
+        x >= locator.bounds.x - tolerance &&
+        x <= locator.bounds.x + locator.bounds.width + tolerance &&
+        y >= locator.bounds.y - tolerance &&
+        y <= locator.bounds.y + locator.bounds.height + tolerance
+      );
+      
+      if (isWithinBounds || distance < 80) { // Within element or nearby (increased from 50)
+        candidates.push({
+          locator: locator,
+          distance: distance,
+          isWithinBounds: isWithinBounds,
+          geometricScore: this.calculateGeometricScore(locator, x, y),
+          elementScore: this.calculateElementScore(locator)
+        });
+        candidatesFound++;
+      }
+    }
+    
+    if (candidates.length === 0) {
+      this.logger.warn(`No candidate elements found near (${x}, ${y})`);
+      return null;
+    }
+    
+    // Step 2: Score candidates using AI or rules
+    let scoredCandidates;
+    
+    if (this.aiModel && !this.useRuleBasedMatching) {
+      scoredCandidates = await this.scoreWithAI(candidates, x, y);
+    } else {
+      scoredCandidates = this.scoreWithRules(candidates, x, y);
+    }
+    
+    // Step 3: Select best candidate
+    scoredCandidates.sort((a, b) => b.totalScore - a.totalScore);
+    const bestCandidate = scoredCandidates[0];
+    
+    this.logger.info(`🎯 Best candidate: ${bestCandidate.locator.elementType} with score ${bestCandidate.totalScore.toFixed(3)}`);
+    
+    return {
+      locator: this.buildOptimalLocator(bestCandidate.locator),
+      confidence: bestCandidate.totalScore,
+      element: bestCandidate.locator,
+      allCandidates: scoredCandidates.slice(0, 3) // Top 3 for debugging
+    };
+  }
+
+  /**
+   * 🤖 Score Candidates using AI Model
+   */
+  async scoreWithAI(candidates, x, y) {
+    // This would use the TensorFlow model to score candidates
+    // For now, we'll fall back to rule-based scoring
+    return this.scoreWithRules(candidates, x, y);
+  }
+
+  /**
+   * 📐 Score Candidates using Geometric and Heuristic Rules
+   */
+  scoreWithRules(candidates, x, y) {
+    return candidates.map(candidate => {
+      const { locator, distance, isWithinBounds, geometricScore, elementScore } = candidate;
+      
+      // Distance score (closer is better, more generous)
+      const maxDistance = 150; // Increased from 100
+      const distanceScore = Math.max(0.1, 1 - (distance / maxDistance)); // Min score of 0.1
+      
+      // Bounds score (inside is much better, but outside isn't terrible)
+      const boundsScore = isWithinBounds ? 1.0 : 0.5; // Improved from 0.3
+      
+      // Clickability score
+      const clickabilityScore = locator.isClickable ? 1.0 : 0.5;
+      
+      // Size appropriateness (not too small, not too large)
+      const idealArea = 1000; // ~30x30 px
+      const sizeScore = locator.area > 0 ? 
+        Math.exp(-Math.abs(Math.log(locator.area / idealArea))) : 0.5;
+      
+      // Element type preference (iOS-specific types, improved for links)
+      const elementTypeLower = (locator.elementType || '').toLowerCase();
+      let typeScore = 0.6; // Default score
+      
+      // HIGH PRIORITY: Link elements (especially for URL text)
+      if (elementTypeLower.includes('link')) typeScore = 1.0;
+      else if (elementTypeLower.includes('button') || elementTypeLower.includes('cell')) typeScore = 0.95;
+      else if (elementTypeLower.includes('switch') || elementTypeLower.includes('slider')) typeScore = 0.9;
+      else if (elementTypeLower.includes('textfield') || elementTypeLower.includes('input')) typeScore = 0.85;
+      else if (elementTypeLower.includes('image')) typeScore = 0.8;
+      else if (elementTypeLower.includes('text') || elementTypeLower.includes('label')) {
+        // Give higher score to text that looks like links
+        const textContent = (locator.text || '').toLowerCase();
+        if (textContent.includes('learn more') || textContent.includes('coverage') || 
+            textContent.includes('...') || textContent.includes('http')) {
+          typeScore = 0.9; // Boost for link-like text
+        } else {
+          typeScore = 0.75;
+        }
+      }
+      else if (locator.isClickable) typeScore = 0.8; // Any clickable element
+      
+      // Combine all scores with improved weights (favor proximity and bounds)
+      const totalScore = (
+        distanceScore * 0.35 +     // Increased: proximity is very important
+        boundsScore * 0.35 +       // Increased: being within bounds is crucial
+        clickabilityScore * 0.15 + // Reduced: many elements are clickable
+        typeScore * 0.10 +         // Added: element type matters
+        geometricScore * 0.03 +    // Reduced: less important than proximity
+        elementScore * 0.02        // Reduced: less important than proximity
+      );
+      
+      return {
+        ...candidate,
+        scores: {
+          distance: distanceScore,
+          bounds: boundsScore,
+          clickability: clickabilityScore,
+          geometric: geometricScore,
+          element: elementScore,
+          size: sizeScore,
+          type: typeScore
+        },
+        totalScore: Math.min(1.0, totalScore) // Cap at 1.0
+      };
+    });
+  }
+
+  /**
+   * 📐 Calculate Geometric Score
+   */
+  calculateGeometricScore(locator, x, y) {
+    if (!locator.bounds) return 0;
+    
+    // Prefer elements that are centered around the click point
+    const centerDistanceScore = 1 / (1 + Math.abs(locator.centerX - x) + Math.abs(locator.centerY - y));
+    
+    // Prefer reasonable aspect ratios
+    const aspectRatio = locator.bounds.width / locator.bounds.height;
+    const aspectScore = Math.exp(-Math.abs(Math.log(aspectRatio / 1.5))); // Prefer ~1.5:1 ratio
+    
+    return (centerDistanceScore + aspectScore) / 2;
+  }
+
+  /**
+   * 🏷️ Calculate Element Score based on properties (Enhanced for App Icons)
+   */
+  calculateElementScore(locator) {
+    let score = 0.5; // Base score
+    const className = (locator.className || locator.type || '').toLowerCase();
+    
+    // 🎯 HIGH PRIORITY: App icons with text labels
+    if ((className.includes('cell') || className.includes('icon') || className.includes('app')) && 
+        locator.text && locator.text.trim().length > 0) {
+      score += 0.4; // Very high boost for app icons with names
+      this.logger.debug(`📱 App icon detected: "${locator.text}" - boosted score`);
+    }
+    
+    // Has meaningful text
+    if (locator.hasText && locator.textLength > 2) score += 0.2;
+    
+    // Has accessibility info
+    if (locator.accessibilityId || locator.accessibilityLabel) score += 0.15;
+    
+    // Has resource ID (Android) or name (iOS)
+    if (locator.resourceId || locator.name) score += 0.15;
+    
+    // Clickable elements get priority
+    if (this.isElementClickable(locator)) score += 0.1;
+    
+    return Math.min(1.0, score);
+  }
+
+  /**
+   * 🏷️ Classify Element Type
+   */
+  classifyElementType(locator) {
+    const text = (locator.text || '').toLowerCase();
+    const className = (locator.className || locator.type || '').toLowerCase();
+    const resourceId = (locator.resourceId || '').toLowerCase();
+    
+    // Link detection (NEW - high priority for URL links)
+    if (className.includes('link') || 
+        className.includes('xcuielementtypelink') ||
+        text.includes('http') || 
+        text.includes('www.') ||
+        text.includes('learn more') ||
+        text.includes('coverage') ||
+        text.includes('more info') ||
+        (text.includes('...') && text.length > 10)) { // Truncated link text
+      return 'link';
+    }
+    
+    // Button detection (enhanced for back buttons, navigation, and app icons)
+    if (className.includes('button') || 
+        resourceId.includes('btn') || 
+        // Back button specific patterns
+        className.includes('back') ||
+        className.includes('navigation') ||
+        locator.accessibilityLabel?.toLowerCase().includes('back') ||
+        locator.name?.toLowerCase().includes('back') ||
+        // iOS specific button types
+        className.includes('xcuielementtypebutton') ||
+        // App icon patterns
+        className.includes('icon') ||
+        className.includes('app') ||
+        (className.includes('cell') && locator.text) || // App cells with text
+        // Generic button text patterns
+        text.match(/^(ok|cancel|submit|save|send|login|sign|tap|click|back|close|done)$/i)) {
+      return 'button';
+    }
+    
+    // Input field detection
+    if (className.includes('edit') || 
+        className.includes('input') || 
+        className.includes('field') ||
+        resourceId.includes('input') ||
+        resourceId.includes('edit')) {
+      return 'input';
+    }
+    
+    // App icon detection
+    if (className.includes('icon') || 
+        className.includes('app') ||
+        (className.includes('cell') && locator.text) || // App grid cells
+        (className.includes('collection') && locator.text)) { // Collection view cells
+      return 'app_icon';
+    }
+    
+    // Image detection
+    if (className.includes('image') || className.includes('img')) {
+      return 'image';
+    }
+    
+    // Text detection
+    if (className.includes('text') || locator.hasText) {
+      return 'text';
+    }
+    
+    return 'unknown';
+  }
+
+  /**
+   * ✅ Check if Element is Clickable (Enhanced for Navigation Elements)
+   */
+  isElementClickable(locator) {
+    const className = (locator.className || locator.type || '').toLowerCase();
+    const text = (locator.text || '').toLowerCase();
+    const accessibilityLabel = (locator.accessibilityLabel || locator.label || '').toLowerCase();
+    const name = (locator.name || '').toLowerCase();
+    
+    // Explicitly clickable elements
+    if (className.includes('button') || 
+        className.includes('clickable') ||
+        locator.clickable === true) {
+      return true;
+    }
+    
+    // Back buttons and navigation elements (often without text)
+    if (className.includes('back') ||
+        className.includes('navigation') ||
+        className.includes('xcuielementtypebutton') ||
+        accessibilityLabel.includes('back') ||
+        name.includes('back') ||
+        accessibilityLabel.includes('close') ||
+        accessibilityLabel.includes('done')) {
+      return true;
+    }
+    
+    // App icons and collection view cells (always clickable)
+    if (className.includes('icon') ||
+        className.includes('app') ||
+        className.includes('cell') || // Collection/table view cells
+        className.includes('collection') ||
+        (className.includes('xcuielementtypecell') && locator.text)) { // iOS cells with app names
+      return true;
+    }
+    
+    // Interactive elements
+    if (className.includes('edit') || 
+        className.includes('input') ||
+        className.includes('switch') ||
+        className.includes('checkbox')) {
+      return true;
+    }
+    
+    // Has click handlers (iOS) or meaningful accessibility info
+    if (locator.enabled !== false && (locator.text || locator.accessibilityLabel || locator.name)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * ⭐ Calculate Element Priority for Caching Order
+   */
+  calculateElementPriority(locator) {
+    let priority = 0;
+    
+    // Clickable elements get higher priority
+    if (this.isElementClickable(locator)) priority += 10;
+    
+    // Elements with text get priority
+    if (locator.hasText) priority += 5;
+    
+    // Elements with IDs get priority
+    if (locator.resourceId || locator.accessibilityId) priority += 3;
+    
+    // Reasonable size elements
+    if (locator.area > 100 && locator.area < 10000) priority += 2;
+    
+    return priority;
+  }
+
+  /**
+   * 🎯 Build Optimal Locator Strategy
+   */
+  buildOptimalLocator(element) {
+    const locators = [];
+    
+    // Priority 1: Accessibility ID (most reliable)
+    if (element.accessibilityId) {
+      locators.push({
+        strategy: 'accessibility_id',
+        selector: element.accessibilityId,
+        priority: 1
+      });
+    }
+    
+    // Priority 2: Resource ID (Android)
+    if (element.resourceId) {
+      locators.push({
+        strategy: 'id',
+        selector: element.resourceId,
+        priority: 1
+      });
+    }
+    
+    // Priority 3: XPath (if available and short)
+    if (element.xpath && element.xpath.length < 200) {
+      locators.push({
+        strategy: 'xpath',
+        selector: element.xpath,
+        priority: 2
+      });
+    }
+    
+    // Priority 4: Text-based (if unique)
+    if (element.text && element.text.length > 2) {
+      const decodedText = this.decodeHtmlEntities(element.text);
+      locators.push({
+        strategy: 'text',
+        selector: decodedText,
+        priority: 3
+      });
+    }
+    
+    // Priority 5: Class name + index
+    if (element.className) {
+      locators.push({
+        strategy: 'class_name',
+        selector: element.className,
+        index: element.index || 0,
+        priority: 4
+      });
+    }
+    
+    // Sort by priority and return the best strategy
+    locators.sort((a, b) => a.priority - b.priority);
+    
+    return locators.length > 0 ? locators[0] : null;
+  }
+
+  /**
+   * 🎯 MAIN EXECUTION METHOD: Apply Intelligent Locator on Follower
+   */
+  async executeIntelligentAction(followerDevice, intelligentLocator, action = 'tap') {
+    this.logger.info(`🎯 Executing ${action} on ${followerDevice.name} using intelligent locator`);
+    
+    // ENHANCED: Special handling for URL links that often fail with locators
+    const isUrlLink = intelligentLocator.locator && 
+                      intelligentLocator.locator.strategy === 'text' && 
+                      intelligentLocator.locator.selector &&
+                      (intelligentLocator.locator.selector.toLowerCase().includes('learn more') ||
+                       intelligentLocator.locator.selector.toLowerCase().includes('coverage') ||
+                       intelligentLocator.locator.selector.toLowerCase().includes('http') ||
+                       intelligentLocator.locator.selector.includes('...'));
+    
+    if (isUrlLink) {
+      this.logger.warn(`🔗 URL link detected: "${intelligentLocator.locator.selector}"`);
+      this.logger.warn('💡 URL links often fail with locators - using coordinate fallback for reliability');
+      
+      // For URL links, skip locator attempts and go straight to coordinates
+      if (intelligentLocator.fallbackCoords || intelligentLocator.method === 'coordinates') {
+        const coords = intelligentLocator.fallbackCoords || intelligentLocator;
+        const success = await this.executeCoordinateAction(followerDevice, coords, action);
+        
+        return { 
+          success: success, 
+          method: 'coordinates',
+          reason: 'URL link - forced coordinate fallback for reliability',
+          coordinates: coords
+        };
+      }
+    }
+    
+    try {
+      if (intelligentLocator.method === 'locator' && intelligentLocator.locator && !isUrlLink) {
+        // Try locator-based execution first (except for URL links)
+        const success = await this.executeLocatorAction(followerDevice, intelligentLocator.locator, action);
+        
+        if (success) {
+          this.logger.info(`✅ Locator-based ${action} succeeded on ${followerDevice.name}`);
+          return { success: true, method: 'locator' };
+        } else {
+          this.logger.warn(`⚠️ Locator failed, falling back to coordinates on ${followerDevice.name}`);
+        }
+      }
+      
+      // Fallback to coordinate-based execution
+      if (intelligentLocator.fallbackCoords || intelligentLocator.method === 'coordinates') {
+        const coords = intelligentLocator.fallbackCoords || intelligentLocator;
+        const success = await this.executeCoordinateAction(followerDevice, coords, action);
+        
+        return { 
+          success: success, 
+          method: 'coordinates',
+          coordinates: coords
+        };
+      }
+      
+      throw new Error('No valid execution method available');
+      
+    } catch (error) {
+      this.logger.error(`❌ Intelligent action failed: ${error.message}`);
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * 🎯 Execute Action using Locator
+   */
+  async executeLocatorAction(device, locator, action) {
+    const port = device.port || 8100;
+    const platform = device.platform || 'ios';
+    
+    try {
+      if (platform.toLowerCase() === 'ios') {
+        return await this.executeIOSLocatorAction(device, locator, action, port);
+      } else {
+        return await this.executeAndroidLocatorAction(device, locator, action, port);
+      }
+    } catch (error) {
+      this.logger.error(`Locator action failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 🔄 Get Fresh Session ID with Universal Session Manager (UPDATED)
+   * Uses the universal session manager for consistent session handling
+   */
+  async getFreshSessionId(deviceName, validateWithSourceEndpoint = false) {
+    try {
+      this.logger.debug(`[${deviceName}] Getting session via Universal Session Manager...`);
+      
+      // REVOLUTIONARY: Use Universal Session Manager
+      const sessionId = await this.universalSessionManager.getSessionWithRetry(deviceName);
+      
+      if (sessionId) {
+        this.logger.debug(`✅ Session retrieved via Universal Manager: ${sessionId.substring(0, 8)}... for ${deviceName}`);
+        return sessionId;
+      }
+      
+      throw new Error(`No session available via Universal Session Manager`);
+      
+    } catch (error) {
+      this.logger.error(`❌ Universal session lookup failed for ${deviceName}: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * 🩺 Check if device disconnect should trigger immediate cleanup (DISABLED)
+   */
+  async checkDeviceDisconnection(deviceName, error) {
+    // DISABLED: Was too aggressive and cleaning up healthy devices
+    // TODO: Fix health check logic before re-enabling
+    /*
+    const disconnectionKeywords = [
+      'ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 
+      'Connection refused', 'connect ECONNREFUSED',
+      'Session does not exist', 'invalid session id'
+    ];
+    
+    const isDisconnectionError = disconnectionKeywords.some(keyword => 
+      error.message?.includes(keyword)
+    );
+    
+    if (isDisconnectionError && global.performDeviceHealthCheck) {
+      this.logger.warn(`🩺 Device ${deviceName} shows disconnection signs, triggering immediate health check...`);
+      
+      setTimeout(async () => {
+        try {
+          await global.performDeviceHealthCheck();
+        } catch (healthError) {
+          this.logger.error(`Health check failed: ${healthError.message}`);
+        }
+      }, 1000);
+    }
+    */
+    
+    // Just log the error for now without triggering cleanup
+    this.logger.debug(`Device ${deviceName} session error (auto-cleanup disabled): ${error.message}`);
+  }
+
+  /**
+   * 📱 Execute iOS Locator Action (Updated with Fresh Session Management)
+   */
+  async executeIOSLocatorAction(device, locator, action, port) {
+    // REVOLUTIONARY: Use universal session manager for consistent sessions
+    let sessionId;
+    try {
+      sessionId = await this.universalSessionManager.getSessionWithRetry(device.name, port);
+      this.logger.debug(`✅ Using universal session: ${sessionId.substring(0, 8)}... for ${device.name}`);
+    } catch (sessionError) {
+      this.logger.warn(`⚠️ Universal session failed: ${sessionError.message}`);
+      throw new Error('No valid iOS session available');
+    }
+    
+    const baseUrl = `http://localhost:${port}`;
+    
+    try {
+      let elementId = null;
+      
+      // Find element using the best locator strategy
+      switch (locator.strategy) {
+        case 'accessibility_id':
+          const accessResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'accessibility id',
+            value: locator.selector
+          });
+          elementId = accessResponse.data.value.ELEMENT;
+          break;
+          
+        case 'xpath':
+          const xpathResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'xpath',
+            value: locator.selector
+          });
+          elementId = xpathResponse.data.value.ELEMENT;
+          break;
+          
+        case 'text':
+          // Try multiple iOS text matching strategies
+          const decodedText = this.decodeHtmlEntities(locator.selector);
+          try {
+            // Strategy 1: Accessibility label (most common for iOS buttons)
+            const labelResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+              using: 'accessibility id',
+              value: decodedText
+            });
+            elementId = labelResponse.data.value.ELEMENT;
+          } catch {
+            try {
+              // Strategy 2: XPath with text content for iOS (improved for links)
+              const xpathResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+                using: 'xpath',
+                value: `//*[@name="${decodedText}" or @label="${decodedText}" or @value="${decodedText}" or contains(@name, "${decodedText}")]`
+              });
+              elementId = xpathResponse.data.value.ELEMENT;
+            } catch {
+              try {
+                // Strategy 3: Predicate string (iOS-specific, improved)
+                const predicateResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+                  using: '-ios predicate string',
+                  value: `name CONTAINS "${decodedText}" OR label CONTAINS "${decodedText}" OR value CONTAINS "${decodedText}"`
+                });
+                elementId = predicateResponse.data.value.ELEMENT;
+              } catch {
+                try {
+                  // Strategy 4: Class chain for buttons (original)
+                  const classChainResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+                    using: '-ios class chain',
+                    value: `**/XCUIElementTypeButton[\`name == "${decodedText}" OR label == "${decodedText}"\`]`
+                  });
+                  elementId = classChainResponse.data.value.ELEMENT;
+                } catch {
+                  // Strategy 5: Class chain for links and text elements (NEW - specifically for URLs)
+                  const linkChainResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+                    using: '-ios class chain',
+                    value: `**/XCUIElementTypeLink[\`name CONTAINS "${decodedText}" OR label CONTAINS "${decodedText}"\`]`
+                  });
+                  if (linkChainResponse.data?.value?.ELEMENT) {
+                    elementId = linkChainResponse.data.value.ELEMENT;
+                  } else {
+                    // Strategy 6: Generic text elements (for text that might be clickable)
+                    const textChainResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+                      using: '-ios class chain',
+                      value: `**/XCUIElementTypeStaticText[\`name CONTAINS "${decodedText}" OR label CONTAINS "${decodedText}"\`]`
+                    });
+                    elementId = textChainResponse.data.value.ELEMENT;
+                  }
+                }
+              }
+            }
+          }
+          break;
+          
+        case 'class_name':
+          const classResponse = await axios.post(`${baseUrl}/session/${sessionId}/elements`, {
+            using: 'class name',
+            value: locator.selector
+          });
+          const elements = classResponse.data.value;
+          if (elements && elements.length > locator.index) {
+            elementId = elements[locator.index].ELEMENT;
+          }
+          break;
+      }
+      
+      if (!elementId) {
+        throw new Error('Element not found with locator strategy');
+      }
+      
+      // Execute action on found element
+      switch (action) {
+        case 'tap':
+        case 'click':
+          await axios.post(`${baseUrl}/session/${sessionId}/element/${elementId}/click`);
+          break;
+        case 'sendKeys':
+          await axios.post(`${baseUrl}/session/${sessionId}/element/${elementId}/value`, {
+            value: [locator.text || '']
+          });
+          break;
+      }
+      
+      // 🎯 Invalidate cache after successful iOS locator action (screen likely changed)
+      this.invalidateCache(device.name);
+      
+      return true;
+      
+    } catch (error) {
+      this.logger.warn(`iOS locator action failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 🤖 Execute Android Locator Action (Updated with Fresh Session Management)
+   */
+  async executeAndroidLocatorAction(device, locator, action, port) {
+    // Get fresh session ID
+    const sessionId = await this.getFreshSessionId(device.name);
+    if (!sessionId) {
+      throw new Error('No valid Android session available');
+    }
+    
+    const baseUrl = `http://localhost:${port}/wd/hub`;
+    
+    try {
+      let elementId = null;
+      
+      // Find element using the best locator strategy
+      switch (locator.strategy) {
+        case 'id':
+          const idResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'id',
+            value: locator.selector
+          });
+          elementId = idResponse.data.value.ELEMENT;
+          break;
+          
+        case 'accessibility_id':
+          const accessResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'accessibility id',
+            value: locator.selector
+          });
+          elementId = accessResponse.data.value.ELEMENT;
+          break;
+          
+        case 'xpath':
+          const xpathResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'xpath',
+            value: locator.selector
+          });
+          elementId = xpathResponse.data.value.ELEMENT;
+          break;
+          
+        case 'text':
+          const textResponse = await axios.post(`${baseUrl}/session/${sessionId}/element`, {
+            using: 'partial link text',
+            value: locator.selector
+          });
+          elementId = textResponse.data.value.ELEMENT;
+          break;
+          
+        case 'class_name':
+          const classResponse = await axios.post(`${baseUrl}/session/${sessionId}/elements`, {
+            using: 'class name',
+            value: locator.selector
+          });
+          const elements = classResponse.data.value;
+          if (elements && elements.length > locator.index) {
+            elementId = elements[locator.index].ELEMENT;
+          }
+          break;
+      }
+      
+      if (!elementId) {
+        throw new Error('Element not found with locator strategy');
+      }
+      
+      // Execute action on found element
+      switch (action) {
+        case 'tap':
+        case 'click':
+          await axios.post(`${baseUrl}/session/${sessionId}/element/${elementId}/click`);
+          break;
+        case 'sendKeys':
+          await axios.post(`${baseUrl}/session/${sessionId}/element/${elementId}/value`, {
+            value: [locator.text || '']
+          });
+          break;
+      }
+      
+      // 🎯 Invalidate cache after successful Android locator action (screen likely changed)
+      this.invalidateCache(device.name);
+      
+      return true;
+      
+    } catch (error) {
+      this.logger.warn(`Android locator action failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 📍 Execute Coordinate Action (Fallback) - Optimized Performance
+   */
+  async executeCoordinateAction(device, coordinates, action) {
+    const port = device.port || 8100;
+    const platform = device.platform || 'ios';
+    
+    // 🎯 FAST COORDINATE PROCESSING: Only scale if obviously wrong
+    let scaledX = coordinates.x;
+    let scaledY = coordinates.y;
+    
+    // Quick check: Only scale if coordinates are suspiciously small (< 50 pixels)
+    if (scaledX < 50 || scaledY < 100) {
+      // These are likely incorrectly scaled - apply 3x scaling
+      scaledX = scaledX * 3;
+      scaledY = scaledY * 3;
+      this.logger.info(`🔧 Quick-scaled tiny coordinates (${coordinates.x}, ${coordinates.y}) → (${scaledX}, ${scaledY})`);
+    }
+    
+    // Fast bounds check - only clamp if outside reasonable limits
+    if (scaledX > 500) scaledX = 450;
+    if (scaledY > 1000) scaledY = 900;
+    if (scaledX < 5) scaledX = 10;
+    if (scaledY < 20) scaledY = 30;
+    
+    try {
+      if (platform.toLowerCase() === 'ios') {
+        // REVOLUTIONARY: Use universal session manager for coordinate actions  
+        let sessionId;
+        try {
+          sessionId = await this.universalSessionManager.getSessionWithRetry(device.name, port);
+          this.logger.debug(`✅ Using universal session for coordinates: ${sessionId.substring(0, 8)}... for ${device.name}`);
+        } catch (sessionError) {
+          this.logger.warn(`⚠️ Universal session failed for coordinates: ${sessionError.message}`);
+          throw new Error('No valid iOS session available for coordinate action');
+        }
+        
+        // Use WDA tap endpoint for iOS
+        await axios.post(`http://localhost:${port}/session/${sessionId}/wda/tap`, {
+          x: scaledX,
+          y: scaledY
+        }, { timeout: 5000 });
+        
+      } else {
+        // REVOLUTIONARY: Use universal session manager for Android too
+        let sessionId;
+        try {
+          sessionId = await this.universalSessionManager.getSessionWithRetry(device.name, port);
+        } catch (sessionError) {
+          throw new Error('No valid Android session available for coordinate action');
+        }
+        
+        await axios.post(`http://localhost:${port}/wd/hub/session/${sessionId}/touch/click`, {
+          element: { x: scaledX, y: scaledY }
+        }, { timeout: 5000 });
+      }
+      
+      this.logger.info(`✅ Coordinate action successful on ${device.name} at (${scaledX}, ${scaledY})`);
+      
+      // 🎯 Invalidate cache after successful coordinate action (screen likely changed)
+      this.invalidateCache(device.name);
+      
+      return true;
+      
+    } catch (error) {
+      // If 404 error, try session recovery once
+      if (error.response?.status === 404) {
+        this.logger.warn(`⚠️ Session validation failed for ${device.name}: ${error.message}`);
+        
+        try {
+          // Try to get a fresh session directly from WDA status
+          const statusRes = await axios.get(`http://localhost:${port}/status`, { timeout: 3000 });
+          const freshSessionId = statusRes.data?.sessionId;
+          
+          if (freshSessionId) {
+            this.logger.info(`🔄 Found different session after validation failure: ${freshSessionId.substring(0, 8)}...`);
+            
+            // Update universal session manager port mapping
+            this.universalSessionManager.setDevicePort(device.name, port);
+            
+            // Retry the coordinate action with fresh session
+            if (platform.toLowerCase() === 'ios') {
+              await axios.post(`http://localhost:${port}/session/${freshSessionId}/wda/tap`, {
+                x: coordinates.x,
+                y: coordinates.y
+              }, { timeout: 5000 });
+            } else {
+              await axios.post(`http://localhost:${port}/wd/hub/session/${freshSessionId}/touch/click`, {
+                element: { x: coordinates.x, y: coordinates.y }
+              }, { timeout: 5000 });
+            }
+            
+            this.logger.info(`✅ Coordinate action successful on ${device.name} at (${coordinates.x}, ${coordinates.y}) after session recovery`);
+            
+            // 🎯 Invalidate cache after successful coordinate recovery action (screen likely changed)
+            this.invalidateCache(device.name);
+            
+            return true;
+          }
+        } catch (recoveryError) {
+          this.logger.error(`Failed to recover session for ${device.name}: ${recoveryError.message}`);
+        }
+      }
+      
+      this.logger.error(`Coordinate action failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * 📊 Get Performance Metrics
+   */
+  getPerformanceMetrics() {
+    const total = this.performanceMetrics.cacheHits + this.performanceMetrics.cacheMisses;
+    const cacheHitRate = total > 0 ? (this.performanceMetrics.cacheHits / total * 100).toFixed(1) : 0;
+    
+    return {
+      ...this.performanceMetrics,
+      cacheHitRate: `${cacheHitRate}%`,
+      totalRequests: total,
+      accuracyRate: `${((this.performanceMetrics.accurateMatches / (this.performanceMetrics.accurateMatches + this.performanceMetrics.fallbackToCoordinates)) * 100).toFixed(1)}%`
+    };
+  }
+
+  /**
+   * 🔄 Convert elements array to parseable page source format
+   */
+  convertElementsToPageSource(elements, port, sessionId) {
+    // This is a fallback method to create a basic parseable structure
+    // when proper page source endpoints fail
+    let xmlContent = '<?xml version="1.0" encoding="UTF-8"?>\n<hierarchy>\n';
+    
+    elements.forEach((element, index) => {
+      try {
+        // Get element details if possible
+        const elementId = element.ELEMENT;
+        // For now, just create a basic structure - this would need enhancement
+        // to fetch actual element properties via separate API calls
+        xmlContent += `  <XCUIElementTypeButton name="" label="" x="0" y="0" width="100" height="50" />\n`;
+      } catch (error) {
+        // Skip problematic elements
+      }
+    });
+    
+    xmlContent += '</hierarchy>';
+    return xmlContent;
+  }
+
+  /**
+   * 🧹 Clear Cache (for testing or troubleshooting)
+   */
+  clearCache() {
+    this.locatorCache.clear();
+    this.cacheTimestamps.clear();
+    this.logger.info('🧹 Locator cache cleared');
+  }
+
+  /**
+   * 🔍 Check if device has cached locators
+   */
+  hasCachedLocators(deviceName) {
+    return this.locatorCache.has(deviceName) && this.locatorCache.get(deviceName).length > 0;
+  }
+
+  /**
+   * 🎯 Invalidate Cache for Specific Device (after screen changes)
+   */
+  invalidateCache(deviceName) {
+    const hadCache = this.locatorCache.has(deviceName);
+    const cacheSize = hadCache ? this.locatorCache.get(deviceName).length : 0;
+    
+    this.locatorCache.delete(deviceName);
+    this.cacheTimestamps.delete(deviceName);
+    
+    if (hadCache) {
+      this.logger.info(`🧹 Locator cache invalidated for ${deviceName} (had ${cacheSize} locators)`);
+    } else {
+      this.logger.debug(`🧹 Locator cache invalidated for ${deviceName} (was empty)`);
+    }
+    
+    // Also remove from refreshing set to allow immediate refresh
+    this.refreshingDevices.delete(deviceName);
+  }
+
+  /**
+   * 🕐 Get Cache Age in milliseconds
+   * Returns null if no cache exists, or age in ms since last refresh
+   */
+  getCacheAge(deviceName) {
+    const timestamp = this.cacheTimestamps.get(deviceName);
+    if (!timestamp) {
+      return null; // No cache exists
+    }
+    
+    return Date.now() - timestamp;
+  }
+
+  /**
+   * 🎯 Invalidate All Device Caches (after major screen changes)
+   */
+  invalidateAllCaches() {
+    const deviceCount = this.locatorCache.size;
+    this.locatorCache.clear();
+    this.cacheTimestamps.clear();
+    this.logger.info(`🧹 All locator caches invalidated (${deviceCount} devices)`);
+  }
+}
+
+module.exports = IntelligentLocatorService;