Metadata-Version: 2.4
Name: cursorflow
Version: 2.0.2
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*
