@desklink/host 0.3.0 → 0.4.0

package/engine/src/input_win.rs

@@ -0,0 +1,91 @@
+use anyhow::{bail, Result};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Button {
+    Left,
+    Middle,
+    Right,
+}
+
+impl Button {
+    pub fn from_number(number: i64) -> Self {
+        match number {
+            2 => Self::Middle,
+            3 => Self::Right,
+            _ => Self::Left,
+        }
+    }
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub struct HeldState {
+    keys: Vec<i16>,
+    buttons: Vec<Button>,
+}
+
+impl HeldState {
+    pub fn key(&mut self, code: i16, down: bool) {
+        if down {
+            if !self.keys.contains(&code) {
+                self.keys.push(code);
+            }
+        } else {
+            self.keys.retain(|held| *held != code);
+        }
+    }
+
+    pub fn button(&mut self, button: Button, down: bool) {
+        if down {
+            if !self.buttons.contains(&button) {
+                self.buttons.push(button);
+            }
+        } else {
+            self.buttons.retain(|held| *held != button);
+        }
+    }
+
+    pub fn release_plan(&mut self) -> (Vec<Button>, Vec<i16>) {
+        (
+            std::mem::take(&mut self.buttons),
+            std::mem::take(&mut self.keys),
+        )
+    }
+}
+
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct InputUnavailable {
+    pub reason: String,
+    pub remedy: String,
+}
+
+pub fn unavailable_reason() -> &'static str {
+    "Windows input is not implemented in this build."
+}
+pub fn probe() -> Result<(), InputUnavailable> {
+    Err(InputUnavailable {
+        reason: unavailable_reason().into(),
+        remedy: "Use a future Windows input-enabled build.".into(),
+    })
+}
+// This private, unconstructible adapter cannot inject native input.
+pub struct InputDevices {
+    _private: (),
+}
+impl InputDevices {
+    pub fn create_for_display(_width: i32, _height: i32, _display: u32) -> Result<Self> {
+        bail!("{}", unavailable_reason())
+    }
+    pub fn move_absolute(&mut self, _x: i64, _y: i64) {}
+    pub fn button(&mut self, _button: Button, _down: bool) {}
+    pub fn scroll(&mut self, _dx: f64, _dy: f64) {}
+    pub fn key(&mut self, _code: i16, _down: bool) -> Result<()> {
+        bail!("{}", unavailable_reason())
+    }
+    pub fn unicode_text(&mut self, _text: &str) -> Result<()> {
+        bail!("{}", unavailable_reason())
+    }
+}
+
+pub fn native_keycode(_code: i16) -> Result<i16> {
+    bail!("{}", unavailable_reason())
+}

package/engine/src/keymap_win.rs

@@ -0,0 +1,39 @@
+use anyhow::Result;
+
+// No key mapping is advertised until the native input lane is implemented.
+pub struct Keystroke {
+    pub code: i16,
+}
+impl Keystroke {
+    pub fn modifiers(&self) -> Vec<i16> {
+        Vec::new()
+    }
+}
+
+pub fn named_key(_name: &str) -> Option<Keystroke> {
+    None
+}
+pub fn modifier_key(_name: &str) -> Option<i16> {
+    None
+}
+pub fn keyboard_layout() -> &'static str {
+    "unknown"
+}
+pub struct LayoutNames;
+impl LayoutNames {
+    pub fn from_environment() -> Self {
+        Self
+    }
+    pub fn identity(&self) -> String {
+        keyboard_layout().into()
+    }
+}
+pub struct Layout;
+impl Layout {
+    pub fn from_environment() -> Result<Self> {
+        Ok(Self)
+    }
+    pub fn keystroke_for_char(&self, _character: char) -> Option<Keystroke> {
+        None
+    }
+}

package/engine/src/mac.rs

@@ -26,6 +26,7 @@ struct CGRect {
 type DisplayId = u32;
 
 unsafe extern "C" {
+    fn desklink_point_overlay_main(display_id: i32) -> i32;
     fn desklink_agent_overlay_main(display_id: i32) -> i32;
     fn desklink_image_bgra(image: *const c_void, length: *mut usize, stride: *mut usize)
         -> *mut u8;
@@ -182,6 +183,7 @@ fn capabilities() -> Value {
             "backends": ["screencapturekit"],
             "formats": ["bgra"],
             "cursor": "embedded",
+            "cursor_modes": ["embedded"],
             "audio": false,
             "displays": displays(),
             "grant": if capture_granted { "granted" } else { "missing-screen-recording" },
@@ -463,14 +465,25 @@ fn indicator_demo(display_id: u32, path: &str) -> Result<(), String> {
 fn record_agent_overlay(path: &str) -> Result<(), String> {
     use std::io::Write;
     let display = unsafe { CGMainDisplayID() };
-    let (w, h) = crate::convert::fit(unsafe { CGDisplayPixelsWide(display) },
-        unsafe { CGDisplayPixelsHigh(display) }, 960, 640);
+    let (w, h) = crate::convert::fit(
+        unsafe { CGDisplayPixelsWide(display) },
+        unsafe { CGDisplayPixelsHigh(display) },
+        960,
+        640,
+    );
     let mut file = std::fs::File::create(path).map_err(|error| error.to_string())?;
     for _ in 0..30 {
         let (pixels, sw, sh, stride) = capture_display(display)?;
-        let raw = crate::convert::to_bgrx(&pixels, sw, sh, stride,
-            crate::convert::PixelFormat::Bgra, w, h)
-            .ok_or_else(|| String::from("could not scale recording frame"))?;
+        let raw = crate::convert::to_bgrx(
+            &pixels,
+            sw,
+            sh,
+            stride,
+            crate::convert::PixelFormat::Bgra,
+            w,
+            h,
+        )
+        .ok_or_else(|| String::from("could not scale recording frame"))?;
         file.write_all(&raw).map_err(|error| error.to_string())?;
         std::thread::sleep(Duration::from_millis(100));
     }
@@ -581,7 +594,12 @@ pub fn run() -> i32 {
     let command = args.next().unwrap_or_else(|| "help".into());
     if matches!(
         command.as_str(),
-        "serve" | "capabilities" | "capture-probe" | "indicator-demo" | "axi-record" | "setup-input"
+        "serve"
+            | "capabilities"
+            | "capture-probe"
+            | "indicator-demo"
+            | "axi-record"
+            | "setup-input"
     ) {
         #[cfg(not(desklink_macos_cli))]
         if let Err(error) = ensure_disclaimed() {
@@ -599,6 +617,10 @@ pub fn run() -> i32 {
                 .status();
             return match result { Ok(status) => status.code().unwrap_or(1), Err(error) => { eprintln!("axi bridge: {error}"); 1 } };
         }
+        "point-overlay" => {
+            let display = args.next().and_then(|value| value.parse().ok()).unwrap_or(0);
+            return unsafe { desklink_point_overlay_main(display) };
+        }
         "agent-overlay" => {
             let display = args.next().and_then(|value| value.parse().ok()).unwrap_or(0);
             return unsafe { desklink_agent_overlay_main(display) };

package/engine/src/main.rs

@@ -11,18 +11,29 @@ mod capture;
 #[cfg(target_os = "macos")]
 #[path = "capture_mac.rs"]
 mod capture;
+#[cfg(target_os = "windows")]
+#[path = "capture_win.rs"]
+mod capture;
 #[cfg(target_os = "linux")]
 mod clipboard;
 #[cfg(target_os = "macos")]
 #[path = "clipboard_mac.rs"]
 mod clipboard;
-#[cfg(any(target_os = "linux", target_os = "macos"))]
+#[cfg(target_os = "windows")]
+#[path = "clipboard_win.rs"]
+mod clipboard;
+#[cfg(any(target_os = "linux", target_os = "macos", target_os = "windows"))]
 mod convert;
 #[cfg(target_os = "linux")]
+mod cursor;
+#[cfg(target_os = "linux")]
 mod encoder;
-#[cfg(all(target_os = "macos", desklink_vpx))]
+#[cfg(all(any(target_os = "macos", target_os = "windows"), desklink_vpx))]
 mod encoder;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 mod h264;
 #[cfg(target_os = "linux")]
 mod h264_nvenc;
@@ -32,13 +43,19 @@ mod h264_openh264;
 mod h264_vaapi;
 #[cfg(all(target_os = "macos", desklink_vpx))]
 mod h264_vt;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 mod indicator;
 #[cfg(target_os = "linux")]
 mod input;
 #[cfg(target_os = "macos")]
 #[path = "input_mac.rs"]
 mod input;
+#[cfg(target_os = "windows")]
+#[path = "input_win.rs"]
+mod input;
 #[cfg(target_os = "linux")]
 mod keeper;
 #[cfg(target_os = "linux")]
@@ -46,44 +63,76 @@ mod keymap;
 #[cfg(target_os = "macos")]
 #[path = "keymap_mac.rs"]
 mod keymap;
+#[cfg(target_os = "windows")]
+#[path = "keymap_win.rs"]
+mod keymap;
 #[cfg(target_os = "macos")]
 mod mac;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 mod peer;
 #[cfg(target_os = "linux")]
 mod portal;
 #[cfg(target_os = "macos")]
 #[path = "portal_mac.rs"]
 mod portal;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(target_os = "windows")]
+#[path = "portal_win.rs"]
+mod portal;
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 mod protocol;
 #[cfg(target_os = "linux")]
 mod session;
-#[cfg(all(target_os = "macos", desklink_vpx))]
+#[cfg(all(any(target_os = "macos", target_os = "windows"), desklink_vpx))]
 mod session;
+#[cfg(target_os = "windows")]
+mod win;
 #[cfg(target_os = "linux")]
 mod x11;
-#[cfg(target_os = "macos")]
+#[cfg(any(target_os = "macos", target_os = "windows"))]
 #[path = "x11_mac.rs"]
 mod x11;
 
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 use anyhow::Result;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 use protocol::{ErrorBody, Event, Request, Response};
 #[cfg(target_os = "linux")]
 use std::sync::mpsc as std_mpsc;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 use std::time::Duration;
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 use tokio::sync::mpsc as tokio_mpsc;
 
 #[cfg(target_os = "linux")]
 unsafe extern "C" {
+    fn desklink_point_overlay_main(display: *const std::ffi::c_char) -> i32;
     fn desklink_agent_overlay_main(display: *const std::ffi::c_char) -> i32;
     fn desklink_agent_overlay_wayland(source_w: i32, source_h: i32) -> i32;
+    fn desklink_wayland_layer_shell_available() -> i32;
+    fn desklink_point_overlay_wayland(w: i32, h: i32, known: i32, x: i32, y: i32) -> i32;
 }
 
 #[cfg(target_os = "linux")]
@@ -105,11 +154,39 @@ fn main() {
             println!("{}", env!("CARGO_PKG_VERSION"));
             0
         }
+        "point-overlay" => {
+            let display = args.get(1).map(String::as_str).unwrap_or("");
+            let display = std::ffi::CString::new(display).expect("valid X display");
+            unsafe { desklink_point_overlay_main(display.as_ptr()) }
+        }
         "agent-overlay" => {
             let display = args.get(1).map(String::as_str).unwrap_or("");
             let display = std::ffi::CString::new(display).expect("valid X display");
             unsafe { desklink_agent_overlay_main(display.as_ptr()) }
         }
+        "point-layer-shell-probe" => match unsafe { desklink_wayland_layer_shell_available() } {
+            1 => {
+                println!("READY");
+                0
+            }
+            0 => {
+                println!("layer_shell_unavailable");
+                2
+            }
+            _ => 2,
+        },
+        "point-overlay-wayland" => {
+            let values: Vec<i32> = args.iter().skip(1).filter_map(|v| v.parse().ok()).collect();
+            if values.len() != 5 || values[0] <= 0 || values[1] <= 0 {
+                2
+            } else {
+                unsafe {
+                    desklink_point_overlay_wayland(
+                        values[0], values[1], values[2], values[3], values[4],
+                    )
+                }
+            }
+        }
         "agent-overlay-wayland" => {
             let width = args.get(1).and_then(|v| v.parse().ok()).unwrap_or(0);
             let height = args.get(2).and_then(|v| v.parse().ok()).unwrap_or(0);
@@ -149,7 +226,10 @@ fn main() {
     std::process::exit(code);
 }
 
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 fn report(result: Result<()>) -> i32 {
     match result {
         Ok(()) => 0,
@@ -230,7 +310,7 @@ fn print_input_setup() {
             println!(
                 "To undo it: remove the rule, remove the user from the group, reload the rules."
             );
-            println!("Without it the engine still captures the desktop and reports view-only.");
+            println!("Without it the engine still captures the desktop; input actions are refused with input-unavailable.");
         }
     }
 }
@@ -295,7 +375,7 @@ fn frame_shape(frame: &crate::convert::I420) -> u64 {
 
 #[cfg(target_os = "linux")]
 async fn probe_portal(seconds: u64) -> Result<()> {
-    let portal = portal::open(None).await?;
+    let portal = portal::open(None, protocol::CursorMode::Embedded).await?;
     eprintln!("portal source: {:?}", portal.source);
     // The source's own size: a zero box converts nothing and reports no frames.
     let (width, height) = crate::convert::fit(
@@ -311,6 +391,7 @@ async fn probe_portal(seconds: u64) -> Result<()> {
         width,
         height,
         30,
+        None,
         Box::new(move |frame, seq, _raw| {
             let _ = tx.send((frame.width, frame.height, seq));
         }),
@@ -349,7 +430,10 @@ async fn probe_portal(seconds: u64) -> Result<()> {
 }
 
 /// The local control protocol loop.
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 async fn serve() -> Result<()> {
     let (out_tx, mut out_rx) = tokio_mpsc::unbounded_channel::<String>();
     let writer = tokio::spawn(async move {
@@ -434,13 +518,16 @@ async fn serve() -> Result<()> {
     if let Some(session) = current.take() {
         session.close("the consumer disconnected").await;
     }
-    let _ = out_tx.send(String::new()).ok();
+    drop(events_tx);
     drop(out_tx);
     let _ = writer.await;
     Ok(())
 }
 
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 fn render_event(notice: session::Notice) -> Option<String> {
     let session::Notice { session_id, event } = notice;
     let (name, params) = match event {
@@ -471,9 +558,17 @@ fn render_event(notice: session::Notice) -> Option<String> {
             "session.state",
             serde_json::json!({ "sessionId": session_id, "capture": capture, "transport": transport, "firstFrame": first_frame }),
         ),
-        session::SessionEvent::Frame { seq, damage } => (
+        session::SessionEvent::Cursor { position } => (
+            "session.cursor",
+            serde_json::json!({ "sessionId": session_id, "x": position.x, "y": position.y, "visible": position.visible, "timestamp_us": position.timestamp_us }),
+        ),
+        session::SessionEvent::Frame {
+            seq,
+            damage,
+            timestamp_us,
+        } => (
             "session.frame.changed",
-            serde_json::json!({ "sessionId": session_id, "seq": seq, "damage": damage }),
+            serde_json::json!({ "sessionId": session_id, "seq": seq, "damage": damage, "timestamp_us": timestamp_us }),
         ),
         session::SessionEvent::Input { input } => (
             "session.input",
@@ -503,7 +598,10 @@ fn render_event(notice: session::Notice) -> Option<String> {
     .ok()
 }
 
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 async fn dispatch(
     request: &Request,
     hello_seen: &mut bool,
@@ -546,7 +644,7 @@ async fn dispatch(
                 .map_err(|error| ErrorBody::new("malformed", error.to_string()))?;
             let open = session::OpenRequest {
                 source: params.source,
-                permissions: params.permissions,
+                cursor: params.cursor,
                 max_width: params.max_width,
                 max_height: params.max_height,
                 bitrate_kbps: params.bitrate_kbps,
@@ -580,10 +678,22 @@ async fn dispatch(
                     "origin": { "x": session.source().origin_x, "y": session.source().origin_y },
                 },
                 "geometry": session.geometry(),
+                "cursor": session.cursor_info(),
+                "agentIndicator": session.agent_indicator(),
             });
             *current = Some(session);
             Ok(result)
         }
+        "session.point" => {
+            let session = require_session(current)?;
+            let params: protocol::PointParams = serde_json::from_value(request.params.clone())
+                .map_err(|error| ErrorBody::new("malformed", error.to_string()))?;
+            check_session(session, &params.session_id, None)?;
+            session
+                .point(&params)
+                .map_err(|error| ErrorBody::new(error.code, error.message))?;
+            Ok(serde_json::json!({"shown": !params.clear}))
+        }
         "session.description" => {
             let session = require_session(current)?;
             let params: protocol::DescriptionParams =
@@ -705,7 +815,10 @@ async fn dispatch(
     }
 }
 
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 fn require_session(
     current: &mut Option<session::Session>,
 ) -> std::result::Result<&mut session::Session, ErrorBody> {
@@ -716,7 +829,10 @@ fn require_session(
 
 /// A late message for a session that has already ended must not revive it, and a
 /// message for a different session must not reach this one.
-#[cfg(any(target_os = "linux", all(target_os = "macos", desklink_vpx)))]
+#[cfg(any(
+    target_os = "linux",
+    all(any(target_os = "macos", target_os = "windows"), desklink_vpx)
+))]
 fn check_session(
     session: &session::Session,
     id: &str,
@@ -741,6 +857,11 @@ fn main() {
     std::process::exit(mac::run());
 }
 
+#[cfg(target_os = "windows")]
+fn main() {
+    std::process::exit(win::run());
+}
+
 #[cfg(all(test, target_os = "linux"))]
 mod tests {
     use super::*;
@@ -762,6 +883,27 @@ mod tests {
         assert!(!hello_seen, "a refused handshake must not open the gate");
     }
 
+    #[test]
+    fn cursor_notice_preserves_source_coordinates_visibility_and_clock() {
+        let line = render_event(session::Notice {
+            session_id: String::from("cursor-session"),
+            event: session::SessionEvent::Cursor {
+                position: protocol::CursorPosition {
+                    x: 32,
+                    y: 64,
+                    visible: false,
+                    timestamp_us: 123456,
+                },
+            },
+        })
+        .unwrap();
+        let parsed: serde_json::Value = serde_json::from_str(&line).unwrap();
+        assert_eq!(
+            parsed,
+            serde_json::json!({"event":"session.cursor","params":{"sessionId":"cursor-session","x":32,"y":64,"visible":false,"timestamp_us":123456}})
+        );
+    }
+
     #[tokio::test]
     async fn the_state_notification_carries_exactly_what_the_document_promises() {
         let line = render_event(session::Notice {

package/engine/src/peer.rs

@@ -5,10 +5,10 @@
 //! module never assumes anything about that channel, which is what keeps the
 //! engine usable by an application that is not this one.
 //!
-//! Input and clipboard ride the session's data channel rather than the local
-//! protocol. The channel is inside the DTLS/SRTP session the engine created for
-//! one authorized grant, so it inherits that session's identity and dies with
-//! it — a revoked session cannot be driven by a client that kept a socket open.
+//! Remote input and clipboard ride the session's data channel; co-located
+//! consumers can also use the local clipboard protocol. The channel is inside
+//! the DTLS/SRTP session opened by a paired consumer and dies with it — a revoked
+//! session cannot be driven by a client that kept a socket open.
 
 use anyhow::{Context, Result};
 use rtc::interceptor::{
@@ -1120,6 +1120,12 @@ impl VideoPeer {
     }
 
     pub async fn close(&self) {
+        let _ = tokio::time::timeout(Duration::from_millis(500), async {
+            while self.control.outstanding_bytes().await.unwrap_or(0) > 0 {
+                tokio::time::sleep(Duration::from_millis(5)).await;
+            }
+        })
+        .await;
         self.feedback.abort();
         let _ = self.control.close().await;
         let _ = self.peer.close().await;

package/engine/src/portal.rs

@@ -33,6 +33,7 @@ pub struct SelectedSource {
 
 pub struct PortalSession {
     pub fd: OwnedFd,
+    pub cursor_mode: &'static str,
     pub source: SelectedSource,
     pub restore_token: Option<String>,
 }
@@ -46,7 +47,10 @@ pub async fn open_display(_: Option<u32>) -> Result<PortalSession> {
     anyhow::bail!("display selection is only supported on macOS")
 }
 
-pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
+pub async fn open(
+    restore_token: Option<&str>,
+    cursor: crate::protocol::CursorMode,
+) -> Result<PortalSession> {
     let proxy = Screencast::new()
         .await
         .context("compositor has no ScreenCast portal")?;
@@ -59,6 +63,15 @@ pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
         anyhow::bail!("ScreenCast portal advertises no monitor source");
     }
 
+    let cursor_mode = if cursor == crate::protocol::CursorMode::Hidden {
+        let available = proxy
+            .available_cursor_modes()
+            .await
+            .context("portal did not advertise cursor modes")?;
+        choose_cursor_mode(available)?
+    } else {
+        CursorMode::Embedded
+    };
     let session = proxy
         .create_session()
         .await
@@ -67,9 +80,7 @@ pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
     proxy
         .select_sources(
             &session,
-            // The cursor is part of the picture the user drives; hiding it would
-            // make precise placement impossible.
-            CursorMode::Embedded,
+            cursor_mode,
             BitFlags::from(SourceType::Monitor),
             false,
             restore_token,
@@ -104,6 +115,11 @@ pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
         .context("OpenPipeWireRemote failed")?;
 
     Ok(PortalSession {
+        cursor_mode: match cursor_mode {
+            CursorMode::Metadata => "metadata",
+            CursorMode::Hidden => "hidden",
+            _ => "embedded",
+        },
         fd,
         source: SelectedSource {
             node_id: stream.pipe_wire_node_id(),
@@ -117,3 +133,25 @@ pub async fn open(restore_token: Option<&str>) -> Result<PortalSession> {
         restore_token: streams.restore_token().map(str::to_owned),
     })
 }
+
+fn choose_cursor_mode(available: BitFlags<CursorMode>) -> Result<CursorMode> {
+    if available.contains(CursorMode::Metadata) {
+        return Ok(CursorMode::Metadata);
+    }
+    anyhow::bail!("cursor_positions_unavailable: portal does not provide cursor metadata")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn hidden_requires_metadata_and_refuses_hidden_only_portals() {
+        assert_eq!(
+            choose_cursor_mode(CursorMode::Metadata | CursorMode::Hidden).unwrap(),
+            CursorMode::Metadata
+        );
+        let error = choose_cursor_mode(CursorMode::Hidden.into()).unwrap_err();
+        assert!(error.to_string().contains("cursor_positions_unavailable:"));
+        assert!(choose_cursor_mode(CursorMode::Embedded.into()).is_err());
+    }
+}