From 572dd2f37cce2f4244e7246601d3d4bf7701904c Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:00:25 -0700
Subject: [PATCH 01/27] perf(linux): read write-combined dmabufs with streaming
 loads

xdg-desktop-portal-hyprland hands out LINEAR dmabufs, which the helper
maps and copies on the PipeWire thread. The driver maps them
write-combined, so ordinary reads are uncached: on an Intel Arc B390 a
3840x2160 frame took ~100 ms through extend_from_slice (0.33 GB/s).
While the copy ran the compositor ran out of buffers, rebuilt the stream
several times a second ("Out of buffers" in the portal log) and the
recording stuttered at 15-35 fps.

Copy with SSE4.1 streaming loads (MOVNTDQA) instead: ~3.3 ms per 4K
frame (10 GB/s). On ordinary write-back memory a streaming load is a
plain load, so shm and memfd buffers take the same path. CPUs without
SSE4.1 and non-x86 builds keep extend_from_slice.
---
 electron/native/pipewire-capture/src/shim.rs | 76 +++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/electron/native/pipewire-capture/src/shim.rs b/electron/native/pipewire-capture/src/shim.rs
index d85ad084ae..fd09e84cb4 100644
--- a/electron/native/pipewire-capture/src/shim.rs
+++ b/electron/native/pipewire-capture/src/shim.rs
@@ -348,6 +348,64 @@ struct Mailbox {
     spare: Option<Vec<u8>>,
 }
 
+/// Appends `source` to `dest`, reading it with streaming loads where the CPU
+/// has them.
+///
+/// `source` is often a CPU mapping of a LINEAR dmabuf, which the driver maps
+/// write-combined: writes are fast, ordinary reads are uncached and crawl.
+/// Measured on an Intel Arc B390 (xdg-desktop-portal-hyprland hands out exactly
+/// these buffers), a 3840x2160 frame took ~100 ms through `extend_from_slice`
+/// (0.33 GB/s) and ~3.3 ms through MOVNTDQA (10 GB/s). This copy runs on the
+/// PipeWire thread, so at 100 ms the compositor ran out of buffers, rebuilt the
+/// stream several times a second and the recording stuttered at 15-35 fps.
+///
+/// On ordinary write-back memory (shm, memfd) a streaming load is a plain load,
+/// so the same path serves every buffer type.
+fn copy_from_mapping(dest: &mut Vec<u8>, source: &[u8]) {
+    #[cfg(target_arch = "x86_64")]
+    if std::arch::is_x86_feature_detected!("sse4.1") {
+        dest.reserve(source.len());
+        let start = dest.len();
+        // SAFETY: `reserve` made room for `source.len()` bytes past `start`, the
+        // copy initialises all of them, and the two regions cannot overlap
+        // (`dest` is our own heap allocation, `source` the compositor's mapping).
+        unsafe {
+            stream_copy_sse41(dest.as_mut_ptr().add(start), source);
+            dest.set_len(start + source.len());
+        }
+        return;
+    }
+    dest.extend_from_slice(source);
+}
+
+/// MOVNTDQA needs a 16-byte-aligned source, so the head up to the first
+/// boundary and the tail past the last 64-byte block go through a plain copy.
+#[cfg(target_arch = "x86_64")]
+#[target_feature(enable = "sse4.1")]
+unsafe fn stream_copy_sse41(dest: *mut u8, source: &[u8]) {
+    use std::arch::x86_64::{__m128i, _mm_storeu_si128, _mm_stream_load_si128};
+
+    let len = source.len();
+    let base = source.as_ptr();
+    let head = base.align_offset(16).min(len);
+    std::ptr::copy_nonoverlapping(base, dest, head);
+    let mut offset = head;
+    while offset + 64 <= len {
+        let from = base.add(offset) as *const __m128i;
+        let a = _mm_stream_load_si128(from);
+        let b = _mm_stream_load_si128(from.add(1));
+        let c = _mm_stream_load_si128(from.add(2));
+        let d = _mm_stream_load_si128(from.add(3));
+        let to = dest.add(offset) as *mut __m128i;
+        _mm_storeu_si128(to, a);
+        _mm_storeu_si128(to.add(1), b);
+        _mm_storeu_si128(to.add(2), c);
+        _mm_storeu_si128(to.add(3), d);
+        offset += 64;
+    }
+    std::ptr::copy_nonoverlapping(base.add(offset), dest.add(offset), len - offset);
+}
+
 impl FrameMailbox {
     /// Copies `pixels` into the slot, replacing whatever was there.
     ///
@@ -373,7 +431,7 @@ impl FrameMailbox {
             None => inner.spare.take().unwrap_or_default(),
         };
         pixels.clear();
-        pixels.extend_from_slice(source);
+        copy_from_mapping(&mut pixels, source);
 
         inner.pending = Some(Frame {
             pixels,
@@ -1321,6 +1379,22 @@ mod tests {
     use std::sync::mpsc;
     use std::time::Duration;
 
+    /// Every head misalignment and tail length the streaming copy splits on must
+    /// come out byte-identical, appended after whatever `dest` already held.
+    #[test]
+    fn copy_from_mapping_is_byte_exact_at_any_alignment_and_length() {
+        let source: Vec<u8> = (0..1024u32).map(|i| (i * 7 + 3) as u8).collect();
+        for skew in 0..16 {
+            for len in [0, 1, 15, 16, 63, 64, 65, 127, 128, 200, 1000 - skew] {
+                let slice = &source[skew..skew + len];
+                let mut dest = vec![0xAA, 0xBB];
+                copy_from_mapping(&mut dest, slice);
+                assert_eq!(&dest[..2], &[0xAA, 0xBB], "skew {skew} len {len}");
+                assert_eq!(&dest[2..], slice, "skew {skew} len {len}");
+            }
+        }
+    }
+
     /// The bound that made Stage 1 produce nothing on the first real run.
     ///
     /// Compositors declare SPA_PARAM_META_size for the cursor as a FIXED

From 407da2d2f533e00b50537a50812c6be81114a2e6 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:00:46 -0700
Subject: [PATCH 02/27] fix(linux): stamp frames by arrival slot, not encode
 time

Capture::advance stamped a fresh frame with current_index(), the clock at
the moment it was encoded. At 4K the ~13 ms of conversion and upload
before that put about half of a steady 60 Hz stream one slot late; the
next frame then found its slot taken and skipped one, so smooth motion
was recorded with 33 ms gaps even though the compositor delivered every
frame on time.

Each frame now carries the instant the PipeWire thread handed it up, and
a fresh frame is written in the slot it arrived in (or the first free
one after it). The held picture a heartbeat re-encodes is stamped two
slots behind the clock, so it can no longer claim the slot a frame
arriving right now belongs in; finish() still stamps the true end.
---
 .../native/pipewire-capture/src/capture.rs    | 86 ++++++++++++++++++-
 electron/native/pipewire-capture/src/main.rs  |  1 +
 electron/native/pipewire-capture/src/shim.rs  |  8 +-
 3 files changed, 91 insertions(+), 4 deletions(-)

diff --git a/electron/native/pipewire-capture/src/capture.rs b/electron/native/pipewire-capture/src/capture.rs
index 8eb8b7b01a..602a7338df 100644
--- a/electron/native/pipewire-capture/src/capture.rs
+++ b/electron/native/pipewire-capture/src/capture.rs
@@ -172,6 +172,11 @@ pub struct Selection {
 /// At 1920×1080/60 it comes to about 12 Mbit/s.
 const BITS_PER_PIXEL: f64 = 0.1;
 
+/// How far behind the clock a heartbeat re-stamps the held picture. Two slots
+/// cover one frame waiting in the mailbox while the previous one converts, so a
+/// held frame never claims a slot a fresh one arrived in. See `advance`.
+const HELD_FRAME_LAG_SLOTS: i64 = 2;
+
 /// Picks a video bitrate from the size the compositor actually negotiated.
 ///
 /// THE CALLER CANNOT DO THIS. On Wayland the app does not know the capture
@@ -227,6 +232,12 @@ pub struct Capture {
     paused_at: Option<Instant>,
     /// The next output frame index to write.
     next_index: i64,
+    /// Arrival instant of the first staged frame: index 0 of the arrival clock
+    /// fresh frames are placed by. See `advance`.
+    first_arrival: Option<Instant>,
+    /// Arrival instant of the staged picture while it is still unwritten. `None`
+    /// once written, when what is staged is only the held picture.
+    staged_arrival: Option<Instant>,
     frames_written: u64,
     /// The size the encoder was opened at, latched for the whole file.
     ///
@@ -376,6 +387,8 @@ impl Capture {
                 paused_total: Duration::ZERO,
                 paused_at: None,
                 next_index: 0,
+                first_arrival: None,
+                staged_arrival: None,
                 frames_written: 0,
                 committed_width: width,
                 committed_height: height,
@@ -491,7 +504,7 @@ impl Capture {
             // SAFETY: `nv12` is a VAAPI NV12 frame from the pool the encoder was
             // opened against; the encoder takes ownership.
             unsafe { self.encoder.stage_hw(nv12) };
-            self.mark_started();
+            self.mark_staged(frame.arrived);
             return Ok(StageOutcome::Staged);
         }
 
@@ -512,7 +525,7 @@ impl Capture {
             .ok_or_else(|| format!("crop offset {offset} is past the end of the frame"))?;
 
         self.encoder.stage(pixels, frame.stride, format)?;
-        self.mark_started();
+        self.mark_staged(frame.arrived);
         Ok(StageOutcome::Staged)
     }
 
@@ -536,6 +549,12 @@ impl Capture {
         }
     }
 
+    fn mark_staged(&mut self, arrived: Instant) {
+        self.mark_started();
+        self.first_arrival.get_or_insert(arrived);
+        self.staged_arrival = Some(arrived);
+    }
+
     /// Whether a picture has been staged, which is also whether the timeline has
     /// started.
     pub fn started(&self) -> bool {
@@ -563,7 +582,20 @@ impl Capture {
         if self.paused_at.is_some() || !self.encoder.has_staged_frame() {
             return Ok(0);
         }
-        let target = self.current_index();
+        // A fresh picture goes in the slot it ARRIVED in, or the first free one
+        // after it. Stamping it from the clock at encode time put the ~13 ms of
+        // conversion and upload into the PTS: a 60 Hz stream at 4K landed half its
+        // frames one slot late, the next frame then skipped a slot, and the file
+        // showed 33 ms gaps in steady motion.
+        //
+        // The held picture is re-stamped HELD_FRAME_LAG_SLOTS behind the clock,
+        // so a heartbeat can never take the slot a frame that is arriving right
+        // now belongs in. Only the static-screen tail is affected, and `finish`
+        // stamps the true end.
+        let target = match self.staged_arrival {
+            Some(arrived) => self.arrival_index(arrived).max(self.next_index),
+            None => self.current_index() - HELD_FRAME_LAG_SLOTS,
+        };
         let Some(muxer) = self.muxer.as_mut() else {
             return Ok(0);
         };
@@ -574,6 +606,7 @@ impl Capture {
                 .encode_staged(target, |packet| muxer.write(track, packet))?;
             self.next_index = target + 1;
             self.frames_written += 1;
+            self.staged_arrival = None;
             written = 1;
         }
 
@@ -707,6 +740,20 @@ impl Capture {
 
     /// Output frame index the wall clock is currently on, excluding paused time.
     /// `-1` before the first frame is staged, so `advance` writes nothing.
+    /// The slot a frame that arrived at `arrived` belongs in, on the clock that
+    /// starts at the first frame's arrival. Paused time is taken off the same way
+    /// `elapsed_active` takes it off; a frame never arrives during a pause, since
+    /// `stage` freezes then.
+    fn arrival_index(&self, arrived: Instant) -> i64 {
+        let Some(first) = self.first_arrival else {
+            return 0;
+        };
+        let elapsed = arrived
+            .saturating_duration_since(first)
+            .saturating_sub(self.paused_total);
+        (elapsed.as_nanos() as i64 * self.fps as i64) / 1_000_000_000
+    }
+
     fn current_index(&self) -> i64 {
         match self.elapsed_active() {
             Some(elapsed) => (elapsed.as_nanos() as i64 * self.fps as i64) / 1_000_000_000,
@@ -780,6 +827,7 @@ mod tests {
             height,
             video_format: format,
             pts_ns: -1,
+            arrived: std::time::Instant::now(),
             crop: shim::CropRect { x: 0, y: 0, width, height },
             has_crop: false,
             dmabuf: None,
@@ -869,6 +917,38 @@ mod tests {
         let _ = std::fs::remove_file(&output);
     }
 
+    /// A frame processed late still lands in the slot it arrived in. Stamping by
+    /// the encode-time clock pushed 4K frames one slot late and left 33 ms gaps.
+    #[test]
+    fn a_fresh_frame_is_placed_by_arrival_not_by_when_it_was_encoded() {
+        let output = std::env::temp_dir().join("openscreen-capture-arrival.mp4");
+        let (mut capture, _) =
+            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
+                .expect("start");
+        let format = shim::constants().video_format_bgrx;
+        let first = Instant::now();
+        let mut frame_at = |arrived: Instant| {
+            let mut f = frame(320, 240, format);
+            f.arrived = arrived;
+            f
+        };
+
+        capture.stage(&frame_at(first)).expect("stage");
+        assert_eq!(capture.advance().expect("advance"), 1);
+        assert_eq!(capture.next_index, 1);
+
+        // Arrived 40 ms in (slot 1 at 30 fps) but encoded ~150 ms in (slot 4).
+        std::thread::sleep(Duration::from_millis(150));
+        capture.stage(&frame_at(first + Duration::from_millis(40))).expect("stage");
+        assert_eq!(capture.advance().expect("advance"), 1);
+        assert_eq!(capture.next_index, 2, "written at its arrival slot, not the clock's");
+
+        // The held picture is then re-stamped HELD_FRAME_LAG_SLOTS behind the clock.
+        assert_eq!(capture.advance().expect("advance"), 1);
+        assert_eq!(capture.next_index, capture.current_index() - HELD_FRAME_LAG_SLOTS + 1);
+        let _ = std::fs::remove_file(&output);
+    }
+
     /// The window-capture bug, at the layer where it produced wrong pixels.
     ///
     /// mutter hands a window stream MONITOR-sized buffers and reports the
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 685b64d606..fc4fe4b581 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -1791,6 +1791,7 @@ mod cursor_sample_tests {
                 height: 1080,
                 video_format: shim::constants().video_format_bgrx,
                 pts_ns: -1,
+                arrived: std::time::Instant::now(),
                 crop: shim::CropRect { x: 100, y: 50, width: 320, height: 240 },
                 has_crop: true,
                 dmabuf: None,
diff --git a/electron/native/pipewire-capture/src/shim.rs b/electron/native/pipewire-capture/src/shim.rs
index fd09e84cb4..0e1792b67b 100644
--- a/electron/native/pipewire-capture/src/shim.rs
+++ b/electron/native/pipewire-capture/src/shim.rs
@@ -231,7 +231,7 @@ pub struct CursorBitmap {
 }
 
 /// One captured frame, copied out of the PipeWire buffer.
-#[derive(Debug, Default)]
+#[derive(Debug)]
 pub struct Frame {
     pub pixels: Vec<u8>,
     pub stride: usize,
@@ -241,6 +241,10 @@ pub struct Frame {
     /// Compositor monotonic clock in nanoseconds, or -1 when the buffer carried
     /// no SPA_META_Header.
     pub pts_ns: i64,
+    /// When the PipeWire thread handed this frame up, before any conversion. The
+    /// encoder places the frame on the timeline by this instant rather than by
+    /// when the main loop got round to it (see `Capture::advance`).
+    pub arrived: std::time::Instant,
     /// The sub-rectangle of `pixels` holding content, from SPA_META_VideoCrop.
     /// Defaults to the whole frame, so it is always safe to read.
     pub crop: CropRect,
@@ -440,6 +444,7 @@ impl FrameMailbox {
             height: meta.height,
             video_format: meta.video_format,
             pts_ns: meta.pts_ns,
+            arrived: std::time::Instant::now(),
             crop: CropRect {
                 x: meta.crop_x,
                 y: meta.crop_y,
@@ -476,6 +481,7 @@ impl FrameMailbox {
             height: meta.height,
             video_format: meta.video_format,
             pts_ns: meta.pts_ns,
+            arrived: std::time::Instant::now(),
             crop: CropRect {
                 x: meta.crop_x,
                 y: meta.crop_y,

From 74c03cc43a3f705ba8c72672d733f76653277663 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:00:57 -0700
Subject: [PATCH 03/27] perf(linux): thread colour conversion via
 sws_scale_frame

The helper asked libswscale for threads but converted with sws_scale,
the pointer API, which runs single-threaded whatever the context's
`threads` says. That is why the measurement behind the old default of
one thread saw no difference between one and eight. Only
sws_scale_frame slices the work.

Convert through sws_scale_frame with a source frame that borrows the
captured pixels (no copy), and default to half the CPU's threads, at
most eight. 3840x2160 BGRx->NV12 drops from 7.6 ms/frame on one thread
to 4.0 ms on eight (Core Ultra X7 358H), which leaves a third of the
4K60 frame budget instead of almost none; the output is byte-identical.
OPENSCREEN_LINUX_SWS_THREADS still overrides the count.
---
 .../native/pipewire-capture/src/encoder.rs    | 71 ++++++++++++-------
 1 file changed, 44 insertions(+), 27 deletions(-)

diff --git a/electron/native/pipewire-capture/src/encoder.rs b/electron/native/pipewire-capture/src/encoder.rs
index 5f0a2fe49e..e745a785b9 100644
--- a/electron/native/pipewire-capture/src/encoder.rs
+++ b/electron/native/pipewire-capture/src/encoder.rs
@@ -258,6 +258,9 @@ pub struct VideoEncoder {
     upload_is_safe: bool,
     sws: *mut ff::SwsContext,
     sws_src_format: ff::AVPixelFormat,
+    /// A frame with no buffers of its own, re-pointed at each captured frame's
+    /// pixels so `sws_scale_frame` reads them in place. See [`Self::stage`].
+    sws_src: *mut ff::AVFrame,
     packet: *mut ff::AVPacket,
     params: VideoParams,
     stats: EncodeStats,
@@ -374,6 +377,7 @@ impl VideoEncoder {
                 upload_is_safe: true,
                 sws: ptr::null_mut(),
                 sws_src_format: ff::AV_PIX_FMT_NONE,
+                sws_src: ptr::null_mut(),
                 packet: ptr::null_mut(),
                 params: VideoParams {
                     width: params.width,
@@ -620,21 +624,30 @@ impl VideoEncoder {
                 ));
             }
 
-            let src_data = [pixels.as_ptr(), ptr::null(), ptr::null(), ptr::null()];
-            let src_stride = [stride as i32, 0, 0, 0];
+            // `sws_scale_frame`, not `sws_scale`: only the frame API slices the
+            // conversion across the context's `threads`. The pointer API runs on
+            // one thread whatever was asked for, which is why threading once
+            // measured as useless. The source frame only borrows `pixels` (no
+            // buffer refs), so nothing is copied and nothing is freed with it.
+            if self.sws_src.is_null() {
+                self.sws_src = ff::av_frame_alloc();
+                if self.sws_src.is_null() {
+                    return Err("av_frame_alloc returned null".to_owned());
+                }
+            }
+            let src = &mut *self.sws_src;
+            src.format = src_format as i32;
+            src.width = self.params.width;
+            src.height = self.params.height;
+            src.data[0] = pixels.as_ptr().cast_mut();
+            src.linesize[0] = stride as i32;
             let convert_started = std::time::Instant::now();
-            let scaled = ff::sws_scale(
-                self.sws,
-                src_data.as_ptr(),
-                src_stride.as_ptr(),
-                0,
-                self.params.height,
-                (*self.sw_frame).data.as_mut_ptr(),
-                (*self.sw_frame).linesize.as_mut_ptr(),
-            );
+            let scaled = ff::sws_scale_frame(self.sws, self.sw_frame, self.sws_src);
             self.stats.convert_ns += convert_started.elapsed().as_nanos();
+            // Never leave a pointer into the compositor's frame behind.
+            (*self.sws_src).data[0] = ptr::null_mut();
             if scaled < 0 {
-                return Err(format!("sws_scale: {}", ff::err_to_string(scaled)));
+                return Err(format!("sws_scale_frame: {}", ff::err_to_string(scaled)));
             }
             // This CPU frame is now what `encode_staged` must send, so drop any hw
             // surface a previous dmabuf frame left staged — e.g. after the stream
@@ -799,8 +812,8 @@ impl VideoEncoder {
         }
         // Built through the option API rather than `sws_getContext` so that
         // `threads` can be set at all — `sws_getContext` has no way to express
-        // it. It is set to 1 by default; see [`sws_thread_count`] for the
-        // measurement behind that.
+        // it. See [`sws_thread_count`] for how many, and [`Self::stage`] for why
+        // they only take effect through `sws_scale_frame`.
         //
         // Source and destination are the same size, so no resampling filter is
         // involved and the cheapest kernel is the right one: this is a pure
@@ -890,6 +903,9 @@ impl Drop for VideoEncoder {
             if !self.sw_frame.is_null() {
                 ff::av_frame_free(&mut self.sw_frame);
             }
+            if !self.sws_src.is_null() {
+                ff::av_frame_free(&mut self.sws_src);
+            }
             if !self.codec_ctx.is_null() {
                 ff::avcodec_free_context(&mut self.codec_ctx);
             }
@@ -1354,27 +1370,28 @@ impl Drop for Muxer {
     }
 }
 
-/// Threads to give libswscale. One, by measurement.
+/// Threads to give libswscale: half the CPU's, at most eight.
 ///
-/// BGRA→NV12 at 1920×1080 was timed at 3.80 ms/frame with one thread and
-/// 3.84 ms with eight, on an 8-thread Radeon 610M APU. The request is not being
-/// ignored — [`VideoEncoder::sws_threads`] reads the granted count back out of
-/// libswscale and it matches — the conversion is simply memory-bandwidth bound,
-/// and extra threads contend for the same bandwidth instead of adding any.
-/// Spawning eight threads per recording to gain 1% of nothing is not worth the
-/// scheduler churn on a machine that is simultaneously compositing the screen
-/// being captured.
+/// This used to be one, on a measurement that could not see threading at all:
+/// BGRA→NV12 timed the same with one thread and eight because `sws_scale` (the
+/// pointer API) runs single-threaded whatever the context's `threads` says. Only
+/// `sws_scale_frame` slices the work, and through it 3840×2160 BGRx→NV12 went
+/// from 7.6 ms/frame on one thread to 5.2 ms on four and 4.0 ms on eight (Intel
+/// Core Ultra X7 358H, 16 threads). At 4K60 that is the difference between
+/// using almost all of the 16.7 ms frame budget and keeping a third of it.
 ///
-/// The override exists because that measurement is one machine at one
-/// resolution; a 4K capture on a many-core desktop with more memory channels may
-/// well behave differently, and this makes checking it a one-liner.
+/// Half, so the compositor producing the frames keeps cores to itself; eight,
+/// because the gain flattens past that. `OPENSCREEN_LINUX_SWS_THREADS` still
+/// overrides it.
 fn sws_thread_count() -> usize {
     if let Ok(raw) = std::env::var("OPENSCREEN_LINUX_SWS_THREADS") {
         if let Ok(count) = raw.trim().parse::<usize>() {
             return count.clamp(1, 32);
         }
     }
-    1
+    std::thread::available_parallelism()
+        .map(|threads| (threads.get() / 2).clamp(1, 8))
+        .unwrap_or(1)
 }
 
 /// Parses `OPENSCREEN_LINUX_ENCODER`. Returns `None` when unset, which means

From 7237e1bccc52697aa0130f85051ef5c78946f94c Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:00:58 -0700
Subject: [PATCH 04/27] fix(linux): pass the real dmabuf size to the VA-API
 import

The importer left AVDRMFrameDescriptor.objects[0].size at 0 for the
driver to recover from the fd. Intel's iHD driver does not do that for a
LINEAR buffer: vaCreateSurfaces fails with "resource allocation failed"
and av_hwframe_map returns EIO, so every linear frame reaching the GPU
import was refused.

Read the size by seeking a dup of the fd to its end, which is how the
kernel exposes a dmabuf's size, and fall back to 0 if that fails.
Reproduced against a linear 3840x2160 GBM buffer: size 0 fails, the real
size imports.
---
 .../pipewire-capture/src/dmabuf_import.rs       | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/electron/native/pipewire-capture/src/dmabuf_import.rs b/electron/native/pipewire-capture/src/dmabuf_import.rs
index 59e900a84a..9cc5e9ff97 100644
--- a/electron/native/pipewire-capture/src/dmabuf_import.rs
+++ b/electron/native/pipewire-capture/src/dmabuf_import.rs
@@ -50,6 +50,17 @@ pub struct DmabufFrame<'a> {
     pub planes: &'a [crate::shim::DmabufPlane],
 }
 
+/// A dmabuf's allocation size, from seeking its fd to the end, which is how the
+/// kernel exposes it. 0 ("let the driver find out") if that fails; the seek goes
+/// through a dup so the plane's own fd is not touched.
+fn dmabuf_size(fd: &std::os::fd::OwnedFd) -> usize {
+    use std::io::{Seek, SeekFrom};
+    fd.try_clone()
+        .map(std::fs::File::from)
+        .and_then(|mut file| file.seek(SeekFrom::End(0)))
+        .map_or(0, |size| size as usize)
+}
+
 /// The pixel format the VAAPI-mapped surface presents, derived from the dmabuf's
 /// DRM fourcc. Only the 32-bit RGB layouts we negotiate are handled.
 fn sw_format_for_fourcc(drm_fourcc: u32) -> Option<ff::AVPixelFormat> {
@@ -357,7 +368,11 @@ impl DmabufImporter {
             }
             (*desc).nb_objects = 1;
             (*desc).objects[0].fd = frame.planes[0].fd.as_raw_fd();
-            (*desc).objects[0].size = 0; // recovered by the driver from the fd
+            // The real allocation size, not 0. Intel's iHD driver does not recover
+            // it from the fd for a LINEAR buffer: vaCreateSurfaces fails with
+            // "resource allocation failed" and the map with EIO, which is why every
+            // linear frame xdg-desktop-portal-hyprland hands out was refused.
+            (*desc).objects[0].size = dmabuf_size(&frame.planes[0].fd);
             (*desc).objects[0].format_modifier = frame.modifier;
             (*desc).nb_layers = 1;
             (*desc).layers[0].format = frame.drm_fourcc;

From 4d646eddda7458bfa6e074569c4aac27b8aa539a Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:01:05 -0700
Subject: [PATCH 05/27] fix(linux): fall back to the embedded cursor when the
 portal lacks METADATA

xdg-desktop-portal-hyprland offers only the HIDDEN and EMBEDDED cursor
modes (AvailableCursorModes = 3). With the HUD on its default editable
cursor, the helper requested METADATA, failed with
cursor-metadata-unsupported, and nothing was recorded at all.

A session that writes video now falls back to EMBEDDED, the mirror of
the existing EMBEDDED -> METADATA fallback for niri (#1357): the
recording gets the system cursor painted in rather than no recording. A
cursor-only session has no frames to paint into, so it keeps METADATA
and is still refused. handlers.ts records the mode actually negotiated,
so the editor treats such a take as system-cursor instead of drawing a
second cursor over the painted one.
---
 electron/ipc/handlers.ts                      |  8 +--
 electron/native/pipewire-capture/src/main.rs  |  7 +--
 .../native/pipewire-capture/src/portal.rs     | 51 ++++++++++++++-----
 3 files changed, 48 insertions(+), 18 deletions(-)

diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 75c3a23df7..830f157dda 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -2772,10 +2772,12 @@ export function registerIpcHandlers(
 
 				linuxNativeCaptureSession = session;
 				linuxNativeCaptureRecordingId = recordingId;
-				// The portal may lack EMBEDDED and get METADATA instead (#1357): the
-				// pointer is then not in the pixels, so the editor has to draw it.
+				// The negotiated mode, not the requested one: the portal may lack
+				// EMBEDDED and get METADATA instead (#1357), so the editor has to draw
+				// the pointer; or lack METADATA and get EMBEDDED (Hyprland), so the
+				// pointer is already in the pixels and there are no samples to draw.
 				linuxNativeCaptureCursorMode =
-					session.cursorMode === "metadata" ? "editable-overlay" : cursorCaptureMode;
+					session.cursorMode === "metadata" ? "editable-overlay" : "system";
 
 				// The portal's answer, not an in-app selection — on Wayland there
 				// is none to have. This used to read `selectedSource || { name:
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index fc4fe4b581..cd231de7e4 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -284,8 +284,9 @@ fn main() {
 
     // Probed before `ready` so the event can report it, and so an unsupported
     // compositor fails immediately instead of after a pointless picker. Only
-    // fatal when METADATA is the mode actually requested — a recording that
-    // wants the system cursor painted in has no use for it.
+    // fatal when METADATA is the mode actually negotiated — a recording that
+    // wants the system cursor painted in has no use for it, and a recording that
+    // asked for METADATA falls back to EMBEDDED where the portal lacks it.
     let offered_cursor_modes = match pollster::block_on(portal::offered_cursor_modes()) {
         Ok(modes) => modes,
         Err(error) => fail(&mut emitter, error.code(), &error.message()),
@@ -293,7 +294,7 @@ fn main() {
     let cursor_metadata_supported = offered_cursor_modes.contains(&portal::CursorMode::Metadata);
     // Resolved before anything reads it, so the portal, the click readers and
     // `ready` all see the mode that is really negotiated.
-    let cursor_mode = cursor_mode.resolve(&offered_cursor_modes);
+    let cursor_mode = cursor_mode.resolve(&offered_cursor_modes, output_path.is_some());
     if !cursor_metadata_supported && cursor_mode.reports_cursor() {
         let error = portal::PortalError::CursorMetadataUnsupported;
         fail(&mut emitter, error.code(), &error.message());
diff --git a/electron/native/pipewire-capture/src/portal.rs b/electron/native/pipewire-capture/src/portal.rs
index 68ef7156de..e4c3dbaedf 100644
--- a/electron/native/pipewire-capture/src/portal.rs
+++ b/electron/native/pipewire-capture/src/portal.rs
@@ -69,15 +69,29 @@ impl CursorMode {
     /// Some portals offer no EMBEDDED at all (niri's, #1357). Refusing to record
     /// there leaves the user nothing, so EMBEDDED falls back to METADATA: the
     /// pointer stays out of the pixels and the editor draws it from the samples
-    /// instead. Any other miss is returned unchanged, for the negotiation to
-    /// refuse with its own error.
-    pub fn resolve(self, offered: &[CursorMode]) -> CursorMode {
+    /// instead.
+    ///
+    /// Others offer no METADATA (xdg-desktop-portal-hyprland offers only HIDDEN
+    /// and EMBEDDED). The same reasoning runs the other way for a session that
+    /// writes video: METADATA falls back to EMBEDDED, and the recording gets the
+    /// system cursor painted in rather than no recording at all. A cursor-only
+    /// session (`records_video` false) has no frames to paint into, so it keeps
+    /// METADATA and is refused. Any other miss is returned unchanged, for the
+    /// negotiation to refuse with its own error.
+    pub fn resolve(self, offered: &[CursorMode], records_video: bool) -> CursorMode {
         if self == Self::Embedded
             && !offered.contains(&Self::Embedded)
             && offered.contains(&Self::Metadata)
         {
             return Self::Metadata;
         }
+        if self == Self::Metadata
+            && records_video
+            && !offered.contains(&Self::Metadata)
+            && offered.contains(&Self::Embedded)
+        {
+            return Self::Embedded;
+        }
         self
     }
 }
@@ -129,10 +143,10 @@ pub struct PortalStream {
 
 #[derive(Debug)]
 pub enum PortalError {
-    /// The compositor's portal does not offer METADATA cursor mode. Nothing
-    /// this helper does can work without it, and falling back to EMBEDDED would
-    /// bake the cursor into the pixels, which is the opposite of what the
-    /// editor needs.
+    /// The compositor's portal does not offer METADATA cursor mode, and the
+    /// session cannot fall back to EMBEDDED: it records no video to paint the
+    /// pointer into, or the portal offers no EMBEDDED either (see
+    /// `CursorMode::resolve`).
     CursorMetadataUnsupported,
     /// The user dismissed the picker, or the portal refused.
     Cancelled,
@@ -311,18 +325,31 @@ mod tests {
 
     #[test]
     fn embedded_falls_back_to_metadata_when_the_portal_lacks_it() {
-        assert_eq!(Embedded.resolve(&[Metadata, Hidden]), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Hidden], true), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Hidden], false), Metadata);
+    }
+
+    #[test]
+    fn metadata_falls_back_to_embedded_when_recording_video() {
+        // xdg-desktop-portal-hyprland's offer.
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], true), Embedded);
+    }
+
+    #[test]
+    fn a_cursor_only_session_keeps_metadata_for_negotiation_to_refuse() {
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], false), Metadata);
     }
 
     #[test]
     fn an_offered_mode_is_kept() {
-        assert_eq!(Embedded.resolve(&[Metadata, Embedded]), Embedded);
-        assert_eq!(Metadata.resolve(&[Metadata]), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Embedded], true), Embedded);
+        assert_eq!(Metadata.resolve(&[Metadata, Embedded], true), Metadata);
+        assert_eq!(Metadata.resolve(&[Metadata], false), Metadata);
     }
 
     #[test]
     fn a_miss_without_a_fallback_is_left_for_negotiation_to_refuse() {
-        assert_eq!(Embedded.resolve(&[Hidden]), Embedded);
-        assert_eq!(Metadata.resolve(&[Embedded]), Metadata);
+        assert_eq!(Embedded.resolve(&[Hidden], true), Embedded);
+        assert_eq!(Metadata.resolve(&[Hidden], true), Metadata);
     }
 }

From 5a9914b81128e78363e10bf689e4208eb41af31a Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 09:17:04 -0700
Subject: [PATCH 06/27] feat(linux): cursor positions and click zooms on
 Hyprland

xdg-desktop-portal-hyprland offers no METADATA cursor mode, so Hyprland
takes had no cursor positions: no auto-zoom, no editor-drawn cursor.
Hyprland's own IPC reports the pointer, so the capture helper now takes
positions from there (hyprland.rs), polled at the sample cadence.

- Editable cursor requested: the helper negotiates HIDDEN and limits the
  picker to monitors, and the editor draws the cursor from these samples
  (.cursor.json), so hide, styles and click bounce work. Windows are left
  out because the portal does not say which window was shared.
- The granted monitor's position and scale come from Hyprland's monitor
  list: the portal reports its size in physical pixels, which halved
  every position on a scale-2 monitor.
- A take with the pointer painted in (EMBEDDED) keeps its samples in
  <video>.pointer.json, which feeds auto-zoom and click sounds but is
  never drawn. The compositor falls back to it for auto focus and marks
  the track painted-in so it draws no second cursor.
- Clicks come from the existing evdev reader, which now also runs for
  these sessions.
---
 crates/compositor/src/cursor.rs               |  62 +++
 crates/compositor/src/frame_geometry.rs       |  37 +-
 electron/ipc/handlers.ts                      |  22 +-
 electron/media/cursorSidecar.test.ts          |  34 ++
 electron/media/cursorSidecar.ts               |  19 +-
 .../capture/linuxNativeCaptureSession.test.ts |  18 +
 .../capture/linuxNativeCaptureSession.ts      |  17 +-
 .../native/pipewire-capture/src/hyprland.rs   | 352 ++++++++++++++++++
 electron/native/pipewire-capture/src/main.rs  | 118 +++++-
 .../native/pipewire-capture/src/portal.rs     |  67 +++-
 .../ai-edition/recordingImport.test.ts        |  19 +-
 src/components/ai-edition/recordingImport.ts  |   6 +-
 src/lib/recordingSession.ts                   |   8 +
 13 files changed, 747 insertions(+), 32 deletions(-)
 create mode 100644 electron/native/pipewire-capture/src/hyprland.rs

diff --git a/crates/compositor/src/cursor.rs b/crates/compositor/src/cursor.rs
index 4eb981919c..6ca4439121 100644
--- a/crates/compositor/src/cursor.rs
+++ b/crates/compositor/src/cursor.rs
@@ -55,6 +55,10 @@ pub struct CursorTrack {
     /// (`follow_in_view`). Partagé entre clones, qui ont les mêmes échantillons.
     view_cache:
         std::sync::Arc<std::sync::Mutex<Vec<(ViewKey, std::sync::Arc<Vec<(f32, f32, f32)>>)>>>,
+    /// Le pointeur est déjà PEINT dans les pixels (`<vidéo>.pointer.json`, cf. `load`) : la
+    /// piste sert au suivi auto du zoom, mais rien ne la dessine, ni sprite ni impact de clic,
+    /// sans quoi un second curseur se poserait sur le premier (`frame_geometry::cursor_alpha`).
+    painted_in: bool,
 }
 
 type ViewKey = (u32, u32, u32);
@@ -161,9 +165,15 @@ impl CursorTrack {
             visibility,
             types,
             view_cache: Default::default(),
+            painted_in: false,
         }
     }
 
+    /// Vrai pour une piste chargée depuis un `.pointer.json` : voir le champ `painted_in`.
+    pub fn painted_in(&self) -> bool {
+        self.painted_in
+    }
+
     /// Visibilité enregistrée au temps `t`. Les anciens sidecars qui n'ont pas ce champ sont
     /// visibles par défaut, comme les lecteurs TypeScript.
     pub fn visible_at(&self, t: f32) -> bool {
@@ -188,7 +198,28 @@ impl CursorTrack {
     }
 
     /// Charge la fenêtre [offset_ms, offset_ms + dur_s*1000] et la ramène à t=0.
+    ///
+    /// Un `<vidéo>.cursor.json` absent retombe sur `<vidéo>.pointer.json` : une prise dont le
+    /// pointeur est peint dans l'image (Linux sous Hyprland, dont le portail ne sait pas l'en
+    /// sortir) ne sait que où il était. Résolu ICI, pas à chaque appelant : l'aperçu, l'export
+    /// MP4 et le GIF passent tous le chemin du `.cursor.json` et passent tous par ici.
     pub fn load(path: &str, offset_ms: f64, dur_s: f64) -> Result<CursorTrack> {
+        match CursorTrack::load_file(path, offset_ms, dur_s) {
+            Err(error) if !std::path::Path::new(path).exists() => {
+                let Some(stem) = path.strip_suffix(".cursor.json") else { return Err(error) };
+                let pointer = format!("{stem}.pointer.json");
+                if !std::path::Path::new(&pointer).exists() {
+                    return Err(error);
+                }
+                let mut track = CursorTrack::load_file(&pointer, offset_ms, dur_s)?;
+                track.painted_in = true;
+                Ok(track)
+            }
+            loaded => loaded,
+        }
+    }
+
+    fn load_file(path: &str, offset_ms: f64, dur_s: f64) -> Result<CursorTrack> {
         let txt = std::fs::read_to_string(path).with_context(|| format!("lecture {path}"))?;
         let v: serde_json::Value = serde_json::from_str(&txt)?;
         let arr = v["samples"].as_array().context("samples[]")?;
@@ -536,6 +567,7 @@ impl CursorTrack {
         // cliqués restent ceux de la piste brute.
         CursorTrack {
             click_points: self.click_points.clone(),
+            painted_in: self.painted_in,
             ..CursorTrack::new_with_visibility(
                 samples,
                 self.clicks.clone(),
@@ -1151,4 +1183,34 @@ mod tests {
         // Et s'éteint 1.8s après le clic (4.0 + 1.8 = 5.8s)
         assert_eq!(track.opacity_at(5.9, true), 0.0);
     }
+
+    #[test]
+    fn falls_back_to_the_pointer_sidecar_of_a_painted_in_take() {
+        let dir = std::env::temp_dir().join(format!("pointer-sidecar-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).expect("temp dir");
+        let video = dir.join("take.mp4");
+        let cursor_json = format!("{}.cursor.json", video.to_str().expect("utf-8 path"));
+        let pointer_json = format!("{}.pointer.json", video.to_str().expect("utf-8 path"));
+        std::fs::write(
+            &pointer_json,
+            r#"{"samples":[{"timeMs":0,"cx":0.2,"cy":0.2},{"timeMs":1000,"cx":0.8,"cy":0.8}]}"#,
+        )
+        .expect("write pointer sidecar");
+
+        let track = CursorTrack::load(&cursor_json, 0.0, 2.0).expect("falls back");
+        assert!(track.painted_in());
+        assert!(track.at(1.0).is_some());
+        // Le lissage (slider « smoothing ») garde le marqueur : sinon le curseur réapparaît.
+        assert!(track.smoothed(0.5).painted_in());
+
+        // Un `.cursor.json` présent l'emporte, et se dessine.
+        std::fs::write(&cursor_json, r#"{"samples":[{"timeMs":0,"cx":0.5,"cy":0.5}]}"#)
+            .expect("write cursor sidecar");
+        let drawn = CursorTrack::load(&cursor_json, 0.0, 2.0).expect("loads the drawable one");
+        assert!(!drawn.painted_in());
+        let _ = std::fs::remove_dir_all(&dir);
+
+        // Ni l'un ni l'autre : l'erreur d'origine, comme avant.
+        assert!(CursorTrack::load(&cursor_json, 0.0, 2.0).is_err());
+    }
 }
diff --git a/crates/compositor/src/frame_geometry.rs b/crates/compositor/src/frame_geometry.rs
index f189f6f379..39102846a8 100644
--- a/crates/compositor/src/frame_geometry.rs
+++ b/crates/compositor/src/frame_geometry.rs
@@ -3723,7 +3723,8 @@ pub struct CursorPlanInput<'a> {
     pub t: f32,
 }
 
-/// Opacité du curseur à `t`, avant placement : 0 quand il est masqué (`cursor.show`), sinon
+/// Opacité du curseur à `t`, avant placement : 0 quand il est masqué (`cursor.show`) ou déjà
+/// peint dans l'image (`CursorTrack::painted_in`), sinon
 /// l'auto-hide × le `hideCursor` des régions de zoom. Partagée par `plan_cursor` et l'impact du
 /// clic : le plan ne bascule que sous un pointeur qu'on voit.
 pub fn cursor_alpha(
@@ -3733,7 +3734,7 @@ pub fn cursor_alpha(
     track: &crate::cursor::CursorTrack,
     t: f32,
 ) -> f32 {
-    if !scene.map(|s| s.cursor.show).unwrap_or(cfg.cursor) {
+    if !scene.map(|s| s.cursor.show).unwrap_or(cfg.cursor) || track.painted_in() {
         return 0.0;
     }
     let idle_alpha = track.opacity_at(t, live.cursor_auto_hide);
@@ -8242,6 +8243,38 @@ mod tests {
 
     /// clickBounce au maximum du slider (5) : le creux de la pression donnerait 1 - 0.24 * 5 < 0.
     /// La taille ne doit jamais devenir négative ; au creux, rien n'est dessiné.
+    #[test]
+    fn plan_cursor_draws_nothing_for_a_pointer_painted_into_the_pixels() {
+        let cfg = crate::config::all().pop().expect("cfg");
+        let scene = zoomed_golden_scene();
+        let fg = full_frame_geometry();
+        let dir = std::env::temp_dir().join(format!("painted-in-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).expect("temp dir");
+        let video = dir.join("take.mp4");
+        std::fs::write(
+            dir.join("take.mp4.pointer.json"),
+            r#"{"samples":[{"timeMs":0,"cx":0.5,"cy":0.5},{"timeMs":500,"cx":0.5,"cy":0.5,"interactionType":"click"},{"timeMs":2000,"cx":0.5,"cy":0.5}]}"#,
+        )
+        .expect("write pointer sidecar");
+        let cursor_json = format!("{}.cursor.json", video.to_str().expect("utf-8 path"));
+        let track = crate::cursor::CursorTrack::load(&cursor_json, 0.0, 3.0).expect("load");
+        let _ = std::fs::remove_dir_all(&dir);
+
+        let input = |t: f32| CursorPlanInput {
+            render_px: [1920.0, 1080.0],
+            u_max: 1.0,
+            v_max: 1.0,
+            cfg: &cfg,
+            live: LiveParams::default(),
+            scene: Some(&scene),
+            track: &track,
+            t,
+        };
+        // Ni sprite ni anneau de clic, juste après le clic compris : le pointeur est dans l'image.
+        assert!(plan_cursor(&fg, &input(0.6)).is_none());
+        assert!(plan_cursor(&fg, &input(1.0)).is_none());
+    }
+
     #[test]
     fn plan_cursor_never_yields_a_negative_size_at_max_bounce() {
         let cfg = crate::config::all().pop().expect("cfg");
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 830f157dda..3ad4b32293 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -90,6 +90,7 @@ import { createMediaTools, type MediaToolDeps, type RecordRequest } from "../mcp
 import { createToolRunner, type McpToolDeps } from "../mcp/openscreen-mcp-server";
 import { type AudioPeaksResult, getAudioPeaks } from "../media/audioPeaks";
 import {
+	POINTER_TELEMETRY_SUFFIX,
 	readCursorRecordingFile as readCursorRecordingFileFrom,
 	readCursorSidecar,
 	readCursorTelemetryFile as readCursorTelemetryFileFrom,
@@ -2774,10 +2775,11 @@ export function registerIpcHandlers(
 				linuxNativeCaptureRecordingId = recordingId;
 				// The negotiated mode, not the requested one: the portal may lack
 				// EMBEDDED and get METADATA instead (#1357), so the editor has to draw
-				// the pointer; or lack METADATA and get EMBEDDED (Hyprland), so the
-				// pointer is already in the pixels and there are no samples to draw.
+				// the pointer; or lack METADATA and get HIDDEN (Hyprland, positions from
+				// its IPC), so the editor draws it too; or EMBEDDED, so the pointer is
+				// already in the pixels and its samples, if any, only place zooms.
 				linuxNativeCaptureCursorMode =
-					session.cursorMode === "metadata" ? "editable-overlay" : "system";
+					session.cursorMode === "embedded" ? "system" : "editable-overlay";
 
 				// The portal's answer, not an in-app selection — on Wayland there
 				// is none to have. This used to read `selectedSource || { name:
@@ -2834,6 +2836,7 @@ export function registerIpcHandlers(
 				await Promise.all([
 					fs.rm(discarded, { force: true }),
 					fs.rm(`${discarded}.cursor.json`, { force: true }),
+					fs.rm(`${discarded}${POINTER_TELEMETRY_SUFFIX}`, { force: true }),
 				]);
 				return { success: true, discarded: true };
 			}
@@ -2850,11 +2853,24 @@ export function registerIpcHandlers(
 					"utf-8",
 				);
 			}
+			// The pointer is painted into the video, yet the helper still reported where it
+			// was (Hyprland's IPC, when its portal could not leave it out). Kept apart from
+			// `.cursor.json`, which the editor and the compositor DRAW: these samples only
+			// place zooms and click sounds, over the pointer already in the pixels.
+			const pointerTelemetry = cursorCaptureMode === "system" && result.cursor.samples.length > 0;
+			if (pointerTelemetry) {
+				await fs.writeFile(
+					`${result.path}${POINTER_TELEMETRY_SUFFIX}`,
+					JSON.stringify({ ...result.cursor, assets: [] }, null, 2),
+					"utf-8",
+				);
+			}
 
 			const session_: RecordingSession = {
 				screenVideoPath: result.path,
 				createdAt: recordingId,
 				cursorCaptureMode,
+				...(pointerTelemetry ? { pointerTelemetry: true } : {}),
 			};
 			setCurrentRecordingSessionState(session_);
 			currentProjectPath = null;
diff --git a/electron/media/cursorSidecar.test.ts b/electron/media/cursorSidecar.test.ts
index 88c7ed0dac..8fdcce2bcb 100644
--- a/electron/media/cursorSidecar.test.ts
+++ b/electron/media/cursorSidecar.test.ts
@@ -13,6 +13,8 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
+	POINTER_TELEMETRY_SUFFIX,
+	readCursorRecordingFile,
 	readCursorRecordingFileAt,
 	readCursorSidecar,
 	readCursorTelemetryFile,
@@ -193,4 +195,36 @@ describe("readCursorTelemetryFile", () => {
 			"middle-click",
 		]);
 	});
+
+	it("falls back to the pointer telemetry of a take with the pointer painted in", async () => {
+		const video = path.join(dir, "painted.mp4");
+		await fs.writeFile(
+			`${video}${POINTER_TELEMETRY_SUFFIX}`,
+			JSON.stringify({ samples: [{ timeMs: 10, cx: 0.25, cy: 0.75, interactionType: "click" }] }),
+			"utf-8",
+		);
+
+		const telemetry = await readCursorTelemetryFile(video, {});
+
+		expect(telemetry.samples).toEqual([
+			{ timeMs: 10, cx: 0.25, cy: 0.75, visible: true, interactionType: "click" },
+		]);
+		// What draws a cursor never sees it: a second pointer would sit over the one
+		// already in the pixels.
+		expect((await readCursorRecordingFile(video, {})).samples).toEqual([]);
+	});
+
+	it("prefers the drawable sidecar when a take has both", async () => {
+		const video = path.join(dir, "both.mp4");
+		await writeSidecar(video, { samples: [{ timeMs: 10, cx: 0.1, cy: 0.1 }] });
+		await fs.writeFile(
+			`${video}${POINTER_TELEMETRY_SUFFIX}`,
+			JSON.stringify({ samples: [{ timeMs: 10, cx: 0.9, cy: 0.9 }] }),
+			"utf-8",
+		);
+
+		const telemetry = await readCursorTelemetryFile(video, {});
+
+		expect(telemetry.samples.map((sample) => sample.cx)).toEqual([0.1]);
+	});
 });
diff --git a/electron/media/cursorSidecar.ts b/electron/media/cursorSidecar.ts
index 0a588e0ae7..2fc62d3b7c 100644
--- a/electron/media/cursorSidecar.ts
+++ b/electron/media/cursorSidecar.ts
@@ -27,6 +27,15 @@ import { findMediaLinksByFingerprint } from "./mediaLinksRegistry";
 
 export const CURSOR_TELEMETRY_VERSION = 2;
 
+/**
+ * `<video>.pointer.json`: where the pointer was in a take that has it painted into its
+ * pixels (Linux on Hyprland, whose portal cannot leave it out). Same format as
+ * `.cursor.json`, but a separate file on purpose: everything that DRAWS a cursor (the
+ * editor overlay, the compositor) reads `.cursor.json` only, so this one can feed
+ * auto-zoom and click sounds without a second pointer appearing over the first.
+ */
+export const POINTER_TELEMETRY_SUFFIX = ".pointer.json";
+
 /** Where a sidecar was found, or why it was not. `"none"` means we LOOKED and
  * there was nothing — distinct from never having looked, which this module
  * cannot represent and its callers must not conflate. */
@@ -229,13 +238,19 @@ export async function readCursorRecordingFile(
 /** The renderer's `loadCursorTelemetry`. Carries `interactionType` through: the
  * ai-edition auto-zoom detector places zooms on recorded clicks (issue #699), so
  * this IS a "where did the user act" consumer. The old projection here dropped
- * the field — the detector never saw a click, however many the take recorded. */
+ * the field — the detector never saw a click, however many the take recorded.
+ * A take with no drawable sidecar falls back to its `.pointer.json`. */
 export async function readCursorTelemetryFile(
 	targetVideoPath: string,
 	options: { recordingsDir?: string },
 ) {
 	try {
-		const recordingData = await readCursorRecordingFile(targetVideoPath, options);
+		let recordingData = await readCursorRecordingFile(targetVideoPath, options);
+		if (recordingData.samples.length === 0) {
+			recordingData = await readCursorRecordingFileAt(
+				`${targetVideoPath}${POINTER_TELEMETRY_SUFFIX}`,
+			);
+		}
 		return {
 			success: true,
 			samples: recordingData.samples.map((sample) => ({
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index 0d900a7d70..63aad34d91 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -206,6 +206,24 @@ describe("LinuxNativeCaptureSession", () => {
 		expect(session.cursorMode).toBe("metadata");
 	});
 
+	// Hyprland: no METADATA, but its IPC reports the pointer, so the helper keeps it out
+	// of the pixels and the editor draws it.
+	it("reports a hidden cursor the helper negotiated", async () => {
+		const session = new LinuxNativeCaptureSession({
+			outputPath: "/tmp/recording.mp4",
+			cursorMode: "metadata",
+			fps: 30,
+			audio: { system: { enabled: false }, microphone: { enabled: false, gain: 1 } },
+			maxCursorSamples: 100,
+		});
+		const started = session.start();
+		await Promise.resolve();
+		helper.emitEvent({ event: "ready", timestampMs: 1_000, cursorMode: "hidden" });
+		await started;
+
+		expect(session.cursorMode).toBe("hidden");
+	});
+
 	it("keeps the requested cursor mode when the helper does not report one", async () => {
 		const session = newSession();
 		await startReady(session);
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index 19a83b5c60..bd4518a173 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -54,6 +54,9 @@ const FIRST_FRAME_TIMEOUT_MS = 10_000;
  */
 const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
 
+/** What the helper negotiated, which the request does not decide alone (see `cursorMode`). */
+export type LinuxNegotiatedCursorMode = "metadata" | "embedded" | "hidden";
+
 export interface LinuxCaptureConfig {
 	outputPath: string;
 	cursorMode: "metadata" | "embedded";
@@ -114,7 +117,7 @@ export class LinuxNativeCaptureSession {
 	private stoppedReject: ((error: Error) => void) | null = null;
 
 	private sourceKind: LinuxCaptureSourceKind | undefined;
-	private negotiatedCursorMode: LinuxCaptureConfig["cursorMode"] | undefined;
+	private negotiatedCursorMode: LinuxNegotiatedCursorMode | undefined;
 	private videoEncoder: string | undefined;
 	private lastError: string | null = null;
 	private paused = false;
@@ -359,9 +362,11 @@ export class LinuxNativeCaptureSession {
 	/**
 	 * 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.
+	 * to be drawn by the editor even though the system cursor was asked for. A
+	 * portal without METADATA gets HIDDEN under Hyprland, whose IPC reports the
+	 * pointer instead, so the editor draws it there too; EMBEDDED otherwise.
 	 */
-	get cursorMode(): LinuxCaptureConfig["cursorMode"] {
+	get cursorMode(): LinuxNegotiatedCursorMode {
 		return this.negotiatedCursorMode ?? this.config.cursorMode;
 	}
 
@@ -481,7 +486,11 @@ export class LinuxNativeCaptureSession {
 	private handleEvent(payload: PipeWireHelperEvent) {
 		switch (payload.event) {
 			case "ready":
-				if (payload.cursorMode === "metadata" || payload.cursorMode === "embedded") {
+				if (
+					payload.cursorMode === "metadata" ||
+					payload.cursorMode === "embedded" ||
+					payload.cursorMode === "hidden"
+				) {
 					this.negotiatedCursorMode = payload.cursorMode;
 				}
 				this.resolveReady();
diff --git a/electron/native/pipewire-capture/src/hyprland.rs b/electron/native/pipewire-capture/src/hyprland.rs
new file mode 100644
index 0000000000..5258705eed
--- /dev/null
+++ b/electron/native/pipewire-capture/src/hyprland.rs
@@ -0,0 +1,352 @@
+//! Pointer positions from Hyprland's IPC, for a portal that cannot report them.
+//!
+//! WHY THIS EXISTS. xdg-desktop-portal-hyprland offers only the HIDDEN and
+//! EMBEDDED cursor modes, never METADATA, so a recording there gets the pointer
+//! painted into its pixels and no record of where it was. Without positions the
+//! editor has nothing to place a zoom on, and the clicks `input.rs` reads have
+//! no location. Hyprland itself knows: its request socket answers `j/cursorpos`
+//! with the pointer in global layout coordinates, the space its monitors are
+//! placed in.
+//!
+//! SCOPE. Positions only, polled at the sample cadence, and only for a monitor
+//! stream: for a window the portal says nothing about which window the user
+//! picked, so there is nothing to subtract. The monitor's place in the layout
+//! comes from Hyprland's own `j/monitors` too, not from the portal: its portal
+//! reports the stream's size in PHYSICAL pixels, so a scale derived from it was
+//! 1 on a scale-2 monitor and put every position at half its real distance
+//! from the corner (measured against a take with the pointer painted in).
+
+use std::io::{Read, Write};
+use std::os::unix::net::UnixStream;
+use std::path::PathBuf;
+use std::sync::mpsc::Sender;
+use std::thread;
+use std::time::Duration;
+
+use serde::Deserialize;
+
+use crate::Message;
+
+/// A request is one connection: Hyprland answers and closes, so a reply that
+/// takes longer than this is a compositor that has stopped answering.
+const QUERY_TIMEOUT: Duration = Duration::from_millis(250);
+
+/// The request socket of the Hyprland instance this process runs under, if any.
+///
+/// `$XDG_RUNTIME_DIR/hypr/<signature>/` since Hyprland 0.40; `/tmp/hypr/` before.
+pub fn socket_path() -> Option<PathBuf> {
+    let signature = std::env::var_os("HYPRLAND_INSTANCE_SIGNATURE")?;
+    let runtime = std::env::var_os("XDG_RUNTIME_DIR").map(PathBuf::from);
+    runtime
+        .into_iter()
+        .chain([PathBuf::from("/tmp")])
+        .map(|base| base.join("hypr").join(&signature).join(".socket.sock"))
+        .find(|path| path.exists())
+}
+
+#[derive(Debug, Deserialize)]
+struct CursorPos {
+    x: f64,
+    y: f64,
+}
+
+fn request(socket: &PathBuf, command: &str) -> Result<String, String> {
+    let mut stream = UnixStream::connect(socket).map_err(|error| error.to_string())?;
+    stream
+        .set_read_timeout(Some(QUERY_TIMEOUT))
+        .map_err(|error| error.to_string())?;
+    stream
+        .set_write_timeout(Some(QUERY_TIMEOUT))
+        .map_err(|error| error.to_string())?;
+    stream
+        .write_all(command.as_bytes())
+        .map_err(|error| error.to_string())?;
+    let mut reply = String::new();
+    stream
+        .read_to_string(&mut reply)
+        .map_err(|error| error.to_string())?;
+    Ok(reply)
+}
+
+/// The pointer in global layout coordinates (logical pixels).
+pub fn query_cursor(socket: &PathBuf) -> Result<(f64, f64), String> {
+    parse_cursor(&request(socket, "j/cursorpos")?)
+}
+
+/// One output as `j/monitors` describes it: its place in the layout (logical),
+/// its mode (physical pixels, before rotation) and the scale between the two.
+#[derive(Debug, Clone, Deserialize, PartialEq)]
+pub struct Monitor {
+    pub x: i32,
+    pub y: i32,
+    pub width: i32,
+    pub height: i32,
+    pub scale: f64,
+    #[serde(default)]
+    pub transform: i32,
+}
+
+impl Monitor {
+    /// The output's size in the layout. A quarter turn (transforms 1, 3, 5, 7)
+    /// swaps the mode's sides.
+    fn logical_size(&self) -> (i32, i32) {
+        let (width, height) = if self.transform % 2 == 1 {
+            (self.height, self.width)
+        } else {
+            (self.width, self.height)
+        };
+        let scale = if self.scale > 0.0 { self.scale } else { 1.0 };
+        (
+            (f64::from(width) / scale).round() as i32,
+            (f64::from(height) / scale).round() as i32,
+        )
+    }
+}
+
+pub fn query_monitors(socket: &PathBuf) -> Result<Vec<Monitor>, String> {
+    let reply = request(socket, "j/monitors")?;
+    serde_json::from_str(&reply).map_err(|error| format!("unexpected monitors reply: {error}"))
+}
+
+/// The granted monitor's place in the layout: (position, logical size).
+///
+/// Found by the position the portal reports, which is the layout's; failing a
+/// single match there, by its size, which this portal gives in physical pixels
+/// (a mode) and others in logical ones. None when neither is unambiguous: a
+/// position guessed on the wrong monitor would be worse than none.
+fn only<'a>(found: Vec<&'a Monitor>) -> Option<&'a Monitor> {
+    (found.len() == 1).then(|| found[0])
+}
+
+pub fn granted_monitor(
+    monitors: &[Monitor],
+    portal_position: Option<(i32, i32)>,
+    portal_size: Option<(i32, i32)>,
+) -> Option<((i32, i32), (i32, i32))> {
+    let monitor = portal_position
+        .and_then(|position| only(monitors.iter().filter(|m| (m.x, m.y) == position).collect()))
+        .or_else(|| {
+            let size = portal_size?;
+            only(
+                monitors
+                    .iter()
+                    .filter(|m| {
+                        let mode = if m.transform % 2 == 1 {
+                            (m.height, m.width)
+                        } else {
+                            (m.width, m.height)
+                        };
+                        mode == size || m.logical_size() == size
+                    })
+                    .collect(),
+            )
+        })?;
+    Some(((monitor.x, monitor.y), monitor.logical_size()))
+}
+
+fn parse_cursor(reply: &str) -> Result<(f64, f64), String> {
+    let position: CursorPos = serde_json::from_str(reply)
+        .map_err(|error| format!("unexpected cursorpos reply {reply:?}: {error}"))?;
+    Ok((position.x, position.y))
+}
+
+/// Polls the pointer every `interval` and forwards it as
+/// [`Message::HostPointer`]. Stops at the first failed query, reporting it as
+/// [`Message::HostPointerLost`]: a compositor that stopped answering will not
+/// start again within one recording, and retrying would flood the log.
+pub fn spawn_poller(sender: Sender<Message>, socket: PathBuf, interval: Duration) {
+    thread::spawn(move || loop {
+        match query_cursor(&socket) {
+            Ok(position) => {
+                if sender.send(Message::HostPointer(position)).is_err() {
+                    return; // the session is over
+                }
+            }
+            Err(message) => {
+                let _ = sender.send(Message::HostPointerLost(message));
+                return;
+            }
+        }
+        thread::sleep(interval);
+    });
+}
+
+/// Where a monitor stream sits in the global layout, from the portal, and its
+/// size in stream pixels, from the negotiated format.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct MonitorPlacement {
+    pub position: (i32, i32),
+    pub logical_size: (i32, i32),
+    pub pixel_size: (i32, i32),
+}
+
+/// Maps a global pointer position into the stream's pixels, the space the
+/// portal's own cursor metadata uses and `emit_sample` expects. The scale is
+/// derived per axis from the two sizes, so a fractional monitor scale needs no
+/// separate lookup.
+pub fn to_stream_pixels(pointer: (f64, f64), placement: MonitorPlacement) -> Option<(i32, i32)> {
+    let (logical_width, logical_height) = placement.logical_size;
+    if logical_width <= 0 || logical_height <= 0 {
+        return None;
+    }
+    let scale_x = f64::from(placement.pixel_size.0) / f64::from(logical_width);
+    let scale_y = f64::from(placement.pixel_size.1) / f64::from(logical_height);
+    let x = (pointer.0 - f64::from(placement.position.0)) * scale_x;
+    let y = (pointer.1 - f64::from(placement.position.1)) * scale_y;
+    Some((x.round() as i32, y.round() as i32))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_hyprlands_reply() {
+        assert_eq!(
+            parse_cursor("{\n    \"x\": 2911,\n    \"y\": 541\n}\n"),
+            Ok((2911.0, 541.0))
+        );
+    }
+
+    #[test]
+    fn refuses_a_reply_that_is_not_a_position() {
+        assert!(parse_cursor("unknown request").is_err());
+    }
+
+    #[test]
+    fn maps_a_scaled_monitor_into_its_stream_pixels() {
+        // A 3840x2160 monitor at scale 2, placed at the origin: 1920x1080 logical.
+        let placement = MonitorPlacement {
+            position: (0, 0),
+            logical_size: (1920, 1080),
+            pixel_size: (3840, 2160),
+        };
+        assert_eq!(
+            to_stream_pixels((1007.0, 551.0), placement),
+            Some((2014, 1102))
+        );
+    }
+
+    #[test]
+    fn subtracts_the_monitors_place_in_the_layout() {
+        // The second monitor, right of a 1920-wide one, at scale 2.
+        let placement = MonitorPlacement {
+            position: (1920, 0),
+            logical_size: (1536, 960),
+            pixel_size: (3072, 1920),
+        };
+        assert_eq!(
+            to_stream_pixels((2911.0, 541.0), placement),
+            Some((1982, 1082))
+        );
+    }
+
+    #[test]
+    fn keeps_a_pointer_on_another_monitor_outside_the_stream() {
+        // Reported, not clamped: emit_sample marks it invisible.
+        let placement = MonitorPlacement {
+            position: (1920, 0),
+            logical_size: (1536, 960),
+            pixel_size: (3072, 1920),
+        };
+        let (x, _) = to_stream_pixels((100.0, 100.0), placement).unwrap();
+        assert!(x < 0);
+    }
+
+    #[test]
+    fn handles_a_fractional_scale() {
+        // 2880x1800 at scale 1.5: 1920x1200 logical.
+        let placement = MonitorPlacement {
+            position: (0, 0),
+            logical_size: (1920, 1200),
+            pixel_size: (2880, 1800),
+        };
+        assert_eq!(
+            to_stream_pixels((1000.0, 600.0), placement),
+            Some((1500, 900))
+        );
+    }
+
+    fn monitors() -> Vec<Monitor> {
+        // This machine's layout: a 4K monitor at scale 2, a 3072x1920 laptop panel
+        // at scale 2 to its right.
+        serde_json::from_str(
+            r#"[{"name":"HDMI-A-1","x":0,"y":0,"width":3840,"height":2160,"scale":2.0,"transform":0},
+                {"name":"eDP-1","x":1920,"y":0,"width":3072,"height":1920,"scale":2.0,"transform":0}]"#,
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn finds_the_granted_monitor_by_its_place_in_the_layout() {
+        assert_eq!(
+            granted_monitor(&monitors(), Some((1920, 0)), Some((3072, 1920))),
+            Some(((1920, 0), (1536, 960)))
+        );
+    }
+
+    #[test]
+    fn takes_the_scale_from_hyprland_not_from_the_portals_physical_size() {
+        // The portal reports 3840x2160 for the 4K monitor; the layout is 1920x1080.
+        let (position, logical_size) =
+            granted_monitor(&monitors(), Some((0, 0)), Some((3840, 2160))).unwrap();
+        let placement = MonitorPlacement {
+            position,
+            logical_size,
+            pixel_size: (3840, 2160),
+        };
+        // Measured: the pointer painted at (3670, 2090) of the frame, Hyprland at (1835, 1045).
+        assert_eq!(
+            to_stream_pixels((1835.0, 1045.0), placement),
+            Some((3670, 2090))
+        );
+    }
+
+    #[test]
+    fn falls_back_to_the_size_when_the_position_matches_nothing() {
+        assert_eq!(
+            granted_monitor(&monitors(), None, Some((3072, 1920))),
+            Some(((1920, 0), (1536, 960)))
+        );
+        assert_eq!(
+            granted_monitor(&monitors(), Some((5, 5)), Some((1536, 960))),
+            Some(((1920, 0), (1536, 960)))
+        );
+    }
+
+    #[test]
+    fn gives_up_rather_than_guess_between_two_matching_monitors() {
+        let twins: Vec<Monitor> = serde_json::from_str(
+            r#"[{"x":0,"y":0,"width":1920,"height":1080,"scale":1.0},
+                {"x":1920,"y":0,"width":1920,"height":1080,"scale":1.0}]"#,
+        )
+        .unwrap();
+        assert_eq!(granted_monitor(&twins, None, Some((1920, 1080))), None);
+        assert_eq!(
+            granted_monitor(&twins, Some((1920, 0)), Some((1920, 1080))),
+            Some(((1920, 0), (1920, 1080)))
+        );
+    }
+
+    #[test]
+    fn swaps_the_sides_of_a_rotated_monitor() {
+        let rotated: Vec<Monitor> = serde_json::from_str(
+            r#"[{"x":0,"y":0,"width":2560,"height":1440,"scale":1.0,"transform":1}]"#,
+        )
+        .unwrap();
+        assert_eq!(
+            granted_monitor(&rotated, Some((0, 0)), None),
+            Some(((0, 0), (1440, 2560)))
+        );
+    }
+
+    #[test]
+    fn refuses_an_empty_logical_size() {
+        let placement = MonitorPlacement {
+            position: (0, 0),
+            logical_size: (0, 0),
+            pixel_size: (3840, 2160),
+        };
+        assert_eq!(to_stream_pixels((10.0, 10.0), placement), None);
+    }
+}
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index cd231de7e4..b83007a79a 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -33,6 +33,7 @@ mod dmabuf_import;
 mod encoder;
 mod events;
 mod ffmpeg;
+mod hyprland;
 mod input;
 mod portal;
 mod shim;
@@ -233,6 +234,11 @@ enum Message {
     /// the string is the OS error. Surfaced as a warning so click capture going
     /// quiet mid-recording is not silent.
     PointerDeviceLost(String),
+    /// The pointer in global layout coordinates, from the compositor's own IPC
+    /// rather than the portal. See [`hyprland`] for when this is the source.
+    HostPointer((f64, f64)),
+    /// The compositor IPC stopped answering; no further positions will arrive.
+    HostPointerLost(String),
     /// Arm a deferred session: connect to PipeWire and start encoding.
     Record,
     Pause,
@@ -292,9 +298,23 @@ fn main() {
         Err(error) => fail(&mut emitter, error.code(), &error.message()),
     };
     let cursor_metadata_supported = offered_cursor_modes.contains(&portal::CursorMode::Metadata);
+    // The editable cursor was asked for and the portal cannot report the pointer
+    // (Hyprland's offers no METADATA): Hyprland's IPC can, so the pointer is kept out
+    // of the pixels (HIDDEN) and the editor draws it from these positions, or, where
+    // the portal cannot keep it out, it is painted in and the positions still place
+    // zooms. See `hyprland.rs`.
+    let hyprland_socket = (cursor_mode.reports_cursor()
+        && !cursor_metadata_supported
+        && output_path.is_some())
+    .then(hyprland::socket_path)
+    .flatten();
     // Resolved before anything reads it, so the portal, the click readers and
     // `ready` all see the mode that is really negotiated.
-    let cursor_mode = cursor_mode.resolve(&offered_cursor_modes, output_path.is_some());
+    let cursor_mode = cursor_mode.resolve(
+        &offered_cursor_modes,
+        output_path.is_some(),
+        hyprland_socket.is_some(),
+    );
     if !cursor_metadata_supported && cursor_mode.reports_cursor() {
         let error = portal::PortalError::CursorMetadataUnsupported;
         fail(&mut emitter, error.code(), &error.message());
@@ -311,9 +331,17 @@ fn main() {
         std::process::exit(0);
     }
 
+    let host_pointer_socket = hyprland_socket.filter(|_| !cursor_mode.reports_cursor());
+    // A HIDDEN pointer has to be drawn from these positions, which only a monitor can
+    // place: a window recorded that way would have no cursor at all.
+    let monitors_only = host_pointer_socket.is_some() && cursor_mode == portal::CursorMode::Hidden;
+
     let (sender, receiver) = mpsc::channel::<Message>();
     spawn_stdin_reader(sender.clone());
-    spawn_portal(sender.clone(), cursor_mode);
+    spawn_portal(sender.clone(), cursor_mode, monitors_only);
+    if let Some(socket) = host_pointer_socket.clone() {
+        hyprland::spawn_poller(sender.clone(), socket, sample_interval);
+    }
     // Left-button telemetry from evdev. Gated on the cursor mode FIRST: a session
     // that paints no cursor emits no samples to tag, so opening every pointer node
     // and blocking a thread on each would buy nothing. Warn only when the devices
@@ -321,7 +349,7 @@ fn main() {
     // which would recommend the permission they just declined — so a "clicks do
     // nothing on Linux" report is answerable from the log alone rather than
     // looking like a capture bug.
-    if cursor_mode.reports_cursor()
+    if (cursor_mode.reports_cursor() || host_pointer_socket.is_some())
         && input::spawn_readers(&sender) == input::ClickCapture::NoDevice
     {
         let _ = emitter.emit(&Event::Warning {
@@ -343,6 +371,7 @@ fn main() {
         cursor_mode,
         audio: request.audio_sources(),
         defer_start: request.defer_start,
+        host_pointer: host_pointer_socket,
     };
     let exit_code = run(&mut emitter, receiver, sender, session);
     std::process::exit(exit_code);
@@ -364,6 +393,9 @@ struct RunConfig {
     /// Wait for `record` on stdin before connecting to PipeWire. See
     /// [`Request::defer_start`].
     defer_start: bool,
+    /// Hyprland's request socket when the pointer's positions come from there
+    /// (`hyprland.rs`); it also places the granted monitor in the layout.
+    host_pointer: Option<PathBuf>,
 }
 
 /// Opens every requested audio stream, returning the live sessions (which must
@@ -525,9 +557,9 @@ fn spawn_stdin_reader(sender: Sender<Message>) {
 /// The portal runs on its own thread because `Start()` blocks on the user for
 /// an unbounded time, and a `stop` arriving during the picker must still be
 /// honoured.
-fn spawn_portal(sender: Sender<Message>, cursor_mode: portal::CursorMode) {
+fn spawn_portal(sender: Sender<Message>, cursor_mode: portal::CursorMode, monitors_only: bool) {
     std::thread::spawn(move || {
-        let result = pollster::block_on(portal::negotiate(cursor_mode));
+        let result = pollster::block_on(portal::negotiate(cursor_mode, monitors_only));
         let _ = sender.send(Message::Portal(Box::new(result)));
     });
 }
@@ -657,6 +689,11 @@ fn run<W: Write>(
     // What the portal granted, kept past the `StreamInfo` that is consumed at
     // Format: only a window stream is expected to carry a crop.
     let mut granted_kind: Option<portal::SourceKind> = None;
+    // The granted monitor's place in the global layout (position, logical size),
+    // from Hyprland, for positions that arrive from its IPC (`hyprland.rs`). None
+    // for a window, whose place the portal does not give.
+    let mut host_pointer_origin: Option<((i32, i32), (i32, i32))> = None;
+    let mut host_pointer_window_reported = false;
     // While a window's first usable crop rectangle is awaited: when the wait
     // began, and the latest crop-less frame, which starts the recording if the
     // wait runs out. See MAX_CROP_WAIT.
@@ -792,6 +829,44 @@ fn run<W: Write>(
                 }
             }
 
+            // Positions from the compositor's IPC, in global layout coordinates:
+            // placed into the monitor stream's pixels, then sampled exactly like the
+            // portal's own cursor metadata. There is no sprite to ship; the pointer
+            // is painted into the pixels.
+            Ok(Message::HostPointer(pointer)) => {
+                let Some(kind) = granted_kind else { continue };
+                let (Some((position, logical_size)), Some(pixel_size)) = (host_pointer_origin, size)
+                else {
+                    if kind == portal::SourceKind::Window && !host_pointer_window_reported {
+                        host_pointer_window_reported = true;
+                        let _ = emitter.emit(&Event::Warning {
+                            code: "cursor-positions-unavailable".to_owned(),
+                            message: "the portal does not say where a shared window is, so this \
+                                      recording has no cursor positions and no automatic zooms"
+                                .to_owned(),
+                        });
+                    }
+                    continue;
+                };
+                let placement = hyprland::MonitorPlacement { position, logical_size, pixel_size };
+                let Some((x, y)) = hyprland::to_stream_pixels(pointer, placement) else { continue };
+                cursor = Some(CursorState { x, y, asset_id: None });
+                if last_emit.elapsed() >= config.sample_interval {
+                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, None);
+                    last_emit = Instant::now();
+                }
+            }
+
+            Ok(Message::HostPointerLost(reason)) => {
+                let _ = emitter.emit(&Event::Warning {
+                    code: "cursor-positions-lost".to_owned(),
+                    message: format!(
+                        "the compositor stopped reporting the pointer ({reason}); no further cursor \
+                         positions will be recorded"
+                    ),
+                });
+            }
+
             // A reader lost its device (typically an unplug). Report it — if it
             // was the only pointer, clicks stop until one is (re)connected, which
             // the input watcher will pick up.
@@ -1098,6 +1173,39 @@ fn run<W: Write>(
                         position_y: stream.position.map(|(_, y)| y),
                     });
                     granted_kind = stream.source_kind;
+                    host_pointer_origin = match (&config.host_pointer, stream.source_kind) {
+                        (Some(socket), Some(portal::SourceKind::Monitor)) => {
+                            match hyprland::query_monitors(socket) {
+                                Ok(monitors) => {
+                                    let found = hyprland::granted_monitor(
+                                        &monitors,
+                                        stream.position,
+                                        stream.size,
+                                    );
+                                    if found.is_none() {
+                                        let _ = emitter.emit(&Event::Warning {
+                                            code: "cursor-positions-unavailable".to_owned(),
+                                            message: "could not tell which monitor the portal granted, \
+                                                      so this recording has no cursor positions"
+                                                .to_owned(),
+                                        });
+                                    }
+                                    found
+                                }
+                                Err(message) => {
+                                    let _ = emitter.emit(&Event::Warning {
+                                        code: "cursor-positions-unavailable".to_owned(),
+                                        message: format!(
+                                            "Hyprland did not describe its monitors ({message}), so \
+                                             this recording has no cursor positions"
+                                        ),
+                                    });
+                                    None
+                                }
+                            }
+                        }
+                        _ => None,
+                    };
 
                     if config.defer_start && !armed {
                         // Hold the grant WITHOUT connecting a pw_stream. mutter
diff --git a/electron/native/pipewire-capture/src/portal.rs b/electron/native/pipewire-capture/src/portal.rs
index e4c3dbaedf..d4f3db0285 100644
--- a/electron/native/pipewire-capture/src/portal.rs
+++ b/electron/native/pipewire-capture/src/portal.rs
@@ -78,7 +78,26 @@ impl CursorMode {
     /// session (`records_video` false) has no frames to paint into, so it keeps
     /// METADATA and is refused. Any other miss is returned unchanged, for the
     /// negotiation to refuse with its own error.
-    pub fn resolve(self, offered: &[CursorMode], records_video: bool) -> CursorMode {
+    ///
+    /// Before that last fallback, METADATA goes to HIDDEN when the compositor reports
+    /// the pointer itself (`host_reports_pointer`, Hyprland's IPC): the pointer stays
+    /// out of the pixels and the samples come from there, so the editor still draws
+    /// it, the editable cursor the user asked for. Only for a recording, which has
+    /// pixels to keep it out of.
+    pub fn resolve(
+        self,
+        offered: &[CursorMode],
+        records_video: bool,
+        host_reports_pointer: bool,
+    ) -> CursorMode {
+        if self == Self::Metadata
+            && records_video
+            && host_reports_pointer
+            && !offered.contains(&Self::Metadata)
+            && offered.contains(&Self::Hidden)
+        {
+            return Self::Hidden;
+        }
         if self == Self::Embedded
             && !offered.contains(&Self::Embedded)
             && offered.contains(&Self::Metadata)
@@ -229,7 +248,10 @@ pub async fn offered_cursor_modes() -> Result<Vec<CursorMode>, PortalError> {
 /// ashpd has no `Drop` impl for sessions and holds its D-Bus connection in a
 /// process-global `OnceLock`, so the portal session stays open until this
 /// process exits — which is exactly the lifetime we want.
-pub async fn negotiate(cursor_mode: CursorMode) -> Result<PortalStream, PortalError> {
+pub async fn negotiate(
+    cursor_mode: CursorMode,
+    monitors_only: bool,
+) -> Result<PortalStream, PortalError> {
     let proxy = Screencast::new().await.map_err(portal_unavailable)?;
 
     let cursor_modes = proxy
@@ -255,8 +277,15 @@ pub async fn negotiate(cursor_mode: CursorMode) -> Result<PortalStream, PortalEr
         .map_err(|error| failed("CreateSession", error))?;
 
     // Monitors and windows both; the picker decides which. Virtual sources are
-    // excluded — a virtual monitor has no cursor to report.
-    let types: BitFlags<SourceType> = SourceType::Monitor | SourceType::Window;
+    // excluded — a virtual monitor has no cursor to report. Monitors only when the
+    // pointer's positions come from the compositor (`monitors_only`): they can be
+    // placed in a monitor, never in a window the portal does not name, and a window
+    // recorded without the pointer in its pixels would have no cursor at all.
+    let types: BitFlags<SourceType> = if monitors_only {
+        SourceType::Monitor.into()
+    } else {
+        SourceType::Monitor | SourceType::Window
+    };
     proxy
         .select_sources(
             &session,
@@ -325,31 +354,43 @@ mod tests {
 
     #[test]
     fn embedded_falls_back_to_metadata_when_the_portal_lacks_it() {
-        assert_eq!(Embedded.resolve(&[Metadata, Hidden], true), Metadata);
-        assert_eq!(Embedded.resolve(&[Metadata, Hidden], false), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Hidden], true, false), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Hidden], false, false), Metadata);
     }
 
     #[test]
     fn metadata_falls_back_to_embedded_when_recording_video() {
         // xdg-desktop-portal-hyprland's offer.
-        assert_eq!(Metadata.resolve(&[Embedded, Hidden], true), Embedded);
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], true, false), Embedded);
     }
 
     #[test]
     fn a_cursor_only_session_keeps_metadata_for_negotiation_to_refuse() {
-        assert_eq!(Metadata.resolve(&[Embedded, Hidden], false), Metadata);
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], false, false), Metadata);
     }
 
     #[test]
     fn an_offered_mode_is_kept() {
-        assert_eq!(Embedded.resolve(&[Metadata, Embedded], true), Embedded);
-        assert_eq!(Metadata.resolve(&[Metadata, Embedded], true), Metadata);
-        assert_eq!(Metadata.resolve(&[Metadata], false), Metadata);
+        assert_eq!(Embedded.resolve(&[Metadata, Embedded], true, false), Embedded);
+        assert_eq!(Metadata.resolve(&[Metadata, Embedded], true, false), Metadata);
+        assert_eq!(Metadata.resolve(&[Metadata], false, false), Metadata);
+    }
+
+    #[test]
+    fn metadata_goes_hidden_when_the_compositor_reports_the_pointer() {
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], true, true), Hidden);
+        // Nothing to keep the pointer out of without video, and no HIDDEN to ask for.
+        assert_eq!(Metadata.resolve(&[Embedded, Hidden], false, true), Metadata);
+        assert_eq!(Metadata.resolve(&[Embedded], true, true), Embedded);
+        // A portal with METADATA reports the pointer itself.
+        assert_eq!(Metadata.resolve(&[Metadata, Hidden], true, true), Metadata);
+        // The system cursor stays painted in.
+        assert_eq!(Embedded.resolve(&[Embedded, Hidden], true, true), Embedded);
     }
 
     #[test]
     fn a_miss_without_a_fallback_is_left_for_negotiation_to_refuse() {
-        assert_eq!(Embedded.resolve(&[Hidden], true), Embedded);
-        assert_eq!(Metadata.resolve(&[Hidden], true), Metadata);
+        assert_eq!(Embedded.resolve(&[Hidden], true, false), Embedded);
+        assert_eq!(Metadata.resolve(&[Hidden], true, false), Metadata);
     }
 }
diff --git a/src/components/ai-edition/recordingImport.test.ts b/src/components/ai-edition/recordingImport.test.ts
index 4b1a314a66..97f5d8b1cb 100644
--- a/src/components/ai-edition/recordingImport.test.ts
+++ b/src/components/ai-edition/recordingImport.test.ts
@@ -57,12 +57,21 @@ function stubElectronApi(
 	screenVideoPath: string | null,
 	cursorCaptureMode: "editable-overlay" | "system" = "editable-overlay",
 	warning?: string,
+	pointerTelemetry?: boolean,
 ) {
 	let session: {
 		screenVideoPath: string;
 		createdAt: number;
 		cursorCaptureMode: "editable-overlay" | "system";
-	} | null = screenVideoPath ? { screenVideoPath, createdAt: 0, cursorCaptureMode } : null;
+		pointerTelemetry?: boolean;
+	} | null = screenVideoPath
+		? {
+				screenVideoPath,
+				createdAt: 0,
+				cursorCaptureMode,
+				...(pointerTelemetry ? { pointerTelemetry } : {}),
+			}
+		: null;
 	const api = {
 		getCurrentRecordingSession: vi.fn(async () =>
 			session ? { success: true, session, ...(warning ? { warning } : {}) } : { success: false },
@@ -341,6 +350,14 @@ describe("fresh-recording auto-zoom", () => {
 		expect(consumeFreshRecordingAutoZoomPending()).toBe(false);
 	});
 
+	// Linux on Hyprland: the pointer is painted in, but where it was and where it
+	// clicked is in `.pointer.json`, so there are clicks to find after all.
+	it("marks a system-cursor take that recorded pointer telemetry", async () => {
+		stubElectronApi("/home/user/Videos/recording-1.mp4", "system", undefined, true);
+		await importPendingRecording();
+		expect(consumeFreshRecordingAutoZoomPending()).toBe(true);
+	});
+
 	it("still marks an editable-cursor take from the same import path", async () => {
 		stubElectronApi("C:\\recordings\\recording-1.mp4", "editable-overlay");
 		await importPendingRecording();
diff --git a/src/components/ai-edition/recordingImport.ts b/src/components/ai-edition/recordingImport.ts
index b6b3e119ad..5c59ccd88f 100644
--- a/src/components/ai-edition/recordingImport.ts
+++ b/src/components/ai-edition/recordingImport.ts
@@ -350,8 +350,10 @@ export async function importPendingRecording(
 	// toggle stays on in prefs (it is only disabled in the UI while that mode is
 	// picked), so without this the flag is set for a recording that can never produce
 	// a click. What governs is the mode THIS take was recorded in, not the current
-	// preference.
-	if (cursorCaptureMode !== "system") {
+	// preference. A system take that recorded where the pointer was anyway
+	// (`pointerTelemetry`, Linux on Hyprland) can produce one, so it is marked too.
+	const pointerTelemetry = result.success && result.session?.pointerTelemetry === true;
+	if (cursorCaptureMode !== "system" || pointerTelemetry) {
 		markFreshRecordingAutoZoomPending(screenPath);
 	}
 	// Consumed: the recording now lives in a project. Cleared here rather than
diff --git a/src/lib/recordingSession.ts b/src/lib/recordingSession.ts
index 5fd06bc256..f877ebc0be 100644
--- a/src/lib/recordingSession.ts
+++ b/src/lib/recordingSession.ts
@@ -17,6 +17,13 @@ export type CursorCaptureMode = "editable-overlay" | "system";
 
 export interface RecordingSession extends ProjectMedia {
 	createdAt: number;
+	/**
+	 * A system-cursor take that still knows where the pointer was: it is painted into
+	 * the video, and its positions and clicks are in `<video>.pointer.json`, which feeds
+	 * auto-zoom but is never drawn (Linux on Hyprland, whose portal cannot leave the
+	 * pointer out of the pixels). Absent for every other take.
+	 */
+	pointerTelemetry?: boolean;
 }
 
 export interface RecordedVideoAssetInput {
@@ -97,5 +104,6 @@ export function normalizeRecordingSession(candidate: unknown): RecordingSession
 			typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
 				? raw.createdAt
 				: Date.now(),
+		...(raw.pointerTelemetry === true ? { pointerTelemetry: true } : {}),
 	};
 }

From a4382f895828ff3146715ae551f674c9f3e6a67d Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 09:39:19 -0700
Subject: [PATCH 07/27] fix(linux): poll Hyprland's pointer at a steady rate

The poller slept a full interval after each query, so its period drifted
past the sample interval, and the loop then dropped any position that
came in under it: about one gap in three was doubled, and a fast move
jumped twice as far in one step, which made the 3D cursor jitter.

The poller now runs at a fixed rate and stamps each position when it is
taken, every poll becomes a sample, and the idle heartbeat stays off
while Hyprland supplies positions. Measured on a real take: 371 of 373
gaps at 33 ms, none longer.
---
 .../native/pipewire-capture/src/hyprland.rs   | 38 ++++++---
 electron/native/pipewire-capture/src/main.rs  | 77 +++++++++++++++----
 2 files changed, 89 insertions(+), 26 deletions(-)

diff --git a/electron/native/pipewire-capture/src/hyprland.rs b/electron/native/pipewire-capture/src/hyprland.rs
index 5258705eed..d8497f45e1 100644
--- a/electron/native/pipewire-capture/src/hyprland.rs
+++ b/electron/native/pipewire-capture/src/hyprland.rs
@@ -21,10 +21,11 @@ use std::os::unix::net::UnixStream;
 use std::path::PathBuf;
 use std::sync::mpsc::Sender;
 use std::thread;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 use serde::Deserialize;
 
+use crate::events::timestamp_ms;
 use crate::Message;
 
 /// A request is one connection: Hyprland answers and closes, so a reply that
@@ -155,19 +156,36 @@ fn parse_cursor(reply: &str) -> Result<(f64, f64), String> {
 /// [`Message::HostPointerLost`]: a compositor that stopped answering will not
 /// start again within one recording, and retrying would flood the log.
 pub fn spawn_poller(sender: Sender<Message>, socket: PathBuf, interval: Duration) {
-    thread::spawn(move || loop {
-        match query_cursor(&socket) {
-            Ok(position) => {
-                if sender.send(Message::HostPointer(position)).is_err() {
-                    return; // the session is over
+    thread::spawn(move || {
+        // A fixed rate, not a sleep after each query: that drifted past the
+        // interval by the query's own time, and the spacing went uneven.
+        let mut next = Instant::now();
+        loop {
+            let taken_ms = timestamp_ms();
+            match query_cursor(&socket) {
+                Ok(position) => {
+                    if sender
+                        .send(Message::HostPointer(position, taken_ms))
+                        .is_err()
+                    {
+                        return; // the session is over
+                    }
+                }
+                Err(message) => {
+                    let _ = sender.send(Message::HostPointerLost(message));
+                    return;
                 }
             }
-            Err(message) => {
-                let _ = sender.send(Message::HostPointerLost(message));
-                return;
+            next += interval;
+            let now = Instant::now();
+            if next > now {
+                thread::sleep(next - now);
+            } else {
+                // Fell behind (a stalled compositor): resume from here rather
+                // than firing the missed polls back to back.
+                next = now;
             }
         }
-        thread::sleep(interval);
     });
 }
 
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index b83007a79a..831ce4b053 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -236,7 +236,7 @@ enum Message {
     PointerDeviceLost(String),
     /// The pointer in global layout coordinates, from the compositor's own IPC
     /// rather than the portal. See [`hyprland`] for when this is the source.
-    HostPointer((f64, f64)),
+    HostPointer((f64, f64), u64),
     /// The compositor IPC stopped answering; no further positions will arrive.
     HostPointerLost(String),
     /// Arm a deferred session: connect to PipeWire and start encoding.
@@ -825,7 +825,7 @@ fn run<W: Write>(
             // its message is delivered after the stream-state one.
             Ok(Message::PointerButton(press_ms)) => {
                 if streaming_since.is_some_and(|since| press_ms >= since) {
-                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, Some(press_ms));
+                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, SampleKind::Click(press_ms));
                 }
             }
 
@@ -833,7 +833,10 @@ fn run<W: Write>(
             // placed into the monitor stream's pixels, then sampled exactly like the
             // portal's own cursor metadata. There is no sprite to ship; the pointer
             // is painted into the pixels.
-            Ok(Message::HostPointer(pointer)) => {
+            // Every poll is a sample, stamped when it was taken: the poller already
+            // paces them, and throttling them again here dropped one in three, so
+            // a fast move jumped twice as far in one step.
+            Ok(Message::HostPointer(pointer, taken_ms)) => {
                 let Some(kind) = granted_kind else { continue };
                 let (Some((position, logical_size)), Some(pixel_size)) = (host_pointer_origin, size)
                 else {
@@ -851,10 +854,14 @@ fn run<W: Write>(
                 let placement = hyprland::MonitorPlacement { position, logical_size, pixel_size };
                 let Some((x, y)) = hyprland::to_stream_pixels(pointer, placement) else { continue };
                 cursor = Some(CursorState { x, y, asset_id: None });
-                if last_emit.elapsed() >= config.sample_interval {
-                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, None);
-                    last_emit = Instant::now();
-                }
+                emit_sample(
+                    emitter,
+                    &cursor,
+                    content_rect(&capture, size),
+                    &mut pending_asset,
+                    SampleKind::MoveAt(taken_ms),
+                );
+                last_emit = Instant::now();
             }
 
             Ok(Message::HostPointerLost(reason)) => {
@@ -1513,14 +1520,20 @@ fn run<W: Write>(
                 // A new sprite ships immediately; positions respect the sample
                 // interval so a 120fps compositor cannot flood stdout.
                 if asset_is_new || last_emit.elapsed() >= config.sample_interval {
-                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, None);
+                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, SampleKind::Move);
                     last_emit = Instant::now();
                 }
             }
 
             Err(RecvTimeoutError::Timeout) => {
-                if cursor.is_some() && last_emit.elapsed() >= config.sample_interval {
-                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, None);
+                // Not while the compositor's IPC is polled: those positions come at
+                // a steady rate, motionless or not, and a heartbeat between them only
+                // makes the spacing uneven.
+                if cursor.is_some()
+                    && config.host_pointer.is_none()
+                    && last_emit.elapsed() >= config.sample_interval
+                {
+                    emit_sample(emitter, &cursor, content_rect(&capture, size), &mut pending_asset, SampleKind::Move);
                     last_emit = Instant::now();
                 }
                 // No advance here: a timeout means a tick has passed, so the
@@ -1649,12 +1662,24 @@ fn content_rect(capture: &Option<Capture>, size: Option<(i32, i32)>) -> Option<s
 /// tagged `"click"` and stamped with that press time — or `None` for an ordinary
 /// throttled position sample stamped now. Either way a pending new sprite rides
 /// out on it.
+/// What a sample records, and so when it is stamped.
+#[derive(Debug, Clone, Copy)]
+enum SampleKind {
+    /// The latest position, stamped now.
+    Move,
+    /// A position stamped when it was taken: a poll of the compositor's IPC
+    /// (`hyprland.rs`), which reaches the loop a moment later.
+    MoveAt(u64),
+    /// A left-button press, stamped with the press time.
+    Click(u64),
+}
+
 fn emit_sample<W: Write>(
     emitter: &mut Emitter<W>,
     cursor: &Option<CursorState>,
     content: Option<shim::CropRect>,
     pending_asset: &mut Option<CursorAsset>,
-    click: Option<u64>,
+    kind: SampleKind,
 ) {
     let (Some(state), Some(content)) = (cursor, content) else {
         return;
@@ -1667,9 +1692,10 @@ fn emit_sample<W: Write>(
     // A click carries its own press time so the bounce lands when the button went
     // down, not up to a sample interval later; the position is the latest known,
     // which at the sample cadence has not moved enough to be wrong.
-    let (timestamp, interaction_type) = match click {
-        Some(press_ms) => (press_ms, Some("click".to_owned())),
-        None => (timestamp_ms(), None),
+    let (timestamp, interaction_type) = match kind {
+        SampleKind::Click(press_ms) => (press_ms, Some("click".to_owned())),
+        SampleKind::MoveAt(taken_ms) => (taken_ms, None),
+        SampleKind::Move => (timestamp_ms(), None),
     };
     let _ = emitter.emit(&Event::CursorSample {
         timestamp_ms: timestamp,
@@ -1760,7 +1786,7 @@ mod cursor_sample_tests {
             &Some(CursorState { x: cursor.0, y: cursor.1, asset_id: None }),
             content,
             &mut None,
-            None,
+            SampleKind::Move,
         );
         let line = String::from_utf8(buffer).expect("utf8");
         serde_json::from_str(line.trim()).expect("json")
@@ -1836,11 +1862,30 @@ mod cursor_sample_tests {
             &Some(CursorState { x: 10, y: 10, asset_id: None }),
             None,
             &mut None,
-            None,
+            SampleKind::Move,
         );
         assert!(buffer.is_empty(), "emitted {}", String::from_utf8_lossy(&buffer));
     }
 
+    /// A position polled from the compositor keeps the time it was taken, not the
+    /// moment the loop got round to it: uneven stamps make a fast move stutter.
+    #[test]
+    fn a_polled_position_is_stamped_when_it_was_taken() {
+        let mut buffer = Vec::new();
+        let mut emitter = Emitter::new(&mut buffer, false);
+        emit_sample(
+            &mut emitter,
+            &Some(CursorState { x: 10, y: 10, asset_id: None }),
+            Some(shim::CropRect { x: 0, y: 0, width: 100, height: 100 }),
+            &mut None,
+            SampleKind::MoveAt(1234),
+        );
+        let value: serde_json::Value =
+            serde_json::from_str(String::from_utf8(buffer).expect("utf8").trim()).expect("json");
+        assert_eq!(value["timestampMs"], 1234);
+        assert!(value.get("interactionType").is_none());
+    }
+
     /// #936: messages arriving faster than the tick must not hold the heartbeat
     /// off. The loop checks it on every pass, so what matters is that it comes
     /// due once a tick has passed, however many passes happened in between.

From 2a85ef81f65f121cb86a988a8953ef4735610282 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 07:57:32 -0700
Subject: [PATCH 08/27] fix(linux): size the HUD window to the bar alone

On Wayland the HUD's transparent reserve cannot be made click-through, and
Hyprland frames and blurs it, so the bar showed inside a large glass box.

- The Linux HUD window is now exactly the bar. Device settings, the
  language menu, notices and toasts move to a separate panel window
  (hudPanel.ts, HudPanelWindow.tsx) that the HUD drives over IPC.
- The bar's tooltips use native title tooltips on Linux, which Chromium
  draws outside the window, so no tooltip room is reserved.
- HUD_WINDOW_MIN drops to 40x40 so the floor no longer pads a bar-sized
  window; elsewhere the window is always far larger.
- On Wayland, force Chromium's device scale factor to 1: it folded the
  desktop's text-scaling factor into windows that size themselves and
  painted their page into only part of the window.
- On Hyprland, place the panel next to the bar through its IPC, since the
  compositor centres every new floating window over the bar.
---
 electron/electron-env.d.ts                    |  19 +
 electron/hudWindowBounds.ts                   |   8 +-
 electron/hyprland.test.ts                     | 207 +++++++
 electron/hyprland.ts                          | 168 ++++++
 electron/preload.ts                           |  32 ++
 electron/wayland.test.ts                      |  45 +-
 electron/wayland.ts                           |  19 +-
 electron/windows.ts                           | 200 +++++++
 src/App.tsx                                   |   5 +-
 src/components/launch/HudControls.tsx         |  10 +
 src/components/launch/HudPanelWindow.test.tsx | 191 +++++++
 src/components/launch/HudPanelWindow.tsx      | 184 ++++++
 src/components/launch/LaunchWindow.module.css |  10 +
 src/components/launch/LaunchWindow.test.tsx   | 132 +++++
 src/components/launch/LaunchWindow.tsx        | 527 ++++++++++++------
 src/components/launch/hudGeometry.test.ts     |  18 +
 src/components/launch/hudGeometry.ts          |  17 +
 src/components/launch/hudPanel.test.ts        |  59 ++
 src/components/launch/hudPanel.ts             | 135 +++++
 19 files changed, 1817 insertions(+), 169 deletions(-)
 create mode 100644 electron/hyprland.test.ts
 create mode 100644 electron/hyprland.ts
 create mode 100644 src/components/launch/HudPanelWindow.test.tsx
 create mode 100644 src/components/launch/HudPanelWindow.tsx
 create mode 100644 src/components/launch/hudPanel.test.ts
 create mode 100644 src/components/launch/hudPanel.ts

diff --git a/electron/electron-env.d.ts b/electron/electron-env.d.ts
index fc6b5f9118..342a133a19 100644
--- a/electron/electron-env.d.ts
+++ b/electron/electron-env.d.ts
@@ -517,6 +517,25 @@ interface Window {
 			width: number;
 			height: number;
 		}) => void;
+		/** Linux: what the HUD's floating surfaces show, for the panel window to render
+		 *  (src/components/launch/hudPanel.ts). An empty state hides the panel. */
+		sendHudPanelState: (state: import("../src/components/launch/hudPanel").HudPanelState) => void;
+		/** Linux: what the user did in the panel window, delivered to the HUD. */
+		onHudPanelAction: (
+			callback: (action: import("../src/components/launch/hudPanel").HudPanelAction) => void,
+		) => () => void;
+		/** The panel window's side of {@link sendHudPanelState}. */
+		onHudPanelState: (
+			callback: (state: import("../src/components/launch/hudPanel").HudPanelState) => void,
+		) => () => void;
+		/** The panel window asks for the current snapshot once it is listening for them. */
+		requestHudPanelState: () => void;
+		/** The panel window's side of {@link onHudPanelAction}. */
+		sendHudPanelAction: (
+			action: import("../src/components/launch/hudPanel").HudPanelAction,
+		) => void;
+		/** The panel window reports the size of what it shows; the window is sized to it. */
+		setHudPanelSize: (width: number, height: number) => void;
 		showCountdownOverlay: (value: number, runId: number) => Promise<void>;
 		setCountdownOverlayValue: (value: number, runId: number) => Promise<void>;
 		hideCountdownOverlay: (runId: number) => Promise<void>;
diff --git a/electron/hudWindowBounds.ts b/electron/hudWindowBounds.ts
index 071c89a109..7509a2aa47 100644
--- a/electron/hudWindowBounds.ts
+++ b/electron/hudWindowBounds.ts
@@ -24,8 +24,12 @@ import {
 	type EditorWindowRect,
 } from "./editorWindowState";
 
-/** The HUD's own floor, matching `minWidth`/`minHeight` at construction. */
-export const HUD_WINDOW_MIN = { width: 120, height: 80 };
+/**
+ * The HUD's own floor, matching `minWidth`/`minHeight` at construction. Below the bar's
+ * own thickness (about 54px), since on Linux the window is exactly the bar
+ * (computeHudLinuxWindowSize); elsewhere the window is always far larger than this.
+ */
+export const HUD_WINDOW_MIN = { width: 40, height: 40 };
 
 /**
  * The visible stack's rect relative to the window, as measured by the renderer:
diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
new file mode 100644
index 0000000000..58b73d6fe5
--- /dev/null
+++ b/electron/hyprland.test.ts
@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	hyprlandSocketPath,
+	monitorWorkArea,
+	panelPositionNearBar,
+	placeHudPanelNearBar,
+} from "./hyprland";
+
+const workArea = { x: 0, y: 22, width: 1920, height: 1058 };
+
+describe("panelPositionNearBar", () => {
+	it("centres the panel on the bar, just above it", () => {
+		const bar = { x: 672, y: 476, width: 576, height: 150 };
+		expect(panelPositionNearBar(bar, { width: 382, height: 300 }, workArea, 8)).toEqual({
+			x: 769,
+			y: 168,
+		});
+	});
+
+	it("goes below the bar when there is not room above it", () => {
+		const bar = { x: 672, y: 40, width: 576, height: 150 };
+		expect(panelPositionNearBar(bar, { width: 382, height: 300 }, workArea, 8)).toEqual({
+			x: 769,
+			y: 198,
+		});
+	});
+
+	it("stays inside the work area at a screen edge", () => {
+		const bar = { x: 1700, y: 900, width: 200, height: 150 };
+		expect(panelPositionNearBar(bar, { width: 382, height: 300 }, workArea, 8)).toEqual({
+			x: 1920 - 382,
+			y: 592,
+		});
+	});
+});
+
+describe("monitorWorkArea", () => {
+	it("is the monitor in logical px less what bars reserve", () => {
+		expect(
+			monitorWorkArea({
+				id: 0,
+				x: 1920,
+				y: 0,
+				width: 3072,
+				height: 1920,
+				scale: 2,
+				reserved: [0, 22, 0, 0],
+			}),
+		).toEqual({ x: 1920, y: 22, width: 1536, height: 938 });
+	});
+});
+
+describe("hyprlandSocketPath", () => {
+	it("is null outside a Hyprland session", () => {
+		expect(hyprlandSocketPath({ XDG_RUNTIME_DIR: "/run/user/1000" })).toBeNull();
+	});
+
+	it("points at the instance's request socket", () => {
+		expect(
+			hyprlandSocketPath({ XDG_RUNTIME_DIR: "/run/user/1000", HYPRLAND_INSTANCE_SIGNATURE: "abc" }),
+		).toBe("/run/user/1000/hypr/abc/.socket.sock");
+	});
+});
+
+describe("placeHudPanelNearBar", () => {
+	let server: net.Server | null = null;
+	let runtimeDir = "";
+
+	afterEach(async () => {
+		await new Promise<void>((resolve) => (server ? server.close(() => resolve()) : resolve()));
+		server = null;
+		if (runtimeDir) fs.rmSync(runtimeDir, { recursive: true, force: true });
+	});
+
+	/** A stand-in for Hyprland's request socket: one reply per command, recorded. */
+	async function fakeHyprland(replies: Record<string, string>) {
+		runtimeDir = fs.mkdtempSync(path.join(os.tmpdir(), "openscreen-hypr-"));
+		fs.mkdirSync(path.join(runtimeDir, "hypr", "sig"), { recursive: true });
+		const received: string[] = [];
+		server = net.createServer((socket) => {
+			socket.on("data", (chunk) => {
+				const command = chunk.toString("utf8");
+				received.push(command);
+				const key = command.startsWith("dispatch") ? "dispatch" : command;
+				socket.end(replies[key] ?? "unknown request");
+			});
+		});
+		const socketPath = path.join(runtimeDir, "hypr", "sig", ".socket.sock");
+		await new Promise<void>((resolve) => server?.listen(socketPath, resolve));
+		return { env: { XDG_RUNTIME_DIR: runtimeDir, HYPRLAND_INSTANCE_SIGNATURE: "sig" }, received };
+	}
+
+	const clients = JSON.stringify([
+		{
+			address: "0xbar",
+			pid: 42,
+			title: "openscreen",
+			at: [672, 476],
+			size: [576, 150],
+			monitor: 2,
+		},
+		{
+			address: "0xpanel",
+			pid: 42,
+			title: "OpenScreen panel",
+			at: [769, 306],
+			size: [382, 300],
+			monitor: 2,
+		},
+		{
+			address: "0xother",
+			pid: 7,
+			title: "OpenScreen panel",
+			at: [0, 0],
+			size: [10, 10],
+			monitor: 2,
+		},
+	]);
+	const monitors = JSON.stringify([
+		{ id: 2, x: 0, y: 0, width: 3840, height: 2160, scale: 2, reserved: [0, 22, 0, 0] },
+	]);
+
+	it("moves this process's panel above its bar", async () => {
+		const { env, received } = await fakeHyprland({
+			"j/clients": clients,
+			"j/monitors": monitors,
+			dispatch: "ok",
+		});
+
+		const placed = await placeHudPanelNearBar({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 576, height: 150 },
+			gap: 8,
+		});
+
+		expect(placed).toBe(true);
+		expect(received).toContain(
+			'dispatch hl.dsp.window.move({ x = 769, y = 168, window = "address:0xpanel" })',
+		);
+	});
+
+	it("falls back to the classic dispatcher on a Hyprland without Lua", async () => {
+		const { env, received } = await fakeHyprland({
+			"j/clients": clients,
+			"j/monitors": monitors,
+		});
+		// The fake answers both dispatch forms alike, so make only the classic one succeed.
+		server?.removeAllListeners("connection");
+		server?.on("connection", (socket) => {
+			socket.on("data", (chunk) => {
+				const command = chunk.toString("utf8");
+				received.push(command);
+				if (command === "j/clients") socket.end(clients);
+				else if (command === "j/monitors") socket.end(monitors);
+				else socket.end(command.startsWith("dispatch movewindowpixel") ? "ok" : "error: lua");
+			});
+		});
+
+		const placed = await placeHudPanelNearBar({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 576, height: 150 },
+			gap: 8,
+		});
+
+		expect(placed).toBe(true);
+		expect(received).toContain("dispatch movewindowpixel exact 769 168,address:0xpanel");
+	});
+
+	it("moves nothing when the bar is not among this process's windows", async () => {
+		const { env, received } = await fakeHyprland({
+			"j/clients": clients,
+			"j/monitors": monitors,
+			dispatch: "ok",
+		});
+
+		const placed = await placeHudPanelNearBar({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 999, height: 150 },
+			gap: 8,
+		});
+
+		expect(placed).toBe(false);
+		expect(received.some((command) => command.startsWith("dispatch"))).toBe(false);
+	});
+
+	it("gives up quietly outside Hyprland", async () => {
+		await expect(
+			placeHudPanelNearBar({
+				env: {},
+				pid: 42,
+				panelTitle: "OpenScreen panel",
+				barSize: { width: 576, height: 150 },
+				gap: 8,
+			}),
+		).resolves.toBe(false);
+	});
+});
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
new file mode 100644
index 0000000000..f7ba5f17b7
--- /dev/null
+++ b/electron/hyprland.ts
@@ -0,0 +1,168 @@
+// Hyprland: placing the HUD panel next to the bar, which Wayland gives a client no way to do.
+//
+// A toplevel cannot position itself on Wayland, and Hyprland centres every new floating window
+// on its monitor. The HUD bar starts centred too, so the panel (src/components/launch/hudPanel.ts)
+// opened on top of it, and a toast covered the very controls it was about. Hyprland's IPC socket
+// can move a window, so on Hyprland the panel is moved next to the bar after it maps. Best
+// effort only: anything unexpected leaves the window where the compositor put it.
+import net from "node:net";
+import path from "node:path";
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+export interface Rect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+interface HyprlandClient {
+	address: string;
+	pid: number;
+	title: string;
+	at: [number, number];
+	size: [number, number];
+	monitor: number;
+}
+
+interface HyprlandMonitor {
+	id: number;
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	scale: number;
+	/** Logical px taken by bars and docks: left, top, right, bottom. */
+	reserved: [number, number, number, number];
+}
+
+const IPC_TIMEOUT_MS = 500;
+
+/** The request socket of the Hyprland instance this process runs under, or null outside one. */
+export function hyprlandSocketPath(env: Env): string | null {
+	const signature = env.HYPRLAND_INSTANCE_SIGNATURE;
+	const runtimeDir = env.XDG_RUNTIME_DIR;
+	if (!signature || !runtimeDir) return null;
+	return path.join(runtimeDir, "hypr", signature, ".socket.sock");
+}
+
+/** One request over Hyprland's IPC socket; null on any failure, so callers simply give up. */
+function request(socketPath: string, command: string): Promise<string | null> {
+	return new Promise((resolve) => {
+		let reply = "";
+		const socket = net.createConnection(socketPath);
+		const done = (value: string | null) => {
+			socket.destroy();
+			resolve(value);
+		};
+		socket.setTimeout(IPC_TIMEOUT_MS, () => done(null));
+		socket.on("connect", () => socket.write(command));
+		socket.on("data", (chunk) => {
+			reply += chunk.toString("utf8");
+		});
+		socket.on("end", () => done(reply));
+		socket.on("error", () => done(null));
+	});
+}
+
+async function requestJson<T>(socketPath: string, command: string): Promise<T | null> {
+	const reply = await request(socketPath, `j/${command}`);
+	if (!reply) return null;
+	try {
+		return JSON.parse(reply) as T;
+	} catch {
+		return null;
+	}
+}
+
+/** A monitor's usable area in logical px: its size less the bars and docks reserved on it. */
+export function monitorWorkArea(monitor: HyprlandMonitor): Rect {
+	const [left, top, right, bottom] = monitor.reserved;
+	const width = monitor.width / monitor.scale;
+	const height = monitor.height / monitor.scale;
+	return {
+		x: monitor.x + left,
+		y: monitor.y + top,
+		width: width - left - right,
+		height: height - top - bottom,
+	};
+}
+
+/**
+ * Where the panel goes: centred on the bar, above it with `gap` between, or below it when there
+ * is not room above; then kept inside the work area.
+ */
+export function panelPositionNearBar(
+	bar: Rect,
+	panel: { width: number; height: number },
+	workArea: Rect,
+	gap: number,
+): { x: number; y: number } {
+	const above = bar.y - gap - panel.height;
+	const y = above >= workArea.y ? above : bar.y + bar.height + gap;
+	const x = bar.x + (bar.width - panel.width) / 2;
+	const clamp = (value: number, min: number, max: number) =>
+		Math.round(Math.min(Math.max(value, min), Math.max(min, max)));
+	return {
+		x: clamp(x, workArea.x, workArea.x + workArea.width - panel.width),
+		y: clamp(y, workArea.y, workArea.y + workArea.height - panel.height),
+	};
+}
+
+const toRect = (client: HyprlandClient): Rect => ({
+	x: client.at[0],
+	y: client.at[1],
+	width: client.size[0],
+	height: client.size[1],
+});
+
+/**
+ * Moves the panel window next to the bar. Both are found among this process's clients: the
+ * panel by its title, the bar by the size this process gave it. Resolves false when not under
+ * Hyprland or when anything does not match, in which case nothing was moved.
+ */
+export async function placeHudPanelNearBar(options: {
+	env: Env;
+	pid: number;
+	panelTitle: string;
+	barSize: { width: number; height: number };
+	gap: number;
+}): Promise<boolean> {
+	const socketPath = hyprlandSocketPath(options.env);
+	if (!socketPath) return false;
+	const [clients, monitors] = await Promise.all([
+		requestJson<HyprlandClient[]>(socketPath, "clients"),
+		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+	]);
+	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+
+	const ours = clients.filter((client) => client.pid === options.pid);
+	const panel = ours.find((client) => client.title === options.panelTitle);
+	const bar = ours.find(
+		(client) =>
+			client !== panel &&
+			client.size[0] === options.barSize.width &&
+			client.size[1] === options.barSize.height,
+	);
+	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
+	if (!panel || !bar || !monitor) return false;
+
+	const { x, y } = panelPositionNearBar(
+		toRect(bar),
+		{ width: panel.size[0], height: panel.size[1] },
+		monitorWorkArea(monitor),
+		options.gap,
+	);
+	if (x === panel.at[0] && y === panel.at[1]) return true;
+	// Hyprland 0.56 evaluates `dispatch` as Lua (hl.dsp.window.move); earlier releases only
+	// know the classic dispatcher. Each refuses the other's syntax, so try both in turn.
+	const target = `address:${panel.address}`;
+	for (const command of [
+		`dispatch hl.dsp.window.move({ x = ${x}, y = ${y}, window = "${target}" })`,
+		`dispatch movewindowpixel exact ${x} ${y},${target}`,
+	]) {
+		if ((await request(socketPath, command))?.trim() === "ok") return true;
+	}
+	return false;
+}
diff --git a/electron/preload.ts b/electron/preload.ts
index 23160bcaa8..2f52923c14 100644
--- a/electron/preload.ts
+++ b/electron/preload.ts
@@ -148,6 +148,38 @@ contextBridge.exposeInMainWorld("electronAPI", {
 	setHudOverlayContent: (content: { x: number; y: number; width: number; height: number }) => {
 		ipcRenderer.send("hud-overlay-content", content);
 	},
+	sendHudPanelState: (state: import("../src/components/launch/hudPanel").HudPanelState) => {
+		ipcRenderer.send("hud-panel-state", state);
+	},
+	onHudPanelAction: (
+		callback: (action: import("../src/components/launch/hudPanel").HudPanelAction) => void,
+	) => {
+		const listener = (
+			_event: Electron.IpcRendererEvent,
+			action: import("../src/components/launch/hudPanel").HudPanelAction,
+		) => callback(action);
+		ipcRenderer.on("hud-panel-action", listener);
+		return () => ipcRenderer.removeListener("hud-panel-action", listener);
+	},
+	onHudPanelState: (
+		callback: (state: import("../src/components/launch/hudPanel").HudPanelState) => void,
+	) => {
+		const listener = (
+			_event: Electron.IpcRendererEvent,
+			state: import("../src/components/launch/hudPanel").HudPanelState,
+		) => callback(state);
+		ipcRenderer.on("hud-panel-state", listener);
+		return () => ipcRenderer.removeListener("hud-panel-state", listener);
+	},
+	sendHudPanelAction: (action: import("../src/components/launch/hudPanel").HudPanelAction) => {
+		ipcRenderer.send("hud-panel-action", action);
+	},
+	requestHudPanelState: () => {
+		ipcRenderer.send("hud-panel-ready");
+	},
+	setHudPanelSize: (width: number, height: number) => {
+		ipcRenderer.send("hud-panel-set-size", width, height);
+	},
 	getSources: async (opts: Electron.SourcesOptions) => {
 		return await ipcRenderer.invoke("get-sources", opts);
 	},
diff --git a/electron/wayland.test.ts b/electron/wayland.test.ts
index 01624872d2..0ac0145d5d 100644
--- a/electron/wayland.test.ts
+++ b/electron/wayland.test.ts
@@ -6,7 +6,11 @@ describe("Wayland startup configuration", () => {
 		{ XDG_SESSION_TYPE: "wayland" },
 		{ WAYLAND_DISPLAY: "wayland-1" },
 	])("defaults to Wayland when the environment advertises a Wayland session: %j", (env) => {
-		const commandLine = { appendSwitch: vi.fn(), hasSwitch: vi.fn(() => false) };
+		const commandLine = {
+			appendSwitch: vi.fn(),
+			hasSwitch: vi.fn(() => false),
+			getSwitchValue: vi.fn(() => ""),
+		};
 		configureWaylandSupport(commandLine, env);
 		expect(commandLine.appendSwitch).toHaveBeenCalledWith("ozone-platform", "wayland");
 		expect(commandLine.appendSwitch).toHaveBeenCalledWith("disable-features", "Vulkan");
@@ -16,6 +20,7 @@ describe("Wayland startup configuration", () => {
 		const switches = new Map([["ozone-platform", platform]]);
 		const commandLine = {
 			hasSwitch: (name: string) => switches.has(name),
+			getSwitchValue: (name: string) => switches.get(name) ?? "",
 			appendSwitch: vi.fn((name: string, value?: string) => {
 				switches.set(name, value ?? "");
 			}),
@@ -31,10 +36,46 @@ describe("Wayland startup configuration", () => {
 	});
 
 	it.each([{}, { XDG_SESSION_TYPE: "x11" }])("leaves a non-Wayland session alone: %j", (env) => {
-		const commandLine = { appendSwitch: vi.fn(), hasSwitch: vi.fn(() => false) };
+		const commandLine = {
+			appendSwitch: vi.fn(),
+			hasSwitch: vi.fn(() => false),
+			getSwitchValue: vi.fn(() => ""),
+		};
 		configureWaylandSupport(commandLine, env);
 		expect(commandLine.appendSwitch).not.toHaveBeenCalled();
 	});
+
+	// The desktop's text scaling otherwise left every window the app sizes itself painted
+	// in only part of its surface (see configureWaylandSupport).
+	function fakeCommandLine(initial: Record<string, string> = {}) {
+		const switches = new Map(Object.entries(initial));
+		return {
+			switches,
+			hasSwitch: (name: string) => switches.has(name),
+			getSwitchValue: (name: string) => switches.get(name) ?? "",
+			appendSwitch: vi.fn((name: string, value?: string) => {
+				switches.set(name, value ?? "");
+			}),
+		};
+	}
+
+	it("pins the device scale factor to 1 on the Wayland backend", () => {
+		const commandLine = fakeCommandLine();
+		configureWaylandSupport(commandLine, { XDG_SESSION_TYPE: "wayland" });
+		expect(commandLine.switches.get("force-device-scale-factor")).toBe("1");
+	});
+
+	it("leaves the scale factor alone under Xwayland, where it is the whole HiDPI scale", () => {
+		const commandLine = fakeCommandLine({ "ozone-platform": "x11" });
+		configureWaylandSupport(commandLine, { XDG_SESSION_TYPE: "wayland" });
+		expect(commandLine.switches.has("force-device-scale-factor")).toBe(false);
+	});
+
+	it("never overrides a scale factor the user passed", () => {
+		const commandLine = fakeCommandLine({ "force-device-scale-factor": "1.5" });
+		configureWaylandSupport(commandLine, { XDG_SESSION_TYPE: "wayland" });
+		expect(commandLine.switches.get("force-device-scale-factor")).toBe("1.5");
+	});
 });
 
 describe("Wayland backend detection", () => {
diff --git a/electron/wayland.ts b/electron/wayland.ts
index c89e70da71..7c4f870fec 100644
--- a/electron/wayland.ts
+++ b/electron/wayland.ts
@@ -1,4 +1,4 @@
-type CommandLine = Pick<Electron.CommandLine, "appendSwitch" | "hasSwitch">;
+type CommandLine = Pick<Electron.CommandLine, "appendSwitch" | "hasSwitch" | "getSwitchValue">;
 type Env = Readonly<Record<string, string | undefined>>;
 
 export function isWaylandSession(env: Env): boolean {
@@ -36,4 +36,21 @@ export function configureWaylandSupport(commandLine: CommandLine, env: Env): voi
 	// GL/EGL path so DMA-BUF import works. (Chromium itself logs this suggestion:
 	// "'--ozone-platform=wayland' is not compatible with Vulkan ... disabling Vulkan".)
 	commandLine.appendSwitch("disable-features", "Vulkan");
+	// Chromium folds the desktop's text-scaling factor (GNOME's `text-scaling-factor`) into
+	// its device scale, on top of the output scale the compositor applies, and gets it wrong
+	// for a window that sizes ITSELF: given a size through setSize/setBounds, the window lays
+	// its page out in that many CSS px but paints them at the scaled ratio. With a factor of
+	// 0.818 on a scale-2 output (devicePixelRatio 1.625), every frameless window the app
+	// sizes to its content (the HUD, its panel, the countdown) showed its page in the
+	// top-left 81% and left the rest empty, which Hyprland framed and blurred like content.
+	// Measured with a fixed 400x200 window: 81% filled by default, 100% with the factor
+	// forced to 1. Forcing it replaces only the text-scaling part; the compositor's
+	// per-output scale still applies. Not under Xwayland, where this factor is the whole
+	// HiDPI scale, and never over an explicit factor.
+	if (
+		commandLine.getSwitchValue("ozone-platform") !== "x11" &&
+		!commandLine.hasSwitch("force-device-scale-factor")
+	) {
+		commandLine.appendSwitch("force-device-scale-factor", "1");
+	}
 }
diff --git a/electron/windows.ts b/electron/windows.ts
index 8db7d9cd4a..863933afa9 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -1,6 +1,11 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { app, BrowserWindow, ipcMain, screen } from "electron";
+import {
+	type HudPanelAction,
+	type HudPanelState,
+	hudPanelHasContent,
+} from "../src/components/launch/hudPanel";
 import {
 	fitEditorRect,
 	loadEditorWindowState,
@@ -20,6 +25,7 @@ import {
 	parseHudContentRect,
 	sameRect,
 } from "./hudWindowBounds";
+import { placeHudPanelNearBar } from "./hyprland";
 import { keepAlwaysOnTop, reassertAlwaysOnTop } from "./keepOnTop";
 import { followAcrossSpaces } from "./macSpaces";
 import { markSheetless } from "./messageBox";
@@ -544,8 +550,13 @@ export function createHudOverlayWindow(): BrowserWindow {
 			hudContentRect = null;
 			hudBarHome = null;
 			stopHudCursorPoll();
+			closeHudPanelWindow();
 		}
 	});
+	// The panel belongs to the bar: hidden with it, and its popovers closed when focus
+	// leaves the pair (see checkHudPanelFocus).
+	win.on("hide", () => hudPanelWindow?.hide());
+	win.on("blur", checkHudPanelFocus);
 
 	if (VITE_DEV_SERVER_URL) {
 		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=hud-overlay");
@@ -559,6 +570,195 @@ export function createHudOverlayWindow(): BrowserWindow {
 	return win;
 }
 
+// ---------------------------------------------------------------------------
+// Linux: the HUD's floating surfaces in a window of their own.
+//
+// On Wayland the HUD cannot have a transparent reserve that lets clicks through, cannot
+// place itself and cannot choose how it grows (src/components/launch/hudPanel.ts), so on
+// Linux the HUD window is just the bar and the device settings, the language menu, the
+// notices and the toasts are shown here instead. This window only renders a snapshot
+// the HUD sends and relays what the user does back to it; the HUD owns all of it.
+// ---------------------------------------------------------------------------
+
+let hudPanelWindow: BrowserWindow | null = null;
+/** The last snapshot from the HUD, replayed to a panel window once it has loaded. */
+let hudPanelState: HudPanelState | null = null;
+/** Gap between the bar and the panel, where the panel can be placed (X11, Hyprland). */
+const HUD_PANEL_GAP = 8;
+/** Fixed, so Hyprland's IPC can tell the panel from the bar (see placeHudPanelNearBar). */
+const HUD_PANEL_TITLE = "OpenScreen panel";
+let hudPanelPlacementTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * On Hyprland, moves the panel next to the bar: the compositor centres it on the monitor,
+ * which is where the bar starts too. Retried briefly, since a window that was just shown may
+ * not be in the compositor's client list yet. Elsewhere this resolves false and does nothing.
+ */
+function placeHudPanel(attempt = 0) {
+	if (hudPanelPlacementTimer) clearTimeout(hudPanelPlacementTimer);
+	hudPanelPlacementTimer = setTimeout(async () => {
+		hudPanelPlacementTimer = null;
+		if (!hudPanelWindow || hudPanelWindow.isDestroyed() || !hudPanelWindow.isVisible()) return;
+		const placed = await placeHudPanelNearBar({
+			env: process.env,
+			pid: process.pid,
+			panelTitle: HUD_PANEL_TITLE,
+			barSize: hudWindowSize,
+			gap: HUD_PANEL_GAP,
+		});
+		if (!placed && attempt < 4 && process.env.HYPRLAND_INSTANCE_SIGNATURE) {
+			placeHudPanel(attempt + 1);
+		}
+	}, 40);
+}
+
+function hudPanelHasPopover(state: HudPanelState | null): boolean {
+	return Boolean(state && (state.deviceSettings || state.languageMenu));
+}
+
+function sendToHud(action: HudPanelAction) {
+	if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
+		hudOverlayWindow.webContents.send("hud-panel-action", action);
+	}
+}
+
+/**
+ * A popover closes when the user leaves it, which here means leaving BOTH windows: moving
+ * from the bar into the panel blurs the bar, and that must not close what was just opened.
+ * Checked a tick after the blur, once the focus has landed wherever it is going.
+ */
+function checkHudPanelFocus() {
+	setTimeout(() => {
+		if (!hudPanelHasPopover(hudPanelState)) return;
+		const focused = BrowserWindow.getFocusedWindow();
+		if (focused && (focused === hudOverlayWindow || focused === hudPanelWindow)) return;
+		sendToHud({ kind: "close-popovers" });
+	}, 50);
+}
+
+function closeHudPanelWindow() {
+	hudPanelState = null;
+	if (hudPanelWindow && !hudPanelWindow.isDestroyed()) hudPanelWindow.destroy();
+	hudPanelWindow = null;
+}
+
+function createHudPanelWindow(): BrowserWindow {
+	const win = new BrowserWindow({
+		width: 380,
+		height: 200,
+		// The renderer reports its size before the first show (hud-panel-set-size).
+		show: false,
+		frame: false,
+		resizable: false,
+		alwaysOnTop: true,
+		skipTaskbar: true,
+		title: HUD_PANEL_TITLE,
+		backgroundColor: "#0f1115",
+		// No `parent`, deliberately: a compositor centres a child window over its parent,
+		// and centred over the bar it covered the bar entirely (Hyprland, measured). Without
+		// one it is placed like any new window, which most compositors keep clear of others.
+		webPreferences: {
+			preload: path.join(__dirname, "preload.mjs"),
+			additionalArguments: [ASSET_BASE_URL_ARG],
+			nodeIntegration: false,
+			contextIsolation: true,
+			backgroundThrottling: false,
+		},
+	});
+	keepAlwaysOnTop(win);
+	applyContentProtection(win, "HUD panel");
+	// The page's <title> would replace it, and the title is how Hyprland's IPC finds the panel.
+	win.on("page-title-updated", (event) => event.preventDefault());
+
+	win.on("blur", checkHudPanelFocus);
+	// Closed from outside (a compositor keybinding): nothing it showed is open any more.
+	win.on("closed", () => {
+		if (hudPanelWindow !== win) return;
+		hudPanelWindow = null;
+		if (hudPanelHasPopover(hudPanelState)) sendToHud({ kind: "close-popovers" });
+	});
+
+	if (VITE_DEV_SERVER_URL) {
+		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=hud-panel");
+	} else {
+		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
+			query: { windowType: "hud-panel" },
+		});
+	}
+	return win;
+}
+
+ipcMain.on("hud-panel-state", (event, state: HudPanelState) => {
+	if (!hudOverlayWindow || event.sender !== hudOverlayWindow.webContents) return;
+	const popoverOpened = !hudPanelHasPopover(hudPanelState) && hudPanelHasPopover(state);
+	hudPanelState = state;
+	if (!hudPanelHasContent(state)) {
+		if (hudPanelWindow && !hudPanelWindow.isDestroyed()) hudPanelWindow.hide();
+		return;
+	}
+	if (!hudPanelWindow || hudPanelWindow.isDestroyed()) {
+		hudPanelWindow = createHudPanelWindow();
+		return;
+	}
+	hudPanelWindow.webContents.send("hud-panel-state", state);
+	// A popover opening over a panel already showing notices or toasts takes the focus, as
+	// it would on first show (hud-panel-set-size).
+	if (popoverOpened && hudPanelWindow.isVisible()) hudPanelWindow.focus();
+});
+
+// The panel asks for the snapshot once it is listening, rather than being sent one on
+// did-finish-load: the renderer mounts after its translations load, which is later than
+// that, and a snapshot sent before the listener exists is lost.
+ipcMain.on("hud-panel-ready", (event) => {
+	const win = hudPanelWindow;
+	if (!win || win.isDestroyed() || event.sender !== win.webContents || !hudPanelState) return;
+	win.webContents.send("hud-panel-state", hudPanelState);
+});
+
+ipcMain.on("hud-panel-action", (event, action: HudPanelAction) => {
+	if (!hudPanelWindow || event.sender !== hudPanelWindow.webContents) return;
+	sendToHud(action);
+});
+
+ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
+	const win = hudPanelWindow;
+	if (!win || win.isDestroyed() || event.sender !== win.webContents) return;
+	if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return;
+	if (!hudPanelState || !hudPanelHasContent(hudPanelState)) return;
+	const size = { width: Math.ceil(width), height: Math.ceil(height) };
+	const [currentWidth, currentHeight] = win.getContentSize();
+	const resized = currentWidth !== size.width || currentHeight !== size.height;
+	if (resized) {
+		win.setContentSize(size.width, size.height);
+	}
+	// Above the bar where the platform honours a position (X11). Wayland ignores it and the
+	// compositor places the window, which is the point of having one.
+	const hud = hudOverlayWindow;
+	if (hud && !hud.isDestroyed() && !win.isVisible()) {
+		const bar = hud.getBounds();
+		const workArea = screen.getDisplayMatching(bar).workArea;
+		const x = Math.round(bar.x + (bar.width - size.width) / 2);
+		const y = bar.y - size.height - HUD_PANEL_GAP;
+		win.setPosition(
+			Math.min(Math.max(x, workArea.x), workArea.x + workArea.width - size.width),
+			Math.max(y, workArea.y),
+		);
+	}
+	if (!win.isVisible()) {
+		// A popover takes focus, so its keyboard handling works straight away; a notice or a
+		// toast appearing must not pull focus away from whatever the user is doing.
+		if (hudPanelHasPopover(hudPanelState)) {
+			win.show();
+		} else {
+			win.showInactive();
+		}
+		placeHudPanel();
+	} else if (resized) {
+		// Hyprland keeps a resized floating window centred where it was, off the bar's edge.
+		placeHudPanel();
+	}
+});
+
 /**
  * Main editor window. Starts maximised with a hidden title bar on macOS; not
  * always-on-top and appears in the taskbar/dock.
diff --git a/src/App.tsx b/src/App.tsx
index 681bb59939..fa34b0b881 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -6,6 +6,7 @@ import { installBrowserShims } from "./native/browserShim";
 installBrowserShims();
 
 import { CountdownOverlay } from "./components/launch/CountdownOverlay.tsx";
+import { HudPanelWindow } from "./components/launch/HudPanelWindow";
 import { LaunchWindow } from "./components/launch/LaunchWindow";
 import { NotesWindow } from "./components/launch/NotesWindow.tsx";
 import { SourceSelector } from "./components/launch/SourceSelector";
@@ -85,6 +86,8 @@ export default function App() {
 		switch (windowType) {
 			case "hud-overlay":
 				return <LaunchWindow />;
+			case "hud-panel":
+				return <HudPanelWindow />;
 			case "source-selector":
 				return <SourceSelector />;
 			case "countdown-overlay":
@@ -170,7 +173,7 @@ export default function App() {
 		<TooltipProvider>
 			{showNotes ? <NotesWindow /> : content}
 			{/* The HUD mounts its own, placed clear of the bar (LaunchWindow). */}
-			{windowType !== "hud-overlay" && <Toaster />}
+			{windowType !== "hud-overlay" && windowType !== "hud-panel" && <Toaster />}
 		</TooltipProvider>
 	);
 }
diff --git a/src/components/launch/HudControls.tsx b/src/components/launch/HudControls.tsx
index 2c5fa7df1f..95db360c7e 100644
--- a/src/components/launch/HudControls.tsx
+++ b/src/components/launch/HudControls.tsx
@@ -1,5 +1,6 @@
 import { Check, Languages, NotepadText, Settings } from "lucide-react";
 import {
+	cloneElement,
 	createContext,
 	memo,
 	type ReactElement,
@@ -50,6 +51,12 @@ const hudLockedClasses =
 const HudVerticalContext = createContext(false);
 export const HudLayoutProvider = HudVerticalContext.Provider;
 
+// On Linux the HUD window is just the bar (hudPanel.ts), so a tooltip drawn in the page has
+// nowhere to go. The native `title` tooltip is its own surface, drawn by Chromium outside
+// the window (a popup on Wayland, measured on Hyprland), so the bar uses that there.
+const HudNativeTooltipsContext = createContext(false);
+export const HudNativeTooltipsProvider = HudNativeTooltipsContext.Provider;
+
 // Keeps a tooltip off the window's own edge, where its shadow would be cut.
 const HUD_TOOLTIP_EDGE_PADDING = 8;
 
@@ -60,6 +67,7 @@ const HUD_TOOLTIP_EDGE_PADDING = 8;
 // right in the render that shows it, not one effect later) and added to the primitive's gap.
 function HudTooltip({ content, children }: { content: string; children: ReactElement }) {
 	const vertical = useContext(HudVerticalContext);
+	const native = useContext(HudNativeTooltipsContext);
 	const side = vertical ? "right" : "top";
 	const triggerRef = useRef<HTMLButtonElement | null>(null);
 	const [open, setOpen] = useState(false);
@@ -80,6 +88,8 @@ function HudTooltip({ content, children }: { content: string; children: ReactEle
 		setOpen(next);
 	};
 
+	if (native) return cloneElement(children, { title: content });
+
 	return (
 		<Tooltip
 			ref={triggerRef}
diff --git a/src/components/launch/HudPanelWindow.test.tsx b/src/components/launch/HudPanelWindow.test.tsx
new file mode 100644
index 0000000000..435799f367
--- /dev/null
+++ b/src/components/launch/HudPanelWindow.test.tsx
@@ -0,0 +1,191 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom";
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TooltipProvider } from "../ui/tooltip";
+import type { HudDeviceSettingsLabels } from "./HudDeviceSettings";
+import { HudPanelWindow } from "./HudPanelWindow";
+import { EMPTY_HUD_PANEL_STATE, type HudPanelAction, type HudPanelState } from "./hudPanel";
+
+vi.mock("../../hooks/useAudioLevelMeter", () => ({
+	useAudioLevelMeter: () => ({ level: 0 }),
+}));
+vi.mock("../../hooks/useCameraPreviewStream", () => ({
+	useCameraPreviewStream: () => ({ stream: null, error: null }),
+}));
+
+const labels: HudDeviceSettingsLabels = {
+	title: "Device settings",
+	close: "Close",
+	microphone: "Microphone",
+	camera: "Camera",
+	micLevel: "Input level",
+	micHint: "Speak to check",
+	noMicrophones: "No microphone found",
+	searching: "Searching...",
+	noCameras: "No camera found",
+	cameraUnavailable: "Camera unavailable",
+	preview: "Preview",
+	previewUnavailable: "Preview unavailable",
+	about: "About",
+	checkForUpdates: "Check for updates",
+	checkingForUpdates: "Checking…",
+	cameraQuality: "Camera quality",
+	cameraQualityOptions: { "1080p": "1080p", "1440p": "1440p", "2160p": "4K" },
+};
+
+class StubResizeObserver {
+	observe = vi.fn();
+	unobserve = vi.fn();
+	disconnect = vi.fn();
+}
+
+let pushState: ((state: HudPanelState) => void) | null;
+let sentActions: HudPanelAction[];
+
+beforeEach(() => {
+	vi.stubGlobal("ResizeObserver", StubResizeObserver);
+	pushState = null;
+	sentActions = [];
+	window.electronAPI = {
+		...window.electronAPI,
+		onHudPanelState: vi.fn((callback: (state: HudPanelState) => void) => {
+			pushState = callback;
+			return () => {
+				pushState = null;
+			};
+		}),
+		sendHudPanelAction: vi.fn((action: HudPanelAction) => {
+			sentActions.push(action);
+		}),
+		setHudPanelSize: vi.fn(),
+		requestHudPanelState: vi.fn(),
+	};
+});
+
+afterEach(() => {
+	cleanup();
+	vi.useRealTimers();
+	vi.unstubAllGlobals();
+});
+
+function renderPanel(state: HudPanelState) {
+	render(
+		<TooltipProvider>
+			<HudPanelWindow />
+		</TooltipProvider>,
+	);
+	act(() => pushState?.(state));
+}
+
+describe("HudPanelWindow", () => {
+	it("renders the device settings the HUD sent and sends a pick back as an action", () => {
+		const mic = { deviceId: "mic-2", label: "USB mic", groupId: "g" };
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			deviceSettings: {
+				showMicrophone: true,
+				micDevices: [{ deviceId: "mic-1", label: "Built-in", groupId: "g" }, mic],
+				cameraDevices: [],
+				activeMicId: "mic-1",
+				activeCameraId: undefined,
+				cameraLoading: false,
+				cameraError: null,
+				labels,
+				versionLabel: "Version 2.1.2",
+				canCheckForUpdates: false,
+				checkingForUpdates: false,
+				cameraQuality: "1080p",
+			},
+		});
+
+		expect(screen.getByTestId("hud-device-settings")).toBeInTheDocument();
+		fireEvent.click(screen.getByText("USB mic"));
+		expect(sentActions).toContainEqual({ kind: "select-mic", device: mic });
+
+		fireEvent.click(screen.getByRole("button", { name: "Close" }));
+		expect(sentActions).toContainEqual({ kind: "close-device-settings" });
+	});
+
+	it("sends a notice's choice back with the notice's id", () => {
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			notices: [
+				{
+					id: "system-locale",
+					title: "Use French?",
+					description: "Your system is set to French.",
+					dismissLabel: "Keep English",
+					confirmLabel: "Switch",
+				},
+			],
+		});
+
+		fireEvent.click(screen.getByRole("button", { name: "Switch" }));
+		expect(sentActions).toEqual([{ kind: "notice", id: "system-locale", choice: "confirm" }]);
+	});
+
+	it("reports its size on every snapshot, so a hidden panel is shown again", () => {
+		vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+			width: 380.2,
+			height: 140.6,
+		} as DOMRect);
+		renderPanel(EMPTY_HUD_PANEL_STATE);
+		const sizeMock = window.electronAPI.setHudPanelSize as unknown as ReturnType<typeof vi.fn>;
+		sizeMock.mockClear();
+
+		act(() =>
+			pushState?.({
+				...EMPTY_HUD_PANEL_STATE,
+				toasts: [{ id: 1, type: "default", title: "Saved" }],
+			}),
+		);
+
+		expect(sizeMock).toHaveBeenCalledWith(381, 141);
+		vi.restoreAllMocks();
+	});
+
+	it("asks for the current snapshot once it is listening, so none is lost to a late mount", () => {
+		renderPanel(EMPTY_HUD_PANEL_STATE);
+		expect(window.electronAPI.requestHudPanelState).toHaveBeenCalledTimes(1);
+	});
+
+	it("closes popovers on Escape", () => {
+		renderPanel(EMPTY_HUD_PANEL_STATE);
+		fireEvent.keyDown(window, { key: "Escape" });
+		expect(sentActions).toEqual([{ kind: "close-popovers" }]);
+	});
+
+	it("times a toast out itself and reports the dismissal, since the HUD runs no toaster", () => {
+		vi.useFakeTimers();
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			toasts: [{ id: "fail", type: "error", title: "Recording failed", duration: 5000 }],
+		});
+		expect(screen.getByRole("alert")).toHaveTextContent("Recording failed");
+
+		act(() => vi.advanceTimersByTime(4999));
+		expect(sentActions).toEqual([]);
+		act(() => vi.advanceTimersByTime(1));
+		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "fail" }]);
+	});
+
+	it("keeps a loading toast until the HUD replaces or dismisses it", () => {
+		vi.useFakeTimers();
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			toasts: [{ id: "save", type: "loading", title: "Saving…" }],
+		});
+		act(() => vi.advanceTimersByTime(60_000));
+		expect(sentActions).toEqual([]);
+	});
+
+	it("sends a toast's action back to the HUD", () => {
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			toasts: [{ id: "perm", type: "warning", title: "Needs a permission", actionLabel: "Open" }],
+		});
+		fireEvent.click(screen.getByRole("button", { name: "Open" }));
+		expect(sentActions).toEqual([{ kind: "toast-action", id: "perm" }]);
+	});
+});
diff --git a/src/components/launch/HudPanelWindow.tsx b/src/components/launch/HudPanelWindow.tsx
new file mode 100644
index 0000000000..9f35c2d001
--- /dev/null
+++ b/src/components/launch/HudPanelWindow.tsx
@@ -0,0 +1,184 @@
+import { X } from "lucide-react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Button } from "../ui/button";
+import { HudLanguageMenu, HudNotice } from "./HudControls";
+import { HudDeviceSettings } from "./HudDeviceSettings";
+import { HUD_MODAL_MAX_HEIGHT, HUD_POPOVER_MAX_HEIGHT } from "./hudGeometry";
+import {
+	EMPTY_HUD_PANEL_STATE,
+	type HudPanelAction,
+	type HudPanelState,
+	type HudPanelToast,
+} from "./hudPanel";
+import styles from "./LaunchWindow.module.css";
+
+/** Padding around the stack, so the cards' rounded corners keep clear of the window edge. */
+const PANEL_PADDING = 10;
+/** Sonner's default, for a toast that names no duration of its own. */
+const DEFAULT_TOAST_DURATION_MS = 4000;
+
+const send = (action: HudPanelAction) => window.electronAPI?.sendHudPanelAction?.(action);
+const noop = () => undefined;
+
+/**
+ * One mirrored toast. The HUD owns the toast (sonner's store); this card owns its timer,
+ * since the HUD mounts no toaster on Linux to run one, and reports the dismissal back.
+ */
+function HudPanelToastCard({ toast }: { toast: HudPanelToast }) {
+	const { id, duration, type } = toast;
+	useEffect(() => {
+		if (type === "loading") return;
+		const ms = duration ?? DEFAULT_TOAST_DURATION_MS;
+		if (!Number.isFinite(ms)) return;
+		const timer = window.setTimeout(() => send({ kind: "toast-dismiss", id }), ms);
+		return () => window.clearTimeout(timer);
+	}, [id, duration, type]);
+
+	const accent =
+		type === "error"
+			? "border-l-[#ef4444]"
+			: type === "warning"
+				? "border-l-[#f59e0b]"
+				: type === "success"
+					? "border-l-[#10b981]"
+					: "border-l-white/20";
+
+	return (
+		<div
+			role={type === "error" ? "alert" : "status"}
+			data-testid="hud-panel-toast"
+			className={`${styles.hudNotice} w-full border-l-4 ${accent} p-3 text-white`}
+		>
+			<div className="flex items-start gap-2">
+				<div className="min-w-0 flex-1">
+					<div className="text-[13.5px] font-semibold text-white">{toast.title}</div>
+					{toast.description && (
+						<div className="mt-1 text-[12.5px] leading-relaxed text-white/75">
+							{toast.description}
+						</div>
+					)}
+				</div>
+				<button
+					type="button"
+					aria-label="Dismiss"
+					onClick={() => send({ kind: "toast-dismiss", id })}
+					className="rounded-md p-1 text-white/60 hover:bg-white/10 hover:text-white"
+				>
+					<X size={14} />
+				</button>
+			</div>
+			{toast.actionLabel && (
+				<div className="mt-2 flex justify-end">
+					<Button
+						type="button"
+						size="sm"
+						onClick={() => send({ kind: "toast-action", id })}
+						className="h-8 rounded-[9px] bg-[#10b981] text-[13px] font-semibold text-[#08090d] hover:bg-[#10b981]/85"
+					>
+						{toast.actionLabel}
+					</Button>
+				</div>
+			)}
+		</div>
+	);
+}
+
+/**
+ * The Linux HUD's floating surfaces, in their own window: see hudPanel.ts for why. A view
+ * of the snapshot the HUD sends, with every control wired back to the HUD as an action.
+ */
+export function HudPanelWindow() {
+	const [state, setState] = useState<HudPanelState>(EMPTY_HUD_PANEL_STATE);
+	const rootRef = useRef<HTMLDivElement | null>(null);
+
+	useEffect(() => {
+		const unsubscribe = window.electronAPI?.onHudPanelState?.(setState);
+		window.electronAPI?.requestHudPanelState?.();
+		return unsubscribe;
+	}, []);
+
+	useEffect(() => {
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") send({ kind: "close-popovers" });
+		};
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, []);
+
+	// The window is sized to the stack, so it is never bigger than what it shows.
+	const reportSize = useCallback(() => {
+		const root = rootRef.current;
+		if (!root) return;
+		const { width, height } = root.getBoundingClientRect();
+		if (width > 0 && height > 0) {
+			window.electronAPI?.setHudPanelSize?.(Math.ceil(width), Math.ceil(height));
+		}
+	}, []);
+	useLayoutEffect(() => {
+		const root = rootRef.current;
+		if (!root) return;
+		const observer = new ResizeObserver(reportSize);
+		observer.observe(root);
+		reportSize();
+		return () => observer.disconnect();
+	}, [reportSize]);
+	// Also on every snapshot: a hidden panel is shown again by its next size report, and
+	// content of the same size as last time would otherwise never send one.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `state` is the trigger, not an input.
+	useLayoutEffect(() => reportSize(), [state, reportSize]);
+
+	const { deviceSettings, languageMenu, notices, toasts } = state;
+	const names = languageMenu?.names;
+	const getName = useCallback((locale: string) => names?.[locale] ?? locale, [names]);
+
+	return (
+		<div
+			ref={rootRef}
+			data-testid="hud-panel"
+			className="flex w-max flex-col items-stretch gap-[10px]"
+			style={
+				{
+					padding: PANEL_PADDING,
+					"--hud-popover-max-h": `${HUD_POPOVER_MAX_HEIGHT}px`,
+					"--hud-modal-max-h": `${HUD_MODAL_MAX_HEIGHT}px`,
+				} as React.CSSProperties
+			}
+		>
+			{deviceSettings && (
+				<HudDeviceSettings
+					{...deviceSettings}
+					onSelectCameraQuality={(quality) => send({ kind: "select-camera-quality", quality })}
+					onSelectMic={(device) => send({ kind: "select-mic", device })}
+					onSelectCamera={(device) => send({ kind: "select-camera", device })}
+					onCheckForUpdates={() => send({ kind: "check-for-updates" })}
+					onClose={() => send({ kind: "close-device-settings" })}
+					panelRef={noop}
+				/>
+			)}
+			{languageMenu && (
+				<HudLanguageMenu
+					locales={languageMenu.locales}
+					activeLocale={languageMenu.activeLocale}
+					getName={getName}
+					onSelect={(locale) => send({ kind: "select-locale", locale })}
+					panelRef={noop}
+					onEnsureInteractive={noop}
+				/>
+			)}
+			{notices.map((notice) => (
+				<HudNotice
+					key={notice.id}
+					title={notice.title}
+					description={notice.description}
+					dismissLabel={notice.dismissLabel}
+					confirmLabel={notice.confirmLabel}
+					onDismiss={() => send({ kind: "notice", id: notice.id, choice: "dismiss" })}
+					onConfirm={() => send({ kind: "notice", id: notice.id, choice: "confirm" })}
+				/>
+			))}
+			{toasts.map((toast) => (
+				<HudPanelToastCard key={toast.id} toast={toast} />
+			))}
+		</div>
+	);
+}
diff --git a/src/components/launch/LaunchWindow.module.css b/src/components/launch/LaunchWindow.module.css
index 0f522b32ef..391daed352 100644
--- a/src/components/launch/LaunchWindow.module.css
+++ b/src/components/launch/LaunchWindow.module.css
@@ -34,6 +34,16 @@
 	pointer-events: none;
 }
 
+/* Linux: the window is exactly the bar (computeHudLinuxWindowSize), so the bar fills it.
+   max-content keeps a bar that just changed orientation at its own size while the window
+   still has the previous one, rather than squeezed into it, so it measures true. */
+.hudAnchorFill {
+	bottom: 0;
+	left: 0;
+	transform: none;
+	width: max-content;
+}
+
 .hudAbove {
 	display: flex;
 	flex-direction: column-reverse;
diff --git a/src/components/launch/LaunchWindow.test.tsx b/src/components/launch/LaunchWindow.test.tsx
index 8cd92de957..7b7d7e9357 100644
--- a/src/components/launch/LaunchWindow.test.tsx
+++ b/src/components/launch/LaunchWindow.test.tsx
@@ -16,6 +16,7 @@ import {
 	HUD_TOAST_WIDTH,
 	HUD_UNREPORTED_PANELS_ALLOWANCE,
 } from "./hudGeometry";
+import type { HudPanelAction, HudPanelState } from "./hudPanel";
 import { LaunchWindow } from "./LaunchWindow";
 
 type SelectedSourceChangedListener = Parameters<
@@ -2374,3 +2375,134 @@ describe("LaunchWindow toasts", () => {
 		});
 	});
 });
+
+/**
+ * Linux: the HUD window is just the bar, and everything that floats is handed to the panel
+ * window as a snapshot (hudPanel.ts). Wayland cannot make a transparent reserve
+ * click-through, so the reserve showed as a framed box that swallowed clicks.
+ */
+describe("LaunchWindow on Linux (floating surfaces in the panel window)", () => {
+	let sentStates: HudPanelState[];
+	let deliverAction: ((action: HudPanelAction) => void) | null;
+
+	beforeEach(() => {
+		platformState.value = "linux";
+		resetLaunchMocks();
+		resizeCallbacks.length = 0;
+		vi.stubGlobal("ResizeObserver", CapturingResizeObserver);
+		sentStates = [];
+		deliverAction = null;
+		window.electronAPI.sendHudPanelState = vi.fn((state: HudPanelState) => {
+			sentStates.push(state);
+		});
+		window.electronAPI.onHudPanelAction = vi.fn((callback: (action: HudPanelAction) => void) => {
+			deliverAction = callback;
+			return () => {
+				deliverAction = null;
+			};
+		});
+	});
+
+	afterEach(() => {
+		cleanup();
+		vi.unstubAllGlobals();
+		toast.dismiss();
+	});
+
+	const lastState = () => sentStates[sentStates.length - 1];
+
+	it("sizes the window to the bar alone, with the bar filling it", async () => {
+		renderLaunchWindow();
+		const bar = (await screen.findByTestId("hud-drag-handle")).closest(
+			"[data-tray-layout]",
+		) as HTMLElement;
+		stubBox(bar, 400, 56);
+		await flushResizeObservers();
+
+		expect(lastRequestedHudSize()).toEqual([400, 56, { x: 0, y: 0, width: 400, height: 56 }]);
+	});
+
+	it("uses native tooltips, which Chromium draws outside the bar-sized window", async () => {
+		renderLaunchWindow();
+
+		const button = await screen.findByTestId("launch-tray-layout-button");
+		expect(button).toHaveAttribute("title");
+		expect(button.getAttribute("title")).not.toBe("");
+	});
+
+	it("hands the device settings to the panel window instead of drawing them over the bar", async () => {
+		renderLaunchWindow();
+
+		fireEvent.click(await screen.findByTestId("launch-device-settings-button"));
+
+		await waitFor(() => expect(lastState()?.deviceSettings).not.toBeNull());
+		expect(screen.queryByTestId("hud-device-settings")).toBeNull();
+
+		act(() => deliverAction?.({ kind: "close-device-settings" }));
+		await waitFor(() => expect(lastState()?.deviceSettings).toBeNull());
+	});
+
+	it("runs a language picked in the panel through the HUD's own handler", async () => {
+		renderLaunchWindow();
+
+		fireEvent.click(await screen.findByRole("button", { name: "Language: English" }));
+		await waitFor(() => expect(lastState()?.languageMenu).not.toBeNull());
+		expect(screen.queryByTestId("hud-language-menu")).toBeNull();
+
+		act(() => deliverAction?.({ kind: "select-locale", locale: "fr" }));
+
+		expect(i18nState.value.setLocale).toHaveBeenCalledWith("fr");
+		await waitFor(() => expect(lastState()?.languageMenu).toBeNull());
+	});
+
+	it("keeps a popover open when the HUD window loses focus to the panel", async () => {
+		renderLaunchWindow();
+
+		fireEvent.click(await screen.findByTestId("launch-device-settings-button"));
+		await waitFor(() => expect(lastState()?.deviceSettings).not.toBeNull());
+
+		act(() => {
+			window.dispatchEvent(new Event("blur"));
+		});
+
+		expect(lastState()?.deviceSettings).not.toBeNull();
+	});
+
+	it("mirrors toasts to the panel and dismisses them when the panel says so", async () => {
+		renderLaunchWindow();
+		await screen.findByTestId("hud-drag-handle");
+		expect(screen.queryByTestId("hud-toaster")).toBeNull();
+
+		act(() => {
+			toast.error("Recording failed", { id: "fail" });
+		});
+		await waitFor(() =>
+			expect(lastState()?.toasts).toEqual([
+				expect.objectContaining({ id: "fail", type: "error", title: "Recording failed" }),
+			]),
+		);
+
+		act(() => deliverAction?.({ kind: "toast-dismiss", id: "fail" }));
+		await waitFor(() => expect(lastState()?.toasts).toEqual([]));
+	});
+
+	it("runs a toast's action from the panel, then dismisses it", async () => {
+		const onClick = vi.fn();
+		renderLaunchWindow();
+		await screen.findByTestId("hud-drag-handle");
+
+		act(() => {
+			toast.warning("Needs a permission", { id: "perm", action: { label: "Open", onClick } });
+		});
+		await waitFor(() =>
+			expect(lastState()?.toasts).toEqual([
+				expect.objectContaining({ id: "perm", actionLabel: "Open" }),
+			]),
+		);
+
+		act(() => deliverAction?.({ kind: "toast-action", id: "perm" }));
+
+		expect(onClick).toHaveBeenCalledTimes(1);
+		await waitFor(() => expect(lastState()?.toasts).toEqual([]));
+	});
+});
diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index d4b402b841..22f1aa9521 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { toast, useSonner } from "sonner";
 import { useI18n, useScopedT } from "@/contexts/I18nContext";
 import { getAvailableLocales, getLocaleName } from "@/i18n/loader";
 import { offersEditableCursor } from "@/lib/editableCursorAvailability";
@@ -28,6 +29,7 @@ import {
 	HudLanguageMenu,
 	HudLayoutProvider,
 	HudMicButton,
+	HudNativeTooltipsProvider,
 	HudNotesButton,
 	HudNotice,
 	HudRecordButton,
@@ -44,6 +46,7 @@ import {
 	addHudToastsToStack,
 	computeHudAvailableHeight,
 	computeHudBarMaxHeight,
+	computeHudLinuxWindowSize,
 	computeHudModalMaxHeight,
 	computeHudPopoverMaxHeight,
 	computeHudToastBottom,
@@ -54,6 +57,13 @@ import {
 	HUD_POPOVER_GAP,
 	HUD_STACK_GAP,
 } from "./hudGeometry";
+import {
+	EMPTY_HUD_PANEL_STATE,
+	type HudPanelAction,
+	type HudPanelNotice,
+	type HudPanelState,
+	toHudPanelToasts,
+} from "./hudPanel";
 import styles from "./LaunchWindow.module.css";
 
 // Locale list is computed once at module load; keeping the reference stable lets
@@ -151,6 +161,10 @@ export function LaunchWindow() {
 	// cursor toggle is only shown once it is known to change something.
 	const [supportsCursorModeToggle, setSupportsCursorModeToggle] = useState(false);
 	const [isLinuxHud, setIsLinuxHud] = useState(false);
+	// On Linux everything that floats above the bar is shown in a window of its own and this
+	// one is just the bar (hudPanel.ts). Decided synchronously, unlike `isLinuxHud`, so the
+	// very first measurement already sizes the window to the bar.
+	const [floatsInPanel] = useState(() => getPlatform() === "linux");
 	// The running version, and whether this copy may offer an update check at all — a
 	// Store/Flathub/Snap/Nix install is kept current by its package manager and is offered
 	// nothing (electron/install-channel.ts). Asked once: neither answer changes while the app
@@ -364,14 +378,18 @@ export function LaunchWindow() {
 		// that has no focus" state simply doesn't exist. Bubble phase on purpose:
 		// element blur doesn't bubble, so this only ever fires for the window itself
 		// and never when focus moves between the menu's own buttons.
-		window.addEventListener("blur", closePopovers);
+		//
+		// Not on Linux, where the popover is in the panel window: focus moving into it blurs
+		// this one, and closing then would close the popover the user is reaching for. The
+		// main process closes it once focus has left both windows (checkHudPanelFocus).
+		if (!floatsInPanel) window.addEventListener("blur", closePopovers);
 
 		return () => {
 			window.removeEventListener("pointerdown", handlePointerDown);
 			window.removeEventListener("keydown", handleEscape);
 			window.removeEventListener("blur", closePopovers);
 		};
-	}, [closePopovers, isPopoverOpen, isLanguageMenuOpen]);
+	}, [closePopovers, floatsInPanel, isPopoverOpen, isLanguageMenuOpen]);
 
 	// ---------------------------------------------------------------------------
 	// Overlay window sizing
@@ -421,6 +439,31 @@ export function LaunchWindow() {
 		const barRect = barEl.getBoundingClientRect();
 		const barWidth = barRect.width || barEl.scrollWidth;
 		const barHeight = barRect.height || barEl.scrollHeight;
+
+		if (floatsInPanel) {
+			// Just the bar: nothing floats in this window on Linux, so there is no reserve, no
+			// hysteresis and no stack to keep on screen. A resize whenever the bar's size changes
+			// costs nothing here, since Wayland places the window wherever the compositor wants.
+			const size = computeHudLinuxWindowSize({ barWidth, barHeight, availableHeight });
+			const allocated = hudAllocatedSizeRef.current;
+			if (
+				allocated.orientation === trayLayout &&
+				allocated.width === size.width &&
+				allocated.height === size.height
+			) {
+				return;
+			}
+			allocated.orientation = trayLayout;
+			allocated.width = size.width;
+			allocated.height = size.height;
+			window.electronAPI.setHudOverlaySize(size.width, size.height, {
+				x: 0,
+				y: 0,
+				width: barWidth,
+				height: barHeight,
+			});
+			return;
+		}
 		const noticeEl = hudNoticesRef.current;
 		const noticeHeight = noticeEl
 			? noticeEl.getBoundingClientRect().height || noticeEl.scrollHeight
@@ -517,7 +560,7 @@ export function LaunchWindow() {
 		allocated.height = granted.height;
 		lastSentHudContentRef.current = grantedContent;
 		window.electronAPI.setHudOverlaySize(granted.width, granted.height, grantedContent);
-	}, [trayLayout]);
+	}, [floatsInPanel, trayLayout]);
 
 	// One persistent observer; elements wire themselves up via callback refs as
 	// they mount/unmount. The bar and the notice column size the window; the anchor
@@ -1174,6 +1217,156 @@ export function LaunchWindow() {
 
 	const hasNotices = Boolean(systemLocaleSuggestion) || softwareEncoderFallbackNoticeVisible;
 
+	// Linux: what floats above the bar elsewhere, as a snapshot for the panel window
+	// (hudPanel.ts), built from exactly what the stack below renders on the other platforms.
+	// The toasts are read from sonner's store; no toaster is mounted here on Linux.
+	const { toasts: liveToasts } = useSonner();
+	const languageNames = useMemo(
+		() => Object.fromEntries(AVAILABLE_LOCALES.map((loc) => [loc, getLocaleName(loc)])),
+		[],
+	);
+	const hudPanelState = useMemo<HudPanelState>(() => {
+		if (!floatsInPanel) return EMPTY_HUD_PANEL_STATE;
+		const notices: HudPanelNotice[] = [];
+		if (systemLocaleSuggestion) {
+			notices.push({
+				id: "system-locale",
+				title: t("systemLanguagePrompt.title"),
+				description: t("systemLanguagePrompt.description", { language: suggestedLanguageName }),
+				dismissLabel: t("systemLanguagePrompt.keepDefault"),
+				confirmLabel: t("systemLanguagePrompt.switch", { language: suggestedLanguageName }),
+			});
+		}
+		if (softwareEncoderFallbackNoticeVisible) {
+			notices.push({
+				id: "software-encoder-fallback",
+				title: t("softwareEncoderFallback.title"),
+				description: t("softwareEncoderFallback.description"),
+				dismissLabel: t("softwareEncoderFallback.dontShowAgain"),
+				confirmLabel: t("softwareEncoderFallback.dismiss"),
+			});
+		}
+		return {
+			deviceSettings: isDeviceSettingsOpen
+				? {
+						showMicrophone: microphoneOffered,
+						micDevices,
+						cameraDevices,
+						activeMicId: microphoneDeviceId || selectedMicId,
+						activeCameraId: webcamDeviceId || selectedCameraId,
+						cameraLoading: isCameraDevicesLoading,
+						cameraError: cameraDevicesError,
+						labels: deviceSettingsLabels,
+						versionLabel,
+						// See the same veto on the in-window panel below.
+						canCheckForUpdates: (appInfo?.canCheckForUpdates ?? false) && !recording,
+						checkingForUpdates: isCheckingForUpdates,
+						cameraQuality: webcamQuality,
+					}
+				: null,
+			languageMenu: isLanguageMenuOpen
+				? { locales: AVAILABLE_LOCALES, activeLocale: locale, names: languageNames }
+				: null,
+			notices,
+			toasts: toHudPanelToasts(liveToasts),
+		};
+	}, [
+		floatsInPanel,
+		systemLocaleSuggestion,
+		suggestedLanguageName,
+		softwareEncoderFallbackNoticeVisible,
+		isDeviceSettingsOpen,
+		isLanguageMenuOpen,
+		microphoneOffered,
+		micDevices,
+		cameraDevices,
+		microphoneDeviceId,
+		selectedMicId,
+		webcamDeviceId,
+		selectedCameraId,
+		isCameraDevicesLoading,
+		cameraDevicesError,
+		deviceSettingsLabels,
+		versionLabel,
+		appInfo,
+		recording,
+		isCheckingForUpdates,
+		webcamQuality,
+		locale,
+		languageNames,
+		liveToasts,
+		t,
+	]);
+	useEffect(() => {
+		if (floatsInPanel) window.electronAPI?.sendHudPanelState?.(hudPanelState);
+	}, [floatsInPanel, hudPanelState]);
+
+	// What the user did in the panel window, run through the same handlers the in-window
+	// surfaces use. Read through a ref so the subscription is made once.
+	const handleHudPanelActionRef = useRef<(action: HudPanelAction) => void>(() => undefined);
+	handleHudPanelActionRef.current = (action: HudPanelAction) => {
+		switch (action.kind) {
+			case "select-mic":
+				handleSelectMicDevice(action.device);
+				return;
+			case "select-camera":
+				handleSelectCameraDevice(action.device);
+				return;
+			case "select-camera-quality":
+				handleSelectCameraQuality(action.quality);
+				return;
+			case "check-for-updates":
+				handleCheckForUpdates();
+				return;
+			case "close-device-settings":
+				closeDeviceSettings();
+				return;
+			case "select-locale":
+				handleSelectLocale(action.locale);
+				return;
+			case "close-popovers":
+				closePopovers();
+				return;
+			case "notice":
+				if (action.id === "system-locale") {
+					(action.choice === "confirm"
+						? acceptSystemLocaleSuggestion
+						: dismissSystemLocaleSuggestion)();
+				} else {
+					(action.choice === "confirm"
+						? dismissSoftwareFallbackOnce
+						: dismissSoftwareFallbackForever)();
+				}
+				return;
+			case "toast-action": {
+				// As sonner does: run the action, then dismiss unless it prevented that.
+				const live = liveToasts.find((item) => item.id === action.id)?.action;
+				let prevented = false;
+				if (live && typeof live === "object" && "onClick" in live) {
+					live.onClick({
+						preventDefault: () => {
+							prevented = true;
+						},
+						get defaultPrevented() {
+							return prevented;
+						},
+					} as unknown as React.MouseEvent<HTMLButtonElement, MouseEvent>);
+				}
+				if (!prevented) toast.dismiss(action.id);
+				return;
+			}
+			case "toast-dismiss":
+				toast.dismiss(action.id);
+				return;
+		}
+	};
+	useEffect(() => {
+		if (!floatsInPanel) return;
+		return window.electronAPI?.onHudPanelAction?.((action) =>
+			handleHudPanelActionRef.current(action),
+		);
+	}, [floatsInPanel]);
+
 	return (
 		// Avoid w-screen/h-screen: 100vw can exceed the inner layout width when scrollbars
 		// affect the viewport (Windows), causing a horizontal scrollbar (issue #305).
@@ -1192,190 +1385,195 @@ export function LaunchWindow() {
 			{/* One bottom-anchored stack: the bar, then whatever floats above it.
 			    Everything is laid out by flexbox relative to the bar, so no popover
 			    needs a measured position and none of them can move the window. */}
-			<div ref={hudAnchorRef} className={styles.hudAnchor}>
+			<div
+				ref={hudAnchorRef}
+				className={`${styles.hudAnchor} ${floatsInPanel ? styles.hudAnchorFill : ""}`}
+			>
 				<HudLayoutProvider value={isVertical}>
-					<div
-						ref={setHudBarEl}
-						data-hud-interactive="true"
-						data-tray-layout={trayLayout}
-						className={`${styles.hudBar} ${isVertical ? styles.hudBarVertical : styles.hudBarHorizontal}`}
-						onPointerEnter={enableHudMouseEvents}
-						onPointerDown={enableHudMouseEvents}
-						onMouseEnter={enableHudMouseEvents}
-						onMouseLeave={handlePointerLeave}
-					>
-						<HudDragHandle
-							vertical={isVertical}
-							nativeDrag={isLinuxHud}
-							onPointerDown={handleHudDragPointerDown}
-							onPointerMove={handleHudDragPointerMove}
-							onPointerEnd={handleHudDragPointerEnd}
-						/>
-
-						<HudDivider vertical={isVertical} />
-
-						<HudTrayLayoutButton
-							vertical={isVertical}
-							label={isVertical ? t("tooltips.useHorizontalTray") : t("tooltips.useVerticalTray")}
-							onClick={toggleTrayLayout}
-						/>
-
-						{/* No source button on Linux: `SelectSources` has no parameter
+					<HudNativeTooltipsProvider value={floatsInPanel}>
+						<div
+							ref={setHudBarEl}
+							data-hud-interactive="true"
+							data-tray-layout={trayLayout}
+							className={`${styles.hudBar} ${isVertical ? styles.hudBarVertical : styles.hudBarHorizontal}`}
+							onPointerEnter={enableHudMouseEvents}
+							onPointerDown={enableHudMouseEvents}
+							onMouseEnter={enableHudMouseEvents}
+							onMouseLeave={handlePointerLeave}
+						>
+							<HudDragHandle
+								vertical={isVertical}
+								nativeDrag={isLinuxHud}
+								onPointerDown={handleHudDragPointerDown}
+								onPointerMove={handleHudDragPointerMove}
+								onPointerEnd={handleHudDragPointerEnd}
+							/>
+
+							<HudDivider vertical={isVertical} />
+
+							<HudTrayLayoutButton
+								vertical={isVertical}
+								label={isVertical ? t("tooltips.useHorizontalTray") : t("tooltips.useVerticalTray")}
+								onClick={toggleTrayLayout}
+							/>
+
+							{/* No source button on Linux: `SelectSources` has no parameter
 					    naming a source, so nothing this picker returned could reach
 					    the capture. It raised a second portal dialog of its own —
 					    via `desktopCapturer.getSources()` — whose grant was then
 					    discarded, which is why picking a window here changed
 					    nothing. The compositor's picker is the only one that
 					    decides, and it appears when recording starts. */}
-						{!portalOwnsSource && (
-							<HudSourceButton
-								vertical={isVertical}
-								label={
-									hasSelectedSource ? selectedSource : (rememberedSourceName ?? selectedSource)
-								}
-								tooltip={
-									hasSelectedSource || rememberedSourceName !== null
-										? t("tooltips.changeSource")
-										: t("recording.selectSource")
-								}
-								remembered={!hasSelectedSource && rememberedSourceName !== null}
-								disabled={controlsLocked}
-								onClick={openSourceSelector}
-							/>
-						)}
+							{!portalOwnsSource && (
+								<HudSourceButton
+									vertical={isVertical}
+									label={
+										hasSelectedSource ? selectedSource : (rememberedSourceName ?? selectedSource)
+									}
+									tooltip={
+										hasSelectedSource || rememberedSourceName !== null
+											? t("tooltips.changeSource")
+											: t("recording.selectSource")
+									}
+									remembered={!hasSelectedSource && rememberedSourceName !== null}
+									disabled={controlsLocked}
+									onClick={openSourceSelector}
+								/>
+							)}
 
-						<HudDivider vertical={isVertical} />
+							<HudDivider vertical={isVertical} />
 
-						{/* System audio / mic / camera / cursor — each its own standalone
+							{/* System audio / mic / camera / cursor — each its own standalone
 					    transparent icon button (no shared group pill), matching the
 					    design exactly: rest color is muted gray, active/enabled color
 					    is the accent green. */}
-						<HudSystemAudioButton
-							enabled={systemAudioEnabled}
-							locked={controlsLocked}
-							name={t("audio.systemAudio")}
-							tooltip={t("tooltips.systemAudio")}
-							onClick={toggleSystemAudio}
-						/>
-						{/* The gear configures the two toggles beside it, so the three sit
+							<HudSystemAudioButton
+								enabled={systemAudioEnabled}
+								locked={controlsLocked}
+								name={t("audio.systemAudio")}
+								tooltip={t("tooltips.systemAudio")}
+								onClick={toggleSystemAudio}
+							/>
+							{/* The gear configures the two toggles beside it, so the three sit
 					    closer together than the bar's normal control spacing — proximity
 					    is the design's own grouping device, no extra furniture needed. */}
-						<div
-							className={`${styles.hudControlGroup} ${isVertical ? styles.hudControlGroupVertical : ""}`}
-						>
-							{microphoneOffered && (
-								<HudMicButton
-									enabled={microphoneEnabled}
+							<div
+								className={`${styles.hudControlGroup} ${isVertical ? styles.hudControlGroupVertical : ""}`}
+							>
+								{microphoneOffered && (
+									<HudMicButton
+										enabled={microphoneEnabled}
+										locked={controlsLocked}
+										name={t("audio.microphone")}
+										tooltip={t("tooltips.microphone")}
+										onClick={toggleMicrophone}
+									/>
+								)}
+								<HudCameraButton
+									enabled={webcamEnabled}
 									locked={controlsLocked}
-									name={t("audio.microphone")}
-									tooltip={t("tooltips.microphone")}
-									onClick={toggleMicrophone}
+									name={t("webcam.camera")}
+									tooltip={t("tooltips.camera")}
+									onClick={toggleWebcam}
+								/>
+								<HudSettingsButton
+									buttonRef={settingsTriggerRef}
+									locked={controlsLocked}
+									expanded={isDeviceSettingsOpen}
+									label={t("deviceSettings.title")}
+									onClick={toggleDeviceSettings}
+								/>
+							</div>
+							{supportsCursorModeToggle && (
+								<HudCursorButton
+									editableOverlay={cursorCaptureMode === "editable-overlay"}
+									locked={controlsLocked}
+									name={t("cursor.name")}
+									tooltip={
+										cursorCaptureMode === "editable-overlay"
+											? t("cursor.editableTip")
+											: t("cursor.systemTip")
+									}
+									onClick={toggleCursorMode}
 								/>
 							)}
-							<HudCameraButton
-								enabled={webcamEnabled}
-								locked={controlsLocked}
-								name={t("webcam.camera")}
-								tooltip={t("tooltips.camera")}
-								onClick={toggleWebcam}
-							/>
-							<HudSettingsButton
-								buttonRef={settingsTriggerRef}
-								locked={controlsLocked}
-								expanded={isDeviceSettingsOpen}
-								label={t("deviceSettings.title")}
-								onClick={toggleDeviceSettings}
-							/>
-						</div>
-						{supportsCursorModeToggle && (
-							<HudCursorButton
-								editableOverlay={cursorCaptureMode === "editable-overlay"}
-								locked={controlsLocked}
-								name={t("cursor.name")}
-								tooltip={
-									cursorCaptureMode === "editable-overlay"
-										? t("cursor.editableTip")
-										: t("cursor.systemTip")
-								}
-								onClick={toggleCursorMode}
-							/>
-						)}
 
-						<HudDivider vertical={isVertical} />
-
-						<HudRecordButton
-							recording={recording}
-							paused={paused}
-							saving={saving}
-							elapsedSeconds={elapsedSeconds}
-							label={recordLabel}
-							savingLabel={t("recording.saving")}
-							onClick={handleRecordClick}
-						/>
-
-						{!recording && (
-							<HudStudioButton
-								disabled={saving}
-								label={t("tooltips.openStudio")}
-								onClick={openStudio}
-							/>
-						)}
+							<HudDivider vertical={isVertical} />
 
-						{recording && (
-							<HudRecordingControls
-								vertical={isVertical}
+							<HudRecordButton
+								recording={recording}
 								paused={paused}
 								saving={saving}
-								canPause={canPauseRecording}
-								pauseLabel={paused ? t("tooltips.resumeRecording") : t("tooltips.pauseRecording")}
-								restartLabel={t("tooltips.restartRecording")}
-								cancelLabel={t("tooltips.cancelRecording")}
-								onTogglePause={togglePaused}
-								onRestart={restartRecording}
-								onCancel={cancelRecording}
+								elapsedSeconds={elapsedSeconds}
+								label={recordLabel}
+								savingLabel={t("recording.saving")}
+								onClick={handleRecordClick}
 							/>
-						)}
 
-						{!isLinuxHud && (
-							<HudNotesButton
-								disabled={saving}
-								label={t("tooltips.openNotes")}
-								onClick={openNotes}
-							/>
-						)}
+							{!recording && (
+								<HudStudioButton
+									disabled={saving}
+									label={t("tooltips.openStudio")}
+									onClick={openStudio}
+								/>
+							)}
 
-						<HudDivider vertical={isVertical} />
+							{recording && (
+								<HudRecordingControls
+									vertical={isVertical}
+									paused={paused}
+									saving={saving}
+									canPause={canPauseRecording}
+									pauseLabel={paused ? t("tooltips.resumeRecording") : t("tooltips.pauseRecording")}
+									restartLabel={t("tooltips.restartRecording")}
+									cancelLabel={t("tooltips.cancelRecording")}
+									onTogglePause={togglePaused}
+									onRestart={restartRecording}
+									onCancel={cancelRecording}
+								/>
+							)}
 
-						{/* Right sidebar controls */}
-						<div
-							className={`flex items-center gap-[5px] ${isVertical ? "flex-col" : ""} ${styles.electronNoDrag}`}
-						>
-							<HudLanguageButton
-								buttonRef={languageTriggerRef}
-								vertical={isVertical}
-								code={languageCode}
-								label={t("languageWithName", { language: activeLanguageLabel })}
-								disabled={saving}
-								expanded={isLanguageMenuOpen}
-								onClick={toggleLanguageMenu}
-							/>
+							{!isLinuxHud && (
+								<HudNotesButton
+									disabled={saving}
+									label={t("tooltips.openNotes")}
+									onClick={openNotes}
+								/>
+							)}
 
 							<HudDivider vertical={isVertical} />
 
-							<HudWindowControls
-								vertical={isVertical}
-								disabled={saving}
-								hideLabel={t("tooltips.hideHUD")}
-								hideTooltip={t("tooltips.hideHUDTip")}
-								closeLabel={t("tooltips.closeApp")}
-								onHide={sendHudOverlayHide}
-								onClose={sendHudOverlayClose}
-							/>
+							{/* Right sidebar controls */}
+							<div
+								className={`flex items-center gap-[5px] ${isVertical ? "flex-col" : ""} ${styles.electronNoDrag}`}
+							>
+								<HudLanguageButton
+									buttonRef={languageTriggerRef}
+									vertical={isVertical}
+									code={languageCode}
+									label={t("languageWithName", { language: activeLanguageLabel })}
+									disabled={saving}
+									expanded={isLanguageMenuOpen}
+									onClick={toggleLanguageMenu}
+								/>
+
+								<HudDivider vertical={isVertical} />
+
+								<HudWindowControls
+									vertical={isVertical}
+									disabled={saving}
+									hideLabel={t("tooltips.hideHUD")}
+									hideTooltip={t("tooltips.hideHUDTip")}
+									closeLabel={t("tooltips.closeApp")}
+									onHide={sendHudOverlayHide}
+									onClose={sendHudOverlayClose}
+								/>
+							</div>
 						</div>
-					</div>
+					</HudNativeTooltipsProvider>
 				</HudLayoutProvider>
 
-				{(isPopoverOpen || hasNotices) && (
+				{!floatsInPanel && (isPopoverOpen || hasNotices) && (
 					// column-reverse: first child sits closest to the bar.
 					<div className={styles.hudAbove}>
 						{isDeviceSettingsOpen && (
@@ -1458,13 +1656,16 @@ export function LaunchWindow() {
 			    window is click-through everywhere else, so without it a toast's close button
 			    passed the click to the app behind. It has no box of its own, the toasts are
 			    `fixed`, so it adds nothing to the hit area but the toasts themselves. */}
-			<div ref={hudToasterRef} data-hud-interactive="true" data-testid="hud-toaster">
-				<Toaster
-					position="bottom-center"
-					offset={{ bottom: hudToastBottom }}
-					mobileOffset={{ bottom: hudToastBottom }}
-				/>
-			</div>
+			{/* Not on Linux: the toasts are shown in the panel window there (hudPanel.ts). */}
+			{!floatsInPanel && (
+				<div ref={hudToasterRef} data-hud-interactive="true" data-testid="hud-toaster">
+					<Toaster
+						position="bottom-center"
+						offset={{ bottom: hudToastBottom }}
+						mobileOffset={{ bottom: hudToastBottom }}
+					/>
+				</div>
+			)}
 		</div>
 	);
 }
diff --git a/src/components/launch/hudGeometry.test.ts b/src/components/launch/hudGeometry.test.ts
index a5044b6c5a..d8f69efd54 100644
--- a/src/components/launch/hudGeometry.test.ts
+++ b/src/components/launch/hudGeometry.test.ts
@@ -3,6 +3,7 @@ import {
 	addHudToastsToStack,
 	computeHudAvailableHeight,
 	computeHudBarMaxHeight,
+	computeHudLinuxWindowSize,
 	computeHudModalMaxHeight,
 	computeHudPopoverMaxHeight,
 	computeHudToastBottom,
@@ -222,3 +223,20 @@ describe("HUD toasts", () => {
 		});
 	});
 });
+
+describe("computeHudLinuxWindowSize", () => {
+	it("is exactly the bar, with no reserve around it", () => {
+		expect(
+			computeHudLinuxWindowSize({ barWidth: 600.4, barHeight: 55.2, availableHeight: 1080 }),
+		).toEqual({ width: 601, height: 56 });
+	});
+
+	it("never asks for more height than the screen has", () => {
+		const size = computeHudLinuxWindowSize({
+			barWidth: 56,
+			barHeight: 1200,
+			availableHeight: 900,
+		});
+		expect(size.height).toBe(900);
+	});
+});
diff --git a/src/components/launch/hudGeometry.ts b/src/components/launch/hudGeometry.ts
index 5887343f6e..16479325df 100644
--- a/src/components/launch/hudGeometry.ts
+++ b/src/components/launch/hudGeometry.ts
@@ -182,6 +182,23 @@ export function computeHudWindowSize(input: HudSizeInput): {
 	};
 }
 
+/**
+ * The Linux HUD window: exactly the bar. Wayland cannot make a transparent reserve
+ * click-through, and a compositor that frames and blurs windows (Hyprland) shows any
+ * reserve as a glass box around the bar, so nothing else may be in this window. What
+ * floats is shown in a window of its own (hudPanel.ts), and the tooltips are native ones
+ * (HudTooltip), which Chromium draws outside the window.
+ */
+export function computeHudLinuxWindowSize(input: {
+	barWidth: number;
+	barHeight: number;
+	availableHeight: number;
+}): HudSize {
+	const size = { width: Math.ceil(input.barWidth), height: Math.ceil(input.barHeight) };
+	if (input.availableHeight > 0) size.height = Math.min(size.height, input.availableHeight);
+	return size;
+}
+
 /** Sonner's toast width (its TOAST_WIDTH), which a centred toast takes whatever it says. */
 export const HUD_TOAST_WIDTH = 356;
 /** How far sonner lifts each toast behind the front one in its collapsed stack (its GAP). */
diff --git a/src/components/launch/hudPanel.test.ts b/src/components/launch/hudPanel.test.ts
new file mode 100644
index 0000000000..ef255d476b
--- /dev/null
+++ b/src/components/launch/hudPanel.test.ts
@@ -0,0 +1,59 @@
+import type { ToastT } from "sonner";
+import { describe, expect, it } from "vitest";
+import { EMPTY_HUD_PANEL_STATE, hudPanelHasContent, toHudPanelToasts } from "./hudPanel";
+
+describe("hudPanelHasContent", () => {
+	it("is false only when nothing at all is open", () => {
+		expect(hudPanelHasContent(EMPTY_HUD_PANEL_STATE)).toBe(false);
+		expect(
+			hudPanelHasContent({
+				...EMPTY_HUD_PANEL_STATE,
+				toasts: [{ id: 1, type: "default", title: "Saved" }],
+			}),
+		).toBe(true);
+		expect(
+			hudPanelHasContent({
+				...EMPTY_HUD_PANEL_STATE,
+				languageMenu: { locales: ["en"], activeLocale: "en", names: { en: "English" } },
+			}),
+		).toBe(true);
+	});
+});
+
+describe("toHudPanelToasts", () => {
+	it("carries a toast across as plain data: text, type, duration and the action's label", () => {
+		const toasts: ToastT[] = [
+			{
+				id: "perm",
+				type: "warning",
+				title: "Needs a permission",
+				description: () => "Open the settings",
+				duration: 10_000,
+				action: { label: "Open", onClick: () => undefined },
+			},
+		];
+		expect(toHudPanelToasts(toasts)).toEqual([
+			{
+				id: "perm",
+				type: "warning",
+				title: "Needs a permission",
+				description: "Open the settings",
+				duration: 10_000,
+				actionLabel: "Open",
+			},
+		]);
+	});
+
+	it("leaves out dismissed toasts and maps sonner's internal types to the default look", () => {
+		const toasts: ToastT[] = [
+			{ id: 1, type: "normal", title: "Plain" },
+			{ id: 2, type: "error", title: "Gone", delete: true },
+		];
+		expect(toHudPanelToasts(toasts)).toEqual([{ id: 1, type: "default", title: "Plain" }]);
+	});
+
+	it("drops markup it cannot send between windows rather than sending an object", () => {
+		const toasts: ToastT[] = [{ id: 1, title: { type: "b" } as unknown as ToastT["title"] }];
+		expect(toHudPanelToasts(toasts)).toEqual([{ id: 1, type: "default", title: "" }]);
+	});
+});
diff --git a/src/components/launch/hudPanel.ts b/src/components/launch/hudPanel.ts
new file mode 100644
index 0000000000..31739d6a9f
--- /dev/null
+++ b/src/components/launch/hudPanel.ts
@@ -0,0 +1,135 @@
+/**
+ * The HUD's floating surfaces, rendered in a window of their own on Linux.
+ *
+ * Elsewhere the device settings, the language menu, the notices and the toasts float
+ * above the bar inside one large transparent window, and only the bar takes clicks: the
+ * rest is click-through, re-enabled from the OS cursor position (see the
+ * "hud-overlay-cursor" poll in electron/windows.ts). Wayland gives a client none of the
+ * three things that design rests on. There is no global cursor position to poll; the
+ * input region cannot be narrowed (BrowserWindow.setShape sends no
+ * wl_surface.set_input_region on Wayland); and a client can neither place its window nor
+ * choose which edge a resize grows from — Hyprland keeps a floating window centred,
+ * mutter keeps its top-left corner. The reserve therefore showed as a large framed,
+ * blurred box on Hyprland and swallowed every click inside it on any Wayland desktop.
+ *
+ * So on Linux the HUD window is the bar and nothing else, and everything that floats goes
+ * to this panel window instead. The HUD keeps owning all of the state and every handler:
+ * it sends a plain-data snapshot of what is open ({@link HudPanelState}), and the panel
+ * sends back what the user did ({@link HudPanelAction}). Nothing but data crosses.
+ */
+import type { ToastT } from "sonner";
+import type { CameraDevice } from "../../hooks/useCameraDevices";
+import type { MicrophoneDevice } from "../../hooks/useMicrophoneDevices";
+import type { WebcamQualityId } from "../../hooks/webcamCaptureTarget";
+import type { HudDeviceSettingsLabels } from "./HudDeviceSettings";
+
+export interface HudPanelDeviceSettings {
+	showMicrophone: boolean;
+	micDevices: MicrophoneDevice[];
+	cameraDevices: CameraDevice[];
+	activeMicId: string | undefined;
+	activeCameraId: string | undefined;
+	cameraLoading: boolean;
+	cameraError: string | null;
+	labels: HudDeviceSettingsLabels;
+	versionLabel: string | null;
+	canCheckForUpdates: boolean;
+	checkingForUpdates: boolean;
+	cameraQuality: WebcamQualityId;
+}
+
+export interface HudPanelLanguageMenu {
+	locales: readonly string[];
+	activeLocale: string;
+	/** Display name per locale, resolved in the HUD where the i18n context lives. */
+	names: Record<string, string>;
+}
+
+export type HudPanelNoticeId = "system-locale" | "software-encoder-fallback";
+
+export interface HudPanelNotice {
+	id: HudPanelNoticeId;
+	title: string;
+	description: string;
+	dismissLabel: string;
+	confirmLabel: string;
+}
+
+export interface HudPanelToast {
+	id: string | number;
+	type: "default" | "success" | "error" | "warning" | "info" | "loading";
+	title: string;
+	description?: string;
+	actionLabel?: string;
+	duration?: number;
+}
+
+export interface HudPanelState {
+	deviceSettings: HudPanelDeviceSettings | null;
+	languageMenu: HudPanelLanguageMenu | null;
+	notices: HudPanelNotice[];
+	toasts: HudPanelToast[];
+}
+
+export type HudPanelAction =
+	| { kind: "select-mic"; device: MicrophoneDevice }
+	| { kind: "select-camera"; device: CameraDevice }
+	| { kind: "select-camera-quality"; quality: WebcamQualityId }
+	| { kind: "check-for-updates" }
+	| { kind: "close-device-settings" }
+	| { kind: "select-locale"; locale: string }
+	| { kind: "close-popovers" }
+	| { kind: "notice"; id: HudPanelNoticeId; choice: "dismiss" | "confirm" }
+	| { kind: "toast-action"; id: string | number }
+	| { kind: "toast-dismiss"; id: string | number };
+
+export const EMPTY_HUD_PANEL_STATE: HudPanelState = {
+	deviceSettings: null,
+	languageMenu: null,
+	notices: [],
+	toasts: [],
+};
+
+/** Whether there is anything for the panel to show; when not, the window is hidden. */
+export function hudPanelHasContent(state: HudPanelState): boolean {
+	return (
+		state.deviceSettings !== null ||
+		state.languageMenu !== null ||
+		state.notices.length > 0 ||
+		state.toasts.length > 0
+	);
+}
+
+/** A toast's title or description as text. Only strings survive the trip between windows. */
+function toastText(value: ToastT["title"]): string | undefined {
+	const resolved = typeof value === "function" ? value() : value;
+	if (resolved === null || resolved === undefined || resolved === false) return undefined;
+	return typeof resolved === "string" || typeof resolved === "number"
+		? String(resolved)
+		: undefined;
+}
+
+/**
+ * The HUD's live toasts (sonner's `useSonner`) as plain data. Dismissed ones are left out;
+ * an action is carried as its label, and the click comes back as a `toast-action`.
+ */
+export function toHudPanelToasts(toasts: readonly ToastT[]): HudPanelToast[] {
+	return toasts
+		.filter((toast) => !toast.delete)
+		.map((toast) => {
+			const action =
+				toast.action && typeof toast.action === "object" && "label" in toast.action
+					? toastText(toast.action.label as ToastT["title"])
+					: undefined;
+			const type =
+				toast.type && toast.type !== "normal" && toast.type !== "action" ? toast.type : "default";
+			return {
+				id: toast.id,
+				type,
+				title: toastText(toast.title) ?? "",
+				...(toastText(toast.description) ? { description: toastText(toast.description) } : {}),
+				...(action ? { actionLabel: action } : {}),
+				...(toast.duration !== undefined ? { duration: toast.duration } : {}),
+			};
+		});
+}

From 5bd9808c1f1ef0b023826186930b2b2b8c971e4e Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 09:40:47 -0700
Subject: [PATCH 09/27] feat(linux): ship a pointer-only udev rule for click
 capture

The capture helper reads left-button presses from /dev/input, whose nodes
are root:input. The `input` group would open keyboards too, to every
program the user runs. The deb, rpm and pacman packages now install
70-openscreen-pointer.rules, which has systemd-logind grant the active
local session access to mice and touchpads only (`uaccess`), and reload
udev so it reaches devices already plugged in.

- The install/remove scripts are electron-builder's own templates with
  the udev reload appended; a test fails if they drift from upstream.
- NixOS: the package installs the rule and the module adds it to
  services.udev.packages. Home Manager cannot install udev rules.
- AppImage: the docs give the one-time manual install.
- The helper's warning now points at the rule instead of the input group.
---
 README.md                                     |   2 +-
 build/linux/70-openscreen-pointer.rules       |  16 +++
 build/linux/after-install.tpl                 |  76 ++++++++++++
 build/linux/after-remove.tpl                  |  46 +++++++
 electron-builder.json5                        |  34 ++++-
 .../recording/pipeWireCursorAccumulator.ts    |   4 +-
 .../pipeWireCursorRecordingSession.ts         |   9 +-
 electron/native/README.md                     |  19 +--
 electron/native/pipewire-capture/src/input.rs |  21 ++--
 electron/native/pipewire-capture/src/main.rs  |  10 +-
 nix/hm-module.nix                             |   5 +
 nix/module.nix                                |   6 +
 nix/package.nix                               |   7 ++
 scripts/linux-package-scripts.test.mjs        | 116 ++++++++++++++++++
 scripts/verify-linux-package.sh               |  11 ++
 .../engineering/build-and-packaging.md        |   6 +-
 website/docs/installation.md                  |  29 +++--
 website/src/pages/screen-recorder-linux.mdx   |   4 +-
 18 files changed, 373 insertions(+), 48 deletions(-)
 create mode 100644 build/linux/70-openscreen-pointer.rules
 create mode 100644 build/linux/after-install.tpl
 create mode 100644 build/linux/after-remove.tpl
 create mode 100644 scripts/linux-package-scripts.test.mjs

diff --git a/README.md b/README.md
index c5a0b2ffb1..05241a00c0 100644
--- a/README.md
+++ b/README.md
@@ -214,7 +214,7 @@ You may need to grant screen recording permissions depending on your desktop env
 Everything in the editor and export is the same on macOS, Windows, and Linux: zooms, backgrounds, motion blur, crop/trim/speed, blur regions, annotations, auto-captions, AI editing, projects, export, and all languages. All three now record through a native capture pipeline; the remaining differences are narrower than they used to be:
 
 - **Native recording**: macOS (ScreenCaptureKit), Windows (Windows Graphics Capture), and Linux (PipeWire via the ScreenCast portal) all record through a native pipeline for higher quality and clean window-level capture. On Linux the browser pipeline stays as an automatic fallback if the helper isn't available.
-- **Custom cursors**: on macOS and Windows the real cursor is captured with shape, type, and clicks. Linux captures position and cursor shape through the portal, so the editable cursor overlay works there too. Click effects work on Linux as well, but not through the portal — Wayland exposes no portal for mouse buttons, so the capture helper reads the left button from evdev, which needs read access to your mouse: a udev rule for pointer devices (recommended) or the `input` group, set up as [Mouse clicks on Wayland](https://getopenscreen.com/docs/installation#mouse-clicks-on-wayland) shows. Without that, recording is unaffected and every cursor sample is simply a move.
+- **Custom cursors**: on macOS and Windows the real cursor is captured with shape, type, and clicks. Linux captures position and cursor shape through the portal, so the editable cursor overlay works there too. Click effects work on Linux as well, but not through the portal — Wayland exposes no portal for mouse buttons, so the capture helper reads the left button from evdev, which needs read access to your mouse. The `.deb`, `.rpm` and `.pacman` packages install a udev rule that grants it for mice and touchpads only, never keyboards; with the AppImage, add that rule by hand as [Mouse clicks on Wayland](https://getopenscreen.com/docs/installation#mouse-clicks-on-wayland) shows (the `input` group also works, but opens keyboards too and is not recommended). Without that, recording is unaffected and every cursor sample is simply a move.
 - **Webcam**: every platform saves the webcam as a separate file next to the screen recording. Windows captures it natively in the recording helper; macOS and Linux record it in the app. It works as a picture-in-picture overlay on all three.
 - **System audio** support varies by OS:
   - **macOS**: works on every supported version. On macOS 14.2+ you'll be prompted to grant audio capture permission.
diff --git a/build/linux/70-openscreen-pointer.rules b/build/linux/70-openscreen-pointer.rules
new file mode 100644
index 0000000000..85a473c2aa
--- /dev/null
+++ b/build/linux/70-openscreen-pointer.rules
@@ -0,0 +1,16 @@
+# OpenScreen click zooms: let the logged-in user read mice and touchpads, never keyboards.
+#
+# The Linux capture helper reads left-button presses from /dev/input/event* (Wayland has no
+# portal for mouse buttons; see electron/native/pipewire-capture/src/input.rs). Those nodes
+# are root:input. The `input` group would open every input device, keyboards included, to
+# every program the user runs. `uaccess` instead has systemd-logind put an ACL for the user
+# of the active local session on the matched nodes, and on nothing else. A node that reports
+# any keyboard key (ID_INPUT_KEY) is never matched, even when it is also a mouse.
+#
+# The 70- prefix is load-bearing: the tag has to be set before systemd's 73-seat-late.rules,
+# which is where uaccess is applied. The deb, rpm and pacman packages install this file to
+# /usr/lib/udev/rules.d/, and the NixOS module adds it to services.udev.packages. For the
+# AppImage, copy it to /etc/udev/rules.d/ by hand: website/docs/installation.md,
+# "Mouse clicks on Wayland".
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_KEY}!="1", ENV{ID_INPUT_MOUSE}=="1", TAG+="uaccess"
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_KEY}!="1", ENV{ID_INPUT_TOUCHPAD}=="1", TAG+="uaccess"
diff --git a/build/linux/after-install.tpl b/build/linux/after-install.tpl
new file mode 100644
index 0000000000..8ca294cd28
--- /dev/null
+++ b/build/linux/after-install.tpl
@@ -0,0 +1,76 @@
+#!/bin/bash
+
+if type update-alternatives >/dev/null 2>&1; then
+    # Remove previous link if it doesn't use update-alternatives
+    if [ -L '/usr/bin/${executable}' -a -e '/usr/bin/${executable}' -a "`readlink '/usr/bin/${executable}'`" != '/etc/alternatives/${executable}' ]; then
+        rm -f '/usr/bin/${executable}'
+    fi
+    update-alternatives --install '/usr/bin/${executable}' '${executable}' '/opt/${sanitizedProductName}/${executable}' 100 || ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+else
+    ln -sf '/opt/${sanitizedProductName}/${executable}' '/usr/bin/${executable}'
+fi
+
+# Check if user namespaces are supported by the kernel and working with a quick test:
+if ! { [[ -L /proc/self/ns/user ]] && unshare --user true; }; then
+    # Use SUID chrome-sandbox only on systems without user namespaces:
+    chmod 4755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+else
+    chmod 0755 '/opt/${sanitizedProductName}/chrome-sandbox' || true
+fi
+
+if hash update-mime-database 2>/dev/null; then
+    update-mime-database /usr/share/mime || true
+fi
+
+if hash update-desktop-database 2>/dev/null; then
+    update-desktop-database /usr/share/applications || true
+fi
+
+# Install apparmor profile. (Ubuntu 24+)
+# First check if the version of AppArmor running on the device supports our profile.
+# This is in order to keep backwards compatibility with Ubuntu 22.04 which does not support abi/4.0.
+# In that case, we just skip installing the profile since the app runs fine without it on 22.04.
+#
+# Those apparmor_parser flags are akin to performing a dry run of loading a profile.
+# https://wiki.debian.org/AppArmor/HowToUse#Dumping_profiles
+#
+# Unfortunately, at the moment AppArmor doesn't have a good story for backwards compatibility.
+# https://askubuntu.com/questions/1517272/writing-a-backwards-compatible-apparmor-profile
+if apparmor_status --enabled > /dev/null 2>&1; then
+  APPARMOR_PROFILE_SOURCE='/opt/${sanitizedProductName}/resources/apparmor-profile'
+  APPARMOR_PROFILE_TARGET='/etc/apparmor.d/${executable}'
+  if apparmor_parser --skip-kernel-load --debug "$APPARMOR_PROFILE_SOURCE" > /dev/null 2>&1; then
+    cp -f "$APPARMOR_PROFILE_SOURCE" "$APPARMOR_PROFILE_TARGET"
+
+    # Updating the current AppArmor profile is not possible and probably not meaningful in a chroot'ed environment.
+    # Use cases are for example environments where images for clients are maintained.
+    # There, AppArmor might correctly be installed, but live updating makes no sense.
+    if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+      # Extra flags taken from dh_apparmor:
+      # > By using '-W -T' we ensure that any abstraction updates are also pulled in.
+      # https://wiki.debian.org/AppArmor/Contribute/FirstTimeProfileImport
+      apparmor_parser --replace --write-cache --skip-read-cache "$APPARMOR_PROFILE_TARGET"
+    fi
+  else
+    echo "Skipping the installation of the AppArmor profile as this version of AppArmor does not seem to support the bundled profile"
+  fi
+fi
+
+# ---------------------------------------------------------------------------------------
+# OpenScreen. Everything above is app-builder-lib's templates/linux/after-install.tpl,
+# verbatim: naming a script in electron-builder.json5 REPLACES that template instead of
+# extending it, and it is what creates /usr/bin/openscreen and sets chrome-sandbox's mode.
+# scripts/linux-package-scripts.test.mjs fails when the two drift apart.
+#
+# The package ships /usr/lib/udev/rules.d/70-openscreen-pointer.rules (build/linux/), which
+# gives the logged-in user read access to mice and touchpads for click capture. udev only
+# applies a rule to an event, so a mouse that is already plugged in would wait for a replug
+# or a reboot; reloading and replaying a change event on the input devices applies it now.
+#
+# Skipped where no udev daemon is listening (a container, a chroot, an image build): there
+# is nothing to reload, and the rule applies on the first boot anyway. Never fatal.
+if command -v udevadm >/dev/null 2>&1 && [ -S /run/udev/control ] \
+    && ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; }; then
+    udevadm control --reload-rules || true
+    udevadm trigger --subsystem-match=input --action=change || true
+fi
diff --git a/build/linux/after-remove.tpl b/build/linux/after-remove.tpl
new file mode 100644
index 0000000000..80eda1a31f
--- /dev/null
+++ b/build/linux/after-remove.tpl
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Delete the link to the binary
+# update-alternatives --remove <name> <path>: 'path' must be the registered alternative binary,
+# not the generic symlink — see https://man7.org/linux/man-pages/man1/update-alternatives.1.html
+if type update-alternatives >/dev/null 2>&1; then
+    update-alternatives --remove '${executable}' '/opt/${sanitizedProductName}/${executable}'
+else
+    rm -f '/usr/bin/${executable}'
+fi
+
+APPARMOR_PROFILE_DEST='/etc/apparmor.d/${executable}'
+
+# Remove and unload apparmor profile.
+if [ -f "$APPARMOR_PROFILE_DEST" ]; then
+  # Unload the profile from the running kernel before deleting the file so the
+  # policy is not left enforced until the next reboot.  Mirror the chroot guard
+  # used in the after-install script — live AppArmor operations are not
+  # meaningful inside a chroot.
+  # https://wiki.debian.org/AppArmor/HowToUse
+  if apparmor_status --enabled > /dev/null 2>&1; then
+    if ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; } && hash apparmor_parser 2>/dev/null; then
+      apparmor_parser --remove "$APPARMOR_PROFILE_DEST" || true
+    fi
+  fi
+  rm -f "$APPARMOR_PROFILE_DEST"
+fi
+
+# ---------------------------------------------------------------------------------------
+# OpenScreen. Everything above is app-builder-lib's templates/linux/after-remove.tpl,
+# verbatim: naming a script in electron-builder.json5 REPLACES that template instead of
+# extending it. scripts/linux-package-scripts.test.mjs fails when the two drift apart.
+#
+# The package manager has already deleted 70-openscreen-pointer.rules by now. Reload so
+# udev stops tagging pointer devices for uaccess, and replay a change event so the current
+# devices are re-evaluated without it. An ACL logind already placed on a node can outlive
+# this until the device is replugged or the machine reboots: udev has no event that
+# withdraws one.
+#
+# This also runs on upgrade (deb postrm, rpm %postun), when the new package's copy of the
+# rule is in place. Reloading then is harmless. Same guard as after-install.
+if command -v udevadm >/dev/null 2>&1 && [ -S /run/udev/control ] \
+    && ! { [ -x '/usr/bin/ischroot' ] && /usr/bin/ischroot; }; then
+    udevadm control --reload-rules || true
+    udevadm trigger --subsystem-match=input --action=change || true
+fi
diff --git a/electron-builder.json5 b/electron-builder.json5
index 8b11d8cc77..29dc9d9b6b 100644
--- a/electron-builder.json5
+++ b/electron-builder.json5
@@ -327,7 +327,26 @@
       "libasound2",
       "libgomp1",
       "xdg-desktop-portal"
-    ]
+    ],
+    // Click capture without manual setup: ship build/linux/70-openscreen-pointer.rules, which
+    // grants the logged-in user (systemd-logind `uaccess`) read access to mice and touchpads,
+    // never keyboards. The same three keys are repeated on `pacman` and `rpm`, because the
+    // `linux` block does not accept them: fpm options are per target.
+    //
+    // `fpm` is extra fpm arguments, and a `src=dest` argument maps one more file into the
+    // package. The source is relative to fpm's working directory, which is the project root
+    // whenever electron-builder runs from an npm script. The package owns the file, so the
+    // package manager also deletes it on uninstall.
+    //
+    // A custom `afterInstall`/`afterRemove` REPLACES electron-builder's default script instead
+    // of extending it, and the default is what creates /usr/bin/openscreen and sets
+    // chrome-sandbox's mode. So build/linux/after-*.tpl are those templates verbatim with a
+    // udev reload appended, and scripts/linux-package-scripts.test.mjs fails when they drift
+    // after an electron-builder upgrade. The reload is what lets the rule reach a mouse that
+    // is already plugged in, without a replug or a reboot.
+    "afterInstall": "build/linux/after-install.tpl",
+    "afterRemove": "build/linux/after-remove.tpl",
+    "fpm": ["build/linux/70-openscreen-pointer.rules=/usr/lib/udev/rules.d/70-openscreen-pointer.rules"]
   },
   "pacman": {
     // `vulkan-swrast` est le lavapipe d'Arch ; il tire `vulkan-icd-loader` avec lui.
@@ -365,7 +384,12 @@
       "alsa-lib",
       "libgomp",
       "xdg-desktop-portal"
-    ]
+    ],
+    // The pointer udev rule and the scripts that reload udev: see `deb` above. Arch's own
+    // systemd pacman hook also reloads udev when a file under usr/lib/udev/rules.d changes.
+    "afterInstall": "build/linux/after-install.tpl",
+    "afterRemove": "build/linux/after-remove.tpl",
+    "fpm": ["build/linux/70-openscreen-pointer.rules=/usr/lib/udev/rules.d/70-openscreen-pointer.rules"]
   },
   "rpm": {
     // Même règle que ci-dessus : la liste REMPLACE le défaut d'electron-builder, donc
@@ -404,7 +428,11 @@
       "alsa-lib",
       "libgomp",
       "xdg-desktop-portal"
-    ]
+    ],
+    // The pointer udev rule and the scripts that reload udev: see `deb` above.
+    "afterInstall": "build/linux/after-install.tpl",
+    "afterRemove": "build/linux/after-remove.tpl",
+    "fpm": ["build/linux/70-openscreen-pointer.rules=/usr/lib/udev/rules.d/70-openscreen-pointer.rules"]
   },
   "win": {
     "target": [
diff --git a/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts b/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
index 9a233c7d26..0a9c416bac 100644
--- a/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
+++ b/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
@@ -182,8 +182,8 @@ export class PipeWireCursorAccumulator {
 			cy: clamp(payload.y / height, 0, 1),
 			visible: payload.visible,
 			// The portal never reports a button; the helper tags a sample "click"
-			// only when it read a left-button press from evdev (needs the user in
-			// the `input` group). Everything else — the common case — is a move.
+			// only when it read a left-button press from evdev (needs the pointer
+			// udev rule the packages install). Everything else is a move.
 			interactionType: payload.interactionType ?? "move",
 			...(payload.assetId ? { assetId: payload.assetId } : {}),
 		});
diff --git a/electron/native-bridge/cursor/recording/pipeWireCursorRecordingSession.ts b/electron/native-bridge/cursor/recording/pipeWireCursorRecordingSession.ts
index 7dd222ced0..3008c6d32c 100644
--- a/electron/native-bridge/cursor/recording/pipeWireCursorRecordingSession.ts
+++ b/electron/native-bridge/cursor/recording/pipeWireCursorRecordingSession.ts
@@ -22,10 +22,11 @@ import type { CursorRecordingSession } from "./session";
  * Two consequences the caller should know about:
  *
  *   * `interactionType` is "move" unless the helper could read left-button
- *     presses from evdev — which needs the user in the `input` group, because
- *     Wayland exposes no portal for mouse buttons and /dev/input/event* is
- *     root:input. When it can, the coinciding sample is tagged "click"; when it
- *     cannot, every sample is a move, as before. See the helper's input.rs.
+ *     presses from evdev — which needs the pointer udev rule the Linux packages
+ *     install (build/linux/70-openscreen-pointer.rules), because Wayland exposes
+ *     no portal for mouse buttons and /dev/input/event* is root:input. When it
+ *     can, the coinciding sample is tagged "click"; when it cannot, every
+ *     sample is a move, as before. See the helper's input.rs.
  *   * The helper raises its own portal picker. On Wayland, Electron's
  *     `desktopCapturer` already raised one, so the user currently picks a source
  *     twice. Merging the two is the job of the capture stage that will reuse this
diff --git a/electron/native/README.md b/electron/native/README.md
index 1a0774ef89..c6d54a9371 100644
--- a/electron/native/README.md
+++ b/electron/native/README.md
@@ -229,13 +229,18 @@ electron/native/bin/linux-x64/openscreen-pipewire-helper '{"probeOnly":true}'
 
 - **Mouse clicks need read access to evdev.** Wayland exposes no portal for input
   events, so the helper reads left-button presses straight from evdev
-  (`/dev/input/event*`). Those nodes are `root:input`, so a user with neither a
-  udev `uaccess` rule for pointer devices (recommended) nor membership in the
-  `input` group gets no readable device and every sample's `interactionType`
-  stays `"move"` — the same as before. When a device is readable, the coinciding
-  sample is tagged `"click"`. Scope is deliberately narrow: `BTN_LEFT` only,
-  never keystrokes (see `pipewire-capture/src/input.rs`), and
-  `OPENSCREEN_DISABLE_CLICK_CAPTURE=1` turns it off entirely. User setup:
+  (`/dev/input/event*`). Those nodes are `root:input`. The deb, rpm and pacman
+  packages install `build/linux/70-openscreen-pointer.rules`, a udev `uaccess`
+  rule for mice and touchpads (never keyboards), and the NixOS module adds it to
+  `services.udev.packages`. A user with neither that rule (an AppImage or a dev
+  build, unless added by hand) nor membership in the `input` group (not
+  recommended: it opens keyboards too) gets no readable device, and every
+  sample's `interactionType` stays `"move"` — the same as before; the helper
+  then logs a `click-capture-unavailable` warning that names the rule. When a
+  device is readable, the coinciding sample is tagged `"click"`. Scope is
+  deliberately narrow: `BTN_LEFT` only, never keystrokes (see
+  `pipewire-capture/src/input.rs`), and `OPENSCREEN_DISABLE_CLICK_CAPTURE=1`
+  turns it off entirely. User setup:
   [Mouse clicks on Wayland](../../website/docs/installation.md#mouse-clicks-on-wayland).
 - **Window takes keep the client-side shadow as a black border, and a window
   take in which the pointer never enters the window has no cursor data.** Both
diff --git a/electron/native/pipewire-capture/src/input.rs b/electron/native/pipewire-capture/src/input.rs
index a1d41c90de..887867248d 100644
--- a/electron/native/pipewire-capture/src/input.rs
+++ b/electron/native/pipewire-capture/src/input.rs
@@ -5,10 +5,13 @@
 //! metadata but never button state, and the only portal that streams input
 //! (`InputCapture`) *grabs* it, redirecting clicks away from the app being
 //! recorded — useless while the user is demoing. The one remaining source is the
-//! kernel's evdev interface (`/dev/input/event*`). Reading it needs membership in
-//! the `input` group (the nodes are `root:input`), which is the user's own,
-//! out-of-band act of consent — the Wayland equivalent of the button state the
-//! macOS and Windows helpers already read from their native APIs.
+//! kernel's evdev interface (`/dev/input/event*`). The nodes are `root:input`, so
+//! reading them needs access granted out of band: the udev rule the Linux
+//! packages install (build/linux/70-openscreen-pointer.rules, a logind `uaccess`
+//! ACL on mice and touchpads only), or membership in the `input` group, which
+//! also opens keyboards and is not recommended. Installing the package is the
+//! user's act of consent — the Wayland equivalent of the button state the macOS
+//! and Windows helpers already read from their native APIs.
 //!
 //! SCOPE AND PRIVACY. A pointer node can also deliver keystrokes on a combined
 //! keyboard+mouse device. This reader inspects ONLY `EV_KEY` events whose code is
@@ -54,14 +57,14 @@ pub fn is_left_button_press(event_type: EventType, code: u16, value: i32) -> boo
 ///
 /// The two ways of ending up without clicks are NOT the same event: no readable
 /// node is a permission the operator may still want to grant, while `DISABLE_ENV`
-/// is one they explicitly declined — recommending the `input` group there answers
-/// a question nobody asked.
+/// is one they explicitly declined — recommending the udev rule there answers a
+/// question nobody asked.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClickCapture {
     /// Turned off by `OPENSCREEN_DISABLE_CLICK_CAPTURE`; nothing was opened.
     Disabled,
     /// No readable `/dev/input` node reports `BTN_LEFT` — the common case, when
-    /// the user is not in the `input` group.
+    /// the pointer udev rule is not installed (an AppImage, typically).
     NoDevice,
     /// At least one device is open, with a reader thread running on it.
     Active,
@@ -71,8 +74,8 @@ pub enum ClickCapture {
 /// thread per device, and leaves a daemon thread re-scanning for devices plugged
 /// in later.
 ///
-/// Never fails: an unreadable node (the common case, when the user is not in the
-/// `input` group) is skipped by `evdev::enumerate`, and no readable node at all
+/// Never fails: an unreadable node (the common case, without the pointer udev
+/// rule) is skipped by `evdev::enumerate`, and no readable node at all
 /// simply means every sample stays `"move"`, exactly as before this existed. The
 /// returned value reflects the INITIAL scan only — a device attached afterwards
 /// is adopted by the watcher without changing it.
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 831ce4b053..08a1022acf 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -22,7 +22,8 @@
 //!
 //! MOUSE BUTTONS. Not from the portal — Wayland exposes no portal for input
 //! events. The one source left is evdev (/dev/input/event*), which is root:input
-//! and so needs the user in the `input` group. When that permission exists the
+//! and so needs read access granted by the udev rule the Linux packages ship
+//! (build/linux/70-openscreen-pointer.rules). When that permission exists the
 //! helper reads left-button presses and tags the coinciding sample "click"; when
 //! it does not, every sample is a "move", as before. See `input.rs` for the
 //! reader and its deliberately narrow scope (BTN_LEFT only, never keystrokes).
@@ -354,9 +355,10 @@ fn main() {
     {
         let _ = emitter.emit(&Event::Warning {
             code: "click-capture-unavailable".to_owned(),
-            message: "no readable /dev/input pointer device — grant this user access (a udev \
-                      uaccess rule for mice, or the 'input' group) to record click telemetry; \
-                      cursor samples will otherwise all be moves"
+            message: "no readable /dev/input pointer device — install the udev rule \
+                      70-openscreen-pointer.rules (the deb, rpm and pacman packages ship it; \
+                      for the AppImage see \"Mouse clicks on Wayland\" in the install docs) \
+                      to record click telemetry; cursor samples will otherwise all be moves"
                 .to_owned(),
         });
     }
diff --git a/nix/hm-module.nix b/nix/hm-module.nix
index 9ed0a7d4f5..f307cffe20 100644
--- a/nix/hm-module.nix
+++ b/nix/hm-module.nix
@@ -31,6 +31,11 @@ in
   };
 
   config = lib.mkIf cfg.enable {
+    # Home Manager cannot install udev rules, so click capture is not set up from
+    # here: use the NixOS module (which adds the package's pointer rule to
+    # services.udev.packages), or add `services.udev.packages = [ <the package> ];`
+    # to the system configuration yourself. On a non-NixOS host, install the rule
+    # by hand as website/docs/installation.md ("Mouse clicks on Wayland") shows.
     home.packages = [ cfg.package ];
   };
 }
diff --git a/nix/module.nix b/nix/module.nix
index 0cb7242ca7..c4f1696937 100644
--- a/nix/module.nix
+++ b/nix/module.nix
@@ -33,6 +33,12 @@ in
   config = lib.mkIf cfg.enable {
     environment.systemPackages = [ cfg.package ];
 
+    # Click capture reads left-button presses from /dev/input (Wayland has no portal
+    # for mouse buttons). The package's lib/udev/rules.d/70-openscreen-pointer.rules
+    # grants the logged-in user read access to mice and touchpads, never keyboards,
+    # which is what makes the `input` group unnecessary.
+    services.udev.packages = [ cfg.package ];
+
     # Screen capture on Wayland requires xdg-desktop-portal.
     # We enable the base portal; users should also enable a
     # desktop-specific portal (e.g. xdg-desktop-portal-gtk,
diff --git a/nix/package.nix b/nix/package.nix
index 93b0204fae..93876fb2dc 100644
--- a/nix/package.nix
+++ b/nix/package.nix
@@ -152,6 +152,13 @@ buildNpmPackage {
       fi
     done
 
+    # Pointer udev rule for click capture: lets the logged-in user read mice and
+    # touchpads (systemd-logind uaccess), never keyboards. A package cannot apply a
+    # udev rule by being installed; the NixOS module adds this package to
+    # services.udev.packages, which is what does. See build/linux/ for the rule.
+    install -Dm644 build/linux/70-openscreen-pointer.rules \
+      "$out/lib/udev/rules.d/70-openscreen-pointer.rules"
+
     runHook postInstall
   '';
 
diff --git a/scripts/linux-package-scripts.test.mjs b/scripts/linux-package-scripts.test.mjs
new file mode 100644
index 0000000000..f0e4cc2c6f
--- /dev/null
+++ b/scripts/linux-package-scripts.test.mjs
@@ -0,0 +1,116 @@
+// Guards the pointer udev rule that the deb, rpm and pacman packages ship for Linux click
+// capture, and the install scripts that reload udev so the rule takes effect at once.
+//
+// Three things here fail silently if they go wrong, which is why they are asserted rather
+// than trusted:
+//
+//   * build/linux/after-*.tpl REPLACE electron-builder's own scripts, they do not extend
+//     them. Those templates create /usr/bin/openscreen, set chrome-sandbox's mode and
+//     install the AppArmor profile. Ours are copies with a udev block appended, so an
+//     electron-builder upgrade that changes the upstream template would leave us shipping
+//     the old one, and nothing would say so. The first test is that check.
+//   * The rule exists to open mice and touchpads WITHOUT opening keyboards; a rule edited
+//     to drop the keyboard exclusion would still "work".
+//   * The rule text is also printed in the install docs for AppImage users, who have to
+//     copy it by hand.
+//
+// A text assertion rather than a package build: fpm, rpmbuild and a udev daemon are not
+// on every CI runner. That the `fpm` mapping really lands the file at /usr/lib/udev/rules.d
+// is checked on the built packages by scripts/verify-linux-package.sh.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { objectBody, stripJson5Comments } from "./macos-floor.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const RULE_NAME = "70-openscreen-pointer.rules";
+const RULE_SOURCE = path.join("build", "linux", RULE_NAME);
+const RULE_TARGET = `/usr/lib/udev/rules.d/${RULE_NAME}`;
+const UPSTREAM_TEMPLATES = path.join(ROOT, "node_modules", "app-builder-lib", "templates", "linux");
+
+function read(...segments) {
+	return readFileSync(path.join(ROOT, ...segments), "utf8");
+}
+
+function ruleLines(source) {
+	return source
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+
+describe("Linux package install scripts", () => {
+	for (const name of ["after-install.tpl", "after-remove.tpl"]) {
+		it(`${name} is electron-builder's template verbatim, plus our udev block`, () => {
+			const upstream = readFileSync(path.join(UPSTREAM_TEMPLATES, name), "utf8");
+			const ours = read("build", "linux", name);
+			// If this fails after an electron-builder upgrade: copy the new template over
+			// build/linux/<name> and re-append everything from the "# OpenScreen." block on.
+			expect(ours.startsWith(upstream.trimEnd())).toBe(true);
+			const appended = ours.slice(upstream.trimEnd().length);
+			expect(appended).toContain("udevadm control --reload-rules");
+			expect(appended).toContain("udevadm trigger --subsystem-match=input --action=change");
+			// The udev daemon is absent in a chroot or a container; the install must not fail
+			// there, so the calls sit behind a guard and are never fatal.
+			expect(appended).toContain("[ -S /run/udev/control ]");
+			const calls = appended
+				.split("\n")
+				.map((line) => line.trim())
+				.filter((line) => line.startsWith("udevadm "));
+			expect(calls).toHaveLength(2);
+			for (const call of calls) {
+				expect(call).toMatch(/\|\| true$/);
+			}
+		});
+	}
+
+	for (const target of ["deb", "pacman", "rpm"]) {
+		it(`the ${target} package ships the rule and runs our scripts`, () => {
+			const block = objectBody(stripJson5Comments(read("electron-builder.json5")), target);
+			expect(block, `no "${target}" block in electron-builder.json5`).toBeTruthy();
+			expect(block).toMatch(/"afterInstall"\s*:\s*"build\/linux\/after-install\.tpl"/);
+			expect(block).toMatch(/"afterRemove"\s*:\s*"build\/linux\/after-remove\.tpl"/);
+			expect(block).toContain(`"${RULE_SOURCE}=${RULE_TARGET}"`);
+		});
+	}
+});
+
+describe("pointer udev rule", () => {
+	const rule = read(RULE_SOURCE);
+	const lines = ruleLines(rule);
+
+	it("sorts before systemd's 73-seat-late.rules, which applies uaccess", () => {
+		expect(existsSync(path.join(ROOT, RULE_SOURCE))).toBe(true);
+		expect(RULE_NAME.localeCompare("73-seat-late.rules")).toBeLessThan(0);
+	});
+
+	it("tags only mice and touchpads, and never a node that reports keyboard keys", () => {
+		expect(lines.length).toBeGreaterThan(0);
+		for (const line of lines) {
+			expect(line).toContain('SUBSYSTEM=="input"');
+			expect(line).toContain('KERNEL=="event*"');
+			expect(line).toContain('ENV{ID_INPUT_KEY}!="1"');
+			expect(line).toMatch(/ENV\{ID_INPUT_(MOUSE|TOUCHPAD)\}=="1"/);
+			expect(line).toContain('TAG+="uaccess"');
+			expect(line).not.toMatch(/GROUP|MODE|OWNER/);
+		}
+	});
+
+	it("is printed verbatim in the install docs, for the AppImage", () => {
+		const docs = read("website", "docs", "installation.md");
+		for (const line of lines) {
+			expect(docs).toContain(line);
+		}
+		expect(docs).toContain(`/etc/udev/rules.d/${RULE_NAME}`);
+	});
+
+	it("is installed by the Nix package, where the NixOS module picks it up", () => {
+		expect(read("nix", "package.nix")).toContain(`$out/lib/udev/rules.d/${RULE_NAME}`);
+		expect(read("nix", "module.nix")).toMatch(
+			/services\.udev\.packages\s*=\s*\[\s*cfg\.package\s*\]/,
+		);
+	});
+});
diff --git a/scripts/verify-linux-package.sh b/scripts/verify-linux-package.sh
index 9420843af3..af34d4ab9d 100755
--- a/scripts/verify-linux-package.sh
+++ b/scripts/verify-linux-package.sh
@@ -99,6 +99,17 @@ if [[ ! -d "$ROOT" ]]; then
 	exit 1
 fi
 
+# Mapped in by the `fpm` option of each target in electron-builder.json5, which is easy to
+# lose without anything else failing: click capture just goes back to needing manual setup.
+# The install above also ran the post-install script in a container with no udev daemon,
+# which is the case its udevadm guard exists for.
+UDEV_RULE=/usr/lib/udev/rules.d/70-openscreen-pointer.rules
+if [[ ! -f "$UDEV_RULE" ]]; then
+	echo "FAIL layout: $UDEV_RULE is missing — click capture would need manual setup"
+	exit 1
+fi
+echo "ok layout: $UDEV_RULE installed"
+
 # Every ELF that ships, by magic rather than by extension: the helpers,
 # whisper-stt-server and ffmpeg have none. `head -c`, not bash's `read`, which stops at
 # the NUL bytes an ELF header is full of.
diff --git a/technical-documentation/engineering/build-and-packaging.md b/technical-documentation/engineering/build-and-packaging.md
index 6084eebd71..9f9715a59c 100644
--- a/technical-documentation/engineering/build-and-packaging.md
+++ b/technical-documentation/engineering/build-and-packaging.md
@@ -319,7 +319,11 @@ Electron-builder targets DMG for both `arm64` and `x64`, enables hardened runtim
 
 ### Linux and Nix
 
-Electron-builder produces AppImage, `.deb`, `.pacman`, and `.rpm` targets. Each fpm target carries its own `depends` list, which *replaces* electron-builder's default rather than extending it; all three package formats therefore repeat that default verbatim before adding the Vulkan ICD (`mesa-vulkan-drivers`, `vulkan-swrast` on Arch) the native compositor needs. The RPM list also restores `libsecret`, which electron-builder includes in its `deb` default but omits from its `rpm` one, and which `safeStorage` needs to encrypt LLM credentials. The flake separately supports `x86_64-linux` and `aarch64-linux`, offers NixOS and Home Manager modules, and builds a wrapper around nixpkgs' system Electron. `nix/package.nix` runs Vite directly, installs `dist/`, `dist-electron/`, production npm dependencies, wallpapers, icons, and a desktop entry; it does not invoke electron-builder. The version comes from `package.json`; the npm dependency hash is refreshed by the release workflows in the same commit that bumps the version.
+Electron-builder produces AppImage, `.deb`, `.pacman`, and `.rpm` targets. Each fpm target carries its own `depends` list, which *replaces* electron-builder's default rather than extending it; all three package formats therefore repeat that default verbatim before adding the Vulkan ICD (`mesa-vulkan-drivers`, `vulkan-swrast` on Arch) the native compositor needs. The RPM list also restores `libsecret`, which electron-builder includes in its `deb` default but omits from its `rpm` one, and which `safeStorage` needs to encrypt LLM credentials.
+
+The three fpm targets also ship `build/linux/70-openscreen-pointer.rules` to `/usr/lib/udev/rules.d/`, through each target's `fpm` option (a `src=dest` argument, relative to the project root). The rule tags mice and touchpads, never a node reporting keyboard keys, with `uaccess`, so the active session can read them and the capture helper can record left clicks on Wayland without the `input` group. Each target also names `build/linux/after-install.tpl` and `after-remove.tpl`. A custom script *replaces* electron-builder's own, which creates `/usr/bin/openscreen` and sets `chrome-sandbox`'s mode, so these are its templates verbatim with a guarded `udevadm control --reload-rules` and `udevadm trigger --subsystem-match=input --action=change` appended. That is what applies the rule to a mouse already plugged in. `scripts/linux-package-scripts.test.mjs` fails when the copies drift from the installed electron-builder's templates; after an upgrade, re-copy them and re-append the OpenScreen block. `verify-linux-package.sh` checks that the rule lands in each package. The AppImage cannot install system files, so its users add the rule by hand ([Mouse clicks on Wayland](../../website/docs/installation.md#mouse-clicks-on-wayland)).
+
+The flake separately supports `x86_64-linux` and `aarch64-linux`, offers NixOS and Home Manager modules, and builds a wrapper around nixpkgs' system Electron. `nix/package.nix` runs Vite directly, installs `dist/`, `dist-electron/`, production npm dependencies, wallpapers, icons, a desktop entry, and the pointer udev rule under `lib/udev/rules.d/`, which the NixOS module adds to `services.udev.packages` (Home Manager cannot install udev rules); it does not invoke electron-builder. The version comes from `package.json`; the npm dependency hash is refreshed by the release workflows in the same commit that bumps the version.
 
 ## Node and toolchain versions
 
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 57b910a814..35c79501de 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -27,7 +27,7 @@ On Windows, the recommended route is the [Microsoft Store](#windows). Everywhere
 |---|---|---|
 | **Windows** | Windows 10 version 1903 (build 18362) or later, x64 (or ARM64 with the standalone `.exe`), Intel 8th Gen / AMD Ryzen 2000 series or newer. Native capture needs Windows 10 version 2004 (build 19041) or later; older builds record through the [browser-capture fallback](#platform-differences) | Windows 11, Intel 12th Gen / AMD Ryzen 4000 series or newer |
 | **macOS** | macOS 13 (Ventura) — required by ScreenCaptureKit for capture. Recording the microphone needs macOS 15 or later | macOS 15.2 or later |
-| **Linux** | x64. `xdg-desktop-portal` and PipeWire, which recording needs: the native capture helper goes through them, and a failure there is reported as an error. The [browser-capture fallback](#platform-differences) only takes over when a build is missing the helper itself. System audio additionally needs PipeWire as the sound server (the default on [Ubuntu 22.10+](https://discourse.ubuntu.com/t/kinetic-kudu-release-notes/27976) and [Fedora 34+](https://fedoraproject.org/wiki/Changes/DefaultPipeWire)). Recording mouse clicks on Wayland needs read access to mouse evdev devices — see [Mouse clicks on Wayland](#mouse-clicks-on-wayland) | Same, kept up to date |
+| **Linux** | x64. `xdg-desktop-portal` and PipeWire, which recording needs: the native capture helper goes through them, and a failure there is reported as an error. The [browser-capture fallback](#platform-differences) only takes over when a build is missing the helper itself. System audio additionally needs PipeWire as the sound server (the default on [Ubuntu 22.10+](https://discourse.ubuntu.com/t/kinetic-kudu-release-notes/27976) and [Fedora 34+](https://fedoraproject.org/wiki/Changes/DefaultPipeWire)). Recording mouse clicks on Wayland needs read access to mouse evdev devices, which the `.deb`, `.rpm` and `.pacman` packages set up — see [Mouse clicks on Wayland](#mouse-clicks-on-wayland) | Same, kept up to date |
 | **RAM** | 8 GB | 16 GB |
 
 :::note Older integrated graphics on Windows
@@ -137,24 +137,23 @@ The scope is deliberately narrow: click capture uses only left-button presses (`
 
 #### Recommended: udev rule (least privilege)
 
-On systems where systemd-logind manages the local desktop seat, the safer approach is to grant that seat access (`TAG+="uaccess"`) exclusively to pointer devices (mice and touchpads) while explicitly excluding keyboards. This requires udev's `uaccess` support and ensures that only the actively logged-in seat user has access, without exposing your keyboard:
+**The `.deb`, `.rpm` and `.pacman` packages set this up for you.** They install the udev rule `/usr/lib/udev/rules.d/70-openscreen-pointer.rules` and apply it to the devices already plugged in, so clicks are recorded from the first take, with no reboot. The NixOS module does the same through `services.udev.packages`. Uninstalling the package removes the rule; access it already granted lasts until the device is replugged or the machine reboots.
 
-1. Create a udev rule file at `/etc/udev/rules.d/70-openscreen-mouse.rules` (the `70-` prefix is important so it runs before systemd's seat rules):
+The rule tags mice and touchpads with `uaccess`, so systemd-logind gives the user of the active local session read access to those devices and to nothing else. A device that reports any keyboard key is never matched, even a mouse that also has keys, so your keyboard stays closed. It needs systemd-logind, which manages the local session on most desktop distributions.
+
+**AppImage, `nix profile` / `nix run`, Home Manager, or a build from source:** these cannot install system files, so add the rule by hand, once. It is the same file the packages ship (`build/linux/70-openscreen-pointer.rules` in the repository), and the `70-` prefix matters: it has to run before systemd's seat rules.
 
 ```bash
-sudo tee /etc/udev/rules.d/70-openscreen-mouse.rules << 'EOF'
-KERNEL=="event*", SUBSYSTEM=="input", ENV{ID_INPUT_MOUSE}=="1", ENV{ID_INPUT_KEYBOARD}!="1", TAG+="uaccess"
-KERNEL=="event*", SUBSYSTEM=="input", ENV{ID_INPUT_TOUCHPAD}=="1", ENV{ID_INPUT_KEYBOARD}!="1", TAG+="uaccess"
+sudo tee /etc/udev/rules.d/70-openscreen-pointer.rules << 'EOF'
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_KEY}!="1", ENV{ID_INPUT_MOUSE}=="1", TAG+="uaccess"
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_KEY}!="1", ENV{ID_INPUT_TOUCHPAD}=="1", TAG+="uaccess"
 EOF
+sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=input --action=change
 ```
 
-2. Reload and apply the rules:
-
-```bash
-sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=input
-```
+If you created `/etc/udev/rules.d/70-openscreen-mouse.rules` by following an earlier version of this page, you can delete it once the package rule is installed.
 
-You can verify that your user has access to mouse evdev nodes (e.g. `user:<your-username>:rw-`) with:
+To check that your user can read the mouse, look for `user:<your-username>:rw-` on the mouse and touchpad nodes:
 
 ```bash
 getfacl /dev/input/event*
@@ -162,7 +161,7 @@ getfacl /dev/input/event*
 
 #### Alternative: `input` group
 
-Alternatively, you can add your user to the `input` group:
+Not recommended. You can add your user to the `input` group instead:
 
 ```bash
 sudo usermod -aG input $USER
@@ -171,7 +170,7 @@ sudo usermod -aG input $USER
 Log out and back in for the new group to take effect.
 
 :::caution Security consideration
-Adding your user to the `input` group grants all programs running under your user account ambient read access to **every** input device on the system, including keyboards (acting as an unprivileged keylogger). Using the udev rule above is recommended instead.
+Adding your user to the `input` group grants all programs running under your user account ambient read access to **every** input device on the system, including keyboards (acting as an unprivileged keylogger). Use the udev rule above instead.
 :::
 
 **Touchpads:** only a physical click — pressing the pad down until it depresses — is recorded. **Tap-to-click is not**, because your compositor's input stack (libinput) synthesises those taps for its own use and never writes them back to the kernel device that OpenScreen reads, so there is nothing at the evdev layer to see. A mouse, or a touchpad with tap-to-click turned off, records every click.
@@ -183,7 +182,7 @@ 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)) |
+| Custom cursor / click effects | ✅ — clicks and cursor shape need the Accessibility permission | ✅ | ✅ on Wayland — click capture needs mouse evdev permissions, set up by the packages ([details](#mouse-clicks-on-wayland)) |
 | 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/src/pages/screen-recorder-linux.mdx b/website/src/pages/screen-recorder-linux.mdx
index 06470e6623..e420fba850 100644
--- a/website/src/pages/screen-recorder-linux.mdx
+++ b/website/src/pages/screen-recorder-linux.mdx
@@ -39,7 +39,7 @@ OpenScreen records the screen on Linux with its own native helper, not with the
 - **System audio from PipeWire.** It comes from the monitor of the default PipeWire sink and is mixed with the microphone into one AAC track. It needs PipeWire as the sound server, the default on Ubuntu 22.10 and later and Fedora 34 and later.
 - **Microphone choice.** The HUD lists every input device, with a live level meter. The helper finds the matching PipeWire node by its description.
 - **An editable cursor.** In the default overlay mode, the portal reports the cursor position and shape, so you can restyle the cursor in the editor. System mode records the pointer as it is.
-- **Clicks on Wayland.** Wayland has no portal for input events, so OpenScreen reads left-button presses from evdev. That works when your user can read the mouse, and OpenScreen uses only left-button presses and ignores every other event, so keystrokes are never recorded. The recommended way is a udev rule that gives your desktop session access to mice and touchpads, keyboards excluded. The `input` group also works but is broader: it lets every program you run read every input device, keyboard included. Without either, recording still works and every cursor sample is saved as a move. [Mouse clicks on Wayland](/docs/installation/#mouse-clicks-on-wayland) has the commands.
+- **Clicks on Wayland.** Wayland has no portal for input events, so OpenScreen reads left-button presses from evdev. That works when your user can read the mouse, and OpenScreen uses only left-button presses and ignores every other event, so keystrokes are never recorded. The `.deb`, `.rpm` and `.pacman` packages install a udev rule that gives your desktop session access to mice and touchpads, keyboards excluded, so clicks are recorded with no setup. With the AppImage you add that rule once by hand. The `input` group also works but is broader: it lets every program you run read every input device, keyboard included. Without either, recording still works and every cursor sample is saved as a move. [Mouse clicks on Wayland](/docs/installation/#mouse-clicks-on-wayland) has the commands.
 - **Browser capture only as a fallback.** Chromium's capture takes over only in a build that is missing the helper. A helper that fails reports an error instead of switching. See [Recording](/docs/recording/).
 
 ## Screen Studio-style polish on Linux
@@ -71,7 +71,7 @@ Screen Studio supports only macOS (as of September 2026). OpenScreen offers the
 ## Getting started
 
 1. Download the package for your distribution from the [download page](/download/), or use the Nix flake.
-2. Follow the [Linux installation steps](/docs/installation/#linux). If you want clicks recorded, set up the udev rule or the `input` group from [Mouse clicks on Wayland](/docs/installation/#mouse-clicks-on-wayland).
+2. Follow the [Linux installation steps](/docs/installation/#linux). The `.deb`, `.rpm` and `.pacman` packages set up click recording themselves; with the AppImage, add the udev rule from [Mouse clicks on Wayland](/docs/installation/#mouse-clicks-on-wayland) if you want clicks recorded.
 3. Make a first recording with the [quick start](/docs/quick-start/) and answer the portal dialog when it opens. The take opens in the editor with automatic zooms already placed.
 
 On another system? See the [Windows](/screen-recorder-windows/) and [macOS](/screen-recorder-mac/) pages. Coming from a Mac app? See the [Screen Studio alternative](/alternatives/screen-studio/). Or go back to the [OpenScreen home page](/).

From 0c53d7ab74d89d15e795ca84e9449b779ba89bc5 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 22:39:04 -0700
Subject: [PATCH 10/27] perf(linux): import LINEAR dmabufs on the GPU when
 VA-API can

A dmabuf was routed to the VA-API import only when it could not be
mmap'd, which is the tiled case. xdg-desktop-portal-hyprland hands out
LINEAR buffers, which map, so every frame took the CPU route even with
the importer available: a streaming copy out of write-combined memory,
swscale to NV12, and an upload back to the GPU, about 10 ms of
main-thread work per 4K frame.

With prefer_dmabuf set, osc_on_add_buffer now leaves every dmabuf
unmapped and latches the import, as it already did for a tiled one.
Shared memory, machines without the import, and a forced software
encoder keep the CPU path.

Measured on a 38 s 3840x2160 take (Arc B390, Hyprland): convertMs 0,
uploadMs ~0, encodeMs 0.68, encoder vaapi, 2 of 1729 frames replaced.
---
 .../native/pipewire-capture/csrc/pw_shim.c    | 62 ++++++++++++++++++-
 .../native/pipewire-capture/csrc/pw_shim.h    |  1 +
 electron/native/pipewire-capture/src/shim.rs  | 27 ++++++++
 3 files changed, 87 insertions(+), 3 deletions(-)

diff --git a/electron/native/pipewire-capture/csrc/pw_shim.c b/electron/native/pipewire-capture/csrc/pw_shim.c
index d28e6c9909..2831634f4a 100644
--- a/electron/native/pipewire-capture/csrc/pw_shim.c
+++ b/electron/native/pipewire-capture/csrc/pw_shim.c
@@ -227,7 +227,8 @@ struct osc_pw_session {
     /* Set from the negotiated format's SPA_VIDEO_FLAG_MODIFIER, which is what
      * decides whether buffers arrive as dmabuf fds or shared memory. */
     int uses_dmabuf;
-    /* Latched when a dmabuf buffer cannot be CPU-mmap'd (a tiled buffer on, e.g.,
+    /* Latched when a dmabuf buffer is left unmapped: always under prefer_dmabuf,
+     * and otherwise when it cannot be CPU-mmap'd (a tiled buffer on, e.g.,
      * AMD/mutter). Frames then travel as raw dmabuf descriptors for a GPU import
      * (issue #507) instead of the shared-memory path. */
     int import_dmabuf;
@@ -1170,6 +1171,19 @@ static void osc_on_add_buffer(void *userdata, struct pw_buffer *pw_buf)
     if (data->type != SPA_DATA_DmaBuf) {
         return;
     }
+    /*
+     * With the VAAPI import available, every dmabuf goes to the GPU, a LINEAR one
+     * included. A LINEAR buffer does map, which is why it used to take the CPU
+     * route: copied out of write-combined memory on this thread, converted to
+     * NV12 by swscale and uploaded straight back to the GPU it came from — about
+     * 10 ms of main-thread work per 4K frame (xdg-desktop-portal-hyprland hands
+     * out nothing else). The import reads the same buffer where it already is.
+     * Nothing is mapped, exactly as for a tiled buffer.
+     */
+    if (session->prefer_dmabuf) {
+        session->import_dmabuf = 1;
+        return;
+    }
     /* References keep a shared plane mapped until its last buffer is removed. */
     existing = osc_find_dmabuf_map(session, (int)data->fd, data->mapoffset);
     if (existing != NULL) {
@@ -1256,6 +1270,47 @@ static void osc_on_remove_buffer(void *userdata, struct pw_buffer *pw_buf)
     }
 }
 
+/*
+ * The route osc_on_add_buffer gives a DMA-BUF plane backed by `fd`, which the
+ * caller makes mappable: 1 when it stored a CPU mapping, 2 when it left the
+ * plane unmapped for a GPU import, 0 for anything else. The buffer is removed
+ * again before returning, so no mapping outlives the call.
+ */
+int osc_pw_dmabuf_add_buffer_route(int fd, int prefer_dmabuf)
+{
+    struct osc_pw_session session;
+    struct spa_data data;
+    struct spa_buffer buffer;
+    struct pw_buffer pw_buf;
+    int mapped = 0;
+    int route = 0;
+    size_t i;
+
+    memset(&session, 0, sizeof(session));
+    memset(&data, 0, sizeof(data));
+    memset(&buffer, 0, sizeof(buffer));
+    memset(&pw_buf, 0, sizeof(pw_buf));
+    session.prefer_dmabuf = prefer_dmabuf;
+    data.type = SPA_DATA_DmaBuf;
+    data.fd = fd;
+    data.flags = SPA_DATA_FLAG_READABLE | SPA_DATA_FLAG_MAPPABLE;
+    buffer.n_datas = 1;
+    buffer.datas = &data;
+    pw_buf.buffer = &buffer;
+
+    osc_on_add_buffer(&session, &pw_buf);
+    for (i = 0; i < OSC_MAX_DMABUF_MAPS; i++) {
+        mapped |= session.dmabuf_maps[i].ptr != NULL;
+    }
+    if (mapped && !session.import_dmabuf) {
+        route = 1;
+    } else if (!mapped && session.import_dmabuf) {
+        route = 2;
+    }
+    osc_on_remove_buffer(&session, &pw_buf);
+    return route;
+}
+
 static void osc_unmap_all_dmabufs(struct osc_pw_session *session)
 {
     size_t i;
@@ -1432,8 +1487,9 @@ static int osc_read_frame(struct osc_pw_session *session, const struct spa_buffe
             if (!session->import_dmabuf) {
                 return 0;
             }
-            /* Tiled dmabuf: no CPU mapping exists. It travels up as a raw
-             * descriptor for a GPU import instead of being read here. */
+            /* No CPU mapping exists (any dmabuf under prefer_dmabuf, or a tiled
+             * one). It travels up as a raw descriptor for a GPU import instead of
+             * being read here. */
             is_dmabuf_import = 1;
             base = NULL;
             mapped_len = 0;
diff --git a/electron/native/pipewire-capture/csrc/pw_shim.h b/electron/native/pipewire-capture/csrc/pw_shim.h
index 609943517f..48d47ef415 100644
--- a/electron/native/pipewire-capture/csrc/pw_shim.h
+++ b/electron/native/pipewire-capture/csrc/pw_shim.h
@@ -241,6 +241,7 @@ const char *osc_pw_frame_bounds_reason(uint32_t data_type, uint32_t maxsize, siz
 /* DMA-BUF mapoffset and shared-mapping lifecycle test helpers. */
 int osc_pw_dmabuf_mapped_len(size_t allocation_len, uint32_t mapoffset, size_t *mapped_len);
 int osc_pw_dmabuf_map_lifecycle_valid(void);
+int osc_pw_dmabuf_add_buffer_route(int fd, int prefer_dmabuf);
 
 struct osc_pw_session;
 
diff --git a/electron/native/pipewire-capture/src/shim.rs b/electron/native/pipewire-capture/src/shim.rs
index 0e1792b67b..aea145f061 100644
--- a/electron/native/pipewire-capture/src/shim.rs
+++ b/electron/native/pipewire-capture/src/shim.rs
@@ -155,6 +155,8 @@ extern "C" {
     ) -> i32;
     #[cfg(test)]
     fn osc_pw_dmabuf_map_lifecycle_valid() -> i32;
+    #[cfg(test)]
+    fn osc_pw_dmabuf_add_buffer_route(fd: i32, prefer_dmabuf: i32) -> i32;
     fn osc_pw_start(
         fd: i32,
         node_id: u32,
@@ -1542,6 +1544,31 @@ mod tests {
         assert_eq!(unsafe { osc_pw_dmabuf_map_lifecycle_valid() }, 1);
     }
 
+    /// A LINEAR dmabuf maps, and used to be read on the CPU for that reason even
+    /// with the VAAPI import available. A regular file stands in for one: it
+    /// seeks to its size and maps, which is all `osc_on_add_buffer` asks of it.
+    #[test]
+    fn a_mappable_dmabuf_goes_to_the_gpu_import_when_it_is_available() {
+        use std::os::fd::AsRawFd;
+
+        let path = std::env::temp_dir()
+            .join(format!("osc-linear-dmabuf-{}", std::process::id()));
+        std::fs::write(&path, vec![0u8; 4096]).expect("write the stand-in plane");
+        let plane = std::fs::File::open(&path).expect("open the stand-in plane");
+        let _ = std::fs::remove_file(&path);
+
+        // SAFETY: `plane` stays open across both calls; the helper builds its own
+        // synthetic session and buffer, and unmaps whatever it mapped.
+        let (cpu, gpu) = unsafe {
+            (
+                osc_pw_dmabuf_add_buffer_route(plane.as_raw_fd(), 0),
+                osc_pw_dmabuf_add_buffer_route(plane.as_raw_fd(), 1),
+            )
+        };
+        assert_eq!(cpu, 1, "without the import, a mappable plane is read on the CPU");
+        assert_eq!(gpu, 2, "with the import, it is left unmapped for the GPU");
+    }
+
     /// `maxsize` is advisory on the DMA-BUF path, so it can be arbitrarily
     /// large — and being large must not let a frame reach past what was mapped.
     #[test]

From 6ffa7466c4a1ed4be898ca7dec6e2d7a36069c42 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 22:39:05 -0700
Subject: [PATCH 11/27] perf(linux): read the dmabuf size without a dup per
 frame

dmabuf_size dup'd the plane fd, seeked the dup to its end and closed it,
three syscalls per imported frame. The dup isolated nothing: it shares
the open file description, offset included. Seek the plane's own fd
through a borrowed File instead.
---
 .../pipewire-capture/src/dmabuf_import.rs     | 38 ++++++++++++++++---
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/electron/native/pipewire-capture/src/dmabuf_import.rs b/electron/native/pipewire-capture/src/dmabuf_import.rs
index 9cc5e9ff97..2326c1185e 100644
--- a/electron/native/pipewire-capture/src/dmabuf_import.rs
+++ b/electron/native/pipewire-capture/src/dmabuf_import.rs
@@ -51,14 +51,19 @@ pub struct DmabufFrame<'a> {
 }
 
 /// A dmabuf's allocation size, from seeking its fd to the end, which is how the
-/// kernel exposes it. 0 ("let the driver find out") if that fails; the seek goes
-/// through a dup so the plane's own fd is not touched.
+/// kernel exposes it. 0 ("let the driver find out") if that fails.
+///
+/// One lseek on the plane's own fd, every frame. It used to seek a dup, which
+/// added a dup and a close per frame and isolated nothing: a dup shares the open
+/// file description, offset included, and a dmabuf's offset is never read anyway.
 fn dmabuf_size(fd: &std::os::fd::OwnedFd) -> usize {
     use std::io::{Seek, SeekFrom};
-    fd.try_clone()
-        .map(std::fs::File::from)
-        .and_then(|mut file| file.seek(SeekFrom::End(0)))
-        .map_or(0, |size| size as usize)
+    use std::os::fd::{AsRawFd, FromRawFd};
+    // SAFETY: `fd` is open for the whole call, and ManuallyDrop keeps this File
+    // from closing a descriptor it only borrows.
+    let mut file =
+        std::mem::ManuallyDrop::new(unsafe { std::fs::File::from_raw_fd(fd.as_raw_fd()) });
+    file.seek(SeekFrom::End(0)).map_or(0, |size| size as usize)
 }
 
 /// The pixel format the VAAPI-mapped surface presents, derived from the dmabuf's
@@ -501,6 +506,27 @@ mod tests {
         assert_eq!(sw_format_for_fourcc(0x3432_4241), Some(ff::AV_PIX_FMT_ABGR));
     }
 
+    // The size is read through the plane's own fd, which must still be open
+    // afterwards: the import and the PipeWire buffer's re-queue both need it.
+    #[test]
+    fn reads_the_size_without_closing_the_plane() {
+        use std::os::fd::{AsRawFd, OwnedFd};
+
+        let path = std::env::temp_dir().join(format!("osc-dmabuf-size-{}", std::process::id()));
+        std::fs::write(&path, vec![0u8; 8192]).expect("write the stand-in plane");
+        let plane = OwnedFd::from(std::fs::File::open(&path).expect("open the stand-in plane"));
+        let _ = std::fs::remove_file(&path);
+
+        assert_eq!(dmabuf_size(&plane), 8192);
+        assert_eq!(dmabuf_size(&plane), 8192);
+        // SAFETY: F_GETFD only queries the descriptor.
+        assert_ne!(unsafe { fcntl(plane.as_raw_fd(), 1) }, -1, "the plane fd was closed");
+    }
+
+    extern "C" {
+        fn fcntl(fd: i32, cmd: i32, ...) -> i32;
+    }
+
     #[test]
     fn rejects_a_fourcc_we_do_not_negotiate() {
         // "NV12" is a real fourcc, just not one of our packed RGB layouts.

From 7a17de8e58f1c53f5155c91eac29157ee59009e8 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 22:39:05 -0700
Subject: [PATCH 12/27] fix(linux): find the granted Hyprland monitor by its
 size

The granted monitor was matched by the portal's position first.
xdg-desktop-portal-hyprland reported (0, 0) for a 4K monitor placed at
(1536, 0), which is where the laptop panel sat, so the panel was picked
and every pointer position landed past its right edge: the editable
cursor was never visible and there was nothing to zoom on.

Match by size first, and use the position only to tell two monitors of
the same size apart or when no size matches.
---
 .../native/pipewire-capture/src/hyprland.rs   | 74 +++++++++++++------
 1 file changed, 51 insertions(+), 23 deletions(-)

diff --git a/electron/native/pipewire-capture/src/hyprland.rs b/electron/native/pipewire-capture/src/hyprland.rs
index d8497f45e1..d9531e1dd7 100644
--- a/electron/native/pipewire-capture/src/hyprland.rs
+++ b/electron/native/pipewire-capture/src/hyprland.rs
@@ -111,37 +111,50 @@ pub fn query_monitors(socket: &PathBuf) -> Result<Vec<Monitor>, String> {
 
 /// The granted monitor's place in the layout: (position, logical size).
 ///
-/// Found by the position the portal reports, which is the layout's; failing a
-/// single match there, by its size, which this portal gives in physical pixels
-/// (a mode) and others in logical ones. None when neither is unambiguous: a
-/// position guessed on the wrong monitor would be worse than none.
+/// Found by the size the portal reports, which this portal gives in physical
+/// pixels (a mode) and others in logical ones, and only then by its position.
+/// The position is not to be trusted first: xdg-desktop-portal-hyprland reported
+/// (0, 0) for a 4K monitor placed at (1536, 0), which is where the laptop panel
+/// sat, so every position landed past the panel's right edge and the take had no
+/// visible cursor. It still tells two monitors of one size apart, and stands in
+/// when no size matches. None when neither is unambiguous: a position guessed on
+/// the wrong monitor would be worse than none.
 fn only<'a>(found: Vec<&'a Monitor>) -> Option<&'a Monitor> {
     (found.len() == 1).then(|| found[0])
 }
 
+fn at_position<'a>(
+    candidates: Vec<&'a Monitor>,
+    position: Option<(i32, i32)>,
+) -> Option<&'a Monitor> {
+    let position = position?;
+    only(candidates.into_iter().filter(|m| (m.x, m.y) == position).collect())
+}
+
 pub fn granted_monitor(
     monitors: &[Monitor],
     portal_position: Option<(i32, i32)>,
     portal_size: Option<(i32, i32)>,
 ) -> Option<((i32, i32), (i32, i32))> {
-    let monitor = portal_position
-        .and_then(|position| only(monitors.iter().filter(|m| (m.x, m.y) == position).collect()))
-        .or_else(|| {
-            let size = portal_size?;
-            only(
-                monitors
-                    .iter()
-                    .filter(|m| {
-                        let mode = if m.transform % 2 == 1 {
-                            (m.height, m.width)
-                        } else {
-                            (m.width, m.height)
-                        };
-                        mode == size || m.logical_size() == size
-                    })
-                    .collect(),
-            )
-        })?;
+    let sized: Vec<&Monitor> = match portal_size {
+        Some(size) => monitors
+            .iter()
+            .filter(|m| {
+                let mode = if m.transform % 2 == 1 {
+                    (m.height, m.width)
+                } else {
+                    (m.width, m.height)
+                };
+                mode == size || m.logical_size() == size
+            })
+            .collect(),
+        None => Vec::new(),
+    };
+    let monitor = match sized.len() {
+        0 => at_position(monitors.iter().collect(), portal_position),
+        1 => Some(sized[0]),
+        _ => at_position(sized, portal_position),
+    }?;
     Some(((monitor.x, monitor.y), monitor.logical_size()))
 }
 
@@ -296,13 +309,28 @@ mod tests {
     }
 
     #[test]
-    fn finds_the_granted_monitor_by_its_place_in_the_layout() {
+    fn finds_the_granted_monitor_by_its_size() {
         assert_eq!(
             granted_monitor(&monitors(), Some((1920, 0)), Some((3072, 1920))),
             Some(((1920, 0), (1536, 960)))
         );
     }
 
+    /// Measured: the panel at (0, 0), the 4K monitor to its right at (1536, 0),
+    /// and the portal granting the 4K monitor while reporting it at (0, 0).
+    #[test]
+    fn trusts_the_size_over_a_position_that_names_the_other_monitor() {
+        let layout: Vec<Monitor> = serde_json::from_str(
+            r#"[{"name":"eDP-1","x":0,"y":0,"width":3072,"height":1920,"scale":2.0,"transform":0},
+                {"name":"HDMI-A-1","x":1536,"y":0,"width":3840,"height":2160,"scale":2.0,"transform":0}]"#,
+        )
+        .unwrap();
+        assert_eq!(
+            granted_monitor(&layout, Some((0, 0)), Some((3840, 2160))),
+            Some(((1536, 0), (1920, 1080)))
+        );
+    }
+
     #[test]
     fn takes_the_scale_from_hyprland_not_from_the_portals_physical_size() {
         // The portal reports 3840x2160 for the 4K monitor; the layout is 1920x1080.

From 26e1d3ec3c79e9bcc6b2ac660b93abcf6823f331 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Tue, 27 Oct 2026 22:46:59 -0700
Subject: [PATCH 13/27] feat(linux): auto-zoom system-cursor takes on Hyprland

The helper polled Hyprland's pointer only when the editable cursor was
asked for, so a take with the system cursor painted in had no positions
and therefore no auto-zoom or click sounds.

Poll for the system cursor (EMBEDDED) too. The app already keeps those
samples apart in <video>.pointer.json, which places zooms and click
sounds and is never drawn over the painted pointer. A HIDDEN request
still gets no positions, and nothing is polled where the portal reports
the pointer itself.
---
 electron/native/pipewire-capture/src/main.rs | 62 ++++++++++++++++----
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 08a1022acf..9fe0d773d6 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -299,16 +299,12 @@ fn main() {
         Err(error) => fail(&mut emitter, error.code(), &error.message()),
     };
     let cursor_metadata_supported = offered_cursor_modes.contains(&portal::CursorMode::Metadata);
-    // The editable cursor was asked for and the portal cannot report the pointer
-    // (Hyprland's offers no METADATA): Hyprland's IPC can, so the pointer is kept out
-    // of the pixels (HIDDEN) and the editor draws it from these positions, or, where
-    // the portal cannot keep it out, it is painted in and the positions still place
-    // zooms. See `hyprland.rs`.
-    let hyprland_socket = (cursor_mode.reports_cursor()
-        && !cursor_metadata_supported
-        && output_path.is_some())
-    .then(hyprland::socket_path)
-    .flatten();
+    // The portal cannot report the pointer (Hyprland's offers no METADATA), but
+    // Hyprland's IPC can. See `polls_host_pointer` and `hyprland.rs`.
+    let hyprland_socket =
+        polls_host_pointer(cursor_mode, cursor_metadata_supported, output_path.is_some())
+            .then(hyprland::socket_path)
+            .flatten();
     // Resolved before anything reads it, so the portal, the click readers and
     // `ready` all see the mode that is really negotiated.
     let cursor_mode = cursor_mode.resolve(
@@ -648,6 +644,27 @@ struct SharedMemoryFallback {
 
 /// Whether a crop-less window frame is held back rather than opening the encoder.
 /// See MAX_CROP_WAIT.
+/// Whether a recording takes pointer positions from the compositor's IPC, for a
+/// portal that cannot report them (no METADATA).
+///
+/// The editable cursor (METADATA asked for): the pointer is kept out of the pixels
+/// (HIDDEN) and the editor draws it from these positions, or, where the portal
+/// cannot keep it out, it is painted in and the positions still place zooms. The
+/// system cursor (EMBEDDED): it is painted in either way, and the positions go to
+/// `.pointer.json`, where they place zooms and click sounds and are never drawn.
+/// A HIDDEN request wants no pointer at all, so it gets none.
+fn polls_host_pointer(
+    requested: portal::CursorMode,
+    cursor_metadata_supported: bool,
+    records_video: bool,
+) -> bool {
+    let wants_positions = matches!(
+        requested,
+        portal::CursorMode::Metadata | portal::CursorMode::Embedded
+    );
+    wants_positions && !cursor_metadata_supported && records_video
+}
+
 fn holds_for_crop(expecting_crop: bool, waited: Duration) -> bool {
     expecting_crop && waited < MAX_CROP_WAIT
 }
@@ -2029,6 +2046,31 @@ mod microphone_resolution_tests {
     }
 }
 
+#[cfg(test)]
+mod host_pointer_tests {
+    use super::polls_host_pointer;
+    use crate::portal::CursorMode;
+
+    #[test]
+    fn both_cursor_choices_take_positions_where_the_portal_has_none() {
+        // Hyprland: no METADATA. The editable cursor is drawn from the positions;
+        // the system cursor is painted in, and they place its zooms.
+        assert!(polls_host_pointer(CursorMode::Metadata, false, true));
+        assert!(polls_host_pointer(CursorMode::Embedded, false, true));
+    }
+
+    #[test]
+    fn nothing_is_polled_that_nothing_would_use() {
+        // The portal reports the pointer itself.
+        assert!(!polls_host_pointer(CursorMode::Metadata, true, true));
+        assert!(!polls_host_pointer(CursorMode::Embedded, true, true));
+        // A cursor-only session has no take to place zooms in.
+        assert!(!polls_host_pointer(CursorMode::Embedded, false, false));
+        // HIDDEN asks for no pointer at all.
+        assert!(!polls_host_pointer(CursorMode::Hidden, false, true));
+    }
+}
+
 #[cfg(test)]
 mod capture_fallback_tests {
     use super::{

From dfb078f40ee89928eb7d1326364961893e9e6493 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:16:15 -0700
Subject: [PATCH 14/27] fix(linux): keep audio and video aligned when the first
 frame waits for its crop

Arrival slots counted from the first frame's arrival and the audio from
the epoch, when that frame was staged. A window's first frame can be
replayed after waiting up to MAX_CROP_WAIT for its crop, so every later
frame landed that far ahead of the audio and the file ran that much
longer than the take.

Clamp the first arrival to at most one slot before the epoch. A frame
delivered normally keeps its own arrival as zero, which is what places
frames in the slot they arrived in; a late replay no longer moves the
video. A test stages a first frame 400 ms late: without the fix the next
frame lands in slot 12.

Also bracket the held-picture assertion's clock read, which could fail
when a slot boundary fell between two reads, and add a test that frames
after a pause are placed by active time.
---
 .../native/pipewire-capture/src/capture.rs    | 87 ++++++++++++++++++-
 1 file changed, 85 insertions(+), 2 deletions(-)

diff --git a/electron/native/pipewire-capture/src/capture.rs b/electron/native/pipewire-capture/src/capture.rs
index 602a7338df..037d0452bf 100644
--- a/electron/native/pipewire-capture/src/capture.rs
+++ b/electron/native/pipewire-capture/src/capture.rs
@@ -551,7 +551,17 @@ impl Capture {
 
     fn mark_staged(&mut self, arrived: Instant) {
         self.mark_started();
-        self.first_arrival.get_or_insert(arrived);
+        // The arrival slots count from here, the audio from the epoch, so the two
+        // must agree. A frame normally reaches staging well inside one slot, and
+        // its own arrival is the better zero (see `advance`). A window's first
+        // frame can instead be replayed after waiting up to MAX_CROP_WAIT for its
+        // crop: counting from that arrival put every later frame that far ahead
+        // of the audio, and the file that much longer than the take.
+        if let Some(epoch) = self.epoch {
+            let slot = Duration::from_nanos(1_000_000_000 / self.fps.max(1) as u64);
+            let oldest = epoch.checked_sub(slot).unwrap_or(epoch);
+            self.first_arrival.get_or_insert(arrived.max(oldest));
+        }
         self.staged_arrival = Some(arrived);
     }
 
@@ -944,8 +954,81 @@ mod tests {
         assert_eq!(capture.next_index, 2, "written at its arrival slot, not the clock's");
 
         // The held picture is then re-stamped HELD_FRAME_LAG_SLOTS behind the clock.
+        // `advance` reads the clock itself, so bracket that read: a slot boundary
+        // between it and a second read here would fail an exact comparison.
+        let before = capture.current_index();
+        assert_eq!(capture.advance().expect("advance"), 1);
+        let after = capture.current_index();
+        let stamped = capture.next_index - 1 + HELD_FRAME_LAG_SLOTS;
+        assert!(
+            (before..=after).contains(&stamped),
+            "held picture stamped at clock {stamped}, outside the {before}..={after} it was read in"
+        );
+        let _ = std::fs::remove_file(&output);
+    }
+
+    /// Arrival slots count active time only: a frame after a pause lands right
+    /// after the one before it, not the length of the pause later.
+    #[test]
+    fn a_frame_after_a_pause_is_placed_by_active_time() {
+        let output = std::env::temp_dir().join("openscreen-capture-arrival-pause.mp4");
+        let (mut capture, _) =
+            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
+                .expect("start");
+        let format = shim::constants().video_format_bgrx;
+        let mut frame_at = |arrived: Instant| {
+            let mut f = frame(320, 240, format);
+            f.arrived = arrived;
+            f
+        };
+
+        capture.stage(&frame_at(Instant::now())).expect("stage");
+        assert_eq!(capture.advance().expect("advance"), 1);
+
+        // 300 ms paused is 9 slots at 30 fps.
+        capture.pause();
+        std::thread::sleep(Duration::from_millis(300));
+        capture.resume();
+
+        capture.stage(&frame_at(Instant::now())).expect("stage");
+        assert_eq!(capture.advance().expect("advance"), 1);
+        assert!(
+            capture.next_index <= 3,
+            "the frame after the pause was stamped at slot {}, counting the pause",
+            capture.next_index - 1
+        );
+        let _ = std::fs::remove_file(&output);
+    }
+
+    /// A window's first frame can wait up to MAX_CROP_WAIT for its crop and is
+    /// staged late. The next frame must still land where the audio clock is,
+    /// not that long after it.
+    #[test]
+    fn a_first_frame_staged_late_does_not_push_the_video_ahead_of_the_audio() {
+        let output = std::env::temp_dir().join("openscreen-capture-late-first.mp4");
+        let (mut capture, _) =
+            Capture::start(&output, 320, 240, 30, Some(1_000_000), Some(Backend::Software), Vec::new(), None)
+                .expect("start");
+        let format = shim::constants().video_format_bgrx;
+        let mut frame_at = |arrived: Instant| {
+            let mut f = frame(320, 240, format);
+            f.arrived = arrived;
+            f
+        };
+
+        // Arrived 400 ms (12 slots at 30 fps) before it could be staged.
+        let staged = Instant::now();
+        capture.stage(&frame_at(staged - Duration::from_millis(400))).expect("stage");
+        assert_eq!(capture.advance().expect("advance"), 1);
+
+        // The next frame arrives right after: it belongs near slot 1, not 13.
+        capture.stage(&frame_at(Instant::now())).expect("stage");
         assert_eq!(capture.advance().expect("advance"), 1);
-        assert_eq!(capture.next_index, capture.current_index() - HELD_FRAME_LAG_SLOTS + 1);
+        assert!(
+            capture.next_index <= 3,
+            "the second frame was stamped at slot {}, ahead of the audio",
+            capture.next_index - 1
+        );
         let _ = std::fs::remove_file(&output);
     }
 

From 0ccdf9267e28bea7ab95f12ee0e4c4b80a1cfbfc Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:16:16 -0700
Subject: [PATCH 15/27] fix(linux): harden the Hyprland pointer path

- The socket has to answer a cursorpos query before it counts. It
  decides HIDDEN, and a HIDDEN take with no positions has no cursor
  anywhere.
- Forget the last position when the poll is lost, so a later click is
  not recorded there and does not place a zoom on it.
- Warn once at stream start when the portal does not say what kind of
  source it shared; those takes dropped every sample in silence.
---
 electron/native/pipewire-capture/src/main.rs | 23 ++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 9fe0d773d6..8d07d59094 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -300,11 +300,14 @@ fn main() {
     };
     let cursor_metadata_supported = offered_cursor_modes.contains(&portal::CursorMode::Metadata);
     // The portal cannot report the pointer (Hyprland's offers no METADATA), but
-    // Hyprland's IPC can. See `polls_host_pointer` and `hyprland.rs`.
+    // Hyprland's IPC can. See `polls_host_pointer` and `hyprland.rs`. The socket
+    // has to ANSWER, not just exist: it decides HIDDEN below, and a HIDDEN take
+    // with no positions has no cursor anywhere, painted or drawn.
     let hyprland_socket =
         polls_host_pointer(cursor_mode, cursor_metadata_supported, output_path.is_some())
             .then(hyprland::socket_path)
-            .flatten();
+            .flatten()
+            .filter(|socket| hyprland::query_cursor(socket).is_ok());
     // Resolved before anything reads it, so the portal, the click readers and
     // `ready` all see the mode that is really negotiated.
     let cursor_mode = cursor_mode.resolve(
@@ -884,6 +887,10 @@ fn run<W: Write>(
             }
 
             Ok(Message::HostPointerLost(reason)) => {
+                // Forget the last position: a click after this would otherwise be
+                // recorded there, wherever the pointer has since gone, and place a
+                // zoom on it.
+                cursor = None;
                 let _ = emitter.emit(&Event::Warning {
                     code: "cursor-positions-lost".to_owned(),
                     message: format!(
@@ -1230,6 +1237,18 @@ fn run<W: Write>(
                                 }
                             }
                         }
+                        // Every other missing-position case says so; this one used to
+                        // drop each sample in silence. A window is reported by the
+                        // HostPointer branch, once it has a sample to drop.
+                        (Some(_), None) => {
+                            let _ = emitter.emit(&Event::Warning {
+                                code: "cursor-positions-unavailable".to_owned(),
+                                message: "the portal did not say whether it shared a monitor or a \
+                                          window, so this recording has no cursor positions"
+                                    .to_owned(),
+                            });
+                            None
+                        }
                         _ => None,
                     };
 

From c5a61323d6c5c766b6ac3fa77de7fbc088ac5cce Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:16:16 -0700
Subject: [PATCH 16/27] fix: keep painted-in takes painted-in

- CursorTrack::smoothed dropped the painted_in marker on its early
  return, so with cursor smoothing off a system-cursor take drew a
  second cursor over the one in the video.
- The Linux webcam attach rebuilt the session without pointerTelemetry;
  it now sets it when the take's .pointer.json exists.
- The agent's cursor reader falls back to .pointer.json through a new
  readCursorActivity, as the editor's reader already does.
---
 crates/compositor/src/cursor.rs      | 19 ++++++++++++------
 electron/ipc/handlers.ts             | 15 +++++++++++---
 electron/media/cursorSidecar.test.ts | 29 ++++++++++++++++++++++++++++
 electron/media/cursorSidecar.ts      | 27 +++++++++++++++++++++++++-
 4 files changed, 80 insertions(+), 10 deletions(-)

diff --git a/crates/compositor/src/cursor.rs b/crates/compositor/src/cursor.rs
index 6ca4439121..b0e9c339a4 100644
--- a/crates/compositor/src/cursor.rs
+++ b/crates/compositor/src/cursor.rs
@@ -502,12 +502,17 @@ impl CursorTrack {
     /// bruts (le bounce est temporel, pas positionnel — ne doit pas suivre le lissage).
     pub fn smoothed(&self, factor: f32) -> CursorTrack {
         if self.samples.len() < 2 || factor <= 0.0 {
-            return CursorTrack::new_with_visibility(
-                self.samples.clone(),
-                self.clicks.clone(),
-                self.types.clone(),
-                self.visibility.clone(),
-            );
+            // Le marqueur suit ici aussi : lissage coupé, une prise peinte dessinait sinon un
+            // second curseur par-dessus le sien.
+            return CursorTrack {
+                painted_in: self.painted_in,
+                ..CursorTrack::new_with_visibility(
+                    self.samples.clone(),
+                    self.clicks.clone(),
+                    self.types.clone(),
+                    self.visibility.clone(),
+                )
+            };
         }
         const STEP_S: f32 = 1.0 / 240.0;
         let start = self.samples[0].0;
@@ -1202,6 +1207,8 @@ mod tests {
         assert!(track.at(1.0).is_some());
         // Le lissage (slider « smoothing ») garde le marqueur : sinon le curseur réapparaît.
         assert!(track.smoothed(0.5).painted_in());
+        // Lissage coupé (0) : le chemin court garde le marqueur, lui aussi.
+        assert!(track.smoothed(0.0).painted_in());
 
         // Un `.cursor.json` présent l'emporte, et se dessine.
         std::fs::write(&cursor_json, r#"{"samples":[{"timeMs":0,"cx":0.5,"cy":0.5}]}"#)
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 3ad4b32293..47019914bb 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -91,8 +91,8 @@ import { createToolRunner, type McpToolDeps } from "../mcp/openscreen-mcp-server
 import { type AudioPeaksResult, getAudioPeaks } from "../media/audioPeaks";
 import {
 	POINTER_TELEMETRY_SUFFIX,
+	readCursorActivity,
 	readCursorRecordingFile as readCursorRecordingFileFrom,
-	readCursorSidecar,
 	readCursorTelemetryFile as readCursorTelemetryFileFrom,
 } from "../media/cursorSidecar";
 import { findMediaLinksByFingerprint, registerMediaLinks } from "../media/mediaLinksRegistry";
@@ -1058,7 +1058,7 @@ const agentCursorTelemetryReader: CursorTelemetryReader = {
 	probe: async ({ originalPath }) => {
 		const approved = resolveApprovedVideoPath(originalPath);
 		if (!approved) return false;
-		return (await readCursorSidecar(approved, cursorSidecarOptions())).found;
+		return (await readCursorActivity(approved, cursorSidecarOptions())).found;
 	},
 	read: async ({ assetId, originalPath }) => {
 		const approved = resolveApprovedVideoPath(originalPath);
@@ -1069,7 +1069,7 @@ const agentCursorTelemetryReader: CursorTelemetryReader = {
 				note: "The asset's file is outside the folders this app may read, so its cursor sidecar was not opened.",
 			};
 		}
-		const sidecar = await readCursorSidecar(approved, cursorSidecarOptions());
+		const sidecar = await readCursorActivity(approved, cursorSidecarOptions());
 		if (!sidecar.found) return { status: "no-sidecar", assetId };
 		return { status: "ok", assetId, samples: sidecar.data.samples };
 	},
@@ -3937,12 +3937,21 @@ export function registerIpcHandlers(
 				const webcamOffsetMs = Number.isFinite(payload.webcamOffsetMs)
 					? payload.webcamOffsetMs
 					: undefined;
+				// This session replaces the one the stopped take stored, so it carries that
+				// take's pointer telemetry forward: read from the file, which is what set it.
+				const pointerTelemetry =
+					cursorCaptureMode === "system" &&
+					(await fs
+						.access(`${screenVideoPath}${POINTER_TELEMETRY_SUFFIX}`, fsConstants.F_OK)
+						.then(() => true)
+						.catch(() => false));
 				const session: RecordingSession = {
 					screenVideoPath,
 					webcamVideoPath,
 					createdAt,
 					...(webcamOffsetMs !== undefined ? { webcamOffsetMs } : {}),
 					...(cursorCaptureMode ? { cursorCaptureMode } : {}),
+					...(pointerTelemetry ? { pointerTelemetry: true } : {}),
 				};
 				setCurrentRecordingSessionState(session);
 				currentProjectPath = null;
diff --git a/electron/media/cursorSidecar.test.ts b/electron/media/cursorSidecar.test.ts
index 8fdcce2bcb..7899829b62 100644
--- a/electron/media/cursorSidecar.test.ts
+++ b/electron/media/cursorSidecar.test.ts
@@ -14,6 +14,7 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
 	POINTER_TELEMETRY_SUFFIX,
+	readCursorActivity,
 	readCursorRecordingFile,
 	readCursorRecordingFileAt,
 	readCursorSidecar,
@@ -214,6 +215,34 @@ describe("readCursorTelemetryFile", () => {
 		expect((await readCursorRecordingFile(video, {})).samples).toEqual([]);
 	});
 
+	it("gives the agent the pointer telemetry of a painted-in take", async () => {
+		const video = path.join(dir, "painted-agent.mp4");
+		await fs.writeFile(
+			`${video}${POINTER_TELEMETRY_SUFFIX}`,
+			JSON.stringify({ samples: [{ timeMs: 10, cx: 0.25, cy: 0.75, interactionType: "click" }] }),
+			"utf-8",
+		);
+
+		const activity = await readCursorActivity(video, {});
+
+		expect(activity.found).toBe(true);
+		expect(activity.source).toBe("pointer");
+		expect(activity.data.samples.map((sample) => sample.cx)).toEqual([0.25]);
+		// The drawable lookup still finds nothing.
+		expect((await readCursorSidecar(video, {})).found).toBe(false);
+	});
+
+	it("reports a malformed pointer telemetry file as not found", async () => {
+		const video = path.join(dir, "painted-broken.mp4");
+		await fs.writeFile(`${video}${POINTER_TELEMETRY_SUFFIX}`, "{ not json", "utf-8");
+		vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+		const activity = await readCursorActivity(video, {});
+
+		expect(activity.found).toBe(false);
+		expect(activity.source).toBe("none");
+	});
+
 	it("prefers the drawable sidecar when a take has both", async () => {
 		const video = path.join(dir, "both.mp4");
 		await writeSidecar(video, { samples: [{ timeMs: 10, cx: 0.1, cy: 0.1 }] });
diff --git a/electron/media/cursorSidecar.ts b/electron/media/cursorSidecar.ts
index 2fc62d3b7c..7e16ad5ff2 100644
--- a/electron/media/cursorSidecar.ts
+++ b/electron/media/cursorSidecar.ts
@@ -39,7 +39,7 @@ export const POINTER_TELEMETRY_SUFFIX = ".pointer.json";
 /** Where a sidecar was found, or why it was not. `"none"` means we LOOKED and
  * there was nothing — distinct from never having looked, which this module
  * cannot represent and its callers must not conflate. */
-export type CursorSidecarSource = "sidecar" | "registry" | "none";
+export type CursorSidecarSource = "sidecar" | "registry" | "pointer" | "none";
 
 export interface CursorSidecarResult {
 	found: boolean;
@@ -226,6 +226,31 @@ export async function readCursorSidecar(
 	return { found: false, source: "none", path: null, data: emptyRecording() };
 }
 
+/** Where the user acted, for the agent: the take's cursor sidecar, or, for a take with
+ * the pointer painted in, its `.pointer.json`, the fallback `readCursorTelemetryFile`
+ * makes for the editor. Never for drawing a cursor: see `POINTER_TELEMETRY_SUFFIX`.
+ * Like `readCursorSidecar`, a malformed file reports `found: false`. */
+export async function readCursorActivity(
+	targetVideoPath: string,
+	options: { recordingsDir?: string },
+): Promise<CursorSidecarResult> {
+	const sidecar = await readCursorSidecar(targetVideoPath, options);
+	const pointerPath = `${targetVideoPath}${POINTER_TELEMETRY_SUFFIX}`;
+	if (sidecar.found || !(await fileExists(pointerPath))) {
+		return sidecar;
+	}
+	try {
+		return {
+			found: true,
+			source: "pointer",
+			path: pointerPath,
+			data: await readCursorRecordingFileAt(pointerPath),
+		};
+	} catch {
+		return sidecar;
+	}
+}
+
 /** The shape the renderer's `loadCursorRecordingData` has always returned: the
  * recording data alone, with "not found" flattened into an empty payload. */
 export async function readCursorRecordingFile(

From 6a973ae5a3abfd6719f1aa46a0719d5120fabcab Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:16:16 -0700
Subject: [PATCH 17/27] fix(linux): HUD panel review fixes

- Mirrored toasts default to the app toaster's 3000 ms, shared as
  TOAST_DURATION_MS, restart their timer when replaced under the same
  id, read a function-valued description once, and label the dismiss
  button in the app's language.
- The panel goes below the bar only when it fits there or has more
  room, is repositioned on every resize on X11, is shown again with the
  bar while it has content, and is only used where a panel bridge exists
  (the browser shim also reads as Linux).
- Docs: on NixOS a mouse already plugged in gets the rule after a
  replug or a reboot.
- The package-script tests check the mapping inside fpm, both device
  classes, and that the udevadm calls sit inside their guard.
---
 electron/hyprland.test.ts                     |  9 ++++
 electron/hyprland.ts                          | 11 ++++-
 electron/windows.ts                           | 33 +++++++++-----
 scripts/linux-package-scripts.test.mjs        | 23 +++++++---
 src/components/launch/HudPanelWindow.test.tsx | 44 +++++++++++++++++--
 src/components/launch/HudPanelWindow.tsx      | 17 ++++---
 src/components/launch/LaunchWindow.test.tsx   | 11 +++++
 src/components/launch/LaunchWindow.tsx        |  7 ++-
 src/components/launch/hudPanel.ts             |  4 +-
 src/components/ui/sonner.tsx                  |  6 ++-
 website/docs/installation.md                  |  2 +-
 11 files changed, 134 insertions(+), 33 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index 58b73d6fe5..8e04d27385 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -29,6 +29,15 @@ describe("panelPositionNearBar", () => {
 		});
 	});
 
+	it("stays above the bar when below has even less room", () => {
+		// 140 px free above, 92 below: neither fits a 300 px panel.
+		const bar = { x: 672, y: 170, width: 576, height: 800 };
+		expect(panelPositionNearBar(bar, { width: 382, height: 300 }, workArea, 8)).toEqual({
+			x: 769,
+			y: 22,
+		});
+	});
+
 	it("stays inside the work area at a screen edge", () => {
 		const bar = { x: 1700, y: 900, width: 200, height: 150 };
 		expect(panelPositionNearBar(bar, { width: 382, height: 300 }, workArea, 8)).toEqual({
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index f7ba5f17b7..08eef4f539 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -91,7 +91,8 @@ export function monitorWorkArea(monitor: HyprlandMonitor): Rect {
 
 /**
  * Where the panel goes: centred on the bar, above it with `gap` between, or below it when there
- * is not room above; then kept inside the work area.
+ * is room below and not above. When neither side has room it takes the roomier one, so the clamp
+ * into the work area covers as little of the bar as it can.
  */
 export function panelPositionNearBar(
 	bar: Rect,
@@ -100,7 +101,13 @@ export function panelPositionNearBar(
 	gap: number,
 ): { x: number; y: number } {
 	const above = bar.y - gap - panel.height;
-	const y = above >= workArea.y ? above : bar.y + bar.height + gap;
+	const below = bar.y + bar.height + gap;
+	const roomAbove = bar.y - gap - workArea.y;
+	const roomBelow = workArea.y + workArea.height - below;
+	let y = above;
+	if (panel.height > roomAbove) {
+		y = panel.height <= roomBelow || roomBelow > roomAbove ? below : above;
+	}
 	const x = bar.x + (bar.width - panel.width) / 2;
 	const clamp = (value: number, min: number, max: number) =>
 		Math.round(Math.min(Math.max(value, min), Math.max(min, max)));
diff --git a/electron/windows.ts b/electron/windows.ts
index 863933afa9..ad95951fe0 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -556,6 +556,13 @@ export function createHudOverlayWindow(): BrowserWindow {
 	// The panel belongs to the bar: hidden with it, and its popovers closed when focus
 	// leaves the pair (see checkHudPanelFocus).
 	win.on("hide", () => hudPanelWindow?.hide());
+	// And back with it: a notice still in the state sends no new size report to bring it.
+	win.on("show", () => {
+		const panel = hudPanelWindow;
+		if (panel && !panel.isDestroyed() && hudPanelState && hudPanelHasContent(hudPanelState)) {
+			revealHudPanel(panel, hudPanelState);
+		}
+	});
 	win.on("blur", checkHudPanelFocus);
 
 	if (VITE_DEV_SERVER_URL) {
@@ -720,6 +727,18 @@ ipcMain.on("hud-panel-action", (event, action: HudPanelAction) => {
 	sendToHud(action);
 });
 
+/** Shows the panel and places it at the bar. A popover takes focus, so its keyboard handling
+ * works straight away; a notice or a toast appearing must not pull focus away from whatever the
+ * user is doing. */
+function revealHudPanel(win: BrowserWindow, state: HudPanelState) {
+	if (hudPanelHasPopover(state)) {
+		win.show();
+	} else {
+		win.showInactive();
+	}
+	placeHudPanel();
+}
+
 ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
 	const win = hudPanelWindow;
 	if (!win || win.isDestroyed() || event.sender !== win.webContents) return;
@@ -732,9 +751,10 @@ ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
 		win.setContentSize(size.width, size.height);
 	}
 	// Above the bar where the platform honours a position (X11). Wayland ignores it and the
-	// compositor places the window, which is the point of having one.
+	// compositor places the window, which is the point of having one. Again on a resize: the
+	// window grows from its top-left, so a taller panel would reach down over the bar.
 	const hud = hudOverlayWindow;
-	if (hud && !hud.isDestroyed() && !win.isVisible()) {
+	if (hud && !hud.isDestroyed() && (!win.isVisible() || resized)) {
 		const bar = hud.getBounds();
 		const workArea = screen.getDisplayMatching(bar).workArea;
 		const x = Math.round(bar.x + (bar.width - size.width) / 2);
@@ -745,14 +765,7 @@ ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
 		);
 	}
 	if (!win.isVisible()) {
-		// A popover takes focus, so its keyboard handling works straight away; a notice or a
-		// toast appearing must not pull focus away from whatever the user is doing.
-		if (hudPanelHasPopover(hudPanelState)) {
-			win.show();
-		} else {
-			win.showInactive();
-		}
-		placeHudPanel();
+		revealHudPanel(win, hudPanelState);
 	} else if (resized) {
 		// Hyprland keeps a resized floating window centred where it was, off the bar's edge.
 		placeHudPanel();
diff --git a/scripts/linux-package-scripts.test.mjs b/scripts/linux-package-scripts.test.mjs
index f0e4cc2c6f..1e7ffc60ad 100644
--- a/scripts/linux-package-scripts.test.mjs
+++ b/scripts/linux-package-scripts.test.mjs
@@ -56,13 +56,16 @@ describe("Linux package install scripts", () => {
 			// The udev daemon is absent in a chroot or a container; the install must not fail
 			// there, so the calls sit behind a guard and are never fatal.
 			expect(appended).toContain("[ -S /run/udev/control ]");
-			const calls = appended
-				.split("\n")
-				.map((line) => line.trim())
-				.filter((line) => line.startsWith("udevadm "));
+			const appendedLines = appended.split("\n").map((line) => line.trim());
+			const guard = appendedLines.findIndex((line) => line.includes("[ -S /run/udev/control ]"));
+			const calls = appendedLines.flatMap((line, index) =>
+				line.startsWith("udevadm ") ? [{ line, index }] : [],
+			);
 			expect(calls).toHaveLength(2);
 			for (const call of calls) {
-				expect(call).toMatch(/\|\| true$/);
+				expect(call.line).toMatch(/\|\| true$/);
+				// Inside the guard, not merely somewhere in the block.
+				expect(call.index).toBeGreaterThan(guard);
 			}
 		});
 	}
@@ -73,7 +76,10 @@ describe("Linux package install scripts", () => {
 			expect(block, `no "${target}" block in electron-builder.json5`).toBeTruthy();
 			expect(block).toMatch(/"afterInstall"\s*:\s*"build\/linux\/after-install\.tpl"/);
 			expect(block).toMatch(/"afterRemove"\s*:\s*"build\/linux\/after-remove\.tpl"/);
-			expect(block).toContain(`"${RULE_SOURCE}=${RULE_TARGET}"`);
+			// In the `fpm` arguments, the one key that maps a file into the package.
+			const fpm = block.match(/"fpm"\s*:\s*\[([^\]]*)\]/)?.[1];
+			expect(fpm, `no "fpm" array in the ${target} block`).toBeTruthy();
+			expect(fpm).toContain(`"${RULE_SOURCE}=${RULE_TARGET}"`);
 		});
 	}
 });
@@ -88,7 +94,10 @@ describe("pointer udev rule", () => {
 	});
 
 	it("tags only mice and touchpads, and never a node that reports keyboard keys", () => {
-		expect(lines.length).toBeGreaterThan(0);
+		// Both classes: dropping either line would leave every check below passing.
+		for (const kind of ["MOUSE", "TOUCHPAD"]) {
+			expect(lines.some((line) => line.includes(`ENV{ID_INPUT_${kind}}=="1"`))).toBe(true);
+		}
 		for (const line of lines) {
 			expect(line).toContain('SUBSYSTEM=="input"');
 			expect(line).toContain('KERNEL=="event*"');
diff --git a/src/components/launch/HudPanelWindow.test.tsx b/src/components/launch/HudPanelWindow.test.tsx
index 435799f367..271a5acada 100644
--- a/src/components/launch/HudPanelWindow.test.tsx
+++ b/src/components/launch/HudPanelWindow.test.tsx
@@ -2,6 +2,7 @@
 import "@testing-library/jest-dom";
 import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { I18nProvider } from "@/contexts/I18nContext";
 import { TooltipProvider } from "../ui/tooltip";
 import type { HudDeviceSettingsLabels } from "./HudDeviceSettings";
 import { HudPanelWindow } from "./HudPanelWindow";
@@ -71,9 +72,11 @@ afterEach(() => {
 
 function renderPanel(state: HudPanelState) {
 	render(
-		<TooltipProvider>
-			<HudPanelWindow />
-		</TooltipProvider>,
+		<I18nProvider>
+			<TooltipProvider>
+				<HudPanelWindow />
+			</TooltipProvider>
+		</I18nProvider>,
 	);
 	act(() => pushState?.(state));
 }
@@ -170,6 +173,41 @@ describe("HudPanelWindow", () => {
 		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "fail" }]);
 	});
 
+	it("times a toast with no duration of its own like the app's toaster", () => {
+		vi.useFakeTimers();
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			toasts: [{ id: "saved", type: "success", title: "Saved" }],
+		});
+
+		act(() => vi.advanceTimersByTime(2999));
+		expect(sentActions).toEqual([]);
+		act(() => vi.advanceTimersByTime(1));
+		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "saved" }]);
+	});
+
+	it("restarts the timer of a toast replaced under the same id", () => {
+		vi.useFakeTimers();
+		const toast = { id: "upload", type: "default" as const, title: "Uploading", duration: 3000 };
+		renderPanel({ ...EMPTY_HUD_PANEL_STATE, toasts: [toast] });
+
+		act(() => vi.advanceTimersByTime(2000));
+		act(() => pushState?.({ ...EMPTY_HUD_PANEL_STATE, toasts: [{ ...toast, title: "Uploaded" }] }));
+		act(() => vi.advanceTimersByTime(2000));
+		expect(sentActions).toEqual([]);
+		act(() => vi.advanceTimersByTime(1000));
+		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "upload" }]);
+	});
+
+	it("names the dismiss button in the app's language", () => {
+		renderPanel({
+			...EMPTY_HUD_PANEL_STATE,
+			toasts: [{ id: "note", type: "default", title: "Heads up" }],
+		});
+		fireEvent.click(screen.getByRole("button", { name: "Close notification" }));
+		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "note" }]);
+	});
+
 	it("keeps a loading toast until the HUD replaces or dismisses it", () => {
 		vi.useFakeTimers();
 		renderPanel({
diff --git a/src/components/launch/HudPanelWindow.tsx b/src/components/launch/HudPanelWindow.tsx
index 9f35c2d001..14f6785482 100644
--- a/src/components/launch/HudPanelWindow.tsx
+++ b/src/components/launch/HudPanelWindow.tsx
@@ -1,6 +1,8 @@
 import { X } from "lucide-react";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useScopedT } from "@/contexts/I18nContext";
 import { Button } from "../ui/button";
+import { TOAST_DURATION_MS } from "../ui/sonner";
 import { HudLanguageMenu, HudNotice } from "./HudControls";
 import { HudDeviceSettings } from "./HudDeviceSettings";
 import { HUD_MODAL_MAX_HEIGHT, HUD_POPOVER_MAX_HEIGHT } from "./hudGeometry";
@@ -14,9 +16,6 @@ import styles from "./LaunchWindow.module.css";
 
 /** Padding around the stack, so the cards' rounded corners keep clear of the window edge. */
 const PANEL_PADDING = 10;
-/** Sonner's default, for a toast that names no duration of its own. */
-const DEFAULT_TOAST_DURATION_MS = 4000;
-
 const send = (action: HudPanelAction) => window.electronAPI?.sendHudPanelAction?.(action);
 const noop = () => undefined;
 
@@ -25,10 +24,11 @@ const noop = () => undefined;
  * since the HUD mounts no toaster on Linux to run one, and reports the dismissal back.
  */
 function HudPanelToastCard({ toast }: { toast: HudPanelToast }) {
+	const tc = useScopedT("common");
 	const { id, duration, type } = toast;
 	useEffect(() => {
 		if (type === "loading") return;
-		const ms = duration ?? DEFAULT_TOAST_DURATION_MS;
+		const ms = duration ?? TOAST_DURATION_MS;
 		if (!Number.isFinite(ms)) return;
 		const timer = window.setTimeout(() => send({ kind: "toast-dismiss", id }), ms);
 		return () => window.clearTimeout(timer);
@@ -60,7 +60,7 @@ function HudPanelToastCard({ toast }: { toast: HudPanelToast }) {
 				</div>
 				<button
 					type="button"
-					aria-label="Dismiss"
+					aria-label={tc("actions.closeNotification")}
 					onClick={() => send({ kind: "toast-dismiss", id })}
 					className="rounded-md p-1 text-white/60 hover:bg-white/10 hover:text-white"
 				>
@@ -177,7 +177,12 @@ export function HudPanelWindow() {
 				/>
 			))}
 			{toasts.map((toast) => (
-				<HudPanelToastCard key={toast.id} toast={toast} />
+				// Keyed on the content too, so a toast replaced under the same id gets a fresh
+				// timer, as sonner gives it; an unchanged snapshot keeps the card and its timer.
+				<HudPanelToastCard
+					key={`${toast.id}\u0000${toast.title}\u0000${toast.description ?? ""}`}
+					toast={toast}
+				/>
 			))}
 		</div>
 	);
diff --git a/src/components/launch/LaunchWindow.test.tsx b/src/components/launch/LaunchWindow.test.tsx
index 7b7d7e9357..83f073d118 100644
--- a/src/components/launch/LaunchWindow.test.tsx
+++ b/src/components/launch/LaunchWindow.test.tsx
@@ -2430,6 +2430,17 @@ describe("LaunchWindow on Linux (floating surfaces in the panel window)", () =>
 		expect(button.getAttribute("title")).not.toBe("");
 	});
 
+	it("draws them itself where there is no panel to send to, as in the browser shim", async () => {
+		// The shim also reads as Linux, but has no panel window: hiding everything for one
+		// would leave the settings nowhere.
+		Reflect.deleteProperty(window.electronAPI, "sendHudPanelState");
+		renderLaunchWindow();
+
+		fireEvent.click(await screen.findByTestId("launch-device-settings-button"));
+
+		expect(await screen.findByTestId("hud-device-settings")).toBeInTheDocument();
+	});
+
 	it("hands the device settings to the panel window instead of drawing them over the bar", async () => {
 		renderLaunchWindow();
 
diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index 22f1aa9521..6e6f2e4cb2 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -163,8 +163,11 @@ export function LaunchWindow() {
 	const [isLinuxHud, setIsLinuxHud] = useState(false);
 	// On Linux everything that floats above the bar is shown in a window of its own and this
 	// one is just the bar (hudPanel.ts). Decided synchronously, unlike `isLinuxHud`, so the
-	// very first measurement already sizes the window to the bar.
-	const [floatsInPanel] = useState(() => getPlatform() === "linux");
+	// very first measurement already sizes the window to the bar. Only with a panel to send to:
+	// the browser shim also reads as Linux, and would otherwise hide all of it.
+	const [floatsInPanel] = useState(
+		() => getPlatform() === "linux" && typeof window.electronAPI?.sendHudPanelState === "function",
+	);
 	// The running version, and whether this copy may offer an update check at all — a
 	// Store/Flathub/Snap/Nix install is kept current by its package manager and is offered
 	// nothing (electron/install-channel.ts). Asked once: neither answer changes while the app
diff --git a/src/components/launch/hudPanel.ts b/src/components/launch/hudPanel.ts
index 31739d6a9f..e32456f7a7 100644
--- a/src/components/launch/hudPanel.ts
+++ b/src/components/launch/hudPanel.ts
@@ -123,11 +123,13 @@ export function toHudPanelToasts(toasts: readonly ToastT[]): HudPanelToast[] {
 					: undefined;
 			const type =
 				toast.type && toast.type !== "normal" && toast.type !== "action" ? toast.type : "default";
+			// Once: a function-valued description is called each time it is read.
+			const description = toastText(toast.description);
 			return {
 				id: toast.id,
 				type,
 				title: toastText(toast.title) ?? "",
-				...(toastText(toast.description) ? { description: toastText(toast.description) } : {}),
+				...(description ? { description } : {}),
 				...(action ? { actionLabel: action } : {}),
 				...(toast.duration !== undefined ? { duration: toast.duration } : {}),
 			};
diff --git a/src/components/ui/sonner.tsx b/src/components/ui/sonner.tsx
index 83e5e37a03..5af964a1a5 100644
--- a/src/components/ui/sonner.tsx
+++ b/src/components/ui/sonner.tsx
@@ -5,6 +5,10 @@ import { cn } from "@/lib/utils";
 
 type ToasterProps = React.ComponentProps<typeof Sonner>;
 
+/** How long a toast that names no duration stays up. The Linux HUD panel, which mirrors
+ * toasts without mounting a toaster, times them with the same value. */
+export const TOAST_DURATION_MS = 3000;
+
 // Sonner paints a toast from its own variables, under `[data-styled=true]` selectors that
 // outrank any class passed in `toastOptions` — which is why the old `bg-[#09090b]` never
 // showed and every toast came out #000, 8px, in the system font. Setting the variables on
@@ -27,7 +31,7 @@ const Toaster = ({ className, style, ...props }: ToasterProps) => {
 				className,
 			)}
 			style={{ ...TOKEN_STYLE, ...style }}
-			duration={3000}
+			duration={TOAST_DURATION_MS}
 			// A toast that can only be waited out is the one case where the 3s timer works
 			// against the reader: an error with a long description is dismissed before it is
 			// finished, and a stack of them hides the editor with no way to clear it. The
diff --git a/website/docs/installation.md b/website/docs/installation.md
index 35c79501de..02dc445d54 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -137,7 +137,7 @@ The scope is deliberately narrow: click capture uses only left-button presses (`
 
 #### Recommended: udev rule (least privilege)
 
-**The `.deb`, `.rpm` and `.pacman` packages set this up for you.** They install the udev rule `/usr/lib/udev/rules.d/70-openscreen-pointer.rules` and apply it to the devices already plugged in, so clicks are recorded from the first take, with no reboot. The NixOS module does the same through `services.udev.packages`. Uninstalling the package removes the rule; access it already granted lasts until the device is replugged or the machine reboots.
+**The `.deb`, `.rpm` and `.pacman` packages set this up for you.** They install the udev rule `/usr/lib/udev/rules.d/70-openscreen-pointer.rules` and apply it to the devices already plugged in, so clicks are recorded from the first take, with no reboot. The NixOS module installs the same rule through `services.udev.packages`; a mouse that was already plugged in gets it after a replug or a reboot. Uninstalling the package removes the rule; access it already granted lasts until the device is replugged or the machine reboots.
 
 The rule tags mice and touchpads with `uaccess`, so systemd-logind gives the user of the active local session read access to those devices and to nothing else. A device that reports any keyboard key is never matched, even a mouse that also has keys, so your keyboard stays closed. It needs systemd-logind, which manages the local session on most desktop distributions.
 

From 7ba7f5fc4e8e60021268347ce2f0b6042ddc701a Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:39:59 -0700
Subject: [PATCH 18/27] test(linux): tighten the arrival-placement test bounds

- The pause test measured its bound from the first frame, so a slow
  first encode could eat into it. Measure from the active clock just
  before the pause.
- The late-first-frame test accepted slot 2, one slot past what the
  clamp allows, so a clamp that drifted one slot further still passed.
  Bound it by the second frame's arrival slot on the epoch's clock.
---
 .../native/pipewire-capture/src/capture.rs    | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/electron/native/pipewire-capture/src/capture.rs b/electron/native/pipewire-capture/src/capture.rs
index 037d0452bf..bbc12217aa 100644
--- a/electron/native/pipewire-capture/src/capture.rs
+++ b/electron/native/pipewire-capture/src/capture.rs
@@ -985,17 +985,20 @@ mod tests {
         capture.stage(&frame_at(Instant::now())).expect("stage");
         assert_eq!(capture.advance().expect("advance"), 1);
 
-        // 300 ms paused is 9 slots at 30 fps.
+        // 300 ms paused is 9 slots at 30 fps. Measured from the active clock just
+        // before the pause, so a slow first encode cannot eat into the bound.
+        let before_pause = capture.current_index();
         capture.pause();
         std::thread::sleep(Duration::from_millis(300));
         capture.resume();
 
         capture.stage(&frame_at(Instant::now())).expect("stage");
         assert_eq!(capture.advance().expect("advance"), 1);
+        let stamped = capture.next_index - 1;
         assert!(
-            capture.next_index <= 3,
-            "the frame after the pause was stamped at slot {}, counting the pause",
-            capture.next_index - 1
+            stamped <= before_pause + 1,
+            "the frame after the pause was stamped at slot {stamped}, past {} active",
+            before_pause + 1
         );
         let _ = std::fs::remove_file(&output);
     }
@@ -1021,13 +1024,18 @@ mod tests {
         capture.stage(&frame_at(staged - Duration::from_millis(400))).expect("stage");
         assert_eq!(capture.advance().expect("advance"), 1);
 
-        // The next frame arrives right after: it belongs near slot 1, not 13.
-        capture.stage(&frame_at(Instant::now())).expect("stage");
+        // The next frame arrives right after: it belongs in the slot it arrived in
+        // on the audio's clock, plus the one slot the clamp allows, not 12 later.
+        let epoch = capture.epoch.expect("the first stage started the timeline");
+        let second = Instant::now();
+        capture.stage(&frame_at(second)).expect("stage");
         assert_eq!(capture.advance().expect("advance"), 1);
+        let arrival_slot = (second.duration_since(epoch).as_nanos() as i64 * 30) / 1_000_000_000;
+        let stamped = capture.next_index - 1;
         assert!(
-            capture.next_index <= 3,
-            "the second frame was stamped at slot {}, ahead of the audio",
-            capture.next_index - 1
+            stamped <= arrival_slot + 1,
+            "the second frame was stamped at slot {stamped}, ahead of its slot {arrival_slot} \
+             on the audio's clock"
         );
         let _ = std::fs::remove_file(&output);
     }

From e9e5bc269dd0959c1397fcf696f7e9d04e561538 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Wed, 28 Oct 2026 00:40:00 -0700
Subject: [PATCH 19/27] fix(linux): translate the panel's toast dismiss label
 live

The panel window's own i18n reads the locale once, so after a language
change in the HUD its toasts kept the old dismiss label. The HUD now
sends the translated label in the panel state, as it already does for
every other string the panel shows.
---
 src/components/launch/HudPanelWindow.test.tsx | 25 ++++++++++---------
 src/components/launch/HudPanelWindow.tsx      |  9 +++----
 src/components/launch/LaunchWindow.tsx        |  2 ++
 src/components/launch/hudPanel.ts             |  4 +++
 4 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/src/components/launch/HudPanelWindow.test.tsx b/src/components/launch/HudPanelWindow.test.tsx
index 271a5acada..8c942a01c6 100644
--- a/src/components/launch/HudPanelWindow.test.tsx
+++ b/src/components/launch/HudPanelWindow.test.tsx
@@ -2,7 +2,6 @@
 import "@testing-library/jest-dom";
 import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { I18nProvider } from "@/contexts/I18nContext";
 import { TooltipProvider } from "../ui/tooltip";
 import type { HudDeviceSettingsLabels } from "./HudDeviceSettings";
 import { HudPanelWindow } from "./HudPanelWindow";
@@ -72,11 +71,9 @@ afterEach(() => {
 
 function renderPanel(state: HudPanelState) {
 	render(
-		<I18nProvider>
-			<TooltipProvider>
-				<HudPanelWindow />
-			</TooltipProvider>
-		</I18nProvider>,
+		<TooltipProvider>
+			<HudPanelWindow />
+		</TooltipProvider>,
 	);
 	act(() => pushState?.(state));
 }
@@ -199,12 +196,16 @@ describe("HudPanelWindow", () => {
 		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "upload" }]);
 	});
 
-	it("names the dismiss button in the app's language", () => {
-		renderPanel({
-			...EMPTY_HUD_PANEL_STATE,
-			toasts: [{ id: "note", type: "default", title: "Heads up" }],
-		});
-		fireEvent.click(screen.getByRole("button", { name: "Close notification" }));
+	it("names the dismiss button with the label the HUD translated, and follows a change", () => {
+		const toasts = [{ id: "note", type: "default" as const, title: "Heads up" }];
+		renderPanel({ ...EMPTY_HUD_PANEL_STATE, toasts, toastCloseLabel: "Close notification" });
+		expect(screen.getByRole("button", { name: "Close notification" })).toBeInTheDocument();
+
+		// A language picked in the HUD reaches the panel in the next snapshot.
+		act(() =>
+			pushState?.({ ...EMPTY_HUD_PANEL_STATE, toasts, toastCloseLabel: "Fermer la notification" }),
+		);
+		fireEvent.click(screen.getByRole("button", { name: "Fermer la notification" }));
 		expect(sentActions).toEqual([{ kind: "toast-dismiss", id: "note" }]);
 	});
 
diff --git a/src/components/launch/HudPanelWindow.tsx b/src/components/launch/HudPanelWindow.tsx
index 14f6785482..651f1dc5a7 100644
--- a/src/components/launch/HudPanelWindow.tsx
+++ b/src/components/launch/HudPanelWindow.tsx
@@ -1,6 +1,5 @@
 import { X } from "lucide-react";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
-import { useScopedT } from "@/contexts/I18nContext";
 import { Button } from "../ui/button";
 import { TOAST_DURATION_MS } from "../ui/sonner";
 import { HudLanguageMenu, HudNotice } from "./HudControls";
@@ -23,8 +22,7 @@ const noop = () => undefined;
  * One mirrored toast. The HUD owns the toast (sonner's store); this card owns its timer,
  * since the HUD mounts no toaster on Linux to run one, and reports the dismissal back.
  */
-function HudPanelToastCard({ toast }: { toast: HudPanelToast }) {
-	const tc = useScopedT("common");
+function HudPanelToastCard({ toast, closeLabel }: { toast: HudPanelToast; closeLabel: string }) {
 	const { id, duration, type } = toast;
 	useEffect(() => {
 		if (type === "loading") return;
@@ -60,7 +58,7 @@ function HudPanelToastCard({ toast }: { toast: HudPanelToast }) {
 				</div>
 				<button
 					type="button"
-					aria-label={tc("actions.closeNotification")}
+					aria-label={closeLabel}
 					onClick={() => send({ kind: "toast-dismiss", id })}
 					className="rounded-md p-1 text-white/60 hover:bg-white/10 hover:text-white"
 				>
@@ -127,7 +125,7 @@ export function HudPanelWindow() {
 	// biome-ignore lint/correctness/useExhaustiveDependencies: `state` is the trigger, not an input.
 	useLayoutEffect(() => reportSize(), [state, reportSize]);
 
-	const { deviceSettings, languageMenu, notices, toasts } = state;
+	const { deviceSettings, languageMenu, notices, toasts, toastCloseLabel } = state;
 	const names = languageMenu?.names;
 	const getName = useCallback((locale: string) => names?.[locale] ?? locale, [names]);
 
@@ -182,6 +180,7 @@ export function HudPanelWindow() {
 				<HudPanelToastCard
 					key={`${toast.id}\u0000${toast.title}\u0000${toast.description ?? ""}`}
 					toast={toast}
+					closeLabel={toastCloseLabel}
 				/>
 			))}
 		</div>
diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index 6e6f2e4cb2..be774fbbd4 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -1272,6 +1272,7 @@ export function LaunchWindow() {
 				: null,
 			notices,
 			toasts: toHudPanelToasts(liveToasts),
+			toastCloseLabel: tCommon("actions.closeNotification"),
 		};
 	}, [
 		floatsInPanel,
@@ -1299,6 +1300,7 @@ export function LaunchWindow() {
 		languageNames,
 		liveToasts,
 		t,
+		tCommon,
 	]);
 	useEffect(() => {
 		if (floatsInPanel) window.electronAPI?.sendHudPanelState?.(hudPanelState);
diff --git a/src/components/launch/hudPanel.ts b/src/components/launch/hudPanel.ts
index e32456f7a7..8d9da7e4e2 100644
--- a/src/components/launch/hudPanel.ts
+++ b/src/components/launch/hudPanel.ts
@@ -69,6 +69,9 @@ export interface HudPanelState {
 	languageMenu: HudPanelLanguageMenu | null;
 	notices: HudPanelNotice[];
 	toasts: HudPanelToast[];
+	/** The toasts' dismiss label, translated in the HUD like every other string here: the
+	 * panel's own i18n reads the locale once, so it would miss a language change. */
+	toastCloseLabel: string;
 }
 
 export type HudPanelAction =
@@ -88,6 +91,7 @@ export const EMPTY_HUD_PANEL_STATE: HudPanelState = {
 	languageMenu: null,
 	notices: [],
 	toasts: [],
+	toastCloseLabel: "",
 };
 
 /** Whether there is anything for the panel to show; when not, the window is hidden. */

From 56a1b22283e2e57107e2163d1d5c1d90d29df959 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 00:06:48 -0700
Subject: [PATCH 20/27] fix(linux): restart a take without raising the portal
 picker again

Restart discarded the take, then started a fresh portal session whose
picker opened while the portal was still closing the discarded one. On
Hyprland that close stalls for its full 25 s timeout and the picker waits
behind it, so nothing appeared and the take was already gone; a record
press in that gap spawned helpers that timed out before `ready`.

The helper now asks for a persistent grant and reports its restore token
on `source-selected`. Main keeps the discarded take's token in memory and
hands it back only to the start Restart marks with `restart`, once, so the
same source is shared again with no picker. A fresh recording never gets a
token and is always asked.

Record presses are also ignored while a restart is in flight: `recording`
is cleared before the next take is asked for, so the button was live.
---
 electron/ipc/handlers.ts                      | 21 ++++++++
 .../capture/linuxNativeCaptureSession.test.ts | 33 +++++++++++++
 .../capture/linuxNativeCaptureSession.ts      | 14 ++++++
 .../recording/pipeWireCursorAccumulator.ts    |  2 +
 .../native/pipewire-capture/src/events.rs     |  3 ++
 electron/native/pipewire-capture/src/main.rs  | 27 ++++++++--
 .../native/pipewire-capture/src/portal.rs     | 34 ++++++++-----
 .../useScreenRecorder.restartFailure.test.tsx | 49 +++++++++++++++++++
 src/hooks/useScreenRecorder.ts                | 17 +++++--
 src/lib/nativeLinuxRecording.ts               |  5 +-
 10 files changed, 184 insertions(+), 21 deletions(-)

diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 47019914bb..58e3ae61bb 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -921,6 +921,22 @@ let preparedLinuxCapture: {
  * nothing recording behind it.
  */
 let preparingLinuxCaptureToken: symbol | null = null;
+/**
+ * The source of the take Restart just discarded, to share again without the picker.
+ *
+ * Memory only, and spent by the next start whatever it is: a token replayed on a
+ * fresh recording would record the old source with no way to pick another. Restart
+ * needs it because a second picker there stalls behind the portal closing the
+ * discarded take's session (a 25 s timeout on Hyprland), so nothing appears.
+ */
+let linuxRestartRestoreToken: string | null = null;
+
+/** Hands the discarded take's token to a Restart, and drops it for anything else. */
+function takeLinuxRestartRestoreToken(request: NativeLinuxRecordingRequest): string | undefined {
+	const token = linuxRestartRestoreToken;
+	linuxRestartRestoreToken = null;
+	return request?.restart && token ? token : undefined;
+}
 
 /**
  * Claims the prepared session when it matches the recording about to start.
@@ -2631,6 +2647,7 @@ export function registerIpcHandlers(
 				return { success: false, reason: "already-recording" };
 			}
 			discardPreparedLinuxCapture("superseded by a new prepare");
+			linuxRestartRestoreToken = null;
 			const token = Symbol("prepare-native-linux-recording");
 			preparingLinuxCaptureToken = token;
 
@@ -2732,6 +2749,7 @@ export function registerIpcHandlers(
 				// below, just with the picker after its countdown instead of
 				// before. Nothing has to know which path it is on.
 				const prepared = takePreparedLinuxSession(outputPath, request);
+				const restoreToken = takeLinuxRestartRestoreToken(request);
 				const session =
 					prepared ??
 					new LinuxNativeCaptureSession({
@@ -2750,12 +2768,14 @@ export function registerIpcHandlers(
 							},
 						},
 						maxCursorSamples: MAX_CURSOR_SAMPLES,
+						...(restoreToken ? { restoreToken } : {}),
 					});
 				lastLinuxCaptureSession = session;
 
 				console.info("[native-linux] starting capture", {
 					outputPath,
 					prepared: Boolean(prepared),
+					restoredSource: Boolean(restoreToken && !prepared),
 					cursor: { mode: cursorCaptureMode },
 					audio: request.audio,
 					video: request.video,
@@ -2830,6 +2850,7 @@ export function registerIpcHandlers(
 		}
 
 		try {
+			linuxRestartRestoreToken = discard ? (session.restoreToken ?? null) : null;
 			if (discard) {
 				session.discard();
 				const discarded = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index 63aad34d91..97a2f64b95 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -318,6 +318,39 @@ describe("LinuxNativeCaptureSession", () => {
 		expect(JSON.parse((args as string[])[0])).not.toHaveProperty("deferStart");
 	});
 
+	// Restart replays the discarded take's grant so no second picker opens; a
+	// fresh recording sends no token and must always be asked.
+	it("sends no restore token unless it was given one", async () => {
+		await startReady(newSession());
+
+		const [, args] = spawnMock.mock.calls[0];
+		expect(JSON.parse((args as string[])[0])).not.toHaveProperty("restoreToken");
+	});
+
+	it("replays the token it was given, and keeps the grant's new one", async () => {
+		const session = new LinuxNativeCaptureSession({
+			outputPath: "/tmp/recording.mp4",
+			cursorMode: "metadata",
+			fps: 30,
+			audio: { system: { enabled: false }, microphone: { enabled: false, gain: 1 } },
+			maxCursorSamples: 100,
+			restoreToken: "previous-take",
+		});
+		await startReady(session);
+		const [, args] = spawnMock.mock.calls[0];
+		expect(JSON.parse((args as string[])[0])).toMatchObject({ restoreToken: "previous-take" });
+
+		helper.emitEvent({
+			event: "source-selected",
+			timestampMs: 1_100,
+			nodeId: 42,
+			restoreToken: "this-take",
+		});
+		await session.waitUntilSourceSelected();
+
+		expect(session.restoreToken).toBe("this-take");
+	});
+
 	/**
 	 * A prepared session is held open across the countdown, so it can die before
 	 * it is ever armed — the user revoking the share from the compositor's
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index bd4518a173..53e74c43dc 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -77,6 +77,12 @@ export interface LinuxCaptureConfig {
 	 * dialog they have not been shown yet.
 	 */
 	deferStart?: boolean;
+	/**
+	 * An earlier take's [`restoreToken`], to share that source again without the
+	 * picker. Restart only: a fresh recording must always ask (see the helper's
+	 * `portal::negotiate`).
+	 */
+	restoreToken?: string;
 }
 
 /** What the portal handed over. `undefined` means the backend did not say. */
@@ -117,6 +123,7 @@ export class LinuxNativeCaptureSession {
 	private stoppedReject: ((error: Error) => void) | null = null;
 
 	private sourceKind: LinuxCaptureSourceKind | undefined;
+	private grantRestoreToken: string | undefined;
 	private negotiatedCursorMode: LinuxNegotiatedCursorMode | undefined;
 	private videoEncoder: string | undefined;
 	private lastError: string | null = null;
@@ -159,6 +166,7 @@ export class LinuxNativeCaptureSession {
 			},
 			audio: this.config.audio,
 			...(this.config.deferStart ? { deferStart: true } : {}),
+			...(this.config.restoreToken ? { restoreToken: this.config.restoreToken } : {}),
 		};
 
 		const child = spawn(helperPath, [JSON.stringify(request)], {
@@ -359,6 +367,11 @@ export class LinuxNativeCaptureSession {
 		return this.sourceKind;
 	}
 
+	/** Shares this take's source again without the picker, for a Restart. */
+	get restoreToken(): string | undefined {
+		return this.grantRestoreToken;
+	}
+
 	/**
 	 * The cursor mode the helper really negotiates, known once `start()` resolves.
 	 * A portal without EMBEDDED gets METADATA instead (#1357), so the cursor has
@@ -500,6 +513,7 @@ export class LinuxNativeCaptureSession {
 				if (payload.sourceKind) {
 					this.sourceKind = payload.sourceKind;
 				}
+				this.grantRestoreToken = payload.restoreToken ?? undefined;
 				this.sourceSelected = true;
 				console.info(
 					"[capture-linux] source selected",
diff --git a/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts b/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
index 0a9c416bac..d8d04dafb7 100644
--- a/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
+++ b/electron/native-bridge/cursor/recording/pipeWireCursorAccumulator.ts
@@ -42,6 +42,8 @@ export type PipeWireHelperEvent =
 			sourceKind?: "monitor" | "window" | "virtual" | null;
 			positionX?: number | null;
 			positionY?: number | null;
+			/** Shares the same source again without the picker; Restart only. */
+			restoreToken?: string | null;
 	  }
 	| {
 			event: "stream-started";
diff --git a/electron/native/pipewire-capture/src/events.rs b/electron/native/pipewire-capture/src/events.rs
index 9bc4d4c7a4..e55a281d09 100644
--- a/electron/native/pipewire-capture/src/events.rs
+++ b/electron/native/pipewire-capture/src/events.rs
@@ -67,6 +67,9 @@ pub enum Event {
         source_kind: Option<String>,
         position_x: Option<i32>,
         position_y: Option<i32>,
+        /// Shares the same source again without the picker. Only Restart uses it.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        restore_token: Option<String>,
     },
     #[serde(rename_all = "camelCase")]
     StreamStarted {
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 8d07d59094..63983486dc 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -137,6 +137,9 @@ struct Request {
     /// the picker has even appeared. Defaults to false, which keeps the
     /// single-shot behaviour every existing caller relies on.
     defer_start: bool,
+    /// A token from an earlier take's `source-selected`, to share that source
+    /// again without the picker. Only Restart sends one; see `portal::negotiate`.
+    restore_token: Option<String>,
     /// Emit `ready` and exit, without ever calling the portal's `Start()`.
     ///
     /// Everything up to that point is non-interactive; `Start()` is the single
@@ -338,7 +341,12 @@ fn main() {
 
     let (sender, receiver) = mpsc::channel::<Message>();
     spawn_stdin_reader(sender.clone());
-    spawn_portal(sender.clone(), cursor_mode, monitors_only);
+    spawn_portal(
+        sender.clone(),
+        cursor_mode,
+        monitors_only,
+        request.restore_token.clone(),
+    );
     if let Some(socket) = host_pointer_socket.clone() {
         hyprland::spawn_poller(sender.clone(), socket, sample_interval);
     }
@@ -558,9 +566,18 @@ fn spawn_stdin_reader(sender: Sender<Message>) {
 /// The portal runs on its own thread because `Start()` blocks on the user for
 /// an unbounded time, and a `stop` arriving during the picker must still be
 /// honoured.
-fn spawn_portal(sender: Sender<Message>, cursor_mode: portal::CursorMode, monitors_only: bool) {
+fn spawn_portal(
+    sender: Sender<Message>,
+    cursor_mode: portal::CursorMode,
+    monitors_only: bool,
+    restore_token: Option<String>,
+) {
     std::thread::spawn(move || {
-        let result = pollster::block_on(portal::negotiate(cursor_mode, monitors_only));
+        let result = pollster::block_on(portal::negotiate(
+            cursor_mode,
+            monitors_only,
+            restore_token.as_deref(),
+        ));
         let _ = sender.send(Message::Portal(Box::new(result)));
     });
 }
@@ -590,7 +607,7 @@ fn begin_stream<W: Write>(
     prefer_dmabuf: bool,
     shared_memory_fallback: &mut Option<SharedMemoryFallback>,
 ) -> Result<(), ()> {
-    let portal::PortalStream { fd, fallback_fd, node_id, position, size, source_kind } = stream;
+    let portal::PortalStream { fd, fallback_fd, node_id, position, size, source_kind, .. } = stream;
     *shared_memory_fallback = if prefer_dmabuf {
         fallback_fd.map(|fd| SharedMemoryFallback {
             fd,
@@ -1204,6 +1221,7 @@ fn run<W: Write>(
                         source_kind: stream.source_kind.map(|kind| kind.as_str().to_owned()),
                         position_x: stream.position.map(|(x, _)| x),
                         position_y: stream.position.map(|(_, y)| y),
+                        restore_token: stream.restore_token.clone(),
                     });
                     granted_kind = stream.source_kind;
                     host_pointer_origin = match (&config.host_pointer, stream.source_kind) {
@@ -1438,6 +1456,7 @@ fn run<W: Write>(
                         position: fallback.position,
                         size: fallback.size,
                         source_kind: fallback.source_kind,
+                        restore_token: None,
                     };
                     if let Err(()) = begin_stream(
                         emitter,
diff --git a/electron/native/pipewire-capture/src/portal.rs b/electron/native/pipewire-capture/src/portal.rs
index d4f3db0285..32a2ad7a24 100644
--- a/electron/native/pipewire-capture/src/portal.rs
+++ b/electron/native/pipewire-capture/src/portal.rs
@@ -158,6 +158,9 @@ pub struct PortalStream {
     /// `None` when the portal omits it — older backends do, and the spec makes
     /// it optional. Absent means "unknown", never "monitor".
     pub source_kind: Option<SourceKind>,
+    /// Replays this grant without the picker. Only Restart may use it — see
+    /// `negotiate`.
+    pub restore_token: Option<String>,
 }
 
 #[derive(Debug)]
@@ -251,6 +254,7 @@ pub async fn offered_cursor_modes() -> Result<Vec<CursorMode>, PortalError> {
 pub async fn negotiate(
     cursor_mode: CursorMode,
     monitors_only: bool,
+    restore_token: Option<&str>,
 ) -> Result<PortalStream, PortalError> {
     let proxy = Screencast::new().await.map_err(portal_unavailable)?;
 
@@ -292,19 +296,22 @@ pub async fn negotiate(
             cursor_mode.to_portal(),
             types,
             false,
-            // NO RESTORE TOKEN, AND NOTHING TO PERSIST. This used to replay a
-            // token from the previous run so the picker would not reappear —
-            // and that is precisely how "record this window" produced a
-            // recording of the whole screen. A token is bound to the source it
-            // was minted for, so once any monitor had been approved the portal
-            // restored that monitor on every later run and never raised the
-            // picker again; the app had no way to ask for anything else,
-            // because `SelectSources` cannot name a source. The picker IS the
-            // source chooser on Wayland, so suppressing it removed the only
-            // control the user had. Asking every time is the cost of letting
-            // them choose at all.
-            None,
-            PersistMode::DoNot,
+            // A TOKEN ONLY EVER REPLAYS THE SOURCE IT WAS MINTED FOR, which is
+            // why a fresh recording never gets one: a token replayed on every
+            // run used to turn "record this window" into a recording of the
+            // whole screen, because the picker — the only source chooser
+            // Wayland has — never came back. Restart is the one caller that
+            // wants exactly that: the same source again, and no second picker.
+            // That picker is not just a nuisance there. On Hyprland it opens
+            // while the portal is still closing the discarded take's session,
+            // that close stalls for its full 25 s timeout, and the picker waits
+            // behind it — so the take is deleted and nothing appears.
+            //
+            // Persistent because a transient grant belongs to the process that
+            // asked for it, and every take is a new helper. The caller keeps
+            // the token in memory and hands it back once, for one Restart.
+            restore_token,
+            PersistMode::ExplicitlyRevoked,
         )
         .await
         .map_err(|error| failed("SelectSources", error))?
@@ -345,6 +352,7 @@ pub async fn negotiate(
         position: stream.position(),
         size: stream.size(),
         source_kind: stream.source_type().map(SourceKind::from_portal),
+        restore_token: streams.restore_token().map(str::to_owned),
     })
 }
 
diff --git a/src/hooks/useScreenRecorder.restartFailure.test.tsx b/src/hooks/useScreenRecorder.restartFailure.test.tsx
index 63c78d9165..24166c35c8 100644
--- a/src/hooks/useScreenRecorder.restartFailure.test.tsx
+++ b/src/hooks/useScreenRecorder.restartFailure.test.tsx
@@ -193,9 +193,17 @@ describe("useScreenRecorder Restart that does not start a new take", () => {
 		stubElectronAPI("linux");
 		const view = renderHook(() => useScreenRecorder());
 		await startTake(view);
+		expect(api.startNativeLinuxRecording).toHaveBeenLastCalledWith(
+			expect.not.objectContaining({ restart: true }),
+		);
 
 		await restart(view);
 
+		// Marked, so main can record the discarded take's source again without a
+		// second picker.
+		expect(api.startNativeLinuxRecording).toHaveBeenLastCalledWith(
+			expect.objectContaining({ restart: true }),
+		);
 		expect(view.result.current.recording).toBe(true);
 		expect(toast.error).not.toHaveBeenCalledWith("recording.restartFailed");
 	});
@@ -226,3 +234,44 @@ describe("useScreenRecorder Restart that does not start a new take", () => {
 		expect(toast.error).not.toHaveBeenCalledWith("recording.restartFailed");
 	});
 });
+
+describe("useScreenRecorder Restart on native Linux", () => {
+	// Restart clears `recording` and then waits on the portal's picker, which on
+	// Hyprland blocks the portal: a record press there spawned helpers that timed
+	// out before they were ready, then fresh unprepared starts.
+	it("ignores a record press while the restarted take waits on the picker", async () => {
+		stubElectronAPI("linux");
+		const view = renderHook(() => useScreenRecorder());
+		await startTake(view);
+
+		let answerPicker: (value: { success: boolean; recordingId: number }) => void = () => undefined;
+		api.startNativeLinuxRecording.mockImplementation(
+			() =>
+				new Promise((resolve) => {
+					answerPicker = resolve;
+				}),
+		);
+		let restarted: Promise<void> = Promise.resolve();
+		await act(async () => {
+			// Typed `void`, but async: Promise.resolve adopts the promise it returns.
+			restarted = Promise.resolve(view.result.current.restartRecording());
+		});
+		await settle();
+		expect(view.result.current.recording).toBe(false);
+
+		await act(async () => {
+			view.result.current.toggleRecording();
+		});
+		await settle(3_500);
+		expect(api.prepareNativeLinuxRecording).toHaveBeenCalledTimes(1);
+		expect(api.startNativeLinuxRecording).toHaveBeenCalledTimes(2);
+
+		await act(async () => {
+			answerPicker({ success: true, recordingId: 8 });
+			await restarted;
+		});
+		await settle();
+		expect(view.result.current.recording).toBe(true);
+		expect(api.startNativeLinuxRecording).toHaveBeenCalledTimes(2);
+	});
+});
diff --git a/src/hooks/useScreenRecorder.ts b/src/hooks/useScreenRecorder.ts
index 3ec0a4ac4d..ed25b0d62a 100644
--- a/src/hooks/useScreenRecorder.ts
+++ b/src/hooks/useScreenRecorder.ts
@@ -1514,8 +1514,10 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	const buildNativeLinuxRequest = (
 		recordMicrophone: boolean,
 		recordingId?: number,
+		restart = false,
 	): NativeLinuxRecordingRequest => ({
 		...(recordingId === undefined ? {} : { recordingId }),
+		...(restart ? { restart: true } : {}),
 		video: {
 			// No bitrate on purpose. TARGET_WIDTH/HEIGHT are the app's 4K ceiling,
 			// not the capture size — on Wayland nobody knows that until the portal
@@ -1547,6 +1549,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 		recordMicrophone: boolean,
 		countdownRunToken?: number,
 		preparedRecordingId?: number | null,
+		restart = false,
 	) => {
 		try {
 			const platform = window.electronAPI.getPlatform();
@@ -1601,7 +1604,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 			}
 
 			const result = await window.electronAPI.startNativeLinuxRecording(
-				buildNativeLinuxRequest(recordMicrophone, activeRecordingId),
+				buildNativeLinuxRequest(recordMicrophone, activeRecordingId, restart),
 			);
 			if (!result.success || !result.recordingId) {
 				throw new Error(result.error ?? "Native Linux capture failed.");
@@ -1640,7 +1643,11 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	};
 
 	const startRecordCountdown = async () => {
-		if (countdownActive || recording || countdownStarting.current) {
+		// A restart clears `recording` before it asks for the next take, so the
+		// record button is live while that start waits on the portal's picker. On
+		// Hyprland the portal answers nothing else while its picker is up, so a
+		// press there spawned helpers that timed out and fresh unprepared starts.
+		if (countdownActive || recording || countdownStarting.current || restarting.current) {
 			return;
 		}
 		const starting = {};
@@ -1810,6 +1817,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	const startRecording = async (
 		countdownRunToken?: number,
 		preparedRecordingId?: number | null,
+		restart = false,
 	) => {
 		const platform = window.electronAPI.getPlatform();
 		const browserCursorCaptureMode = effectiveBrowserCursorMode(platform, cursorCaptureMode);
@@ -1843,6 +1851,7 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 					recordMicrophone,
 					countdownRunToken,
 					preparedRecordingId,
+					restart,
 				)
 			) {
 				return;
@@ -2324,7 +2333,9 @@ export function useScreenRecorder(): UseScreenRecorderReturn {
 	 * without a word (#995).
 	 */
 	const startRecordingAfterRestart = async () => {
-		await startRecording();
+		// `restart` lets native Linux record the discarded take's source again
+		// without raising the portal's picker a second time.
+		await startRecording(undefined, null, true);
 		if (
 			!nativeWindowsRecording.current &&
 			!nativeMacRecording.current &&
diff --git a/src/lib/nativeLinuxRecording.ts b/src/lib/nativeLinuxRecording.ts
index 3beee7c521..89670cf0be 100644
--- a/src/lib/nativeLinuxRecording.ts
+++ b/src/lib/nativeLinuxRecording.ts
@@ -15,10 +15,13 @@
  *     would stop raising its picker, and that is exactly how picking a window
  *     produced a recording of the whole screen: a token is bound to the source
  *     it was minted for, so an approved monitor came back forever and the picker
- *     — the only source chooser Wayland offers — never reappeared.
+ *     — the only source chooser Wayland offers — never reappeared. `restart`
+ *     asks main for the one exception it keeps itself: the take just discarded.
  */
 export type NativeLinuxRecordingRequest = {
 	recordingId?: number;
+	/** Restart: record the source of the take just discarded, without the picker. */
+	restart?: boolean;
 	video: {
 		fps: number;
 		bitrate?: number;

From 7466468a3394824ba2e96a8e546e116d65a4a8c0 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 00:31:39 -0700
Subject: [PATCH 21/27] fix(linux): keep the HUD bar at the bottom and above
 fullscreen on Hyprland

Hyprland centres every new floating window and ignores the position a
Wayland client asks for, so the bar sat mid-screen instead of at the
bottom centre where Windows and macOS put it. It is now moved there over
Hyprland's IPC when it is shown and after each resize, which Hyprland
anchors at the top-left; the panel follows it.

`alwaysOnTop` means nothing on Wayland either, so a maximized or
fullscreen window (Omarchy's Super+Alt+F, Super+F) covered the bar. The
bar and the panel are pinned as they are placed, which keeps them above
it and on every workspace.
---
 electron/hyprland.test.ts | 79 +++++++++++++++++++++++++++++++++
 electron/hyprland.ts      | 92 ++++++++++++++++++++++++++++++++++++---
 electron/windows.ts       | 44 ++++++++++++++++++-
 3 files changed, 208 insertions(+), 7 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index 8e04d27385..dd870c81f6 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -4,9 +4,11 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
+	barPositionAtBottom,
 	hyprlandSocketPath,
 	monitorWorkArea,
 	panelPositionNearBar,
+	placeHudBarAtBottom,
 	placeHudPanelNearBar,
 } from "./hyprland";
 
@@ -47,6 +49,15 @@ describe("panelPositionNearBar", () => {
 	});
 });
 
+describe("barPositionAtBottom", () => {
+	it("centres the bar at the bottom of the work area", () => {
+		expect(barPositionAtBottom({ width: 576, height: 150 }, workArea, 5)).toEqual({
+			x: 672,
+			y: 22 + 1058 - 150 - 5,
+		});
+	});
+});
+
 describe("monitorWorkArea", () => {
 	it("is the monitor in logical px less what bars reserve", () => {
 		expect(
@@ -202,6 +213,74 @@ describe("placeHudPanelNearBar", () => {
 		expect(received.some((command) => command.startsWith("dispatch"))).toBe(false);
 	});
 
+	// Hyprland centres a new window and ignores the position it asked for; every other
+	// platform puts the bar at the bottom centre.
+	it("moves this process's bar to the bottom of its monitor", async () => {
+		const { env, received } = await fakeHyprland({
+			"j/clients": clients,
+			"j/monitors": monitors,
+			dispatch: "ok",
+		});
+
+		const placed = await placeHudBarAtBottom({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 576, height: 150 },
+			margin: 5,
+		});
+
+		expect(placed).toBe(true);
+		expect(received).toContain(
+			'dispatch hl.dsp.window.move({ x = 672, y = 925, window = "address:0xbar" })',
+		);
+		// Above a maximized or fullscreen window, which otherwise hides it.
+		expect(received).toContain('dispatch hl.dsp.window.pin({ window = "address:0xbar" })');
+	});
+
+	it("does not unpin a bar that is already pinned", async () => {
+		const pinned = JSON.stringify(
+			(JSON.parse(clients) as Record<string, unknown>[]).map((client) => ({
+				...client,
+				pinned: true,
+			})),
+		);
+		const { env, received } = await fakeHyprland({
+			"j/clients": pinned,
+			"j/monitors": monitors,
+			dispatch: "ok",
+		});
+
+		await placeHudBarAtBottom({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 576, height: 150 },
+			margin: 5,
+		});
+
+		expect(received.some((command) => command.includes("pin"))).toBe(false);
+	});
+
+	it("moves no bar it cannot find by its size", async () => {
+		const { env, received } = await fakeHyprland({
+			"j/clients": clients,
+			"j/monitors": monitors,
+			dispatch: "ok",
+		});
+
+		const placed = await placeHudBarAtBottom({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 999, height: 150 },
+			margin: 5,
+		});
+
+		expect(placed).toBe(false);
+		expect(received.some((command) => command.startsWith("dispatch"))).toBe(false);
+	});
+
 	it("gives up quietly outside Hyprland", async () => {
 		await expect(
 			placeHudPanelNearBar({
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index 08eef4f539..ce68ade62d 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -1,10 +1,14 @@
-// Hyprland: placing the HUD panel next to the bar, which Wayland gives a client no way to do.
+// Hyprland: placing the HUD bar and its panel, which Wayland gives a client no way to do.
 //
 // A toplevel cannot position itself on Wayland, and Hyprland centres every new floating window
-// on its monitor. The HUD bar starts centred too, so the panel (src/components/launch/hudPanel.ts)
+// on its monitor. The bar asks for the bottom centre of the screen, where Windows and macOS put
+// it, and was left in the middle instead; the panel (src/components/launch/hudPanel.ts) then
 // opened on top of it, and a toast covered the very controls it was about. Hyprland's IPC socket
-// can move a window, so on Hyprland the panel is moved next to the bar after it maps. Best
-// effort only: anything unexpected leaves the window where the compositor put it.
+// can move a window, so on Hyprland the bar is moved to the bottom and the panel next to it
+// after each maps. Both are pinned too: `alwaysOnTop` means nothing on Wayland, and a window
+// made fullscreen or maximized (Omarchy's Super+F, Super+Alt+F) otherwise covers the bar,
+// which is how the user stops a recording. Best effort only: anything unexpected leaves the
+// window where the compositor put it.
 import net from "node:net";
 import path from "node:path";
 
@@ -24,6 +28,7 @@ interface HyprlandClient {
 	at: [number, number];
 	size: [number, number];
 	monitor: number;
+	pinned?: boolean;
 }
 
 interface HyprlandMonitor {
@@ -117,6 +122,18 @@ export function panelPositionNearBar(
 	};
 }
 
+/** Where the bar goes: centred at the bottom of the work area, `margin` above its edge. */
+export function barPositionAtBottom(
+	bar: { width: number; height: number },
+	workArea: Rect,
+	margin: number,
+): { x: number; y: number } {
+	return {
+		x: Math.round(workArea.x + (workArea.width - bar.width) / 2),
+		y: Math.round(workArea.y + workArea.height - bar.height - margin),
+	};
+}
+
 const toRect = (client: HyprlandClient): Rect => ({
 	x: client.at[0],
 	y: client.at[1],
@@ -161,10 +178,75 @@ export async function placeHudPanelNearBar(options: {
 		monitorWorkArea(monitor),
 		options.gap,
 	);
+	await pinClient(socketPath, panel);
 	if (x === panel.at[0] && y === panel.at[1]) return true;
+	return moveClient(socketPath, panel.address, x, y);
+}
+
+/**
+ * Moves the bar window to the bottom centre of the monitor it is on. Found among this
+ * process's clients by the size this process gave it, skipping the panel. Resolves false
+ * when not under Hyprland or when anything does not match, in which case nothing was moved.
+ */
+export async function placeHudBarAtBottom(options: {
+	env: Env;
+	pid: number;
+	panelTitle: string;
+	barSize: { width: number; height: number };
+	margin: number;
+}): Promise<boolean> {
+	const socketPath = hyprlandSocketPath(options.env);
+	if (!socketPath) return false;
+	const [clients, monitors] = await Promise.all([
+		requestJson<HyprlandClient[]>(socketPath, "clients"),
+		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+	]);
+	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+
+	const bar = clients.find(
+		(client) =>
+			client.pid === options.pid &&
+			client.title !== options.panelTitle &&
+			client.size[0] === options.barSize.width &&
+			client.size[1] === options.barSize.height,
+	);
+	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
+	if (!bar || !monitor) return false;
+
+	const { x, y } = barPositionAtBottom(
+		{ width: bar.size[0], height: bar.size[1] },
+		monitorWorkArea(monitor),
+		options.margin,
+	);
+	await pinClient(socketPath, bar);
+	if (x === bar.at[0] && y === bar.at[1]) return true;
+	return moveClient(socketPath, bar.address, x, y);
+}
+
+/**
+ * Pins a window: shown on every workspace and above a fullscreen or maximized one. Both
+ * dispatchers toggle, so an already pinned window is left alone.
+ */
+async function pinClient(socketPath: string, client: HyprlandClient): Promise<void> {
+	if (client.pinned) return;
+	const target = `address:${client.address}`;
+	for (const command of [
+		`dispatch hl.dsp.window.pin({ window = "${target}" })`,
+		`dispatch pin ${target}`,
+	]) {
+		if ((await request(socketPath, command))?.trim() === "ok") return;
+	}
+}
+
+async function moveClient(
+	socketPath: string,
+	address: string,
+	x: number,
+	y: number,
+): Promise<boolean> {
 	// Hyprland 0.56 evaluates `dispatch` as Lua (hl.dsp.window.move); earlier releases only
 	// know the classic dispatcher. Each refuses the other's syntax, so try both in turn.
-	const target = `address:${panel.address}`;
+	const target = `address:${address}`;
 	for (const command of [
 		`dispatch hl.dsp.window.move({ x = ${x}, y = ${y}, window = "${target}" })`,
 		`dispatch movewindowpixel exact ${x} ${y},${target}`,
diff --git a/electron/windows.ts b/electron/windows.ts
index ad95951fe0..1bb9ac666d 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -25,7 +25,7 @@ import {
 	parseHudContentRect,
 	sameRect,
 } from "./hudWindowBounds";
-import { placeHudPanelNearBar } from "./hyprland";
+import { placeHudBarAtBottom, placeHudPanelNearBar } from "./hyprland";
 import { keepAlwaysOnTop, reassertAlwaysOnTop } from "./keepOnTop";
 import { followAcrossSpaces } from "./macSpaces";
 import { markSheetless } from "./messageBox";
@@ -442,6 +442,9 @@ ipcMain.on("hud-overlay-set-size", (_event, width: number, height: number, conte
 
 	if (!sameRect(next, bounds)) {
 		hudOverlayWindow.setBounds(next, false);
+		// Hyprland keeps the top-left of a resized window, which lifts the bar off the
+		// bottom; the bounds asked for above are ignored there.
+		placeHudBar();
 	}
 	reassertAlwaysOnTop(hudOverlayWindow);
 });
@@ -456,6 +459,9 @@ ipcMain.on("hud-overlay-content", (_event, content: unknown) => {
 	if (hudOverlayWindow) reassertAlwaysOnTop(hudOverlayWindow);
 });
 
+/** Gap between the HUD window and the bottom of the work area. */
+const HUD_BOTTOM_MARGIN = 5;
+
 /**
  * Frameless transparent HUD overlay, always-on-top, centred at the bottom of the
  * primary display. Follows the user across macOS Spaces so it isn't lost on switch.
@@ -471,7 +477,7 @@ export function createHudOverlayWindow(): BrowserWindow {
 	const windowHeight = 560;
 
 	const x = Math.floor(workArea.x + (workArea.width - windowWidth) / 2);
-	const y = Math.floor(workArea.y + workArea.height - windowHeight - 5);
+	const y = Math.floor(workArea.y + workArea.height - windowHeight - HUD_BOTTOM_MARGIN);
 
 	const win = new BrowserWindow({
 		width: windowWidth,
@@ -558,6 +564,9 @@ export function createHudOverlayWindow(): BrowserWindow {
 	win.on("hide", () => hudPanelWindow?.hide());
 	// And back with it: a notice still in the state sends no new size report to bring it.
 	win.on("show", () => {
+		// On Linux a hide unmaps the window and show maps a new one, which Hyprland
+		// centres again.
+		placeHudBar();
 		const panel = hudPanelWindow;
 		if (panel && !panel.isDestroyed() && hudPanelState && hudPanelHasContent(hudPanelState)) {
 			revealHudPanel(panel, hudPanelState);
@@ -619,6 +628,37 @@ function placeHudPanel(attempt = 0) {
 	}, 40);
 }
 
+let hudBarPlacementTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * On Hyprland, moves the bar to the bottom centre of its monitor, where every other platform
+ * puts it: the compositor centres it instead, ignoring the position the window asked for.
+ * Retried briefly, as a window just shown or resized may not be listed at its new size yet.
+ * Then the panel follows the bar. Elsewhere this does nothing.
+ */
+function placeHudBar(attempt = 0) {
+	if (!process.env.HYPRLAND_INSTANCE_SIGNATURE) return;
+	if (hudBarPlacementTimer) clearTimeout(hudBarPlacementTimer);
+	hudBarPlacementTimer = setTimeout(async () => {
+		hudBarPlacementTimer = null;
+		if (!hudOverlayWindow || hudOverlayWindow.isDestroyed() || !hudOverlayWindow.isVisible()) {
+			return;
+		}
+		const placed = await placeHudBarAtBottom({
+			env: process.env,
+			pid: process.pid,
+			panelTitle: HUD_PANEL_TITLE,
+			barSize: hudWindowSize,
+			margin: HUD_BOTTOM_MARGIN,
+		});
+		if (!placed && attempt < 4) {
+			placeHudBar(attempt + 1);
+			return;
+		}
+		if (placed) placeHudPanel();
+	}, 40);
+}
+
 function hudPanelHasPopover(state: HudPanelState | null): boolean {
 	return Boolean(state && (state.deviceSettings || state.languageMenu));
 }

From 92780471580c28574e50187e3b5f76cb53f3bec2 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 00:50:25 -0700
Subject: [PATCH 22/27] fix(linux): release the camera when the device settings
 close

On Linux the device settings are drawn in the HUD's panel window, which
was hidden when it emptied without being sent the empty state. A hidden
panel still renders its last snapshot, so the settings stayed mounted and
kept the camera preview and the microphone meter open after closing, even
with the camera toggle off. The empty state is now sent before the panel
hides, which unmounts them as closing does on Windows and macOS.
---
 electron/windows.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/electron/windows.ts b/electron/windows.ts
index 1bb9ac666d..395ef88513 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -740,7 +740,12 @@ ipcMain.on("hud-panel-state", (event, state: HudPanelState) => {
 	const popoverOpened = !hudPanelHasPopover(hudPanelState) && hudPanelHasPopover(state);
 	hudPanelState = state;
 	if (!hudPanelHasContent(state)) {
-		if (hudPanelWindow && !hudPanelWindow.isDestroyed()) hudPanelWindow.hide();
+		if (hudPanelWindow && !hudPanelWindow.isDestroyed()) {
+			// Sent, not just hidden: a hidden panel still renders its last snapshot, and the
+			// device settings in it hold the camera preview and the microphone meter open.
+			hudPanelWindow.webContents.send("hud-panel-state", state);
+			hudPanelWindow.hide();
+		}
 		return;
 	}
 	if (!hudPanelWindow || hudPanelWindow.isDestroyed()) {

From d98a116b7a5b428fdb263bf14de3528d6f6c0804 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 00:50:26 -0700
Subject: [PATCH 23/27] fix(linux): open the HUD panel next to the bar on
 Hyprland

The panel is a window of its own, shown each time a popover opens, and
Hyprland centres a new window: it was seen opening mid-screen and then
jumping to the bar. Before it is shown, a named window rule set over
Hyprland's IPC now maps it floating at its size beside the bar. On
Hyprland it waits ~80 ms for its size to settle first, since the device
list loads after the first measurement and grows it. It is still pinned
after it maps, as the bar is: pinned by the rule at map time, it stayed
under a fullscreen window. The move after it maps stays as the fallback
for a Hyprland without Lua.
---
 electron/hyprland.test.ts |  51 +++++++++++++++++++
 electron/hyprland.ts      | 101 ++++++++++++++++++++++++++++++++------
 electron/windows.ts       |  53 +++++++++++++++-----
 3 files changed, 179 insertions(+), 26 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index dd870c81f6..e63425f98e 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -7,9 +7,11 @@ import {
 	barPositionAtBottom,
 	hyprlandSocketPath,
 	monitorWorkArea,
+	panelPlacementRule,
 	panelPositionNearBar,
 	placeHudBarAtBottom,
 	placeHudPanelNearBar,
+	presetHudPanelPlacement,
 } from "./hyprland";
 
 const workArea = { x: 0, y: 22, width: 1920, height: 1058 };
@@ -58,6 +60,19 @@ describe("barPositionAtBottom", () => {
 	});
 });
 
+describe("panelPlacementRule", () => {
+	it("floats the panel at its size and a monitor-relative position", () => {
+		expect(panelPlacementRule("OpenScreen panel", { width: 382, height: 300 }, 769.4, 168)).toBe(
+			'hl.window_rule({ name = "openscreen-hud-panel", match = { title = "^(OpenScreen panel)$" }, ' +
+				'float = true, size = "382 300", move = "769 168" })',
+		);
+	});
+
+	it("refuses a title it would have to escape", () => {
+		expect(panelPlacementRule('a "quoted" (title)', { width: 1, height: 1 }, 0, 0)).toBeNull();
+	});
+});
+
 describe("monitorWorkArea", () => {
 	it("is the monitor in logical px less what bars reserve", () => {
 		expect(
@@ -281,6 +296,42 @@ describe("placeHudPanelNearBar", () => {
 		expect(received.some((command) => command.startsWith("dispatch"))).toBe(false);
 	});
 
+	// Without the rule the panel maps mid-screen and is then seen jumping to the bar.
+	it("sets a rule that maps the panel next to the bar before it is shown", async () => {
+		// A second monitor at x 1920, with the bar on it.
+		const onSecondMonitor = JSON.stringify([
+			{
+				address: "0xbar",
+				pid: 42,
+				title: "openscreen",
+				at: [1920 + 672, 476],
+				size: [576, 150],
+				monitor: 3,
+			},
+		]);
+		// Placed in that monitor's work area, but handed to the rule relative to the monitor.
+		const rule = `eval ${panelPlacementRule("OpenScreen panel", { width: 382, height: 300 }, 769, 168)}`;
+		const { env, received } = await fakeHyprland({
+			"j/clients": onSecondMonitor,
+			"j/monitors": JSON.stringify([
+				{ id: 3, x: 1920, y: 0, width: 3840, height: 2160, scale: 2, reserved: [0, 22, 0, 0] },
+			]),
+			[rule]: "ok",
+		});
+
+		const preset = await presetHudPanelPlacement({
+			env,
+			pid: 42,
+			panelTitle: "OpenScreen panel",
+			panelSize: { width: 382, height: 300 },
+			barSize: { width: 576, height: 150 },
+			gap: 8,
+		});
+
+		expect(received).toContain(rule);
+		expect(preset).toBe(true);
+	});
+
 	it("gives up quietly outside Hyprland", async () => {
 		await expect(
 			placeHudPanelNearBar({
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index ce68ade62d..a014e9f645 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -5,7 +5,8 @@
 // it, and was left in the middle instead; the panel (src/components/launch/hudPanel.ts) then
 // opened on top of it, and a toast covered the very controls it was about. Hyprland's IPC socket
 // can move a window, so on Hyprland the bar is moved to the bottom and the panel next to it
-// after each maps. Both are pinned too: `alwaysOnTop` means nothing on Wayland, and a window
+// after each maps. The panel, shown and hidden as often as a popover opens, is also placed
+// before it maps, by a window rule, or it would be seen opening mid-screen and then jumping. Both are pinned too: `alwaysOnTop` means nothing on Wayland, and a window
 // made fullscreen or maximized (Omarchy's Super+F, Super+Alt+F) otherwise covers the bar,
 // which is how the user stops a recording. Best effort only: anything unexpected leaves the
 // window where the compositor put it.
@@ -141,6 +142,86 @@ const toRect = (client: HyprlandClient): Rect => ({
 	height: client.size[1],
 });
 
+/** The bar among this process's windows: the size this process gave it, and not the panel. */
+function findBar(
+	clients: HyprlandClient[],
+	options: { pid: number; panelTitle: string; barSize: { width: number; height: number } },
+): HyprlandClient | undefined {
+	return clients.find(
+		(client) =>
+			client.pid === options.pid &&
+			client.title !== options.panelTitle &&
+			client.size[0] === options.barSize.width &&
+			client.size[1] === options.barSize.height,
+	);
+}
+
+/** Name of the window rule that places the panel as it maps; replaced on every show. */
+const PANEL_RULE = "openscreen-hud-panel";
+
+/**
+ * The Lua that (re)defines the panel's window rule: floating, at its size, and at `x`,`y`
+ * relative to its monitor, which is how a rule's `move` is read. The size is in the rule because
+ * a window mapping for the first time has not had the size it was given applied yet: it maps
+ * small and then grows, away from where it was placed. Not pinned here: a window pinned by a rule
+ * as it maps stays under a fullscreen window, where one pinned after it maps is drawn above it, so
+ * `placeHudPanelNearBar` pins it. Null for a title that would need escaping.
+ */
+export function panelPlacementRule(
+	title: string,
+	size: { width: number; height: number },
+	x: number,
+	y: number,
+): string | null {
+	// Nothing to escape, for the regex or the Lua string it sits in.
+	if (!/^[\w ]+$/.test(title)) return null;
+	return (
+		`hl.window_rule({ name = "${PANEL_RULE}", match = { title = "^(${title})$" }, ` +
+		`float = true, size = "${Math.round(size.width)} ${Math.round(size.height)}", ` +
+		`move = "${Math.round(x)} ${Math.round(y)}" })`
+	);
+}
+
+/**
+ * Before the panel is shown: a window rule that maps it next to the bar, so it never appears
+ * where Hyprland would centre it. Resolves false when not under Hyprland, on a Hyprland
+ * without Lua, or when the bar cannot be found; the panel is then moved after it maps instead.
+ */
+export async function presetHudPanelPlacement(options: {
+	env: Env;
+	pid: number;
+	panelTitle: string;
+	panelSize: { width: number; height: number };
+	barSize: { width: number; height: number };
+	gap: number;
+}): Promise<boolean> {
+	const socketPath = hyprlandSocketPath(options.env);
+	if (!socketPath) return false;
+	const [clients, monitors] = await Promise.all([
+		requestJson<HyprlandClient[]>(socketPath, "clients"),
+		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+	]);
+	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+	const bar = findBar(clients, options);
+	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
+	if (!bar || !monitor) return false;
+
+	const { x, y } = panelPositionNearBar(
+		toRect(bar),
+		options.panelSize,
+		monitorWorkArea(monitor),
+		options.gap,
+	);
+	const rule = panelPlacementRule(
+		options.panelTitle,
+		options.panelSize,
+		x - monitor.x,
+		y - monitor.y,
+	);
+	if (!rule) return false;
+	return (await request(socketPath, `eval ${rule}`))?.trim() === "ok";
+}
+
 /**
  * Moves the panel window next to the bar. Both are found among this process's clients: the
  * panel by its title, the bar by the size this process gave it. Resolves false when not under
@@ -161,14 +242,10 @@ export async function placeHudPanelNearBar(options: {
 	]);
 	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
 
-	const ours = clients.filter((client) => client.pid === options.pid);
-	const panel = ours.find((client) => client.title === options.panelTitle);
-	const bar = ours.find(
-		(client) =>
-			client !== panel &&
-			client.size[0] === options.barSize.width &&
-			client.size[1] === options.barSize.height,
+	const panel = clients.find(
+		(client) => client.pid === options.pid && client.title === options.panelTitle,
 	);
+	const bar = findBar(clients, options);
 	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
 	if (!panel || !bar || !monitor) return false;
 
@@ -203,13 +280,7 @@ export async function placeHudBarAtBottom(options: {
 	]);
 	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
 
-	const bar = clients.find(
-		(client) =>
-			client.pid === options.pid &&
-			client.title !== options.panelTitle &&
-			client.size[0] === options.barSize.width &&
-			client.size[1] === options.barSize.height,
-	);
+	const bar = findBar(clients, options);
 	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
 	if (!bar || !monitor) return false;
 
diff --git a/electron/windows.ts b/electron/windows.ts
index 395ef88513..c312d41328 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -25,7 +25,7 @@ import {
 	parseHudContentRect,
 	sameRect,
 } from "./hudWindowBounds";
-import { placeHudBarAtBottom, placeHudPanelNearBar } from "./hyprland";
+import { placeHudBarAtBottom, placeHudPanelNearBar, presetHudPanelPlacement } from "./hyprland";
 import { keepAlwaysOnTop, reassertAlwaysOnTop } from "./keepOnTop";
 import { followAcrossSpaces } from "./macSpaces";
 import { markSheetless } from "./messageBox";
@@ -569,7 +569,7 @@ export function createHudOverlayWindow(): BrowserWindow {
 		placeHudBar();
 		const panel = hudPanelWindow;
 		if (panel && !panel.isDestroyed() && hudPanelState && hudPanelHasContent(hudPanelState)) {
-			revealHudPanel(panel, hudPanelState);
+			revealHudPanel(panel);
 		}
 	});
 	win.on("blur", checkHudPanelFocus);
@@ -604,6 +604,9 @@ const HUD_PANEL_GAP = 8;
 /** Fixed, so Hyprland's IPC can tell the panel from the bar (see placeHudPanelNearBar). */
 const HUD_PANEL_TITLE = "OpenScreen panel";
 let hudPanelPlacementTimer: ReturnType<typeof setTimeout> | null = null;
+let hudPanelRevealTimer: ReturnType<typeof setTimeout> | null = null;
+/** How long a panel about to show on Hyprland waits for its size to stop changing. */
+const HUD_PANEL_SETTLE_MS = 80;
 
 /**
  * On Hyprland, moves the panel next to the bar: the compositor centres it on the monitor,
@@ -774,14 +777,31 @@ ipcMain.on("hud-panel-action", (event, action: HudPanelAction) => {
 
 /** Shows the panel and places it at the bar. A popover takes focus, so its keyboard handling
  * works straight away; a notice or a toast appearing must not pull focus away from whatever the
- * user is doing. */
-function revealHudPanel(win: BrowserWindow, state: HudPanelState) {
-	if (hudPanelHasPopover(state)) {
-		win.show();
-	} else {
-		win.showInactive();
-	}
-	placeHudPanel();
+ * user is doing.
+ *
+ * On Hyprland a window rule places the panel first, or every show would map it mid-screen and
+ * then jump it to the bar. The move after it maps stays, for a Hyprland the rule did not reach. */
+function revealHudPanel(win: BrowserWindow, size?: { width: number; height: number }) {
+	// The size just asked for, when there is one: an unmapped window reports its old size.
+	const [width, height] = size ? [size.width, size.height] : win.getSize();
+	void presetHudPanelPlacement({
+		env: process.env,
+		pid: process.pid,
+		panelTitle: HUD_PANEL_TITLE,
+		panelSize: { width, height },
+		barSize: hudWindowSize,
+		gap: HUD_PANEL_GAP,
+	}).finally(() => {
+		// The state can have moved on while Hyprland answered.
+		const state = hudPanelState;
+		if (win.isDestroyed() || win.isVisible() || !state || !hudPanelHasContent(state)) return;
+		if (hudPanelHasPopover(state)) {
+			win.show();
+		} else {
+			win.showInactive();
+		}
+		placeHudPanel();
+	});
 }
 
 ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
@@ -810,7 +830,18 @@ ipcMain.on("hud-panel-set-size", (event, width: number, height: number) => {
 		);
 	}
 	if (!win.isVisible()) {
-		revealHudPanel(win, hudPanelState);
+		// On Hyprland the panel is placed for the size it maps at (revealHudPanel), and content
+		// still loading reports a second, taller size moments later — the device list, for one —
+		// which then moved the panel in plain sight. So it waits for the size to settle first.
+		if (hudPanelRevealTimer) clearTimeout(hudPanelRevealTimer);
+		if (!process.env.HYPRLAND_INSTANCE_SIGNATURE) {
+			revealHudPanel(win, size);
+			return;
+		}
+		hudPanelRevealTimer = setTimeout(() => {
+			hudPanelRevealTimer = null;
+			if (!win.isDestroyed()) revealHudPanel(win, size);
+		}, HUD_PANEL_SETTLE_MS);
 	} else if (resized) {
 		// Hyprland keeps a resized floating window centred where it was, off the bar's edge.
 		placeHudPanel();

From 7b8573d3f8f30daddcbb6c96257563896da468a4 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 01:46:00 -0700
Subject: [PATCH 24/27] fix(linux): ask for a persistent portal grant only on
 Hyprland

Restart replays the discarded take's grant so it raises no second picker,
which on Hyprland stalls behind the portal closing the previous session.
That needs a grant that outlives the helper, and every take asked for one
on every Linux desktop: an entry in the portal's permission store per take,
and a request no other backend was tested with.

The helper now asks for it only when the request sets `persistGrant`, and
main sets it only under Hyprland (`runsUnderHyprland`). Everywhere else a
take keeps the unpersisted grant it always had, and Restart asks again.
---
 electron/hyprland.test.ts                     | 12 +++++++++++
 electron/hyprland.ts                          |  5 +++++
 electron/ipc/handlers.ts                      |  9 ++++++++
 .../capture/linuxNativeCaptureSession.test.ts | 21 ++++++++++++++++++-
 .../capture/linuxNativeCaptureSession.ts      |  7 +++++++
 electron/native/pipewire-capture/src/main.rs  |  6 ++++++
 .../native/pipewire-capture/src/portal.rs     | 12 +++++++++--
 7 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index e63425f98e..9dd2bc9ef3 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -12,6 +12,7 @@ import {
 	placeHudBarAtBottom,
 	placeHudPanelNearBar,
 	presetHudPanelPlacement,
+	runsUnderHyprland,
 } from "./hyprland";
 
 const workArea = { x: 0, y: 22, width: 1920, height: 1058 };
@@ -89,6 +90,17 @@ describe("monitorWorkArea", () => {
 	});
 });
 
+describe("runsUnderHyprland", () => {
+	// Gates every Hyprland-only behaviour, so no other desktop is touched by it.
+	it("is true only on Linux with a Hyprland instance", () => {
+		const env = { HYPRLAND_INSTANCE_SIGNATURE: "sig" };
+		expect(runsUnderHyprland(env, "linux")).toBe(true);
+		expect(runsUnderHyprland({}, "linux")).toBe(false);
+		expect(runsUnderHyprland({ XDG_CURRENT_DESKTOP: "GNOME" }, "linux")).toBe(false);
+		expect(runsUnderHyprland(env, "win32")).toBe(false);
+	});
+});
+
 describe("hyprlandSocketPath", () => {
 	it("is null outside a Hyprland session", () => {
 		expect(hyprlandSocketPath({ XDG_RUNTIME_DIR: "/run/user/1000" })).toBeNull();
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index a014e9f645..c119b3ef6b 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -45,6 +45,11 @@ interface HyprlandMonitor {
 
 const IPC_TIMEOUT_MS = 500;
 
+/** Whether this process runs in a Hyprland session, whatever distribution ships it. */
+export function runsUnderHyprland(env: Env, platform: string = process.platform): boolean {
+	return platform === "linux" && Boolean(env.HYPRLAND_INSTANCE_SIGNATURE);
+}
+
 /** The request socket of the Hyprland instance this process runs under, or null outside one. */
 export function hyprlandSocketPath(env: Env): string | null {
 	const signature = env.HYPRLAND_INSTANCE_SIGNATURE;
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 58e3ae61bb..6fd1ea7bdb 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -72,6 +72,7 @@ import { AppSettingsStore } from "../app-settings";
 import { createRunnerHost } from "../cli/runnerHost";
 import { hideCountdownOverlay } from "../countdownOverlay";
 import { isDiagnosticModeEnabled, mainLogBuffer } from "../diagnostics/main-log-buffer";
+import { runsUnderHyprland } from "../hyprland";
 import { mainT } from "../i18n";
 import { getInstallChannel } from "../install-channel";
 import {
@@ -930,6 +931,12 @@ let preparingLinuxCaptureToken: symbol | null = null;
  * discarded take's session (a 25 s timeout on Hyprland), so nothing appears.
  */
 let linuxRestartRestoreToken: string | null = null;
+/**
+ * Whether takes ask the portal for a grant Restart can replay. Only on Hyprland, the one place
+ * the second picker was seen to stall: everywhere else a take keeps the unpersisted grant it
+ * always had, leaves nothing in the portal's permission store, and Restart asks again.
+ */
+const LINUX_CAPTURE_PERSISTS_GRANT = runsUnderHyprland(process.env);
 
 /** Hands the discarded take's token to a Restart, and drops it for anything else. */
 function takeLinuxRestartRestoreToken(request: NativeLinuxRecordingRequest): string | undefined {
@@ -2682,6 +2689,7 @@ export function registerIpcHandlers(
 					},
 					maxCursorSamples: MAX_CURSOR_SAMPLES,
 					deferStart: true,
+					...(LINUX_CAPTURE_PERSISTS_GRANT ? { persistGrant: true } : {}),
 				});
 				lastLinuxCaptureSession = session;
 
@@ -2769,6 +2777,7 @@ export function registerIpcHandlers(
 						},
 						maxCursorSamples: MAX_CURSOR_SAMPLES,
 						...(restoreToken ? { restoreToken } : {}),
+						...(LINUX_CAPTURE_PERSISTS_GRANT ? { persistGrant: true } : {}),
 					});
 				lastLinuxCaptureSession = session;
 
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
index 97a2f64b95..9cc60fcfdb 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.test.ts
@@ -324,7 +324,26 @@ describe("LinuxNativeCaptureSession", () => {
 		await startReady(newSession());
 
 		const [, args] = spawnMock.mock.calls[0];
-		expect(JSON.parse((args as string[])[0])).not.toHaveProperty("restoreToken");
+		const request = JSON.parse((args as string[])[0]);
+		expect(request).not.toHaveProperty("restoreToken");
+		// Nor asks for a grant that would outlive the helper: only Hyprland does.
+		expect(request).not.toHaveProperty("persistGrant");
+	});
+
+	it("asks for a persistent grant only when configured to", async () => {
+		await startReady(
+			new LinuxNativeCaptureSession({
+				outputPath: "/tmp/recording.mp4",
+				cursorMode: "metadata",
+				fps: 30,
+				audio: { system: { enabled: false }, microphone: { enabled: false, gain: 1 } },
+				maxCursorSamples: 100,
+				persistGrant: true,
+			}),
+		);
+
+		const [, args] = spawnMock.mock.calls[0];
+		expect(JSON.parse((args as string[])[0])).toMatchObject({ persistGrant: true });
 	});
 
 	it("replays the token it was given, and keeps the grant's new one", async () => {
diff --git a/electron/native-bridge/capture/linuxNativeCaptureSession.ts b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
index 53e74c43dc..f3445c5894 100644
--- a/electron/native-bridge/capture/linuxNativeCaptureSession.ts
+++ b/electron/native-bridge/capture/linuxNativeCaptureSession.ts
@@ -83,6 +83,12 @@ export interface LinuxCaptureConfig {
 	 * `portal::negotiate`).
 	 */
 	restoreToken?: string;
+	/**
+	 * Ask the portal for a grant that outlives the helper, so [`restoreToken`] gets a token to
+	 * hand to a Restart. Only where a second picker stalls (Hyprland); elsewhere the grant stays
+	 * unpersisted, as it always was.
+	 */
+	persistGrant?: boolean;
 }
 
 /** What the portal handed over. `undefined` means the backend did not say. */
@@ -167,6 +173,7 @@ export class LinuxNativeCaptureSession {
 			audio: this.config.audio,
 			...(this.config.deferStart ? { deferStart: true } : {}),
 			...(this.config.restoreToken ? { restoreToken: this.config.restoreToken } : {}),
+			...(this.config.persistGrant ? { persistGrant: true } : {}),
 		};
 
 		const child = spawn(helperPath, [JSON.stringify(request)], {
diff --git a/electron/native/pipewire-capture/src/main.rs b/electron/native/pipewire-capture/src/main.rs
index 63983486dc..0bcd5ae0ad 100644
--- a/electron/native/pipewire-capture/src/main.rs
+++ b/electron/native/pipewire-capture/src/main.rs
@@ -140,6 +140,9 @@ struct Request {
     /// A token from an earlier take's `source-selected`, to share that source
     /// again without the picker. Only Restart sends one; see `portal::negotiate`.
     restore_token: Option<String>,
+    /// Ask for a grant that outlives this helper, so its `source-selected`
+    /// carries a token Restart can replay. Off by default; see `portal::negotiate`.
+    persist_grant: bool,
     /// Emit `ready` and exit, without ever calling the portal's `Start()`.
     ///
     /// Everything up to that point is non-interactive; `Start()` is the single
@@ -346,6 +349,7 @@ fn main() {
         cursor_mode,
         monitors_only,
         request.restore_token.clone(),
+        request.persist_grant,
     );
     if let Some(socket) = host_pointer_socket.clone() {
         hyprland::spawn_poller(sender.clone(), socket, sample_interval);
@@ -571,12 +575,14 @@ fn spawn_portal(
     cursor_mode: portal::CursorMode,
     monitors_only: bool,
     restore_token: Option<String>,
+    persist_grant: bool,
 ) {
     std::thread::spawn(move || {
         let result = pollster::block_on(portal::negotiate(
             cursor_mode,
             monitors_only,
             restore_token.as_deref(),
+            persist_grant,
         ));
         let _ = sender.send(Message::Portal(Box::new(result)));
     });
diff --git a/electron/native/pipewire-capture/src/portal.rs b/electron/native/pipewire-capture/src/portal.rs
index 32a2ad7a24..0e70e6eb4e 100644
--- a/electron/native/pipewire-capture/src/portal.rs
+++ b/electron/native/pipewire-capture/src/portal.rs
@@ -255,6 +255,7 @@ pub async fn negotiate(
     cursor_mode: CursorMode,
     monitors_only: bool,
     restore_token: Option<&str>,
+    persist_grant: bool,
 ) -> Result<PortalStream, PortalError> {
     let proxy = Screencast::new().await.map_err(portal_unavailable)?;
 
@@ -309,9 +310,16 @@ pub async fn negotiate(
             //
             // Persistent because a transient grant belongs to the process that
             // asked for it, and every take is a new helper. The caller keeps
-            // the token in memory and hands it back once, for one Restart.
+            // the token in memory and hands it back once, for one Restart —
+            // and asks for it only where that stall was seen (Hyprland). Every
+            // other desktop keeps the non-persisted grant it always had: no
+            // token, no permission-store entry, and Restart raises the picker.
             restore_token,
-            PersistMode::ExplicitlyRevoked,
+            if persist_grant {
+                PersistMode::ExplicitlyRevoked
+            } else {
+                PersistMode::DoNot
+            },
         )
         .await
         .map_err(|error| failed("SelectSources", error))?

From 982fe7f692eff82b7f1bff885953adf97b4ab8ba Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 01:46:50 -0700
Subject: [PATCH 25/27] fix(linux): draw the HUD square inside Hyprland's own
 frame

Hyprland frames every window, frameless or not, with the desktop's border
and corner rounding (2 px and 6 px on Omarchy). Inside that frame the bar
drew its own 17 px pill and the panel its rounded, padded cards, so two
mismatched corners showed at each edge.

Where Hyprland runs, main passes the bar's and the panel's windows
`--hud-framed-by-compositor`, and they render square and flat inside the
compositor's frame: no outer radius, border or shadow, and no padding
around the panel's cards. A toast keeps its coloured stripe. Every other
desktop draws nothing around a frameless window and keeps the rounded
look, as do Windows and macOS.
---
 electron/electron-env.d.ts                    |  2 ++
 electron/hudWindowArgs.ts                     |  5 ++++
 electron/preload.ts                           |  6 +++++
 electron/windows.ts                           | 23 ++++++++++++++---
 src/components/launch/HudPanelWindow.tsx      | 12 ++++++---
 src/components/launch/LaunchWindow.module.css | 25 +++++++++++++++++++
 src/components/launch/LaunchWindow.tsx        |  6 ++++-
 7 files changed, 71 insertions(+), 8 deletions(-)
 create mode 100644 electron/hudWindowArgs.ts

diff --git a/electron/electron-env.d.ts b/electron/electron-env.d.ts
index 342a133a19..b8b0734fd5 100644
--- a/electron/electron-env.d.ts
+++ b/electron/electron-env.d.ts
@@ -464,6 +464,8 @@ interface Window {
 		quitApp: () => void;
 		setTitleBarOverlay: (color: string, symbolColor: string) => void;
 		getPlatform: () => string;
+		/** True in the HUD bar's and panel's windows when the compositor draws their frame. */
+		isHudFramedByCompositor?: () => boolean;
 		getSystemVersion: () => string;
 		getAppInfo: () => Promise<{ version: string; canCheckForUpdates: boolean }>;
 		checkForUpdates: () => Promise<void>;
diff --git a/electron/hudWindowArgs.ts b/electron/hudWindowArgs.ts
new file mode 100644
index 0000000000..d033a6a5ec
--- /dev/null
+++ b/electron/hudWindowArgs.ts
@@ -0,0 +1,5 @@
+/**
+ * Passed to the HUD bar's and panel's preload when the compositor frames their windows itself
+ * (Hyprland), so the renderer draws them square inside that frame. Shared by main and preload.
+ */
+export const HUD_FRAMED_BY_COMPOSITOR_ARG = "--hud-framed-by-compositor";
diff --git a/electron/preload.ts b/electron/preload.ts
index 2f52923c14..be25a3f665 100644
--- a/electron/preload.ts
+++ b/electron/preload.ts
@@ -18,6 +18,7 @@ import {
 	NATIVE_BRIDGE_CHANNEL,
 	type NativeBridgeRequest,
 } from "../src/native/contracts";
+import { HUD_FRAMED_BY_COMPOSITOR_ARG } from "./hudWindowArgs";
 import type { RecordingPrefs } from "./ipc/handlers";
 import type {
 	SttStatusEvent,
@@ -35,6 +36,8 @@ const assetBaseUrl = assetBaseUrlArg ? assetBaseUrlArg.slice(ASSET_BASE_URL_ARG_
 // Renderer side: process.platform is the same Node global as in the main process,
 // so a synchronous read here saves the renderer's every-call IPC round-trip.
 const PLATFORM = process.platform;
+// Given to the HUD bar's and panel's windows only, and only where the compositor frames them.
+const HUD_FRAMED_BY_COMPOSITOR = process.argv.includes(HUD_FRAMED_BY_COMPOSITOR_ARG);
 
 // Preview frames the main process hands over as shared GPU textures (see
 // `compositorViewService`). Electron gives up on a send after 1 s without a receiver, so it is
@@ -501,6 +504,9 @@ contextBridge.exposeInMainWorld("electronAPI", {
 		ipcRenderer.send("set-titlebar-overlay", color, symbolColor);
 	},
 	getPlatform: () => PLATFORM,
+	/** True in the HUD bar's and panel's windows when the compositor draws their frame
+	 *  (Hyprland): they render square inside it instead of drawing a rounded one of their own. */
+	isHudFramedByCompositor: () => HUD_FRAMED_BY_COMPOSITOR,
 	/** The OS version, as the main process reads it: "14.6.1" on macOS, not the Darwin
 	 *  kernel's "23.6.0" that `os.release()` gives. Part of the sandboxed preload's `process`. */
 	getSystemVersion: () => process.getSystemVersion(),
diff --git a/electron/windows.ts b/electron/windows.ts
index c312d41328..7417d524d9 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -14,6 +14,7 @@ import {
 	shouldTrackEditorWindow,
 	WAYLAND_MAXIMIZE_SETTLE_MS,
 } from "./editorWindowState";
+import { HUD_FRAMED_BY_COMPOSITOR_ARG } from "./hudWindowArgs";
 import {
 	clampHudBoundsToWorkArea,
 	HUD_WINDOW_MIN,
@@ -25,7 +26,12 @@ import {
 	parseHudContentRect,
 	sameRect,
 } from "./hudWindowBounds";
-import { placeHudBarAtBottom, placeHudPanelNearBar, presetHudPanelPlacement } from "./hyprland";
+import {
+	placeHudBarAtBottom,
+	placeHudPanelNearBar,
+	presetHudPanelPlacement,
+	runsUnderHyprland,
+} from "./hyprland";
 import { keepAlwaysOnTop, reassertAlwaysOnTop } from "./keepOnTop";
 import { followAcrossSpaces } from "./macSpaces";
 import { markSheetless } from "./messageBox";
@@ -153,6 +159,17 @@ const ASSET_BASE_DIR = process.defaultApp
 	: process.resourcesPath;
 export const ASSET_BASE_URL_ARG = `--asset-base-url=${pathToFileURL(`${ASSET_BASE_DIR}${path.sep}`).toString()}`;
 
+/**
+ * For the HUD bar and its panel: the compositor draws their windows' frame, with the desktop's
+ * own border and corner rounding, so they render square inside it (LaunchWindow.module.css).
+ * Hyprland does that to every window, frameless or not. Other desktops draw nothing around a
+ * frameless window, so there the bar keeps its own rounded shape.
+ */
+const HUD_WINDOW_ARGUMENTS = [
+	ASSET_BASE_URL_ARG,
+	...(runsUnderHyprland(process.env) ? [HUD_FRAMED_BY_COMPOSITOR_ARG] : []),
+];
+
 let hudOverlayWindow: BrowserWindow | null = null;
 
 // The HUD's size in DIP, as last given: at creation, then by "hud-overlay-set-size".
@@ -507,7 +524,7 @@ export function createHudOverlayWindow(): BrowserWindow {
 		show: false, // shown via ready-to-show to avoid black rectangle flash
 		webPreferences: {
 			preload: path.join(__dirname, "preload.mjs"),
-			additionalArguments: [ASSET_BASE_URL_ARG],
+			additionalArguments: HUD_WINDOW_ARGUMENTS,
 			nodeIntegration: false,
 			contextIsolation: true,
 			backgroundThrottling: false,
@@ -709,7 +726,7 @@ function createHudPanelWindow(): BrowserWindow {
 		// one it is placed like any new window, which most compositors keep clear of others.
 		webPreferences: {
 			preload: path.join(__dirname, "preload.mjs"),
-			additionalArguments: [ASSET_BASE_URL_ARG],
+			additionalArguments: HUD_WINDOW_ARGUMENTS,
 			nodeIntegration: false,
 			contextIsolation: true,
 			backgroundThrottling: false,
diff --git a/src/components/launch/HudPanelWindow.tsx b/src/components/launch/HudPanelWindow.tsx
index 651f1dc5a7..26ec1851a4 100644
--- a/src/components/launch/HudPanelWindow.tsx
+++ b/src/components/launch/HudPanelWindow.tsx
@@ -13,8 +13,12 @@ import {
 } from "./hudPanel";
 import styles from "./LaunchWindow.module.css";
 
-/** Padding around the stack, so the cards' rounded corners keep clear of the window edge. */
-const PANEL_PADDING = 10;
+/**
+ * Where the compositor frames the panel (Hyprland), the cards go square and fill its window to
+ * that frame. Elsewhere they keep their rounded corners, with this much room to the edge.
+ */
+const FRAMED_BY_COMPOSITOR = window.electronAPI?.isHudFramedByCompositor?.() === true;
+const PANEL_PADDING = FRAMED_BY_COMPOSITOR ? 0 : 10;
 const send = (action: HudPanelAction) => window.electronAPI?.sendHudPanelAction?.(action);
 const noop = () => undefined;
 
@@ -45,7 +49,7 @@ function HudPanelToastCard({ toast, closeLabel }: { toast: HudPanelToast; closeL
 		<div
 			role={type === "error" ? "alert" : "status"}
 			data-testid="hud-panel-toast"
-			className={`${styles.hudNotice} w-full border-l-4 ${accent} p-3 text-white`}
+			className={`${styles.hudNotice} ${styles.hudPanelToast} w-full border-l-4 ${accent} p-3 text-white`}
 		>
 			<div className="flex items-start gap-2">
 				<div className="min-w-0 flex-1">
@@ -133,7 +137,7 @@ export function HudPanelWindow() {
 		<div
 			ref={rootRef}
 			data-testid="hud-panel"
-			className="flex w-max flex-col items-stretch gap-[10px]"
+			className={`${FRAMED_BY_COMPOSITOR ? styles.hudPanelFramed : ""} flex w-max flex-col items-stretch gap-[10px]`}
 			style={
 				{
 					padding: PANEL_PADDING,
diff --git a/src/components/launch/LaunchWindow.module.css b/src/components/launch/LaunchWindow.module.css
index 391daed352..19e624675b 100644
--- a/src/components/launch/LaunchWindow.module.css
+++ b/src/components/launch/LaunchWindow.module.css
@@ -62,6 +62,16 @@
 	backdrop-filter: blur(24px) saturate(140%);
 }
 
+/* Where the compositor frames the bar's window with the desktop's own border and corner
+   rounding (Hyprland, isHudFramedByCompositor), the bar fills that window square rather than
+   drawing a second, rounder frame inside it. Other Linux desktops draw no frame around it, and
+   keep the rounded bar. */
+.hudBarFramed {
+	border-radius: 0;
+	border: 0;
+	box-shadow: none;
+}
+
 .hudBarHorizontal {
 	align-items: center;
 	gap: 5px;
@@ -90,6 +100,21 @@
 	box-shadow: 0 20px 44px -14px rgba(0, 0, 0, 0.6), 0 4px 12px rgba(0, 0, 0, 0.4);
 }
 
+/* The same for the panel window those surfaces are shown in on Linux (hudPanel.ts), where
+   the compositor frames it: its frame is theirs, so they go square and flat inside it. */
+.hudPanelFramed .hudPopover,
+.hudPanelFramed .hudModal,
+.hudPanelFramed .hudNotice {
+	border-radius: 0;
+	border-width: 0;
+	box-shadow: none;
+}
+
+/* A toast keeps its coloured stripe: it is what says which kind of toast it is. */
+.hudPanelFramed .hudPanelToast {
+	border-left-width: 4px;
+}
+
 /* Shared shell for every floating HUD menu (language list, device pickers), so
    they all reserve the same space in the window. */
 .hudPopover {
diff --git a/src/components/launch/LaunchWindow.tsx b/src/components/launch/LaunchWindow.tsx
index be774fbbd4..b54f3fb97f 100644
--- a/src/components/launch/LaunchWindow.tsx
+++ b/src/components/launch/LaunchWindow.tsx
@@ -168,6 +168,10 @@ export function LaunchWindow() {
 	const [floatsInPanel] = useState(
 		() => getPlatform() === "linux" && typeof window.electronAPI?.sendHudPanelState === "function",
 	);
+	// Square inside the compositor's own frame (Hyprland), instead of a rounded bar of its own.
+	const [framedByCompositor] = useState(
+		() => floatsInPanel && window.electronAPI?.isHudFramedByCompositor?.() === true,
+	);
 	// The running version, and whether this copy may offer an update check at all — a
 	// Store/Flathub/Snap/Nix install is kept current by its package manager and is offered
 	// nothing (electron/install-channel.ts). Asked once: neither answer changes while the app
@@ -1400,7 +1404,7 @@ export function LaunchWindow() {
 							ref={setHudBarEl}
 							data-hud-interactive="true"
 							data-tray-layout={trayLayout}
-							className={`${styles.hudBar} ${isVertical ? styles.hudBarVertical : styles.hudBarHorizontal}`}
+							className={`${styles.hudBar} ${isVertical ? styles.hudBarVertical : styles.hudBarHorizontal} ${framedByCompositor ? styles.hudBarFramed : ""}`}
 							onPointerEnter={enableHudMouseEvents}
 							onPointerDown={enableHudMouseEvents}
 							onMouseEnter={enableHudMouseEvents}

From 9030a1a47f975e0fca3936737e413710c0cbac57 Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 01:47:06 -0700
Subject: [PATCH 26/27] fix(linux): place the HUD bar before it maps on
 Hyprland

Hyprland centres a new window, so the bar opened mid-screen and was seen
moving to the bottom a moment later, at launch and each time it was shown
again after being hidden.

Under Hyprland the bar's window now has a fixed title, and before it is
shown a named window rule set over Hyprland's IPC maps it floating at the
bottom centre of the monitor it opens on, at its size. The rule follows
every resize, for the next show. The first show waits for the renderer to
report the bar's size, bounded from ready-to-show rather than from window
creation: under the dev server the page took longer than the bound to
load and the bar mapped at its creation size, its top mid-screen. The move
and pin after mapping stay as the fallback. Elsewhere the window keeps the
page's title and shows as before.
---
 electron/hyprland.test.ts | 63 +++++++++++++++++++++++++++++++++---
 electron/hyprland.ts      | 68 ++++++++++++++++++++++++++++++++-------
 electron/windows.ts       | 66 +++++++++++++++++++++++++++++++++++--
 3 files changed, 179 insertions(+), 18 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index 9dd2bc9ef3..0202574df3 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -7,12 +7,13 @@ import {
 	barPositionAtBottom,
 	hyprlandSocketPath,
 	monitorWorkArea,
-	panelPlacementRule,
 	panelPositionNearBar,
 	placeHudBarAtBottom,
 	placeHudPanelNearBar,
+	presetHudBarPlacement,
 	presetHudPanelPlacement,
 	runsUnderHyprland,
+	windowPlacementRule,
 } from "./hyprland";
 
 const workArea = { x: 0, y: 22, width: 1920, height: 1058 };
@@ -61,16 +62,32 @@ describe("barPositionAtBottom", () => {
 	});
 });
 
-describe("panelPlacementRule", () => {
+describe("windowPlacementRule", () => {
 	it("floats the panel at its size and a monitor-relative position", () => {
-		expect(panelPlacementRule("OpenScreen panel", { width: 382, height: 300 }, 769.4, 168)).toBe(
+		expect(
+			windowPlacementRule(
+				"openscreen-hud-panel",
+				"OpenScreen panel",
+				{ width: 382, height: 300 },
+				769.4,
+				168,
+			),
+		).toBe(
 			'hl.window_rule({ name = "openscreen-hud-panel", match = { title = "^(OpenScreen panel)$" }, ' +
 				'float = true, size = "382 300", move = "769 168" })',
 		);
 	});
 
 	it("refuses a title it would have to escape", () => {
-		expect(panelPlacementRule('a "quoted" (title)', { width: 1, height: 1 }, 0, 0)).toBeNull();
+		expect(
+			windowPlacementRule(
+				"openscreen-hud-panel",
+				'a "quoted" (title)',
+				{ width: 1, height: 1 },
+				0,
+				0,
+			),
+		).toBeNull();
 	});
 });
 
@@ -322,7 +339,7 @@ describe("placeHudPanelNearBar", () => {
 			},
 		]);
 		// Placed in that monitor's work area, but handed to the rule relative to the monitor.
-		const rule = `eval ${panelPlacementRule("OpenScreen panel", { width: 382, height: 300 }, 769, 168)}`;
+		const rule = `eval ${windowPlacementRule("openscreen-hud-panel", "OpenScreen panel", { width: 382, height: 300 }, 769, 168)}`;
 		const { env, received } = await fakeHyprland({
 			"j/clients": onSecondMonitor,
 			"j/monitors": JSON.stringify([
@@ -344,6 +361,42 @@ describe("placeHudPanelNearBar", () => {
 		expect(preset).toBe(true);
 	});
 
+	// At launch the bar has not mapped yet: the rule is set for the focused monitor, where it
+	// opens, so it never appears mid-screen first.
+	it("sets a rule that maps the bar at the bottom of the focused monitor before it shows", async () => {
+		const rule = `eval ${windowPlacementRule("openscreen-hud-bar", "OpenScreen recording bar", { width: 528, height: 54 }, 696, 1021)}`;
+		const { env, received } = await fakeHyprland({
+			"j/clients": "[]",
+			"j/monitors": JSON.stringify([
+				{ id: 1, x: 0, y: 0, width: 1920, height: 1080, scale: 1, reserved: [0, 0, 0, 0] },
+				{
+					id: 2,
+					x: 1920,
+					y: 0,
+					width: 3840,
+					height: 2160,
+					scale: 2,
+					reserved: [0, 22, 0, 0],
+					focused: true,
+				},
+			]),
+			[rule]: "ok",
+		});
+
+		const preset = await presetHudBarPlacement({
+			env,
+			pid: 42,
+			barTitle: "OpenScreen recording bar",
+			panelTitle: "OpenScreen panel",
+			barSize: { width: 528, height: 54 },
+			margin: 5,
+		});
+
+		// Bottom centre of the focused monitor's work area, relative to that monitor.
+		expect(received).toContain(rule);
+		expect(preset).toBe(true);
+	});
+
 	it("gives up quietly outside Hyprland", async () => {
 		await expect(
 			placeHudPanelNearBar({
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index c119b3ef6b..9102c49288 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -41,6 +41,8 @@ interface HyprlandMonitor {
 	scale: number;
 	/** Logical px taken by bars and docks: left, top, right, bottom. */
 	reserved: [number, number, number, number];
+	/** The monitor a new window opens on. */
+	focused?: boolean;
 }
 
 const IPC_TIMEOUT_MS = 500;
@@ -161,18 +163,21 @@ function findBar(
 	);
 }
 
-/** Name of the window rule that places the panel as it maps; replaced on every show. */
-const PANEL_RULE = "openscreen-hud-panel";
+/** Names of the window rules that place the panel and the bar as they map; replaced as they change. */
+export const PANEL_RULE = "openscreen-hud-panel";
+export const BAR_RULE = "openscreen-hud-bar";
 
 /**
- * The Lua that (re)defines the panel's window rule: floating, at its size, and at `x`,`y`
- * relative to its monitor, which is how a rule's `move` is read. The size is in the rule because
- * a window mapping for the first time has not had the size it was given applied yet: it maps
- * small and then grows, away from where it was placed. Not pinned here: a window pinned by a rule
- * as it maps stays under a fullscreen window, where one pinned after it maps is drawn above it, so
- * `placeHudPanelNearBar` pins it. Null for a title that would need escaping.
+ * The Lua that (re)defines a window rule placing the window titled `title`: floating, at its
+ * size, and at `x`,`y` relative to its monitor, which is how a rule's `move` is read. The size is
+ * in the rule because a window mapping for the first time has not had the size it was given
+ * applied yet: it maps small and then grows, away from where it was placed. Not pinned here: a
+ * window pinned by a rule as it maps stays under a fullscreen window, where one pinned after it
+ * maps is drawn above it, so the moves after mapping pin it. Null for a title that would need
+ * escaping.
  */
-export function panelPlacementRule(
+export function windowPlacementRule(
+	ruleName: string,
 	title: string,
 	size: { width: number; height: number },
 	x: number,
@@ -181,7 +186,7 @@ export function panelPlacementRule(
 	// Nothing to escape, for the regex or the Lua string it sits in.
 	if (!/^[\w ]+$/.test(title)) return null;
 	return (
-		`hl.window_rule({ name = "${PANEL_RULE}", match = { title = "^(${title})$" }, ` +
+		`hl.window_rule({ name = "${ruleName}", match = { title = "^(${title})$" }, ` +
 		`float = true, size = "${Math.round(size.width)} ${Math.round(size.height)}", ` +
 		`move = "${Math.round(x)} ${Math.round(y)}" })`
 	);
@@ -217,7 +222,8 @@ export async function presetHudPanelPlacement(options: {
 		monitorWorkArea(monitor),
 		options.gap,
 	);
-	const rule = panelPlacementRule(
+	const rule = windowPlacementRule(
+		PANEL_RULE,
 		options.panelTitle,
 		options.panelSize,
 		x - monitor.x,
@@ -227,6 +233,46 @@ export async function presetHudPanelPlacement(options: {
 	return (await request(socketPath, `eval ${rule}`))?.trim() === "ok";
 }
 
+/**
+ * Before the bar is shown, and again whenever its size changes: a window rule that maps it at the
+ * bottom centre, so it never appears where Hyprland would centre it — at launch, or shown again
+ * after being hidden. On the bar's monitor once it has one, else the focused monitor, where a
+ * new window opens. Resolves false when not under Hyprland or on a Hyprland without Lua; the bar
+ * is then moved after it maps instead.
+ */
+export async function presetHudBarPlacement(options: {
+	env: Env;
+	pid: number;
+	barTitle: string;
+	panelTitle: string;
+	barSize: { width: number; height: number };
+	margin: number;
+}): Promise<boolean> {
+	const socketPath = hyprlandSocketPath(options.env);
+	if (!socketPath) return false;
+	const [clients, monitors] = await Promise.all([
+		requestJson<HyprlandClient[]>(socketPath, "clients"),
+		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+	]);
+	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+	const bar = findBar(clients, options);
+	const monitor =
+		(bar && monitors.find((candidate) => candidate.id === bar.monitor)) ??
+		monitors.find((candidate) => candidate.focused);
+	if (!monitor) return false;
+
+	const { x, y } = barPositionAtBottom(options.barSize, monitorWorkArea(monitor), options.margin);
+	const rule = windowPlacementRule(
+		BAR_RULE,
+		options.barTitle,
+		options.barSize,
+		x - monitor.x,
+		y - monitor.y,
+	);
+	if (!rule) return false;
+	return (await request(socketPath, `eval ${rule}`))?.trim() === "ok";
+}
+
 /**
  * Moves the panel window next to the bar. Both are found among this process's clients: the
  * panel by its title, the bar by the size this process gave it. Resolves false when not under
diff --git a/electron/windows.ts b/electron/windows.ts
index 7417d524d9..1804aa90d7 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -29,6 +29,7 @@ import {
 import {
 	placeHudBarAtBottom,
 	placeHudPanelNearBar,
+	presetHudBarPlacement,
 	presetHudPanelPlacement,
 	runsUnderHyprland,
 } from "./hyprland";
@@ -181,6 +182,10 @@ let hudOverlayWindow: BrowserWindow | null = null;
 // (#1004). setPosition() is no way out: Electron implements it as setBounds() with the
 // size from getBounds().
 let hudWindowSize = { width: 0, height: 0 };
+/** Whether the HUD's renderer has reported the bar's size yet, and who is waiting for it; see
+ *  the HUD's ready-to-show. */
+let hudBarSizeKnown = false;
+let hudSizeReported: (() => void) | null = null;
 
 /** The HUD's position, with its own size instead of the drifting read-back. */
 function hudBounds(win: BrowserWindow): Electron.Rectangle {
@@ -456,12 +461,17 @@ ipcMain.on("hud-overlay-set-size", (_event, width: number, height: number, conte
 		hudContentRect = nextContent;
 	}
 	hudWindowSize = { width: next.width, height: next.height };
+	hudBarSizeKnown = true;
+	hudSizeReported?.();
+	hudSizeReported = null;
 
 	if (!sameRect(next, bounds)) {
 		hudOverlayWindow.setBounds(next, false);
 		// Hyprland keeps the top-left of a resized window, which lifts the bar off the
-		// bottom; the bounds asked for above are ignored there.
+		// bottom; the bounds asked for above are ignored there. The rule follows the new
+		// size too, for the next time the bar is shown.
 		placeHudBar();
+		void presetHudBar();
 	}
 	reassertAlwaysOnTop(hudOverlayWindow);
 });
@@ -478,6 +488,14 @@ ipcMain.on("hud-overlay-content", (_event, content: unknown) => {
 
 /** Gap between the HUD window and the bottom of the work area. */
 const HUD_BOTTOM_MARGIN = 5;
+/**
+ * On Hyprland, fixed, so a window rule can place the bar before it maps (presetHudBar). Only
+ * there: elsewhere the window keeps the page's title, as it always has.
+ */
+const HUD_BAR_TITLE = "OpenScreen recording bar";
+const HUD_BAR_TITLE_FIXED = runsUnderHyprland(process.env);
+/** How long the first show waits on Hyprland for the bar to report its size. */
+const HUD_FIRST_SIZE_TIMEOUT_MS = 1500;
 
 /**
  * Frameless transparent HUD overlay, always-on-top, centred at the bottom of the
@@ -522,6 +540,7 @@ export function createHudOverlayWindow(): BrowserWindow {
 		skipTaskbar: true,
 		hasShadow: false,
 		show: false, // shown via ready-to-show to avoid black rectangle flash
+		...(HUD_BAR_TITLE_FIXED ? { title: HUD_BAR_TITLE } : {}),
 		webPreferences: {
 			preload: path.join(__dirname, "preload.mjs"),
 			additionalArguments: HUD_WINDOW_ARGUMENTS,
@@ -550,9 +569,20 @@ export function createHudOverlayWindow(): BrowserWindow {
 
 	// Show only once painted to avoid the black rectangle flash when a transparent
 	// window is shown before its first paint.
+	if (HUD_BAR_TITLE_FIXED) {
+		// The page's <title> would replace it, and the title is what the bar's rule matches.
+		win.on("page-title-updated", (event) => event.preventDefault());
+	}
+	hudBarSizeKnown = false;
 	win.once("ready-to-show", () => {
 		applyContentProtection(win, "HUD", { clickThrough: true });
-		if (!HEADLESS) win.show();
+		if (HEADLESS) return;
+		// Placed before it maps, or Hyprland shows it mid-screen and it is seen moving down.
+		void barSizeKnown()
+			.then(presetHudBar)
+			.finally(() => {
+				if (!win.isDestroyed()) win.show();
+			});
 	});
 
 	win.webContents.on("did-finish-load", () => {
@@ -679,6 +709,38 @@ function placeHudBar(attempt = 0) {
 	}, 40);
 }
 
+/**
+ * Resolves once the bar's size is known, on Hyprland, where the rule that places the bar is set
+ * for it. Painted is not measured: served by the dev server, the page is ready to show before it
+ * has sized the window, which then mapped at its creation size, its top mid-screen, and was seen
+ * shrinking and moving down. The bound starts here, at ready-to-show, not when the window was
+ * created: a page that took longer than it to load used to find it already spent. Bounded, so a
+ * report that never comes delays the bar rather than losing it.
+ */
+function barSizeKnown(): Promise<void> {
+	if (!HUD_BAR_TITLE_FIXED || hudBarSizeKnown) return Promise.resolve();
+	return new Promise<void>((resolve) => {
+		hudSizeReported = resolve;
+		setTimeout(resolve, HUD_FIRST_SIZE_TIMEOUT_MS);
+	});
+}
+
+/**
+ * On Hyprland, (re)sets the rule that maps the bar at the bottom centre at its current size, so
+ * it opens there rather than mid-screen. Resolves at once elsewhere.
+ */
+function presetHudBar(): Promise<boolean> {
+	if (!HUD_BAR_TITLE_FIXED) return Promise.resolve(false);
+	return presetHudBarPlacement({
+		env: process.env,
+		pid: process.pid,
+		barTitle: HUD_BAR_TITLE,
+		panelTitle: HUD_PANEL_TITLE,
+		barSize: hudWindowSize,
+		margin: HUD_BOTTOM_MARGIN,
+	});
+}
+
 function hudPanelHasPopover(state: HudPanelState | null): boolean {
 	return Boolean(state && (state.deviceSettings || state.languageMenu));
 }

From ab7db4fb7eec4a0149d32a61dbed346f22a873ed Mon Sep 17 00:00:00 2001
From: Shilai Li <2649730335git@gmail.com>
Date: Thu, 29 Oct 2026 02:51:31 -0700
Subject: [PATCH 27/27] fix(linux): address CodeRabbit's review of the Hyprland
 HUD changes

- Run bar and panel placements one at a time. Each decides whether to pin
  from its own `clients` snapshot and pinning toggles, so two overlapping
  placements could both toggle and leave the window unpinned, under a
  fullscreen window again. A test with a slow, stateful fake socket fails
  without the serialization.
- Do not reveal the panel when the bar was hidden while the panel waited
  for its placement; the bar's show handler brings it back.
- Report no panel size before there is content to show: the root is then
  only its padding, and main showed that as a small empty square.
- Document that a persisted Hyprland grant outlives its take: the portal
  keeps it until the user revokes it, and nothing in the app can.
---
 electron/hyprland.test.ts                     |  46 ++++++++
 electron/hyprland.ts                          | 103 +++++++++++-------
 .../native/pipewire-capture/src/portal.rs     |   8 ++
 electron/windows.ts                           |   5 +-
 src/components/launch/HudPanelWindow.tsx      |   8 +-
 5 files changed, 126 insertions(+), 44 deletions(-)

diff --git a/electron/hyprland.test.ts b/electron/hyprland.test.ts
index 0202574df3..d40db89b17 100644
--- a/electron/hyprland.test.ts
+++ b/electron/hyprland.test.ts
@@ -397,6 +397,52 @@ describe("placeHudPanelNearBar", () => {
 		expect(preset).toBe(true);
 	});
 
+	// Pinning toggles. Two placements that overlap used to both read `pinned: false` and both
+	// toggle, leaving the bar unpinned and under a fullscreen window again.
+	it("pins once when two placements overlap", async () => {
+		const { env, received } = await fakeHyprland({});
+		let pinned = false;
+		server?.removeAllListeners("connection");
+		server?.on("connection", (socket) => {
+			socket.on("data", (chunk) => {
+				const command = chunk.toString("utf8");
+				received.push(command);
+				if (command === "j/clients") {
+					socket.end(
+						JSON.stringify(
+							(JSON.parse(clients) as Record<string, unknown>[]).map((client) =>
+								client.address === "0xbar" ? { ...client, pinned } : client,
+							),
+						),
+					);
+				} else if (command === "j/monitors") {
+					socket.end(monitors);
+				} else if (command.includes("pin")) {
+					// Slow, and the state changes only as the reply goes out.
+					setTimeout(() => {
+						pinned = !pinned;
+						socket.end("ok");
+					}, 50);
+				} else {
+					socket.end("ok");
+				}
+			});
+		});
+		const place = () =>
+			placeHudBarAtBottom({
+				env,
+				pid: 42,
+				panelTitle: "OpenScreen panel",
+				barSize: { width: 576, height: 150 },
+				margin: 5,
+			});
+
+		await Promise.all([place(), place()]);
+
+		expect(pinned).toBe(true);
+		expect(received.filter((command) => command.includes("pin"))).toHaveLength(1);
+	});
+
 	it("gives up quietly outside Hyprland", async () => {
 		await expect(
 			placeHudPanelNearBar({
diff --git a/electron/hyprland.ts b/electron/hyprland.ts
index 9102c49288..f191f9773d 100644
--- a/electron/hyprland.ts
+++ b/electron/hyprland.ts
@@ -278,37 +278,39 @@ export async function presetHudBarPlacement(options: {
  * panel by its title, the bar by the size this process gave it. Resolves false when not under
  * Hyprland or when anything does not match, in which case nothing was moved.
  */
-export async function placeHudPanelNearBar(options: {
+export function placeHudPanelNearBar(options: {
 	env: Env;
 	pid: number;
 	panelTitle: string;
 	barSize: { width: number; height: number };
 	gap: number;
 }): Promise<boolean> {
-	const socketPath = hyprlandSocketPath(options.env);
-	if (!socketPath) return false;
-	const [clients, monitors] = await Promise.all([
-		requestJson<HyprlandClient[]>(socketPath, "clients"),
-		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
-	]);
-	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+	return oneAtATime(async () => {
+		const socketPath = hyprlandSocketPath(options.env);
+		if (!socketPath) return false;
+		const [clients, monitors] = await Promise.all([
+			requestJson<HyprlandClient[]>(socketPath, "clients"),
+			requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+		]);
+		if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
 
-	const panel = clients.find(
-		(client) => client.pid === options.pid && client.title === options.panelTitle,
-	);
-	const bar = findBar(clients, options);
-	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
-	if (!panel || !bar || !monitor) return false;
+		const panel = clients.find(
+			(client) => client.pid === options.pid && client.title === options.panelTitle,
+		);
+		const bar = findBar(clients, options);
+		const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
+		if (!panel || !bar || !monitor) return false;
 
-	const { x, y } = panelPositionNearBar(
-		toRect(bar),
-		{ width: panel.size[0], height: panel.size[1] },
-		monitorWorkArea(monitor),
-		options.gap,
-	);
-	await pinClient(socketPath, panel);
-	if (x === panel.at[0] && y === panel.at[1]) return true;
-	return moveClient(socketPath, panel.address, x, y);
+		const { x, y } = panelPositionNearBar(
+			toRect(bar),
+			{ width: panel.size[0], height: panel.size[1] },
+			monitorWorkArea(monitor),
+			options.gap,
+		);
+		await pinClient(socketPath, panel);
+		if (x === panel.at[0] && y === panel.at[1]) return true;
+		return moveClient(socketPath, panel.address, x, y);
+	});
 }
 
 /**
@@ -316,39 +318,56 @@ export async function placeHudPanelNearBar(options: {
  * process's clients by the size this process gave it, skipping the panel. Resolves false
  * when not under Hyprland or when anything does not match, in which case nothing was moved.
  */
-export async function placeHudBarAtBottom(options: {
+export function placeHudBarAtBottom(options: {
 	env: Env;
 	pid: number;
 	panelTitle: string;
 	barSize: { width: number; height: number };
 	margin: number;
 }): Promise<boolean> {
-	const socketPath = hyprlandSocketPath(options.env);
-	if (!socketPath) return false;
-	const [clients, monitors] = await Promise.all([
-		requestJson<HyprlandClient[]>(socketPath, "clients"),
-		requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
-	]);
-	if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
+	return oneAtATime(async () => {
+		const socketPath = hyprlandSocketPath(options.env);
+		if (!socketPath) return false;
+		const [clients, monitors] = await Promise.all([
+			requestJson<HyprlandClient[]>(socketPath, "clients"),
+			requestJson<HyprlandMonitor[]>(socketPath, "monitors"),
+		]);
+		if (!Array.isArray(clients) || !Array.isArray(monitors)) return false;
 
-	const bar = findBar(clients, options);
-	const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
-	if (!bar || !monitor) return false;
+		const bar = findBar(clients, options);
+		const monitor = bar && monitors.find((candidate) => candidate.id === bar.monitor);
+		if (!bar || !monitor) return false;
 
-	const { x, y } = barPositionAtBottom(
-		{ width: bar.size[0], height: bar.size[1] },
-		monitorWorkArea(monitor),
-		options.margin,
-	);
-	await pinClient(socketPath, bar);
-	if (x === bar.at[0] && y === bar.at[1]) return true;
-	return moveClient(socketPath, bar.address, x, y);
+		const { x, y } = barPositionAtBottom(
+			{ width: bar.size[0], height: bar.size[1] },
+			monitorWorkArea(monitor),
+			options.margin,
+		);
+		await pinClient(socketPath, bar);
+		if (x === bar.at[0] && y === bar.at[1]) return true;
+		return moveClient(socketPath, bar.address, x, y);
+	});
 }
 
 /**
  * Pins a window: shown on every workspace and above a fullscreen or maximized one. Both
  * dispatchers toggle, so an already pinned window is left alone.
  */
+/** The placement in flight, which the next one waits for; see `oneAtATime`. */
+let placementInFlight: Promise<unknown> = Promise.resolve();
+
+/**
+ * Runs placements one at a time. Each decides whether to pin from the `pinned` of its own
+ * `clients` snapshot, and pinning toggles: two overlapping placements could both read
+ * `pinned: false` and both toggle, leaving the window unpinned — under a fullscreen window
+ * again — until the next one. A failed placement does not hold up the ones after it.
+ */
+function oneAtATime<T>(run: () => Promise<T>): Promise<T> {
+	const result = placementInFlight.then(run, run);
+	placementInFlight = result.catch(() => undefined);
+	return result;
+}
+
 async function pinClient(socketPath: string, client: HyprlandClient): Promise<void> {
 	if (client.pinned) return;
 	const target = `address:${client.address}`;
diff --git a/electron/native/pipewire-capture/src/portal.rs b/electron/native/pipewire-capture/src/portal.rs
index 0e70e6eb4e..f475e8865a 100644
--- a/electron/native/pipewire-capture/src/portal.rs
+++ b/electron/native/pipewire-capture/src/portal.rs
@@ -314,6 +314,14 @@ pub async fn negotiate(
             // and asks for it only where that stall was seen (Hyprland). Every
             // other desktop keeps the non-persisted grant it always had: no
             // token, no permission-store entry, and Restart raises the picker.
+            //
+            // THE GRANT ITSELF OUTLIVES THE TAKE, which is the cost. The portal
+            // keeps a persisted grant until the user revokes it, and nothing
+            // here revokes one: stop, discard and Restart all leave it, so each
+            // Hyprland take can leave a screen-share grant behind. The app never
+            // replays it on its own — only the token kept in memory for one
+            // Restart does — but it stays in the portal's store until cleared
+            // there. ScreenCast has no call that revokes a grant.
             restore_token,
             if persist_grant {
                 PersistMode::ExplicitlyRevoked
diff --git a/electron/windows.ts b/electron/windows.ts
index 1804aa90d7..cc9ae7cc52 100644
--- a/electron/windows.ts
+++ b/electron/windows.ts
@@ -871,9 +871,12 @@ function revealHudPanel(win: BrowserWindow, size?: { width: number; height: numb
 		barSize: hudWindowSize,
 		gap: HUD_PANEL_GAP,
 	}).finally(() => {
-		// The state can have moved on while Hyprland answered.
+		// The state can have moved on while Hyprland answered, and the bar can have been
+		// hidden; its show handler reveals the panel again when it returns.
 		const state = hudPanelState;
 		if (win.isDestroyed() || win.isVisible() || !state || !hudPanelHasContent(state)) return;
+		const bar = hudOverlayWindow;
+		if (!bar || bar.isDestroyed() || !bar.isVisible()) return;
 		if (hudPanelHasPopover(state)) {
 			win.show();
 		} else {
diff --git a/src/components/launch/HudPanelWindow.tsx b/src/components/launch/HudPanelWindow.tsx
index 26ec1851a4..5676f16596 100644
--- a/src/components/launch/HudPanelWindow.tsx
+++ b/src/components/launch/HudPanelWindow.tsx
@@ -10,6 +10,7 @@ import {
 	type HudPanelAction,
 	type HudPanelState,
 	type HudPanelToast,
+	hudPanelHasContent,
 } from "./hudPanel";
 import styles from "./LaunchWindow.module.css";
 
@@ -107,10 +108,15 @@ export function HudPanelWindow() {
 		return () => window.removeEventListener("keydown", onKeyDown);
 	}, []);
 
+	// Nothing to size before there is something to show: the root is then only its padding,
+	// and main would show that as a small, empty square until the snapshot arrived.
+	const hasContentRef = useRef(false);
+	hasContentRef.current = hudPanelHasContent(state);
+
 	// The window is sized to the stack, so it is never bigger than what it shows.
 	const reportSize = useCallback(() => {
 		const root = rootRef.current;
-		if (!root) return;
+		if (!root || !hasContentRef.current) return;
 		const { width, height } = root.getBoundingClientRect();
 		if (width > 0 && height > 0) {
 			window.electronAPI?.setHudPanelSize?.(Math.ceil(width), Math.ceil(height));