@myrialabs/clopen 0.2.5 → 0.2.7

package/frontend/components/preview/browser/components/Canvas.svelte

@@ -24,7 +24,9 @@
 		onCursorUpdate = $bindable<(cursor: string) => void>(() => {}),
 		onFrameUpdate = $bindable<(data: any) => void>(() => {}),
 		onStatsUpdate = $bindable<(stats: BrowserWebCodecsStreamStats | null) => void>(() => {}),
-		onRequestScreencastRefresh = $bindable<() => void>(() => {}) // Called when stream is stuck
+		onRequestScreencastRefresh = $bindable<() => void>(() => {}), // Called when stream is stuck
+		touchMode = $bindable<'scroll' | 'cursor'>('scroll'),
+		onTouchCursorUpdate = $bindable<(pos: { x: number; y: number; visible: boolean; clicking?: boolean }) => void>(() => {})
 	} = $props();
 
 	// WebCodecs service instance
@@ -47,17 +49,24 @@
 	let isRecovering = $state(false); // Track recovery attempts
 	let connectionFailed = $state(false); // Track if connection actually failed (not just slow)
 	let hasRequestedScreencastRefresh = false; // Track if we've already requested refresh for this stream
+	let screencastRefreshCount = 0; // Track retry count for stuck detection
 	let navigationJustCompleted = false; // Track if navigation just completed (for fast refresh)
 
+	// Canvas snapshot storage for instant tab switching
+	// Stores a clone of the canvas per sessionId so switching back shows content immediately
+	const canvasSnapshots = new Map<string, HTMLCanvasElement>();
+	const MAX_SNAPSHOTS = 10;
+	let hasRestoredSnapshot = false; // Prevents canvas clear/reset during streaming start
+
 	// Recovery is only triggered by ACTUAL failures, not timeouts
 	// - ICE connection failed
 	// - WebCodecs connection closed unexpectedly
 	// - Explicit errors
 	const MAX_CONSECUTIVE_FAILURES = 2;
 	const HEALTH_CHECK_INTERVAL = 2000; // Check every 2 seconds for connection health
-	const FRAME_CHECK_INTERVAL = 500; // Check for first frame every 500ms (just for UI update, not recovery)
-	const STUCK_STREAM_TIMEOUT = 5000; // Fallback: Request screencast refresh after 5 seconds of connected but no frame
-	const NAVIGATION_FAST_REFRESH_DELAY = 500; // Fast refresh after navigation: 500ms
+	const FRAME_CHECK_INTERVAL = 100; // Fallback poll for first frame (primary path is onFirstFrame callback)
+	const STUCK_STREAM_TIMEOUT = 3000; // Fallback: Request screencast refresh after 3 seconds of connected but no frame
+	const NAVIGATION_FAST_REFRESH_DELAY = 300; // Fast refresh after navigation: 300ms
 
 	// Sync isStreamReady with hasReceivedFirstFrame for parent component
 	$effect(() => {
@@ -73,6 +82,11 @@
 		if (lastProjectId && currentProjectId && lastProjectId !== currentProjectId) {
 			debug.log('webcodecs', `🔄 Project changed (${lastProjectId} → ${currentProjectId}), destroying old WebCodecs service`);
 
+			// Clear canvas snapshots - they belong to old project's sessions
+			canvasSnapshots.clear();
+			hasRestoredSnapshot = false;
+			lastStartRequestId = null; // Clear so new project sessions aren't blocked by old tab IDs
+
 			// Destroy old service
 			if (webCodecsService) {
 				webCodecsService.destroy();
@@ -285,6 +299,24 @@
 	let mouseDownTime = $state(0);
 	let dragStarted = $state(false); // Track if we've sent mousedown for drag
 
+	// Touch-specific tracking (non-reactive for performance)
+	let longPressTimer: ReturnType<typeof setTimeout> | null = null;
+	let touchLongPressed = false;
+	let lastTouchCoords: { x: number; y: number } | null = null;
+
+	// Trackpad cursor state (cursor/trackpad mode - persists between touch gestures)
+	let trackpadCursorX = 0;
+	let trackpadCursorY = 0;
+	let trackpadLastClientX = 0;
+	let trackpadLastClientY = 0;
+	let trackpadTouchStartClientX = 0;
+	let trackpadTouchStartClientY = 0;
+	let trackpadTwoFingerActive = false;
+	let trackpadTwoFingerStartTime = 0;
+	let trackpadTwoFingerLastCenterX = 0;
+	let trackpadTwoFingerLastCenterY = 0;
+	let trackpadTwoFingerTotalDist = 0;
+
 	function handleCanvasMouseDown(event: MouseEvent, canvas: HTMLCanvasElement) {
 		if (!sessionId) return;
 
@@ -392,31 +424,39 @@
 
 	// Start WebCodecs streaming
 	async function startStreaming() {
-		if (!sessionId || !canvasElement) return;
+		debug.log('webcodecs', `[DIAG] startStreaming() called: sessionId=${sessionId}, canvasElement=${!!canvasElement}, isStartingStream=${isStartingStream}, isWebCodecsActive=${isWebCodecsActive}, activeStreamingSessionId=${activeStreamingSessionId}, lastStartRequestId=${lastStartRequestId}`);
+
+		if (!sessionId || !canvasElement) {
+			debug.log('webcodecs', `[DIAG] startStreaming() early exit: missing sessionId=${!sessionId} or canvasElement=${!canvasElement}`);
+			return;
+		}
 
 		// Prevent concurrent start attempts
 		if (isStartingStream) {
-			debug.log('webcodecs', 'Already starting stream, skipping duplicate call');
+			debug.log('webcodecs', '[DIAG] startStreaming() skipped: already starting stream');
 			return;
 		}
 
 		// If already streaming same session, skip
 		if (isWebCodecsActive && activeStreamingSessionId === sessionId) {
-			debug.log('webcodecs', 'Already streaming same session, skipping');
+			debug.log('webcodecs', '[DIAG] startStreaming() skipped: already streaming same session');
 			return;
 		}
 
 		// Prevent duplicate requests for same session
 		const requestId = `${sessionId}-${Date.now()}`;
 		if (lastStartRequestId && lastStartRequestId.startsWith(sessionId)) {
-			debug.log('webcodecs', `Duplicate start request for ${sessionId}, skipping`);
+			debug.log('webcodecs', `[DIAG] startStreaming() skipped: duplicate request for ${sessionId}, lastStartRequestId=${lastStartRequestId}`);
 			return;
 		}
 		lastStartRequestId = requestId;
 
 		isStartingStream = true;
 		isStreamStarting = true; // Show loading overlay
-		hasReceivedFirstFrame = false; // Reset first frame state
+		// Don't reset if we restored a snapshot - keep showing it
+		if (!hasRestoredSnapshot) {
+			hasReceivedFirstFrame = false; // Reset first frame state
+		}
 
 		try {
 			// If streaming a different session, stop first
@@ -480,6 +520,25 @@
 					onStatsUpdate(stats);
 				});
 
+				// Setup first frame handler - fires immediately when first frame decoded
+				// This eliminates the 500ms polling delay for hiding the loading overlay
+				webCodecsService.setFirstFrameHandler(() => {
+					if (!hasReceivedFirstFrame) {
+						debug.log('webcodecs', 'First frame callback - immediately updating UI');
+						hasReceivedFirstFrame = true;
+						consecutiveFailures = 0;
+						connectionFailed = false;
+					}
+
+					// Always reset reconnecting state on first real frame
+					// (outside !hasReceivedFirstFrame to handle snapshot + reconnect case)
+					if (isReconnecting) {
+						setTimeout(() => {
+							isReconnecting = false;
+						}, 300);
+					}
+				});
+
 				// Setup cursor change handler
 				webCodecsService.setOnCursorChange((cursor: string) => {
 					updateCanvasCursor(cursor);
@@ -491,8 +550,8 @@
 
 			let success = false;
 			let retries = 0;
-			const maxRetries = 5; // Increased for rapid tab switching
-			const retryDelay = 500; // Increased delay for backend cleanup
+			const maxRetries = 5;
+			const retryDelay = 300;
 
 			while (!success && retries < maxRetries) {
 				try {
@@ -502,12 +561,20 @@
 						isConnected = true;
 						activeStreamingSessionId = sessionId;
 						consecutiveFailures = 0; // Reset failure counter on success
-						startHealthCheck(); // Start monitoring for stuck streams
+						startHealthCheck(hasRestoredSnapshot); // Skip first frame reset if snapshot
+						hasRestoredSnapshot = false; // Reset after using
 						debug.log('webcodecs', 'Streaming started successfully');
-						break;
+					} else {
+						// Service handles errors internally and returns false.
+						// Never retry here — retrying immediately creates a stop/start loop.
+						debug.warn('webcodecs', 'Streaming start returned false, stopping retries');
 					}
+					// Always break after the service returns (success or failure).
+					// The service catches all exceptions internally, so the catch block
+					// below never runs, making retries/retryDelay dead code anyway.
+					break;
 				} catch (error: any) {
-					// Check if it's a retriable error - might just need more time
+					// This block only runs if the service unexpectedly throws.
 					const isRetriable = error?.message?.includes('not found') ||
 						error?.message?.includes('invalid') ||
 						error?.message?.includes('Failed to start') ||
@@ -520,11 +587,9 @@
 							await new Promise(resolve => setTimeout(resolve, retryDelay));
 						} else {
 							debug.error('webcodecs', 'Max retries reached, streaming still not ready');
-							// Don't throw - just fail silently and let user retry manually
 							break;
 						}
 					} else {
-						// Other errors - don't retry, just log
 						debug.error('webcodecs', 'Streaming error:', error);
 						break;
 					}
@@ -533,6 +598,7 @@
 		} finally {
 			isStartingStream = false;
 			isStreamStarting = false; // Hide "Launching browser..." (but may still show "Connecting..." until first frame)
+			hasRestoredSnapshot = false; // Always reset in finally
 		}
 	}
 
@@ -561,6 +627,7 @@
 		}
 		connectionFailed = false;
 		hasRequestedScreencastRefresh = false; // Reset for new stream
+		screencastRefreshCount = 0; // Reset retry counter
 
 		const startTime = Date.now();
 
@@ -587,6 +654,7 @@
 				consecutiveFailures = 0;
 				connectionFailed = false;
 				hasRequestedScreencastRefresh = false; // Reset on success
+				screencastRefreshCount = 0; // Reset retry counter on success
 
 				// Reset reconnecting state after successful frame reception
 				// This completes the fast reconnect cycle
@@ -621,10 +689,21 @@
 			// STUCK STREAM DETECTION (FALLBACK): If connected but no first frame for too long,
 			// request screencast refresh (hot-swap) to restart CDP screencast.
 			// This handles cases where WebRTC is connected but CDP frames aren't flowing.
-			if (stats?.isConnected && !stats?.firstFrameRendered && elapsed >= STUCK_STREAM_TIMEOUT && !hasRequestedScreencastRefresh) {
-				debug.warn('webcodecs', `Stream appears stuck (connected but no frame for ${elapsed}ms), requesting screencast refresh`);
-				hasRequestedScreencastRefresh = true;
-				onRequestScreencastRefresh();
+			// Retries: 1st at 3s (screencast refresh), 2nd at 6s (another refresh), 3rd at 10s (full recovery)
+			if (stats?.isConnected && !stats?.firstFrameRendered && !hasRequestedScreencastRefresh) {
+				const MAX_SCREENCAST_RETRIES = 2;
+				const retryThreshold = STUCK_STREAM_TIMEOUT + (screencastRefreshCount * 3000); // 3s, 6s
+
+				if (elapsed >= retryThreshold && screencastRefreshCount < MAX_SCREENCAST_RETRIES) {
+					screencastRefreshCount++;
+					debug.warn('webcodecs', `Stream stuck (connected, no frame for ${elapsed}ms), screencast refresh attempt ${screencastRefreshCount}/${MAX_SCREENCAST_RETRIES}`);
+					onRequestScreencastRefresh();
+				} else if (elapsed >= 10000 && screencastRefreshCount >= MAX_SCREENCAST_RETRIES) {
+					// Screencast refreshes didn't help - attempt full recovery
+					debug.warn('webcodecs', `Stream still stuck after ${screencastRefreshCount} screencast refreshes (${elapsed}ms), attempting full recovery`);
+					hasRequestedScreencastRefresh = true; // Prevent further retries
+					attemptRecovery();
+				}
 			}
 
 		}, FRAME_CHECK_INTERVAL);
@@ -770,11 +849,11 @@
 			lastStartRequestId = null; // Clear to allow new requests
 			// Note: Don't reset hasReceivedFirstFrame here - let startStreaming do it
 			// This prevents flashing when switching tabs
-			// Clear canvas to prevent stale frames, BUT keep last frame during navigation
-			if (!isNavigating) {
+			// Clear canvas to prevent stale frames, BUT keep last frame during navigation or snapshot restore
+			if (!isNavigating && !hasRestoredSnapshot) {
 				clearCanvas();
 			} else {
-				debug.log('webcodecs', 'Skipping canvas clear during navigation - keeping last frame');
+				debug.log('webcodecs', `Skipping canvas clear - navigation: ${isNavigating}, snapshot: ${hasRestoredSnapshot}`);
 			}
 		}
 	}
@@ -802,6 +881,8 @@
 	// Start/restart streaming when session is ready
 	// This handles both initial start and session changes (viewport switch, etc.)
 	$effect(() => {
+		debug.log('webcodecs', `[DIAG] streaming $effect triggered: sessionId=${sessionId}, canvasElement=${!!canvasElement}, sessionInfo=${!!sessionInfo}, isReconnecting=${isReconnecting}, isWebCodecsActive=${isWebCodecsActive}, activeStreamingSessionId=${activeStreamingSessionId}`);
+
 		if (sessionId && canvasElement && sessionInfo) {
 			// Skip during fast reconnect - fastReconnect() handles this case
 			if (isReconnecting) {
@@ -811,12 +892,55 @@
 
 			// Check if we need to start or restart streaming
 			const needsStreaming = !isWebCodecsActive || activeStreamingSessionId !== sessionId;
+			debug.log('webcodecs', `[DIAG] streaming $effect: needsStreaming=${needsStreaming}`);
 
 			if (needsStreaming) {
-				// Clear canvas immediately when session changes to prevent stale frames
 				if (activeStreamingSessionId !== sessionId) {
-					clearCanvas();
-					hasReceivedFirstFrame = false; // Reset to show loading overlay
+					// SNAPSHOT: Save current canvas before switching to new session
+					if (activeStreamingSessionId && hasReceivedFirstFrame && canvasElement.width > 0) {
+						try {
+							const clone = document.createElement('canvas');
+							clone.width = canvasElement.width;
+							clone.height = canvasElement.height;
+							const cloneCtx = clone.getContext('2d');
+							if (cloneCtx) {
+								cloneCtx.drawImage(canvasElement, 0, 0);
+								// Limit snapshot count
+								if (canvasSnapshots.size >= MAX_SNAPSHOTS) {
+									const firstKey = canvasSnapshots.keys().next().value;
+									if (firstKey) canvasSnapshots.delete(firstKey);
+								}
+								canvasSnapshots.set(activeStreamingSessionId, clone);
+								debug.log('webcodecs', `📸 Saved canvas snapshot for session ${activeStreamingSessionId}`);
+							}
+						} catch (e) {
+							debug.warn('webcodecs', 'Failed to capture canvas snapshot:', e);
+						}
+					}
+
+					// SNAPSHOT: Restore for new session if available
+					const existingSnapshot = canvasSnapshots.get(sessionId);
+					if (existingSnapshot) {
+						setupCanvasInternal(); // Ensure canvas dimensions are correct
+						try {
+							const ctx = canvasElement.getContext('2d');
+							if (ctx) {
+								ctx.drawImage(existingSnapshot, 0, 0, canvasElement.width, canvasElement.height);
+								hasRestoredSnapshot = true;
+								// Don't reset hasReceivedFirstFrame - snapshot is visible
+								debug.log('webcodecs', `📸 Restored canvas snapshot for session ${sessionId}`);
+							}
+						} catch (e) {
+							debug.warn('webcodecs', 'Failed to restore canvas snapshot:', e);
+							hasRestoredSnapshot = false;
+							clearCanvas();
+							hasReceivedFirstFrame = false;
+						}
+					} else {
+						hasRestoredSnapshot = false;
+						clearCanvas();
+						hasReceivedFirstFrame = false; // Reset to show loading overlay
+					}
 				}
 
 				// Stop existing streaming first if session changed
@@ -831,12 +955,10 @@
 					await startStreaming();
 				};
 
-				// Longer delay to ensure backend session is fully ready
-				// This is especially important during viewport/device change
-				// when session is being recreated
+				// Small delay to ensure backend session is ready
 				const timeout = setTimeout(() => {
 					doStartStreaming();
-				}, 200);
+				}, 50);
 
 				return () => clearTimeout(timeout);
 			}
@@ -880,9 +1002,20 @@
 				canvas.focus();
 			});
 
-			canvas.addEventListener('touchstart', (e) => handleTouchStart(e, canvas), { passive: false });
-			canvas.addEventListener('touchmove', (e) => handleTouchMove(e, canvas), { passive: false });
-			canvas.addEventListener('touchend', (e) => handleTouchEnd(e, canvas), { passive: false });
+			const touchStartHandler = (e: TouchEvent) => handleTouchStart(e, canvas);
+			let lastTouchMoveTime = 0;
+			const touchMoveHandler = (e: TouchEvent) => {
+				const now = Date.now();
+				if (now - lastTouchMoveTime >= 16) {
+					lastTouchMoveTime = now;
+					handleTouchMove(e, canvas);
+				}
+			};
+			const touchEndHandler = (e: TouchEvent) => handleTouchEnd(e, canvas);
+
+			canvas.addEventListener('touchstart', touchStartHandler, { passive: false });
+			canvas.addEventListener('touchmove', touchMoveHandler, { passive: false });
+			canvas.addEventListener('touchend', touchEndHandler, { passive: false });
 
 			const handleMouseLeave = () => {
 				if (isMouseDown) {
@@ -912,76 +1045,299 @@
 				canvas.removeEventListener('mousedown', (e) => handleCanvasMouseDown(e, canvas));
 				canvas.removeEventListener('mouseup', (e) => handleCanvasMouseUp(e, canvas));
 				canvas.removeEventListener('mousemove', handleMouseMove);
-				canvas.removeEventListener('touchstart', (e) => handleTouchStart(e, canvas));
-				canvas.removeEventListener('touchmove', (e) => handleTouchMove(e, canvas));
-				canvas.removeEventListener('touchend', (e) => handleTouchEnd(e, canvas));
+				canvas.removeEventListener('touchstart', touchStartHandler);
+				canvas.removeEventListener('touchmove', touchMoveHandler);
+				canvas.removeEventListener('touchend', touchEndHandler);
 			};
 		}
 	});
 
+	// Convert canvas coordinates to viewport (screen) coordinates for VirtualCursor display
+	function canvasToScreen(cx: number, cy: number): { x: number; y: number } {
+		if (!canvasElement) return { x: 0, y: 0 };
+		const rect = canvasElement.getBoundingClientRect();
+		return {
+			x: rect.left + cx * (rect.width / canvasElement.width),
+			y: rect.top + cy * (rect.height / canvasElement.height)
+		};
+	}
+
+	// Show / hide cursor when touchMode changes
+	$effect(() => {
+		if (touchMode === 'cursor') {
+			// Init cursor at canvas center on first activation
+			if (canvasElement && trackpadCursorX === 0 && trackpadCursorY === 0) {
+				trackpadCursorX = canvasElement.width / 2;
+				trackpadCursorY = canvasElement.height / 2;
+			}
+			if (canvasElement) {
+				const pos = canvasToScreen(trackpadCursorX, trackpadCursorY);
+				onTouchCursorUpdate({ x: pos.x, y: pos.y, visible: true });
+			}
+		} else {
+			onTouchCursorUpdate({ x: 0, y: 0, visible: false });
+		}
+	});
+
+	// ── Trackpad (cursor) mode handlers ───────────────────────────────────────
+
+	function handleTrackpadTouchStart(event: TouchEvent) {
+		if (event.touches.length >= 2) {
+			// Second finger joined → switch to two-finger mode
+			if (!trackpadTwoFingerActive) {
+				// Cancel any pending single-finger actions
+				if (longPressTimer) { clearTimeout(longPressTimer); longPressTimer = null; }
+				if (touchLongPressed && dragStarted) {
+					sendInteraction({ type: 'mouseup', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY), button: 'left' });
+				}
+				isMouseDown = false;
+				dragStarted = false;
+				touchLongPressed = false;
+			}
+			trackpadTwoFingerActive = true;
+			trackpadTwoFingerStartTime = Date.now();
+			trackpadTwoFingerTotalDist = 0;
+			const t1 = event.touches[0];
+			const t2 = event.touches[1];
+			trackpadTwoFingerLastCenterX = (t1.clientX + t2.clientX) / 2;
+			trackpadTwoFingerLastCenterY = (t1.clientY + t2.clientY) / 2;
+			return;
+		}
+
+		if (trackpadTwoFingerActive) return; // Ignore until two-finger gesture fully ends
+
+		// Single finger
+		const touch = event.touches[0];
+		trackpadTouchStartClientX = touch.clientX;
+		trackpadTouchStartClientY = touch.clientY;
+		trackpadLastClientX = touch.clientX;
+		trackpadLastClientY = touch.clientY;
+		isMouseDown = true;
+		mouseDownTime = Date.now();
+		dragStarted = false;
+		touchLongPressed = false;
+
+		// Long-press (600ms without movement) → drag mode
+		longPressTimer = setTimeout(() => {
+			if (!isMouseDown) return;
+			const dist = Math.sqrt(
+				Math.pow(trackpadLastClientX - trackpadTouchStartClientX, 2) +
+				Math.pow(trackpadLastClientY - trackpadTouchStartClientY, 2)
+			);
+			if (dist < 8) {
+				touchLongPressed = true;
+				dragStarted = true;
+				sendInteraction({ type: 'mousedown', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY), button: 'left' });
+			}
+		}, 600);
+	}
+
+	function handleTrackpadTouchMove(event: TouchEvent) {
+		if (!canvasElement) return;
+
+		if (event.touches.length >= 2 && trackpadTwoFingerActive) {
+			// Two-finger scroll
+			const t1 = event.touches[0];
+			const t2 = event.touches[1];
+			const centerX = (t1.clientX + t2.clientX) / 2;
+			const centerY = (t1.clientY + t2.clientY) / 2;
+			const deltaX = trackpadTwoFingerLastCenterX - centerX;
+			const deltaY = trackpadTwoFingerLastCenterY - centerY;
+			trackpadTwoFingerLastCenterX = centerX;
+			trackpadTwoFingerLastCenterY = centerY;
+			trackpadTwoFingerTotalDist += Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+			if (Math.abs(deltaX) > 0.3 || Math.abs(deltaY) > 0.3) {
+				const rect = canvasElement.getBoundingClientRect();
+				const scale = canvasElement.width / rect.width;
+				sendInteraction({ type: 'scroll', deltaX: deltaX * scale * 2, deltaY: deltaY * scale * 2 });
+			}
+			return;
+		}
+
+		if (event.touches.length !== 1 || !isMouseDown || trackpadTwoFingerActive) return;
+
+		const touch = event.touches[0];
+		const deltaClientX = touch.clientX - trackpadLastClientX;
+		const deltaClientY = touch.clientY - trackpadLastClientY;
+		trackpadLastClientX = touch.clientX;
+		trackpadLastClientY = touch.clientY;
+
+		// Cancel long-press if finger moved significantly
+		const totalDist = Math.sqrt(
+			Math.pow(touch.clientX - trackpadTouchStartClientX, 2) +
+			Math.pow(touch.clientY - trackpadTouchStartClientY, 2)
+		);
+		if (totalDist > 8 && longPressTimer) {
+			clearTimeout(longPressTimer);
+			longPressTimer = null;
+		}
+
+		// Convert screen delta → canvas delta and move cursor
+		const rect = canvasElement.getBoundingClientRect();
+		const scale = canvasElement.width / rect.width;
+		trackpadCursorX = Math.max(0, Math.min(canvasElement.width, trackpadCursorX + deltaClientX * scale));
+		trackpadCursorY = Math.max(0, Math.min(canvasElement.height, trackpadCursorY + deltaClientY * scale));
+
+		// Send mousemove so the browser sees hover state changes
+		sendInteraction({ type: 'mousemove', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY) });
+
+		// Update virtual cursor display
+		const pos = canvasToScreen(trackpadCursorX, trackpadCursorY);
+		onTouchCursorUpdate({ x: pos.x, y: pos.y, visible: true });
+	}
+
+	function handleTrackpadTouchEnd(event: TouchEvent) {
+		if (longPressTimer) { clearTimeout(longPressTimer); longPressTimer = null; }
+
+		const remainingTouches = event.touches.length;
+
+		if (trackpadTwoFingerActive) {
+			if (remainingTouches === 0) {
+				// All fingers lifted: check for two-finger tap → right click
+				const duration = Date.now() - trackpadTwoFingerStartTime;
+				if (duration < 300 && trackpadTwoFingerTotalDist < 20) {
+					sendInteraction({ type: 'rightclick', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY) });
+				}
+				trackpadTwoFingerActive = false;
+			} else if (remainingTouches === 1) {
+				// One finger remains: transition back to single-finger tracking
+				const touch = event.touches[0];
+				trackpadLastClientX = touch.clientX;
+				trackpadLastClientY = touch.clientY;
+				trackpadTouchStartClientX = touch.clientX;
+				trackpadTouchStartClientY = touch.clientY;
+				isMouseDown = true;
+				mouseDownTime = Date.now();
+				trackpadTwoFingerActive = false;
+			}
+			return;
+		}
+
+		if (!isMouseDown) return;
+
+		if (touchLongPressed && dragStarted) {
+			sendInteraction({ type: 'mouseup', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY), button: 'left' });
+		} else {
+			// Tap: short + minimal movement → left click at cursor position
+			const duration = Date.now() - mouseDownTime;
+			const moveDist = Math.sqrt(
+				Math.pow(trackpadLastClientX - trackpadTouchStartClientX, 2) +
+				Math.pow(trackpadLastClientY - trackpadTouchStartClientY, 2)
+			);
+			if (duration < 250 && moveDist < 10) {
+				sendInteraction({ type: 'click', x: Math.round(trackpadCursorX), y: Math.round(trackpadCursorY) });
+			}
+		}
+
+		isMouseDown = false;
+		dragStarted = false;
+		touchLongPressed = false;
+	}
+
+	// ── Touch event handlers (dispatch to scroll or trackpad mode) ────────────
+
 	// Touch event handlers
 	function handleTouchStart(event: TouchEvent, canvas: HTMLCanvasElement) {
 		if (!sessionId || event.touches.length === 0) return;
 		event.preventDefault();
 
+		if (touchMode === 'cursor') {
+			handleTrackpadTouchStart(event);
+			return;
+		}
+
+		// ── Scroll mode ──────────────────────────────────────────────────────────
+		if (event.touches.length > 1) return;
+
 		const coords = getCanvasCoordinates(event, canvas);
 		isMouseDown = true;
 		mouseDownTime = Date.now();
 		dragStartPos = { x: coords.x, y: coords.y };
 		dragCurrentPos = { x: coords.x, y: coords.y };
-		dragStarted = false; // Reset drag started flag
+		dragStarted = false;
+		touchLongPressed = false;
+		lastTouchCoords = { x: coords.x, y: coords.y };
+
+		// Long-press detection: after 500ms without significant movement → drag mode
+		longPressTimer = setTimeout(() => {
+			if (!isMouseDown || !dragStartPos) return;
+			const dist = dragCurrentPos
+				? Math.sqrt(
+						Math.pow(dragCurrentPos.x - dragStartPos.x, 2) +
+						Math.pow(dragCurrentPos.y - dragStartPos.y, 2)
+					)
+				: 0;
+			if (dist < 10) {
+				touchLongPressed = true;
+				dragStarted = true;
+				sendInteraction({ type: 'mousedown', x: dragStartPos.x, y: dragStartPos.y, button: 'left' });
+			}
+		}, 500);
 	}
 
 	function handleTouchMove(event: TouchEvent, canvas: HTMLCanvasElement) {
-		if (!sessionId || event.touches.length === 0 || !isMouseDown || !dragStartPos) return;
+		if (!sessionId || event.touches.length === 0) return;
 		event.preventDefault();
 
+		if (touchMode === 'cursor') {
+			handleTrackpadTouchMove(event);
+			return;
+		}
+
+		// ── Scroll mode ──────────────────────────────────────────────────────────
+		if (!isMouseDown || !dragStartPos) return;
+
 		const coords = getCanvasCoordinates(event, canvas);
 		dragCurrentPos = { x: coords.x, y: coords.y };
 
-		const dragDistance = Math.sqrt(
+		const dist = Math.sqrt(
 			Math.pow(coords.x - dragStartPos.x, 2) + Math.pow(coords.y - dragStartPos.y, 2)
 		);
 
-		if (dragDistance > 15) {
-			// Send mousedown on first drag detection
-			if (!dragStarted) {
-				sendInteraction({
-					type: 'mousedown',
-					x: dragStartPos.x,
-					y: dragStartPos.y,
-					button: 'left'
-				});
-				dragStarted = true;
-			}
+		if (dist > 10 && longPressTimer) {
+			clearTimeout(longPressTimer);
+			longPressTimer = null;
+		}
 
+		if (touchLongPressed) {
 			isDragging = true;
-			// Send mousemove to continue dragging (mouse is already down)
-			sendInteraction({
-				type: 'mousemove',
-				x: coords.x,
-				y: coords.y
-			});
+			sendInteraction({ type: 'mousemove', x: coords.x, y: coords.y });
+		} else {
+			if (lastTouchCoords) {
+				const deltaX = lastTouchCoords.x - coords.x;
+				const deltaY = lastTouchCoords.y - coords.y;
+				sendInteraction({ type: 'scroll', deltaX, deltaY });
+			}
+			lastTouchCoords = { x: coords.x, y: coords.y };
 		}
 	}
 
 	function handleTouchEnd(event: TouchEvent, canvas: HTMLCanvasElement) {
-		if (!sessionId || !isMouseDown) return;
+		if (!sessionId) return;
 		event.preventDefault();
 
-		if (dragStartPos) {
-			const endPos = dragCurrentPos || dragStartPos;
+		if (touchMode === 'cursor') {
+			handleTrackpadTouchEnd(event);
+			return;
+		}
 
-			// If drag was started (mousedown was sent), send mouseup
-			if (dragStarted) {
-				sendInteraction({
-					type: 'mouseup',
-					x: endPos.x,
-					y: endPos.y,
-					button: 'left'
-				});
-			} else {
-				// No drag occurred, this is a tap/click
+		// ── Scroll mode ──────────────────────────────────────────────────────────
+		if (!isMouseDown) return;
+
+		if (longPressTimer) { clearTimeout(longPressTimer); longPressTimer = null; }
+
+		if (touchLongPressed && dragStarted) {
+			const endPos = dragCurrentPos || dragStartPos;
+			if (endPos) sendInteraction({ type: 'mouseup', x: endPos.x, y: endPos.y, button: 'left' });
+		} else if (!isDragging && dragStartPos) {
+			const touchDuration = Date.now() - mouseDownTime;
+			const dist = dragCurrentPos
+				? Math.sqrt(
+						Math.pow(dragCurrentPos.x - dragStartPos.x, 2) +
+						Math.pow(dragCurrentPos.y - dragStartPos.y, 2)
+					)
+				: 0;
+			if (touchDuration < 300 && dist < 15) {
 				sendInteraction({ type: 'click', x: dragStartPos.x, y: dragStartPos.y });
 			}
 		}
@@ -991,6 +1347,8 @@
 		dragStartPos = null;
 		dragCurrentPos = null;
 		dragStarted = false;
+		touchLongPressed = false;
+		lastTouchCoords = null;
 	}
 
 	function getCanvasElement() {
@@ -1039,6 +1397,11 @@
 
 	onDestroy(() => {
 		stopHealthCheck(); // Stop health monitoring
+		canvasSnapshots.clear(); // Free snapshot memory
+		if (longPressTimer) {
+			clearTimeout(longPressTimer);
+			longPressTimer = null;
+		}
 		if (webCodecsService) {
 			webCodecsService.destroy();
 			webCodecsService = null;