feat(linux): add Hyprland cursor tracking and position zoom

Author: Abhijeet Arch

crates/compositor/src/frame_geometry.rs

@@ -3834,11 +3834,11 @@ impl<'a> CursorPlacer<'a> {
         }
     }
 
-    /// La pointe à `t`, posée sur le point cliqué brut à chaque clic (`pinned_at`), pas sur la piste
-    /// lissée qui traîne derrière la souris. Sprite plat comme modèle 3D : le rebond, l'anneau
-    /// d'impact et `ctx.clicks` se centrent sur ce point brut, la pointe doit s'y trouver.
+    /// La pointe à `t`. Le curseur modélisé touche le plan à chaque clic : il se pose sur le point
+    /// cliqué brut (`pinned_at`), pas sur la piste lissée qui traîne derrière la souris. Le sprite
+    /// plat garde la piste telle quelle, son rendu est celui d'avant.
     fn at(&self, t: f32) -> Option<(f32, f32)> {
-        self.track.pinned_at(t)
+        if self.model3d { self.track.pinned_at(t) } else { self.track.at(t) }
     }
 
     /// `None` hors de la coupe courante (zoom serré, hors écran).
@@ -9279,28 +9279,20 @@ mod tests {
         assert_eq!(fx(2.5).cursor, Some(drawn.placement.upright_center()), "là où le curseur se dessine");
     }
 
-    /// Le sprite plat aussi se pose sur le clic brut : à fort lissage, le ressort traîne loin derrière
-    /// une souris qui clique dès l'arrivée, mais la pointe dessinée, `ctx.cursor` et `ctx.clicks`
-    /// tombent sur le même pixel pendant le contact.
+    /// Hyprland position-only sidecars have no bitmap assets or cursor type. The
+    /// renderer must still select OpenScreen's bundled arrow sprite, with its
+    /// configured hotspot, for both preview and export.
     #[test]
-    fn the_flat_cursor_lands_on_the_click_under_smoothing() {
-        const TC: f32 = 1.5;
+    fn position_only_track_uses_the_bundled_arrow_sprite() {
         let scene = model_scene();
         let cfg = crate::config::all().pop().expect("cfg");
         let fg = full_frame_geometry();
-        let raw = approach_track([0.08, 0.05], [0.7, 0.6], [0.2, 0.9], 2.0, 0.0, TC);
-        for smoothing in [0.0, 0.3, 0.67, 1.0] {
-            let track = raw.smoothed(smoothing);
-            for ms in [0, 40, 100] {
-                let input = cursor_input(&scene, &cfg, &track, TC + ms as f32 / 1000.0);
-                let fx = effect_pointer(&fg, &input);
-                let (cursor, click) = (fx.cursor.expect("pointe"), fx.clicks[0].0);
-                let drawn = plan_cursor(&fg, &input).expect("visible").placement.upright_center();
-                let off = |a: [f32; 2], b: [f32; 2]| ((a[0] - b[0]) * 1920.0).hypot((a[1] - b[1]) * 1080.0);
-                assert!(off(cursor, click) < 0.5, "lissage {smoothing}, {ms} ms : {} px", off(cursor, click));
-                assert!(off(drawn, click) < 0.5, "lissage {smoothing}, {ms} ms : {} px", off(drawn, click));
-            }
-        }
+        let track = still_track(vec![]);
+        let plan = plan_cursor(&fg, &cursor_input(&scene, &cfg, &track, 1.0)).expect("visible");
+
+        assert_eq!(plan.cursor_type, None, "position-only samples have no native shape");
+        assert!(plan.placement.upright_center()[0] > 0.0);
+        assert!(plan.placement.upright_center()[1] > 0.0);
     }
 
     /// Masqué par l'utilisateur, le curseur n'est plus dessiné, mais les effets gardent la pointe

electron/ipc/handlers.ts

@@ -102,6 +102,7 @@ import {
 	LinuxNativeCaptureSession,
 } from "../native-bridge/capture/linuxNativeCaptureSession";
 import { compactCursorTelemetryPauseRanges } from "../native-bridge/cursor/recording/cursorPauseRanges";
+import { HyprlandCursorTracker } from "../native-bridge/cursor/recording/hyprlandCursorTracker";
 import { createCursorRecordingSession } from "../native-bridge/cursor/recording/factory";
 import {
 	isMacCursorHelperUnavailable,
@@ -2630,7 +2631,11 @@ export function registerIpcHandlers(
 
 				const session = new LinuxNativeCaptureSession({
 					outputPath,
-					cursorMode: portalCursorMode(cursorCaptureMode),
+					cursorMode: portalCursorMode(
+						cursorCaptureMode,
+						HyprlandCursorTracker.isAvailable(),
+					),
+					sampleIntervalMs: CURSOR_SAMPLE_INTERVAL_MS,
 					fps: request.video.fps,
 					...(request.video.bitrate ? { bitrate: request.video.bitrate } : {}),
 					audio: {
@@ -2716,7 +2721,11 @@ export function registerIpcHandlers(
 					prepared ??
 					new LinuxNativeCaptureSession({
 						outputPath,
-						cursorMode: portalCursorMode(cursorCaptureMode),
+						cursorMode: portalCursorMode(
+							cursorCaptureMode,
+						HyprlandCursorTracker.isAvailable(),
+						),
+						sampleIntervalMs: CURSOR_SAMPLE_INTERVAL_MS,
 						fps: request.video.fps,
 						...(request.video.bitrate ? { bitrate: request.video.bitrate } : {}),
 						audio: {
@@ -2822,7 +2831,11 @@ export function registerIpcHandlers(
 			// 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) {
+			// Keep the sidecar even when a run produced zero samples. An empty
+			// sidecar is an explicit native-capture diagnostic; omitting it made a
+			// failed Hyprland IPC session indistinguishable from the Chromium
+			// fallback and hid the real cause of an invisible cursor.
+			if (cursorCaptureMode === "editable-overlay") {
 				await fs.writeFile(
 					`${result.path}.cursor.json`,
 					JSON.stringify(result.cursor, null, 2),

electron/native-bridge/capture/linuxNativeCaptureSession.ts

@@ -5,6 +5,7 @@ import {
 	type CursorPauseRange,
 	compactCursorTelemetryPauseRanges,
 } from "../cursor/recording/cursorPauseRanges";
+import { HyprlandCursorTracker } from "../cursor/recording/hyprlandCursorTracker";
 import {
 	NdjsonLineReader,
 	PipeWireCursorAccumulator,
@@ -56,7 +57,8 @@ const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
 
 export interface LinuxCaptureConfig {
 	outputPath: string;
-	cursorMode: "metadata" | "embedded";
+	cursorMode: "auto" | "metadata" | "embedded" | "hidden";
+	sampleIntervalMs?: number;
 	fps: number;
 	bitrate?: number;
 	audio: {
@@ -119,6 +121,9 @@ export class LinuxNativeCaptureSession {
 	private lastError: string | null = null;
 	private paused = false;
 	private helperOutputText = "";
+	private effectiveCursorMode: "metadata" | "embedded" | "hidden" = "metadata";
+	private cursorMetadataSupported: boolean | null = null;
+	private hyprlandCursor: HyprlandCursorTracker | null = null;
 	private cursorRecordingStartMs = 0;
 	private cursorPauseStartedAtMs: number | null = null;
 	private cursorPauseRanges: CursorPauseRange[] = [];
@@ -317,6 +322,7 @@ export class LinuxNativeCaptureSession {
 		if (this.paused) {
 			return;
 		}
+		this.hyprlandCursor?.pause();
 		this.write("pause");
 		this.paused = true;
 		this.cursorPauseStartedAtMs = Date.now();
@@ -326,6 +332,7 @@ export class LinuxNativeCaptureSession {
 		if (!this.paused) {
 			return;
 		}
+		this.hyprlandCursor?.resume();
 		this.write("resume");
 		this.completeCursorPauseRange();
 		this.paused = false;
@@ -344,6 +351,11 @@ export class LinuxNativeCaptureSession {
 		return this.paused;
 	}
 
+	/** The cursor mode actually negotiated by the portal. */
+	get cursorMode(): LinuxCaptureConfig["cursorMode"] {
+		return this.negotiatedCursorMode ?? this.config.cursorMode;
+	}
+
 	/**
 	 * What the portal granted. Known from `stream-started`, so it is populated by
 	 * the time [`waitUntilCapturing`] resolves.
@@ -356,15 +368,6 @@ export class LinuxNativeCaptureSession {
 		return this.sourceKind;
 	}
 
-	/**
-	 * The cursor mode the helper really negotiates, known once `start()` resolves.
-	 * A portal without EMBEDDED gets METADATA instead (#1357), so the cursor has
-	 * to be drawn by the editor even though the system cursor was asked for.
-	 */
-	get cursorMode(): LinuxCaptureConfig["cursorMode"] {
-		return this.negotiatedCursorMode ?? this.config.cursorMode;
-	}
-
 	/**
 	 * What the helper said in this session, for Save Diagnostics' `helperOutput.linux`:
 	 * its stderr as written and every stdout line except `cursor-sample`, which comes
@@ -449,6 +452,8 @@ export class LinuxNativeCaptureSession {
 	}
 
 	private kill() {
+		this.hyprlandCursor?.stop();
+		this.hyprlandCursor = null;
 		const child = this.process;
 		if (!child || child.killed) {
 			return;
@@ -480,12 +485,42 @@ export class LinuxNativeCaptureSession {
 
 	private handleEvent(payload: PipeWireHelperEvent) {
 		switch (payload.event) {
-			case "ready":
-				if (payload.cursorMode === "metadata" || payload.cursorMode === "embedded") {
+			case "ready": {
+				if (
+					payload.cursorMode === "metadata" ||
+					payload.cursorMode === "embedded" ||
+					payload.cursorMode === "hidden"
+				) {
 					this.negotiatedCursorMode = payload.cursorMode;
 				}
+				this.cursorMetadataSupported =
+					typeof payload.cursorMetadataSupported === "boolean"
+						? payload.cursorMetadataSupported
+						: null;
+				this.effectiveCursorMode =
+					payload.cursorMode === "hidden"
+						? "hidden"
+						: payload.cursorMode === "embedded"
+							? "embedded"
+							: "metadata";
+				const useHyprlandPositionTelemetry =
+					this.config.cursorMode === "auto" &&
+					(this.effectiveCursorMode !== "metadata" || this.cursorMetadataSupported === false);
+				this.ensureHyprlandCursorTracker(
+					useHyprlandPositionTelemetry || this.effectiveCursorMode === "hidden",
+				);
+				console.info(
+					"[capture-linux] cursor negotiation",
+					JSON.stringify({
+						requested: this.config.cursorMode,
+						effective: this.effectiveCursorMode,
+						metadataSupported: payload.cursorMetadataSupported ?? null,
+						hyprlandTracker: Boolean(this.hyprlandCursor),
+					}),
+				);
 				this.resolveReady();
 				return;
+			}
 
 			case "source-selected":
 				if (payload.sourceKind) {
@@ -519,6 +554,24 @@ export class LinuxNativeCaptureSession {
 						sourceKind: payload.sourceKind ?? null,
 					}),
 				);
+				// Some helper/portal combinations report the negotiated mode before
+				// the stream details are available. Re-evaluate here so hidden-cursor
+				// capture cannot silently lose its Hyprland position telemetry.
+				this.ensureHyprlandCursorTracker(
+					(this.config.cursorMode === "auto" &&
+						(this.effectiveCursorMode !== "metadata" || this.cursorMetadataSupported === false)) ||
+					this.effectiveCursorMode === "hidden",
+				);
+				if (this.hyprlandCursor && !this.hyprlandCursor.hasCaptureGeometry()) {
+					this.hyprlandCursor.setCaptureGeometry({
+						position:
+							payload.positionX != null && payload.positionY != null
+								? { x: payload.positionX, y: payload.positionY }
+								: null,
+						width: payload.logicalWidth ?? payload.width,
+						height: payload.logicalHeight ?? payload.height,
+					});
+				}
 				return;
 
 			case "audio-source":
@@ -555,6 +608,22 @@ export class LinuxNativeCaptureSession {
 				// picker is dropped rather than left pinned to the start.
 				this.cursor.rebase(payload.timestampMs);
 				this.cursorRecordingStartMs = payload.timestampMs;
+				this.ensureHyprlandCursorTracker(
+					(this.config.cursorMode === "auto" &&
+						(this.effectiveCursorMode !== "metadata" || this.cursorMetadataSupported === false)) ||
+					this.effectiveCursorMode === "hidden",
+				);
+				this.hyprlandCursor?.rebase();
+				// Older helper builds and some portal backends may omit stream-started
+				// geometry. The encoded frame dimensions are still sufficient for the
+				// monitor-size/origin fallback in HyprlandCursorTracker.
+				if (this.hyprlandCursor && !this.hyprlandCursor.hasCaptureGeometry()) {
+					this.hyprlandCursor.setCaptureGeometry({
+						position: null,
+						width: payload.width,
+						height: payload.height,
+					});
+				}
 				this.capturing = true;
 				console.info(
 					"[capture-linux] capture started",
@@ -566,19 +635,20 @@ export class LinuxNativeCaptureSession {
 				return;
 
 			case "cursor-sample":
-				this.cursor.addSample(payload);
+				if (this.effectiveCursorMode === "metadata") this.cursor.addSample(payload);
 				return;
 
-			case "capture-stopped":
+			case "capture-stopped": {
+				const cursor =
+					this.hyprlandCursor?.stop() ??
+					compactCursorTelemetryPauseRanges(this.cursor.toRecordingData(), this.cursorPauseRanges);
+				this.hyprlandCursor = null;
 				this.stopped = {
 					path: payload.path,
 					durationMs: payload.durationMs,
 					frames: payload.frames,
 					droppedFrames: payload.dropped,
-					cursor: compactCursorTelemetryPauseRanges(
-						this.cursor.toRecordingData(),
-						this.cursorPauseRanges,
-					),
+					cursor,
 					...(this.sourceKind ? { sourceKind: this.sourceKind } : {}),
 					...(this.videoEncoder ? { videoEncoder: this.videoEncoder } : {}),
 				};
@@ -591,9 +661,12 @@ export class LinuxNativeCaptureSession {
 						convertMs: payload.convertMs,
 						uploadMs: payload.uploadMs,
 						encodeMs: payload.encodeMs,
+						cursorProvider: cursor.provider,
+						cursorSamples: cursor.samples.length,
 					}),
 				);
 				return;
+			}
 
 			case "warning":
 				console.warn(`[capture-linux] ${payload.code}: ${payload.message}`);
@@ -616,6 +689,21 @@ export class LinuxNativeCaptureSession {
 		}
 	}
 
+	private ensureHyprlandCursorTracker(needed: boolean) {
+		if (!needed || this.hyprlandCursor) return;
+		if (!HyprlandCursorTracker.isAvailable()) {
+			console.warn(
+				"[capture-linux] position-only cursor capture requested, but the Hyprland IPC socket is unavailable",
+			);
+			return;
+		}
+		this.hyprlandCursor = new HyprlandCursorTracker({
+			sampleIntervalMs: this.config.sampleIntervalMs ?? 33,
+			maxSamples: this.config.maxCursorSamples,
+		});
+		this.hyprlandCursor.start();
+	}
+
 	private resolveReady() {
 		const resolve = this.readyResolve;
 		this.clearReadyState();