cursorflow 2.4.2__tar.gz → 2.5.0__tar.gz

{cursorflow-2.4.2 → cursorflow-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.4.2
+Version: 2.5.0
 Summary: 🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
 Author-email: GeekWarrior Development <rbush@cooltheory.com>
 License-Expression: MIT
@@ -370,20 +370,22 @@ cursorflow test --base-url http://localhost:3000 --responsive --actions '[
 cursorflow test --base-url http://localhost:3000 --path "/api" --output "api-test-results.json"
 ```
 
-### **Design Comparison**
+### **Design Comparison** (Pure Measurement)
 ```bash
-# Compare mockup to implementation
+# Compare mockup to implementation - get similarity metrics
 cursorflow compare-mockup https://mockup.com/design \
   --base-url http://localhost:3000 \
-  --mockup-actions '[{"navigate": "/"}]' \
   --implementation-actions '[{"navigate": "/dashboard"}]'
+# Output: 87.3% similarity, diff images, element measurements
 
-# CSS iteration with HMR intelligence
+# Test CSS variations - observe real rendering
 cursorflow iterate-mockup https://mockup.com/design \
   --base-url http://localhost:5173 \
   --css-improvements '[
-    {"name": "fix-spacing", "css": ".container { gap: 2rem; }"}
+    {"name": "spacing-fix", "css": ".container { gap: 2rem; }"},
+    {"name": "tighter-spacing", "css": ".container { gap: 1rem; }"}
   ]'
+# Output: Similarity data for each variation (Cursor decides which to apply)
 ```
 
 ### **Element Analysis & CSS Debugging**

{cursorflow-2.4.2 → cursorflow-2.5.0}/README.md

@@ -325,20 +325,22 @@ cursorflow test --base-url http://localhost:3000 --responsive --actions '[
 cursorflow test --base-url http://localhost:3000 --path "/api" --output "api-test-results.json"
 ```
 
-### **Design Comparison**
+### **Design Comparison** (Pure Measurement)
 ```bash
-# Compare mockup to implementation
+# Compare mockup to implementation - get similarity metrics
 cursorflow compare-mockup https://mockup.com/design \
   --base-url http://localhost:3000 \
-  --mockup-actions '[{"navigate": "/"}]' \
   --implementation-actions '[{"navigate": "/dashboard"}]'
+# Output: 87.3% similarity, diff images, element measurements
 
-# CSS iteration with HMR intelligence
+# Test CSS variations - observe real rendering
 cursorflow iterate-mockup https://mockup.com/design \
   --base-url http://localhost:5173 \
   --css-improvements '[
-    {"name": "fix-spacing", "css": ".container { gap: 2rem; }"}
+    {"name": "spacing-fix", "css": ".container { gap: 2rem; }"},
+    {"name": "tighter-spacing", "css": ".container { gap: 1rem; }"}
   ]'
+# Output: Similarity data for each variation (Cursor decides which to apply)
 ```
 
 ### **Element Analysis & CSS Debugging**

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow/cli.py

@@ -357,13 +357,11 @@ def test(base_url, path, actions, output, logs, config, verbose, headless, timeo
               help='JSON array of viewports to test: [{"width": 1440, "height": 900, "name": "desktop"}]')
 @click.option('--diff-threshold', '-t', type=float, default=0.1,
               help='Visual difference threshold (0.0-1.0)')
-@click.option('--block-tracking', is_flag=True,
-              help='Block tracking scripts (Google Analytics, Facebook Pixel, etc.) to prevent timeout')
 @click.option('--output', '-o', default='mockup_comparison_results.json',
               help='Output file for comparison results')
 @click.option('--verbose', is_flag=True,
               help='Verbose output')
-def compare_mockup(mockup_url, base_url, mockup_actions, implementation_actions, viewports, diff_threshold, block_tracking, output, verbose):
+def compare_mockup(mockup_url, base_url, mockup_actions, implementation_actions, viewports, diff_threshold, output, verbose):
     """Compare mockup design to work-in-progress implementation"""
     
     console.print(f"🎨 Comparing mockup [blue]{mockup_url}[/blue] to implementation [blue]{base_url}[/blue]")
@@ -407,16 +405,10 @@ def compare_mockup(mockup_url, base_url, mockup_actions, implementation_actions,
     try:
         from .core.cursorflow import CursorFlow
         
-        # Configure browser with tracking blocking if requested
-        browser_config = {'headless': True}
-        if block_tracking:
-            browser_config['block_tracking'] = True
-            console.print("🚫 Blocking tracking scripts (Google Analytics, Facebook Pixel, etc.)")
-        
         flow = CursorFlow(
             base_url=base_url,
             log_config={'source': 'local', 'paths': ['logs/app.log']},
-            browser_config=browser_config
+            browser_config={'headless': True}
         )
     except Exception as e:
         console.print(f"[red]Error initializing CursorFlow: {e}[/red]")
@@ -436,22 +428,20 @@ def compare_mockup(mockup_url, base_url, mockup_actions, implementation_actions,
             console.print(f"[red]❌ Comparison failed: {results['error']}[/red]")
             return
         
-        # Display results summary
+        # Display results summary (pure metrics only)
         summary = results.get('summary', {})
         console.print(f"✅ Comparison completed: {results.get('comparison_id', 'unknown')}")
         console.print(f"📊 Average similarity: [bold]{summary.get('average_similarity', 0)}%[/bold]")
         console.print(f"📱 Viewports tested: {summary.get('viewports_tested', 0)}")
         
-        # Show recommendations
-        recommendations = results.get('recommendations', [])
-        if recommendations:
-            console.print(f"💡 Recommendations: {len(recommendations)} improvements suggested")
-            for i, rec in enumerate(recommendations[:3]):  # Show first 3
-                console.print(f"  {i+1}. {rec.get('description', 'No description')}")
+        # Show similarity range
+        similarity_range = summary.get('similarity_range', {})
+        if similarity_range:
+            console.print(f"📈 Similarity range: {similarity_range.get('min', 0)}% - {similarity_range.get('max', 0)}%")
         
-        # Save results
-        with open(output, 'w') as f:
-            json.dump(results, f, indent=2, default=str)
+        # Save results with safe serialization
+        from .core.json_utils import safe_json_dump
+        safe_json_dump(results, output)
         
         console.print(f"💾 Full results saved to: [cyan]{output}[/cyan]")
         console.print(f"📁 Visual diffs stored in: [cyan].cursorflow/artifacts/[/cyan]")
@@ -552,9 +542,10 @@ def iterate_mockup(mockup_url, base_url, css_improvements, base_actions, diff_th
             for i, rec in enumerate(recommendations[:3]):
                 console.print(f"  {i+1}. {rec.get('description', 'No description')}")
         
-        # Save results
+        # Save results with numpy type handling
+        from cursorflow.core.json_utils import safe_json_serialize
         with open(output, 'w') as f:
-            json.dump(results, f, indent=2, default=str)
+            json.dump(results, f, indent=2, default=safe_json_serialize)
         
         console.print(f"💾 Full results saved to: [cyan]{output}[/cyan]")
         console.print(f"📁 Iteration progress stored in: [cyan].cursorflow/artifacts/[/cyan]")

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow/core/browser_controller.py

@@ -131,9 +131,9 @@ class BrowserController:
             self.context = await self.browser.new_context(**context_config)
             self.page = await self.context.new_page()
             
-            # Block tracking scripts if requested (prevents timeout on pages with analytics)
-            if self.config.get("block_tracking", False):
-                await self._setup_tracking_blocker()
+            # Note: We do NOT block tracking scripts by default
+            # CursorFlow philosophy: "Capture reality, not fiction"
+            # Blocking scripts would alter the actual page behavior we're measuring
             
             # v2.0 Enhancement: Initialize Error Context Collector
             self.error_context_collector = ErrorContextCollector(self.page, self.logger)
@@ -173,33 +173,6 @@ class BrowserController:
             
             raise
     
-    async def _setup_tracking_blocker(self):
-        """Block common tracking scripts to prevent networkidle timeout"""
-        tracking_patterns = [
-            "*google-analytics.com/*",
-            "*googletagmanager.com/*",
-            "*facebook.com/tr/*",
-            "*facebook.net/*",
-            "*doubleclick.net/*",
-            "*analytics.google.com/*",
-            "*hotjar.com/*",
-            "*mixpanel.com/*",
-            "*segment.com/*",
-            "*googleadservices.com/*",
-            "*connect.facebook.net/*",
-            "*/analytics/*",
-            "*/tracking/*"
-        ]
-        
-        async def block_tracking(route):
-            """Block tracking request"""
-            await route.abort()
-        
-        for pattern in tracking_patterns:
-            await self.page.route(pattern, block_tracking)
-        
-        self.logger.info("🚫 Tracking scripts blocked")
-    
     async def _setup_event_listeners(self):
         """Set up universal event listeners for any framework"""
         
@@ -388,8 +361,9 @@ class BrowserController:
             self.logger.info(f"Navigating to: {url}")
             
             # Navigate and wait
+            # Use 'load' instead of 'networkidle' to avoid timeout on pages with tracking scripts
             if wait_for_load:
-                await self.page.goto(url, wait_until="networkidle", timeout=30000)
+                await self.page.goto(url, wait_until="load", timeout=30000)
             else:
                 await self.page.goto(url, timeout=30000)
                 

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow/core/cursorflow.py

@@ -575,19 +575,9 @@ class CursorFlow:
             if "error" in raw_results:
                 return raw_results
             
-            # Format results for Cursor analysis
-            session_id = f"mockup_comparison_{int(time.time())}"
-            cursor_results = self.cursor_integration.format_mockup_comparison_results(
-                raw_results=raw_results,
-                session_id=session_id,
-                project_context={
-                    "framework": "auto-detected",
-                    "base_url": self.base_url,
-                    "test_type": "mockup_comparison"
-                }
-            )
-            
-            return cursor_results
+            # Return raw measurement data directly (pure observation)
+            # No interpretation, no analysis - Cursor makes decisions based on data
+            return raw_results
             
         except Exception as e:
             self.logger.error(f"Mockup comparison failed: {e}")

cursorflow-2.5.0/cursorflow/core/json_utils.py

@@ -0,0 +1,53 @@
+"""
+JSON Serialization Utilities
+
+Handles conversion of numpy and other non-standard types to JSON-safe Python types.
+Essential for mockup comparison and any feature using PIL/numpy for image analysis.
+"""
+
+import json
+from typing import Any
+from pathlib import Path
+
+
+def safe_json_serialize(obj: Any) -> Any:
+    """
+    Convert any Python/numpy type to JSON-safe type
+    
+    Handles:
+    - numpy scalars (bool_, int_, float_)
+    - numpy arrays (ndarray)
+    - Other non-serializable types (converts to string)
+    
+    Args:
+        obj: Any object that might not be JSON serializable
+        
+    Returns:
+        JSON-safe Python type
+    """
+    # numpy scalars (bool_, int64, float64, etc.)
+    if hasattr(obj, 'item'):
+        return obj.item()
+    
+    # numpy arrays
+    if hasattr(obj, 'tolist'):
+        return obj.tolist()
+    
+    # Fallback for anything else
+    return str(obj)
+
+
+def safe_json_dump(data: Any, file_path: str, indent: int = 2) -> None:
+    """
+    Safely dump data to JSON file with numpy type handling
+    
+    Args:
+        data: Data to serialize
+        file_path: Path to output file
+        indent: JSON indentation level
+    """
+    file_path = Path(file_path)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    with open(file_path, 'w') as f:
+        json.dump(data, f, indent=indent, default=safe_json_serialize)

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow/core/mockup_comparator.py

@@ -11,6 +11,8 @@ import json
 from typing import Dict, List, Optional, Any, Tuple
 from pathlib import Path
 import logging
+
+from .json_utils import safe_json_dump, safe_json_serialize
 try:
     from PIL import Image, ImageDraw, ImageChops
     import numpy as np
@@ -107,9 +109,14 @@ class MockupComparator:
                     await mockup_browser.set_viewport(viewport["width"], viewport["height"])
                     await implementation_browser.set_viewport(viewport["width"], viewport["height"])
                     
-                    # Navigate to initial pages
+                    # Navigate to initial pages with stabilization
                     await mockup_browser.navigate("/")
+                    await asyncio.sleep(1)
+                    await mockup_browser.page.wait_for_load_state("domcontentloaded")
+                    
                     await implementation_browser.navigate("/")
+                    await asyncio.sleep(1)
+                    await implementation_browser.page.wait_for_load_state("domcontentloaded")
                     
                     # Execute any required actions on mockup
                     if mockup_actions:
@@ -119,6 +126,9 @@ class MockupComparator:
                     if implementation_actions:
                         await self._execute_actions_on_browser(implementation_browser, implementation_actions)
                     
+                    # Final stabilization before capturing
+                    await asyncio.sleep(0.5)
+                    
                     # Capture screenshots
                     mockup_screenshot = await self._capture_comparison_screenshot(
                         mockup_browser, f"{comparison_name}_mockup_{viewport_name}"
@@ -163,14 +173,12 @@ class MockupComparator:
                     "implementation_url": implementation_url,
                     "viewports_tested": len(viewports),
                     "results": comparison_results,
-                    "summary": self._create_comparison_summary(comparison_results),
-                    "recommendations": self._generate_improvement_recommendations(comparison_results)
+                    "summary": self._create_comparison_summary(comparison_results)
                 }
                 
-                # Save comparison report
+                # Save comparison report with safe serialization
                 report_path = self.artifacts_base / "mockup_comparisons" / f"{comparison_name}.json"
-                with open(report_path, 'w') as f:
-                    json.dump(comparison_report, f, indent=2, default=str)
+                safe_json_dump(comparison_report, str(report_path))
                 
                 self.logger.info(f"Mockup comparison completed: {comparison_name}")
                 return comparison_report
@@ -288,10 +296,9 @@ class MockupComparator:
                     "final_recommendations": self._generate_final_recommendations(iteration_results)
                 }
                 
-                # Save iteration report
+                # Save iteration report with safe JSON serialization
                 report_path = self.artifacts_base / "iteration_progress" / f"{iteration_session_id}.json"
-                with open(report_path, 'w') as f:
-                    json.dump(iteration_report, f, indent=2, default=str)
+                safe_json_dump(iteration_report, str(report_path))
                 
                 self.logger.info(f"UI matching iteration completed: {iteration_session_id}")
                 return iteration_report
@@ -309,11 +316,15 @@ class MockupComparator:
             if "navigate" in action:
                 path = action["navigate"]
                 await browser.navigate(path)
+                # Wait for page to stabilize after navigation
+                await asyncio.sleep(1)  # Brief pause for dynamic content rendering
+                await browser.page.wait_for_load_state("domcontentloaded")
             elif "click" in action:
                 selector = action["click"]
                 if isinstance(selector, dict):
                     selector = selector["selector"]
                 await browser.click(selector)
+                await asyncio.sleep(0.5)  # Brief pause for UI response
             elif "wait_for" in action:
                 selector = action["wait_for"]
                 if isinstance(selector, dict):
@@ -324,6 +335,7 @@ class MockupComparator:
             elif "scroll" in action:
                 scroll_config = action["scroll"]
                 await browser.page.evaluate(f"window.scrollTo({scroll_config.get('x', 0)}, {scroll_config.get('y', 0)})")
+                await asyncio.sleep(0.3)  # Brief pause for scroll rendering
     
     async def _capture_comparison_screenshot(self, browser: BrowserController, name: str) -> str:
         """Capture screenshot for comparison"""
@@ -1194,11 +1206,11 @@ class MockupComparator:
             improvement = improved_similarity - baseline_similarity
             
             return {
-                "baseline_similarity": baseline_similarity,
-                "improved_similarity": improved_similarity,
-                "improvement": improvement,
-                "improvement_percentage": round(improvement, 2),
-                "is_improvement": improvement > 0
+                "baseline_similarity": float(baseline_similarity),
+                "improved_similarity": float(improved_similarity),
+                "improvement": float(improvement),
+                "improvement_percentage": round(float(improvement), 2),
+                "is_improvement": bool(improvement > 0)  # Convert to Python bool
             }
             
         except Exception as e:
@@ -1218,55 +1230,19 @@ class MockupComparator:
         
         avg_similarity = sum(similarities) / len(similarities) if similarities else 0
         
+        # Pure data summary - no interpretation
         return {
-            "average_similarity": round(avg_similarity, 2),
+            "average_similarity": round(float(avg_similarity), 2),
             "viewports_tested": len(comparison_results),
-            "best_viewport_match": max(comparison_results, key=lambda x: x.get("visual_diff", {}).get("similarity_score", 0)),
-            "needs_improvement": avg_similarity < 80  # Threshold for "good enough"
+            "similarity_by_viewport": [
+                {
+                    "viewport": result.get("viewport", {}).get("name", "unknown"),
+                    "similarity": float(result.get("visual_diff", {}).get("similarity_score", 0))
+                }
+                for result in comparison_results
+            ]
         }
     
-    def _generate_improvement_recommendations(self, comparison_results: List[Dict]) -> List[Dict]:
-        """Generate recommendations for improving implementation to match mockup"""
-        recommendations = []
-        
-        for result in comparison_results:
-            viewport = result.get("viewport", {})
-            layout_analysis = result.get("layout_analysis", {})
-            visual_diff = result.get("visual_diff", {})
-            
-            # Analyze layout differences for recommendations
-            differences = layout_analysis.get("differences", [])
-            
-            for diff in differences:
-                if diff["type"] == "missing_in_implementation":
-                    recommendations.append({
-                        "type": "add_element",
-                        "priority": "high",
-                        "description": f"Add missing element: {diff['selector']}",
-                        "viewport": viewport.get("name", "unknown")
-                    })
-                elif diff["type"] == "property_differences":
-                    for prop, prop_diff in diff.get("differences", {}).items():
-                        recommendations.append({
-                            "type": "adjust_property",
-                            "priority": "medium",
-                            "description": f"Adjust {prop} for {diff['selector']}",
-                            "current_value": prop_diff.get("implementation"),
-                            "target_value": prop_diff.get("mockup"),
-                            "viewport": viewport.get("name", "unknown")
-                        })
-            
-            # Add visual similarity recommendations
-            similarity = visual_diff.get("similarity_score", 0)
-            if similarity < 70:
-                recommendations.append({
-                    "type": "major_visual_changes",
-                    "priority": "high",
-                    "description": f"Significant visual differences detected (similarity: {similarity}%)",
-                    "viewport": viewport.get("name", "unknown")
-                })
-        
-        return recommendations
     
     def _create_iteration_summary(self, baseline_comparison: Dict, iteration_results: List[Dict]) -> Dict[str, Any]:
         """Create summary of iteration session"""

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow/rules/cursorflow-usage.mdc

@@ -425,6 +425,31 @@ cursorflow measure -u http://localhost:3000 -s "#panel"
 # Output: 532w × 900h ✅
 ```
 
+### Visual Comparison & Iteration
+```bash
+# Compare mockup to implementation (pure measurement)
+cursorflow compare-mockup MOCKUP_URL -u BASE_URL -ia '[{"navigate": "/page"}]'
+# Output: Similarity percentage, diff images, element data
+
+# Test CSS variations (observe real rendering)
+cursorflow iterate-mockup MOCKUP_URL -u BASE_URL --css-improvements '[
+  {"name": "test1", "css": ".header { padding: 2rem; }"},
+  {"name": "test2", "css": ".header { padding: 1rem; }"}
+]'
+# Output: Similarity for each variation - Cursor decides which to apply
+```
+
+**Philosophy**: 
+- CursorFlow observes mockup and implementation (both are reality)
+- Provides quantified measurements (similarity %, diff images, element data)
+- Temporarily injects CSS to observe what reality WOULD look like
+- Cursor analyzes the data and makes decisions
+
+**When to use**:
+- User has design mockup and needs to match it
+- Testing multiple CSS approaches before applying
+- Measuring progress toward design specifications
+
 ## Analyzing Results
 
 ### **Hot Reload CSS Iteration Results** 

{cursorflow-2.4.2 → cursorflow-2.5.0}/cursorflow.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ cursorflow/core/error_correlator.py
 cursorflow/core/event_correlator.py
 cursorflow/core/file_change_monitor.py
 cursorflow/core/hmr_detector.py
+cursorflow/core/json_utils.py
 cursorflow/core/log_collector.py
 cursorflow/core/log_monitor.py
 cursorflow/core/mockup_comparator.py