From 7b1ecb16324c96365eb8ed24145244cf6ac16409 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 28 Oct 2026 12:35:29 +0000
Subject: [PATCH 1/2] feat(linux): auto-sample X11 cursor telemetry when portal
 metadata is missing

On X11 (including Xvfb cloud agents) the ScreenCast portal often has no
METADATA cursor mode, so editable-cursor takes used to write no sidecar.
Sample the pointer via Electron/xdotool/xev during record, write the
version-2 <video>.cursor.json next to the take, and add
`openscreen cursor import` for an external CSV. export --auto-zoom then
works with no extra step.
---
 electron/cli/args.test.ts                     |  39 +++
 electron/cli/args.ts                          | 132 ++++++++++
 electron/cli/cliMain.ts                       |   7 +
 electron/cli/cursorCommands.test.ts           |  70 +++++
 electron/cli/cursorCommands.ts                |  44 ++++
 electron/ipc/handlers.ts                      |  70 ++++-
 electron/media/cursorTelemetryImport.test.ts  |  78 ++++++
 electron/media/cursorTelemetryImport.ts       | 195 ++++++++++++++
 .../cursor/recording/factory.test.ts          |  60 +++++
 .../native-bridge/cursor/recording/factory.ts |  34 ++-
 .../fallbackCursorRecordingSession.test.ts    |  92 +++++++
 .../fallbackCursorRecordingSession.ts         |  56 ++++
 .../recording/x11PointerFallback.test.ts      |  42 +++
 .../cursor/recording/x11PointerFallback.ts    |  39 +++
 .../cursor/recording/x11PointerParse.test.ts  |  97 +++++++
 .../cursor/recording/x11PointerParse.ts       | 126 +++++++++
 .../x11PointerRecordingSession.test.ts        |  89 +++++++
 .../recording/x11PointerRecordingSession.ts   | 248 ++++++++++++++++++
 electron/native/README.md                     |   6 +
 src/hooks/useScreenRecorder.ts                |  61 ++++-
 src/lib/nativeLinuxRecording.ts               |   7 +
 .../architecture/cursor.md                    |   4 +
 .../architecture/recording.md                 |   2 +-
 website/docs/cli.md                           |  29 +-
 website/docs/installation.md                  |   4 +-
 website/docs/recording.md                     |   2 +-
 26 files changed, 1609 insertions(+), 24 deletions(-)
 create mode 100644 electron/cli/cursorCommands.test.ts
 create mode 100644 electron/cli/cursorCommands.ts
 create mode 100644 electron/media/cursorTelemetryImport.test.ts
 create mode 100644 electron/media/cursorTelemetryImport.ts
 create mode 100644 electron/native-bridge/cursor/recording/factory.test.ts
 create mode 100644 electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.test.ts
 create mode 100644 electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerFallback.test.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerFallback.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerParse.test.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerParse.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
 create mode 100644 electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts

diff --git a/electron/cli/args.test.ts b/electron/cli/args.test.ts
index 5d52f2ee9a..3dc59092d8 100644
--- a/electron/cli/args.test.ts
+++ b/electron/cli/args.test.ts
@@ -302,4 +302,43 @@ describe("parseCliArgs", () => {
 		expect(parse(["help"])).toMatchObject({ kind: "help" });
 		expect(parse(["--help"])).toMatchObject({ kind: "help" });
 	});
+
+	it("parses cursor import from a CSV next to a video", () => {
+		const cmd = parse([
+			"cursor",
+			"import",
+			"--csv",
+			"mouse.csv",
+			"--clicks",
+			"clicks.txt",
+			"--video",
+			"take.mp4",
+			"--width",
+			"1280",
+			"--height",
+			"720",
+			"--json",
+		]);
+		expect(cmd).toMatchObject({
+			kind: "cursor-import",
+			csvPath: inCwd("mouse.csv"),
+			clicksPath: inCwd("clicks.txt"),
+			videoPath: inCwd("take.mp4"),
+			outputPath: null,
+			width: 1280,
+			height: 720,
+			clickHoldMs: 60,
+			json: true,
+		});
+	});
+
+	it("rejects cursor import without a csv or an output target", () => {
+		expect(parse(["cursor"])).toMatchObject({ kind: "error" });
+		expect(parse(["cursor", "import"])).toMatchObject({ kind: "error" });
+		expect(parse(["cursor", "import", "--csv", "m.csv"])).toMatchObject({
+			kind: "error",
+			message: expect.stringContaining("--video"),
+		});
+		expect(parse(["cursor", "export"])).toMatchObject({ kind: "error" });
+	});
 });
diff --git a/electron/cli/args.ts b/electron/cli/args.ts
index b2b50bd7b2..4cd22e8ae7 100644
--- a/electron/cli/args.ts
+++ b/electron/cli/args.ts
@@ -37,10 +37,22 @@ export interface CliMcpCommand {
 	kind: "mcp";
 }
 
+export interface CliCursorImportCommand {
+	kind: "cursor-import";
+	csvPath: string;
+	clicksPath: string | null;
+	videoPath: string | null;
+	outputPath: string | null;
+	width: number;
+	height: number;
+	clickHoldMs: number;
+}
+
 export type CliCommand = (
 	| CliRequest
 	| CliInfoCommand
 	| CliPackCommand
+	| CliCursorImportCommand
 	| CliMcpCommand
 	| CliHelpCommand
 	| CliErrorCommand
@@ -76,6 +88,7 @@ const SUBCOMMANDS = new Set([
 	"pack",
 	"captions",
 	"info",
+	"cursor",
 	"mcp",
 	"help",
 	"--help",
@@ -92,6 +105,7 @@ Usage:
   openscreen captions <project.openscreen>           Transcribe (on-device Whisper) and turn captions on
                      [--min-words <1-12>] [--max-words <1-12>]
   openscreen info <project.openscreen> [--json]      Inspect a project file
+  openscreen cursor import [options]                 Write <video>.cursor.json from a CSV mouse track
   openscreen mcp                                     Serve the agent tools over MCP on stdio
   openscreen help                                    Show this help
 
@@ -132,6 +146,20 @@ Record options (recording is saved into the app's recordings directory):
 
 Stopping a recording: send SIGINT/SIGTERM, type "stop" + Enter on stdin,
 or pass --duration.
+
+Cursor import options (for takes recorded outside OpenScreen, or a CSV already on disk):
+  --csv <mouse.csv>         Required. Columns t,x,y (seconds + pixel coords). t/time/time_s accepted
+  --clicks <clicks.txt>     Optional. One seconds-timestamp per line
+  --video <file.mp4>        Sidecar path becomes <file.mp4>.cursor.json
+  -o, --output <file>       Explicit sidecar path (overrides --video's default)
+  --width <px>              Capture width used to normalise x (default 1920)
+  --height <px>             Capture height used to normalise y (default 1200)
+  --click-hold-ms <ms>      Synthesized mouseup this long after each click (default 60)
+  --json                    Machine-readable result on stdout
+
+On Linux X11 hosts where the ScreenCast portal has no METADATA cursor mode,
+openscreen record --cursor editable-overlay samples the pointer automatically
+and writes the sidecar itself — cursor import is only needed for an external track.
 `;
 
 function takeValue(argv: string[], i: number, flag: string): [string, number] {
@@ -194,6 +222,7 @@ export function parseCliArgs(
 			if (args.length > 1) throw new Error(`Unexpected argument for mcp: ${args[1]}`);
 			return { kind: "mcp" };
 		}
+		if (sub === "cursor") return parseCursor(args.slice(1), cwd);
 		return parseInfo(args.slice(1), cwd);
 	} catch (error) {
 		return { kind: "error", message: error instanceof Error ? error.message : String(error) };
@@ -546,6 +575,109 @@ function parseCaptions(args: string[], cwd: string): CliCommand {
 	return { kind: "captions", projectPath, minWordsPerCaption, maxWordsPerCaption, json };
 }
 
+function parseCursor(args: string[], cwd: string): CliCommand {
+	const action = args[0];
+	if (!action || action === "--help" || action === "-h") {
+		throw new Error("cursor requires a subcommand: import");
+	}
+	if (action !== "import") {
+		throw new Error(`Unknown cursor subcommand: ${action} (expected import)`);
+	}
+	return parseCursorImport(args.slice(1), cwd);
+}
+
+function parseCursorImport(args: string[], cwd: string): CliCommand {
+	let csvPath = "";
+	let clicksPath: string | null = null;
+	let videoPath: string | null = null;
+	let outputPath: string | null = null;
+	let width = 1920;
+	let height = 1200;
+	let clickHoldMs = 60;
+	let json = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		switch (arg) {
+			case "--csv": {
+				const [value, next] = takeValue(args, i, arg);
+				csvPath = resolvePath(value, cwd);
+				i = next;
+				break;
+			}
+			case "--clicks": {
+				const [value, next] = takeValue(args, i, arg);
+				clicksPath = resolvePath(value, cwd);
+				i = next;
+				break;
+			}
+			case "--video": {
+				const [value, next] = takeValue(args, i, arg);
+				videoPath = resolvePath(value, cwd);
+				i = next;
+				break;
+			}
+			case "-o":
+			case "--output":
+			case "--out": {
+				const [value, next] = takeValue(args, i, arg);
+				outputPath = resolvePath(value, cwd);
+				i = next;
+				break;
+			}
+			case "--width": {
+				const [value, next] = takeValue(args, i, arg);
+				width = Number(value);
+				if (!Number.isInteger(width) || width <= 0) {
+					throw new Error(`--width must be a positive integer, got "${value}"`);
+				}
+				i = next;
+				break;
+			}
+			case "--height": {
+				const [value, next] = takeValue(args, i, arg);
+				height = Number(value);
+				if (!Number.isInteger(height) || height <= 0) {
+					throw new Error(`--height must be a positive integer, got "${value}"`);
+				}
+				i = next;
+				break;
+			}
+			case "--click-hold-ms": {
+				const [value, next] = takeValue(args, i, arg);
+				clickHoldMs = Number(value);
+				if (!Number.isInteger(clickHoldMs) || clickHoldMs < 0) {
+					throw new Error(`--click-hold-ms must be a non-negative integer, got "${value}"`);
+				}
+				i = next;
+				break;
+			}
+			case "--json":
+				json = true;
+				break;
+			default:
+				if (arg.startsWith("-")) throw new Error(`Unknown cursor import option: ${arg}`);
+				throw new Error(`Unexpected extra argument: ${arg}`);
+		}
+	}
+
+	if (!csvPath) throw new Error("cursor import requires --csv <mouse.csv>");
+	if (!outputPath && !videoPath) {
+		throw new Error("cursor import requires --video <file> or --output <file>");
+	}
+	return {
+		kind: "cursor-import",
+		csvPath,
+		clicksPath,
+		videoPath,
+		outputPath,
+		width,
+		height,
+		clickHoldMs,
+		json,
+	};
+}
+
 function parseInfo(args: string[], cwd: string): CliCommand {
 	let projectPath = "";
 	let json = false;
diff --git a/electron/cli/cliMain.ts b/electron/cli/cliMain.ts
index 410ba97458..d787ea1659 100644
--- a/electron/cli/cliMain.ts
+++ b/electron/cli/cliMain.ts
@@ -17,6 +17,7 @@ import { registerSttIpc, shutdownStt } from "../stt";
 import { sendUsagePing, USAGE_PING_INTERVAL_MS } from "../usage-ping";
 import { createRunnerWindow } from "../windows";
 import { CLI_USAGE, type CliCommand } from "./args";
+import { runCursorImportCommand } from "./cursorCommands";
 import { openGuiFromCli } from "./openGui";
 import { runInfoCommand, runPackCommand } from "./projectCommands";
 import { createRunnerHost } from "./runnerHost";
@@ -323,6 +324,12 @@ export function runCli(command: CliCommand): void {
 				return;
 			}
 
+			if (command.kind === "cursor-import") {
+				const code = await runCursorImportCommand(command, command.json === true, writeStdout);
+				app.exit(code);
+				return;
+			}
+
 			milestone("resolving userData path");
 			const userDataDir = app.getPath("userData");
 			milestone(`userData = ${userDataDir}`);
diff --git a/electron/cli/cursorCommands.test.ts b/electron/cli/cursorCommands.test.ts
new file mode 100644
index 0000000000..5b73a4d4ad
--- /dev/null
+++ b/electron/cli/cursorCommands.test.ts
@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { runCursorImportCommand } from "./cursorCommands";
+
+describe("runCursorImportCommand", () => {
+	let dir: string;
+
+	beforeEach(async () => {
+		dir = await fs.mkdtemp(path.join(os.tmpdir(), "cursor-cli-"));
+	});
+
+	afterEach(async () => {
+		await fs.rm(dir, { recursive: true, force: true });
+	});
+
+	it("writes the sidecar and a human summary", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		const videoPath = path.join(dir, "clip.mp4");
+		await fs.writeFile(csvPath, "t,x,y\n0,10,20\n", "utf8");
+		await fs.writeFile(videoPath, "v", "utf8");
+		const lines: string[] = [];
+		const code = await runCursorImportCommand(
+			{
+				csvPath,
+				clicksPath: null,
+				videoPath,
+				outputPath: null,
+				width: 100,
+				height: 100,
+				clickHoldMs: 60,
+			},
+			false,
+			(text) => {
+				lines.push(text);
+			},
+		);
+		expect(code).toBe(0);
+		expect(lines.join("")).toContain("Wrote ");
+		expect(lines.join("")).toContain("samples=1");
+		await expect(fs.stat(`${videoPath}.cursor.json`)).resolves.toMatchObject({
+			size: expect.any(Number),
+		});
+	});
+
+	it("emits JSON when asked", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		await fs.writeFile(csvPath, "t,x,y\n0,1,2\n", "utf8");
+		const outputPath = path.join(dir, "out.cursor.json");
+		const lines: string[] = [];
+		await runCursorImportCommand(
+			{
+				csvPath,
+				clicksPath: null,
+				videoPath: null,
+				outputPath,
+				width: 10,
+				height: 10,
+				clickHoldMs: 60,
+			},
+			true,
+			(text) => {
+				lines.push(text);
+			},
+		);
+		const payload = JSON.parse(lines.join(""));
+		expect(payload).toMatchObject({ event: "done", success: true, outputPath, samples: 1 });
+	});
+});
diff --git a/electron/cli/cursorCommands.ts b/electron/cli/cursorCommands.ts
new file mode 100644
index 0000000000..20f024d274
--- /dev/null
+++ b/electron/cli/cursorCommands.ts
@@ -0,0 +1,44 @@
+// `openscreen cursor import`: write a version-2 `<video>.cursor.json` sidecar
+// from an external mouse CSV (and optional click timestamps). File-only, like
+// `pack` and `info` — no renderer window.
+
+import { writeCursorSidecarFromCsv } from "../media/cursorTelemetryImport";
+import type { CliWriter } from "./projectCommands";
+
+export interface CursorImportRequest {
+	csvPath: string;
+	clicksPath: string | null;
+	videoPath: string | null;
+	outputPath: string | null;
+	width: number;
+	height: number;
+	clickHoldMs: number;
+}
+
+export async function runCursorImportCommand(
+	request: CursorImportRequest,
+	json: boolean,
+	out: CliWriter,
+): Promise<number> {
+	const { outputPath, data } = await writeCursorSidecarFromCsv(request);
+	const clicks = data.samples.filter((sample) => sample.interactionType === "click").length;
+	const mouseups = data.samples.filter((sample) => sample.interactionType === "mouseup").length;
+	const moves = data.samples.length - clicks - mouseups;
+	if (json) {
+		out(
+			`${JSON.stringify({
+				event: "done",
+				success: true,
+				outputPath,
+				samples: data.samples.length,
+				moves,
+				clicks,
+				mouseups,
+			})}\n`,
+		);
+	} else {
+		out(`Wrote ${outputPath}\n`);
+		out(`  samples=${data.samples.length} moves=${moves} clicks=${clicks} mouseups=${mouseups}\n`);
+	}
+	return 0;
+}
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 75c3a23df7..d5f7af41a2 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -102,7 +102,11 @@ import {
 	LinuxNativeCaptureSession,
 } from "../native-bridge/capture/linuxNativeCaptureSession";
 import { compactCursorTelemetryPauseRanges } from "../native-bridge/cursor/recording/cursorPauseRanges";
-import { createCursorRecordingSession } from "../native-bridge/cursor/recording/factory";
+import {
+	createCursorRecordingSession,
+	createX11PointerRecordingSession,
+	isX11PointerFallbackEnabled,
+} from "../native-bridge/cursor/recording/factory";
 import {
 	isMacCursorHelperUnavailable,
 	requestMacCursorAccessibilityAccess,
@@ -1334,11 +1338,39 @@ async function resolveDirectShowWebcamClsid(deviceName?: string) {
 async function startCursorRecording(recordingId?: number) {
 	// On Linux the native capture helper already produces cursor samples, from
 	// the SAME portal session that produces the pixels. Spawning the cursor-only
-	// helper alongside it would open a SECOND portal session — and since
+	// PipeWire helper alongside it would open a SECOND portal session — and since
 	// SelectSources may be called once per session, that means a second picker
 	// in front of the user, for a stream nothing consumes. The double prompt is
 	// precisely what the native path exists to remove.
+	//
+	// X11 is the exception: the portal often has no METADATA cursor mode at all,
+	// so the helper records pixels with an empty cursor track. Sampling the
+	// pointer through X11 (Electron / xdotool / xev) does not talk to the portal,
+	// so it can run in parallel and fill `<video>.cursor.json` when native samples
+	// come back empty.
 	if (linuxNativeCaptureSession) {
+		if (!isX11PointerFallbackEnabled()) {
+			return;
+		}
+		if (cursorRecordingSession) {
+			pendingCursorRecordingData = await cursorRecordingSession.stop();
+			cursorRecordingSession = null;
+		}
+		pendingCursorRecordingData = null;
+		cursorRecordingSession = createX11PointerRecordingSession({
+			getDisplayBounds: getSelectedSourceBounds,
+			maxSamples: MAX_CURSOR_SAMPLES,
+			sampleIntervalMs: CURSOR_SAMPLE_INTERVAL_MS,
+			startTimeMs:
+				typeof recordingId === "number" && Number.isFinite(recordingId) ? recordingId : undefined,
+		});
+		try {
+			await cursorRecordingSession.start();
+			console.info("[cursor-x11] sampling the pointer alongside native Linux capture");
+		} catch (error) {
+			console.error("Failed to start the X11 pointer sampler:", error);
+			cursorRecordingSession = null;
+		}
 		return;
 	}
 
@@ -2784,6 +2816,10 @@ export function registerIpcHandlers(
 				linuxNativeCaptureSourceLabel = linuxSourceLabel(session.grantedSourceKind);
 				setAppRecording(true, linuxNativeCaptureSourceLabel);
 
+				if (cursorCaptureMode === "editable-overlay") {
+					await startCursorRecording(recordingId);
+				}
+
 				return { success: true, recordingId, path: outputPath };
 			} catch (error) {
 				console.error("Failed to start native Linux recording:", error);
@@ -2795,7 +2831,11 @@ export function registerIpcHandlers(
 				if (outputPath) {
 					await removeEmptyCaptureOutput(outputPath);
 				}
-				return { success: false, error: String(error) };
+				return {
+					success: false,
+					error: String(error),
+					fallbackToBrowser: isX11PointerFallbackEnabled(),
+				};
 			}
 		},
 	);
@@ -2838,15 +2878,21 @@ export function registerIpcHandlers(
 
 			const result = await session.stop();
 
-			// The helper collects cursor samples itself, from the same portal
-			// session that produced the pixels, so there is no separate sampler
-			// to stop and no clock offset to correct — the two are one recording.
-			if (cursorCaptureMode === "editable-overlay" && result.cursor.samples.length > 0) {
-				await fs.writeFile(
-					`${result.path}.cursor.json`,
-					JSON.stringify(result.cursor, null, 2),
-					"utf-8",
-				);
+			if (cursorCaptureMode === "editable-overlay") {
+				await stopCursorRecording();
+			} else {
+				pendingCursorRecordingData = null;
+			}
+
+			// Prefer the helper's own samples — they share the portal session that
+			// produced the pixels, so there is no clock offset to correct. When
+			// the portal had no METADATA cursor mode the track is empty; the X11
+			// sampler started alongside the take then fills the sidecar so
+			// `--auto-zoom` still has clicks to work from.
+			const cursor = result.cursor.samples.length > 0 ? result.cursor : pendingCursorRecordingData;
+			pendingCursorRecordingData = null;
+			if (cursorCaptureMode === "editable-overlay" && cursor && cursor.samples.length > 0) {
+				await fs.writeFile(`${result.path}.cursor.json`, JSON.stringify(cursor, null, 2), "utf-8");
 			}
 
 			const session_: RecordingSession = {
diff --git a/electron/media/cursorTelemetryImport.test.ts b/electron/media/cursorTelemetryImport.test.ts
new file mode 100644
index 0000000000..a5cd4a4a03
--- /dev/null
+++ b/electron/media/cursorTelemetryImport.test.ts
@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readCursorRecordingFileAt } from "./cursorSidecar";
+import {
+	buildCursorSidecar,
+	parseClickTimestamps,
+	parseMouseCsv,
+	writeCursorSidecarFromCsv,
+} from "./cursorTelemetryImport";
+
+describe("cursorTelemetryImport", () => {
+	it("parses t,x,y and time,x,y headers", () => {
+		expect(parseMouseCsv("t,x,y\n0,10,20\n0.5,30,40\n")).toEqual([
+			{ t: 0, x: 10, y: 20 },
+			{ t: 0.5, x: 30, y: 40 },
+		]);
+		expect(parseMouseCsv("time,x,y\n1,2,3\n")).toEqual([{ t: 1, x: 2, y: 3 }]);
+	});
+
+	it("parses click timestamps, skipping comments", () => {
+		expect(parseClickTimestamps("# hold\n1.5\n2.0,extra\n")).toEqual([1.5, 2]);
+	});
+
+	it("builds a version-2 sidecar with normalised coords and click/mouseup pairs", () => {
+		const data = buildCursorSidecar({
+			mouse: [
+				{ t: 0, x: 0, y: 0 },
+				{ t: 1, x: 1920, y: 1080 },
+			],
+			clicks: [0.5],
+			width: 1920,
+			height: 1080,
+			clickHoldMs: 60,
+		});
+		expect(data.version).toBe(2);
+		expect(data.provider).toBe("none");
+		const click = data.samples.find((sample) => sample.interactionType === "click");
+		const mouseup = data.samples.find((sample) => sample.interactionType === "mouseup");
+		expect(click).toMatchObject({ timeMs: 500, cx: 0.5, cy: 0.5 });
+		expect(mouseup).toMatchObject({ timeMs: 560, cx: 0.5, cy: 0.5 });
+	});
+});
+
+describe("writeCursorSidecarFromCsv", () => {
+	let dir: string;
+
+	beforeEach(async () => {
+		dir = await fs.mkdtemp(path.join(os.tmpdir(), "cursor-import-"));
+	});
+
+	afterEach(async () => {
+		await fs.rm(dir, { recursive: true, force: true });
+	});
+
+	it("writes <video>.cursor.json that the production reader accepts", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		const clicksPath = path.join(dir, "clicks.txt");
+		const videoPath = path.join(dir, "take.mp4");
+		await fs.writeFile(csvPath, "t,x,y\n0,96,54\n1,192,108\n", "utf8");
+		await fs.writeFile(clicksPath, "0.5\n", "utf8");
+		await fs.writeFile(videoPath, "fake", "utf8");
+
+		const { outputPath, data } = await writeCursorSidecarFromCsv({
+			csvPath,
+			clicksPath,
+			videoPath,
+			width: 1920,
+			height: 1080,
+		});
+
+		expect(outputPath).toBe(`${videoPath}.cursor.json`);
+		expect(data.samples.length).toBeGreaterThan(2);
+		const loaded = await readCursorRecordingFileAt(outputPath);
+		expect(loaded.samples.some((sample) => sample.interactionType === "click")).toBe(true);
+	});
+});
diff --git a/electron/media/cursorTelemetryImport.ts b/electron/media/cursorTelemetryImport.ts
new file mode 100644
index 0000000000..6d5ae540a6
--- /dev/null
+++ b/electron/media/cursorTelemetryImport.ts
@@ -0,0 +1,195 @@
+// Convert an external mouse track (CSV of t,x,y plus optional click timestamps)
+// into the version-2 cursor sidecar (`<video>.cursor.json`) that export, the
+// editor, and `--auto-zoom` already consume.
+//
+// Node-pure: no Electron import, so `openscreen cursor import` and the unit
+// tests can run it without booting Chromium.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { CursorRecordingData, CursorRecordingSample } from "../../src/native/contracts";
+import { clamp } from "../../src/utils/math";
+import { CURSOR_TELEMETRY_VERSION } from "./cursorSidecar";
+
+export type MouseCsvRow = { t: number; x: number; y: number };
+
+const INTERACTION_ORDER: Record<string, number> = {
+	move: 0,
+	click: 1,
+	"double-click": 1,
+	"right-click": 1,
+	"middle-click": 1,
+	mouseup: 2,
+};
+
+export interface BuildCursorSidecarOptions {
+	mouse: MouseCsvRow[];
+	clicks?: number[];
+	width: number;
+	height: number;
+	/** How long a synthesized click is held, in milliseconds. Default 60. */
+	clickHoldMs?: number;
+}
+
+export function parseMouseCsv(text: string): MouseCsvRow[] {
+	const lines = text.split(/\r?\n/);
+	if (lines.length === 0) {
+		return [];
+	}
+	const header = lines[0].split(",").map((cell) => cell.trim().toLowerCase());
+	const tIndex = header.findIndex((name) => name === "t" || name === "time" || name === "time_s");
+	const xIndex = header.findIndex((name) => name === "x");
+	const yIndex = header.findIndex((name) => name === "y");
+	if (xIndex < 0 || yIndex < 0) {
+		throw new Error("mouse CSV must have columns x and y (and t, time, or time_s)");
+	}
+	const rows: MouseCsvRow[] = [];
+	for (const line of lines.slice(1)) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) {
+			continue;
+		}
+		const cells = trimmed.split(",");
+		const t = tIndex >= 0 ? Number(cells[tIndex]) : 0;
+		const x = Number(cells[xIndex]);
+		const y = Number(cells[yIndex]);
+		if (!Number.isFinite(t) || !Number.isFinite(x) || !Number.isFinite(y)) {
+			continue;
+		}
+		rows.push({ t, x, y });
+	}
+	rows.sort((a, b) => a.t - b.t);
+	return rows;
+}
+
+/** One seconds-timestamp per line; a leading `#` comments the line out. Extra CSV columns are ignored. */
+export function parseClickTimestamps(text: string): number[] {
+	const out: number[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) {
+			continue;
+		}
+		const value = Number(trimmed.split(",")[0]);
+		if (Number.isFinite(value)) {
+			out.push(value);
+		}
+	}
+	return out.sort((a, b) => a - b);
+}
+
+function cursorAt(samples: MouseCsvRow[], t: number): { x: number; y: number } {
+	if (samples.length === 0) {
+		return { x: 0.5, y: 0.5 };
+	}
+	if (t <= samples[0].t) {
+		return { x: samples[0].x, y: samples[0].y };
+	}
+	if (t >= samples[samples.length - 1].t) {
+		return { x: samples[samples.length - 1].x, y: samples[samples.length - 1].y };
+	}
+	let lo = 0;
+	let hi = samples.length - 1;
+	while (lo + 1 < hi) {
+		const mid = (lo + hi) >> 1;
+		if (samples[mid].t <= t) {
+			lo = mid;
+		} else {
+			hi = mid;
+		}
+	}
+	const a = samples[lo];
+	const b = samples[hi];
+	if (b.t <= a.t) {
+		return { x: a.x, y: a.y };
+	}
+	const u = (t - a.t) / (b.t - a.t);
+	return { x: a.x + u * (b.x - a.x), y: a.y + u * (b.y - a.y) };
+}
+
+export function buildCursorSidecar(options: BuildCursorSidecarOptions): CursorRecordingData {
+	const width = Math.max(1, options.width);
+	const height = Math.max(1, options.height);
+	const clickHoldMs = options.clickHoldMs ?? 60;
+	const samples: CursorRecordingSample[] = [];
+
+	const add = (
+		tSeconds: number,
+		x: number,
+		y: number,
+		interactionType: "move" | "click" | "mouseup",
+	) => {
+		samples.push({
+			timeMs: Math.max(0, Math.round(tSeconds * 1000)),
+			cx: clamp(x / width, 0, 1),
+			cy: clamp(y / height, 0, 1),
+			visible: true,
+			interactionType,
+		});
+	};
+
+	for (const row of options.mouse) {
+		add(row.t, row.x, row.y, "move");
+	}
+	for (const clickT of options.clicks ?? []) {
+		const point = cursorAt(options.mouse, clickT);
+		add(clickT, point.x, point.y, "click");
+		add(clickT + clickHoldMs / 1000, point.x, point.y, "mouseup");
+	}
+
+	const dedup = new Map<string, CursorRecordingSample>();
+	for (const sample of samples) {
+		dedup.set(`${sample.timeMs}:${sample.interactionType ?? "move"}`, sample);
+	}
+	const ordered = [...dedup.values()].sort((a, b) => {
+		if (a.timeMs !== b.timeMs) {
+			return a.timeMs - b.timeMs;
+		}
+		return (
+			(INTERACTION_ORDER[a.interactionType ?? "move"] ?? 0) -
+			(INTERACTION_ORDER[b.interactionType ?? "move"] ?? 0)
+		);
+	});
+
+	return {
+		version: CURSOR_TELEMETRY_VERSION,
+		provider: "none",
+		samples: ordered,
+		assets: [],
+	};
+}
+
+export function defaultCursorSidecarPath(videoPath: string): string {
+	return `${videoPath}.cursor.json`;
+}
+
+export interface WriteCursorSidecarFromCsvOptions {
+	csvPath: string;
+	clicksPath?: string | null;
+	videoPath?: string | null;
+	outputPath?: string | null;
+	width: number;
+	height: number;
+	clickHoldMs?: number;
+}
+
+export async function writeCursorSidecarFromCsv(
+	options: WriteCursorSidecarFromCsvOptions,
+): Promise<{ outputPath: string; data: CursorRecordingData }> {
+	if (!options.outputPath && !options.videoPath) {
+		throw new Error("provide --output or --video");
+	}
+	const outputPath = options.outputPath ?? defaultCursorSidecarPath(options.videoPath as string);
+	const csvText = await fs.readFile(options.csvPath, "utf8");
+	const clicksText = options.clicksPath ? await fs.readFile(options.clicksPath, "utf8") : "";
+	const data = buildCursorSidecar({
+		mouse: parseMouseCsv(csvText),
+		clicks: clicksText ? parseClickTimestamps(clicksText) : [],
+		width: options.width,
+		height: options.height,
+		clickHoldMs: options.clickHoldMs,
+	});
+	await fs.mkdir(path.dirname(outputPath), { recursive: true });
+	await fs.writeFile(outputPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	return { outputPath, data };
+}
diff --git a/electron/native-bridge/cursor/recording/factory.test.ts b/electron/native-bridge/cursor/recording/factory.test.ts
new file mode 100644
index 0000000000..2fb2b4c744
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/factory.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("electron", () => ({
+	screen: {
+		getCursorScreenPoint: () => ({ x: 0, y: 0 }),
+		getDisplayNearestPoint: () => ({
+			bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+		}),
+	},
+}));
+
+import { createCursorRecordingSession } from "./factory";
+import { FallbackCursorRecordingSession } from "./fallbackCursorRecordingSession";
+import { PipeWireCursorRecordingSession } from "./pipeWireCursorRecordingSession";
+
+describe("createCursorRecordingSession linux fallback", () => {
+	const REAL_PLATFORM = process.platform;
+	const setPlatform = (value: NodeJS.Platform) =>
+		Object.defineProperty(process, "platform", { value, configurable: true });
+
+	let previousWayland: string | undefined;
+
+	beforeEach(() => {
+		setPlatform("linux");
+		previousWayland = process.env.WAYLAND_DISPLAY;
+		delete process.env.WAYLAND_DISPLAY;
+		vi.stubEnv("XDG_SESSION_TYPE", "x11");
+		vi.stubEnv("OPENSCREEN_FORCE_X11_CURSOR", "");
+		vi.stubEnv("OPENSCREEN_DISABLE_X11_CURSOR", "");
+	});
+
+	afterEach(() => {
+		setPlatform(REAL_PLATFORM);
+		vi.unstubAllEnvs();
+		if (previousWayland === undefined) {
+			delete process.env.WAYLAND_DISPLAY;
+		} else {
+			process.env.WAYLAND_DISPLAY = previousWayland;
+		}
+	});
+
+	const options = {
+		getDisplayBounds: () => ({ x: 0, y: 0, width: 1920, height: 1080 }),
+		maxSamples: 10,
+		sampleIntervalMs: 33,
+		platform: "linux" as const,
+	};
+
+	it("wraps PipeWire in the X11 fallback on an X11 session", () => {
+		const session = createCursorRecordingSession(options);
+		expect(session).toBeInstanceOf(FallbackCursorRecordingSession);
+	});
+
+	it("uses PipeWire alone on Wayland", () => {
+		vi.stubEnv("XDG_SESSION_TYPE", "wayland");
+		vi.stubEnv("WAYLAND_DISPLAY", "wayland-0");
+		const session = createCursorRecordingSession(options);
+		expect(session).toBeInstanceOf(PipeWireCursorRecordingSession);
+	});
+});
diff --git a/electron/native-bridge/cursor/recording/factory.ts b/electron/native-bridge/cursor/recording/factory.ts
index facf1f078e..4f116e06a7 100644
--- a/electron/native-bridge/cursor/recording/factory.ts
+++ b/electron/native-bridge/cursor/recording/factory.ts
@@ -1,9 +1,12 @@
 import type { Rectangle } from "electron";
+import { FallbackCursorRecordingSession } from "./fallbackCursorRecordingSession";
 import { MacNativeCursorRecordingSession } from "./macNativeCursorRecordingSession";
 import { PipeWireCursorRecordingSession } from "./pipeWireCursorRecordingSession";
 import type { CursorRecordingSession } from "./session";
 import { TelemetryRecordingSession } from "./telemetryRecordingSession";
 import { WindowsNativeRecordingSession } from "./windowsNativeRecordingSession";
+import { isX11PointerFallbackEnabled } from "./x11PointerFallback";
+import { X11PointerRecordingSession } from "./x11PointerRecordingSession";
 
 interface CreateCursorRecordingSessionOptions {
 	getDisplayBounds: () => Rectangle | null;
@@ -14,6 +17,17 @@ interface CreateCursorRecordingSessionOptions {
 	startTimeMs?: number;
 }
 
+export function createX11PointerRecordingSession(
+	options: Omit<CreateCursorRecordingSessionOptions, "platform" | "sourceId">,
+): CursorRecordingSession {
+	return new X11PointerRecordingSession({
+		getDisplayBounds: options.getDisplayBounds,
+		maxSamples: options.maxSamples,
+		sampleIntervalMs: options.sampleIntervalMs,
+		startTimeMs: options.startTimeMs,
+	});
+}
+
 export function createCursorRecordingSession(
 	options: CreateCursorRecordingSessionOptions,
 ): CursorRecordingSession {
@@ -41,13 +55,27 @@ export function createCursorRecordingSession(
 		// pointer position on Wayland: `screen.getCursorScreenPoint()` returns
 		// {0,0} there, so TelemetryRecordingSession produced well-formed recordings
 		// with every sample pinned to the top-left corner. The helper throws when
-		// it is unavailable rather than falling back here — the caller then records
+		// it is unavailable rather than falling back there — the caller then records
 		// without cursor data, which beats a file full of {0,0}.
-		return new PipeWireCursorRecordingSession({
+		//
+		// On X11 (Xvfb cloud agents included) the portal often advertises
+		// AvailableSourceTypes=0 / no METADATA mode, while the pointer is still
+		// readable via Electron / xdotool / xev. Fall back to that sampler so a
+		// take still writes `<video>.cursor.json` and `export --auto-zoom` works
+		// with no extra import step.
+		const pipewire = new PipeWireCursorRecordingSession({
 			maxSamples: options.maxSamples,
 			sampleIntervalMs: options.sampleIntervalMs,
 			startTimeMs: options.startTimeMs,
 		});
+		if (!isX11PointerFallbackEnabled(options.platform)) {
+			return pipewire;
+		}
+		return new FallbackCursorRecordingSession({
+			primary: pipewire,
+			createFallback: () => createX11PointerRecordingSession(options),
+			fallbackLabel: "X11 pointer sampler",
+		});
 	}
 
 	// Anything else (a future platform, or a test harness): capture cursor
@@ -60,3 +88,5 @@ export function createCursorRecordingSession(
 		startTimeMs: options.startTimeMs,
 	});
 }
+
+export { isX11PointerFallbackEnabled };
diff --git a/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.test.ts b/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.test.ts
new file mode 100644
index 0000000000..7da5b99da2
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from "vitest";
+import { FallbackCursorRecordingSession } from "./fallbackCursorRecordingSession";
+import type { CursorRecordingSession } from "./session";
+
+function session(
+	label: string,
+	startImpl: () => Promise<void>,
+): CursorRecordingSession & {
+	started: boolean;
+	stopped: boolean;
+} {
+	const state = { started: false, stopped: false };
+	return {
+		get started() {
+			return state.started;
+		},
+		get stopped() {
+			return state.stopped;
+		},
+		start: async () => {
+			await startImpl();
+			state.started = true;
+		},
+		stop: async () => {
+			state.stopped = true;
+			return {
+				version: 2,
+				provider: "none",
+				samples: [
+					{
+						timeMs: 0,
+						cx: 0.5,
+						cy: 0.5,
+						visible: true,
+						interactionType: "move" as const,
+					},
+				],
+				assets: [],
+			};
+		},
+		label,
+	} as CursorRecordingSession & { started: boolean; stopped: boolean; label: string };
+}
+
+describe("FallbackCursorRecordingSession", () => {
+	it("keeps the primary session when it starts", async () => {
+		const primary = session("pipewire", async () => undefined);
+		const fallback = session("x11", async () => undefined);
+		const combined = new FallbackCursorRecordingSession({
+			primary,
+			createFallback: () => fallback,
+		});
+		await combined.start();
+		const data = await combined.stop();
+		expect(primary.started).toBe(true);
+		expect(fallback.started).toBe(false);
+		expect(primary.stopped).toBe(true);
+		expect(data.samples).toHaveLength(1);
+	});
+
+	it("starts the fallback when the primary rejects", async () => {
+		vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		const primary = session("pipewire", async () => {
+			throw new Error("no METADATA cursor mode");
+		});
+		const fallback = session("x11", async () => undefined);
+		const combined = new FallbackCursorRecordingSession({
+			primary,
+			createFallback: () => fallback,
+		});
+		await combined.start();
+		await combined.stop();
+		expect(primary.started).toBe(false);
+		expect(fallback.started).toBe(true);
+		expect(fallback.stopped).toBe(true);
+	});
+
+	it("surfaces a fallback that also fails", async () => {
+		vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		const primary = session("pipewire", async () => {
+			throw new Error("portal down");
+		});
+		const combined = new FallbackCursorRecordingSession({
+			primary,
+			createFallback: () =>
+				session("x11", async () => {
+					throw new Error("no DISPLAY");
+				}),
+		});
+		await expect(combined.start()).rejects.toThrow("no DISPLAY");
+	});
+});
diff --git a/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.ts b/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.ts
new file mode 100644
index 0000000000..ae2e6a3cce
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/fallbackCursorRecordingSession.ts
@@ -0,0 +1,56 @@
+import type { Rectangle } from "electron";
+import type { CursorRecordingData } from "../../../../src/native/contracts";
+import type { CursorRecordingSession } from "./session";
+
+interface FallbackCursorRecordingSessionOptions {
+	primary: CursorRecordingSession;
+	createFallback: () => CursorRecordingSession;
+	/** Label used in the warning when the primary session cannot start. */
+	fallbackLabel?: string;
+}
+
+/**
+ * Tries a native cursor session first and, if `start()` rejects, starts a
+ * fallback instead. Used on Linux X11 so a ScreenCast portal without METADATA
+ * cursor mode still produces a `.cursor.json` sidecar.
+ *
+ * `stop()` and `updateCaptureBounds()` always talk to whichever session actually
+ * started. A fallback that also fails is surfaced to the caller — there is then
+ * honestly no pointer data.
+ */
+export class FallbackCursorRecordingSession implements CursorRecordingSession {
+	private active: CursorRecordingSession | null = null;
+	private readonly fallbackLabel: string;
+
+	constructor(private readonly options: FallbackCursorRecordingSessionOptions) {
+		this.fallbackLabel = options.fallbackLabel ?? "X11 pointer sampler";
+	}
+
+	async start(): Promise<void> {
+		try {
+			await this.options.primary.start();
+			this.active = this.options.primary;
+		} catch (error) {
+			console.warn(
+				`[cursor] native cursor capture unavailable; using ${this.fallbackLabel} instead:`,
+				error,
+			);
+			const fallback = this.options.createFallback();
+			await fallback.start();
+			this.active = fallback;
+		}
+	}
+
+	async stop(): Promise<CursorRecordingData> {
+		const session = this.active;
+		this.active = null;
+		if (!session) {
+			return { version: 2, provider: "none", samples: [], assets: [] };
+		}
+		return session.stop();
+	}
+
+	updateCaptureBounds(bounds: Rectangle): void {
+		this.active?.updateCaptureBounds?.(bounds);
+	}
+}
diff --git a/electron/native-bridge/cursor/recording/x11PointerFallback.test.ts b/electron/native-bridge/cursor/recording/x11PointerFallback.test.ts
new file mode 100644
index 0000000000..97f89dd42b
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerFallback.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { isX11PointerFallbackEnabled } from "./x11PointerFallback";
+
+describe("isX11PointerFallbackEnabled", () => {
+	const REAL_PLATFORM = process.platform;
+	const setPlatform = (value: NodeJS.Platform) =>
+		Object.defineProperty(process, "platform", { value, configurable: true });
+
+	afterEach(() => {
+		setPlatform(REAL_PLATFORM);
+	});
+
+	it("is on for a Linux X11 session", () => {
+		expect(isX11PointerFallbackEnabled("linux", { XDG_SESSION_TYPE: "x11" })).toBe(true);
+		expect(isX11PointerFallbackEnabled("linux", {})).toBe(true);
+		expect(isX11PointerFallbackEnabled("linux", { WAYLAND_DISPLAY: "" })).toBe(true);
+	});
+
+	it("is off for a Wayland session unless forced", () => {
+		expect(isX11PointerFallbackEnabled("linux", { XDG_SESSION_TYPE: "wayland" })).toBe(false);
+		expect(
+			isX11PointerFallbackEnabled("linux", {
+				XDG_SESSION_TYPE: "wayland",
+				OPENSCREEN_FORCE_X11_CURSOR: "1",
+			}),
+		).toBe(true);
+	});
+
+	it("is off when explicitly disabled, even on X11", () => {
+		expect(
+			isX11PointerFallbackEnabled("linux", {
+				XDG_SESSION_TYPE: "x11",
+				OPENSCREEN_DISABLE_X11_CURSOR: "1",
+			}),
+		).toBe(false);
+	});
+
+	it("is off off Linux", () => {
+		expect(isX11PointerFallbackEnabled("win32", { XDG_SESSION_TYPE: "x11" })).toBe(false);
+		expect(isX11PointerFallbackEnabled("darwin", {})).toBe(false);
+	});
+});
diff --git a/electron/native-bridge/cursor/recording/x11PointerFallback.ts b/electron/native-bridge/cursor/recording/x11PointerFallback.ts
new file mode 100644
index 0000000000..2760779634
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerFallback.ts
@@ -0,0 +1,39 @@
+/**
+ * Whether Linux recordings should sample the pointer via X11 when the ScreenCast
+ * portal cannot supply METADATA cursor data.
+ *
+ * Wayland is excluded: `screen.getCursorScreenPoint()` returns {0,0} there, and
+ * a well-formed sidecar full of origin samples is worse than no sidecar. X11
+ * (including Xvfb cloud-agent desktops) can read the real pointer through
+ * Electron, xdotool, or xev even when `AvailableSourceTypes=0`.
+ *
+ * An empty `WAYLAND_DISPLAY` does not count as Wayland — cloud Xvfb sessions
+ * often export the variable unset-or-blank alongside `DISPLAY=:N`.
+ *
+ * `OPENSCREEN_FORCE_X11_CURSOR=1` turns the fallback on even in a Wayland
+ * session (Xwayland / diagnostics). `OPENSCREEN_DISABLE_X11_CURSOR=1` turns it
+ * off everywhere.
+ */
+type Env = Readonly<Record<string, string | undefined>>;
+
+export function isX11PointerFallbackEnabled(
+	platform: NodeJS.Platform = process.platform,
+	env: Env = process.env,
+): boolean {
+	if (env.OPENSCREEN_DISABLE_X11_CURSOR === "1") {
+		return false;
+	}
+	if (platform !== "linux") {
+		return false;
+	}
+	if (env.OPENSCREEN_FORCE_X11_CURSOR === "1") {
+		return true;
+	}
+	if (env.XDG_SESSION_TYPE === "wayland") {
+		return false;
+	}
+	if (typeof env.WAYLAND_DISPLAY === "string" && env.WAYLAND_DISPLAY.length > 0) {
+		return false;
+	}
+	return true;
+}
diff --git a/electron/native-bridge/cursor/recording/x11PointerParse.test.ts b/electron/native-bridge/cursor/recording/x11PointerParse.test.ts
new file mode 100644
index 0000000000..f9a9f37e98
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerParse.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import {
+	consumeXevButtonEvents,
+	consumeXInputXi2Events,
+	interactionTypeForButton,
+	parseLibinputButtonLine,
+	parseXdotoolLocation,
+} from "./x11PointerParse";
+
+describe("parseXdotoolLocation", () => {
+	it("reads --shell output", () => {
+		expect(parseXdotoolLocation("X=100\nY=200\nSCREEN=0\nWINDOW=12\n")).toEqual({
+			x: 100,
+			y: 200,
+		});
+	});
+
+	it("reads the inline form", () => {
+		expect(parseXdotoolLocation("x:12 y:34 screen:0 window:99")).toEqual({ x: 12, y: 34 });
+	});
+
+	it("returns null when the point is missing", () => {
+		expect(parseXdotoolLocation("nothing here")).toBeNull();
+	});
+});
+
+describe("consumeXInputXi2Events", () => {
+	const press = `EVENT type 4 (ButtonPress)
+    device: 12 (12)
+    detail: 1
+    flags:
+    root: 10.00/20.00
+`;
+	const release = `EVENT type 5 (ButtonRelease)
+    device: 12 (12)
+    detail: 1
+    flags:
+`;
+
+	it("extracts a complete press and leaves a partial block", () => {
+		const parsed = consumeXInputXi2Events(`${press}EVENT type 4 (ButtonPress)\n    device: 1`);
+		expect(parsed.events).toEqual([{ kind: "press", button: 1 }]);
+		expect(parsed.rest).toContain("EVENT type 4 (ButtonPress)");
+	});
+
+	it("extracts press then release", () => {
+		const parsed = consumeXInputXi2Events(press + release);
+		expect(parsed.events).toEqual([
+			{ kind: "press", button: 1 },
+			{ kind: "release", button: 1 },
+		]);
+		expect(parsed.rest).toBe("");
+	});
+});
+
+describe("consumeXevButtonEvents", () => {
+	const block = `ButtonPress event, serial 32, synthetic NO, window 0x6a3,
+    root 0x51e, subw 0x0, time 1847541, (88,54), root:(1009,873),
+    state 0x0, button 1, same_screen YES
+`;
+
+	it("extracts button 1 press", () => {
+		const parsed = consumeXevButtonEvents(block);
+		expect(parsed.events).toEqual([{ kind: "press", button: 1 }]);
+		expect(parsed.rest).toBe("");
+	});
+
+	it("holds an incomplete event", () => {
+		const parsed = consumeXevButtonEvents("ButtonPress event, serial 1,\n    root 0x1\n");
+		expect(parsed.events).toEqual([]);
+		expect(parsed.rest).toContain("ButtonPress event");
+	});
+});
+
+describe("parseLibinputButtonLine", () => {
+	it("reads a left press", () => {
+		expect(
+			parseLibinputButtonLine(
+				"event0  POINTER_BUTTON    +1.23s\tBTN_LEFT (272) pressed, seat count: 1",
+			),
+		).toEqual({ kind: "press", button: 1 });
+	});
+
+	it("ignores motion", () => {
+		expect(parseLibinputButtonLine("event0  POINTER_MOTION +0.1s  1.0/2.0")).toBeNull();
+	});
+});
+
+describe("interactionTypeForButton", () => {
+	it("maps left/middle/right press and any release of those to mouseup", () => {
+		expect(interactionTypeForButton("press", 1)).toBe("click");
+		expect(interactionTypeForButton("press", 2)).toBe("middle-click");
+		expect(interactionTypeForButton("press", 3)).toBe("right-click");
+		expect(interactionTypeForButton("release", 1)).toBe("mouseup");
+		expect(interactionTypeForButton("press", 8)).toBeNull();
+	});
+});
diff --git a/electron/native-bridge/cursor/recording/x11PointerParse.ts b/electron/native-bridge/cursor/recording/x11PointerParse.ts
new file mode 100644
index 0000000000..5abc46cb86
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerParse.ts
@@ -0,0 +1,126 @@
+/** One-shot pointer location from `xdotool getmouselocation [--shell]`. */
+export function parseXdotoolLocation(text: string): { x: number; y: number } | null {
+	const shellX = text.match(/(?:^|\n)X=([-+]?\d+)/);
+	const shellY = text.match(/(?:^|\n)Y=([-+]?\d+)/);
+	if (shellX && shellY) {
+		return { x: Number(shellX[1]), y: Number(shellY[1]) };
+	}
+	const inline = text.match(/x:\s*([-+]?\d+)\s+y:\s*([-+]?\d+)/i);
+	if (!inline) {
+		return null;
+	}
+	return { x: Number(inline[1]), y: Number(inline[2]) };
+}
+
+export type ParsedButtonEvent = {
+	kind: "press" | "release";
+	button: number;
+};
+
+/**
+ * Pulls complete XI2 button events out of a growing stdout buffer.
+ *
+ * `xinput test-xi2 --root` prints a multi-line block per event. `detail` is the
+ * button number (1 = left). Incomplete trailing text is returned as the leftover.
+ */
+export function consumeXInputXi2Events(buffer: string): {
+	events: ParsedButtonEvent[];
+	rest: string;
+} {
+	const events: ParsedButtonEvent[] = [];
+	const blocks = buffer.split(/(?=EVENT type )/);
+	let rest = "";
+	for (const block of blocks) {
+		if (!block.trim()) {
+			continue;
+		}
+		const header = block.match(/EVENT type\s+(\d+)\s+\((ButtonPress|ButtonRelease)\)/i);
+		if (!header) {
+			rest += block;
+			continue;
+		}
+		const detail = block.match(/\bdetail:\s*(\d+)/);
+		if (!detail) {
+			rest += block;
+			continue;
+		}
+		events.push({
+			kind: header[2].toLowerCase() === "buttonpress" ? "press" : "release",
+			button: Number(detail[1]),
+		});
+	}
+	return { events, rest };
+}
+
+/**
+ * Pulls complete `xev -root -event button` events out of a growing stdout buffer.
+ *
+ * A ButtonPress/ButtonRelease block ends at the `button N` line.
+ */
+export function consumeXevButtonEvents(buffer: string): {
+	events: ParsedButtonEvent[];
+	rest: string;
+} {
+	const events: ParsedButtonEvent[] = [];
+	const blocks = buffer.split(/(?=Button(?:Press|Release) event)/);
+	let rest = "";
+	for (const block of blocks) {
+		if (!block.trim()) {
+			continue;
+		}
+		const kindMatch = block.match(/Button(Press|Release) event/);
+		const buttonMatch = block.match(/\bbutton\s+(\d+)/);
+		if (!kindMatch || !buttonMatch) {
+			rest += block;
+			continue;
+		}
+		events.push({
+			kind: kindMatch[1] === "Press" ? "press" : "release",
+			button: Number(buttonMatch[1]),
+		});
+	}
+	return { events, rest };
+}
+
+/**
+ * One line of `libinput debug-events`. Only BTN_LEFT / BTN_RIGHT / BTN_MIDDLE
+ * (or POINTER_BUTTON with a numeric code) become click events.
+ */
+export function parseLibinputButtonLine(line: string): ParsedButtonEvent | null {
+	if (!/POINTER_BUTTON/.test(line)) {
+		return null;
+	}
+	const kind = /\bpressed\b/.test(line) ? "press" : /\breleased\b/.test(line) ? "release" : null;
+	if (!kind) {
+		return null;
+	}
+	if (/\bBTN_LEFT\b/.test(line)) {
+		return { kind, button: 1 };
+	}
+	if (/\bBTN_MIDDLE\b/.test(line)) {
+		return { kind, button: 2 };
+	}
+	if (/\bBTN_RIGHT\b/.test(line)) {
+		return { kind, button: 3 };
+	}
+	return null;
+}
+
+export function interactionTypeForButton(
+	kind: "press" | "release",
+	button: number,
+): "click" | "right-click" | "middle-click" | "mouseup" | null {
+	if (kind === "release") {
+		return button === 1 || button === 2 || button === 3 ? "mouseup" : null;
+	}
+	if (button === 1) {
+		return "click";
+	}
+	if (button === 2) {
+		return "middle-click";
+	}
+	if (button === 3) {
+		return "right-click";
+	}
+	return null;
+}
diff --git a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
new file mode 100644
index 0000000000..9acaca0df1
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const getCursorScreenPoint = vi.fn(() => ({ x: 96, y: 54 }));
+const getDisplayNearestPoint = vi.fn(() => ({
+	bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+}));
+
+vi.mock("electron", () => ({
+	screen: {
+		getCursorScreenPoint: () => getCursorScreenPoint(),
+		getDisplayNearestPoint: () => getDisplayNearestPoint(),
+	},
+}));
+
+import { X11PointerRecordingSession } from "./x11PointerRecordingSession";
+
+describe("X11PointerRecordingSession", () => {
+	const REAL_PLATFORM = process.platform;
+	const setPlatform = (value: NodeJS.Platform) =>
+		Object.defineProperty(process, "platform", { value, configurable: true });
+
+	beforeEach(() => {
+		setPlatform("linux");
+		vi.useFakeTimers();
+		vi.setSystemTime(1_000);
+		getCursorScreenPoint.mockReturnValue({ x: 96, y: 54 });
+	});
+
+	afterEach(() => {
+		setPlatform(REAL_PLATFORM);
+		vi.useRealTimers();
+		vi.restoreAllMocks();
+	});
+
+	it("records normalised move samples and injected clicks", async () => {
+		const buttons: {
+			onPress: (button: number) => void;
+			onRelease: (button: number) => void;
+		} = {
+			onPress: () => undefined,
+			onRelease: () => undefined,
+		};
+		const session = new X11PointerRecordingSession({
+			getDisplayBounds: () => ({ x: 0, y: 0, width: 1920, height: 1080 }),
+			maxSamples: 100,
+			sampleIntervalMs: 33,
+			startTimeMs: 1_000,
+			watchButtons: (handlers) => {
+				buttons.onPress = handlers.onPress;
+				buttons.onRelease = handlers.onRelease;
+				return () => undefined;
+			},
+		});
+
+		await session.start();
+		vi.setSystemTime(1_100);
+		buttons.onPress(1);
+		vi.setSystemTime(1_160);
+		buttons.onRelease(1);
+		const data = await session.stop();
+
+		expect(data.version).toBe(2);
+		expect(data.provider).toBe("none");
+		expect(data.samples[0]).toMatchObject({
+			timeMs: 0,
+			cx: 96 / 1920,
+			cy: 54 / 1080,
+			visible: true,
+			interactionType: "move",
+		});
+		const types = data.samples.map((sample) => sample.interactionType);
+		expect(types).toContain("click");
+		expect(types).toContain("mouseup");
+	});
+
+	it("uses an injected getPoint instead of Electron", async () => {
+		const session = new X11PointerRecordingSession({
+			getDisplayBounds: () => ({ x: 0, y: 0, width: 100, height: 100 }),
+			maxSamples: 10,
+			sampleIntervalMs: 33,
+			startTimeMs: 1_000,
+			getPoint: () => ({ x: 25, y: 75 }),
+			watchButtons: () => () => undefined,
+		});
+		await session.start();
+		const data = await session.stop();
+		expect(data.samples[0]).toMatchObject({ cx: 0.25, cy: 0.75 });
+	});
+});
diff --git a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts
new file mode 100644
index 0000000000..b11ea6dc54
--- /dev/null
+++ b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts
@@ -0,0 +1,248 @@
+import { type ChildProcess, execFile, type SpawnOptions, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { type Rectangle, screen } from "electron";
+import type { CursorRecordingData, CursorRecordingSample } from "../../../../src/native/contracts";
+import { clamp } from "../../../../src/utils/math";
+import type { CursorRecordingSession } from "./session";
+import {
+	consumeXevButtonEvents,
+	consumeXInputXi2Events,
+	interactionTypeForButton,
+	parseLibinputButtonLine,
+	parseXdotoolLocation,
+} from "./x11PointerParse";
+
+const execFileAsync = promisify(execFile);
+
+export interface X11PointerRecordingSessionOptions {
+	getDisplayBounds: () => Rectangle | null;
+	maxSamples: number;
+	sampleIntervalMs: number;
+	startTimeMs?: number;
+	/** Test injection: current pointer in screen pixels. */
+	getPoint?: () => { x: number; y: number } | null;
+	/** Test injection: subscribe to left/middle/right button edges. */
+	watchButtons?: (handlers: {
+		onPress: (button: number) => void;
+		onRelease: (button: number) => void;
+	}) => () => void;
+}
+
+type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+
+const CLICK_WATCHERS: { command: string; args: string[]; kind: "xi2" | "xev" | "libinput" }[] = [
+	{ command: "xinput", args: ["test-xi2", "--root"], kind: "xi2" },
+	{ command: "xev", args: ["-root", "-event", "button"], kind: "xev" },
+	{ command: "libinput", args: ["debug-events"], kind: "libinput" },
+];
+
+/**
+ * Position + click sampler for Linux X11 (including Xvfb) when the ScreenCast
+ * portal has no METADATA cursor mode.
+ *
+ * Position comes from Electron's `screen.getCursorScreenPoint()` (correct on
+ * X11), falling back to `xdotool getmouselocation` if the Electron point sits
+ * at the origin while xdotool disagrees. Clicks come from the first tool that
+ * actually starts: `xinput test-xi2 --root`, then `xev -root -event button`,
+ * then `libinput debug-events`.
+ */
+export class X11PointerRecordingSession implements CursorRecordingSession {
+	private samples: CursorRecordingSample[] = [];
+	private interval: NodeJS.Timeout | null = null;
+	private startTimeMs = 0;
+	private stopClickWatcher: (() => void) | null = null;
+	private lastPoint: { x: number; y: number } | null = null;
+
+	constructor(
+		private readonly options: X11PointerRecordingSessionOptions,
+		private readonly spawnFn: SpawnFn = spawn,
+	) {}
+
+	async start(): Promise<void> {
+		this.samples = [];
+		this.startTimeMs = this.options.startTimeMs ?? Date.now();
+		this.captureSample("move");
+		this.interval = setInterval(() => {
+			this.captureSample("move");
+		}, this.options.sampleIntervalMs);
+		this.stopClickWatcher = this.options.watchButtons
+			? this.options.watchButtons({
+					onPress: (button) => this.recordButton("press", button),
+					onRelease: (button) => this.recordButton("release", button),
+				})
+			: this.startExternalClickWatcher();
+	}
+
+	async stop(): Promise<CursorRecordingData> {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = null;
+		}
+		this.stopClickWatcher?.();
+		this.stopClickWatcher = null;
+
+		return {
+			version: 2,
+			provider: "none",
+			samples: this.samples,
+			assets: [],
+		};
+	}
+
+	updateCaptureBounds(_bounds: Rectangle): void {
+		// Positions are re-read against getDisplayBounds() on every sample.
+	}
+
+	private recordButton(kind: "press" | "release", button: number) {
+		const interactionType = interactionTypeForButton(kind, button);
+		if (!interactionType) {
+			return;
+		}
+		this.captureSample(interactionType);
+	}
+
+	private captureSample(interactionType: CursorRecordingSample["interactionType"]) {
+		const point = this.readPoint() ?? this.lastPoint;
+		if (!point) {
+			return;
+		}
+		this.lastPoint = point;
+		const display = this.options.getDisplayBounds() ?? screen.getDisplayNearestPoint(point).bounds;
+		const width = Math.max(1, display.width);
+		const height = Math.max(1, display.height);
+		this.samples.push({
+			timeMs: Math.max(0, Date.now() - this.startTimeMs),
+			cx: clamp((point.x - display.x) / width, 0, 1),
+			cy: clamp((point.y - display.y) / height, 0, 1),
+			visible: true,
+			interactionType: interactionType ?? "move",
+		});
+		if (this.samples.length > this.options.maxSamples) {
+			this.samples.shift();
+		}
+	}
+
+	private readPoint(): { x: number; y: number } | null {
+		if (this.options.getPoint) {
+			return this.options.getPoint();
+		}
+		const cursor = screen.getCursorScreenPoint();
+		if (cursor.x !== 0 || cursor.y !== 0) {
+			return cursor;
+		}
+		// {0,0} is either the real origin or a Wayland-style lie. Prefer xdotool
+		// when it answers with a different point; otherwise keep the Electron value.
+		refreshXdotoolLocationCache();
+		return xdotoolCache ?? cursor;
+	}
+
+	private startExternalClickWatcher(): () => void {
+		let child: ChildProcess | null = null;
+		let cancelled = false;
+		let buffer = "";
+		let kind: (typeof CLICK_WATCHERS)[number]["kind"] | null = null;
+
+		const handleChunk = (chunk: string) => {
+			buffer += chunk;
+			if (kind === "xi2") {
+				const parsed = consumeXInputXi2Events(buffer);
+				buffer = parsed.rest;
+				for (const event of parsed.events) {
+					this.recordButton(event.kind, event.button);
+				}
+				return;
+			}
+			if (kind === "xev") {
+				const parsed = consumeXevButtonEvents(buffer);
+				buffer = parsed.rest;
+				for (const event of parsed.events) {
+					this.recordButton(event.kind, event.button);
+				}
+				return;
+			}
+			const lines = buffer.split(/\r?\n/);
+			buffer = lines.pop() ?? "";
+			for (const line of lines) {
+				const event = parseLibinputButtonLine(line);
+				if (event) {
+					this.recordButton(event.kind, event.button);
+				}
+			}
+		};
+
+		const tryNext = (index: number) => {
+			if (cancelled || index >= CLICK_WATCHERS.length) {
+				if (!cancelled && index >= CLICK_WATCHERS.length) {
+					console.warn(
+						"[cursor-x11] no click watcher started (xinput, xev, and libinput all unavailable); " +
+							"pointer motion is still recorded",
+					);
+				}
+				return;
+			}
+			const spec = CLICK_WATCHERS[index];
+			let spawned: ChildProcess;
+			try {
+				spawned = this.spawnFn(spec.command, spec.args, {
+					stdio: ["ignore", "pipe", "pipe"],
+				});
+			} catch (error) {
+				console.warn(`[cursor-x11] ${spec.command} could not start:`, error);
+				tryNext(index + 1);
+				return;
+			}
+			child = spawned;
+			kind = spec.kind;
+			let failed = false;
+			spawned.once("error", (error) => {
+				if (cancelled || failed) {
+					return;
+				}
+				failed = true;
+				console.warn(`[cursor-x11] ${spec.command} could not start:`, error);
+				tryNext(index + 1);
+			});
+			spawned.stdout?.setEncoding("utf8");
+			spawned.stdout?.on("data", (chunk: string) => handleChunk(chunk));
+			spawned.stderr?.resume();
+		};
+
+		tryNext(0);
+
+		return () => {
+			cancelled = true;
+			if (child && !child.killed) {
+				child.kill("SIGTERM");
+			}
+			child = null;
+		};
+	}
+}
+
+let xdotoolCache: { x: number; y: number } | null = null;
+let xdotoolInflight = false;
+
+export function refreshXdotoolLocationCache(): void {
+	if (xdotoolInflight) {
+		return;
+	}
+	xdotoolInflight = true;
+	void execFileAsync("xdotool", ["getmouselocation", "--shell"], {
+		timeout: 400,
+	})
+		.then(({ stdout }) => {
+			xdotoolCache = parseXdotoolLocation(stdout);
+		})
+		.catch(() => {
+			xdotoolCache = null;
+		})
+		.finally(() => {
+			xdotoolInflight = false;
+		});
+}
+
+/** Test hook: reset the process-wide xdotool cache. */
+export function resetXdotoolLocationCacheForTests(): void {
+	xdotoolCache = null;
+	xdotoolInflight = false;
+}
diff --git a/electron/native/README.md b/electron/native/README.md
index 1a0774ef89..bd3a2086be 100644
--- a/electron/native/README.md
+++ b/electron/native/README.md
@@ -153,6 +153,12 @@ METADATA cursor mode is the only source of a real pointer position on Wayland:
 the compositor keeps the cursor out of the captured pixels and attaches it to
 each frame as `SPA_META_Cursor` instead.
 
+On **X11** the portal is often the opposite problem: `AvailableSourceTypes=0` or
+no METADATA cursor mode, while the pointer is still readable. The app then
+samples it through `X11PointerRecordingSession` (Electron, xdotool, xev) and
+writes the same `<video>.cursor.json` sidecar so `--auto-zoom` works without an
+import step. `OPENSCREEN_DISABLE_X11_CURSOR=1` turns that off.
+
 Helper locations, in resolution order:
 
 1. `OPENSCREEN_LINUX_CURSOR_HELPER_EXE`, for local development and diagnostics.
diff --git a/src/hooks/useScreenRecorder.ts b/src/hooks/useScreenRecorder.ts
index 3ec0a4ac4d..449a462fb9 100644
--- a/src/hooks/useScreenRecorder.ts
+++ b/src/hooks/useScreenRecorder.ts
@@ -84,6 +84,43 @@ function effectiveBrowserCursorMode(
 	return platform === "win32" ? requested : "system";
 }
 
+/**
+ * Cursor mode written into the session and handed to `set-recording-state`.
+ *
+ * Off win32 the browser pipeline cannot exclude the OS cursor from the pixels,
+ * so `effectiveBrowserCursorMode` forces "system" and the editor would otherwise
+ * skip auto-zoom (it treats a system-cursor take as having no sidecar). Linux
+ * X11 can still sample the pointer out of band, so the requested editable mode
+ * is kept: the sampler writes `<video>.cursor.json` and `--auto-zoom` sees it.
+ */
+function telemetryCursorMode(platform: string, requested: CursorCaptureMode): CursorCaptureMode {
+	if (platform === "linux") {
+		return requested;
+	}
+	return effectiveBrowserCursorMode(platform, requested);
+}
+
+async function pickFirstScreenSource(): Promise<boolean> {
+	const api = window.electronAPI;
+	if (!api?.getSources || !api.selectSource) {
+		return false;
+	}
+	const existing = await api.getSelectedSource();
+	if (existing) {
+		return true;
+	}
+	const sources = await api.getSources({
+		types: ["screen"],
+		thumbnailSize: { width: 1, height: 1 },
+	});
+	const screen = sources.find((source) => source.id.startsWith("screen:")) ?? sources[0];
+	if (!screen) {
+		return false;
+	}
+	const selected = await api.selectSource(screen, { persist: false });
+	return Boolean(selected);
+}
+
 const AUDIO_BITRATE_VOICE = 128_000;
 const AUDIO_BITRATE_SYSTEM = 192_000;
 
@@ -658,7 +695,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 						// — so the mode reported to the main process was forced to "system" and
 						// the stored metadata has to agree. It is user-visible: `openscreen
 						// project show` prints it.
-						cursorCaptureMode: effectiveBrowserCursorMode(
+						cursorCaptureMode: telemetryCursorMode(
 							window.electronAPI.getPlatform(),
 							cursorCaptureMode,
 						),
@@ -1604,6 +1641,24 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 				buildNativeLinuxRequest(recordMicrophone, activeRecordingId),
 			);
 			if (!result.success || !result.recordingId) {
+				if (result.fallbackToBrowser) {
+					console.warn(
+						"Native Linux capture unavailable; using browser capture and the X11 pointer sampler.",
+						result.error,
+					);
+					if (nativeWebcamRecorder) {
+						try {
+							if (nativeWebcamRecorder.recorder.state !== "inactive") {
+								nativeWebcamRecorder.recorder.stop();
+							}
+						} catch {
+							// Already stopped.
+						}
+						await nativeWebcamRecorder.discard();
+					}
+					await pickFirstScreenSource();
+					return false;
+				}
 				throw new Error(result.error ?? "Native Linux capture failed.");
 			}
 			if (!isCountdownRunActive(countdownRunToken)) {
@@ -1812,7 +1867,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 		preparedRecordingId?: number | null,
 	) => {
 		const platform = window.electronAPI.getPlatform();
-		const browserCursorCaptureMode = effectiveBrowserCursorMode(platform, cursorCaptureMode);
+		const storedCursorCaptureMode = telemetryCursorMode(platform, cursorCaptureMode);
 
 		try {
 			if (!isCountdownRunActive(countdownRunToken)) {
@@ -2110,7 +2165,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 			setRecording(true);
 			setPaused(false);
 			setElapsedSeconds(0);
-			window.electronAPI?.setRecordingState(true, recordingId.current, browserCursorCaptureMode);
+			window.electronAPI?.setRecordingState(true, recordingId.current, storedCursorCaptureMode);
 
 			const activeScreenRecorder = screenRecorder.current;
 			const activeWebcamRecorder = webcamRecorder.current;
diff --git a/src/lib/nativeLinuxRecording.ts b/src/lib/nativeLinuxRecording.ts
index 3beee7c521..bbc504ac43 100644
--- a/src/lib/nativeLinuxRecording.ts
+++ b/src/lib/nativeLinuxRecording.ts
@@ -88,6 +88,13 @@ export type NativeLinuxRecordingStartResult = {
 	error?: string;
 	/** "vaapi", "vulkan" or "software" — which rung of the encoder ladder won. */
 	videoEncoder?: string | null;
+	/**
+	 * Set when native capture could not start on an X11 session. The recorder
+	 * should fall through to Chromium capture (and the X11 pointer sampler)
+	 * rather than aborting the take. Unset on Wayland, where that fallback
+	 * would write {0,0} cursor samples.
+	 */
+	fallbackToBrowser?: boolean;
 };
 
 /**
diff --git a/technical-documentation/architecture/cursor.md b/technical-documentation/architecture/cursor.md
index bd8db12a86..3a22a053ed 100644
--- a/technical-documentation/architecture/cursor.md
+++ b/technical-documentation/architecture/cursor.md
@@ -6,6 +6,8 @@ The cursor feature records system-cursor position and, where the native provider
 
 Native capture keeps cursor data separate from the video frame. On Windows, the WGC cursor sampler in `electron/native/wgc-capture/src/cursor-sampler.cpp` samples the system cursor during desktop duplication and records its position, hotspot, bitmap, and cursor type. On macOS, the ScreenCaptureKit cursor helper at `electron/native/screencapturekit/Sources/OpenScreenMacOSCursorHelper/main.swift` samples the current system cursor, emits unique bitmap assets, and records cursor samples plus left-button interaction events. The recording sessions under `electron/native-bridge/cursor/recording/` select and wrap the platform provider; `telemetryCursorAdapter.ts` provides the position-only fallback when native assets are unavailable. The resulting contracts are `CursorRecordingData` and `CursorRecordingSample` in `src/native/contracts.ts`.
 
+On Linux the ScreenCast portal's METADATA cursor mode is the preferred source. When that mode is missing — common on X11 + Xvfb cloud-agent desktops, where the portal reports `AvailableSourceTypes=0` / `AvailableCursorModes=0` — OpenScreen samples the pointer itself (`X11PointerRecordingSession`): position from Electron's `screen.getCursorScreenPoint()` or `xdotool getmouselocation`, clicks from `xinput test-xi2`, `xev -root -event button`, or `libinput debug-events`. The take still writes `<videoPath>.cursor.json` (version 2) next to the recording, so `openscreen export --auto-zoom` needs no extra import step. `OPENSCREEN_DISABLE_X11_CURSOR=1` turns this off; `OPENSCREEN_FORCE_X11_CURSOR=1` turns it on even under Wayland (not useful there: every sample would sit at the origin). An external CSV can still be converted with `openscreen cursor import --csv mouse.csv --video take.mp4`.
+
 ## Telemetry
 
 Position telemetry is represented by `CursorTelemetryPoint` in `src/lib/cursorTelemetryBuffer.ts`. Each point contains `timeMs`, the offset from recording start, and `cx`/`cy`, clamped ratios of the captured surface (`cursorTelemetryBuffer.ts:1-10`). The main-process `CursorTelemetryBuffer` starts a session with a recording id, appends samples, and finalizes them into FIFO batches keyed by that id (`cursorTelemetryBuffer.ts:25-34`). This key keeps asynchronous persistence and discard operations associated with the correct recording. Native cursor samples use the same recording-time convention, and `crates/compositor/src/cursor.rs:100-123` loads a selected window by subtracting its offset so the first sample is at time zero.
@@ -47,3 +49,5 @@ Each sprite carries its hotspot as a **fraction of its own image**, not in pixel
 ## Known gaps
 
 macOS single-window capture can report a cursor offset relative to the captured surface. This remains an open platform-specific alignment issue; display capture does not exhibit the same verified gap.
+
+On Linux, a browser-pipeline fallback (portal cannot start, or the helper binary is missing) still bakes the OS cursor into the pixels. The X11 sampler writes telemetry anyway, so auto-zoom and the editable overlay work, but a themed overlay is drawn on top of the baked pointer. A take recorded with `ffmpeg -f x11grab -draw_mouse 0` plus `openscreen cursor import` avoids that.
diff --git a/technical-documentation/architecture/recording.md b/technical-documentation/architecture/recording.md
index 2f643ec222..1ce84f7bea 100644
--- a/technical-documentation/architecture/recording.md
+++ b/technical-documentation/architecture/recording.md
@@ -78,7 +78,7 @@ The macOS helper mixes the same two sources into one AAC track (`AudioTrackMixer
 
 The Linux helper mixes the same two sources into one AAC track as well (`AudioMix` in `electron/native/pipewire-capture/src/capture.rs`), and its emit cursor is the data-driven one Windows had: `AudioEncoder::next_pts` is a running count of the samples handed to the encoder, advanced only when a block is encoded, and `AudioMix::pump` returns early when no input has any. Nothing in that code makes a chunk go out for every chunk of real time — what does is the tap. System audio here is the default sink's MONITOR, and PipeWire keeps delivering its buffers whether or not anything is playing, silence included, where WASAPI loopback simply stops. So the count advances at real time for as long as the take runs and the cursor cannot stall. That is a property of the capture source and not of the timeline code, which is the thing to know before moving Linux audio off the sink monitor: a source that gates silence would reproduce the Windows failure above exactly (#406). The anchor half is a decision rather than an accident — the first video frame sets the epoch and clears the audio rings at that instant ("video frame 0 is now, so audio sample 0 is now too"), which is what keeps the pre-roll captured while the portal picker was up, an interval with no upper bound, from shifting the whole track earlier; `cargo test` covers it. The tail is covered by `Capture::finish`, which drains the rings and flushes the AAC encoder before the video flush, so the file ends with the take rather than with the last sound in it. What a mid-take overflow costs is bounded the same way: the ring drops its oldest samples and owes back silence of exactly that length, so the encoder falling two seconds behind leaves a gap where it happened instead of pulling every later sound earlier for the rest of the recording, and it is reported as `audio-dropped`. `npm run test:pw-audio-timeline:linux` measures it end to end — a tone played at a known instant, then the audio track's length against the video track's in the same file. Before it, the whole record that any of this held was one sentence in a commit message: a live 29-second capture whose 18-second tone came back as 18 seconds of steady signal, with the two streams ending 62 ms apart (video 29.100 s, audio 29.162 s). That 62 ms is also why the script allows 250 ms between the tracks where the macOS one allows 100: those two come out of a single writer session, and these two do not — the video track ends at the last `advance()` and the audio track at everything the rings still held, plus AAC's final padded block.
 
-Cursor samples are persisted as cursor telemetry rather than baked into editable-overlay recordings. The loader resolves the sidecar at `<videoPath>.cursor.json` or through the recording links; see [cursor.md](cursor.md) for the telemetry format and rendering path.
+Cursor samples are persisted as cursor telemetry rather than baked into editable-overlay recordings. The loader resolves the sidecar at `<videoPath>.cursor.json` or through the recording links; see [cursor.md](cursor.md) for the telemetry format and rendering path. On Linux X11, when the portal cannot supply METADATA cursor samples, the same sidecar is filled by the X11 pointer sampler during the take so `--auto-zoom` has clicks to work from.
 
 ## Known gaps
 
diff --git a/website/docs/cli.md b/website/docs/cli.md
index f2bf6198a0..0dcf86bbec 100644
--- a/website/docs/cli.md
+++ b/website/docs/cli.md
@@ -14,7 +14,7 @@ keywords:
 
 # Screen recorder CLI
 
-OpenScreen's command-line interface is built into the desktop app's own executable. `openscreen record`, `captions`, `export`, `pack`, `info` and `sources` run from a terminal without opening a window, and `--json` turns their output into NDJSON on stdout. A script, a CI job or a coding agent can record a take, edit the `.openscreen` project as plain JSON, and render an MP4 or GIF with the same native compositor as the editor's **Export** button.
+OpenScreen's command-line interface is built into the desktop app's own executable. `openscreen record`, `captions`, `export`, `pack`, `info`, `cursor import` and `sources` run from a terminal without opening a window, and `--json` turns their output into NDJSON on stdout. A script, a CI job or a coding agent can record a take, edit the `.openscreen` project as plain JSON, and render an MP4 or GIF with the same native compositor as the editor's **Export** button.
 
 It is not a server tool. Every command starts Electron, which needs a display server even though no window appears, and recording needs a real desktop session. See [When the CLI is not the right tool](#when-the-cli-is-not-the-right-tool).
 
@@ -80,7 +80,7 @@ With `--camera`, the webcam is recorded beside the screen, and the `--project` f
 
 - **macOS.** Capture goes through the ScreenCaptureKit helper, with no fallback. The Screen Recording permission is required; for a development build started from a terminal, grant it to the terminal. With `--mic`, the CLI asks for microphone access if it has not been granted. Pointer clicks and shapes are only recorded with the Accessibility permission.
 - **Windows.** Capture goes through the Windows Graphics Capture helper, from Windows 10 build 19041. On older builds, or without the helper, OpenScreen falls back to browser capture. Windows never delivers SIGTERM: use Ctrl+C, stdin `stop`, or `--duration`.
-- **Linux.** Capture goes through the PipeWire helper and the desktop's ScreenCast portal. The portal's own picker decides what is recorded, and it opens on every run and waits for an answer, so `--display` and `--window` do not choose the source and a Linux recording cannot start unattended. It needs a desktop session with `xdg-desktop-portal`: an SSH session without a display cannot record. Only a build without the helper falls back to Chromium's capture.
+- **Linux.** Capture goes through the PipeWire helper and the desktop's ScreenCast portal. The portal's own picker decides what is recorded, and it opens on every run and waits for an answer, so `--display` and `--window` do not choose the source and a Linux recording cannot start unattended. It needs a desktop session with `xdg-desktop-portal`: an SSH session without a display cannot record. Only a build without the helper falls back to Chromium's capture. On **X11** hosts (including Xvfb cloud agents) the portal often advertises no METADATA cursor mode; OpenScreen then samples the pointer itself and still writes `<video>.cursor.json`, so `--auto-zoom` needs no extra step. `OPENSCREEN_DISABLE_X11_CURSOR=1` turns that sampler off.
 
 ### `openscreen sources`
 
@@ -176,6 +176,27 @@ openscreen export demo.openscreen -o demo.mp4   # captions are burned into the v
 - The project's screen video must have an audio track, for example from `record --mic`.
 - Captions are burned into the export. There is no subtitle file output. See [Captions](./captions.md).
 
+### `openscreen cursor import` {#openscreen-cursor-import}
+
+Writes a version-2 `<video>.cursor.json` sidecar from an external mouse track. OpenScreen's own `record` already writes that file when pointer data is available — including on X11 hosts where the ScreenCast portal has no METADATA cursor mode, via the automatic X11 sampler. Use `cursor import` when the video was captured outside OpenScreen (ffmpeg x11grab, another recorder) and you still want `--auto-zoom` and the editable cursor.
+
+```bash
+openscreen cursor import --csv mouse.csv --clicks clicks.txt --video take.mp4 --width 1920 --height 1200
+openscreen export project.openscreen --auto-zoom -o polished.mp4
+```
+
+| Option | Meaning |
+|---|---|
+| `--csv <mouse.csv>` | Required. Columns `t,x,y` (seconds + pixel coordinates). `time` / `time_s` are accepted for `t` |
+| `--clicks <clicks.txt>` | Optional. One seconds-timestamp per line; a `#` comments the line out |
+| `--video <file.mp4>` | Sidecar path becomes `<file.mp4>.cursor.json` |
+| `-o`, `--output <file>` | Explicit sidecar path |
+| `--width <px>` / `--height <px>` | Capture size used to normalise `x` / `y` (defaults 1920×1200) |
+| `--click-hold-ms <ms>` | Synthesized `mouseup` this long after each click (default 60) |
+| `--json` | Machine-readable result on stdout |
+
+Each sample is `{ timeMs, cx, cy, visible, interactionType }`, with `interactionType` one of `move`, `click`, or `mouseup`. `cx` / `cy` are 0–1 fractions of the capture. That is the same schema `record` writes and that `--auto-zoom` reads.
+
 ### `openscreen mcp`
 
 Serves OpenScreen's MCP tools on stdin and stdout, for a coding agent that starts it: the editing tools, plus recording, export and still frames. You do not run it yourself; your agent does, once it is set up as [Letting an agent make the whole video](./ai-editing.md#letting-an-agent-make-the-whole-video) shows.
@@ -289,7 +310,7 @@ openscreen export demo.openscreen -o demo.mp4 --auto-zoom --audio voice.m4a --au
 }
 ```
 
-Save it in the same folder as the clip. Without cursor telemetry, `--auto-zoom` has nothing to work from.
+Save it in the same folder as the clip. Without cursor telemetry, `--auto-zoom` has nothing to work from. If the clip was recorded outside OpenScreen (for example `ffmpeg -f x11grab -draw_mouse 0`), convert a mouse CSV into the sidecar with [`openscreen cursor import`](#openscreen-cursor-import) so `--auto-zoom` sees the clicks.
 
 ## Displays, CI and servers
 
@@ -313,6 +334,8 @@ The CLI is part of the [OpenScreen repository](https://github.com/getopenscreen/
 - `electron/cli/args.ts`: the argument parser and the usage text, unit-tested in `args.test.ts`.
 - `electron/cli/cliMain.ts`: the windowless boot, the stdio protocol, stop signals and exit codes.
 - `electron/cli/projectCommands.ts`: `pack` and `info`.
+- `electron/cli/cursorCommands.ts`: `cursor import`.
+- `electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts`: X11 pointer sampler used when the ScreenCast portal has no METADATA cursor mode.
 - `electron/mcp/stdio-server.ts` and `electron/mcp/media-tools.ts`: `mcp`.
 - `src/cli/`: the hidden-window runners for `record`, `sources`, `export` and `captions`.
 - `src/lib/cliContracts.ts`: the request and result types shared by both sides.
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 57b910a814..0e016be1f1 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -182,8 +182,8 @@ The editing tools are the same everywhere — zooms, backgrounds, crop/trim/spee
 
 | | macOS | Windows | Linux |
 |---|---|---|---|
-| Capture pipeline | Native (ScreenCaptureKit) | Native (Windows Graphics Capture) on build 19041 and later; browser fallback on older builds or without the helper | Native (PipeWire via the ScreenCast portal); browser fallback without the helper, losing hardware encode and cursor telemetry |
-| Custom cursor / click effects | ✅ — clicks and cursor shape need the Accessibility permission | ✅ | ✅ on Wayland — click capture needs mouse evdev permissions ([details](#mouse-clicks-on-wayland)) |
+| Capture pipeline | Native (ScreenCaptureKit) | Native (Windows Graphics Capture) on build 19041 and later; browser fallback on older builds or without the helper | Native (PipeWire via the ScreenCast portal); browser fallback without the helper. On X11, when the portal has no METADATA cursor mode, pointer telemetry is still sampled automatically |
+| Custom cursor / click effects | ✅ — clicks and cursor shape need the Accessibility permission | ✅ | ✅ on Wayland — click capture needs mouse evdev permissions ([details](#mouse-clicks-on-wayland)). On X11, position and clicks are sampled even when the portal has no METADATA mode |
 | Webcam | Browser capture, saved as a separate file (still works as PiP) | Native capture, saved as a separate file | Browser capture, saved as a separate file (still works as PiP) |
 | System audio | Works out of the box; its own permission prompt on macOS 15.2+, covered by Screen Recording on older versions | Works out of the box | Needs PipeWire as the sound server (default on Ubuntu 22.10+, Fedora 34+) |
 | MP4 export | ✅ | ✅ | ✅ — H.264 on the GPU through VAAPI when the GPU stack allows it (see the note below), software otherwise |
diff --git a/website/docs/recording.md b/website/docs/recording.md
index e9978f3a12..2a4a71ef9a 100644
--- a/website/docs/recording.md
+++ b/website/docs/recording.md
@@ -50,7 +50,7 @@ On Windows, macOS, and Linux, a cursor-mode toggle switches between:
 What the editable overlay captures depends on the platform:
 - **Windows** — the real cursor shape and clicks.
 - **macOS** — the cursor shape and clicks, which need the Accessibility permission. In this mode, pressing record without it opens the permissions window instead of starting (see [macOS installation](./installation.md#macos)).
-- **Linux** — position and shape through the ScreenCast portal, plus left clicks when your user can read the mouse, through a udev rule (recommended) or the `input` group (see [Mouse clicks on Wayland](./installation.md#mouse-clicks-on-wayland)).
+- **Linux** — position and shape through the ScreenCast portal, plus left clicks when your user can read the mouse, through a udev rule (recommended) or the `input` group (see [Mouse clicks on Wayland](./installation.md#mouse-clicks-on-wayland)). On **X11** (including Xvfb), if the portal has no METADATA cursor mode, OpenScreen samples the pointer itself and still writes `<video>.cursor.json`, so auto-zoom and the editable overlay have data. Browser-fallback takes may also bake the OS cursor into the pixels; a take recorded with `ffmpeg -draw_mouse 0` plus [`openscreen cursor import`](./cli.md#openscreen-cursor-import) does not.
 
 A Linux take that falls back to [browser capture](#native-vs-browser-capture) records the system cursor, whichever mode you picked.
 

From 4d76cd588040e86ef473d0d546ab2baf77caf037 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 28 Oct 2026 14:33:26 +0000
Subject: [PATCH 2/2] fix(linux): address CodeRabbit review on X11 cursor
 telemetry

Stop the X11 sampler on discard, compact pause ranges into the fallback
sidecar, start the sampler clock at capture start, harden cursor import
CSV parsing/writes, trim XI2 rest, fail over click watchers on exit,
and pass the browser-fallback source through instead of re-reading
getSelectedSource().
---
 electron/cli/args.test.ts                     | 11 +++
 electron/cli/cursorCommands.test.ts           | 42 ++++++++++-
 electron/ipc/handlers.ts                      | 21 ++++--
 electron/media/cursorTelemetryImport.test.ts  | 69 +++++++++++++++++-
 electron/media/cursorTelemetryImport.ts       | 70 +++++++++++++++----
 .../capture/linuxNativeCaptureSession.test.ts |  4 ++
 .../capture/linuxNativeCaptureSession.ts      |  6 ++
 .../cursor/recording/x11PointerParse.test.ts  | 14 ++++
 .../cursor/recording/x11PointerParse.ts       | 14 +++-
 .../x11PointerRecordingSession.test.ts        | 42 +++++++++++
 .../recording/x11PointerRecordingSession.ts   | 25 +++++--
 src/hooks/useScreenRecorder.ts                | 28 +++++---
 .../architecture/recording.md                 |  2 +-
 website/docs/cli.md                           |  4 +-
 website/docs/recording.md                     |  2 +-
 15 files changed, 315 insertions(+), 39 deletions(-)

diff --git a/electron/cli/args.test.ts b/electron/cli/args.test.ts
index 3dc59092d8..0dca2edcff 100644
--- a/electron/cli/args.test.ts
+++ b/electron/cli/args.test.ts
@@ -332,6 +332,17 @@ describe("parseCliArgs", () => {
 		});
 	});
 
+	it("parses cursor import with --output and no --video", () => {
+		expect(
+			parse(["cursor", "import", "--csv", "mouse.csv", "--output", "out.cursor.json"]),
+		).toMatchObject({
+			kind: "cursor-import",
+			csvPath: inCwd("mouse.csv"),
+			videoPath: null,
+			outputPath: inCwd("out.cursor.json"),
+		});
+	});
+
 	it("rejects cursor import without a csv or an output target", () => {
 		expect(parse(["cursor"])).toMatchObject({ kind: "error" });
 		expect(parse(["cursor", "import"])).toMatchObject({ kind: "error" });
diff --git a/electron/cli/cursorCommands.test.ts b/electron/cli/cursorCommands.test.ts
index 5b73a4d4ad..9910b4d438 100644
--- a/electron/cli/cursorCommands.test.ts
+++ b/electron/cli/cursorCommands.test.ts
@@ -65,6 +65,46 @@ describe("runCursorImportCommand", () => {
 			},
 		);
 		const payload = JSON.parse(lines.join(""));
-		expect(payload).toMatchObject({ event: "done", success: true, outputPath, samples: 1 });
+		expect(payload).toMatchObject({
+			event: "done",
+			success: true,
+			outputPath,
+			samples: 1,
+			moves: 1,
+			clicks: 0,
+			mouseups: 0,
+		});
+	});
+
+	it("counts click and mouseup samples in JSON", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		const clicksPath = path.join(dir, "clicks.txt");
+		const outputPath = path.join(dir, "out.cursor.json");
+		await fs.writeFile(csvPath, "t,x,y\n0,0,0\n1,10,10\n", "utf8");
+		await fs.writeFile(clicksPath, "0.5\n", "utf8");
+		const lines: string[] = [];
+		await runCursorImportCommand(
+			{
+				csvPath,
+				clicksPath,
+				videoPath: null,
+				outputPath,
+				width: 10,
+				height: 10,
+				clickHoldMs: 60,
+			},
+			true,
+			(text) => {
+				lines.push(text);
+			},
+		);
+		expect(JSON.parse(lines.join(""))).toMatchObject({
+			event: "done",
+			success: true,
+			samples: 4,
+			moves: 2,
+			clicks: 1,
+			mouseups: 1,
+		});
 	});
 });
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index d5f7af41a2..454a1a8004 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -1357,12 +1357,14 @@ async function startCursorRecording(recordingId?: number) {
 			cursorRecordingSession = null;
 		}
 		pendingCursorRecordingData = null;
+		// Clock origin is sampler start, which is after waitUntilCapturing() —
+		// i.e. at or shortly after the first encoded frame. Passing recordingId
+		// here used to pin t=0 to prepare time (picker + countdown), so every
+		// X11 sample landed late relative to the video.
 		cursorRecordingSession = createX11PointerRecordingSession({
 			getDisplayBounds: getSelectedSourceBounds,
 			maxSamples: MAX_CURSOR_SAMPLES,
 			sampleIntervalMs: CURSOR_SAMPLE_INTERVAL_MS,
-			startTimeMs:
-				typeof recordingId === "number" && Number.isFinite(recordingId) ? recordingId : undefined,
 		});
 		try {
 			await cursorRecordingSession.start();
@@ -2867,6 +2869,8 @@ export function registerIpcHandlers(
 
 		try {
 			if (discard) {
+				await stopCursorRecording();
+				pendingCursorRecordingData = null;
 				session.discard();
 				const discarded = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
 				await Promise.all([
@@ -2888,8 +2892,17 @@ export function registerIpcHandlers(
 			// produced the pixels, so there is no clock offset to correct. When
 			// the portal had no METADATA cursor mode the track is empty; the X11
 			// sampler started alongside the take then fills the sidecar so
-			// `--auto-zoom` still has clicks to work from.
-			const cursor = result.cursor.samples.length > 0 ? result.cursor : pendingCursorRecordingData;
+			// `--auto-zoom` still has clicks to work from. Those fallback samples
+			// still include paused time, which the video does not.
+			const cursor =
+				result.cursor.samples.length > 0
+					? result.cursor
+					: pendingCursorRecordingData
+						? compactCursorTelemetryPauseRanges(
+								pendingCursorRecordingData,
+								result.cursorPauseRanges,
+							)
+						: null;
 			pendingCursorRecordingData = null;
 			if (cursorCaptureMode === "editable-overlay" && cursor && cursor.samples.length > 0) {
 				await fs.writeFile(`${result.path}.cursor.json`, JSON.stringify(cursor, null, 2), "utf-8");
diff --git a/electron/media/cursorTelemetryImport.test.ts b/electron/media/cursorTelemetryImport.test.ts
index a5cd4a4a03..2d9b22d7c6 100644
--- a/electron/media/cursorTelemetryImport.test.ts
+++ b/electron/media/cursorTelemetryImport.test.ts
@@ -17,6 +17,15 @@ describe("cursorTelemetryImport", () => {
 			{ t: 0.5, x: 30, y: 40 },
 		]);
 		expect(parseMouseCsv("time,x,y\n1,2,3\n")).toEqual([{ t: 1, x: 2, y: 3 }]);
+		expect(parseMouseCsv('"t","x","y"\n"1","2","3"\n')).toEqual([{ t: 1, x: 2, y: 3 }]);
+	});
+
+	it("rejects a CSV with no time column", () => {
+		expect(() => parseMouseCsv("x,y\n10,20\n")).toThrow(/t \(or time \/ time_s\)/);
+	});
+
+	it("skips rows with empty numeric cells", () => {
+		expect(parseMouseCsv("t,x,y\n1,,25\n2,10,20\n")).toEqual([{ t: 2, x: 10, y: 20 }]);
 	});
 
 	it("parses click timestamps, skipping comments", () => {
@@ -39,7 +48,23 @@ describe("cursorTelemetryImport", () => {
 		const click = data.samples.find((sample) => sample.interactionType === "click");
 		const mouseup = data.samples.find((sample) => sample.interactionType === "mouseup");
 		expect(click).toMatchObject({ timeMs: 500, cx: 0.5, cy: 0.5 });
-		expect(mouseup).toMatchObject({ timeMs: 560, cx: 0.5, cy: 0.5 });
+		expect(mouseup).toMatchObject({ timeMs: 560, cx: 0.56, cy: 0.56 });
+		expect(data.samples.filter((sample) => sample.interactionType === "click")).toHaveLength(1);
+		expect(data.samples.filter((sample) => sample.interactionType === "mouseup")).toHaveLength(1);
+	});
+
+	it("places a click-only import at the capture centre", () => {
+		const data = buildCursorSidecar({
+			mouse: [],
+			clicks: [1],
+			width: 1920,
+			height: 1080,
+			clickHoldMs: 60,
+		});
+		expect(data.samples).toEqual([
+			expect.objectContaining({ timeMs: 1000, cx: 0.5, cy: 0.5, interactionType: "click" }),
+			expect.objectContaining({ timeMs: 1060, cx: 0.5, cy: 0.5, interactionType: "mouseup" }),
+		]);
 	});
 });
 
@@ -74,5 +99,47 @@ describe("writeCursorSidecarFromCsv", () => {
 		expect(data.samples.length).toBeGreaterThan(2);
 		const loaded = await readCursorRecordingFileAt(outputPath);
 		expect(loaded.samples.some((sample) => sample.interactionType === "click")).toBe(true);
+		const click = loaded.samples.find((sample) => sample.interactionType === "click");
+		expect(click?.cx).toBeCloseTo(0.075);
+		expect(click?.cy).toBeCloseTo(0.075);
+	});
+
+	it("writes --output without a video path", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		const outputPath = path.join(dir, "sidecar.cursor.json");
+		await fs.writeFile(csvPath, "t,x,y\n0,10,20\n", "utf8");
+		const { data } = await writeCursorSidecarFromCsv({
+			csvPath,
+			outputPath,
+			width: 100,
+			height: 100,
+		});
+		expect(data.samples[0]).toMatchObject({ cx: 0.1, cy: 0.2 });
+		await expect(fs.readFile(outputPath, "utf8")).resolves.toContain('"cx": 0.1');
+	});
+
+	it("rejects an empty import before writing", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		const outputPath = path.join(dir, "out.cursor.json");
+		await fs.writeFile(csvPath, "t,x,y\n", "utf8");
+		await fs.writeFile(outputPath, "keep-me", "utf8");
+		await expect(
+			writeCursorSidecarFromCsv({ csvPath, outputPath, width: 1920, height: 1080 }),
+		).rejects.toThrow(/no samples/);
+		await expect(fs.readFile(outputPath, "utf8")).resolves.toBe("keep-me");
+	});
+
+	it("rejects an --output path that matches --csv", async () => {
+		const csvPath = path.join(dir, "mouse.csv");
+		await fs.writeFile(csvPath, "t,x,y\n0,1,2\n", "utf8");
+		await expect(
+			writeCursorSidecarFromCsv({
+				csvPath,
+				outputPath: csvPath,
+				width: 10,
+				height: 10,
+			}),
+		).rejects.toThrow(/same path as --csv/);
+		await expect(fs.readFile(csvPath, "utf8")).resolves.toBe("t,x,y\n0,1,2\n");
 	});
 });
diff --git a/electron/media/cursorTelemetryImport.ts b/electron/media/cursorTelemetryImport.ts
index 6d5ae540a6..c2207a435e 100644
--- a/electron/media/cursorTelemetryImport.ts
+++ b/electron/media/cursorTelemetryImport.ts
@@ -9,6 +9,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { CursorRecordingData, CursorRecordingSample } from "../../src/native/contracts";
 import { clamp } from "../../src/utils/math";
+import { renameWithRetry } from "../atomic-rename";
 import { CURSOR_TELEMETRY_VERSION } from "./cursorSidecar";
 
 export type MouseCsvRow = { t: number; x: number; y: number };
@@ -31,17 +32,25 @@ export interface BuildCursorSidecarOptions {
 	clickHoldMs?: number;
 }
 
+function unquoteCell(cell: string): string {
+	const trimmed = cell.trim();
+	if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		return trimmed.slice(1, -1).replace(/""/g, '"');
+	}
+	return trimmed;
+}
+
 export function parseMouseCsv(text: string): MouseCsvRow[] {
 	const lines = text.split(/\r?\n/);
 	if (lines.length === 0) {
 		return [];
 	}
-	const header = lines[0].split(",").map((cell) => cell.trim().toLowerCase());
+	const header = lines[0].split(",").map((cell) => unquoteCell(cell).toLowerCase());
 	const tIndex = header.findIndex((name) => name === "t" || name === "time" || name === "time_s");
 	const xIndex = header.findIndex((name) => name === "x");
 	const yIndex = header.findIndex((name) => name === "y");
-	if (xIndex < 0 || yIndex < 0) {
-		throw new Error("mouse CSV must have columns x and y (and t, time, or time_s)");
+	if (tIndex < 0 || xIndex < 0 || yIndex < 0) {
+		throw new Error("mouse CSV must have columns x, y, and t (or time / time_s)");
 	}
 	const rows: MouseCsvRow[] = [];
 	for (const line of lines.slice(1)) {
@@ -50,9 +59,15 @@ export function parseMouseCsv(text: string): MouseCsvRow[] {
 			continue;
 		}
 		const cells = trimmed.split(",");
-		const t = tIndex >= 0 ? Number(cells[tIndex]) : 0;
-		const x = Number(cells[xIndex]);
-		const y = Number(cells[yIndex]);
+		const tCell = unquoteCell(cells[tIndex] ?? "");
+		const xCell = unquoteCell(cells[xIndex] ?? "");
+		const yCell = unquoteCell(cells[yIndex] ?? "");
+		if (!tCell || !xCell || !yCell) {
+			continue;
+		}
+		const t = Number(tCell);
+		const x = Number(xCell);
+		const y = Number(yCell);
 		if (!Number.isFinite(t) || !Number.isFinite(x) || !Number.isFinite(y)) {
 			continue;
 		}
@@ -70,7 +85,7 @@ export function parseClickTimestamps(text: string): number[] {
 		if (!trimmed || trimmed.startsWith("#")) {
 			continue;
 		}
-		const value = Number(trimmed.split(",")[0]);
+		const value = Number(unquoteCell(trimmed.split(",")[0] ?? ""));
 		if (Number.isFinite(value)) {
 			out.push(value);
 		}
@@ -79,9 +94,6 @@ export function parseClickTimestamps(text: string): number[] {
 }
 
 function cursorAt(samples: MouseCsvRow[], t: number): { x: number; y: number } {
-	if (samples.length === 0) {
-		return { x: 0.5, y: 0.5 };
-	}
 	if (t <= samples[0].t) {
 		return { x: samples[0].x, y: samples[0].y };
 	}
@@ -132,9 +144,17 @@ export function buildCursorSidecar(options: BuildCursorSidecarOptions): CursorRe
 		add(row.t, row.x, row.y, "move");
 	}
 	for (const clickT of options.clicks ?? []) {
-		const point = cursorAt(options.mouse, clickT);
-		add(clickT, point.x, point.y, "click");
-		add(clickT + clickHoldMs / 1000, point.x, point.y, "mouseup");
+		const clickPoint =
+			options.mouse.length === 0
+				? { x: width / 2, y: height / 2 }
+				: cursorAt(options.mouse, clickT);
+		add(clickT, clickPoint.x, clickPoint.y, "click");
+		const releaseT = clickT + clickHoldMs / 1000;
+		const releasePoint =
+			options.mouse.length === 0
+				? { x: width / 2, y: height / 2 }
+				: cursorAt(options.mouse, releaseT);
+		add(releaseT, releasePoint.x, releasePoint.y, "mouseup");
 	}
 
 	const dedup = new Map<string, CursorRecordingSample>();
@@ -173,6 +193,10 @@ export interface WriteCursorSidecarFromCsvOptions {
 	clickHoldMs?: number;
 }
 
+function sameResolvedPath(a: string, b: string): boolean {
+	return path.resolve(a) === path.resolve(b);
+}
+
 export async function writeCursorSidecarFromCsv(
 	options: WriteCursorSidecarFromCsvOptions,
 ): Promise<{ outputPath: string; data: CursorRecordingData }> {
@@ -180,6 +204,12 @@ export async function writeCursorSidecarFromCsv(
 		throw new Error("provide --output or --video");
 	}
 	const outputPath = options.outputPath ?? defaultCursorSidecarPath(options.videoPath as string);
+	if (sameResolvedPath(outputPath, options.csvPath)) {
+		throw new Error("--output must not be the same path as --csv");
+	}
+	if (options.clicksPath && sameResolvedPath(outputPath, options.clicksPath)) {
+		throw new Error("--output must not be the same path as --clicks");
+	}
 	const csvText = await fs.readFile(options.csvPath, "utf8");
 	const clicksText = options.clicksPath ? await fs.readFile(options.clicksPath, "utf8") : "";
 	const data = buildCursorSidecar({
@@ -189,7 +219,19 @@ export async function writeCursorSidecarFromCsv(
 		height: options.height,
 		clickHoldMs: options.clickHoldMs,
 	});
+	if (data.samples.length === 0) {
+		throw new Error("cursor import produced no samples; sidecar was not written");
+	}
+	const tmpPath = `${outputPath}.${process.pid}.tmp`;
 	await fs.mkdir(path.dirname(outputPath), { recursive: true });
-	await fs.writeFile(outputPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	await fs.writeFile(tmpPath, `${JSON.stringify(data, null, 2)}\n`, {
+		encoding: "utf8",
+		flag: "wx",
+	});
+	try {
+		await renameWithRetry(tmpPath, outputPath);
+	} finally {
+		await fs.rm(tmpPath, { force: true }).catch(() => undefined);
+	}
 	return { outputPath, data };
 }
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index 0d900a7d70..eee5495448 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -526,6 +526,10 @@ describe("LinuxNativeCaptureSession", () => {
 		const result = await finishCapture(session, 2_000);
 
 		expect(result.cursor.samples.map((sample) => sample.timeMs)).toEqual([100, 300, 500]);
+		expect(result.cursorPauseRanges).toEqual([
+			{ startMs: 200, endMs: 400 },
+			{ startMs: 600, endMs: 800 },
+		]);
 		expect(helper.stdinWrites.filter((line) => line === "pause\n")).toHaveLength(2);
 		expect(helper.stdinWrites.filter((line) => line === "resume\n")).toHaveLength(2);
 	});
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index 19a83b5c60..5c026ba2c4 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -85,6 +85,11 @@ export interface LinuxCaptureResult {
 	frames: number;
 	droppedFrames: number;
 	cursor: CursorRecordingData;
+	/**
+	 * Pause ranges relative to capture start, so an out-of-band cursor track
+	 * (the X11 pointer sampler) can be compacted the same way as `cursor`.
+	 */
+	cursorPauseRanges: CursorPauseRange[];
 	/** What the portal actually granted, when it said. */
 	sourceKind?: LinuxCaptureSourceKind;
 	videoEncoder?: string;
@@ -579,6 +584,7 @@ export class LinuxNativeCaptureSession {
 						this.cursor.toRecordingData(),
 						this.cursorPauseRanges,
 					),
+					cursorPauseRanges: this.cursorPauseRanges.slice(),
 					...(this.sourceKind ? { sourceKind: this.sourceKind } : {}),
 					...(this.videoEncoder ? { videoEncoder: this.videoEncoder } : {}),
 				};
diff --git a/electron/native-bridge/cursor/recording/x11PointerParse.test.ts b/electron/native-bridge/cursor/recording/x11PointerParse.test.ts
index f9a9f37e98..9cb2980a57 100644
--- a/electron/native-bridge/cursor/recording/x11PointerParse.test.ts
+++ b/electron/native-bridge/cursor/recording/x11PointerParse.test.ts
@@ -51,6 +51,20 @@ describe("consumeXInputXi2Events", () => {
 		]);
 		expect(parsed.rest).toBe("");
 	});
+
+	it("drops complete non-button blocks and keeps only a trailing incomplete rest", () => {
+		const motion = `EVENT type 17 (RawMotion)
+    device: 12 (12)
+    detail: 0
+    flags:
+`;
+		const parsed = consumeXInputXi2Events(
+			`${motion}${press}${motion}EVENT type 4 (ButtonPress)\n    device: 12\n`,
+		);
+		expect(parsed.events).toEqual([{ kind: "press", button: 1 }]);
+		expect(parsed.rest).toBe("EVENT type 4 (ButtonPress)\n    device: 12\n");
+		expect(parsed.rest).not.toContain("RawMotion");
+	});
 });
 
 describe("consumeXevButtonEvents", () => {
diff --git a/electron/native-bridge/cursor/recording/x11PointerParse.ts b/electron/native-bridge/cursor/recording/x11PointerParse.ts
index 5abc46cb86..d993495c14 100644
--- a/electron/native-bridge/cursor/recording/x11PointerParse.ts
+++ b/electron/native-bridge/cursor/recording/x11PointerParse.ts
@@ -30,18 +30,26 @@ export function consumeXInputXi2Events(buffer: string): {
 	const events: ParsedButtonEvent[] = [];
 	const blocks = buffer.split(/(?=EVENT type )/);
 	let rest = "";
-	for (const block of blocks) {
+	for (const [index, block] of blocks.entries()) {
+		const isLast = index === blocks.length - 1;
 		if (!block.trim()) {
 			continue;
 		}
 		const header = block.match(/EVENT type\s+(\d+)\s+\((ButtonPress|ButtonRelease)\)/i);
 		if (!header) {
-			rest += block;
+			// Complete non-button blocks (motion, hierarchy, …) must not accumulate
+			// for the whole recording. Keep only a trailing block, which may still
+			// be incomplete.
+			if (isLast) {
+				rest += block;
+			}
 			continue;
 		}
 		const detail = block.match(/\bdetail:\s*(\d+)/);
 		if (!detail) {
-			rest += block;
+			if (isLast) {
+				rest += block;
+			}
 			continue;
 		}
 		events.push({
diff --git a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
index 9acaca0df1..533286169a 100644
--- a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
+++ b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.test.ts
@@ -1,3 +1,5 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const getCursorScreenPoint = vi.fn(() => ({ x: 96, y: 54 }));
@@ -86,4 +88,44 @@ describe("X11PointerRecordingSession", () => {
 		const data = await session.stop();
 		expect(data.samples[0]).toMatchObject({ cx: 0.25, cy: 0.75 });
 	});
+
+	it("advances to the next click watcher when a child exits", async () => {
+		const commands: string[] = [];
+		const spawnFn = (command: string) => {
+			commands.push(command);
+			const child = new EventEmitter() as EventEmitter & {
+				stdout: PassThrough;
+				stderr: PassThrough;
+				killed: boolean;
+				kill: () => boolean;
+			};
+			child.stdout = new PassThrough();
+			child.stderr = new PassThrough();
+			child.killed = false;
+			child.kill = () => {
+				child.killed = true;
+				return true;
+			};
+			queueMicrotask(() => child.emit("exit", 1, null));
+			return child;
+		};
+		const session = new X11PointerRecordingSession(
+			{
+				getDisplayBounds: () => ({ x: 0, y: 0, width: 1920, height: 1080 }),
+				maxSamples: 10,
+				sampleIntervalMs: 33,
+				startTimeMs: 1_000,
+				getPoint: () => ({ x: 1, y: 1 }),
+			},
+			spawnFn as unknown as ConstructorParameters<typeof X11PointerRecordingSession>[1],
+		);
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		await session.start();
+		for (let i = 0; i < 8; i++) {
+			await Promise.resolve();
+		}
+		await session.stop();
+		expect(commands).toEqual(["xinput", "xev", "libinput"]);
+		expect(warn.mock.calls.some((call) => String(call[0]).includes("using xev -root"))).toBe(true);
+	});
 });
diff --git a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts
index b11ea6dc54..9055609f4e 100644
--- a/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts
+++ b/electron/native-bridge/cursor/recording/x11PointerRecordingSession.ts
@@ -193,14 +193,26 @@ export class X11PointerRecordingSession implements CursorRecordingSession {
 			}
 			child = spawned;
 			kind = spec.kind;
+			if (spec.kind === "xev") {
+				console.warn(
+					"[cursor-x11] using xev -root; clicks inside a window that selects ButtonPressMask are not reported to the root and will be missed",
+				);
+			}
 			let failed = false;
-			spawned.once("error", (error) => {
+			const failOver = (reason: unknown) => {
 				if (cancelled || failed) {
 					return;
 				}
 				failed = true;
-				console.warn(`[cursor-x11] ${spec.command} could not start:`, error);
+				console.warn(`[cursor-x11] ${spec.command} stopped:`, reason);
+				child = null;
 				tryNext(index + 1);
+			};
+			spawned.once("error", (error) => {
+				failOver(error);
+			});
+			spawned.once("exit", (code, signal) => {
+				failOver(`exited (code=${code ?? "null"}, signal=${signal ?? "null"})`);
 			});
 			spawned.stdout?.setEncoding("utf8");
 			spawned.stdout?.on("data", (chunk: string) => handleChunk(chunk));
@@ -221,9 +233,11 @@ export class X11PointerRecordingSession implements CursorRecordingSession {
 
 let xdotoolCache: { x: number; y: number } | null = null;
 let xdotoolInflight = false;
+let xdotoolUnavailableUntilMs = 0;
+const XDOTOOL_FAILURE_COOLDOWN_MS = 5_000;
 
-export function refreshXdotoolLocationCache(): void {
-	if (xdotoolInflight) {
+export function refreshXdotoolLocationCache(nowMs: number = Date.now()): void {
+	if (xdotoolInflight || nowMs < xdotoolUnavailableUntilMs) {
 		return;
 	}
 	xdotoolInflight = true;
@@ -232,9 +246,11 @@ export function refreshXdotoolLocationCache(): void {
 	})
 		.then(({ stdout }) => {
 			xdotoolCache = parseXdotoolLocation(stdout);
+			xdotoolUnavailableUntilMs = 0;
 		})
 		.catch(() => {
 			xdotoolCache = null;
+			xdotoolUnavailableUntilMs = nowMs + XDOTOOL_FAILURE_COOLDOWN_MS;
 		})
 		.finally(() => {
 			xdotoolInflight = false;
@@ -245,4 +261,5 @@ export function refreshXdotoolLocationCache(): void {
 export function resetXdotoolLocationCacheForTests(): void {
 	xdotoolCache = null;
 	xdotoolInflight = false;
+	xdotoolUnavailableUntilMs = 0;
 }
diff --git a/src/hooks/useScreenRecorder.ts b/src/hooks/useScreenRecorder.ts
index 449a462fb9..db57471bf8 100644
--- a/src/hooks/useScreenRecorder.ts
+++ b/src/hooks/useScreenRecorder.ts
@@ -100,14 +100,14 @@ function telemetryCursorMode(platform: string, requested: CursorCaptureMode): Cu
 	return effectiveBrowserCursorMode(platform, requested);
 }
 
-async function pickFirstScreenSource(): Promise<boolean> {
+async function pickFirstScreenSource(): Promise<ProcessedDesktopSource | null> {
 	const api = window.electronAPI;
 	if (!api?.getSources || !api.selectSource) {
-		return false;
+		return null;
 	}
 	const existing = await api.getSelectedSource();
 	if (existing) {
-		return true;
+		return existing;
 	}
 	const sources = await api.getSources({
 		types: ["screen"],
@@ -115,10 +115,9 @@ async function pickFirstScreenSource(): Promise<boolean> {
 	});
 	const screen = sources.find((source) => source.id.startsWith("screen:")) ?? sources[0];
 	if (!screen) {
-		return false;
+		return null;
 	}
-	const selected = await api.selectSource(screen, { persist: false });
-	return Boolean(selected);
+	return (await api.selectSource(screen, { persist: false })) ?? null;
 }
 
 const AUDIO_BITRATE_VOICE = 128_000;
@@ -384,6 +383,13 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	const nativeWindowsRecording = useRef<NativeWindowsRecordingHandle | null>(null);
 	const nativeMacRecording = useRef<NativeMacRecordingHandle | null>(null);
 	const nativeLinuxRecording = useRef<NativeLinuxRecordingHandle | null>(null);
+	/**
+	 * Source chosen for Chromium capture after native Linux start failed with
+	 * `fallbackToBrowser`. `get-selected-source` returns null on Linux while the
+	 * helper binary is installed (the portal owns the pick), so the browser
+	 * path must not re-read it.
+	 */
+	const linuxBrowserFallbackSource = useRef<ProcessedDesktopSource | null>(null);
 	const stream = useRef<MediaStream | null>(null);
 	const screenStream = useRef<MediaStream | null>(null);
 	const microphoneStream = useRef<MediaStream | null>(null);
@@ -1656,7 +1662,11 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 						}
 						await nativeWebcamRecorder.discard();
 					}
-					await pickFirstScreenSource();
+					const picked = await pickFirstScreenSource();
+					if (!picked) {
+						throw new Error(result.error ?? "Native Linux capture failed.");
+					}
+					linuxBrowserFallbackSource.current = picked;
 					return false;
 				}
 				throw new Error(result.error ?? "Native Linux capture failed.");
@@ -1893,6 +1903,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 			// question this platform never asks the app. It returns false when the
 			// native helper is missing, and the browser fallback below does need a
 			// source, so the gate still guards the path that uses one.
+			linuxBrowserFallbackSource.current = null;
 			if (
 				await startNativeLinuxRecordingIfAvailable(
 					recordMicrophone,
@@ -1903,7 +1914,8 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 				return;
 			}
 
-			const selectedSource = await window.electronAPI.getSelectedSource();
+			const selectedSource =
+				linuxBrowserFallbackSource.current ?? (await window.electronAPI.getSelectedSource());
 			if (!selectedSource) {
 				alert(t("recording.selectSource"));
 				return;
diff --git a/technical-documentation/architecture/recording.md b/technical-documentation/architecture/recording.md
index 1ce84f7bea..ab7c95bf5b 100644
--- a/technical-documentation/architecture/recording.md
+++ b/technical-documentation/architecture/recording.md
@@ -78,7 +78,7 @@ The macOS helper mixes the same two sources into one AAC track (`AudioTrackMixer
 
 The Linux helper mixes the same two sources into one AAC track as well (`AudioMix` in `electron/native/pipewire-capture/src/capture.rs`), and its emit cursor is the data-driven one Windows had: `AudioEncoder::next_pts` is a running count of the samples handed to the encoder, advanced only when a block is encoded, and `AudioMix::pump` returns early when no input has any. Nothing in that code makes a chunk go out for every chunk of real time — what does is the tap. System audio here is the default sink's MONITOR, and PipeWire keeps delivering its buffers whether or not anything is playing, silence included, where WASAPI loopback simply stops. So the count advances at real time for as long as the take runs and the cursor cannot stall. That is a property of the capture source and not of the timeline code, which is the thing to know before moving Linux audio off the sink monitor: a source that gates silence would reproduce the Windows failure above exactly (#406). The anchor half is a decision rather than an accident — the first video frame sets the epoch and clears the audio rings at that instant ("video frame 0 is now, so audio sample 0 is now too"), which is what keeps the pre-roll captured while the portal picker was up, an interval with no upper bound, from shifting the whole track earlier; `cargo test` covers it. The tail is covered by `Capture::finish`, which drains the rings and flushes the AAC encoder before the video flush, so the file ends with the take rather than with the last sound in it. What a mid-take overflow costs is bounded the same way: the ring drops its oldest samples and owes back silence of exactly that length, so the encoder falling two seconds behind leaves a gap where it happened instead of pulling every later sound earlier for the rest of the recording, and it is reported as `audio-dropped`. `npm run test:pw-audio-timeline:linux` measures it end to end — a tone played at a known instant, then the audio track's length against the video track's in the same file. Before it, the whole record that any of this held was one sentence in a commit message: a live 29-second capture whose 18-second tone came back as 18 seconds of steady signal, with the two streams ending 62 ms apart (video 29.100 s, audio 29.162 s). That 62 ms is also why the script allows 250 ms between the tracks where the macOS one allows 100: those two come out of a single writer session, and these two do not — the video track ends at the last `advance()` and the audio track at everything the rings still held, plus AAC's final padded block.
 
-Cursor samples are persisted as cursor telemetry rather than baked into editable-overlay recordings. The loader resolves the sidecar at `<videoPath>.cursor.json` or through the recording links; see [cursor.md](cursor.md) for the telemetry format and rendering path. On Linux X11, when the portal cannot supply METADATA cursor samples, the same sidecar is filled by the X11 pointer sampler during the take so `--auto-zoom` has clicks to work from.
+Cursor samples are persisted as cursor telemetry rather than baked into editable-overlay recordings. The loader resolves the sidecar at `<videoPath>.cursor.json` or through the recording links; see [cursor.md](cursor.md) for the telemetry format and rendering path. On Linux X11, when the portal cannot supply METADATA cursor samples and the take uses editable-overlay, the same sidecar is filled by the X11 pointer sampler during the take so `--auto-zoom` has clicks to work from. A system-cursor take does not start that sampler.
 
 ## Known gaps
 
diff --git a/website/docs/cli.md b/website/docs/cli.md
index 0dcf86bbec..1535db424f 100644
--- a/website/docs/cli.md
+++ b/website/docs/cli.md
@@ -80,7 +80,7 @@ With `--camera`, the webcam is recorded beside the screen, and the `--project` f
 
 - **macOS.** Capture goes through the ScreenCaptureKit helper, with no fallback. The Screen Recording permission is required; for a development build started from a terminal, grant it to the terminal. With `--mic`, the CLI asks for microphone access if it has not been granted. Pointer clicks and shapes are only recorded with the Accessibility permission.
 - **Windows.** Capture goes through the Windows Graphics Capture helper, from Windows 10 build 19041. On older builds, or without the helper, OpenScreen falls back to browser capture. Windows never delivers SIGTERM: use Ctrl+C, stdin `stop`, or `--duration`.
-- **Linux.** Capture goes through the PipeWire helper and the desktop's ScreenCast portal. The portal's own picker decides what is recorded, and it opens on every run and waits for an answer, so `--display` and `--window` do not choose the source and a Linux recording cannot start unattended. It needs a desktop session with `xdg-desktop-portal`: an SSH session without a display cannot record. Only a build without the helper falls back to Chromium's capture. On **X11** hosts (including Xvfb cloud agents) the portal often advertises no METADATA cursor mode; OpenScreen then samples the pointer itself and still writes `<video>.cursor.json`, so `--auto-zoom` needs no extra step. `OPENSCREEN_DISABLE_X11_CURSOR=1` turns that sampler off.
+- **Linux.** Capture goes through the PipeWire helper and the desktop's ScreenCast portal. The portal's own picker decides what is recorded, and it opens on every run and waits for an answer, so `--display` and `--window` do not choose the source and a Linux recording cannot start unattended. It needs a desktop session with `xdg-desktop-portal`: an SSH session without a display cannot record. Only a build without the helper falls back to Chromium's capture. On **X11** hosts (including Xvfb cloud agents) the portal often advertises no METADATA cursor mode; with the default `--cursor editable-overlay`, OpenScreen then samples the pointer itself and still writes `<video>.cursor.json`, so `--auto-zoom` needs no extra step. `--cursor system` does not start that sampler. `OPENSCREEN_DISABLE_X11_CURSOR=1` turns the sampler off.
 
 ### `openscreen sources`
 
@@ -195,7 +195,7 @@ openscreen export project.openscreen --auto-zoom -o polished.mp4
 | `--click-hold-ms <ms>` | Synthesized `mouseup` this long after each click (default 60) |
 | `--json` | Machine-readable result on stdout |
 
-Each sample is `{ timeMs, cx, cy, visible, interactionType }`, with `interactionType` one of `move`, `click`, or `mouseup`. `cx` / `cy` are 0–1 fractions of the capture. That is the same schema `record` writes and that `--auto-zoom` reads.
+Each sample is `{ timeMs, cx, cy, visible, interactionType }`. `cursor import` writes `interactionType` as `move`, `click`, or `mouseup`. `openscreen record` on X11 also writes `right-click` and `middle-click` from the pointer sampler. `cx` / `cy` are 0–1 fractions of the capture. `--auto-zoom` reads the click samples.
 
 ### `openscreen mcp`
 
diff --git a/website/docs/recording.md b/website/docs/recording.md
index 2a4a71ef9a..43c609b85a 100644
--- a/website/docs/recording.md
+++ b/website/docs/recording.md
@@ -50,7 +50,7 @@ On Windows, macOS, and Linux, a cursor-mode toggle switches between:
 What the editable overlay captures depends on the platform:
 - **Windows** — the real cursor shape and clicks.
 - **macOS** — the cursor shape and clicks, which need the Accessibility permission. In this mode, pressing record without it opens the permissions window instead of starting (see [macOS installation](./installation.md#macos)).
-- **Linux** — position and shape through the ScreenCast portal, plus left clicks when your user can read the mouse, through a udev rule (recommended) or the `input` group (see [Mouse clicks on Wayland](./installation.md#mouse-clicks-on-wayland)). On **X11** (including Xvfb), if the portal has no METADATA cursor mode, OpenScreen samples the pointer itself and still writes `<video>.cursor.json`, so auto-zoom and the editable overlay have data. Browser-fallback takes may also bake the OS cursor into the pixels; a take recorded with `ffmpeg -draw_mouse 0` plus [`openscreen cursor import`](./cli.md#openscreen-cursor-import) does not.
+- **Linux** — position and shape through the ScreenCast portal, plus left clicks when your user can read the mouse, through a udev rule (recommended) or the `input` group (see [Mouse clicks on Wayland](./installation.md#mouse-clicks-on-wayland)). On **X11** (including Xvfb), if the portal has no METADATA cursor mode and the take uses the default editable overlay, OpenScreen samples the pointer itself and still writes `<video>.cursor.json`, so auto-zoom and the editable overlay have data. A system-cursor take does not start that sampler. Browser-fallback takes may also bake the OS cursor into the pixels; a take recorded with `ffmpeg -draw_mouse 0` plus [`openscreen cursor import`](./cli.md#openscreen-cursor-import) does not.
 
 A Linux take that falls back to [browser capture](#native-vs-browser-capture) records the system cursor, whichever mode you picked.