cursorflow 2.2.9__tar.gz → 2.3.1__tar.gz

{cursorflow-2.2.9 → cursorflow-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.2.9
+Version: 2.3.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
@@ -386,6 +386,24 @@ cursorflow iterate-mockup https://mockup.com/design \
   ]'
 ```
 
+### **Element Analysis & CSS Debugging**
+```bash
+# Comprehensive element inspection with full CSS analysis
+cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
+
+# Show all computed CSS properties
+cursorflow inspect -u http://localhost:3000 -s ".card" --verbose
+
+# Quick dimension check (surgical precision)
+cursorflow measure --base-url http://localhost:3000 --selector "#panel"
+
+# Measure multiple elements at once
+cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2"
+
+# Verify CSS changes with all properties
+cursorflow measure -u http://localhost:3000 -s ".button" --verbose
+```
+
 ### **AI Integration**
 ```bash
 # Install Cursor AI rules

{cursorflow-2.2.9 → cursorflow-2.3.1}/README.md

@@ -341,6 +341,24 @@ cursorflow iterate-mockup https://mockup.com/design \
   ]'
 ```
 
+### **Element Analysis & CSS Debugging**
+```bash
+# Comprehensive element inspection with full CSS analysis
+cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
+
+# Show all computed CSS properties
+cursorflow inspect -u http://localhost:3000 -s ".card" --verbose
+
+# Quick dimension check (surgical precision)
+cursorflow measure --base-url http://localhost:3000 --selector "#panel"
+
+# Measure multiple elements at once
+cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2"
+
+# Verify CSS changes with all properties
+cursorflow measure -u http://localhost:3000 -s ".button" --verbose
+```
+
 ### **AI Integration**
 ```bash
 # Install Cursor AI rules

{cursorflow-2.2.9 → cursorflow-2.3.1}/cursorflow/cli.py

@@ -191,12 +191,22 @@ def test(base_url, path, actions, output, logs, config, verbose, headless, timeo
             console.print(f"[red]❌ Failed to load actions: {e}[/red]")
             return
     elif path:
-        # Simple path navigation
-        test_actions = [
-            {"navigate": path},
-            {"wait_for_selector": "body"},
-            {"screenshot": "page_loaded"}
-        ]
+        # Simple path navigation with optional wait conditions
+        test_actions = [{"navigate": path}]
+        
+        # Add wait conditions if specified
+        if wait:
+            test_actions.append({"wait_for_timeout": int(wait * 1000)})
+        if wait_for:
+            test_actions.append({"wait_for_selector": wait_for})
+        if wait_for_network_idle:
+            test_actions.append({"wait_for_load_state": "networkidle"})
+        
+        # Default wait if none specified
+        if not any([wait, wait_for, wait_for_network_idle]):
+            test_actions.append({"wait_for_selector": "body"})
+        
+        test_actions.append({"screenshot": "page_loaded"})
         console.print(f"📋 Using simple path navigation to [cyan]{path}[/cyan]")
     else:
         # Default actions - just navigate to root and screenshot
@@ -766,14 +776,21 @@ def sessions(subcommand, name):
 
 @main.command()
 @click.option('--base-url', '-u', required=True)
+@click.option('--path', '-p', default='/', help='Path to navigate to')
 @click.option('--selector', '-s', required=True)
-def inspect(base_url, selector):
+@click.option('--verbose', '-v', is_flag=True, help='Show all computed styles')
+def inspect(base_url, path, selector, verbose):
     """
-    Quick element inspection without full test
+    Comprehensive element inspection with full data capture
+    
+    Shows computed CSS, dimensions, selectors, and visual context for matching elements.
+    Perfect for CSS debugging and element analysis.
     
-    Phase 3.5: Inspect selector and show matching elements
+    Examples:
+      cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
+      cursorflow inspect -u http://localhost:3000 -p /dashboard -s ".card"
     """
-    console.print(f"🔍 Inspecting selector: [cyan]{selector}[/cyan]")
+    console.print(f"🔍 Inspecting selector: [cyan]{selector}[/cyan] at [blue]{path}[/blue]")
     
     try:
         from .core.cursorflow import CursorFlow
@@ -783,18 +800,268 @@ def inspect(base_url, selector):
             browser_config={'headless': True}
         )
         
-        # Quick inspection
+        # Comprehensive inspection with full data capture
+        console.print("📸 Capturing comprehensive page data...")
         results = asyncio.run(flow.execute_and_collect([
-            {"navigate": "/"},
-            {"evaluate": f"""
-                document.querySelectorAll('{selector}').length
-            """}
+            {"navigate": path},
+            {"wait_for_selector": "body"},
+            {"screenshot": "inspection"}
         ]))
         
-        console.print(f"✅ Found matches for: {selector}")
+        # Extract element data from comprehensive analysis
+        comprehensive_data = results.get('comprehensive_data', {})
+        dom_analysis = comprehensive_data.get('dom_analysis', {})
+        elements = dom_analysis.get('elements', [])
+        
+        # Find matching elements
+        matching_elements = []
+        for element in elements:
+            # Check multiple selector strategies
+            if _element_matches_selector(element, selector):
+                matching_elements.append(element)
+        
+        if not matching_elements:
+            console.print(f"[yellow]⚠️  No elements found matching: {selector}[/yellow]")
+            console.print(f"💡 Total elements captured: {len(elements)}")
+            
+            # Debug: Show some element IDs/classes to help user
+            if elements and verbose:
+                console.print(f"\n🔍 Debug - Sample of captured elements:")
+                for elem in elements[:10]:
+                    elem_id = elem.get('id', '')
+                    elem_classes = elem.get('className', '')
+                    elem_tag = elem.get('tagName', '')
+                    if elem_id or elem_classes:
+                        console.print(f"   {elem_tag}#{elem_id or '(no-id)'}.{elem_classes or '(no-classes)'}")
+            
+            return
+        
+        console.print(f"\n✅ Found [bold]{len(matching_elements)}[/bold] matching element(s)\n")
+        
+        # Display detailed information for each match
+        for idx, element in enumerate(matching_elements[:5], 1):  # Show first 5
+            console.print(f"[bold cyan]═══ Element {idx}/{len(matching_elements)} ═══[/bold cyan]")
+            
+            # Basic info
+            tag = element.get('tagName', 'unknown')
+            elem_id = element.get('id', '')
+            classes = element.get('className', '')
+            
+            console.print(f"Tag:       [yellow]{tag}[/yellow]")
+            if elem_id:
+                console.print(f"ID:        [green]#{elem_id}[/green]")
+            if classes:
+                console.print(f"Classes:   [blue].{classes}[/blue]")
+            
+            # Selectors
+            unique_selector = element.get('uniqueSelector', 'N/A')
+            console.print(f"Unique:    [cyan]{unique_selector}[/cyan]")
+            
+            # Dimensions
+            bbox = element.get('boundingBox', {})
+            if bbox:
+                console.print(f"\n📐 Dimensions:")
+                console.print(f"   Position:  x={bbox.get('x', 0):.0f}, y={bbox.get('y', 0):.0f}")
+                console.print(f"   Size:      {bbox.get('width', 0):.0f}w × {bbox.get('height', 0):.0f}h")
+            
+            # Computed styles (key CSS properties)
+            computed = element.get('computedStyles', {})
+            if computed:
+                console.print(f"\n🎨 Key CSS Properties:")
+                
+                # Layout
+                display = computed.get('display', 'N/A')
+                position = computed.get('position', 'N/A')
+                console.print(f"   display:   {display}")
+                console.print(f"   position:  {position}")
+                
+                # Flexbox
+                if 'flex' in computed:
+                    console.print(f"   flex:      {computed.get('flex', 'N/A')}")
+                if 'flexBasis' in computed:
+                    console.print(f"   flex-basis: {computed.get('flexBasis', 'N/A')}")
+                
+                # Dimensions
+                width = computed.get('width', 'N/A')
+                height = computed.get('height', 'N/A')
+                console.print(f"   width:     {width}")
+                console.print(f"   height:    {height}")
+                
+                # Spacing
+                margin = computed.get('margin', 'N/A')
+                padding = computed.get('padding', 'N/A')
+                if margin != 'N/A':
+                    console.print(f"   margin:    {margin}")
+                if padding != 'N/A':
+                    console.print(f"   padding:   {padding}")
+                
+                # Show all styles in verbose mode
+                if verbose:
+                    console.print(f"\n📋 All Computed Styles:")
+                    for prop, value in sorted(computed.items())[:30]:  # Limit to 30
+                        console.print(f"   {prop}: {value}")
+            
+            # Accessibility info
+            accessibility = element.get('accessibility', {})
+            if accessibility:
+                role = accessibility.get('role', 'N/A')
+                is_interactive = accessibility.get('isInteractive', False)
+                console.print(f"\n♿ Accessibility:")
+                console.print(f"   Role:         {role}")
+                console.print(f"   Interactive:  {'✅' if is_interactive else '❌'}")
+            
+            # Visual context
+            visual = element.get('visual_context', {})
+            if visual:
+                console.print(f"\n👁️  Visual Context:")
+                if visual.get('is_visible'):
+                    console.print(f"   Visibility:   ✅ Visible")
+                else:
+                    console.print(f"   Visibility:   ❌ Hidden")
+                if visual.get('z_index'):
+                    console.print(f"   Z-index:      {visual.get('z_index')}")
+            
+            console.print("")  # Spacing between elements
+        
+        if len(matching_elements) > 5:
+            console.print(f"[dim]... and {len(matching_elements) - 5} more elements[/dim]")
+        
+        # Show screenshot location
+        screenshots = results.get('artifacts', {}).get('screenshots', [])
+        if screenshots:
+            screenshot_path = screenshots[0]
+            console.print(f"\n📸 Screenshot saved: [cyan]{screenshot_path}[/cyan]")
         
     except Exception as e:
         console.print(f"[red]❌ Inspection failed: {e}[/red]")
+        import traceback
+        console.print(traceback.format_exc())
+
+def _element_matches_selector(element: Dict, selector: str) -> bool:
+    """Check if element matches the given selector"""
+    
+    # ID selector
+    if selector.startswith('#'):
+        target_id = selector[1:]
+        return element.get('id') == target_id
+    
+    # Class selector
+    if selector.startswith('.'):
+        target_class = selector[1:]
+        classes = element.get('className') or ''  # Handle None from JSON
+        if not isinstance(classes, str):
+            return False
+        return target_class in classes.split() if classes else False
+    
+    # Tag selector
+    tag = element.get('tagName', '').lower()
+    selector_lower = selector.lower()
+    if tag == selector_lower:
+        return True
+    
+    # Check unique selector contains the target
+    unique_selector = element.get('uniqueSelector', '').lower()
+    if selector_lower in unique_selector:
+        return True
+    
+    return False
+
+@main.command()
+@click.option('--base-url', '-u', required=True)
+@click.option('--path', '-p', default='/', help='Path to navigate to')
+@click.option('--selector', '-s', required=True, multiple=True, help='Selector(s) to measure (can specify multiple)')
+@click.option('--verbose', '-v', is_flag=True, help='Show all computed CSS properties')
+def measure(base_url, path, selector, verbose):
+    """
+    Surgical element dimension measurement
+    
+    Quickly measure width, height, and position of elements.
+    Use --verbose to see all computed CSS properties.
+    
+    Examples:
+      cursorflow measure --base-url http://localhost:3000 --selector "#messages-panel"
+      cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2" --verbose
+    """
+    console.print(f"📏 Measuring element dimensions at [blue]{path}[/blue]\n")
+    
+    try:
+        from .core.cursorflow import CursorFlow
+        flow = CursorFlow(
+            base_url=base_url,
+            log_config={'source': 'local', 'paths': []},
+            browser_config={'headless': True}
+        )
+        
+        # Use comprehensive data capture but display only dimensions
+        selectors_list = list(selector)
+        
+        # Execute with screenshot to get comprehensive data
+        results = asyncio.run(flow.execute_and_collect([
+            {"navigate": path},
+            {"wait_for_selector": "body"},
+            {"screenshot": "measurement"}
+        ]))
+        
+        # Extract element data from comprehensive analysis
+        comprehensive_data = results.get('comprehensive_data', {})
+        dom_analysis = comprehensive_data.get('dom_analysis', {})
+        elements = dom_analysis.get('elements', [])
+        
+        # For each selector, find matching elements and display dimensions
+        for sel in selectors_list:
+            matching_elements = []
+            for element in elements:
+                if _element_matches_selector(element, sel):
+                    matching_elements.append(element)
+            
+            if not matching_elements:
+                console.print(f"[yellow]⚠️  {sel}: No elements found[/yellow]\n")
+                continue
+            
+            for idx, element in enumerate(matching_elements):
+                if len(matching_elements) > 1:
+                    console.print(f"[bold cyan]{sel}[/bold cyan] [dim](element {idx + 1}/{len(matching_elements)})[/dim]")
+                else:
+                    console.print(f"[bold cyan]{sel}[/bold cyan]")
+                
+                # Dimensions - check both camelCase and snake_case
+                bbox = element.get('boundingBox') or element.get('visual_context', {}).get('bounding_box')
+                if bbox:
+                    width = bbox.get('width', 0)
+                    height = bbox.get('height', 0)
+                    x = bbox.get('x', 0)
+                    y = bbox.get('y', 0)
+                    console.print(f"  📐 Rendered:  {width:.0f}w × {height:.0f}h")
+                    console.print(f"  📍 Position:  x={x:.0f}, y={y:.0f}")
+                
+                # Computed styles
+                computed = element.get('computedStyles', {})
+                if computed:
+                    if verbose:
+                        # Show ALL computed CSS properties
+                        console.print(f"  🎨 Computed CSS (all properties):")
+                        for prop, value in sorted(computed.items()):
+                            console.print(f"     {prop}: {value}")
+                    else:
+                        # Show key CSS properties only
+                        console.print(f"  🎨 Display:   {computed.get('display', 'N/A')}")
+                        console.print(f"  📦 CSS Width: {computed.get('width', 'N/A')}")
+                        
+                        if computed.get('flex'):
+                            console.print(f"  🔧 Flex:      {computed.get('flex')}")
+                        if computed.get('flexBasis') and computed.get('flexBasis') != 'auto':
+                            console.print(f"  📏 Flex Base: {computed.get('flexBasis')}")
+                        
+                        console.print(f"  💡 Use --verbose to see all {len(computed)} CSS properties")
+                
+                console.print("")
+        
+        console.print("✅ Measurement complete")
+        
+    except Exception as e:
+        console.print(f"[red]❌ Measurement failed: {e}[/red]")
+        import traceback
+        console.print(traceback.format_exc())
 
 @main.command()
 @click.option('--base-url', '-u', required=True)

{cursorflow-2.2.9 → cursorflow-2.3.1}/cursorflow/core/browser_controller.py

@@ -1380,7 +1380,7 @@ class BrowserController:
                             animationData.transition_details.push({
                                 element_selector: element.tagName.toLowerCase() + 
                                     (element.id ? '#' + element.id : '') +
-                                    (element.className ? '.' + element.className.split(' ').join('.') : ''),
+                                    (element.className && typeof element.className === 'string' ? '.' + element.className.split(' ').join('.') : ''),
                                 transition_property: transitionProperty,
                                 duration: computedStyle.transitionDuration,
                                 delay: computedStyle.transitionDelay,

{cursorflow-2.2.9 → cursorflow-2.3.1}/cursorflow/rules/cursorflow-usage.mdc

@@ -255,8 +255,9 @@ cursorflow test --base-url http://localhost:3000 --actions '[
 ### **All CLI Commands:**
 ```bash
 cursorflow test              # Test UI with comprehensive data capture
+cursorflow inspect           # Comprehensive element analysis (CSS, dimensions, accessibility)
+cursorflow measure           # Surgical dimension checking (quick CSS verification)
 cursorflow rerun             # Re-run last test
-cursorflow inspect           # Quick element inspection
 cursorflow count             # Count matching elements
 cursorflow timeline          # View event timeline
 cursorflow sessions          # Manage saved sessions
@@ -376,6 +377,54 @@ cursorflow test \
   ]'
 ```
 
+### CSS Debugging & Element Analysis
+```bash
+# Comprehensive element inspection (full CSS analysis)
+cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
+
+# Output includes:
+# - Computed CSS (all properties: display, flex, width, etc.)
+# - Rendered dimensions (actual width × height on screen)
+# - Position (x, y coordinates)
+# - Unique selector for targeting
+# - Accessibility info (role, interactive state)
+# - Visual context (visibility, z-index)
+# - Screenshot saved to artifacts
+
+# Show ALL computed CSS properties (verbose mode)
+cursorflow inspect -u http://localhost:3000 -p /dashboard -s ".card" --verbose
+
+# Quick dimension check (surgical precision)
+cursorflow measure --base-url http://localhost:3000 --selector "#panel"
+
+# Measure multiple elements at once
+cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2"
+
+# Verify CSS changes with all properties
+cursorflow measure -u http://localhost:3000 -s ".button" --verbose
+```
+
+**When to use inspect vs measure:**
+- **`inspect`**: Deep CSS debugging, complex layout issues, need accessibility info
+- **`measure`**: Quick dimension verification, CSS change validation, multiple elements
+
+**Workflow example:**
+```bash
+# 1. Quick check dimensions
+cursorflow measure -u http://localhost:3000 -s "#panel"
+# Output: 260w × 900h
+
+# 2. Dimensions seem wrong, get full analysis
+cursorflow inspect -u http://localhost:3000 -s "#panel" --verbose
+# Output: Full CSS, flex: 1 1 0%, flex-basis: 260px, etc.
+
+# 3. Make CSS changes based on insights
+
+# 4. Verify fix
+cursorflow measure -u http://localhost:3000 -s "#panel"
+# Output: 532w × 900h ✅
+```
+
 ## Analyzing Results
 
 ### **Hot Reload CSS Iteration Results** 

{cursorflow-2.2.9 → cursorflow-2.3.1}/docs/user/USAGE_GUIDE.md

@@ -181,9 +181,32 @@ cursorflow rerun
 cursorflow rerun --click ".other-element"
 ```
 
-**Inspect elements:**
+**Inspect elements (comprehensive data):**
+```bash
+# Inspect with full element analysis
+cursorflow inspect --base-url http://localhost:3000 --selector "#messages-panel"
+
+# Inspect with custom path
+cursorflow inspect -u http://localhost:3000 -p /dashboard -s ".card"
+
+# Show all computed CSS properties
+cursorflow inspect -u http://localhost:3000 -s ".button" --verbose
+```
+
+**Measure element dimensions (surgical precision):**
+```bash
+# Quick dimension check
+cursorflow measure --base-url http://localhost:3000 --selector "#panel"
+
+# Multiple elements at once
+cursorflow measure -u http://localhost:3000 -s "#panel1" -s "#panel2"
+
+# Show all CSS properties
+cursorflow measure -u http://localhost:3000 -s ".card" --verbose
+```
+
+**Count elements:**
 ```bash
-cursorflow inspect --base-url http://localhost:3000 --selector ".message-item"
 cursorflow count --base-url http://localhost:3000 --selector ".message-item"
 ```
 
@@ -192,6 +215,113 @@ cursorflow count --base-url http://localhost:3000 --selector ".message-item"
 cursorflow timeline --session session_12345
 ```
 
+### **Element Analysis Commands**
+
+CursorFlow provides powerful element inspection tools for CSS debugging and layout analysis.
+
+#### **`inspect` - Comprehensive Element Analysis**
+
+The `inspect` command captures full page data and displays detailed element information:
+
+**What you get:**
+- **Computed CSS** - All browser-computed styles (display, position, flex, dimensions, etc.)
+- **Dimensions** - Rendered width, height, and position
+- **Selectors** - Unique CSS selector for targeting
+- **Accessibility** - Role, interactive state, ARIA attributes
+- **Visual Context** - Visibility, z-index, viewport position
+- **Screenshot** - Visual reference saved to artifacts
+
+**Example output:**
+```
+═══ Element 1/1 ═══
+Tag:       div
+ID:        #messages-panel
+Classes:   .console-panel.message-list-panel
+
+📐 Dimensions:
+   Position:  x=320, y=73
+   Size:      532w × 927h
+
+🎨 Key CSS Properties:
+   display:   flex
+   flex:      1 1 0%
+   flex-basis: 260px
+   width:     532px
+
+♿ Accessibility:
+   Role:         None
+   Interactive:  ❌
+
+👁️  Visual Context:
+   Visibility:   ✅ Visible
+
+📸 Screenshot saved: .cursorflow/artifacts/screenshots/inspection.png
+```
+
+**Use cases:**
+- Debug CSS layout issues
+- Verify flex/grid calculations
+- Check computed vs authored styles
+- Find optimal selectors for automation
+- Analyze element visibility and positioning
+
+#### **`measure` - Surgical Dimension Checking**
+
+The `measure` command provides quick dimension and CSS checks without verbose output:
+
+**What you get:**
+- **Rendered dimensions** - Actual width × height on screen
+- **Position** - x, y coordinates
+- **Key CSS** - display, width, flex properties
+- **Multiple elements** - Measure several at once
+- **All CSS (--verbose)** - Complete computed styles (76+ properties)
+
+**Example output:**
+```
+h1
+  📐 Rendered:  600w × 38h
+  📍 Position:  x=420, y=133
+  🎨 Display:   block
+  📦 CSS Width: 600px
+  🔧 Flex:      0 1 auto
+  💡 Use --verbose to see all 76 CSS properties
+```
+
+**Use cases:**
+- Verify CSS changes took effect
+- Check flex layout calculations
+- Compare dimensions across breakpoints
+- Quick dimension reference during development
+- Validate responsive behavior
+
+#### **Comparison: inspect vs measure**
+
+| Feature | `inspect` | `measure` |
+|---------|-----------|-----------|
+| **Purpose** | Comprehensive analysis | Quick dimension check |
+| **Output** | Detailed, multi-section | Concise, focused |
+| **Screenshot** | Always included | Captured but not shown |
+| **Use when** | Debugging complex CSS | Verifying dimensions |
+| **Speed** | ~3 seconds | ~2 seconds |
+| **Multiple elements** | One at a time | Multiple with `-s` flags |
+
+**Workflow example:**
+```bash
+# 1. Use measure for quick check
+cursorflow measure -u http://localhost:3000 -s "#panel"
+# Output: 260w × 900h
+
+# 2. If dimensions seem wrong, use inspect for full analysis
+cursorflow inspect -u http://localhost:3000 -s "#panel" --verbose
+# Output: Full CSS, accessibility, visual context, screenshot
+
+# 3. Make CSS changes based on insights
+
+# 4. Verify with measure again
+cursorflow measure -u http://localhost:3000 -s "#panel"
+# Output: 532w × 900h ✅ Fixed!
+```
+
 ### **Artifact Management**
 
 CursorFlow generates screenshots, traces, and session data. Clean up regularly:

{cursorflow-2.2.9 → cursorflow-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.2.9"
+version = "2.3.1"
 description = "🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis"
 authors = [
     {name = "GeekWarrior Development", email = "rbush@cooltheory.com"}
@@ -72,6 +72,6 @@ line-length = 88
 target-version = ['py38']
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "2.3.1"
 warn_return_any = true
 warn_unused_configs = true