fix(linux): keep the portal first and capture X11 through MIT-SHM

Review follow-up for #1328.

- Direct X11 capture only when the ScreenCast portal does not answer on an
  X11 session. The helper decides and reports it as `backend` on `ready`;
  the main process asks it once per process, and never on Wayland.
- Frames come through a server-created MIT-SHM segment instead of the X
  socket, with plain GetImage kept for servers that cannot share memory.
- Window capture reads the root over the window rectangle, clipped to the
  screen: no BadMatch past the edge, and covered areas show what is on screen.
- A non-zero helper exit after `capture-stopped` keeps the finalized file
  again, as on Wayland.
- Clicks made during the countdown are dropped, and the French CLI page
  loses its doubled "Wayland".

Author: EtienneLescot

README.md

@@ -213,7 +213,7 @@ You may need to grant screen recording permissions depending on your desktop env
 
 Everything in the editor and export is the same on macOS, Windows, and Linux: zooms, backgrounds, motion blur, crop/trim/speed, blur regions, annotations, auto-captions, AI editing, projects, export, and all languages. All three now record through a native capture pipeline; the remaining differences are narrower than they used to be:
 
-- **Native recording**: macOS (ScreenCaptureKit), Windows (Windows Graphics Capture), and Linux (direct X11 capture, or PipeWire via the ScreenCast portal on Wayland) all record through a native pipeline for higher quality and clean window-level capture. On Linux the browser pipeline stays as an automatic fallback if the helper isn't available.
+- **Native recording**: macOS (ScreenCaptureKit), Windows (Windows Graphics Capture), and Linux (PipeWire via the ScreenCast portal, or direct X11 capture on an X11 desktop without one) all record through a native pipeline for higher quality and clean window-level capture. On Linux the browser pipeline stays as an automatic fallback if the helper isn't available.
 - **Custom cursors**: on macOS and Windows the real cursor is captured with shape, type, and clicks. On X11, the helper captures cursor shape through XFixes and mouse buttons through XInput2, without access to `/dev/input`. On Wayland, Linux captures position and cursor shape through the portal, so the editable cursor overlay works there too. Click effects work on Wayland as well, but not through the portal — Wayland exposes no portal for mouse buttons, so the capture helper reads the left button from evdev, which needs read access to your mouse: a udev rule for pointer devices (recommended) or the `input` group, set up as [Mouse clicks on Wayland](https://getopenscreen.com/docs/installation#mouse-clicks-on-wayland) shows. Without that, recording is unaffected and every cursor sample is simply a move.
 - **Webcam**: every platform saves the webcam as a separate file next to the screen recording. Windows captures it natively in the recording helper; macOS and Linux record it in the app. It works as a picture-in-picture overlay on all three.
 - **System audio** support varies by OS:

electron/ipc/handlers.ts

@@ -27,6 +27,7 @@ import {
 import type { CliSourcesResult } from "../../src/lib/cliContracts";
 import { pickRecordingSource } from "../../src/lib/cliSourcePick";
 import {
+	type NativeLinuxCaptureSource,
 	type NativeLinuxRecordingRequest,
 	portalCursorMode,
 } from "../../src/lib/nativeLinuxRecording";
@@ -2091,9 +2092,9 @@ export function registerIpcHandlers(
 				process.platform,
 				sources,
 				{
-					waylandPortal: linuxPortalOwnsSources(
+					waylandPortal: await linuxPortalOwnsSources(
 						process.platform,
-						Boolean(findPipeWireCursorHelperPath()),
+						findPipeWireCursorHelperPath(),
 						process.env,
 					),
 				},
@@ -2244,7 +2245,7 @@ export function registerIpcHandlers(
 	ipcMain.handle("get-selected-source", async () => {
 		const previousSelectedSource = selectedSource;
 		if (
-			linuxPortalOwnsSources(process.platform, Boolean(findPipeWireCursorHelperPath()), process.env)
+			await linuxPortalOwnsSources(process.platform, findPipeWireCursorHelperPath(), process.env)
 		) {
 			selectedSource = null;
 			selectedDesktopSource = null;
@@ -2459,6 +2460,13 @@ export function registerIpcHandlers(
 		return access;
 	});
 
+	/** The selection the direct X11 backend records; the portal path takes none. */
+	async function linuxX11Source(): Promise<{ source?: NativeLinuxCaptureSource }> {
+		const helperPath = findPipeWireCursorHelperPath();
+		if (!helperPath || (await linuxCaptureBackend(helperPath, process.env)) !== "x11") return {};
+		return { source: resolveX11CaptureSource(selectedSource, screen.getAllDisplays()) };
+	}
+
 	ipcMain.handle("open-source-selector", async () => {
 		// Nothing to open on Wayland WHEN THE NATIVE HELPER IS THERE. The selector's
 		// own `desktopCapturer.getSources()` raises a portal dialog — a SECOND
@@ -2470,7 +2478,7 @@ export function registerIpcHandlers(
 		// DOES consume a source id, so the picker has to stay reachable there or
 		// that path could never start.
 		if (
-			linuxPortalOwnsSources(process.platform, Boolean(findPipeWireCursorHelperPath()), process.env)
+			await linuxPortalOwnsSources(process.platform, findPipeWireCursorHelperPath(), process.env)
 		) {
 			return { opened: false, reason: "portal-owns-selection" };
 		}
@@ -2623,7 +2631,12 @@ export function registerIpcHandlers(
 
 		const helperPath = findPipeWireCursorHelperPath();
 		return helperPath
-			? { success: true, available: true, helperPath, backend: linuxCaptureBackend(process.env) }
+			? {
+					success: true,
+					available: true,
+					helperPath,
+					backend: await linuxCaptureBackend(helperPath, process.env),
+				}
 			: { success: true, available: false, reason: "missing-helper" };
 	});
 
@@ -2663,9 +2676,7 @@ export function registerIpcHandlers(
 				await fs.mkdir(RECORDINGS_DIR, { recursive: true });
 
 				const session = new LinuxNativeCaptureSession({
-					...(linuxCaptureBackend(process.env) === "x11"
-						? { source: resolveX11CaptureSource(selectedSource, screen.getAllDisplays()) }
-						: {}),
+					...(await linuxX11Source()),
 					outputPath,
 					cursorMode: portalCursorMode(cursorCaptureMode),
 					fps: request.video.fps,
@@ -2752,9 +2763,7 @@ export function registerIpcHandlers(
 				const session =
 					prepared ??
 					new LinuxNativeCaptureSession({
-						...(linuxCaptureBackend(process.env) === "x11"
-							? { source: resolveX11CaptureSource(selectedSource, screen.getAllDisplays()) }
-							: {}),
+						...(await linuxX11Source()),
 						outputPath,
 						cursorMode: portalCursorMode(cursorCaptureMode),
 						fps: request.video.fps,
@@ -5150,7 +5159,7 @@ export function registerIpcHandlers(
 			broadcastSelectedSource(before.source);
 		};
 		if (
-			linuxPortalOwnsSources(process.platform, Boolean(findPipeWireCursorHelperPath()), process.env)
+			await linuxPortalOwnsSources(process.platform, findPipeWireCursorHelperPath(), process.env)
 		) {
 			// The portal asks the user once the take starts: nothing here to select.
 		} else {

electron/native-bridge/capture/linuxNativeCaptureSession.test.ts

@@ -172,38 +172,6 @@ afterEach(() => {
 });
 
 describe("LinuxNativeCaptureSession", () => {
-	it.each([
-		true,
-		false,
-	])("rejects an interrupted take even with a finalized partial file (stop pending: %s)", async (stopBeforeExit) => {
-		const session = newSession();
-		await startReady(session);
-		const pending = stopBeforeExit
-			? expect(session.stop()).rejects.toThrow("The selected X11 window is no longer viewable")
-			: null;
-		helper.emitEvent({
-			event: "capture-stopped",
-			timestampMs: 1_100,
-			path: "/tmp/recording.mp4",
-			durationMs: 33,
-			frames: 2,
-			dropped: 0,
-		});
-		helper.emitEvent({
-			event: "error",
-			timestampMs: 1_100,
-			code: "x11-capture-failed",
-			message: "The selected X11 window is no longer viewable",
-		});
-		await flushStdout();
-		helper.emit("exit", 1, null);
-		if (pending) {
-			await pending;
-		} else {
-			await expect(session.stop()).rejects.toThrow("The selected X11 window is no longer viewable");
-		}
-	});
-
 	/**
 	 * The regression this file exists for. A restore token is bound to the source
 	 * it was minted for, so replaying one made the portal hand back an

electron/native-bridge/capture/linuxNativeCaptureSession.ts

@@ -120,7 +120,6 @@ export class LinuxNativeCaptureSession {
 	private negotiatedCursorMode: LinuxCaptureConfig["cursorMode"] | undefined;
 	private videoEncoder: string | undefined;
 	private lastError: string | null = null;
-	private exitError: Error | null = null;
 	private paused = false;
 	private helperOutputText = "";
 	private cursorRecordingStartMs = 0;
@@ -183,9 +182,6 @@ export class LinuxNativeCaptureSession {
 			const reason =
 				this.lastError ??
 				`the Linux capture helper exited (code=${code ?? "null"}, signal=${signal ?? "null"})`;
-			if (code !== 0 || signal) {
-				this.exitError = new Error(reason);
-			}
 			this.rejectReady(new Error(reason));
 			this.startedReject?.(new Error(reason));
 			this.startedReject = null;
@@ -199,7 +195,7 @@ export class LinuxNativeCaptureSession {
 			this.sourceSelectedResolve = null;
 			// A clean exit after `capture-stopped` is the normal path; anything
 			// else means the file may not have its trailer.
-			if (this.stopped && !this.exitError) {
+			if (this.stopped) {
 				this.stoppedResolve?.();
 			} else {
 				this.stoppedReject?.(new Error(reason));
@@ -409,9 +405,6 @@ export class LinuxNativeCaptureSession {
 	async stop(): Promise<LinuxCaptureResult> {
 		const child = this.process;
 		if (!child) {
-			if (this.exitError) {
-				throw this.exitError;
-			}
 			if (this.stopped) {
 				return this.stopped;
 			}

electron/native/pipewire-capture/Cargo.lock

@@ -53,7 +53,9 @@ sha2 = "0.10"
 evdev = "0.13"
 # X11 capture uses the wire protocol directly: no compositor, portal, root or
 # Xlib development package is needed, and Wayland never enters this path.
-x11rb = { version = "0.13", features = ["xfixes", "xinput"] }
+x11rb = { version = "0.13", features = ["shm", "xfixes", "xinput"] }
+# mmap of the server-created MIT-SHM segment; already in the tree through zbus.
+libc = "0.2"
 
 [build-dependencies]
 cc = "1"

electron/native/pipewire-capture/Cargo.toml

@@ -51,6 +51,9 @@ pub enum Event {
         /// The cursor mode actually negotiated, which can differ from the one
         /// asked for (see `CursorMode::resolve`).
         cursor_mode: &'static str,
+        /// `pipewire` (the ScreenCast portal) or `x11` (direct capture, taken
+        /// only on an X11 session where the portal does not answer).
+        backend: &'static str,
     },
     /// The user has answered the compositor's picker and a source was granted.
     ///
@@ -257,6 +260,7 @@ mod tests {
                 pipewire_version: Some("1.0.5".to_owned()),
                 cursor_metadata_supported: true,
                 cursor_mode: "metadata",
+                backend: "pipewire",
             },
             false,
         );
@@ -280,12 +284,14 @@ mod tests {
             pipewire_version: None,
             cursor_metadata_supported: false,
             cursor_mode: "embedded",
+            backend: "x11",
         });
         assert_eq!(value["event"], "ready");
         assert_eq!(value["timestampMs"], 7);
         assert!(value["pipewireVersion"].is_null());
         assert_eq!(value["cursorMetadataSupported"], false);
         assert_eq!(value["cursorMode"], "embedded");
+        assert_eq!(value["backend"], "x11");
     }
 
     #[test]

electron/native/pipewire-capture/src/events.rs

@@ -260,12 +260,6 @@ fn main() {
         Ok(mode) => mode,
         Err(message) => fail(&mut emitter, "invalid-arguments", &message),
     };
-    if x11::is_x11_session() {
-        if let Err(message) = x11::run(&request, &mut emitter) {
-            fail(&mut emitter, "x11-capture-failed", &message);
-        }
-        return;
-    }
     let output_path = request.output_path.as_deref().map(PathBuf::from);
     let forced_encoder = match encoder::forced_backend_from_env() {
         Ok(backend) => backend,
@@ -288,6 +282,18 @@ fn main() {
         None => sample_interval,
     };
 
+    // The portal first: it is what gives dmabuf frames and GPU encoding. Direct
+    // X11 capture is only for an X11 session where nothing answers on the
+    // ScreenCast interface (Xfce, i3...). Probed before `shim::load` because an
+    // X11 desktop without a portal often has no PipeWire either.
+    let offered_cursor_modes = pollster::block_on(portal::offered_cursor_modes());
+    if offered_cursor_modes.is_err() && x11::is_x11_session() {
+        if let Err(message) = x11::run(&request, &mut emitter) {
+            fail(&mut emitter, "x11-capture-failed", &message);
+        }
+        return;
+    }
+
     if let Err(message) = shim::load() {
         fail(&mut emitter, "pipewire-unavailable", &message);
     }
@@ -296,7 +302,7 @@ fn main() {
     // compositor fails immediately instead of after a pointless picker. Only
     // fatal when METADATA is the mode actually requested — a recording that
     // wants the system cursor painted in has no use for it.
-    let offered_cursor_modes = match pollster::block_on(portal::offered_cursor_modes()) {
+    let offered_cursor_modes = match offered_cursor_modes {
         Ok(modes) => modes,
         Err(error) => fail(&mut emitter, error.code(), &error.message()),
     };
@@ -314,6 +320,7 @@ fn main() {
         pipewire_version: shim::library_version(),
         cursor_metadata_supported,
         cursor_mode: cursor_mode.as_str(),
+        backend: "pipewire",
     });
 
     if request.probe_only {