# Background Window Implementation for Chrome MCP Extension

## Overview

This document outlines the changes made to implement background window functionality for web browsing automation, allowing the LiveKit agent to work with web pages without interrupting the user's current browser session.

## Changes Made

### 1. Chrome Extension Default Behavior

**File: `app/chrome-extension/entrypoints/background/tools/browser/common.ts`**
- Changed default `backgroundPage` setting from `false` to `true`
- URLs now open in background windows by default instead of new tabs
- Background windows are created at 1280x720 pixels then minimized

### 2. Popup UI Updates

**File: `app/chrome-extension/entrypoints/popup/App.vue`**
- Updated default setting: `openUrlsInBackground` now defaults to `true`
- Updated UI text to reflect that background pages are now recommended
- Description now mentions "1280x720 minimized windows for better automation"

### 3. LiveKit Agent Navigation Updates

**File: `agent-livekit/mcp_chrome_client.py`**
- Updated `_navigate_mcp()` to use background windows with explicit parameters
- Updated `_go_to_google_mcp()` to use background windows
- Updated `_go_to_facebook_mcp()` to use background windows  
- Updated `_go_to_twitter_mcp()` to use background windows
- All navigation functions now specify:
  - `backgroundPage: True`
  - `width: 1280`
  - `height: 720`

**File: `agent-livekit/livekit_agent.py`**
- Updated `navigate_to_url()` function description to mention background windows
- Added new `open_url_in_background()` function for explicit background navigation
- Enhanced logging to indicate background window usage

## How Background Windows Work

1. **Window Creation**: Chrome creates a new window with specified dimensions (1280x720)
2. **Initial State**: Window starts in normal state with `focused: false`
3. **Minimization**: After 1 second, window is minimized using `chrome.windows.update()`
4. **Automation Access**: Minimized windows remain accessible to automation tools
5. **User Experience**: User's current browsing session is not interrupted

## Benefits

### For Users
- No interruption to current browsing session
- URLs open silently in background
- Cleaner browser experience during automation

### For Automation
- Consistent window dimensions (1280x720) for reliable automation
- Full DOM access even when minimized
- Better performance for web scraping and content extraction
- Reduced visual distractions during automated tasks

### For LiveKit Agent
- Can process web content without disrupting user
- Better suited for search result processing
- Improved web content extraction capabilities

## Configuration Options

Users can still control this behavior through:

1. **Extension Popup**: Toggle "Open URLs in background pages" setting
2. **API Parameters**: Explicitly set `backgroundPage: false` to use tabs instead
3. **Storage Settings**: Preference is saved in `chrome.storage.local`

## Testing

Use the existing test file `test-background-navigation.js` to verify functionality:

```bash
node test-background-navigation.js
```

Expected results:
- Window created with ID
- Dimensions: 1280x720
- Minimized: true
- Automation Ready: true

## Technical Implementation Details

### Window Creation Parameters
```javascript
{
  url: url,
  width: 1280,
  height: 720,
  focused: false,
  state: chrome.windows.WindowState.NORMAL,
  type: 'normal',
  left: 0,
  top: 0
}
```

### Minimization Process
```javascript
await chrome.windows.update(windowId, {
  state: chrome.windows.WindowState.MINIMIZED
});
```

## Compatibility

- Requires Chrome extension with `windows` permission
- Works with Chromium-based browsers
- Requires `chrome.windows.WindowState.MINIMIZED` API support
- Compatible with existing MCP tools and automation scripts

## Migration Notes

- Existing code will automatically use background windows due to new defaults
- No breaking changes to API
- Users can opt-out via extension settings if needed
- All existing automation tools remain compatible

## Future Enhancements

Potential improvements for future versions:
- Configurable default window dimensions
- Window grouping for better organization
- Automatic cleanup of unused background windows
- Enhanced window state management
