cursorflow 1.3.7__tar.gz → 2.0.1__tar.gz

{cursorflow-1.3.7 → cursorflow-2.0.1}/MANIFEST.in

@@ -15,6 +15,7 @@ include examples/react_example.py
 include examples/opensas_example.py
 include examples/mockup_comparison_example.py
 include examples/comprehensive_screenshot_example.py
+include examples/v2_comprehensive_demo.py
 
 # INCLUDE: Single comprehensive user manual
 include docs/USER_MANUAL.md

cursorflow-2.0.1/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: cursorflow
+Version: 2.0.1
+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
+Project-URL: Homepage, https://github.com/haley-marketing-group/cursorflow
+Project-URL: Documentation, https://cursorflow.readthedocs.io
+Project-URL: Repository, https://github.com/haley-marketing-group/cursorflow
+Keywords: ui-testing,automation,cursor,ai,web-testing,css-iteration,hot-reload,hmr,element-intelligence,page-analysis,error-context
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: paramiko>=3.3.1
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: asyncio-mqtt>=0.11.1
+Requires-Dist: click>=8.1.7
+Requires-Dist: rich>=13.6.0
+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
+Requires-Dist: websockets>=11.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.1; extra == "dev"
+Requires-Dist: black>=23.9.1; extra == "dev"
+Requires-Dist: flake8>=6.1.0; extra == "dev"
+Requires-Dist: mypy>=1.6.1; extra == "dev"
+Dynamic: license-file
+
+# CursorFlow
+
+**Complete page intelligence for AI-driven development**
+
+CursorFlow captures comprehensive data from web applications - DOM structure, CSS properties, network activity, console logs, and performance metrics - enabling AI agents like Cursor to make intelligent decisions about UI improvements and debugging.
+
+## 🎯 What CursorFlow Does
+
+**Data Collection, Not Analysis** - We gather structured data, AI makes the decisions.
+
+### **📊 Complete Page Intelligence**
+Every screenshot captures everything:
+- **DOM**: All elements with 7 selector strategies each
+- **Network**: All requests, responses, and complete response bodies
+- **Console**: All logs, errors, and smart error correlation
+- **Performance**: Load times, memory usage, with reliability indicators
+- **Visual**: Screenshots with pixel-perfect comparisons
+- **Fonts**: Loading status, performance, and usage analysis
+- **Animations**: Active animations and transitions tracking
+- **Resources**: Complete resource loading analysis
+- **Storage**: localStorage, sessionStorage, cookies, IndexedDB state
+
+### **🔄 Rapid Iteration Support**
+- **Hot Reload Intelligence** with framework auto-detection (Vite, Webpack, Next.js, Parcel, Laravel Mix)
+- **Mockup comparison** with enhanced DOM and CSS analysis
+- **Hot reload integration** for instant, perfectly-timed CSS testing
+- **Persistent sessions** that survive code changes
+- **Universal framework support** (React, Vue, PHP, Perl, anything)
+
+### **🤖 AI-First Design**
+All data structured for AI consumption:
+- Consistent JSON format across all features
+- **Multi-selector element identification** for robust automation
+- **Accessibility-aware** element analysis
+- Error correlation with **smart screenshot deduplication**
+- Performance insights with **reliability metadata**
+- **HMR event correlation** for CSS change tracking
+
+## 🚀 Quick Start
+
+```bash
+# Install CursorFlow
+pip install cursorflow
+
+# Test with complete intelligence
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/dashboard"},
+  {"wait_for": "#main-content"},
+  {"screenshot": "dashboard-loaded"}
+]'
+
+# HMR-powered CSS iteration
+cursorflow iterate-mockup https://mockup.com/design \
+  --base-url http://localhost:5173 \
+  --css-improvements '[
+    {"name": "fix-spacing", "css": ".container { gap: 2rem; }"}
+  ]'
+```
+
+## 💻 Usage Examples
+
+### **Hot Reload Intelligence**
+```python
+from cursorflow import CursorFlow
+
+async def hmr_workflow():
+    flow = CursorFlow("http://localhost:5173", {"headless": False})
+    
+    # Start HMR monitoring (auto-detects Vite/Webpack/Next.js)
+    await flow.browser.start_hmr_monitoring()
+    
+    # Take baseline
+    await flow.execute_and_collect([
+        {"navigate": "/app"},
+        {"screenshot": "baseline"}
+    ])
+    
+    # Wait for CSS changes with perfect timing
+    hmr_event = await flow.browser.wait_for_css_update()
+    print(f"🔥 {hmr_event['framework']} CSS update detected!")
+    
+    # Capture immediately after change
+    await flow.execute_and_collect([
+        {"screenshot": "updated"}
+    ])
+```
+
+### **Advanced Element Analysis**
+```python
+# Get comprehensive element data
+results = await flow.execute_and_collect([
+    {"navigate": "/form"},
+    {"screenshot": "form-analysis"}
+])
+
+# Access enhanced element data
+for element in results['artifacts']['screenshots'][0]['dom_analysis']['elements']:
+    print(f"Element: {element['selector']}")
+    print(f"  7 Selectors: {list(element['selectors'].keys())}")
+    print(f"  Accessible: {element['accessibility']['role']}")
+    print(f"  Interactive: {element['accessibility']['interactive']}")
+    print(f"  Visible: {element['visual_context']['visibility']['is_visible']}")
+```
+
+### **Comprehensive Page Intelligence**
+```python
+# Get complete page analysis
+screenshot = results['artifacts']['screenshots'][0]
+
+# Complete Intelligence
+print(f"Fonts loaded: {screenshot['font_status']['loadedFonts']}")
+print(f"Animations running: {screenshot['animation_status']['runningAnimations']}")  
+print(f"Resources: {screenshot['resource_status']['totalResources']}")
+print(f"Storage items: {screenshot['storage_status']['localStorage']['itemCount']}")
+```
+
+### **Smart Error Diagnostics**
+```python
+# Enhanced error context with deduplication
+error_context = await flow.browser.capture_interaction_error_context(
+    action_description="Submit form",
+    error_details={"type": "validation_error"}
+)
+
+print(f"Screenshot: {error_context['screenshot_info']['path']}")
+print(f"Reused: {error_context['screenshot_info']['is_reused']}")  # Smart deduplication
+print(f"Context: {len(error_context['recent_actions'])} recent actions")
+```
+
+## 🔧 CLI Commands
+
+### **Universal Testing with Complete Intelligence**
+```bash
+# Simple page test with full intelligence
+cursorflow test --base-url http://localhost:3000 --path "/dashboard"
+
+# Complex interaction test
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#email", "value": "test@example.com"}},
+  {"click": "#login-btn"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "logged-in"}
+]'
+```
+
+### **HMR-Powered CSS Iteration**
+```bash
+# Perfect CSS iteration with HMR intelligence
+cursorflow iterate-mockup https://mockup.com/design \
+  --base-url http://localhost:5173 \
+  --css-improvements '[
+    {"name": "improve-spacing", "css": ".container { gap: 2rem; }"},
+    {"name": "enhance-colors", "css": ".button { background: #007bff; }"}
+  ]'
+```
+
+### **Enhanced Design Comparison**
+```bash
+# Compare with comprehensive intelligence
+cursorflow compare-mockup https://mockup.com/design \
+  --base-url http://localhost:3000 \
+  --mockup-actions '[{"navigate": "/"}]' \
+  --implementation-actions '[{"navigate": "/dashboard"}]'
+```
+
+## 🧠 AI Integration
+
+### **Cursor Rules (Auto-Install)**
+```bash
+# Install AI assistance rules
+cursorflow install-rules
+```
+
+CursorFlow includes comprehensive rules that teach Cursor:
+- **When to use HMR intelligence** for CSS iteration
+- **How to analyze multi-selector element data**
+- **Best practices for comprehensive page analysis**
+- **Error debugging with smart context collection**
+
+### **Structured Data for AI**
+Every CursorFlow operation returns **perfectly structured JSON** optimized for AI analysis:
+
+```json
+{
+  "artifacts": {
+    "screenshots": [{
+      "path": ".cursorflow/artifacts/screenshots/dashboard_123.png",
+      "dom_analysis": {
+        "elements": [...],  // 7 selectors + accessibility per element
+        "pageStructure": {...},  // Enhanced page analysis
+        "analysisVersion": "2.0"  // Version tracking
+      },
+      "font_status": {...},      // Font loading intelligence
+      "animation_status": {...}, // Animation tracking
+      "resource_status": {...},  // Resource analysis
+      "storage_status": {...},   // Storage state
+      "hmr_status": {...}        // HMR event data
+    }]
+  }
+}
+```
+
+## 🌟 Framework Support
+
+**HMR Auto-Detection:**
+- ✅ **Vite** (port 5173, WebSocket `/__vite_hmr`)
+- ✅ **Webpack Dev Server** (port 3000, WebSocket `/sockjs-node`)
+- ✅ **Next.js** (port 3000, WebSocket `/_next/webpack-hmr`)
+- ✅ **Parcel** (port 1234, WebSocket `/hmr`)
+- ✅ **Laravel Mix** (port 3000, WebSocket `/browser-sync/socket.io`)
+
+**Universal Compatibility:**
+- Works with **any web application** regardless of framework
+- **Framework-agnostic** core operations
+- **Smart adaptation** to different development environments
+
+## 📖 Documentation
+
+- **[Complete User Manual](docs/USER_MANUAL.md)** - Full feature guide
+- **[Examples](examples/)** - Practical usage examples
+- **[API Reference](docs/api/)** - Complete Python API documentation
+
+## 🚀 Why CursorFlow?
+
+### **For Developers:**
+- **Faster CSS iteration** with HMR precision timing
+- **Complete element intelligence** with multi-selector strategies
+- **Full page visibility** with comprehensive analysis
+- **Smart error debugging** with rich context collection
+
+### **For AI Agents:**
+- **Perfect structured data** for intelligent decision making
+- **Multi-selector reliability** for robust automation
+- **Accessibility awareness** for inclusive development
+- **HMR correlation** for understanding change impact
+
+### **For Teams:**
+- **Framework agnostic** - works with any web technology
+- **Production ready** - handles real-world complexity
+- **Comprehensive testing** - covers all aspects of web apps
+- **AI-first design** - built for autonomous development
+
+---
+
+**Complete page intelligence for AI-driven development with CursorFlow**
+
+*Hot reload precision • Advanced element analysis • Smart error diagnostics • Comprehensive page intelligence*

cursorflow-2.0.1/README.md

@@ -0,0 +1,248 @@
+# CursorFlow
+
+**Complete page intelligence for AI-driven development**
+
+CursorFlow captures comprehensive data from web applications - DOM structure, CSS properties, network activity, console logs, and performance metrics - enabling AI agents like Cursor to make intelligent decisions about UI improvements and debugging.
+
+## 🎯 What CursorFlow Does
+
+**Data Collection, Not Analysis** - We gather structured data, AI makes the decisions.
+
+### **📊 Complete Page Intelligence**
+Every screenshot captures everything:
+- **DOM**: All elements with 7 selector strategies each
+- **Network**: All requests, responses, and complete response bodies
+- **Console**: All logs, errors, and smart error correlation
+- **Performance**: Load times, memory usage, with reliability indicators
+- **Visual**: Screenshots with pixel-perfect comparisons
+- **Fonts**: Loading status, performance, and usage analysis
+- **Animations**: Active animations and transitions tracking
+- **Resources**: Complete resource loading analysis
+- **Storage**: localStorage, sessionStorage, cookies, IndexedDB state
+
+### **🔄 Rapid Iteration Support**
+- **Hot Reload Intelligence** with framework auto-detection (Vite, Webpack, Next.js, Parcel, Laravel Mix)
+- **Mockup comparison** with enhanced DOM and CSS analysis
+- **Hot reload integration** for instant, perfectly-timed CSS testing
+- **Persistent sessions** that survive code changes
+- **Universal framework support** (React, Vue, PHP, Perl, anything)
+
+### **🤖 AI-First Design**
+All data structured for AI consumption:
+- Consistent JSON format across all features
+- **Multi-selector element identification** for robust automation
+- **Accessibility-aware** element analysis
+- Error correlation with **smart screenshot deduplication**
+- Performance insights with **reliability metadata**
+- **HMR event correlation** for CSS change tracking
+
+## 🚀 Quick Start
+
+```bash
+# Install CursorFlow
+pip install cursorflow
+
+# Test with complete intelligence
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/dashboard"},
+  {"wait_for": "#main-content"},
+  {"screenshot": "dashboard-loaded"}
+]'
+
+# HMR-powered CSS iteration
+cursorflow iterate-mockup https://mockup.com/design \
+  --base-url http://localhost:5173 \
+  --css-improvements '[
+    {"name": "fix-spacing", "css": ".container { gap: 2rem; }"}
+  ]'
+```
+
+## 💻 Usage Examples
+
+### **Hot Reload Intelligence**
+```python
+from cursorflow import CursorFlow
+
+async def hmr_workflow():
+    flow = CursorFlow("http://localhost:5173", {"headless": False})
+    
+    # Start HMR monitoring (auto-detects Vite/Webpack/Next.js)
+    await flow.browser.start_hmr_monitoring()
+    
+    # Take baseline
+    await flow.execute_and_collect([
+        {"navigate": "/app"},
+        {"screenshot": "baseline"}
+    ])
+    
+    # Wait for CSS changes with perfect timing
+    hmr_event = await flow.browser.wait_for_css_update()
+    print(f"🔥 {hmr_event['framework']} CSS update detected!")
+    
+    # Capture immediately after change
+    await flow.execute_and_collect([
+        {"screenshot": "updated"}
+    ])
+```
+
+### **Advanced Element Analysis**
+```python
+# Get comprehensive element data
+results = await flow.execute_and_collect([
+    {"navigate": "/form"},
+    {"screenshot": "form-analysis"}
+])
+
+# Access enhanced element data
+for element in results['artifacts']['screenshots'][0]['dom_analysis']['elements']:
+    print(f"Element: {element['selector']}")
+    print(f"  7 Selectors: {list(element['selectors'].keys())}")
+    print(f"  Accessible: {element['accessibility']['role']}")
+    print(f"  Interactive: {element['accessibility']['interactive']}")
+    print(f"  Visible: {element['visual_context']['visibility']['is_visible']}")
+```
+
+### **Comprehensive Page Intelligence**
+```python
+# Get complete page analysis
+screenshot = results['artifacts']['screenshots'][0]
+
+# Complete Intelligence
+print(f"Fonts loaded: {screenshot['font_status']['loadedFonts']}")
+print(f"Animations running: {screenshot['animation_status']['runningAnimations']}")  
+print(f"Resources: {screenshot['resource_status']['totalResources']}")
+print(f"Storage items: {screenshot['storage_status']['localStorage']['itemCount']}")
+```
+
+### **Smart Error Diagnostics**
+```python
+# Enhanced error context with deduplication
+error_context = await flow.browser.capture_interaction_error_context(
+    action_description="Submit form",
+    error_details={"type": "validation_error"}
+)
+
+print(f"Screenshot: {error_context['screenshot_info']['path']}")
+print(f"Reused: {error_context['screenshot_info']['is_reused']}")  # Smart deduplication
+print(f"Context: {len(error_context['recent_actions'])} recent actions")
+```
+
+## 🔧 CLI Commands
+
+### **Universal Testing with Complete Intelligence**
+```bash
+# Simple page test with full intelligence
+cursorflow test --base-url http://localhost:3000 --path "/dashboard"
+
+# Complex interaction test
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#email", "value": "test@example.com"}},
+  {"click": "#login-btn"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "logged-in"}
+]'
+```
+
+### **HMR-Powered CSS Iteration**
+```bash
+# Perfect CSS iteration with HMR intelligence
+cursorflow iterate-mockup https://mockup.com/design \
+  --base-url http://localhost:5173 \
+  --css-improvements '[
+    {"name": "improve-spacing", "css": ".container { gap: 2rem; }"},
+    {"name": "enhance-colors", "css": ".button { background: #007bff; }"}
+  ]'
+```
+
+### **Enhanced Design Comparison**
+```bash
+# Compare with comprehensive intelligence
+cursorflow compare-mockup https://mockup.com/design \
+  --base-url http://localhost:3000 \
+  --mockup-actions '[{"navigate": "/"}]' \
+  --implementation-actions '[{"navigate": "/dashboard"}]'
+```
+
+## 🧠 AI Integration
+
+### **Cursor Rules (Auto-Install)**
+```bash
+# Install AI assistance rules
+cursorflow install-rules
+```
+
+CursorFlow includes comprehensive rules that teach Cursor:
+- **When to use HMR intelligence** for CSS iteration
+- **How to analyze multi-selector element data**
+- **Best practices for comprehensive page analysis**
+- **Error debugging with smart context collection**
+
+### **Structured Data for AI**
+Every CursorFlow operation returns **perfectly structured JSON** optimized for AI analysis:
+
+```json
+{
+  "artifacts": {
+    "screenshots": [{
+      "path": ".cursorflow/artifacts/screenshots/dashboard_123.png",
+      "dom_analysis": {
+        "elements": [...],  // 7 selectors + accessibility per element
+        "pageStructure": {...},  // Enhanced page analysis
+        "analysisVersion": "2.0"  // Version tracking
+      },
+      "font_status": {...},      // Font loading intelligence
+      "animation_status": {...}, // Animation tracking
+      "resource_status": {...},  // Resource analysis
+      "storage_status": {...},   // Storage state
+      "hmr_status": {...}        // HMR event data
+    }]
+  }
+}
+```
+
+## 🌟 Framework Support
+
+**HMR Auto-Detection:**
+- ✅ **Vite** (port 5173, WebSocket `/__vite_hmr`)
+- ✅ **Webpack Dev Server** (port 3000, WebSocket `/sockjs-node`)
+- ✅ **Next.js** (port 3000, WebSocket `/_next/webpack-hmr`)
+- ✅ **Parcel** (port 1234, WebSocket `/hmr`)
+- ✅ **Laravel Mix** (port 3000, WebSocket `/browser-sync/socket.io`)
+
+**Universal Compatibility:**
+- Works with **any web application** regardless of framework
+- **Framework-agnostic** core operations
+- **Smart adaptation** to different development environments
+
+## 📖 Documentation
+
+- **[Complete User Manual](docs/USER_MANUAL.md)** - Full feature guide
+- **[Examples](examples/)** - Practical usage examples
+- **[API Reference](docs/api/)** - Complete Python API documentation
+
+## 🚀 Why CursorFlow?
+
+### **For Developers:**
+- **Faster CSS iteration** with HMR precision timing
+- **Complete element intelligence** with multi-selector strategies
+- **Full page visibility** with comprehensive analysis
+- **Smart error debugging** with rich context collection
+
+### **For AI Agents:**
+- **Perfect structured data** for intelligent decision making
+- **Multi-selector reliability** for robust automation
+- **Accessibility awareness** for inclusive development
+- **HMR correlation** for understanding change impact
+
+### **For Teams:**
+- **Framework agnostic** - works with any web technology
+- **Production ready** - handles real-world complexity
+- **Comprehensive testing** - covers all aspects of web apps
+- **AI-first design** - built for autonomous development
+
+---
+
+**Complete page intelligence for AI-driven development with CursorFlow**
+
+*Hot reload precision • Advanced element analysis • Smart error diagnostics • Comprehensive page intelligence*