cursorflow 2.4.3__py3-none-any.whl → 2.5.0__py3-none-any.whl

cursorflow/cli.py

@@ -428,29 +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 numpy type handling
-        with open(output, 'w') as f:
-            def json_serializer(obj):
-                # Handle numpy types
-                if hasattr(obj, 'item'):  # numpy scalars (bool_, int_, float_)
-                    return obj.item()
-                if hasattr(obj, 'tolist'):  # numpy arrays
-                    return obj.tolist()
-                return str(obj)
-            json.dump(results, f, indent=2, default=json_serializer)
+        # 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]")
@@ -551,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/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/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/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,19 +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:
-                    # Custom JSON encoder to handle numpy booleans/integers
-                    def json_serializer(obj):
-                        if hasattr(obj, 'item'):  # numpy types
-                            return obj.item()
-                        return str(obj)
-                    json.dump(comparison_report, f, indent=2, default=json_serializer)
+                safe_json_dump(comparison_report, str(report_path))
                 
                 self.logger.info(f"Mockup comparison completed: {comparison_name}")
                 return comparison_report
@@ -293,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
@@ -314,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):
@@ -329,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"""
@@ -1223,55 +1230,19 @@ class MockupComparator:
         
         avg_similarity = sum(similarities) / len(similarities) if similarities else 0
         
+        # Pure data summary - no interpretation
         return {
             "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": bool(avg_similarity < 80)  # Convert numpy.bool_ to Python bool
+            "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/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.3.dist-info → cursorflow-2.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.4.3
+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.3.dist-info → cursorflow-2.5.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 cursorflow/__init__.py,sha256=2V9xzG2tYxVWOTmSw2v9Jdbr7lSrMi_y2SMUMuNZdvw,2990
 cursorflow/auto_init.py,sha256=dXQaXXiXe4wkUP-jd8fcJ5fYVt7ASdTb47b7SzXymOM,6122
 cursorflow/auto_updater.py,sha256=oQ12TIMZ6Cm3HF-x9iRWFtvOLkRh-JWPqitS69-4roE,7851
-cursorflow/cli.py,sha256=CzvxsXYt-cHImGDgnzO1cVjUE819fX6UrILMTGL4v3U,65084
+cursorflow/cli.py,sha256=Wj4i60rYGZlGaejES7msuEFWODlu_f0DMlVnHzEFSaU,64742
 cursorflow/install_cursorflow_rules.py,sha256=DsZ0680y9JMuTKFXjdgYtOKIEAjBMsdwL8LmA9WEb5A,11864
 cursorflow/post_install.py,sha256=WieBiKWG0qBAQpF8iMVWUyb9Fr2Xky9qECTMPrlAbpE,2678
 cursorflow/updater.py,sha256=SroSQHQi5cYyzcOK_bf-WzmQmE7yeOs8qo3r__j-Z6E,19583
@@ -13,15 +13,16 @@ cursorflow/core/browser_engine.py,sha256=7N9hPOyDrEhLWYgZW2981N9gKlHF6Lbp7D7h0zB
 cursorflow/core/config_validator.py,sha256=HRtONSOmM0Xxt3-ok3xwnBADRiNnI0nNOMaS2OqOkDk,7286
 cursorflow/core/css_iterator.py,sha256=whLCIwbHZEWaH1HCbmqhNX5zrh_fL-r3hsxKjYsukcE,16478
 cursorflow/core/cursor_integration.py,sha256=MAeHjXYeqzaXnhskqkTDB-n5ixIHqapGe93X0lLKhws,67501
-cursorflow/core/cursorflow.py,sha256=qLTyLMf1fm2l5yDafalZXbtBHETsDXyJUSyoW4f8L_o,46470
+cursorflow/core/cursorflow.py,sha256=j1LRNiRpUl3gZlB3r-yQ_h0HISNwnhi8-iZa_E0h86o,46111
 cursorflow/core/error_context_collector.py,sha256=so-aveqwb6_vRDbtKR2ln8_F84aaVIceNi1UHsaVPgc,26196
 cursorflow/core/error_correlator.py,sha256=g6YaIF2yFXUDrTuWHCyuES6K0696H8LDWmXH1qI8ddA,13367
 cursorflow/core/event_correlator.py,sha256=lCzXFnii17AQt3rOVOclez_AnjvBCF_2ZlnFG0mIN6c,7808
 cursorflow/core/file_change_monitor.py,sha256=tl_ZdsGW8LZBTImniD-lqaGgNb9dYjlDsP2XmevE0xk,21258
 cursorflow/core/hmr_detector.py,sha256=IrGYhXIeTBukffRXF74SW45cB_Im0cmq8RxxjtSz-2w,17431
+cursorflow/core/json_utils.py,sha256=ofqRP1twDSHQx-SERgLTO5y2ZXkoirsEw8OOiJkGh2w,1370
 cursorflow/core/log_collector.py,sha256=CYh41SLDI_t-hgzJqG3fTrSTDhEPFDktjO_mOQwucnE,15198
 cursorflow/core/log_monitor.py,sha256=pONMu_JHEnT0T62OA5KRZ4nClzKgNpifPyrfN5w_RM8,6704
-cursorflow/core/mockup_comparator.py,sha256=Xg6_LGfPxTAaEf5eVdrBBtq8NVtBhy-C8wd-96w3WwY,65059
+cursorflow/core/mockup_comparator.py,sha256=ttcXdueZz9dwcUGBQ2sft4i66zRdkZkFPu41s6JlEwU,63472
 cursorflow/core/persistent_session.py,sha256=FsEHj4wKkycmdp6PFRHv3g333Y74yqra0x_qhUTQpik,36075
 cursorflow/core/report_generator.py,sha256=-vosfyrnfVyWDbAIMlMurl90xOXqBae8d6aLd9sEqiY,10113
 cursorflow/core/trace_manager.py,sha256=Jj9ultZrL1atiZXfcRVI6ynCnnfqZM-X0_taxt-llJ0,7189
@@ -29,10 +30,10 @@ cursorflow/log_sources/local_file.py,sha256=GVnhsaifIdc41twXwbxRM9-fBeRDsknDpk5I
 cursorflow/log_sources/ssh_remote.py,sha256=_Kwh0bhRpKgq-0c98oaX2hN6h9cT-wCHlqY5NiWVCoY,8388
 cursorflow/rules/__init__.py,sha256=gPcA-IkhXj03sl7cvZV0wwo7CtEkcyuKs4y0F5oQbqE,458
 cursorflow/rules/cursorflow-installation.mdc,sha256=D55pzzDPAVVbE3gAtKPUGoT-2fvB-FI2l6yrTdzUIEo,10208
-cursorflow/rules/cursorflow-usage.mdc,sha256=8TUeQ1hq2fTlgPqUBYOVBXrdEN0BR0Xp0d_1L-eUsME,23150
-cursorflow-2.4.3.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
-cursorflow-2.4.3.dist-info/METADATA,sha256=kyrYszlZJXJSSjvt4wdASU4onxYp3vq3MoFVtv49rdQ,14793
-cursorflow-2.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cursorflow-2.4.3.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
-cursorflow-2.4.3.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
-cursorflow-2.4.3.dist-info/RECORD,,
+cursorflow/rules/cursorflow-usage.mdc,sha256=W56Qydfb4jqSBTrki7cNyFPfOe_b89mzniRtKSrMlz4,24138
+cursorflow-2.5.0.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
+cursorflow-2.5.0.dist-info/METADATA,sha256=vr-9bDM-frTvKKRDVPCdekst6mD8oNtxObWj9Y9VaUY,15011
+cursorflow-2.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cursorflow-2.5.0.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
+cursorflow-2.5.0.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
+cursorflow-2.5.0.dist-info/RECORD,,