@sashbot/uibridge/documentation/simple-example.md

🤖 AI-friendly live session automation with REAL screenshot backgrounds (no transparency issues!) - control your EXISTING browser with visual debug panel. Perfect for AI agents!

# Simple Example: Before vs After v1.3.0

## ❌ Before v1.3.0 (Complex & Error-Prone)

```javascript
// OLD WAY - Required manual polling implementation
onMount(async () => {
  if (!browser) return;
  
  try {
    const { default: UIBridge } = await import('@sashbot/uibridge');
    uibridge = new UIBridge({ 
      debug: true,
      defaultScreenshotConfig: {
        autoSave: true,
        folder: 'ai-screenshots',
        timestamp: true,
        includeMetadata: true
      }
    });
    await uibridge.init();
    
    // Make UIBridge globally available for REST API commands
    window.uibridge = uibridge;
    
    console.log('✅ UIBridge initialized and ready for automation');
    
    // 😩 Manual polling required - users had to implement this
    pollForCommands();
    
  } catch (error) {
    console.error('❌ Failed to initialize UIBridge:', error);
  }
});

// 30+ lines of manual polling code users had to write
async function pollForCommands() {
  if (!browser) return;
  
  try {
    const response = await fetch('http://localhost:3001/pending-commands');
    const data = await response.json();
    
    if (data.success && data.commands.length > 0) {
      for (const command of data.commands) {
        await executeCommand(command);
      }
    }
  } catch (error) {
    // Server might not be running yet, that's ok
  }
  
  // Poll every 500ms for new commands
  setTimeout(pollForCommands, 500);
}

// 20+ more lines of manual execution logic
async function executeCommand(commandData) {
  if (!uibridge) return;
  
  const { id, command, selector, options } = commandData;
  
  try {
    let result;
    
    if (command === 'click') {
      result = await uibridge.execute('click', selector, options);
    } else if (command === 'screenshot') {
      result = await uibridge.execute('screenshot', options);
    } else {
      result = await uibridge.execute(command, selector, options);
    }
    
    // Send result back to server
    await fetch('http://localhost:3001/command-result', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        commandId: id,
        result: result
      })
    });
    
    console.log(`✅ Command ${command} executed successfully`, result);
    
  } catch (error) {
    console.error(`❌ Command ${command} failed:`, error);
    
    // Send error back to server
    await fetch('http://localhost:3001/command-result', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        commandId: id,
        error: error.message
      })
    });
  }
}
```

**Problems with the old way:**
- 🤯 **50+ lines** of boilerplate code required
- 🐛 **Error-prone** - easy to make mistakes in polling logic
- 📚 **Complex setup** - users needed to understand the architecture
- ⚡ **Inconsistent** - every project implemented it differently
- 🔄 **Manual maintenance** - updates required code changes

---

## ✅ After v1.3.0 (Simple & Automatic)

```javascript
// NEW WAY - Built-in remote control
onMount(async () => {
  if (!browser) return;
  
  try {
    const { default: UIBridge } = await import('@sashbot/uibridge');
    
    // 🎯 This is ALL you need now!
    uibridge = new UIBridge({ 
      enableRemoteControl: true,  // Auto-polling enabled
      debug: true,
      defaultScreenshotConfig: {
        autoSave: true,
        folder: 'ai-screenshots',
        timestamp: true,
        includeMetadata: true
      }
    });
    
    await uibridge.init();
    // 🤖 External automation now works automatically!
    
    console.log('✅ UIBridge initialized with remote control');
    console.log('🤖 External tools can now send commands automatically');
    
  } catch (error) {
    console.error('❌ Failed to initialize UIBridge:', error);
  }
});

// No more manual polling code needed!
// No more executeCommand function needed!
// UIBridge handles all of this internally now.
```

**Benefits of the new way:**
- ⚡ **5 lines vs 50+** - 90% reduction in code
- 🛡️ **Zero boilerplate** - UIBridge handles everything
- 🤖 **Automatic polling** - starts immediately when enabled
- 🔄 **Built-in error handling** - robust retry logic included
- 📡 **Optimized communication** - efficient server handshake
- 🎯 **Single config option** - `enableRemoteControl: true`

---

## External Automation (Same for Both Versions)

```powershell
# PowerShell automation - works with both old and new versions
$params = @{
    Uri = 'http://localhost:3002/execute'  # Port 3002 for api-server
    Method = 'POST'
    Headers = @{ 'Content-Type' = 'application/json' }
    Body = @{
        command = 'click'
        selector = '#submit-button'
    } | ConvertTo-Json
}
$response = Invoke-RestMethod @params
```

## Migration Guide

### Step 1: Update UIBridge
```bash
npm update @sashbot/uibridge  # Gets v1.3.0+
```

### Step 2: Replace Your Code
1. **Remove** all manual polling functions (`pollForCommands`, `executeCommand`)
2. **Add** `enableRemoteControl: true` to UIBridge config
3. **Delete** 40+ lines of manual polling code
4. **Enjoy** the simplicity!

### Step 3: Test
Your external automation tools should work exactly the same, but your web app code is now dramatically simpler.

---

## The Bottom Line

**Before**: 50+ lines of complex, error-prone code  
**After**: 1 configuration option

UIBridge v1.3.0 represents a **10x improvement** in developer experience while maintaining all the automation power that makes UIBridge essential for modern web development.