broswer-automation/BACKGROUND_WINDOW_CHANGES.md

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:

node test-background-navigation.js

Expected results:

• Window created with ID
• Dimensions: 1280x720
• Minimized: true
• Automation Ready: true

Technical Implementation Details

Window Creation Parameters

{
  url: url,
  width: 1280,
  height: 720,
  focused: false,
  state: chrome.windows.WindowState.NORMAL,
  type: 'normal',
  left: 0,
  top: 0
}

Minimization Process

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