fix: reserve camera preview before capture exclusions

Author: Satyam Raj

electron/cameraPreview.test.ts

@@ -1,11 +1,13 @@
 import { EventEmitter } from "node:events";
 import type { BrowserWindow, WebContents } from "electron";
 import { describe, expect, it, vi } from "vitest";
+import { collectMacCaptureExcludedWindowIds } from "../src/lib/nativeMacRecording";
 import { CameraPreviewController } from "./cameraPreview";
 
 function setup() {
 	const owner = Object.assign(new EventEmitter(), { send: vi.fn() });
 	const overlay = Object.assign(new EventEmitter(), {
+		getMediaSourceId: () => "window:123:0",
 		webContents: { send: vi.fn() },
 		showInactive: vi.fn(),
 		hide: vi.fn(),
@@ -24,6 +26,32 @@ function setup() {
 const jpeg = "data:image/jpeg;base64,/9j/";
 
 describe("floating camera preview lifecycle", () => {
+	it("reserves the same exclusion ID before the renderer enables the preview", () => {
+		const { preview, sender, overlay, create } = setup();
+		const reserved = preview.ensure(sender);
+		const excludedIds = collectMacCaptureExcludedWindowIds([reserved!.getMediaSourceId()]);
+		expect(excludedIds).toContain(123);
+		overlay.emit("ready-to-show");
+		expect(overlay.showInactive).not.toHaveBeenCalled();
+		preview.configure(sender, true, true);
+		expect(preview.ensure(sender)).toBe(reserved);
+		expect(create).toHaveBeenCalledOnce();
+		expect(overlay.showInactive).toHaveBeenCalledOnce();
+		expect(excludedIds).toContain(123);
+	});
+
+	it("ensuring an existing preview preserves visibility and refuses a different owner", () => {
+		const { preview, sender, overlay, create } = setup();
+		preview.configure(sender, true, true);
+		overlay.emit("ready-to-show");
+		expect(preview.ensure(sender)).toBe(overlay);
+		expect(preview.ensure({} as WebContents)).toBeNull();
+		preview.frame(sender, jpeg);
+		expect(overlay.webContents.send).toHaveBeenCalledWith("camera-preview:frame", jpeg);
+		expect(overlay.hide).not.toHaveBeenCalled();
+		expect(create).toHaveBeenCalledOnce();
+	});
+
 	it("waits for the window to paint, then shows without taking focus", () => {
 		const { preview, sender, overlay } = setup();
 		preview.configure(sender, true, true);

electron/cameraPreview.ts

@@ -24,8 +24,9 @@ export class CameraPreviewController {
 		) => void,
 	) {}
 
-	configure(owner: WebContents, enabled: boolean, visible: boolean): void {
-		if (this.owner && this.owner !== owner) return;
+	/** Reserve the capture-exclusion window before renderer configuration arrives. */
+	ensure(owner: WebContents): BrowserWindow | null {
+		if (this.owner && this.owner !== owner) return null;
 		if (!this.owner) {
 			this.owner = owner;
 			this.onOwnerDestroyed = () => {
@@ -49,9 +50,15 @@ export class CameraPreviewController {
 				if (this.visible) this.window?.showInactive();
 			});
 		}
+		return this.window;
+	}
+
+	configure(owner: WebContents, enabled: boolean, visible: boolean): void {
+		const previewWindow = this.ensure(owner);
+		if (!previewWindow) return;
 		this.visible = enabled && visible;
-		if (this.visible && this.ready) this.window.showInactive();
-		else if (!this.visible) this.window.hide();
+		if (this.visible && this.ready) previewWindow.showInactive();
+		else if (!this.visible) previewWindow.hide();
 	}
 
 	hide(sender: WebContents): void {

electron/ipc/handlers.ts

@@ -2147,6 +2147,7 @@ export function registerIpcHandlers(
 	 * pick would record them unless the picker is told to leave them out.
 	 */
 	function macPickerExcludedWindowIds() {
+		ensureMacCameraPreviewWindow();
 		const appWindowSourceIds = [getMainWindow(), getNotesWindow(), getCameraPreviewWindow()]
 			.filter((window): window is BrowserWindow => !!window && !window.isDestroyed())
 			.map((window) => window.getMediaSourceId());
@@ -2480,6 +2481,17 @@ export function registerIpcHandlers(
 		createCameraPreviewWindow,
 		resizeCameraPreviewWindow,
 	);
+	function ensureMacCameraPreviewWindow() {
+		const hud = getMainWindow();
+		if (
+			process.platform === "darwin" &&
+			hud &&
+			!hud.isDestroyed() &&
+			new URL(hud.webContents.getURL()).searchParams.get("windowType") === "hud-overlay"
+		) {
+			cameraPreview.ensure(hud.webContents);
+		}
+	}
 	ipcMain.handle("camera-preview:configure", (event, enabled: unknown, visible: unknown) => {
 		if (
 			process.platform !== "darwin" ||
@@ -3175,6 +3187,7 @@ export function registerIpcHandlers(
 				normalizeCursorCaptureMode(request.cursor?.mode) ?? "editable-overlay";
 			// A source from Apple's picker records through the session that holds the pick,
 			// and needs no Screen Recording grant -- so nothing here may go near one.
+			ensureMacCameraPreviewWindow();
 			const pickerSession = isMacPickerSourceId(request.source.sourceId) ? macPickerSession : null;
 			// Normally caught by `get-selected-source` first; this is the last word (#965).
 			pickerSession?.forgetSelectionUnlessExcluding(macPickerExcludedWindowIds());

technical-documentation/testing/manual-e2e-checklist.md

@@ -999,3 +999,5 @@ These checks are the human slice: an agent cannot click Apple's picker (see abov
 | 2026-10-19 | dev `codex/macos-floating-camera-preview`, rebased on `main` @ `3620cf8`, plus #1288 review changes; Electron 41.2.1; native helper rebuilt directly with `swiftc` + macOS 26.5 SDK | macOS 26.7, Apple M5 Pro, MacBook Pro Camera | **Partial — preview review slice passed** | Computer-use verified the complete rounded rectangular camera frame, aspect-preserving resize, camera-off hiding the HUD preview control, and show/hide during a finalized camera take. In the same take, after 5 s settling per condition, 30 s process-tree CPU deltas were **17.5% hidden / 22.3% shown** (100%=one core; includes Electron children and capture helper). Native `recording-stopped` reported **0 droppedVideoFrames over the entire take**, covering both intervals; this counts screen-writer backpressure/append failures, not upstream capture or webcam drops. Screen 1 at 3024×1964, saved webcam verified 1920×1080 (30 fps requested); mic/system audio off, system cursor. One sequential pair, no statistical claim. **Skipped:** Apple’s picker, fullscreen Spaces, other cameras/platforms, restart/cancel, export, exhaustive exclusion and remaining checklist. |
 
 | 2026-10-19 | dev #1288 on `8c2608d9` + preview lifetime/quit fixes; Electron 41.2.1 | macOS 26.7, Apple Silicon, MacBook Pro Camera | **Partial — lifecycle slice passed** | Computer-use camera off/on removed/restored the HUD preview control. Normal Cmd+Q exited the OpenScreen Electron process with the preview enabled. Unit tests verify the same preview window survives initial camera-off and repeated toggles, with one owner-destruction listener and cleanup on HUD destruction. **Skipped:** recording, export, capture-exclusion measurements, other platforms and remaining checklist; no native capture changes in this slice. |
+
+| 2026-10-21 | dev #1288 on `20975d30` + synchronous preview reservation before capture exclusions; Electron 41.2.1; existing helper rebuilt from this branch on Oct 19 | macOS 26.7, Apple Silicon, MacBook Pro Camera | **Partial — capture-exclusion ordering slice passed** | Computer-use started native display recording with the preview hidden, showed it during the take and finalized into the editor. Helper diagnostics resolved both requested app window IDs and reported zero screen-writer drops; a decoded late screen frame contained no floating preview. Unit regression covers reserving the exclusion window before any renderer configuration and reusing it when enabled later without altering an existing preview’s visibility. **Skipped:** Apple’s picker (ordering path checked in code), forced renderer-effect race on desktop (covered by unit regression), other platforms, export, exhaustive frame-by-frame exclusion and remaining checklist. |