fix(recording): record the window Linux users actually pick

Choosing a window on Wayland produced a recording of the whole screen.
Two independent defects, both proven on a real GNOME 46 session.

The portal restore token pinned the first grant forever. A token is bound
to the source it was minted for, so once any monitor had been approved the
portal restored that monitor on every later run and stopped raising its
picker — and SelectSources has no parameter naming a source, so the app had
no way to ask for anything else. GNOME's permission store held ours as
source_type=1 (MONITOR, CMN:0x1468), created 1.7s into one full-screen
recording and replayed 93ms into a later one. The token is gone, and
PersistMode is DoNot so we stop littering that store.

SPA_META_VideoCrop was never requested. mutter pins a window stream to its
monitor's size — "we cannot set the stream size to the exact size of the
window, because windows can be resized, whereas streams cannot" — and
reports the window's live rectangle in that meta, but only writes it if the
consumer asked. We never asked, so a window arrived as a monitor-sized
buffer: measured 1920x982 of content at (0,0) inside a 1920x1080 frame,
98px of black below. The declaration and per-frame read follow OBS and
WebRTC; the validation follows WebRTC's stricter posture because the
pointer goes straight to swscale.

Neither reference handles a mid-recording resize — both let the frame size
vary per frame, which an MP4 track cannot. The crop is latched at encoder
open, the live origin is followed but clamped inside the buffer, and the
first divergence is reported once as `crop-changed`. The encoder is opened
from the first frame carrying a usable crop rather than the first frame at
all: mutter's rectangle intersection reports success on an empty result and
records a frame synchronously from enable(), so committing to frame zero
could pin a window recording at monitor size again.

Since the portal owns the choice, the in-app picker is gone on Linux: it
could not steer the capture and only raised a second portal dialog whose
grant was discarded. Both entry points — the HUD and the editor's Rec stage
— now ask one shared hook, and the tray names what the portal granted
instead of echoing a selection the capture never heard of.

The picker also now comes before the countdown. The helper negotiates the
portal, reports `source-selected`, and waits for `record` on stdin; the
stream is not connected until then, so nothing is captured and WirePlumber
cannot suspend an idle node out from under us. Preparing is optional and
best-effort — start still negotiates on its own — so every other platform
and any future caller is unaffected.

Author: EtienneLescot

electron/electron-env.d.ts

@@ -192,6 +192,23 @@ interface Window {
 			reason?: "unsupported-platform" | "missing-helper" | string;
 			error?: string;
 		}>;
+		/**
+		 * Raises the compositor's picker and holds the grant until the recording
+		 * actually starts, so a countdown can run AFTER the user has chosen.
+		 *
+		 * Best-effort: a `success: false` means "start normally", never "fail".
+		 */
+		prepareNativeLinuxRecording: (
+			request: import("../src/lib/nativeLinuxRecording").NativeLinuxRecordingRequest,
+		) => Promise<{
+			success: boolean;
+			recordingId?: number;
+			sourceKind?: "monitor" | "window" | "virtual" | null;
+			reason?: string;
+			error?: string;
+		}>;
+		/** Drops a prepared session when the countdown was abandoned. */
+		cancelNativeLinuxPrepare: () => Promise<{ success: boolean }>;
 		startNativeLinuxRecording: (
 			request: import("../src/lib/nativeLinuxRecording").NativeLinuxRecordingRequest,
 		) => Promise<import("../src/lib/nativeLinuxRecording").NativeLinuxRecordingStartResult>;

electron/ipc/handlers.ts

@@ -62,7 +62,10 @@ import {
 	readCursorTelemetryFile as readCursorTelemetryFileFrom,
 } from "../media/cursorSidecar";
 import { findMediaLinksByFingerprint, registerMediaLinks } from "../media/mediaLinksRegistry";
-import { LinuxNativeCaptureSession } from "../native-bridge/capture/linuxNativeCaptureSession";
+import {
+	type LinuxCaptureSourceKind,
+	LinuxNativeCaptureSession,
+} from "../native-bridge/capture/linuxNativeCaptureSession";
 import { createCursorRecordingSession } from "../native-bridge/cursor/recording/factory";
 import { requestMacCursorAccessibilityAccess } from "../native-bridge/cursor/recording/macNativeCursorRecordingSession";
 import { findPipeWireCursorHelperPath } from "../native-bridge/cursor/recording/pipeWireCursorRecordingSession";
@@ -539,48 +542,83 @@ let activeMacCaptureBounds: Rectangle | null = null;
 let linuxNativeCaptureSession: LinuxNativeCaptureSession | null = null;
 let linuxNativeCaptureRecordingId: number | null = null;
 let linuxNativeCaptureCursorMode: CursorCaptureMode = "editable-overlay";
+/** What the portal granted for the running capture, for the tray's label. */
+let linuxNativeCaptureSourceLabel: string | null = null;
 /**
- * The portal's restore token, kept between recordings.
+ * A portal session negotiated ahead of the countdown, waiting to be armed.
  *
- * Without it the compositor raises its source picker on EVERY recording, which
- * on Wayland is the single most intrusive thing about capturing at all. The
- * portal issues the token only after a successful session and honours it until
- * the user revokes it in system settings, so it is safe to persist and useless
- * to anyone else.
+ * Held here rather than in the renderer because the helper is a child process of
+ * THIS process: a renderer that reloads, or a countdown abandoned without a
+ * cancel, would otherwise leak a live ScreenCast session — the compositor's
+ * "screen is being shared" indicator with nothing recording behind it.
  */
-const LINUX_RESTORE_TOKEN_FILE = "linux-capture-restore-token.json";
+let preparedLinuxCapture: { session: LinuxNativeCaptureSession; outputPath: string } | null = null;
 
-async function readLinuxRestoreToken(): Promise<string | undefined> {
-	try {
-		const raw = await fs.readFile(
-			path.join(app.getPath("userData"), LINUX_RESTORE_TOKEN_FILE),
-			"utf-8",
-		);
-		const parsed = JSON.parse(raw) as { restoreToken?: unknown };
-		return typeof parsed.restoreToken === "string" && parsed.restoreToken
-			? parsed.restoreToken
-			: undefined;
-	} catch {
-		// Absent or unreadable: the picker appears, which is the old behaviour
-		// and not worth failing a recording over.
-		return undefined;
+/**
+ * Claims the prepared session when it matches the recording about to start.
+ *
+ * A mismatch means the prepare was for a recording that never happened, so it is
+ * discarded rather than reused: arming it would record against the wrong output
+ * path, and leaving it would strand a portal session.
+ */
+function takePreparedLinuxSession(outputPath: string): LinuxNativeCaptureSession | null {
+	const prepared = preparedLinuxCapture;
+	if (!prepared) {
+		return null;
+	}
+	preparedLinuxCapture = null;
+	if (prepared.outputPath === outputPath) {
+		return prepared.session;
 	}
+	console.warn("[native-linux] discarding a prepared session for a different recording");
+	prepared.session.discard();
+	return null;
 }
 
-async function writeLinuxRestoreToken(restoreToken?: string) {
-	if (!restoreToken) {
+/** Tears down a prepared-but-unarmed session, e.g. an abandoned countdown. */
+function discardPreparedLinuxCapture(reason: string) {
+	if (!preparedLinuxCapture) {
 		return;
 	}
-	try {
-		await fs.writeFile(
-			path.join(app.getPath("userData"), LINUX_RESTORE_TOKEN_FILE),
-			JSON.stringify({ restoreToken }, null, 2),
-			"utf-8",
-		);
-	} catch (error) {
-		console.warn("Could not persist the Linux portal restore token:", error);
+	console.info(`[native-linux] discarding the prepared capture: ${reason}`);
+	preparedLinuxCapture.session.discard();
+	preparedLinuxCapture = null;
+}
+
+/**
+ * Names what the portal handed over, for the tray tooltip.
+ *
+ * There is no window title to show: the ScreenCast portal reports a kind and a
+ * PipeWire node id, never a name. Reporting the kind is the most that can be
+ * said honestly, and an unknown kind stays unknown — calling it "Screen" would
+ * be the same guess that put a window's name on a full-screen recording.
+ */
+function linuxSourceLabel(kind?: LinuxCaptureSourceKind): string {
+	switch (kind) {
+		case "window":
+			return "Window";
+		case "monitor":
+			return "Screen";
+		case "virtual":
+			return "Virtual display";
+		default:
+			return "Screen recording";
 	}
 }
+/**
+ * NO PORTAL RESTORE TOKEN IS KEPT, AND THAT IS DELIBERATE.
+ *
+ * A token used to be persisted here so the compositor's picker would not appear
+ * on every recording. It is gone because it made "record this window" record the
+ * whole screen instead. A restore token is bound to the source it was minted
+ * for, so once any monitor had been approved the portal restored that monitor on
+ * every later run and stopped raising the picker at all — and `SelectSources`
+ * has no parameter naming a source, so the app could not ask for anything else.
+ * On Wayland the picker IS the source chooser; suppressing it left the user with
+ * no way to change what they were recording.
+ *
+ * Answering the picker each time is the cost of being able to choose at all.
+ */
 
 // ponytail: the sidecar readers used to live here, ~150 lines of parsing wedged
 // between the capture state machine and the asset-path helpers, reachable only
@@ -1653,6 +1691,19 @@ export function registerIpcHandlers(
 	});
 
 	ipcMain.handle("open-source-selector", async () => {
+		// Nothing to open on Linux WHEN THE NATIVE HELPER IS THERE. The selector's
+		// own `desktopCapturer.getSources()` raises a portal dialog — a SECOND
+		// one, for a session that is thrown away — and whatever it returns cannot
+		// reach the helper, because `SelectSources` has no parameter naming a
+		// source. Refusing keeps that dialog from appearing at all.
+		//
+		// Without the helper the recorder falls back to Chromium's capture, which
+		// DOES consume a source id, so the picker has to stay reachable there or
+		// that path could never start.
+		if (process.platform === "linux" && findPipeWireCursorHelperPath()) {
+			return { opened: false, reason: "portal-owns-selection" };
+		}
+
 		const access = await requestScreenAccess();
 		if (!access.granted) {
 			if (process.platform === "darwin" && access.status !== "not-determined") {
@@ -1802,20 +1853,29 @@ export function registerIpcHandlers(
 			: { success: true, available: false, reason: "missing-helper" };
 	});
 
+	/**
+	 * Raises the compositor's picker and stops there, holding the grant.
+	 *
+	 * Best-effort by contract: every failure returns `success: false` rather than
+	 * throwing, because the caller's fallback is simply to start normally and get
+	 * the picker after its countdown — the behaviour that shipped before this
+	 * existed. Nothing downstream may depend on a prepare having succeeded.
+	 */
 	ipcMain.handle(
-		"start-native-linux-recording",
+		"prepare-native-linux-recording",
 		async (_, request: NativeLinuxRecordingRequest) => {
+			if (process.platform !== "linux") {
+				return { success: false, reason: "unsupported-platform" };
+			}
+			if (linuxNativeCaptureSession) {
+				return { success: false, reason: "already-recording" };
+			}
+			discardPreparedLinuxCapture("superseded by a new prepare");
+
 			try {
-				if (process.platform !== "linux") {
-					return { success: false, error: "Native Linux capture requires Linux." };
-				}
-				if (linuxNativeCaptureSession) {
-					return { success: false, error: "Native Linux capture is already running." };
-				}
 				if (!findPipeWireCursorHelperPath()) {
-					return { success: false, error: "Native Linux capture helper is not available." };
+					return { success: false, reason: "missing-helper" };
 				}
-
 				const recordingId =
 					typeof request?.recordingId === "number" && Number.isFinite(request.recordingId)
 						? request.recordingId
@@ -1825,7 +1885,6 @@ export function registerIpcHandlers(
 					normalizeCursorCaptureMode(request?.cursor?.mode) ?? "editable-overlay";
 
 				await fs.mkdir(RECORDINGS_DIR, { recursive: true });
-				const restoreToken = await readLinuxRestoreToken();
 
 				const session = new LinuxNativeCaptureSession({
 					outputPath,
@@ -1843,28 +1902,112 @@ export function registerIpcHandlers(
 						},
 					},
 					maxCursorSamples: MAX_CURSOR_SAMPLES,
-					...(restoreToken ? { restoreToken } : {}),
+					deferStart: true,
 				});
 
+				await session.start();
+				// The picker is up now. No timeout: a human is reading a dialog.
+				await session.waitUntilSourceSelected();
+
+				preparedLinuxCapture = { session, outputPath };
+				return {
+					success: true,
+					recordingId,
+					sourceKind: session.grantedSourceKind ?? null,
+				};
+			} catch (error) {
+				console.warn("Could not prepare the native Linux capture:", error);
+				discardPreparedLinuxCapture("prepare failed");
+				return { success: false, error: String(error) };
+			}
+		},
+	);
+
+	/** Drops a prepared session, e.g. when the countdown was cancelled. */
+	ipcMain.handle("cancel-native-linux-prepare", async () => {
+		discardPreparedLinuxCapture("cancelled by the renderer");
+		return { success: true };
+	});
+
+	ipcMain.handle(
+		"start-native-linux-recording",
+		async (_, request: NativeLinuxRecordingRequest) => {
+			try {
+				if (process.platform !== "linux") {
+					return { success: false, error: "Native Linux capture requires Linux." };
+				}
+				if (linuxNativeCaptureSession) {
+					return { success: false, error: "Native Linux capture is already running." };
+				}
+				if (!findPipeWireCursorHelperPath()) {
+					return { success: false, error: "Native Linux capture helper is not available." };
+				}
+
+				const recordingId =
+					typeof request?.recordingId === "number" && Number.isFinite(request.recordingId)
+						? request.recordingId
+						: Date.now();
+				const outputPath = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
+				const cursorCaptureMode =
+					normalizeCursorCaptureMode(request?.cursor?.mode) ?? "editable-overlay";
+
+				await fs.mkdir(RECORDINGS_DIR, { recursive: true });
+
+				// A session prepared before the countdown, if there was one. Taking
+				// it here rather than requiring it is what keeps every caller
+				// working: a path that never prepared still gets a full start
+				// below, just with the picker after its countdown instead of
+				// before. Nothing has to know which path it is on.
+				const prepared = takePreparedLinuxSession(outputPath);
+				const session =
+					prepared ??
+					new LinuxNativeCaptureSession({
+						outputPath,
+						cursorMode: portalCursorMode(cursorCaptureMode),
+						fps: request.video.fps,
+						...(request.video.bitrate ? { bitrate: request.video.bitrate } : {}),
+						audio: {
+							system: { enabled: request.audio.system.enabled },
+							microphone: {
+								enabled: request.audio.microphone.enabled,
+								...(request.audio.microphone.deviceName
+									? { deviceName: request.audio.microphone.deviceName }
+									: {}),
+								gain: request.audio.microphone.gain,
+							},
+						},
+						maxCursorSamples: MAX_CURSOR_SAMPLES,
+					});
+
 				console.info("[native-linux] starting capture", {
 					outputPath,
+					prepared: Boolean(prepared),
 					cursor: { mode: cursorCaptureMode },
 					audio: request.audio,
 					video: request.video,
 				});
 
-				await session.start();
-				// Blocks until the user answers the portal picker, which has no
-				// upper bound — the countdown UI is already showing by now.
+				if (!prepared) {
+					await session.start();
+					// Blocks until the user answers the portal picker, which has no
+					// upper bound. On this path the countdown has already run.
+					await session.waitUntilSourceSelected();
+				}
+				// Idempotent, and a no-op for a session that was not deferred.
+				session.arm();
 				await session.waitUntilCapturing();
 
 				linuxNativeCaptureSession = session;
 				linuxNativeCaptureRecordingId = recordingId;
 				linuxNativeCaptureCursorMode = cursorCaptureMode;
 
-				const source = selectedSource || { name: "Screen" };
+				// The portal's answer, not an in-app selection — on Wayland there
+				// is none to have. This used to read `selectedSource || { name:
+				// "Screen" }`, so the tray confidently displayed the name of a
+				// window the capture had never been told about.
+				linuxNativeCaptureSourceLabel = linuxSourceLabel(session.grantedSourceKind);
 				if (onRecordingStateChange) {
-					onRecordingStateChange(true, source.name);
+					onRecordingStateChange(true, linuxNativeCaptureSourceLabel);
 				}
 
 				return { success: true, recordingId, path: outputPath };
@@ -1915,7 +2058,6 @@ export function registerIpcHandlers(
 			}
 
 			const result = await session.stop();
-			await writeLinuxRestoreToken(result.restoreToken);
 
 			// The helper collects cursor samples itself, from the same portal
 			// session that produced the pixels, so there is no separate sampler
@@ -1965,9 +2107,10 @@ export function registerIpcHandlers(
 			linuxNativeCaptureSession = null;
 			linuxNativeCaptureRecordingId = null;
 			linuxNativeCaptureCursorMode = "editable-overlay";
-			const source = selectedSource || { name: "Screen" };
+			const stoppedLabel = linuxNativeCaptureSourceLabel ?? linuxSourceLabel();
+			linuxNativeCaptureSourceLabel = null;
 			if (onRecordingStateChange) {
-				onRecordingStateChange(false, source.name);
+				onRecordingStateChange(false, stoppedLabel);
 			}
 		}
 	});