camel-ai 0.2.71a7__py3-none-any.whl → 0.2.71a9__py3-none-any.whl

camel/toolkits/hybrid_browser_toolkit/unified_analyzer.js

@@ -2,9 +2,302 @@
     // Unified analyzer that combines visual and structural analysis
     // Preserves complete snapshot.js logic while adding visual coordinate information
 
-    let refCounter = 1;
+    // Memory management constants and configuration
+    const MAX_REFS = 2000; // Maximum number of refs to keep in memory
+    const MAX_UNUSED_AGE_MS = 90000; // Remove refs unused for more than xx seconds
+    const CLEANUP_THRESHOLD = 0.8; // Start aggressive cleanup when 80% of max refs reached
+
+    // Persistent ref management across page analysis calls with memory leak prevention
+    let refCounter = window.__camelRefCounter || 1;
+    let elementRefMap = window.__camelElementRefMap || new WeakMap();
+    let refElementMap = window.__camelRefElementMap || new Map();
+    let elementSignatureMap = window.__camelElementSignatureMap || new Map();
+    
+    // LRU tracking for ref access times
+    let refAccessTimes = window.__camelRefAccessTimes || new Map();
+    let lastNavigationUrl = window.__camelLastNavigationUrl || window.location.href;
+
+    // Initialize navigation event listeners for automatic cleanup
+    if (!window.__camelNavigationListenersInitialized) {
+        window.__camelNavigationListenersInitialized = true;
+        
+        // Listen for page navigation events
+        window.addEventListener('beforeunload', clearAllRefs);
+        window.addEventListener('pagehide', clearAllRefs);
+        
+        // Listen for pushState/replaceState navigation (SPA navigation)
+        const originalPushState = history.pushState;
+        const originalReplaceState = history.replaceState;
+        
+        history.pushState = function(...args) {
+            clearAllRefs();
+            return originalPushState.apply(this, args);
+        };
+        
+        history.replaceState = function(...args) {
+            clearAllRefs();
+            return originalReplaceState.apply(this, args);
+        };
+        
+        // Listen for popstate (back/forward navigation)
+        window.addEventListener('popstate', clearAllRefs);
+        
+        // Check for URL changes periodically (fallback for other navigation types)
+        setInterval(() => {
+            if (window.location.href !== lastNavigationUrl) {
+                clearAllRefs();
+                lastNavigationUrl = window.location.href;
+                window.__camelLastNavigationUrl = lastNavigationUrl;
+            }
+        }, 1000);
+    }
+
     function generateRef() {
-        return `e${refCounter++}`;
+        const ref = `e${refCounter++}`;
+        // Persist counter globally
+        window.__camelRefCounter = refCounter;
+        return ref;
+    }
+
+    // Clear all refs and reset memory state
+    function clearAllRefs() {
+        try {
+            // Clear all DOM aria-ref attributes
+            document.querySelectorAll('[aria-ref]').forEach(element => {
+                element.removeAttribute('aria-ref');
+            });
+            
+            // Clear all maps and reset counters
+            elementRefMap.clear();
+            refElementMap.clear();
+            elementSignatureMap.clear();
+            refAccessTimes.clear();
+            
+            // Reset global state
+            window.__camelElementRefMap = elementRefMap;
+            window.__camelRefElementMap = refElementMap;
+            window.__camelElementSignatureMap = elementSignatureMap;
+            window.__camelRefAccessTimes = refAccessTimes;
+            
+            // Clear cached analysis results
+            delete window.__camelLastAnalysisResult;
+            delete window.__camelLastAnalysisTime;
+            
+            console.log('CAMEL: Cleared all refs due to navigation');
+        } catch (error) {
+            console.warn('CAMEL: Error clearing refs:', error);
+        }
+    }
+
+    // LRU eviction: Remove least recently used refs when limit exceeded
+    function evictLRURefs() {
+        const refsToEvict = refAccessTimes.size - MAX_REFS + Math.floor(MAX_REFS * 0.1); // Remove 10% extra for breathing room
+        if (refsToEvict <= 0) return 0;
+
+        // Sort refs by access time (oldest first)
+        const sortedRefs = Array.from(refAccessTimes.entries())
+            .sort((a, b) => a[1] - b[1])
+            .slice(0, refsToEvict);
+
+        let evictedCount = 0;
+        for (const [ref, _] of sortedRefs) {
+            const element = refElementMap.get(ref);
+            if (element) {
+                // Remove aria-ref attribute from DOM
+                try {
+                    element.removeAttribute('aria-ref');
+                } catch (e) {
+                    // Element might be detached from DOM
+                }
+                elementRefMap.delete(element);
+                
+                // Remove from signature map
+                const signature = generateElementSignature(element);
+                if (signature && elementSignatureMap.get(signature) === ref) {
+                    elementSignatureMap.delete(signature);
+                }
+            }
+            
+            refElementMap.delete(ref);
+            refAccessTimes.delete(ref);
+            evictedCount++;
+        }
+
+        // Persist updated maps
+        window.__camelElementRefMap = elementRefMap;
+        window.__camelRefElementMap = refElementMap;
+        window.__camelElementSignatureMap = elementSignatureMap;
+        window.__camelRefAccessTimes = refAccessTimes;
+
+        return evictedCount;
+    }
+
+    // Update ref access time for LRU tracking
+    function updateRefAccessTime(ref) {
+        refAccessTimes.set(ref, Date.now());
+        window.__camelRefAccessTimes = refAccessTimes;
+    }
+
+    // Generate a unique signature for an element based on its characteristics
+    function generateElementSignature(element) {
+        if (!element || !element.tagName) return null;
+
+        const tagName = element.tagName.toLowerCase();
+        const textContent = (element.textContent || '').trim().substring(0, 50);
+        const className = element.className || '';
+        const id = element.id || '';
+        const href = element.href || '';
+        const src = element.src || '';
+        const value = element.value || '';
+        const type = element.type || '';
+        const placeholder = element.placeholder || '';
+
+        // Include position in DOM tree for uniqueness
+        let pathElements = [];
+        let current = element;
+        let depth = 0;
+        while (current && current.parentElement && depth < 5) {
+            const siblings = Array.from(current.parentElement.children);
+            const index = siblings.indexOf(current);
+            pathElements.unshift(`${current.tagName.toLowerCase()}[${index}]`);
+            current = current.parentElement;
+            depth++;
+        }
+        const domPath = pathElements.join('>');
+
+        return `${tagName}|${textContent}|${className}|${id}|${href}|${src}|${value}|${type}|${placeholder}|${domPath}`;
+    }
+
+    // Get or assign a persistent ref for an element
+    function getOrAssignRef(element) {
+        // Check if element already has a ref assigned
+        if (elementRefMap.has(element)) {
+            const existingRef = elementRefMap.get(element);
+            // Verify the ref is still valid
+            if (refElementMap.get(existingRef) === element) {
+                updateRefAccessTime(existingRef);
+                return existingRef;
+            }
+        }
+
+        // Check if element has aria-ref attribute (from previous analysis)
+        const existingAriaRef = element.getAttribute('aria-ref');
+        if (existingAriaRef && refElementMap.get(existingAriaRef) === element) {
+            // Re-establish mappings
+            elementRefMap.set(element, existingAriaRef);
+            updateRefAccessTime(existingAriaRef);
+            return existingAriaRef;
+        }
+
+        // Try to find element by signature (in case DOM was modified)
+        const signature = generateElementSignature(element);
+        if (signature && elementSignatureMap.has(signature)) {
+            const existingRef = elementSignatureMap.get(signature);
+            // Verify the old element is no longer in DOM or has changed
+            const oldElement = refElementMap.get(existingRef);
+            if (!oldElement || !document.contains(oldElement) || generateElementSignature(oldElement) !== signature) {
+                // Reassign the ref to the new element
+                elementRefMap.set(element, existingRef);
+                refElementMap.set(existingRef, element);
+                elementSignatureMap.set(signature, existingRef);
+                element.setAttribute('aria-ref', existingRef);
+                updateRefAccessTime(existingRef);
+                return existingRef;
+            }
+        }
+
+        // Check if we need to evict refs before creating new ones
+        if (refElementMap.size >= MAX_REFS) {
+            evictLRURefs();
+        }
+
+        // Generate new ref for new element
+        const newRef = generateRef();
+        elementRefMap.set(element, newRef);
+        refElementMap.set(newRef, element);
+        if (signature) {
+            elementSignatureMap.set(signature, newRef);
+        }
+        element.setAttribute('aria-ref', newRef);
+        updateRefAccessTime(newRef);
+        return newRef;
+    }
+
+    // Enhanced cleanup function with aggressive stale ref removal
+    function cleanupStaleRefs() {
+        const staleRefs = [];
+        const currentTime = Date.now();
+        const isAggressiveCleanup = refElementMap.size > (MAX_REFS * CLEANUP_THRESHOLD);
+
+        // Check all mapped elements to see if they're still in DOM or too old
+        for (const [ref, element] of refElementMap.entries()) {
+            let shouldRemove = false;
+
+            // Standard checks: element not in DOM
+            if (!element || !document.contains(element)) {
+                shouldRemove = true;
+            }
+            // Aggressive cleanup: remove refs unused for too long
+            else if (isAggressiveCleanup) {
+                const lastAccess = refAccessTimes.get(ref) || 0;
+                const age = currentTime - lastAccess;
+                if (age > MAX_UNUSED_AGE_MS) {
+                    shouldRemove = true;
+                }
+            }
+            // Additional checks for aggressive cleanup
+            else if (isAggressiveCleanup) {
+                // Remove refs for elements that are hidden or have no meaningful content
+                try {
+                    const style = window.getComputedStyle(element);
+                    const hasNoVisibleContent = !element.textContent?.trim() && 
+                                               !element.value?.trim() && 
+                                               !element.src && 
+                                               !element.href;
+                    
+                    if ((style.display === 'none' || style.visibility === 'hidden') && hasNoVisibleContent) {
+                        shouldRemove = true;
+                    }
+                } catch (e) {
+                    // If we can't get computed style, element might be detached
+                    shouldRemove = true;
+                }
+            }
+
+            if (shouldRemove) {
+                staleRefs.push(ref);
+            }
+        }
+
+        // Remove stale mappings
+        for (const ref of staleRefs) {
+            const element = refElementMap.get(ref);
+            if (element) {
+                // Remove aria-ref attribute from DOM
+                try {
+                    element.removeAttribute('aria-ref');
+                } catch (e) {
+                    // Element might be detached from DOM
+                }
+                elementRefMap.delete(element);
+                
+                // Remove from signature map
+                const signature = generateElementSignature(element);
+                if (signature && elementSignatureMap.get(signature) === ref) {
+                    elementSignatureMap.delete(signature);
+                }
+            }
+            refElementMap.delete(ref);
+            refAccessTimes.delete(ref);
+        }
+
+        // Persist maps globally
+        window.__camelElementRefMap = elementRefMap;
+        window.__camelRefElementMap = refElementMap;
+        window.__camelElementSignatureMap = elementSignatureMap;
+        window.__camelRefAccessTimes = refAccessTimes;
+
+        return staleRefs.length;
     }
 
     // === Complete snapshot.js logic preservation ===
@@ -15,7 +308,7 @@
         if (node.nodeType !== Node.ELEMENT_NODE) return true;
 
         try {
-            const style = window.getComputedStyle(node);
+        const style = window.getComputedStyle(node);
             if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0')
                 return false;
             // An element with `display: contents` is not rendered itself, but its children are.
@@ -29,6 +322,55 @@
         }
     }
 
+    // Optimized occlusion detection with fewer test points
+    function isOccluded(element) {
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+        try {
+            const rect = element.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0) return true;
+
+            // Simplified: Use fewer test points for better performance
+            const testPoints = [
+                // Center point (most important)
+                { x: rect.left + rect.width * 0.5, y: rect.top + rect.height * 0.5, weight: 4 },
+                // Only test 4 strategic points instead of 9
+                { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.25, weight: 1 },
+                { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.25, weight: 1 },
+                { x: rect.left + rect.width * 0.25, y: rect.top + rect.height * 0.75, weight: 1 },
+                { x: rect.left + rect.width * 0.75, y: rect.top + rect.height * 0.75, weight: 1 }
+            ];
+
+            let totalWeight = 0;
+            let visibleWeight = 0;
+
+            for (const point of testPoints) {
+                // Skip points outside viewport
+                if (point.x < 0 || point.y < 0 ||
+                    point.x >= window.innerWidth || point.y >= window.innerHeight) {
+                    continue;
+                }
+
+                const hitElement = document.elementFromPoint(point.x, point.y);
+                totalWeight += point.weight;
+
+                // Simplified visibility check
+                if (hitElement && (hitElement === element || element.contains(hitElement) || hitElement.contains(element))) {
+                    visibleWeight += point.weight;
+                }
+            }
+
+            // If no valid test points, assume not occluded
+            if (totalWeight === 0) return false;
+
+            // Element is occluded if less than 40% of weighted points are visible
+            return (visibleWeight / totalWeight) < 0.4;
+
+        } catch (e) {
+            return false;
+        }
+    }
+
     function getRole(node) {
         // Check if node is null or doesn't have required properties
         if (!node || !node.tagName || !node.getAttribute) {
@@ -39,6 +381,8 @@
         if (role) return role;
 
         const tagName = node.tagName.toLowerCase();
+
+        // Extended role mapping to better match Playwright
         if (tagName === 'a') return 'link';
         if (tagName === 'button') return 'button';
         if (tagName === 'input') {
@@ -48,9 +392,83 @@
         }
         if (['select', 'textarea'].includes(tagName)) return tagName;
         if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tagName)) return 'heading';
+
+        // Additional roles for better Playwright compatibility
+        if (tagName === 'img') return 'img';
+        if (tagName === 'main') return 'main';
+        if (tagName === 'nav') return 'navigation';
+        if (tagName === 'ul' || tagName === 'ol') return 'list';
+        if (tagName === 'li') return 'listitem';
+        if (tagName === 'em') return 'emphasis';
+        if (tagName === 'form' && node.getAttribute('role') === 'search') return 'search';
+        if (tagName === 'section' || tagName === 'article') return 'region';
+        if (tagName === 'aside') return 'complementary';
+        if (tagName === 'header') return 'banner';
+        if (tagName === 'footer') return 'contentinfo';
+        if (tagName === 'fieldset') return 'group';
+
         return 'generic';
     }
 
+    // Playwright-inspired function to check if element receives pointer events
+    function receivesPointerEvents(element) {
+        if (!element || !element.nodeType || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+        try {
+            let e = element;
+            while (e) {
+                const style = window.getComputedStyle(e);
+                if (!style) break;
+
+                const pointerEvents = style.pointerEvents;
+                if (pointerEvents === 'none') return false;
+                if (pointerEvents && pointerEvents !== 'auto') return true;
+
+                e = e.parentElement;
+            }
+            return true;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    // Playwright-inspired function to check if element has pointer cursor
+    function hasPointerCursor(element) {
+        if (!element || !element.nodeType || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+        try {
+            const style = window.getComputedStyle(element);
+            return style.cursor === 'pointer';
+        } catch (error) {
+            return false;
+        }
+    }
+
+    // Playwright-inspired function to get aria level
+    function getAriaLevel(element) {
+        if (!element || !element.tagName) return 0;
+
+        // Native HTML heading levels (H1=1, H2=2, etc.)
+        const tagName = element.tagName.toUpperCase();
+        const nativeLevel = { 'H1': 1, 'H2': 2, 'H3': 3, 'H4': 4, 'H5': 5, 'H6': 6 }[tagName];
+        if (nativeLevel) return nativeLevel;
+
+        // Check aria-level attribute for roles that support it
+        const role = getRole(element);
+        const kAriaLevelRoles = ['heading', 'listitem', 'row', 'treeitem'];
+        if (kAriaLevelRoles.includes(role)) {
+            const ariaLevel = element.getAttribute('aria-level');
+            if (ariaLevel !== null) {
+                const value = Number(ariaLevel);
+                if (Number.isInteger(value) && value >= 1) {
+                    return value;
+                }
+            }
+        }
+
+        return 0;
+    }
+
     function getAccessibleName(node) {
         // Check if node is null or doesn't have required methods
         if (!node || !node.hasAttribute || !node.getAttribute) return '';
@@ -67,7 +485,7 @@
         // Add a heuristic to ignore code-like text that might be in the DOM
         if ((text.match(/[;:{}]/g)?.length || 0) > 2) return '';
         return text;
-    }
+        }
 
     const textCache = new Map();
     function getVisibleTextContent(_node) {
@@ -116,22 +534,49 @@
 
             const name = getAccessibleName(element);
 
+            // Get persistent ref for this element
+            const ref = getOrAssignRef(element);
+
             // Create the node
             const node = {
                 role,
                 name,
                 children: [],
                 element: element,
-                ref: generateRef(),
+                ref: ref,
             };
 
             // Add states for interactive elements, similar to Playwright
-            if (element.hasAttribute('disabled')) node.disabled = true;
-            if (element.hasAttribute('aria-checked')) node.checked = element.getAttribute('aria-checked');
-            if (element.hasAttribute('aria-expanded')) node.expanded = element.getAttribute('aria-expanded');
+            if (element.hasAttribute('disabled') || element.disabled) node.disabled = true;
+
+            // NEW: Check if element is occluded and mark with occluded tag
+            if (isOccluded(element)) {
+                node.occluded = true; // Mark as occluded but don't disable
+            }
+
+            // Handle aria-checked and native checked
+            const ariaChecked = element.getAttribute('aria-checked');
+            if (ariaChecked) {
+                node.checked = ariaChecked;
+            } else if (element.type === 'checkbox' || element.type === 'radio') {
+                node.checked = element.checked;
+            }
+
+            // Handle aria-expanded
+            const ariaExpanded = element.getAttribute('aria-expanded');
+            if (ariaExpanded) {
+                node.expanded = ariaExpanded === 'true';
+            }
 
-            // Tag element with a ref for later lookup
-            element.setAttribute('aria-ref', node.ref);
+            // Handle aria-selected
+            const ariaSelected = element.getAttribute('aria-selected');
+            if (ariaSelected === 'true') {
+                node.selected = true;
+            }
+
+            // Add level support following Playwright's implementation
+            const level = getAriaLevel(element);
+            if (level > 0) node.level = level;
 
             return node;
         }
@@ -217,7 +662,7 @@
 
     /**
      * Phase 2: Normalize the tree by removing redundant generic wrappers.
-     * Complete preservation of snapshot.js normalizeTree logic
+     * Complete preservation of snapshot.js normalizeTree logic with cursor inheritance
      */
     function normalizeTree(node) {
         if (typeof node === 'string') return [node];
@@ -229,6 +674,7 @@
         node.children = newChildren;
 
         // Remove child elements that have the same name as their parent
+        // and inherit cursor=pointer property if child had it
         const filteredChildren = [];
         for (const child of node.children) {
             if (typeof child !== 'string' && child.name && node.name) {
@@ -237,6 +683,15 @@
                 if (childName === parentName) {
                     // If child has same name as parent, merge its children into parent
                     filteredChildren.push(...(child.children || []));
+
+                    // Inherit cursor=pointer from merged child
+                    if (child.element && receivesPointerEvents(child.element) && hasPointerCursor(child.element)) {
+                        node.inheritedCursor = true;
+                    }
+
+                    // Also inherit other properties if needed
+                    if (child.disabled && !node.disabled) node.disabled = child.disabled;
+                    if (child.selected && !node.selected) node.selected = child.selected;
                 } else {
                     filteredChildren.push(child);
                 }
@@ -250,6 +705,15 @@
         if (node.children.length === 1 && typeof node.children[0] !== 'string') {
             const child = node.children[0];
             if (child.name && node.name && child.name.trim() === node.name.trim()) {
+                // Inherit cursor=pointer from the child being merged
+                if (child.element && receivesPointerEvents(child.element) && hasPointerCursor(child.element)) {
+                    node.inheritedCursor = true;
+                }
+
+                // Also inherit other properties
+                if (child.disabled && !node.disabled) node.disabled = child.disabled;
+                if (child.selected && !node.selected) node.selected = child.selected;
+
                 // Merge child's children into parent and remove the redundant child
                 node.children = child.children || [];
             }
@@ -266,19 +730,36 @@
 
     /**
      * Phase 3: Render the normalized tree into the final string format.
-     * Complete preservation of snapshot.js renderTree logic
+     * Complete preservation of snapshot.js renderTree logic with Playwright enhancements
      */
     function renderTree(node, indent = '') {
         const lines = [];
         let meaningfulProps = '';
         if (node.disabled) meaningfulProps += ' disabled';
+        if (node.occluded) meaningfulProps += ' occluded';
         if (node.checked !== undefined) meaningfulProps += ` checked=${node.checked}`;
         if (node.expanded !== undefined) meaningfulProps += ` expanded=${node.expanded}`;
+        if (node.selected) meaningfulProps += ' selected';
+
+        // Add level attribute following Playwright's format
+        if (node.level !== undefined) meaningfulProps += ` [level=${node.level}]`;
 
         const ref = node.ref ? ` [ref=${node.ref}]` : '';
+
+        // Add cursor=pointer detection following Playwright's implementation
+        // Check both direct cursor and inherited cursor from merged children
+        let cursor = '';
+        const hasDirectCursor = node.element && receivesPointerEvents(node.element) && hasPointerCursor(node.element);
+        const hasInheritedCursor = node.inheritedCursor;
+
+        // Only add cursor=pointer if element is not occluded
+        if ((hasDirectCursor || hasInheritedCursor) && !node.occluded) {
+            cursor = ' [cursor=pointer]';
+        }
+
         const name = (node.name || '').replace(/\s+/g, ' ').trim();
 
-        // Skip elements with empty names and no meaningful props (ref is not considered meaningful)
+        // Skip elements with empty names and no meaningful props (ref and cursor are not considered meaningful for this check)
         if (!name && !meaningfulProps) {
             // If element has no name and no meaningful props, render its children directly at current level
             for (const child of node.children) {
@@ -294,7 +775,7 @@
             return lines;
         }
 
-        lines.push(`${indent}- ${node.role}${name ? ` "${name}"` : ''}${meaningfulProps}${ref}`);
+        lines.push(`${indent}- ${node.role}${name ? ` "${name}"` : ''}${meaningfulProps}${ref}${cursor}`);
 
         for (const child of node.children) {
             if (typeof child === 'string') {
@@ -390,6 +871,7 @@
                 disabled: node.disabled,
                 checked: node.checked,
                 expanded: node.expanded,
+                level: node.level,
 
                 // Visual information (from page_script.js)
                 coordinates: coordinates,
@@ -398,7 +880,11 @@
                 href: node.element.href || null,
                 value: node.element.value || null,
                 placeholder: node.element.placeholder || null,
-                scrollable: node.element.scrollHeight > node.element.clientHeight
+                scrollable: node.element.scrollHeight > node.element.clientHeight,
+
+                // Playwright-inspired properties
+                receivesPointerEvents: receivesPointerEvents(node.element),
+                hasPointerCursor: hasPointerCursor(node.element)
             };
         }
 
@@ -411,19 +897,64 @@
     }
 
     function analyzePageElements() {
+        // Clean up stale refs before analysis
+        const cleanedRefCount = cleanupStaleRefs();
+
+        // Performance optimization: Check if we can reuse recent analysis
+        const currentTime = Date.now();
+        const lastAnalysisTime = window.__camelLastAnalysisTime || 0;
+        const timeSinceLastAnalysis = currentTime - lastAnalysisTime;
+
+        // If less than 1 second since last analysis and page hasn't changed significantly
+        if (timeSinceLastAnalysis < 1000 && window.__camelLastAnalysisResult && cleanedRefCount === 0) {
+            const cachedResult = window.__camelLastAnalysisResult;
+            // Update timestamp and memory info in cached result
+            cachedResult.metadata.timestamp = new Date().toISOString();
+            cachedResult.metadata.memoryInfo = {
+                currentRefCount: refElementMap.size,
+                maxRefs: MAX_REFS,
+                memoryUtilization: (refElementMap.size / MAX_REFS * 100).toFixed(1) + '%',
+                lruAccessTimesCount: refAccessTimes.size
+            };
+            cachedResult.metadata.cacheHit = true;
+            return cachedResult;
+        }
+
         // Generate the complete structured snapshot using original snapshot.js logic
         const outputLines = processDocument(document);
         const snapshotText = outputLines.join('\n');
 
         // Build the tree again to collect element information with visual data
         textCache.clear();
-        refCounter = 1; // Reset counter to match snapshot generation
+        // Note: Don't reset refCounter anymore - use persistent counters
         let tree = buildAriaTree(document.body);
         [tree] = normalizeTree(tree);
 
         const elementsMap = {};
         collectElementsFromTree(tree, elementsMap);
 
+        // Verify uniqueness of aria-ref attributes (debugging aid)
+        const ariaRefCounts = {};
+        document.querySelectorAll('[aria-ref]').forEach(element => {
+            const ref = element.getAttribute('aria-ref');
+            ariaRefCounts[ref] = (ariaRefCounts[ref] || 0) + 1;
+        });
+
+        // Log any duplicates for debugging
+        const duplicateRefs = Object.entries(ariaRefCounts).filter(([ref, count]) => count > 1);
+        if (duplicateRefs.length > 0) {
+            console.warn('Duplicate aria-ref attributes found:', duplicateRefs);
+        }
+
+        // Validate ref consistency
+        const refValidationErrors = [];
+        for (const [ref, elementInfo] of Object.entries(elementsMap)) {
+            const mappedElement = refElementMap.get(ref);
+            if (!mappedElement || !document.contains(mappedElement)) {
+                refValidationErrors.push(`Ref ${ref} points to invalid or removed element`);
+            }
+        }
+
         const result = {
             url: window.location.href,
             elements: elementsMap,
@@ -435,10 +966,34 @@
                     width: window.innerWidth,
                     height: window.innerHeight,
                     devicePixelRatio: window.devicePixelRatio || 1
-                }
+                },
+                // Enhanced debugging information
+                ariaRefCounts: ariaRefCounts,
+                duplicateRefsFound: duplicateRefs.length > 0,
+                staleRefsCleanedUp: cleanedRefCount,
+                refValidationErrors: refValidationErrors,
+                totalMappedRefs: refElementMap.size,
+                refCounterValue: refCounter,
+                // Memory management information
+                memoryInfo: {
+                    currentRefCount: refElementMap.size,
+                    maxRefs: MAX_REFS,
+                    memoryUtilization: (refElementMap.size / MAX_REFS * 100).toFixed(1) + '%',
+                    lruAccessTimesCount: refAccessTimes.size,
+                    unusedAgeThreshold: MAX_UNUSED_AGE_MS + 'ms',
+                    cleanupThreshold: (CLEANUP_THRESHOLD * 100).toFixed(0) + '%',
+                    isAggressiveCleanup: refElementMap.size > (MAX_REFS * CLEANUP_THRESHOLD)
+                },
+                // Performance information
+                cacheHit: false,
+                analysisTime: Date.now() - currentTime
             }
         };
 
+        // Cache the result for potential reuse
+        window.__camelLastAnalysisResult = result;
+        window.__camelLastAnalysisTime = currentTime;
+
         return result;
     }