cursorflow 1.3.6__tar.gz → 1.3.7__tar.gz

{cursorflow-1.3.6 → cursorflow-1.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 1.3.6
+Version: 1.3.7
 Summary: Complete page intelligence for AI-driven development - captures DOM, network, console, and performance data
 Author-email: GeekWarrior Development <rbush@cooltheory.com>
 License-Expression: MIT
@@ -32,6 +32,8 @@ Requires-Dist: jinja2>=3.1.2
 Requires-Dist: python-dateutil>=2.8.2
 Requires-Dist: watchdog>=3.0.0
 Requires-Dist: docker>=6.1.3
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"

{cursorflow-1.3.6 → cursorflow-1.3.7}/cursorflow/core/browser_controller.py

@@ -982,6 +982,13 @@ class BrowserController:
                     const paint = perf.getEntriesByType('paint');
                     const resources = perf.getEntriesByType('resource');
                     
+                    // Helper function to safely calculate timing differences
+                    const safeTiming = (end, start) => {
+                        if (!end || !start || end === 0 || start === 0) return null;
+                        const diff = end - start;
+                        return diff >= 0 ? diff : null;
+                    };
+                    
                     // Memory usage (if available)
                     const memory = performance.memory ? {
                         usedJSHeapSize: performance.memory.usedJSHeapSize,
@@ -1000,19 +1007,40 @@ class BrowserController:
                     
                     return {
                         navigation: navigation ? {
-                            domContentLoaded: navigation.domContentLoadedEventEnd - navigation.domContentLoadedEventStart,
-                            loadComplete: navigation.loadEventEnd - navigation.loadEventStart,
-                            domInteractive: navigation.domInteractive - navigation.navigationStart,
-                            domComplete: navigation.domComplete - navigation.navigationStart,
-                            redirectTime: navigation.redirectEnd - navigation.redirectStart,
-                            dnsTime: navigation.domainLookupEnd - navigation.domainLookupStart,
-                            connectTime: navigation.connectEnd - navigation.connectStart,
-                            requestTime: navigation.responseStart - navigation.requestStart,
-                            responseTime: navigation.responseEnd - navigation.responseStart
-                        } : null,
+                            domContentLoaded: safeTiming(navigation.domContentLoadedEventEnd, navigation.domContentLoadedEventStart),
+                            loadComplete: safeTiming(navigation.loadEventEnd, navigation.loadEventStart),
+                            domInteractive: safeTiming(navigation.domInteractive, navigation.navigationStart),
+                            domComplete: safeTiming(navigation.domComplete, navigation.navigationStart),
+                            redirectTime: safeTiming(navigation.redirectEnd, navigation.redirectStart),
+                            dnsTime: safeTiming(navigation.domainLookupEnd, navigation.domainLookupStart),
+                            connectTime: safeTiming(navigation.connectEnd, navigation.connectStart),
+                            requestTime: safeTiming(navigation.responseStart, navigation.requestStart),
+                            responseTime: safeTiming(navigation.responseEnd, navigation.responseStart),
+                            // Add raw values for debugging
+                            _raw: {
+                                navigationStart: navigation.navigationStart,
+                                domContentLoadedEventStart: navigation.domContentLoadedEventStart,
+                                domContentLoadedEventEnd: navigation.domContentLoadedEventEnd,
+                                loadEventStart: navigation.loadEventStart,
+                                loadEventEnd: navigation.loadEventEnd
+                            }
+                        } : {
+                            domContentLoaded: null,
+                            loadComplete: null,
+                            domInteractive: null,
+                            domComplete: null,
+                            redirectTime: null,
+                            dnsTime: null,
+                            connectTime: null,
+                            requestTime: null,
+                            responseTime: null,
+                            _raw: null,
+                            _note: "Navigation timing not available (likely headless mode)"
+                        },
                         paint: {
-                            firstPaint: paint.find(p => p.name === 'first-paint')?.startTime || 0,
-                            firstContentfulPaint: paint.find(p => p.name === 'first-contentful-paint')?.startTime || 0
+                            firstPaint: paint.find(p => p.name === 'first-paint')?.startTime || null,
+                            firstContentfulPaint: paint.find(p => p.name === 'first-contentful-paint')?.startTime || null,
+                            _available: paint.length > 0
                         },
                         memory: memory,
                         resources: {
@@ -1036,12 +1064,18 @@ class BrowserController:
                 "browser_metrics": browser_metrics,
                 "detailed_metrics": additional_metrics,
                 "performance_summary": {
-                    "page_load_time": additional_metrics.get("navigation", {}).get("loadComplete", 0),
-                    "dom_content_loaded": additional_metrics.get("navigation", {}).get("domContentLoaded", 0),
-                    "first_paint": additional_metrics.get("paint", {}).get("firstPaint", 0),
-                    "first_contentful_paint": additional_metrics.get("paint", {}).get("firstContentfulPaint", 0),
+                    "page_load_time": additional_metrics.get("navigation", {}).get("loadComplete"),
+                    "dom_content_loaded": additional_metrics.get("navigation", {}).get("domContentLoaded"),
+                    "first_paint": additional_metrics.get("paint", {}).get("firstPaint"),
+                    "first_contentful_paint": additional_metrics.get("paint", {}).get("firstContentfulPaint"),
                     "total_resources": additional_metrics.get("resources", {}).get("summary", {}).get("totalResources", 0),
-                    "memory_usage_mb": additional_metrics.get("memory", {}).get("usedJSHeapSize", 0) / (1024 * 1024) if additional_metrics.get("memory") else None
+                    "memory_usage_mb": additional_metrics.get("memory", {}).get("usedJSHeapSize", 0) / (1024 * 1024) if additional_metrics.get("memory") else None,
+                    "_reliability": {
+                        "navigation_timing_available": additional_metrics.get("navigation", {}).get("_raw") is not None,
+                        "paint_timing_available": additional_metrics.get("paint", {}).get("_available", False),
+                        "memory_available": additional_metrics.get("memory") is not None,
+                        "note": "Some metrics may be null in headless mode - this is expected behavior"
+                    }
                 }
             }
             

{cursorflow-1.3.6 → cursorflow-1.3.7}/cursorflow/core/mockup_comparator.py

@@ -11,8 +11,20 @@ import json
 from typing import Dict, List, Optional, Any, Tuple
 from pathlib import Path
 import logging
-from PIL import Image, ImageDraw, ImageChops
-import numpy as np
+try:
+    from PIL import Image, ImageDraw, ImageChops
+    import numpy as np
+    VISUAL_COMPARISON_AVAILABLE = True
+    # Type aliases for when PIL is available
+    PILImage = Image.Image
+    NDArray = np.ndarray
+except ImportError:
+    # PIL/numpy not available - visual comparison features disabled
+    Image = ImageDraw = ImageChops = np = None
+    VISUAL_COMPARISON_AVAILABLE = False
+    # Dummy types for when PIL/numpy are not available
+    PILImage = Any
+    NDArray = Any
 
 from .browser_controller import BrowserController
 from .css_iterator import CSSIterator
@@ -327,6 +339,20 @@ class MockupComparator:
         config: Dict
     ) -> Dict[str, Any]:
         """Create visual difference analysis between mockup and implementation"""
+        
+        if not VISUAL_COMPARISON_AVAILABLE:
+            self.logger.warning("Visual comparison unavailable - PIL/numpy not installed")
+            return {
+                "error": "Visual comparison requires PIL and numpy",
+                "diff_path": None,
+                "highlighted_path": None,
+                "similarity_score": 0.0,
+                "difference_areas": [],
+                "pixel_differences": 0,
+                "total_pixels": 0,
+                "note": "Install with: pip install pillow numpy"
+            }
+        
         try:
             # Load images
             mockup_img = Image.open(mockup_path)
@@ -369,7 +395,7 @@ class MockupComparator:
             self.logger.error(f"Visual diff creation failed: {e}")
             return {"error": str(e)}
     
-    def _create_highlighted_diff(self, mockup_img: Image.Image, implementation_img: Image.Image, diff_img: Image.Image, config: Dict) -> Image.Image:
+    def _create_highlighted_diff(self, mockup_img: PILImage, implementation_img: PILImage, diff_img: PILImage, config: Dict) -> PILImage:
         """Create highlighted difference image with colored regions"""
         # Convert to RGBA for overlay
         highlighted = implementation_img.convert("RGBA")
@@ -393,7 +419,7 @@ class MockupComparator:
         
         return highlighted.convert("RGB")
     
-    def _calculate_visual_diff_metrics(self, mockup_img: Image.Image, implementation_img: Image.Image, diff_img: Image.Image, config: Dict) -> Dict[str, Any]:
+    def _calculate_visual_diff_metrics(self, mockup_img: PILImage, implementation_img: PILImage, diff_img: PILImage, config: Dict) -> Dict[str, Any]:
         """Calculate detailed visual difference metrics"""
         try:
             # Convert to numpy arrays for analysis
@@ -426,7 +452,7 @@ class MockupComparator:
             self.logger.error(f"Visual diff metrics calculation failed: {e}")
             return {"error": str(e)}
     
-    def _find_difference_regions(self, diff_array: np.ndarray, threshold: float) -> List[Dict]:
+    def _find_difference_regions(self, diff_array: NDArray, threshold: float) -> List[Dict]:
         """Find regions with significant visual differences"""
         # This is a simplified implementation - could be enhanced with computer vision
         significant_diff = diff_array > threshold
@@ -448,7 +474,7 @@ class MockupComparator:
         
         return regions
     
-    def _calculate_color_metrics(self, mockup_array: np.ndarray, implementation_array: np.ndarray) -> Dict[str, Any]:
+    def _calculate_color_metrics(self, mockup_array: NDArray, implementation_array: NDArray) -> Dict[str, Any]:
         """Calculate color-based difference metrics"""
         try:
             # Calculate average colors

{cursorflow-1.3.6 → cursorflow-1.3.7}/cursorflow/log_sources/local_file.py

@@ -98,7 +98,11 @@ class LocalFileLogSource:
             return True
             
         except Exception as e:
-            self.logger.error(f"Failed to start tail for {log_name}: {e}")
+            # Log as debug instead of error for non-critical issues
+            if "No such file or directory" in str(e) or "Permission denied" in str(e):
+                self.logger.debug(f"Non-critical log file issue for {log_name}: {e}")
+            else:
+                self.logger.error(f"Failed to start tail for {log_name}: {e}")
             return False
     
     def _read_tail_output(self, log_name: str, log_path: str, process: subprocess.Popen):

{cursorflow-1.3.6 → cursorflow-1.3.7}/cursorflow/log_sources/ssh_remote.py

@@ -10,8 +10,9 @@ import threading
 import queue
 import time
 import logging
+import re
 from typing import Dict, List, Optional
-from datetime import datetime
+from datetime import datetime, timedelta
 
 class SSHRemoteLogSource:
     """Remote log monitoring via SSH"""
@@ -89,7 +90,11 @@ class SSHRemoteLogSource:
             return result == 'test'
             
         except Exception as e:
-            self.logger.error(f"SSH connection test failed: {e}")
+            # Log SSH connection issues as debug for non-critical cases
+            if "Connection refused" in str(e) or "timeout" in str(e).lower():
+                self.logger.debug(f"SSH connection issue (may be expected): {e}")
+            else:
+                self.logger.error(f"SSH connection test failed: {e}")
             return False
     
     def _monitor_single_log(self, log_name: str, log_path: str):

{cursorflow-1.3.6 → cursorflow-1.3.7}/docs/USER_MANUAL.md

@@ -514,6 +514,68 @@ All data is structured for AI analysis:
 - Error correlation with confidence scoring
 - Actionable recommendations based on data
 
+## 🔧 **Troubleshooting**
+
+### **Performance Metrics Reliability**
+
+CursorFlow captures comprehensive performance data, but some metrics behave differently in headless vs headed mode:
+
+#### **Always Reliable (Both Modes):**
+- ✅ **DOM Analysis**: Element properties, computed CSS, bounding boxes
+- ✅ **Network Data**: Request timing, response codes, resource sizes  
+- ✅ **Console Logs**: JavaScript errors, warnings, debug messages
+- ✅ **Memory Usage**: JavaScript heap size (when available)
+- ✅ **Resource Count**: Total loaded resources, slowest resource
+
+#### **Headless Mode Limitations:**
+- ⚠️ **Navigation Timing**: May return `null` instead of 0/NaN
+  - `domContentLoaded`, `loadComplete`, `domInteractive` timing
+  - Raw timing values available in `_raw` object for debugging
+- ⚠️ **Paint Timing**: `firstPaint`, `firstContentfulPaint` may be `null`
+  - Check `_available` flag to see if paint metrics are captured
+
+#### **Understanding the Data:**
+```json
+{
+  "performance_summary": {
+    "page_load_time": null,  // ← null = not available (expected in headless)
+    "dom_content_loaded": 45.2,  // ← actual timing when available
+    "_reliability": {
+      "navigation_timing_available": false,
+      "paint_timing_available": true,
+      "note": "Some metrics may be null in headless mode - this is expected behavior"
+    }
+  }
+}
+```
+
+**Key Point**: `null` values are **expected and normal** in headless mode. The CSS/DOM data (which is what matters most for UI testing) is always 100% reliable.
+
+### **Common Issues**
+
+#### **Missing Dependencies**
+```bash
+# If you see PIL/Pillow errors:
+pip install --upgrade cursorflow  # v1.3.7+ includes all dependencies
+
+# Manual fix for older versions:
+pip install pillow numpy
+```
+
+#### **Log Source Warnings**
+Non-critical log warnings are normal and can be ignored:
+- `SSH connection issue (may be expected)` - appears when SSH monitoring isn't configured
+- `Non-critical log file issue` - appears when log files don't exist yet
+
+#### **Browser Launch Issues**
+```bash
+# Install browser dependencies:
+playwright install chromium
+
+# For Docker/CI environments:
+playwright install-deps chromium
+```
+
 ---
 
 **That's everything you need to know!** CursorFlow is designed to be simple: point it at your app, and it captures everything an AI needs to understand and improve your UI. 🚀

{cursorflow-1.3.6 → cursorflow-1.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "1.3.6"
+version = "1.3.7"
 description = "Complete page intelligence for AI-driven development - captures DOM, network, console, and performance data"
 authors = [
     {name = "GeekWarrior Development", email = "rbush@cooltheory.com"}
@@ -36,7 +36,9 @@ dependencies = [
     "jinja2>=3.1.2",
     "python-dateutil>=2.8.2",
     "watchdog>=3.0.0",
-    "docker>=6.1.3"
+    "docker>=6.1.3",
+    "pillow>=10.0.0",
+    "numpy>=1.24.0"
 ]
 
 [project.optional-dependencies]