@myrialabs/clopen 0.0.4 → 0.0.6

package/backend/lib/preview/browser/browser-preview-service.ts

@@ -1,882 +1,882 @@
-import { EventEmitter } from 'events';
-import type { Page } from 'puppeteer-core';
-import { BrowserTabManager } from './browser-tab-manager.js';
-import { BrowserConsoleManager } from './browser-console-manager.js';
-import { BrowserInteractionHandler } from './browser-interaction-handler.js';
-import { BrowserNavigationTracker } from './browser-navigation-tracker.js';
-import { BrowserVideoCapture } from './browser-video-capture.js';
-import { BrowserDialogHandler } from './browser-dialog-handler.js';
-import { BrowserNativeUIHandler } from './browser-native-ui-handler.js';
-import { browserMcpControl } from './browser-mcp-control.js';
-import { ws } from '$backend/lib/utils/ws';
-import { debug } from '$shared/utils/logger';
-import type {
-	BrowserTab,
-	BrowserTabInfo,
-	BrowserConsoleMessage,
-	BrowserAutonomousAction,
-	DeviceSize,
-	Rotation,
-	BrowserDialogResponse,
-	BrowserSelectResponse,
-	BrowserContextMenuResponse,
-	BrowserContextMenuInfo
-} from './types';
-
-/**
- * Browser Preview Service
- *
- * Main orchestrator for browser preview functionality.
- * Tab-centric architecture - all operations work with tabs.
- *
- * Architecture:
- * - Tabs are the primary unit (no separate session concept)
- * - Each tab = isolated browser context + page
- * - Event-driven communication with frontend
- * - Manages all browser operations: streaming, interaction, console, etc.
- * - **PROJECT ISOLATION**: Each instance is isolated per project
- */
-export class BrowserPreviewService extends EventEmitter {
-	private tabManager: BrowserTabManager;
-	private consoleManager: BrowserConsoleManager;
-	private interactionHandler: BrowserInteractionHandler;
-	private navigationTracker: BrowserNavigationTracker;
-	private videoCapture: BrowserVideoCapture;
-	private dialogHandler: BrowserDialogHandler;
-	private nativeUIHandler: BrowserNativeUIHandler;
-
-	// Store context menu info for later action execution
-	private contextMenus = new Map<string, BrowserContextMenuInfo>();
-
-	// Project ID for isolation (REQUIRED)
-	private projectId: string;
-
-	constructor(projectId: string) {
-		super();
-
-		if (!projectId) {
-			throw new Error('projectId is required for BrowserPreviewService');
-		}
-
-		this.projectId = projectId;
-
-		// Initialize managers with projectId for isolation
-		this.tabManager = new BrowserTabManager(projectId);
-		this.consoleManager = new BrowserConsoleManager();
-		this.interactionHandler = new BrowserInteractionHandler();
-		this.navigationTracker = new BrowserNavigationTracker();
-		this.videoCapture = new BrowserVideoCapture();
-		this.dialogHandler = new BrowserDialogHandler();
-		this.nativeUIHandler = new BrowserNativeUIHandler();
-
-		// Forward events from handlers to main service
-		this.setupEventForwarding();
-	}
-
-	private setupEventForwarding() {
-		// Forward console events
-		this.consoleManager.on('console-message', (data) => {
-			this.emit('preview:browser-console-message', data);
-		});
-		this.consoleManager.on('console-clear', (data) => {
-			this.emit('preview:browser-console-clear', data);
-		});
-
-		// Forward interaction events (MCP cursor)
-		this.interactionHandler.on('cursor-position', (data) => {
-			this.emit('preview:browser-mcp-cursor-position', data);
-		});
-		this.interactionHandler.on('cursor-click', (data) => {
-			this.emit('preview:browser-mcp-cursor-click', data);
-		});
-		this.interactionHandler.on('test-completed', (data) => {
-			this.emit('preview:browser-mcp-test-completed', data);
-		});
-
-		// Forward navigation events and handle video streaming restart
-		this.navigationTracker.on('navigation', async (data) => {
-			this.emit('preview:browser-navigation', data);
-
-			// After navigation completes, restart video streaming for the tab
-			// This re-injects the peer script and restarts CDP screencast
-			const { sessionId } = data;
-			if (this.videoCapture.isStreaming(sessionId)) {
-				const tab = this.getTab(sessionId);
-				if (tab) {
-					// Small delay to ensure page is fully loaded
-					setTimeout(async () => {
-						try {
-							const success = await this.videoCapture.handleNavigation(sessionId, tab);
-							if (success) {
-								this.emit('preview:browser-navigation-streaming-ready', { sessionId });
-							}
-						} catch (error) {
-							// Silently fail - frontend will request refresh if needed
-						}
-					}, 100);
-				}
-			}
-		});
-
-		// Forward navigation loading events
-		this.navigationTracker.on('navigation-loading', (data) => {
-			this.emit('preview:browser-navigation-loading', data);
-		});
-
-		// Forward new window events
-		this.tabManager.on('new-window', (data) => {
-			this.emit('preview:browser-new-window', data);
-		});
-
-		// Forward tab events (already have correct event names from tab manager)
-		this.tabManager.on('preview:browser-tab-opened', (data) => {
-			this.emit('preview:browser-tab-opened', data);
-		});
-		this.tabManager.on('preview:browser-tab-closed', (data) => {
-			this.emit('preview:browser-tab-closed', data);
-		});
-		this.tabManager.on('preview:browser-tab-switched', (data) => {
-			this.emit('preview:browser-tab-switched', data);
-		});
-		this.tabManager.on('preview:browser-tab-navigated', (data) => {
-			this.emit('preview:browser-tab-navigated', data);
-		});
-
-		// Forward video capture events
-		this.videoCapture.on('ice-candidate', (data) => {
-			this.emit('preview:browser-webcodecs-ice-candidate', data);
-		});
-		this.videoCapture.on('connection-state', (data) => {
-			this.emit('preview:browser-webcodecs-connection-state', data);
-		});
-		this.videoCapture.on('cursor-change', (data) => {
-			this.emit('preview:browser-cursor-change', data);
-		});
-		this.videoCapture.on('navigation-streaming-ready', (data) => {
-			this.emit('preview:browser-navigation-streaming-ready', data);
-		});
-
-		// Forward dialog events
-		this.dialogHandler.on('dialog', (data) => {
-			this.emit('preview:browser-dialog', data);
-		});
-		this.dialogHandler.on('print', (data) => {
-			this.emit('preview:browser-print', data);
-		});
-
-		// Forward native UI events
-		this.nativeUIHandler.on('copy-to-clipboard', (data) => {
-			this.emit('preview:browser-copy-to-clipboard', data);
-		});
-		this.nativeUIHandler.on('open-url-new-tab', (data) => {
-			this.emit('preview:browser-open-url-new-tab', data);
-		});
-		this.nativeUIHandler.on('download-image', (data) => {
-			this.emit('preview:browser-download-image', data);
-		});
-		this.nativeUIHandler.on('copy-image-to-clipboard', (data) => {
-			this.emit('preview:browser-copy-image-to-clipboard', data);
-		});
-	}
-
-	/**
-	 * Get project ID for this service instance
-	 */
-	getProjectId(): string {
-		return this.projectId;
-	}
-
-	// ============================================================================
-	// Tab Management Methods
-	// ============================================================================
-
-	/**
-	 * Create a new tab with optional URL
-	 *
-	 * If URL is provided, navigate to it immediately.
-	 * If URL is not provided, create blank tab (about:blank).
-	 *
-	 * Default rotation depends on device size:
-	 * - Desktop/laptop: landscape
-	 * - Tablet/mobile: portrait
-	 */
-	async createTab(url?: string, deviceSize: DeviceSize = 'laptop', rotation?: Rotation): Promise<BrowserTab> {
-		// Use device-appropriate default rotation if not specified
-		const actualRotation = rotation || ((deviceSize === 'desktop' || deviceSize === 'laptop') ? 'landscape' : 'portrait');
-		// Pre-navigation setup callback for dialog bindings
-		const preNavigationSetup = async (page: Page) => {
-			// Note: We'll setup dialog bindings using tabId after tab is created
-		};
-
-		// Create tab
-		const tab = await this.tabManager.createTab(url, deviceSize, actualRotation, {
-			setActive: true,
-			preNavigationSetup
-		});
-
-		// Setup console and navigation tracking
-		await this.consoleManager.setupConsoleLogging(tab.id, tab.page, tab);
-		await this.navigationTracker.setupNavigationTracking(tab.id, tab.page, tab);
-
-		// Setup dialog bindings and handling
-		await this.dialogHandler.setupDialogBindings(tab.id, tab.page);
-		await this.dialogHandler.setupDialogHandling(tab.id, tab.page, tab);
-
-		return tab;
-	}
-
-	/**
-	 * Navigate tab to a new URL
-	 */
-	async navigateTab(tabId: string, url: string): Promise<string> {
-		const actualUrl = await this.tabManager.navigateTab(tabId, url);
-
-		// Mark navigation for frame deduplication
-		this.markNavigation(tabId, url);
-
-		return actualUrl;
-	}
-
-	/**
-	 * Close a tab and cleanup its resources
-	 */
-	async closeTab(tabId: string): Promise<{ success: boolean; newActiveTabId: string | null }> {
-		const tab = this.tabManager.getTab(tabId);
-		if (!tab) {
-			return { success: false, newActiveTabId: null };
-		}
-
-		// Stop WebCodecs streaming first
-		await this.stopWebCodecsStreaming(tabId);
-
-		// Clear cursor tracking for this tab
-		this.interactionHandler.clearSessionCursor(tabId);
-
-		// Clear dialogs for this tab
-		this.dialogHandler.clearSessionDialogs(tabId);
-
-		// Close the tab (this will cleanup context, page, etc.)
-		const result = await this.tabManager.closeTab(tabId);
-
-		// Emit tab closed event (for MCP control manager and other listeners)
-		this.emit('preview:browser-tab-destroyed', { tabId });
-
-		return result;
-	}
-
-	/**
-	 * Switch to a specific tab
-	 */
-	switchTab(tabId: string): boolean {
-		return this.tabManager.setActiveTab(tabId);
-	}
-
-	/**
-	 * Get a tab by ID
-	 */
-	getTab(tabId: string): BrowserTab | null {
-		return this.tabManager.getTab(tabId);
-	}
-
-	/**
-	 * Get the active tab
-	 */
-	getActiveTab(): BrowserTab | null {
-		return this.tabManager.getActiveTab();
-	}
-
-	/**
-	 * Get all tabs
-	 */
-	getAllTabs(): BrowserTab[] {
-		return this.tabManager.getAllTabs();
-	}
-
-	/**
-	 * Change viewport settings (device size and rotation) for an existing tab
-	 */
-	async setViewport(tabId: string, deviceSize: DeviceSize, rotation: Rotation): Promise<boolean> {
-		return await this.tabManager.setViewport(tabId, deviceSize, rotation);
-	}
-
-	/**
-	 * Get tab count
-	 */
-	getTabCount(): number {
-		return this.tabManager.getTabCount();
-	}
-
-	/**
-	 * Get tab info
-	 */
-	getTabInfo(tabId: string): BrowserTabInfo | null {
-		return this.tabManager.getTabInfo(tabId);
-	}
-
-	/**
-	 * Get all tabs info
-	 */
-	getAllTabsInfo(): BrowserTabInfo[] {
-		return this.tabManager.getAllTabsInfo();
-	}
-
-	/**
-	 * Get available tab IDs
-	 */
-	getAvailableTabIds(): string[] {
-		return this.tabManager.getAvailableTabIds();
-	}
-
-	/**
-	 * Get tabs status (for admin/debugging)
-	 */
-	getTabsStatus() {
-		return this.tabManager.getTabsStatus();
-	}
-
-	/**
-	 * Update tab title from URL
-	 */
-	updateTabTitleFromUrl(tabId: string, url: string): void {
-		this.tabManager.updateTabTitleFromUrl(tabId, url);
-	}
-
-	/**
-	 * Check if tab is valid
-	 */
-	isValidTab(tabId: string): boolean {
-		const tab = this.getTab(tabId);
-		return tab !== null && !tab.isDestroyed;
-	}
-
-	// ============================================================================
-	// WebCodecs Streaming Methods (optimized, ~20-40ms, lower bandwidth)
-	// ============================================================================
-	async startWebCodecsStreaming(tabId: string): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return false;
-		}
-		return await this.videoCapture.startStreaming(
-			tabId,
-			tab,
-			() => this.isValidTab(tabId)
-		);
-	}
-
-	async stopWebCodecsStreaming(tabId: string): Promise<void> {
-		const tab = this.getTab(tabId);
-		await this.videoCapture.stopStreaming(tabId, tab ?? undefined);
-	}
-
-	async updateWebCodecsScale(tabId: string, newScale: number): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return false;
-		}
-		return await this.videoCapture.updateScale(tabId, tab, newScale);
-	}
-
-	async updateWebCodecsViewport(tabId: string, width: number, height: number, newScale: number): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return false;
-		}
-		return await this.videoCapture.updateViewport(tabId, tab, width, height, newScale);
-	}
-
-	async getWebCodecsOffer(tabId: string): Promise<RTCSessionDescriptionInit | null> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return null;
-		}
-		return await this.videoCapture.createOffer(tabId, tab);
-	}
-
-	async handleWebCodecsAnswer(tabId: string, answer: RTCSessionDescriptionInit): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return false;
-		}
-		return await this.videoCapture.handleAnswer(tabId, tab, answer);
-	}
-
-	async addWebCodecsIceCandidate(tabId: string, candidate: RTCIceCandidateInit): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return false;
-		}
-		return await this.videoCapture.addIceCandidate(tabId, tab, candidate);
-	}
-
-	isWebCodecsActive(tabId: string): boolean {
-		return this.videoCapture.isStreaming(tabId);
-	}
-
-	async getWebCodecsStats(tabId: string) {
-		const tab = this.getTab(tabId);
-		if (!tab) {
-			return null;
-		}
-		return await this.videoCapture.getStats(tabId, tab);
-	}
-
-	markUserInteraction(tabId: string): void {
-		this.tabManager.markTabActivity(tabId);
-	}
-
-	// Public method to mark tab activity (called from WS handlers)
-	markActiveTabActivity(): void {
-		const tab = this.getActiveTab();
-		if (tab) {
-			this.tabManager.markTabActivity(tab.id);
-		}
-	}
-
-	markNavigation(tabId: string, _newUrl?: string): void {
-		// Navigation tracking is now handled by WebCodecs automatically
-		// This method is kept for API compatibility
-	}
-
-	// ============================================================================
-	// Console Management Methods
-	// ============================================================================
-	getConsoleLogs(tabId: string): BrowserConsoleMessage[] {
-		const tab = this.getTab(tabId);
-		return tab ? this.consoleManager.getConsoleLogs(tab) : [];
-	}
-
-	clearConsoleLogs(tabId: string): boolean {
-		const tab = this.getTab(tabId);
-		return tab ? this.consoleManager.clearConsoleLogs(tab) : false;
-	}
-
-	toggleConsoleLogging(tabId: string, enabled: boolean): boolean {
-		const tab = this.getTab(tabId);
-		return tab ? this.consoleManager.toggleConsoleLogging(tab, enabled) : false;
-	}
-
-	async executeConsoleCommand(tabId: string, command: string): Promise<any> {
-		const tab = this.getTab(tabId);
-		if (!tab) throw new Error('Tab not found or invalid');
-		return this.consoleManager.executeConsoleCommand(tab, command);
-	}
-
-	// ============================================================================
-	// Interaction & Autonomous Actions Methods
-	// ============================================================================
-	async performAutonomousActions(tabId: string, actions: BrowserAutonomousAction[]) {
-		const tab = this.getTab(tabId);
-		if (!tab) throw new Error('Tab not found or invalid');
-
-		const results = await this.interactionHandler.performAutonomousActions(
-			tabId,
-			tab,
-			actions,
-			() => this.isValidTab(tabId)
-		);
-
-		return results;
-	}
-
-	/**
-	 * Perform autonomous actions using tab object directly
-	 * More efficient when tab is already available
-	 */
-	async performAutonomousActionsWithTab(tab: BrowserTab, actions: BrowserAutonomousAction[]) {
-		const results = await this.interactionHandler.performAutonomousActions(
-			tab.id,
-			tab,
-			actions,
-			() => this.isValidTab(tab.id)
-		);
-
-		return results;
-	}
-
-	// ============================================================================
-	// Dialog Management Methods
-	// ============================================================================
-	async respondToDialog(response: BrowserDialogResponse): Promise<boolean> {
-		return await this.dialogHandler.respondToDialog(response);
-	}
-
-	// ============================================================================
-	// Native UI Methods (Select & Context Menu)
-	// ============================================================================
-	async checkForSelectElement(tabId: string, x: number, y: number) {
-		const tab = this.getTab(tabId);
-		if (!tab) return null;
-
-		const selectInfo = await this.nativeUIHandler.checkForSelect(tabId, tab.page, x, y);
-		if (selectInfo) {
-			this.emit('preview:browser-select', selectInfo);
-		}
-		return selectInfo;
-	}
-
-	async handleSelectResponse(tabId: string, response: BrowserSelectResponse): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) return false;
-
-		return await this.nativeUIHandler.handleSelectResponse(tab.page, response);
-	}
-
-	async checkForContextMenu(tabId: string, x: number, y: number) {
-		const tab = this.getTab(tabId);
-		if (!tab) return null;
-
-		const menuInfo = await this.nativeUIHandler.checkForContextMenu(tabId, tab.page, x, y);
-		if (menuInfo) {
-			// Store menu info for later action execution
-			this.contextMenus.set(menuInfo.menuId, menuInfo);
-			this.emit('preview:browser-context-menu', menuInfo);
-		}
-		return menuInfo;
-	}
-
-	async handleContextMenuResponse(tabId: string, response: BrowserContextMenuResponse, clipboardText?: string): Promise<boolean> {
-		const tab = this.getTab(tabId);
-		if (!tab) return false;
-
-		// Get stored menu info
-		const menuInfo = this.contextMenus.get(response.menuId);
-		if (!menuInfo) return false;
-
-		const result = await this.nativeUIHandler.handleContextMenuResponse(tab.page, response, menuInfo, clipboardText);
-
-		// Clean up stored menu info
-		this.contextMenus.delete(response.menuId);
-
-		return result;
-	}
-
-	// ============================================================================
-	// Cleanup Methods
-	// ============================================================================
-	async cleanup() {
-		// Clear all cursor tracking
-		this.interactionHandler.clearAllSessionCursors();
-		// Cleanup tabs (this will also cleanup all contexts/pages/browser pool)
-		await this.tabManager.cleanup();
-	}
-
-	async cleanupInactiveTabs() {
-		return this.tabManager.cleanupInactiveTabs();
-	}
-
-	async forceCleanupAll() {
-		// First try normal cleanup
-		await this.cleanup();
-
-		// Cleanup video capture sessions
-		await this.videoCapture.cleanup();
-
-		// Clear all dialogs and context menus
-		this.dialogHandler.clearAllDialogs();
-		this.contextMenus.clear();
-
-		// Remove all listeners to prevent memory leaks
-		this.removeAllListeners();
-		this.consoleManager.removeAllListeners();
-		this.interactionHandler.removeAllListeners();
-		this.navigationTracker.removeAllListeners();
-		this.videoCapture.removeAllListeners();
-		this.dialogHandler.removeAllListeners();
-		this.nativeUIHandler.removeAllListeners();
-	}
-}
-
-/**
- * Browser Preview Service Manager
- *
- * Manages BrowserPreviewService instances per project.
- * Provides project isolation - each project has its own browser tabs and state.
- */
-class BrowserPreviewServiceManager {
-	private services = new Map<string, BrowserPreviewService>();
-
-	/**
-	 * Get or create a BrowserPreviewService for a project
-	 */
-	getService(projectId: string): BrowserPreviewService {
-		if (!projectId) {
-			throw new Error('projectId is required and cannot be empty');
-		}
-
-		if (!this.services.has(projectId)) {
-			debug.log('preview', `🆕 Creating new BrowserPreviewService for project: ${projectId}`);
-			const service = new BrowserPreviewService(projectId);
-			this.services.set(projectId, service);
-
-			// Setup WebSocket event forwarding for this service
-			this.setupWebSocketForwarding(service, projectId);
-			debug.log('preview', `✅ BrowserPreviewService fully initialized for project: ${projectId}`);
-		}
-
-		return this.services.get(projectId)!;
-	}
-
-	/**
-	 * Setup WebSocket event forwarding for a service instance
-	 * Events are emitted to the specific project only
-	 */
-	private setupWebSocketForwarding(service: BrowserPreviewService, projectId: string): void {
-		debug.log('preview', `🔌 Setting up WebSocket forwarding for project: ${projectId}...`);
-
-		// Forward WebCodecs events
-		service.on('preview:browser-webcodecs-ice-candidate', (data) => {
-			ws.emit.project(projectId, 'preview:browser-stream-ice', {
-				sessionId: data.sessionId,
-				candidate: data.candidate,
-				from: data.from
-			});
-		});
-
-		service.on('preview:browser-webcodecs-connection-state', (data) => {
-			ws.emit.project(projectId, 'preview:browser-stream-state', data);
-		});
-
-		service.on('preview:browser-cursor-change', (data) => {
-			ws.emit.project(projectId, 'preview:browser-cursor-change', data);
-		});
-
-		// Forward navigation events
-		service.on('preview:browser-navigation-loading', (data) => {
-			ws.emit.project(projectId, 'preview:browser-navigation-loading', data);
-		});
-
-		service.on('preview:browser-navigation', (data) => {
-			ws.emit.project(projectId, 'preview:browser-navigation', data);
-		});
-
-		// Forward tab events
-		service.on('preview:browser-tab-opened', (data) => {
-			debug.log('preview', `🚀 Forwarding preview:browser-tab-opened to project ${projectId}:`, data);
-			ws.emit.project(projectId, 'preview:browser-tab-opened', data);
-		});
-
-		service.on('preview:browser-tab-closed', (data) => {
-			ws.emit.project(projectId, 'preview:browser-tab-closed', data);
-		});
-
-		service.on('preview:browser-tab-switched', (data) => {
-			ws.emit.project(projectId, 'preview:browser-tab-switched', data);
-		});
-
-		service.on('preview:browser-tab-navigated', (data) => {
-			ws.emit.project(projectId, 'preview:browser-tab-navigated', data);
-		});
-
-		// Forward console events
-		service.on('preview:browser-console-message', (data) => {
-			ws.emit.project(projectId, 'preview:browser-console-message', data);
-		});
-
-		service.on('preview:browser-console-clear', (data) => {
-			ws.emit.project(projectId, 'preview:browser-console-clear', data);
-		});
-
-		// Forward MCP events
-		service.on('preview:browser-mcp-cursor-position', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-cursor-position', data);
-		});
-
-		service.on('preview:browser-mcp-cursor-click', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-cursor-click', data);
-		});
-
-		service.on('preview:browser-mcp-test-completed', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-test-completed', data);
-		});
-
-		// Forward dialog events
-		service.on('preview:browser-dialog', (data) => {
-			ws.emit.project(projectId, 'preview:browser-dialog', data);
-		});
-
-		service.on('preview:browser-print', (data) => {
-			ws.emit.project(projectId, 'preview:browser-print', data);
-		});
-
-		// Forward native UI events
-		service.on('preview:browser-select', (data) => {
-			ws.emit.project(projectId, 'preview:browser-select', data);
-		});
-
-		service.on('preview:browser-context-menu', (data) => {
-			ws.emit.project(projectId, 'preview:browser-context-menu', data);
-		});
-
-		service.on('preview:browser-copy-to-clipboard', (data) => {
-			ws.emit.project(projectId, 'preview:browser-copy-to-clipboard', data);
-		});
-
-		service.on('preview:browser-open-url-new-tab', (data) => {
-			ws.emit.project(projectId, 'preview:browser-open-url-new-tab', data);
-		});
-
-		service.on('preview:browser-download-image', (data) => {
-			ws.emit.project(projectId, 'preview:browser-download-image', data);
-		});
-
-		service.on('preview:browser-copy-image-to-clipboard', (data) => {
-			ws.emit.project(projectId, 'preview:browser-copy-image-to-clipboard', data);
-		});
-
-		// Forward new window events
-		service.on('preview:browser-new-window', (data) => {
-			ws.emit.project(projectId, 'preview:browser-new-window', data);
-		});
-
-		// Forward MCP control events (from singleton browserMcpControl)
-		browserMcpControl.on('control-start', (data) => {
-			debug.log('preview', `🚀 Forwarding mcp-control-start to project ${projectId}:`, data);
-			ws.emit.project(projectId, 'preview:browser-mcp-control-start', {
-				browserSessionId: data.browserTabId,
-				mcpSessionId: data.mcpSessionId,
-				timestamp: data.timestamp
-			});
-		});
-
-		browserMcpControl.on('control-end', (data) => {
-			debug.log('preview', `🚀 Forwarding mcp-control-end to project ${projectId}:`, data);
-			ws.emit.project(projectId, 'preview:browser-mcp-control-end', {
-				browserSessionId: data.browserTabId,
-				timestamp: data.timestamp
-			});
-		});
-
-		// Forward MCP cursor events
-		browserMcpControl.on('cursor-position', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-cursor-position', {
-				sessionId: data.tabId,
-				x: data.x,
-				y: data.y,
-				timestamp: data.timestamp,
-				source: 'mcp'
-			});
-		});
-
-		browserMcpControl.on('cursor-click', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-cursor-click', {
-				sessionId: data.tabId,
-				x: data.x,
-				y: data.y,
-				timestamp: data.timestamp,
-				source: 'mcp'
-			});
-		});
-
-		browserMcpControl.on('test-completed', (data) => {
-			ws.emit.project(projectId, 'preview:browser-mcp-test-completed', {
-				sessionId: data.tabId,
-				timestamp: data.timestamp,
-				source: 'mcp'
-			});
-		});
-
-		debug.log('preview', `🎉 All WebSocket event listeners registered for project: ${projectId}`);
-	}
-
-	/**
-	 * Check if a service exists for a project
-	 */
-	hasService(projectId: string): boolean {
-		if (!projectId) {
-			throw new Error('projectId is required and cannot be empty');
-		}
-		return this.services.has(projectId);
-	}
-
-	/**
-	 * Remove a service for a project (cleanup)
-	 */
-	async removeService(projectId: string): Promise<void> {
-		if (!projectId) {
-			throw new Error('projectId is required and cannot be empty');
-		}
-
-		const service = this.services.get(projectId);
-
-		if (service) {
-			await service.forceCleanupAll();
-			this.services.delete(projectId);
-		}
-	}
-
-	/**
-	 * Cleanup all services
-	 */
-	async cleanup(): Promise<void> {
-		const cleanupPromises = Array.from(this.services.values()).map(service =>
-			service.forceCleanupAll().catch(error => {
-				console.error('Error cleaning up service:', error);
-			})
-		);
-
-		await Promise.all(cleanupPromises);
-		this.services.clear();
-	}
-
-	/**
-	 * Get all active project IDs
-	 */
-	getActiveProjects(): string[] {
-		return Array.from(this.services.keys());
-	}
-
-	/**
-	 * Get stats for all services
-	 */
-	getStats() {
-		const stats = new Map<string, any>();
-
-		for (const [projectId, service] of this.services.entries()) {
-			stats.set(projectId, {
-				projectId,
-				tabs: service.getTabsStatus()
-			});
-		}
-
-		return stats;
-	}
-}
-
-// Service manager instance (singleton)
-export const browserPreviewServiceManager = new BrowserPreviewServiceManager();
-
-// Graceful shutdown handlers
-const gracefulShutdown = async (signal: string) => {
-	try {
-		await browserPreviewServiceManager.cleanup();
-		process.exit(0);
-	} catch (error) {
-		process.exit(1);
-	}
-};
-
-// Handle various termination signals
-process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
-process.on('SIGHUP', () => gracefulShutdown('SIGHUP'));
-
-// Handle Windows-specific signals
-if (process.platform === 'win32') {
-	process.on('SIGBREAK', () => gracefulShutdown('SIGBREAK'));
-}
-
-// Handle uncaught exceptions and unhandled rejections
-process.on('uncaughtException', async (error) => {
-	await browserPreviewServiceManager.cleanup();
-	process.exit(1);
-});
-
-process.on('unhandledRejection', async (reason, promise) => {
-	await browserPreviewServiceManager.cleanup();
-	process.exit(1);
-});
-
-// Handle process exit
-process.on('exit', (code) => {
-});
+import { EventEmitter } from 'events';
+import type { Page } from 'puppeteer-core';
+import { BrowserTabManager } from './browser-tab-manager.js';
+import { BrowserConsoleManager } from './browser-console-manager.js';
+import { BrowserInteractionHandler } from './browser-interaction-handler.js';
+import { BrowserNavigationTracker } from './browser-navigation-tracker.js';
+import { BrowserVideoCapture } from './browser-video-capture.js';
+import { BrowserDialogHandler } from './browser-dialog-handler.js';
+import { BrowserNativeUIHandler } from './browser-native-ui-handler.js';
+import { browserMcpControl } from './browser-mcp-control.js';
+import { ws } from '$backend/lib/utils/ws';
+import { debug } from '$shared/utils/logger';
+import type {
+	BrowserTab,
+	BrowserTabInfo,
+	BrowserConsoleMessage,
+	BrowserAutonomousAction,
+	DeviceSize,
+	Rotation,
+	BrowserDialogResponse,
+	BrowserSelectResponse,
+	BrowserContextMenuResponse,
+	BrowserContextMenuInfo
+} from './types';
+
+/**
+ * Browser Preview Service
+ *
+ * Main orchestrator for browser preview functionality.
+ * Tab-centric architecture - all operations work with tabs.
+ *
+ * Architecture:
+ * - Tabs are the primary unit (no separate session concept)
+ * - Each tab = isolated browser context + page
+ * - Event-driven communication with frontend
+ * - Manages all browser operations: streaming, interaction, console, etc.
+ * - **PROJECT ISOLATION**: Each instance is isolated per project
+ */
+export class BrowserPreviewService extends EventEmitter {
+	private tabManager: BrowserTabManager;
+	private consoleManager: BrowserConsoleManager;
+	private interactionHandler: BrowserInteractionHandler;
+	private navigationTracker: BrowserNavigationTracker;
+	private videoCapture: BrowserVideoCapture;
+	private dialogHandler: BrowserDialogHandler;
+	private nativeUIHandler: BrowserNativeUIHandler;
+
+	// Store context menu info for later action execution
+	private contextMenus = new Map<string, BrowserContextMenuInfo>();
+
+	// Project ID for isolation (REQUIRED)
+	private projectId: string;
+
+	constructor(projectId: string) {
+		super();
+
+		if (!projectId) {
+			throw new Error('projectId is required for BrowserPreviewService');
+		}
+
+		this.projectId = projectId;
+
+		// Initialize managers with projectId for isolation
+		this.tabManager = new BrowserTabManager(projectId);
+		this.consoleManager = new BrowserConsoleManager();
+		this.interactionHandler = new BrowserInteractionHandler();
+		this.navigationTracker = new BrowserNavigationTracker();
+		this.videoCapture = new BrowserVideoCapture();
+		this.dialogHandler = new BrowserDialogHandler();
+		this.nativeUIHandler = new BrowserNativeUIHandler();
+
+		// Forward events from handlers to main service
+		this.setupEventForwarding();
+	}
+
+	private setupEventForwarding() {
+		// Forward console events
+		this.consoleManager.on('console-message', (data) => {
+			this.emit('preview:browser-console-message', data);
+		});
+		this.consoleManager.on('console-clear', (data) => {
+			this.emit('preview:browser-console-clear', data);
+		});
+
+		// Forward interaction events (MCP cursor)
+		this.interactionHandler.on('cursor-position', (data) => {
+			this.emit('preview:browser-mcp-cursor-position', data);
+		});
+		this.interactionHandler.on('cursor-click', (data) => {
+			this.emit('preview:browser-mcp-cursor-click', data);
+		});
+		this.interactionHandler.on('test-completed', (data) => {
+			this.emit('preview:browser-mcp-test-completed', data);
+		});
+
+		// Forward navigation events and handle video streaming restart
+		this.navigationTracker.on('navigation', async (data) => {
+			this.emit('preview:browser-navigation', data);
+
+			// After navigation completes, restart video streaming for the tab
+			// This re-injects the peer script and restarts CDP screencast
+			const { sessionId } = data;
+			if (this.videoCapture.isStreaming(sessionId)) {
+				const tab = this.getTab(sessionId);
+				if (tab) {
+					// Small delay to ensure page is fully loaded
+					setTimeout(async () => {
+						try {
+							const success = await this.videoCapture.handleNavigation(sessionId, tab);
+							if (success) {
+								this.emit('preview:browser-navigation-streaming-ready', { sessionId });
+							}
+						} catch (error) {
+							// Silently fail - frontend will request refresh if needed
+						}
+					}, 100);
+				}
+			}
+		});
+
+		// Forward navigation loading events
+		this.navigationTracker.on('navigation-loading', (data) => {
+			this.emit('preview:browser-navigation-loading', data);
+		});
+
+		// Forward new window events
+		this.tabManager.on('new-window', (data) => {
+			this.emit('preview:browser-new-window', data);
+		});
+
+		// Forward tab events (already have correct event names from tab manager)
+		this.tabManager.on('preview:browser-tab-opened', (data) => {
+			this.emit('preview:browser-tab-opened', data);
+		});
+		this.tabManager.on('preview:browser-tab-closed', (data) => {
+			this.emit('preview:browser-tab-closed', data);
+		});
+		this.tabManager.on('preview:browser-tab-switched', (data) => {
+			this.emit('preview:browser-tab-switched', data);
+		});
+		this.tabManager.on('preview:browser-tab-navigated', (data) => {
+			this.emit('preview:browser-tab-navigated', data);
+		});
+
+		// Forward video capture events
+		this.videoCapture.on('ice-candidate', (data) => {
+			this.emit('preview:browser-webcodecs-ice-candidate', data);
+		});
+		this.videoCapture.on('connection-state', (data) => {
+			this.emit('preview:browser-webcodecs-connection-state', data);
+		});
+		this.videoCapture.on('cursor-change', (data) => {
+			this.emit('preview:browser-cursor-change', data);
+		});
+		this.videoCapture.on('navigation-streaming-ready', (data) => {
+			this.emit('preview:browser-navigation-streaming-ready', data);
+		});
+
+		// Forward dialog events
+		this.dialogHandler.on('dialog', (data) => {
+			this.emit('preview:browser-dialog', data);
+		});
+		this.dialogHandler.on('print', (data) => {
+			this.emit('preview:browser-print', data);
+		});
+
+		// Forward native UI events
+		this.nativeUIHandler.on('copy-to-clipboard', (data) => {
+			this.emit('preview:browser-copy-to-clipboard', data);
+		});
+		this.nativeUIHandler.on('open-url-new-tab', (data) => {
+			this.emit('preview:browser-open-url-new-tab', data);
+		});
+		this.nativeUIHandler.on('download-image', (data) => {
+			this.emit('preview:browser-download-image', data);
+		});
+		this.nativeUIHandler.on('copy-image-to-clipboard', (data) => {
+			this.emit('preview:browser-copy-image-to-clipboard', data);
+		});
+	}
+
+	/**
+	 * Get project ID for this service instance
+	 */
+	getProjectId(): string {
+		return this.projectId;
+	}
+
+	// ============================================================================
+	// Tab Management Methods
+	// ============================================================================
+
+	/**
+	 * Create a new tab with optional URL
+	 *
+	 * If URL is provided, navigate to it immediately.
+	 * If URL is not provided, create blank tab (about:blank).
+	 *
+	 * Default rotation depends on device size:
+	 * - Desktop/laptop: landscape
+	 * - Tablet/mobile: portrait
+	 */
+	async createTab(url?: string, deviceSize: DeviceSize = 'laptop', rotation?: Rotation): Promise<BrowserTab> {
+		// Use device-appropriate default rotation if not specified
+		const actualRotation = rotation || ((deviceSize === 'desktop' || deviceSize === 'laptop') ? 'landscape' : 'portrait');
+		// Pre-navigation setup callback for dialog bindings
+		const preNavigationSetup = async (page: Page) => {
+			// Note: We'll setup dialog bindings using tabId after tab is created
+		};
+
+		// Create tab
+		const tab = await this.tabManager.createTab(url, deviceSize, actualRotation, {
+			setActive: true,
+			preNavigationSetup
+		});
+
+		// Setup console and navigation tracking
+		await this.consoleManager.setupConsoleLogging(tab.id, tab.page, tab);
+		await this.navigationTracker.setupNavigationTracking(tab.id, tab.page, tab);
+
+		// Setup dialog bindings and handling
+		await this.dialogHandler.setupDialogBindings(tab.id, tab.page);
+		await this.dialogHandler.setupDialogHandling(tab.id, tab.page, tab);
+
+		return tab;
+	}
+
+	/**
+	 * Navigate tab to a new URL
+	 */
+	async navigateTab(tabId: string, url: string): Promise<string> {
+		const actualUrl = await this.tabManager.navigateTab(tabId, url);
+
+		// Mark navigation for frame deduplication
+		this.markNavigation(tabId, url);
+
+		return actualUrl;
+	}
+
+	/**
+	 * Close a tab and cleanup its resources
+	 */
+	async closeTab(tabId: string): Promise<{ success: boolean; newActiveTabId: string | null }> {
+		const tab = this.tabManager.getTab(tabId);
+		if (!tab) {
+			return { success: false, newActiveTabId: null };
+		}
+
+		// Stop WebCodecs streaming first
+		await this.stopWebCodecsStreaming(tabId);
+
+		// Clear cursor tracking for this tab
+		this.interactionHandler.clearSessionCursor(tabId);
+
+		// Clear dialogs for this tab
+		this.dialogHandler.clearSessionDialogs(tabId);
+
+		// Close the tab (this will cleanup context, page, etc.)
+		const result = await this.tabManager.closeTab(tabId);
+
+		// Emit tab closed event (for MCP control manager and other listeners)
+		this.emit('preview:browser-tab-destroyed', { tabId });
+
+		return result;
+	}
+
+	/**
+	 * Switch to a specific tab
+	 */
+	switchTab(tabId: string): boolean {
+		return this.tabManager.setActiveTab(tabId);
+	}
+
+	/**
+	 * Get a tab by ID
+	 */
+	getTab(tabId: string): BrowserTab | null {
+		return this.tabManager.getTab(tabId);
+	}
+
+	/**
+	 * Get the active tab
+	 */
+	getActiveTab(): BrowserTab | null {
+		return this.tabManager.getActiveTab();
+	}
+
+	/**
+	 * Get all tabs
+	 */
+	getAllTabs(): BrowserTab[] {
+		return this.tabManager.getAllTabs();
+	}
+
+	/**
+	 * Change viewport settings (device size and rotation) for an existing tab
+	 */
+	async setViewport(tabId: string, deviceSize: DeviceSize, rotation: Rotation): Promise<boolean> {
+		return await this.tabManager.setViewport(tabId, deviceSize, rotation);
+	}
+
+	/**
+	 * Get tab count
+	 */
+	getTabCount(): number {
+		return this.tabManager.getTabCount();
+	}
+
+	/**
+	 * Get tab info
+	 */
+	getTabInfo(tabId: string): BrowserTabInfo | null {
+		return this.tabManager.getTabInfo(tabId);
+	}
+
+	/**
+	 * Get all tabs info
+	 */
+	getAllTabsInfo(): BrowserTabInfo[] {
+		return this.tabManager.getAllTabsInfo();
+	}
+
+	/**
+	 * Get available tab IDs
+	 */
+	getAvailableTabIds(): string[] {
+		return this.tabManager.getAvailableTabIds();
+	}
+
+	/**
+	 * Get tabs status (for admin/debugging)
+	 */
+	getTabsStatus() {
+		return this.tabManager.getTabsStatus();
+	}
+
+	/**
+	 * Update tab title from URL
+	 */
+	updateTabTitleFromUrl(tabId: string, url: string): void {
+		this.tabManager.updateTabTitleFromUrl(tabId, url);
+	}
+
+	/**
+	 * Check if tab is valid
+	 */
+	isValidTab(tabId: string): boolean {
+		const tab = this.getTab(tabId);
+		return tab !== null && !tab.isDestroyed;
+	}
+
+	// ============================================================================
+	// WebCodecs Streaming Methods (optimized, ~20-40ms, lower bandwidth)
+	// ============================================================================
+	async startWebCodecsStreaming(tabId: string): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return false;
+		}
+		return await this.videoCapture.startStreaming(
+			tabId,
+			tab,
+			() => this.isValidTab(tabId)
+		);
+	}
+
+	async stopWebCodecsStreaming(tabId: string): Promise<void> {
+		const tab = this.getTab(tabId);
+		await this.videoCapture.stopStreaming(tabId, tab ?? undefined);
+	}
+
+	async updateWebCodecsScale(tabId: string, newScale: number): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return false;
+		}
+		return await this.videoCapture.updateScale(tabId, tab, newScale);
+	}
+
+	async updateWebCodecsViewport(tabId: string, width: number, height: number, newScale: number): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return false;
+		}
+		return await this.videoCapture.updateViewport(tabId, tab, width, height, newScale);
+	}
+
+	async getWebCodecsOffer(tabId: string): Promise<RTCSessionDescriptionInit | null> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return null;
+		}
+		return await this.videoCapture.createOffer(tabId, tab);
+	}
+
+	async handleWebCodecsAnswer(tabId: string, answer: RTCSessionDescriptionInit): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return false;
+		}
+		return await this.videoCapture.handleAnswer(tabId, tab, answer);
+	}
+
+	async addWebCodecsIceCandidate(tabId: string, candidate: RTCIceCandidateInit): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return false;
+		}
+		return await this.videoCapture.addIceCandidate(tabId, tab, candidate);
+	}
+
+	isWebCodecsActive(tabId: string): boolean {
+		return this.videoCapture.isStreaming(tabId);
+	}
+
+	async getWebCodecsStats(tabId: string) {
+		const tab = this.getTab(tabId);
+		if (!tab) {
+			return null;
+		}
+		return await this.videoCapture.getStats(tabId, tab);
+	}
+
+	markUserInteraction(tabId: string): void {
+		this.tabManager.markTabActivity(tabId);
+	}
+
+	// Public method to mark tab activity (called from WS handlers)
+	markActiveTabActivity(): void {
+		const tab = this.getActiveTab();
+		if (tab) {
+			this.tabManager.markTabActivity(tab.id);
+		}
+	}
+
+	markNavigation(tabId: string, _newUrl?: string): void {
+		// Navigation tracking is now handled by WebCodecs automatically
+		// This method is kept for API compatibility
+	}
+
+	// ============================================================================
+	// Console Management Methods
+	// ============================================================================
+	getConsoleLogs(tabId: string): BrowserConsoleMessage[] {
+		const tab = this.getTab(tabId);
+		return tab ? this.consoleManager.getConsoleLogs(tab) : [];
+	}
+
+	clearConsoleLogs(tabId: string): boolean {
+		const tab = this.getTab(tabId);
+		return tab ? this.consoleManager.clearConsoleLogs(tab) : false;
+	}
+
+	toggleConsoleLogging(tabId: string, enabled: boolean): boolean {
+		const tab = this.getTab(tabId);
+		return tab ? this.consoleManager.toggleConsoleLogging(tab, enabled) : false;
+	}
+
+	async executeConsoleCommand(tabId: string, command: string): Promise<any> {
+		const tab = this.getTab(tabId);
+		if (!tab) throw new Error('Tab not found or invalid');
+		return this.consoleManager.executeConsoleCommand(tab, command);
+	}
+
+	// ============================================================================
+	// Interaction & Autonomous Actions Methods
+	// ============================================================================
+	async performAutonomousActions(tabId: string, actions: BrowserAutonomousAction[]) {
+		const tab = this.getTab(tabId);
+		if (!tab) throw new Error('Tab not found or invalid');
+
+		const results = await this.interactionHandler.performAutonomousActions(
+			tabId,
+			tab,
+			actions,
+			() => this.isValidTab(tabId)
+		);
+
+		return results;
+	}
+
+	/**
+	 * Perform autonomous actions using tab object directly
+	 * More efficient when tab is already available
+	 */
+	async performAutonomousActionsWithTab(tab: BrowserTab, actions: BrowserAutonomousAction[]) {
+		const results = await this.interactionHandler.performAutonomousActions(
+			tab.id,
+			tab,
+			actions,
+			() => this.isValidTab(tab.id)
+		);
+
+		return results;
+	}
+
+	// ============================================================================
+	// Dialog Management Methods
+	// ============================================================================
+	async respondToDialog(response: BrowserDialogResponse): Promise<boolean> {
+		return await this.dialogHandler.respondToDialog(response);
+	}
+
+	// ============================================================================
+	// Native UI Methods (Select & Context Menu)
+	// ============================================================================
+	async checkForSelectElement(tabId: string, x: number, y: number) {
+		const tab = this.getTab(tabId);
+		if (!tab) return null;
+
+		const selectInfo = await this.nativeUIHandler.checkForSelect(tabId, tab.page, x, y);
+		if (selectInfo) {
+			this.emit('preview:browser-select', selectInfo);
+		}
+		return selectInfo;
+	}
+
+	async handleSelectResponse(tabId: string, response: BrowserSelectResponse): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) return false;
+
+		return await this.nativeUIHandler.handleSelectResponse(tab.page, response);
+	}
+
+	async checkForContextMenu(tabId: string, x: number, y: number) {
+		const tab = this.getTab(tabId);
+		if (!tab) return null;
+
+		const menuInfo = await this.nativeUIHandler.checkForContextMenu(tabId, tab.page, x, y);
+		if (menuInfo) {
+			// Store menu info for later action execution
+			this.contextMenus.set(menuInfo.menuId, menuInfo);
+			this.emit('preview:browser-context-menu', menuInfo);
+		}
+		return menuInfo;
+	}
+
+	async handleContextMenuResponse(tabId: string, response: BrowserContextMenuResponse, clipboardText?: string): Promise<boolean> {
+		const tab = this.getTab(tabId);
+		if (!tab) return false;
+
+		// Get stored menu info
+		const menuInfo = this.contextMenus.get(response.menuId);
+		if (!menuInfo) return false;
+
+		const result = await this.nativeUIHandler.handleContextMenuResponse(tab.page, response, menuInfo, clipboardText);
+
+		// Clean up stored menu info
+		this.contextMenus.delete(response.menuId);
+
+		return result;
+	}
+
+	// ============================================================================
+	// Cleanup Methods
+	// ============================================================================
+	async cleanup() {
+		// Clear all cursor tracking
+		this.interactionHandler.clearAllSessionCursors();
+		// Cleanup tabs (this will also cleanup all contexts/pages/browser pool)
+		await this.tabManager.cleanup();
+	}
+
+	async cleanupInactiveTabs() {
+		return this.tabManager.cleanupInactiveTabs();
+	}
+
+	async forceCleanupAll() {
+		// First try normal cleanup
+		await this.cleanup();
+
+		// Cleanup video capture sessions
+		await this.videoCapture.cleanup();
+
+		// Clear all dialogs and context menus
+		this.dialogHandler.clearAllDialogs();
+		this.contextMenus.clear();
+
+		// Remove all listeners to prevent memory leaks
+		this.removeAllListeners();
+		this.consoleManager.removeAllListeners();
+		this.interactionHandler.removeAllListeners();
+		this.navigationTracker.removeAllListeners();
+		this.videoCapture.removeAllListeners();
+		this.dialogHandler.removeAllListeners();
+		this.nativeUIHandler.removeAllListeners();
+	}
+}
+
+/**
+ * Browser Preview Service Manager
+ *
+ * Manages BrowserPreviewService instances per project.
+ * Provides project isolation - each project has its own browser tabs and state.
+ */
+class BrowserPreviewServiceManager {
+	private services = new Map<string, BrowserPreviewService>();
+
+	/**
+	 * Get or create a BrowserPreviewService for a project
+	 */
+	getService(projectId: string): BrowserPreviewService {
+		if (!projectId) {
+			throw new Error('projectId is required and cannot be empty');
+		}
+
+		if (!this.services.has(projectId)) {
+			debug.log('preview', `🆕 Creating new BrowserPreviewService for project: ${projectId}`);
+			const service = new BrowserPreviewService(projectId);
+			this.services.set(projectId, service);
+
+			// Setup WebSocket event forwarding for this service
+			this.setupWebSocketForwarding(service, projectId);
+			debug.log('preview', `✅ BrowserPreviewService fully initialized for project: ${projectId}`);
+		}
+
+		return this.services.get(projectId)!;
+	}
+
+	/**
+	 * Setup WebSocket event forwarding for a service instance
+	 * Events are emitted to the specific project only
+	 */
+	private setupWebSocketForwarding(service: BrowserPreviewService, projectId: string): void {
+		debug.log('preview', `🔌 Setting up WebSocket forwarding for project: ${projectId}...`);
+
+		// Forward WebCodecs events
+		service.on('preview:browser-webcodecs-ice-candidate', (data) => {
+			ws.emit.project(projectId, 'preview:browser-stream-ice', {
+				sessionId: data.sessionId,
+				candidate: data.candidate,
+				from: data.from
+			});
+		});
+
+		service.on('preview:browser-webcodecs-connection-state', (data) => {
+			ws.emit.project(projectId, 'preview:browser-stream-state', data);
+		});
+
+		service.on('preview:browser-cursor-change', (data) => {
+			ws.emit.project(projectId, 'preview:browser-cursor-change', data);
+		});
+
+		// Forward navigation events
+		service.on('preview:browser-navigation-loading', (data) => {
+			ws.emit.project(projectId, 'preview:browser-navigation-loading', data);
+		});
+
+		service.on('preview:browser-navigation', (data) => {
+			ws.emit.project(projectId, 'preview:browser-navigation', data);
+		});
+
+		// Forward tab events
+		service.on('preview:browser-tab-opened', (data) => {
+			debug.log('preview', `🚀 Forwarding preview:browser-tab-opened to project ${projectId}:`, data);
+			ws.emit.project(projectId, 'preview:browser-tab-opened', data);
+		});
+
+		service.on('preview:browser-tab-closed', (data) => {
+			ws.emit.project(projectId, 'preview:browser-tab-closed', data);
+		});
+
+		service.on('preview:browser-tab-switched', (data) => {
+			ws.emit.project(projectId, 'preview:browser-tab-switched', data);
+		});
+
+		service.on('preview:browser-tab-navigated', (data) => {
+			ws.emit.project(projectId, 'preview:browser-tab-navigated', data);
+		});
+
+		// Forward console events
+		service.on('preview:browser-console-message', (data) => {
+			ws.emit.project(projectId, 'preview:browser-console-message', data);
+		});
+
+		service.on('preview:browser-console-clear', (data) => {
+			ws.emit.project(projectId, 'preview:browser-console-clear', data);
+		});
+
+		// Forward MCP events
+		service.on('preview:browser-mcp-cursor-position', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-cursor-position', data);
+		});
+
+		service.on('preview:browser-mcp-cursor-click', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-cursor-click', data);
+		});
+
+		service.on('preview:browser-mcp-test-completed', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-test-completed', data);
+		});
+
+		// Forward dialog events
+		service.on('preview:browser-dialog', (data) => {
+			ws.emit.project(projectId, 'preview:browser-dialog', data);
+		});
+
+		service.on('preview:browser-print', (data) => {
+			ws.emit.project(projectId, 'preview:browser-print', data);
+		});
+
+		// Forward native UI events
+		service.on('preview:browser-select', (data) => {
+			ws.emit.project(projectId, 'preview:browser-select', data);
+		});
+
+		service.on('preview:browser-context-menu', (data) => {
+			ws.emit.project(projectId, 'preview:browser-context-menu', data);
+		});
+
+		service.on('preview:browser-copy-to-clipboard', (data) => {
+			ws.emit.project(projectId, 'preview:browser-copy-to-clipboard', data);
+		});
+
+		service.on('preview:browser-open-url-new-tab', (data) => {
+			ws.emit.project(projectId, 'preview:browser-open-url-new-tab', data);
+		});
+
+		service.on('preview:browser-download-image', (data) => {
+			ws.emit.project(projectId, 'preview:browser-download-image', data);
+		});
+
+		service.on('preview:browser-copy-image-to-clipboard', (data) => {
+			ws.emit.project(projectId, 'preview:browser-copy-image-to-clipboard', data);
+		});
+
+		// Forward new window events
+		service.on('preview:browser-new-window', (data) => {
+			ws.emit.project(projectId, 'preview:browser-new-window', data);
+		});
+
+		// Forward MCP control events (from singleton browserMcpControl)
+		browserMcpControl.on('control-start', (data) => {
+			debug.log('preview', `🚀 Forwarding mcp-control-start to project ${projectId}:`, data);
+			ws.emit.project(projectId, 'preview:browser-mcp-control-start', {
+				browserSessionId: data.browserTabId,
+				mcpSessionId: data.mcpSessionId,
+				timestamp: data.timestamp
+			});
+		});
+
+		browserMcpControl.on('control-end', (data) => {
+			debug.log('preview', `🚀 Forwarding mcp-control-end to project ${projectId}:`, data);
+			ws.emit.project(projectId, 'preview:browser-mcp-control-end', {
+				browserSessionId: data.browserTabId,
+				timestamp: data.timestamp
+			});
+		});
+
+		// Forward MCP cursor events
+		browserMcpControl.on('cursor-position', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-cursor-position', {
+				sessionId: data.tabId,
+				x: data.x,
+				y: data.y,
+				timestamp: data.timestamp,
+				source: 'mcp'
+			});
+		});
+
+		browserMcpControl.on('cursor-click', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-cursor-click', {
+				sessionId: data.tabId,
+				x: data.x,
+				y: data.y,
+				timestamp: data.timestamp,
+				source: 'mcp'
+			});
+		});
+
+		browserMcpControl.on('test-completed', (data) => {
+			ws.emit.project(projectId, 'preview:browser-mcp-test-completed', {
+				sessionId: data.tabId,
+				timestamp: data.timestamp,
+				source: 'mcp'
+			});
+		});
+
+		debug.log('preview', `🎉 All WebSocket event listeners registered for project: ${projectId}`);
+	}
+
+	/**
+	 * Check if a service exists for a project
+	 */
+	hasService(projectId: string): boolean {
+		if (!projectId) {
+			throw new Error('projectId is required and cannot be empty');
+		}
+		return this.services.has(projectId);
+	}
+
+	/**
+	 * Remove a service for a project (cleanup)
+	 */
+	async removeService(projectId: string): Promise<void> {
+		if (!projectId) {
+			throw new Error('projectId is required and cannot be empty');
+		}
+
+		const service = this.services.get(projectId);
+
+		if (service) {
+			await service.forceCleanupAll();
+			this.services.delete(projectId);
+		}
+	}
+
+	/**
+	 * Cleanup all services
+	 */
+	async cleanup(): Promise<void> {
+		const cleanupPromises = Array.from(this.services.values()).map(service =>
+			service.forceCleanupAll().catch(error => {
+				console.error('Error cleaning up service:', error);
+			})
+		);
+
+		await Promise.all(cleanupPromises);
+		this.services.clear();
+	}
+
+	/**
+	 * Get all active project IDs
+	 */
+	getActiveProjects(): string[] {
+		return Array.from(this.services.keys());
+	}
+
+	/**
+	 * Get stats for all services
+	 */
+	getStats() {
+		const stats = new Map<string, any>();
+
+		for (const [projectId, service] of this.services.entries()) {
+			stats.set(projectId, {
+				projectId,
+				tabs: service.getTabsStatus()
+			});
+		}
+
+		return stats;
+	}
+}
+
+// Service manager instance (singleton)
+export const browserPreviewServiceManager = new BrowserPreviewServiceManager();
+
+// Graceful shutdown handlers
+const gracefulShutdown = async (signal: string) => {
+	try {
+		await browserPreviewServiceManager.cleanup();
+		process.exit(0);
+	} catch (error) {
+		process.exit(1);
+	}
+};
+
+// Handle various termination signals
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGHUP', () => gracefulShutdown('SIGHUP'));
+
+// Handle Windows-specific signals
+if (process.platform === 'win32') {
+	process.on('SIGBREAK', () => gracefulShutdown('SIGBREAK'));
+}
+
+// Handle uncaught exceptions and unhandled rejections
+process.on('uncaughtException', async (error) => {
+	await browserPreviewServiceManager.cleanup();
+	process.exit(1);
+});
+
+process.on('unhandledRejection', async (reason, promise) => {
+	await browserPreviewServiceManager.cleanup();
+	process.exit(1);
+});
+
+// Handle process exit
+process.on('exit', (code) => {
+});