@desklink/host 0.3.0 → 0.3.1

package/engine/src/session.rs

@@ -202,12 +202,14 @@ struct Selected {
 
 /// Open an X display, start reading its root window, and hand back the same
 /// shape the portal path produces.
+#[allow(clippy::too_many_arguments)]
 fn select_x11(
     display: Option<&str>,
     max_width: usize,
     max_height: usize,
     max_fps: u32,
     metrics: Arc<Mutex<Metrics>>,
+    #[cfg(target_os = "linux")] cursor_sink: Option<crate::cursor::CursorSink>,
     sink: capture::FrameSink,
     on_stop: Box<dyn Fn(String) + Send>,
 ) -> Result<Selected> {
@@ -238,15 +240,23 @@ fn select_x11(
                 let interval = frame_interval(max_fps);
                 let mut sequence = 0u64;
                 let mut last_sent: Option<Instant> = None;
-                // Without XDamage there is no change signal, so an unchanged
-                // screen is recognised by its pixels exactly as before.
+                // XDamage wakes the loop, but pixels decide whether the root
+                // image actually changed; without XDamage, polling does so.
                 let hashed = !lock(&desktop).damage_armed();
                 let mut last_hash = None;
                 // The first frame is always grabbed; afterwards Damage wakes
                 // the loop, so a still screen costs no grab, no conversion
                 // and no hash. The fps cap stays a minimum spacing.
                 let mut first = true;
+                #[cfg(target_os = "linux")]
+                let mut cursor = cursor_sink.map(crate::cursor::Reporter::new);
                 while !stop.load(Ordering::SeqCst) {
+                    #[cfg(target_os = "linux")]
+                    if let Some(cursor) = cursor.as_mut() {
+                        if let Ok((x, y, visible)) = lock(&desktop).cursor_position() {
+                            cursor.update(x, y, visible);
+                        }
+                    }
                     if !first {
                         let changed = lock(&desktop).take_damage();
                         if !changed {
@@ -269,7 +279,7 @@ fn select_x11(
                     let grab_micros = grabbed.elapsed().as_micros() as u64;
                     match frame {
                         Ok((frame, raw)) => {
-                            let changed = if hashed {
+                            let changed = {
                                 use std::hash::{Hash, Hasher};
                                 let mut hasher = std::collections::hash_map::DefaultHasher::new();
                                 raw.hash(&mut hasher);
@@ -280,8 +290,6 @@ fn select_x11(
                                     last_hash = Some(hash);
                                     true
                                 }
-                            } else {
-                                true
                             };
                             if changed {
                                 // Handing an unchanged frame on would keep the
@@ -480,10 +488,10 @@ impl InputTarget {
         Ok(())
     }
 
-    #[cfg(target_os = "macos")]
+    #[cfg(any(target_os = "macos", target_os = "windows"))]
     fn unicode_text(&mut self, text: &str) -> Result<()> {
         match &mut self.applier {
-            #[cfg(target_os = "macos")]
+            #[cfg(any(target_os = "macos", target_os = "windows"))]
             Applier::Uinput(devices) => devices.unicode_text(text),
             #[cfg(target_os = "linux")]
             Applier::Uinput(_) => anyhow::bail!("Unicode text input is unavailable on Linux"),
@@ -582,6 +590,7 @@ impl SessionError {
 }
 
 pub struct OpenRequest {
+    pub cursor: crate::protocol::CursorMode,
     /** Which desktop to capture; absent means the portal. */
     pub source: Option<SourceRequest>,
     pub permissions: Vec<Permission>,
@@ -603,6 +612,9 @@ pub struct OpenRequest {
 /// Events a session raises for its consumer.
 #[derive(Debug)]
 pub enum SessionEvent {
+    Cursor {
+        position: crate::protocol::CursorPosition,
+    },
     Description {
         generation: u64,
         sdp: String,
@@ -619,6 +631,7 @@ pub enum SessionEvent {
         first_frame: bool,
     },
     Frame {
+        timestamp_us: u64,
         seq: u64,
         damage: Vec<[usize; 4]>,
     },
@@ -661,6 +674,13 @@ type FrameSnapshot = (u64, Instant, usize, usize, Vec<u8>, Vec<u64>, Vec<u64>);
 
 /// Everything a session's background tasks need, shared rather than borrowed so
 /// the consumer can own the `Session` handle while the pipeline runs.
+#[cfg(target_os = "linux")]
+enum PointDesktop {
+    X11(String),
+    Wayland,
+    Unavailable(&'static str),
+}
+
 struct Inner {
     id: String,
     generation: u64,
@@ -679,6 +699,9 @@ struct Inner {
     encoder: Mutex<Option<VideoEncoder>>,
     input: Mutex<Option<InputTarget>>,
     indicator: Mutex<Option<crate::indicator::Indicator>>,
+    point_overlay: Mutex<Option<crate::indicator::Indicator>>,
+    #[cfg(target_os = "linux")]
+    point_desktop: PointDesktop,
     capture: Mutex<Option<FrameSource>>,
     /// Absent for an encoded source: there is no local keyboard to translate a
     /// character through, because the client's keys are forwarded instead.
@@ -694,6 +717,7 @@ struct Inner {
     encoded: Mutex<Option<Encoded>>,
     /// `OpenRequest::local_frames`: whether `latest` is kept at all.
     local_frames: bool,
+    cursor_info: serde_json::Value,
 }
 
 /// A source whose video arrives already encoded.
@@ -772,6 +796,8 @@ pub fn capabilities() -> serde_json::Value {
             "backends": ["portal-screencast+pipewire", "x11-root"],
             "formats": ["bgrx", "bgra", "rgbx", "rgba"],
             "cursor": "embedded",
+            "cursor_modes": ["embedded", "hidden"],
+            "cursor_positions": {"x11": true, "portal": "negotiated"},
             "audio": false,
         },
         "encode": encode_capabilities(),
@@ -824,6 +850,7 @@ pub fn capabilities() -> serde_json::Value {
             "backends": ["screencapturekit"],
             "formats": ["bgra"],
             "cursor": "embedded",
+            "cursor_modes": ["embedded"],
             "audio": false,
             "displays": crate::mac::displays(),
             "grant": if capture_granted { "granted" } else { "missing-screen-recording" },
@@ -849,6 +876,16 @@ pub fn capabilities() -> serde_json::Value {
     })
 }
 
+#[cfg(target_os = "windows")]
+pub fn capabilities() -> serde_json::Value {
+    crate::win::capabilities()
+}
+
+#[cfg(target_os = "windows")]
+fn wayland_clipboard_available() -> bool {
+    false
+}
+
 /// `capabilities.encode`: VP9 always, H.264 when an encoder for it starts
 /// here now. `hardware` describes VP9, the default.
 fn encode_capabilities() -> serde_json::Value {
@@ -878,6 +915,26 @@ impl Session {
                 "session.open requires the view permission",
             ));
         }
+        #[cfg(target_os = "windows")]
+        if request.agent_indicator {
+            return Err(SessionError::new(
+                "indicator-unavailable",
+                "Windows agent indicator is not implemented in this build.",
+            ));
+        }
+        if request.cursor == crate::protocol::CursorMode::Hidden {
+            #[cfg(not(target_os = "linux"))]
+            return Err(SessionError::new(
+                "cursor-unavailable",
+                "hidden cursor capture is not implemented on this platform",
+            ));
+            if matches!(request.source, Some(SourceRequest::Encoded { .. })) {
+                return Err(SessionError::new(
+                    "cursor-unavailable",
+                    "the engine cannot remove cursor pixels from consumer-encoded video",
+                ));
+            }
+        }
         let id = opaque_id();
         let wants_control = request.permissions.contains(&Permission::Control);
         let wants_x11 = matches!(request.source, Some(SourceRequest::X11 { .. }));
@@ -975,7 +1032,7 @@ impl Session {
                     let damage = dirty_regions(&hashes, &previous, frame.width, frame.height);
                     *held = Some((
                         seq,
-                        Instant::now(),
+                        captured_at,
                         frame.width,
                         frame.height,
                         raw,
@@ -985,7 +1042,11 @@ impl Session {
                     frame_tx_signal.send_replace(seq);
                     let _ = frame_events.send(Notice {
                         session_id: frame_session_id.clone(),
-                        event: SessionEvent::Frame { seq, damage },
+                        event: SessionEvent::Frame {
+                            seq,
+                            damage,
+                            timestamp_us: crate::protocol::timestamp_us(captured_at),
+                        },
                     });
                 }
             }
@@ -1002,6 +1063,21 @@ impl Session {
             }
         });
 
+        #[cfg(target_os = "linux")]
+        let cursor_sink: Option<crate::cursor::CursorSink> =
+            if request.cursor == crate::protocol::CursorMode::Hidden {
+                let events = events.clone();
+                let id = id.clone();
+                Some(Box::new(move |position| {
+                    let _ = events.send(Notice {
+                        session_id: id.clone(),
+                        event: SessionEvent::Cursor { position },
+                    });
+                }))
+            } else {
+                None
+            };
+        let mut cursor_info = serde_json::json!({"mode":"embedded", "positions":false});
         let Selected {
             source,
             capture,
@@ -1013,6 +1089,8 @@ impl Session {
                 request.max_height,
                 max_fps,
                 metrics.clone(),
+                #[cfg(target_os = "linux")]
+                cursor_sink,
                 sink,
                 Box::new({
                     let status = capture_status.clone();
@@ -1025,9 +1103,30 @@ impl Session {
                     Some(SourceRequest::Display { display_id }) => {
                         portal::open_display(*display_id).await
                     }
-                    _ => portal::open(request.restore_token.as_deref()).await,
+                    _ => {
+                        #[cfg(target_os = "linux")]
+                        {
+                            portal::open(request.restore_token.as_deref(), request.cursor).await
+                        }
+                        #[cfg(not(target_os = "linux"))]
+                        {
+                            portal::open(request.restore_token.as_deref()).await
+                        }
+                    }
+                }
+                .map_err(|error| {
+                    let message = format!("{error:#}");
+                    let code = if message.contains("cursor_positions_unavailable:") {
+                        "cursor_positions_unavailable"
+                    } else {
+                        "source"
+                    };
+                    SessionError::new(code, message)
+                })?;
+                #[cfg(target_os = "linux")]
+                {
+                    cursor_info = serde_json::json!({"mode":portal.cursor_mode, "positions":false});
                 }
-                .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
                 if let Some(token) = &portal.restore_token {
                     let _ = events.send(Notice {
                         session_id: id.clone(),
@@ -1072,12 +1171,26 @@ impl Session {
                     }),
                 )
                 .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
+                #[cfg(target_os = "windows")]
+                let capture = capture::start(
+                    portal,
+                    width,
+                    height,
+                    max_fps,
+                    sink,
+                    Box::new({
+                        let status = capture_status.clone();
+                        move |running, reason| status(running, reason)
+                    }),
+                )
+                .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
                 #[cfg(target_os = "linux")]
                 let capture = capture::start(
                     portal,
                     width,
                     height,
                     max_fps,
+                    cursor_sink,
                     sink,
                     indicator
                         .as_ref()
@@ -1089,6 +1202,18 @@ impl Session {
                 )
                 .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
                 #[cfg(target_os = "linux")]
+                {
+                    if request.cursor == crate::protocol::CursorMode::Hidden
+                        && !capture.cursor_positions()
+                    {
+                        return Err(SessionError::new(
+                            "cursor_positions_unavailable",
+                            "portal stream did not provide SPA cursor metadata",
+                        ));
+                    }
+                    cursor_info["positions"] = serde_json::json!(capture.cursor_positions());
+                }
+                #[cfg(target_os = "linux")]
                 if let Some(indicator) = indicator.as_mut() {
                     indicator.event('A', -1, -1);
                 }
@@ -1099,6 +1224,9 @@ impl Session {
                 }
             }
         };
+        if wants_x11 {
+            cursor_info = serde_json::json!({"mode":"hidden", "positions": request.cursor == crate::protocol::CursorMode::Hidden});
+        }
 
         let source_w = source.width.max(1) as usize;
         let source_h = source.height.max(1) as usize;
@@ -1150,7 +1278,7 @@ impl Session {
                     applier: Applier::Uinput({
                         #[cfg(target_os = "linux")]
                         let devices = InputDevices::create(source_w as i32, source_h as i32);
-                        #[cfg(target_os = "macos")]
+                        #[cfg(any(target_os = "macos", target_os = "windows"))]
                         let devices = InputDevices::create_for_display(
                             source_w as i32,
                             source_h as i32,
@@ -1221,6 +1349,20 @@ impl Session {
             encoder: Mutex::new(Some(VideoEncoder::Vp9(encoder))),
             input: Mutex::new(input),
             indicator: Mutex::new(indicator),
+            point_overlay: Mutex::new(None),
+            #[cfg(target_os = "linux")]
+            point_desktop: if wants_x11 {
+                match &request.source {
+                    Some(SourceRequest::X11 { display }) => display
+                        .clone()
+                        .or_else(|| std::env::var("DISPLAY").ok())
+                        .map(PointDesktop::X11)
+                        .unwrap_or(PointDesktop::Unavailable("x11-unavailable")),
+                    _ => PointDesktop::Unavailable("x11-unavailable"),
+                }
+            } else {
+                PointDesktop::Wayland
+            },
             capture: Mutex::new(Some(capture)),
             layout: Mutex::new(Some(layout)),
             last_seq: Mutex::new(0),
@@ -1230,6 +1372,7 @@ impl Session {
             events: events.clone(),
             encoded: Mutex::new(None),
             local_frames: request.local_frames,
+            cursor_info,
         });
 
         inner.notify(SessionEvent::Description {
@@ -1308,6 +1451,9 @@ impl Session {
             encoder: Mutex::new(None),
             input: Mutex::new(None),
             indicator: Mutex::new(None),
+            point_overlay: Mutex::new(None),
+            #[cfg(target_os = "linux")]
+            point_desktop: PointDesktop::Unavailable("layer_shell_unavailable"),
             capture: Mutex::new(None),
             layout: Mutex::new(None),
             last_seq: Mutex::new(0),
@@ -1328,6 +1474,7 @@ impl Session {
                 feed,
             })),
             local_frames: false,
+            cursor_info: serde_json::json!({"mode":"unavailable", "positions":false}),
         });
         inner.notify(SessionEvent::State {
             capture: "consented",
@@ -1385,6 +1532,10 @@ impl Session {
         self.inner.generation
     }
 
+    pub fn cursor_info(&self) -> &serde_json::Value {
+        &self.inner.cursor_info
+    }
+
     pub fn geometry(&self) -> &serde_json::Value {
         &self.inner.geometry
     }
@@ -1393,6 +1544,128 @@ impl Session {
         &self.inner.source
     }
 
+    pub fn point(
+        &self,
+        params: &crate::protocol::PointParams,
+    ) -> std::result::Result<(), SessionError> {
+        // Lock through validation and drawing, so a concurrent close cannot leave
+        // a newly spawned marker alive after teardown.
+        let mut overlay = lock(&self.inner.point_overlay);
+        if self.inner.closed.load(Ordering::SeqCst) {
+            return Err(SessionError::new("session", "the session is closed"));
+        }
+        if !self.inner.permissions.contains(&Permission::View) {
+            return Err(SessionError::new(
+                "permission",
+                "point requires view permission",
+            ));
+        }
+        if lock(&self.inner.encoded).is_some() {
+            return Err(SessionError::new(
+                "operation",
+                "an encoded source has no host desktop",
+            ));
+        }
+        #[cfg(target_os = "linux")]
+        if let PointDesktop::Unavailable(reason) = &self.inner.point_desktop {
+            return Err(SessionError::new(
+                "point_unsupported",
+                format!("reason: {reason}; point overlay is unavailable"),
+            ));
+        }
+        if params.clear {
+            if params.x.is_some()
+                || params.y.is_some()
+                || params.timeout_ms.is_some()
+                || !params.label.is_empty()
+            {
+                return Err(SessionError::new(
+                    "malformed",
+                    "clear accepts no coordinates, label or timeout",
+                ));
+            }
+            #[cfg(target_os = "linux")]
+            if overlay.is_none() && matches!(self.inner.point_desktop, PointDesktop::Wayland) {
+                let available = crate::indicator::Indicator::wayland_layer_shell_available()
+                    .map_err(|error| {
+                        SessionError::new("indicator-unavailable", format!("{error:#}"))
+                    })?;
+                if !available {
+                    return Err(SessionError::new(
+                        "point_unsupported",
+                        "reason: layer_shell_unavailable; compositor has no layer-shell",
+                    ));
+                }
+            }
+            if let Some(helper) = overlay.take() {
+                helper.stop();
+            }
+            return Ok(());
+        }
+        let (x, y) = params
+            .x
+            .zip(params.y)
+            .ok_or_else(|| SessionError::new("malformed", "point requires x and y"))?;
+        let source = &self.inner.source;
+        if x < 0 || y < 0 || x >= i64::from(source.width) || y >= i64::from(source.height) {
+            return Err(SessionError::new(
+                "coordinates",
+                "point is outside the selected desktop",
+            ));
+        }
+        let timeout = params.timeout_ms.unwrap_or(3000);
+        if !(1..=120_000).contains(&timeout)
+            || params.label.len() > 96
+            || !params.label.bytes().all(|b| (32..=126).contains(&b))
+        {
+            return Err(SessionError::new(
+                "malformed",
+                "timeout must be 1..120000 ms; label must be at most 96 printable ASCII bytes",
+            ));
+        }
+        #[cfg(not(target_os = "windows"))]
+        if overlay.is_none() {
+            #[cfg(target_os = "linux")]
+            let helper = match &self.inner.point_desktop {
+                PointDesktop::X11(display) => crate::indicator::Indicator::start_point(display),
+                PointDesktop::Wayland => crate::indicator::Indicator::start_point_wayland(
+                    source.width,
+                    source.height,
+                    source.position,
+                ),
+                PointDesktop::Unavailable(_) => unreachable!("validated point target"),
+            };
+            #[cfg(target_os = "macos")]
+            let helper = crate::indicator::Indicator::start_point(
+                source.node_id,
+                source.width as usize,
+                source.height as usize,
+            );
+            *overlay = Some(helper.map_err(|error| {
+                let message = format!("{error:#}");
+                if message.contains("layer_shell_unavailable") {
+                    SessionError::new(
+                        "point_unsupported",
+                        "reason: layer_shell_unavailable; compositor has no layer-shell",
+                    )
+                } else {
+                    SessionError::new("indicator-unavailable", message)
+                }
+            })?);
+        }
+        #[cfg(not(target_os = "windows"))]
+        return overlay
+            .as_mut()
+            .unwrap()
+            .point(x, y, timeout, &params.label)
+            .map_err(|error| SessionError::new("indicator-unavailable", format!("{error:#}")));
+        #[cfg(target_os = "windows")]
+        return Err(SessionError::new(
+            "point_unsupported",
+            "Windows point overlays are unavailable in this build.",
+        ));
+    }
+
     pub async fn wait_frame(
         &self,
         after_seq: Option<u64>,
@@ -1507,7 +1780,7 @@ impl Session {
             }
             Some(pixels)
         };
-        let result = serde_json::json!({ "seq": seq, "still_ms": at.elapsed().as_millis() as u64,
+        let result = serde_json::json!({ "seq": seq, "timestamp_us": crate::protocol::timestamp_us(*at), "still_ms": at.elapsed().as_millis() as u64,
             "width": w, "height": h, "format": "bgrx", "damage": damage, "written": !path.is_empty() });
         drop(held);
         if let Some(pixels) = pixels {
@@ -1630,6 +1903,9 @@ impl Inner {
         if let Ok(mut indicator) = self.indicator.lock() {
             indicator.take();
         }
+        if let Some(helper) = lock(&self.point_overlay).take() {
+            helper.stop();
+        }
         // Release first, then tear down: a stuck modifier is the one failure the
         // user cannot undo by reconnecting.
         if let Ok(mut input) = self.input.lock() {
@@ -1976,7 +2252,7 @@ impl Inner {
         if text.len() > 4096 {
             return Err(("text-too-large", String::from("text exceeds 4096 bytes")));
         }
-        #[cfg(target_os = "macos")]
+        #[cfg(any(target_os = "macos", target_os = "windows"))]
         {
             let _ = seq;
             return self.with_input(|target| target.unicode_text(text));
@@ -2973,6 +3249,9 @@ mod tests {
             encoder: Mutex::new(None),
             input: Mutex::new(None),
             indicator: Mutex::new(None),
+            point_overlay: Mutex::new(None),
+            #[cfg(target_os = "linux")]
+            point_desktop: PointDesktop::Unavailable("layer_shell_unavailable"),
             capture: Mutex::new(None),
             layout: Mutex::new(None),
             last_seq: Mutex::new(0),
@@ -2991,6 +3270,7 @@ mod tests {
                 feed,
             })),
             local_frames: false,
+            cursor_info: serde_json::json!({"mode":"unavailable", "positions":false}),
         });
         spawn_peer_events(&inner, peer_events_rx);
         spawn_encoded(&inner, feed_rx);
@@ -3112,6 +3392,140 @@ mod tests {
         test_inner_with(events, peer, 64, 64)
     }
 
+    #[cfg(target_os = "linux")]
+    #[tokio::test]
+    async fn a_wayland_portal_session_reports_typed_point_unsupported() {
+        let (events, _) = tokio_mpsc::unbounded_channel();
+        let (mut inner, _) = test_inner(events).await;
+        Arc::get_mut(&mut inner)
+            .expect("test session has one owner")
+            .permissions = vec![Permission::View];
+        let session = Session { inner };
+
+        let error = session
+            .point(&crate::protocol::PointParams {
+                session_id: String::from("test-session"),
+                x: Some(10),
+                y: Some(20),
+                label: String::new(),
+                timeout_ms: None,
+                clear: false,
+            })
+            .expect_err("compositors without layer-shell do not support point overlays");
+
+        assert_eq!(error.code, "point_unsupported");
+        assert!(error.message.contains("reason: layer_shell_unavailable"));
+    }
+
+    // Driven only on the private headless compositor created by point-wayland-flow.py.
+    #[cfg(target_os = "linux")]
+    #[tokio::test]
+    #[ignore = "requires the task-owned compositor and screenshot driver"]
+    async fn point_wayland_private_flow() {
+        let evidence = std::path::PathBuf::from(
+            std::env::var_os("DESKLINK_POINT_TEST_DIR").expect("private evidence"),
+        );
+        let socket =
+            std::path::PathBuf::from(std::env::var_os("WAYLAND_DISPLAY").expect("private socket"));
+        assert!(
+            socket.is_absolute() && socket.starts_with(evidence.join("runtime")),
+            "never use an ambient desktop"
+        );
+        fn checkpoint(dir: &std::path::Path, name: &str) {
+            std::fs::write(dir.join(format!("{name}.ready")), b"").unwrap();
+            let deadline = Instant::now() + Duration::from_secs(15);
+            while !dir.join(format!("{name}.continue")).exists() {
+                assert!(
+                    Instant::now() < deadline,
+                    "screenshot driver timed out at {name}"
+                );
+                std::thread::sleep(Duration::from_millis(20));
+            }
+        }
+        let (events, _) = tokio_mpsc::unbounded_channel();
+        let (mut inner, _) = test_inner(events).await;
+        let state = Arc::get_mut(&mut inner).unwrap();
+        state.permissions = vec![Permission::View];
+        state.point_desktop = PointDesktop::Wayland;
+        state.source.width = 1280;
+        state.source.height = 720;
+        state.source.position = Some((1280, 0));
+        let mut session = Session { inner };
+        let mut params = crate::protocol::PointParams {
+            session_id: String::from("test-session"),
+            x: Some(400),
+            y: Some(300),
+            label: String::from("Here"),
+            timeout_ms: Some(3000),
+            clear: false,
+        };
+        let unsupported_socket = std::env::var_os("DESKLINK_POINT_UNSUPPORTED_SOCKET").unwrap();
+        assert!(std::path::Path::new(&unsupported_socket).starts_with(evidence.join("runtime")));
+        // This test runs alone, in a separate process. Only child helper startup
+        // and the read-only clear probe read this private socket environment.
+        std::env::set_var("WAYLAND_DISPLAY", &unsupported_socket);
+        let refusal = session.point(&params).unwrap_err();
+        assert_eq!(refusal.code, "point_unsupported");
+        assert!(refusal.message.contains("reason: layer_shell_unavailable"));
+        let clear = crate::protocol::PointParams {
+            session_id: params.session_id.clone(),
+            clear: true,
+            x: None,
+            y: None,
+            label: String::new(),
+            timeout_ms: None,
+        };
+        let refusal = session.point(&clear).unwrap_err();
+        assert_eq!(refusal.code, "point_unsupported");
+        std::env::set_var("WAYLAND_DISPLAY", &socket);
+        Arc::get_mut(&mut session.inner).unwrap().source.position = None;
+        let ambiguous = session.point(&params).unwrap_err();
+        assert_eq!(ambiguous.code, "indicator-unavailable");
+        assert!(ambiguous.message.contains("selected_output_unavailable"));
+        Arc::get_mut(&mut session.inner).unwrap().source.position = Some((1280, 0));
+        checkpoint(&evidence, "before");
+        session.point(&params).unwrap();
+        checkpoint(&evidence, "after");
+        params.x = Some(1280);
+        assert_eq!(session.point(&params).unwrap_err().code, "coordinates");
+        params.x = Some(400);
+        params.label = String::from("bad\nlabel");
+        assert_eq!(session.point(&params).unwrap_err().code, "malformed");
+        checkpoint(&evidence, "invalid");
+        tokio::time::sleep(Duration::from_millis(3100)).await;
+        checkpoint(&evidence, "expired");
+        params.x = Some(700);
+        params.y = Some(500);
+        params.label.clear();
+        params.timeout_ms = Some(10000);
+        session.point(&params).unwrap();
+        checkpoint(&evidence, "replaced");
+        params.clear = true;
+        params.x = None;
+        params.y = None;
+        params.timeout_ms = None;
+        session.point(&params).unwrap();
+        session.point(&params).unwrap();
+        assert!(lock(&session.inner.point_overlay).is_none());
+        checkpoint(&evidence, "cleared");
+        params.clear = false;
+        params.x = Some(400);
+        params.y = Some(300);
+        session.point(&params).unwrap();
+        let pid = lock(&session.inner.point_overlay)
+            .as_ref()
+            .unwrap()
+            .test_pid();
+        checkpoint(&evidence, "clickthrough");
+        session.close("test complete").await;
+        assert_eq!(
+            unsafe { libc::kill(pid as i32, 0) },
+            -1,
+            "helper reaped on session close"
+        );
+        checkpoint(&evidence, "closed");
+    }
+
     fn test_inner_with(
         events: tokio_mpsc::UnboundedSender<Notice>,
         peer: VideoPeer,
@@ -3157,6 +3571,9 @@ mod tests {
             })),
             capture: Mutex::new(None),
             indicator: Mutex::new(None),
+            point_overlay: Mutex::new(None),
+            #[cfg(target_os = "linux")]
+            point_desktop: PointDesktop::Unavailable("layer_shell_unavailable"),
             layout: Mutex::new(Some(Layout::from_environment().expect("a keymap"))),
             last_seq: Mutex::new(0),
             control_open: AtomicBool::new(true),
@@ -3165,6 +3582,7 @@ mod tests {
             events,
             encoded: Mutex::new(None),
             local_frames: true,
+            cursor_info: serde_json::json!({"mode":"embedded", "positions":false}),
         });
         (inner, recorded)
     }
@@ -3174,6 +3592,11 @@ mod tests {
         let (events, mut received) = tokio_mpsc::unbounded_channel();
         let (inner, recorded) = test_inner(events).await;
 
+        #[cfg(target_os = "windows")]
+        inner
+            .with_input(|target| target.chord(1, Vec::new(), true))
+            .unwrap();
+        #[cfg(not(target_os = "windows"))]
         inner.apply(ControlMessage::Key {
             name: None,
             character: Some(String::from("a")),
@@ -3227,6 +3650,7 @@ mod tests {
         );
     }
 
+    #[cfg(not(target_os = "windows"))]
     #[tokio::test]
     async fn a_held_modifier_survives_character_named_and_text_chords() {
         use crate::input::keycode;
@@ -3526,6 +3950,7 @@ mod tests {
 
     fn encoded_open() -> OpenRequest {
         OpenRequest {
+            cursor: crate::protocol::CursorMode::Embedded,
             source: Some(SourceRequest::Encoded {
                 codec: EncodedCodec::H264,
                 width: 486,
@@ -3552,6 +3977,18 @@ mod tests {
             .expect("the channel stays open")
     }
 
+    #[tokio::test]
+    async fn hidden_cursor_is_refused_for_consumer_encoded_pixels() {
+        let (events, _) = tokio_mpsc::unbounded_channel();
+        let mut request = encoded_open();
+        request.cursor = crate::protocol::CursorMode::Hidden;
+        let error = Session::open(request, events)
+            .await
+            .err()
+            .expect("cannot alter encoded pixels");
+        assert_eq!(error.code, "cursor-unavailable");
+    }
+
     #[tokio::test]
     async fn an_encoded_session_opens_without_capture_encoder_or_input() {
         let (events, _received) = tokio_mpsc::unbounded_channel();
@@ -3698,6 +4135,7 @@ mod tests {
         let (events, _received) = tokio_mpsc::unbounded_channel();
         let result = Session::open(
             OpenRequest {
+                cursor: crate::protocol::CursorMode::Embedded,
                 source: None,
                 permissions: vec![Permission::Control],
                 max_width: 640,
@@ -3726,6 +4164,11 @@ mod tests {
         use webrtc::peer_connection::RTCPeerConnectionState as State;
         let (events, mut received) = tokio_mpsc::unbounded_channel();
         let (inner, recorded) = test_inner(events).await;
+        #[cfg(target_os = "windows")]
+        inner
+            .with_input(|target| target.chord(1, Vec::new(), true))
+            .unwrap();
+        #[cfg(not(target_os = "windows"))]
         inner.apply(ControlMessage::Key {
             name: Some(String::from("Control")),
             character: None,
@@ -3942,7 +4385,10 @@ mod tests {
             1000,
         );
 
-        // 40 frames over 200 ms is 200 fps; the requested 20 fps caps what leaves.
+        // 40 frames nominally over 200 ms; Windows timers can round each 5 ms
+        // sleep upward, so its cap assertion uses the actual burst duration.
+        #[cfg(target_os = "windows")]
+        let burst_started = Instant::now();
         for _ in 0..40 {
             frame_tx.put(
                 I420 {
@@ -3955,9 +4401,13 @@ mod tests {
             tokio::time::sleep(Duration::from_millis(5)).await;
         }
         let motion = inner.metrics.lock().unwrap().encoded_frames;
+        #[cfg(target_os = "windows")]
+        let cap = (burst_started.elapsed().as_secs_f64() * 20.0).ceil() as u64 + 3;
+        #[cfg(not(target_os = "windows"))]
+        let cap = 7;
         assert!(
-            motion <= 7,
-            "the requested rate is a cap, got {motion} of 40"
+            motion <= cap,
+            "the requested rate is a cap, got {motion} of 40 (cap {cap})"
         );
         assert!(
             motion >= 2,