@desklink/host 0.4.0 → 0.5.1

package/README.md

@@ -126,10 +126,13 @@ libvpx's licence and patent grant in `prefix/THIRD_PARTY_LICENSES.txt`.
 Without that prefix the compile seam still builds and refuses `serve`.
 Hosted Windows CI resolves the opt-in engine through the published Node API
 and completes a `serve` hello/capabilities handshake with clean shutdown; it
-also checks Chrome decode and input relay, and DLL
-dependencies. Dedicated Windows rig qualification of
-capture, input, mixed DPI, GPU encoding and elevation is pending; signing and
-packaging are later lanes.
+also installs the packed packages into an empty project, checks the installed
+`@desklink/host` tree against its pack manifest, starts the engine from that
+install, and checks Chrome decode and input relay, and DLL
+dependencies. That install proof is installation and startup on a hosted
+machine: the engine still comes from a source build, because Windows platform
+packages are not published, and capture, input, encoding quality, mixed DPI, GPU
+encoding and elevation stay with the dedicated rig lanes.
 
 ### macOS (preview)
 
@@ -276,11 +279,13 @@ await client.addCandidate(session.sessionId, session.generation, candidate, sdpM
 ```
 
 For cursor-free recordings, open with `cursor: 'hidden'` and inspect
-`session.cursor`: Linux portals require Metadata for hidden capture;
-`positions` is true for accepted hidden sessions. Subscribe to
-`session.cursor` events for source-coordinate `x`, `y`, `visible`, and monotonic
-`timestamp_us` (the same clock as local frame metadata). Hidden-only portals
-return `cursor_positions_unavailable`. X11 reports positions even on still
+`session.cursor`. On Wayland the portal leaves the cursor out of the pixels and
+the compositor supplies its position through `ext-image-copy-capture-v1`;
+`positions` is true once it has. Subscribe to `session.cursor` events for
+source-coordinate `x`, `y`, `visible`, the cursor image's `hotspot` where
+known, and monotonic `timestamp_us` (the same clock as local frame metadata).
+A compositor without that protocol still captures, cursor hidden, and says so
+in `cursor.limitation`. X11 reports positions even on still
 frames and already captures root pixels without a cursor. macOS, Windows, and consumer-encoded
 sources return `cursor-unavailable` for hidden requests. Omitting the option
 preserves existing behavior. See [the cursor protocol](docs/PROTOCOL.md#cursor-free-capture).

package/dist/protocol.d.ts

@@ -32,7 +32,7 @@ export interface EngineCapabilities {
         cursor_modes?: Array<'embedded' | 'hidden'>;
         cursor_positions?: {
             x11: boolean;
-            portal: 'negotiated';
+            wayland: 'ext-image-copy-capture-v1';
         };
         audio: boolean;
         displays?: Array<{
@@ -110,6 +110,10 @@ export type SourceRequest = {
 export interface CursorInfo {
     mode: 'embedded' | 'hidden' | 'metadata' | 'unavailable';
     positions: boolean;
+    /** Where hidden-cursor positions come from on Wayland. */
+    source?: 'ext-image-copy-capture-v1';
+    /** Why a hidden session has no cursor positions (yet). */
+    limitation?: string;
 }
 export interface OpenSessionRequest {
     /** Cursor-free frames with independent source-coordinate position events. */
@@ -164,6 +168,10 @@ export type EngineEvent = {
         y: number;
         visible: boolean;
         timestamp_us: number;
+        hotspot?: {
+            x: number;
+            y: number;
+        };
     };
 } | {
     event: 'session.description';

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA6JlC,wEAAwE;AACxE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAiKlC,wEAAwE;AACxE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACrC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ"}

package/docs/PROTOCOL.md

@@ -126,7 +126,7 @@ require fresh consent. The macOS engine requires a VP9-enabled build
     "formats": ["bgrx", "bgra", "rgbx", "rgba"],
     "cursor": "embedded",
     "cursor_modes": ["embedded", "hidden"],
-    "cursor_positions": {"x11": true, "portal": "negotiated"},
+    "cursor_positions": {"x11": true, "wayland": "ext-image-copy-capture-v1"},
     "audio": false
   },
   "encode": {"codecs": ["vp9", "h264"], "hardware": false,
@@ -450,8 +450,9 @@ runs at most about 60 ms of its rate target ahead of it, so frames never queue
 behind a burst. `refined_frames` counts refinement passes: a
 desktop that stops changing is coded once more at a fine quantizer, so it reads
 sharp. `halved_frames` counts motion frames coded at half width and height: when
-full-size frames that change much of the picture take longer to code than a
-frame interval while a newer frame is already waiting, several frames in a row,
+full-size frames that change much of the picture take longer to code or to
+drain at the current rate target than a frame interval while a newer frame is
+already waiting or send-budget debt is held, several frames in a row,
 motion is coded at half size until the desktop stops or its changes shrink to
 small ones that code in time; the refinement pass is always full size. Key
 frames are sent only for the first frame, when the receiver asks (RTCP PLI or
@@ -459,7 +460,9 @@ FIR), and when the coded size changes that way, so a receiver never has to scale
 references across a size change. `target_kbps` is the current rate target after
 any back-off: for a standing queue on the path, measured from the receiver's
 transport-wide congestion feedback (RTP `transport-cc`), and for the loss
-its receiver reports carry. `codec` is what frames go out in
+its receiver reports carry. It starts at the requested ceiling capped at
+3000 kbps on an unknown link, then grows toward the ceiling on clean
+loss/delay feedback. `codec` is what frames go out in
 (`vp9` or `h264`) and `encoder` what codes them (`libvpx`, `videotoolbox`,
 `nvenc`, `vaapi` or `openh264`); both are empty for an encoded source.
 
@@ -490,40 +493,52 @@ whose accounting is wrong.
 ## Cursor-free capture
 
 `session.open` accepts `cursor: "hidden"` (default `"embedded"`). Existing
-callers keep their capture behavior. Linux hidden capture requires portal
-**Metadata** so cursor positions remain available while cursor pixels are
-omitted. A portal without Metadata returns the typed
-`cursor_positions_unavailable` refusal. Successful open returns
+callers keep their capture behavior. Linux portal capture asks the portal for
+**Hidden** (or **Metadata**, whose cursor data is ignored) so cursor pixels are
+omitted; a portal that offers neither refuses with `cursor-unavailable`. Cursor
+positions do not come from the portal: the engine asks the compositor directly
+through the `ext-image-copy-capture-v1` pointer cursor session over the
+selected output (Hyprland and wlroots compositors advertise it). Successful
+open returns
 `cursor: {"mode":"metadata"|"hidden"|"embedded"|"unavailable",
-"positions":true|false}`; `mode` names the portal mode accepted by the portal,
-not just the requested option.
+"positions":true|false, "source"?:"ext-image-copy-capture-v1", "limitation"?:string}`;
+`mode` names the portal mode accepted by the portal, not just the requested
+option.
 
 Linux capabilities advertise `capture.cursor_modes: ["embedded","hidden"]`
-and `capture.cursor_positions: {"x11":true,"portal":"negotiated"}`. Portal
-support is resolved at open: hidden capture requires Metadata and an observed
-SPA cursor metadata buffer. A portal that offers only Hidden refuses open with
-`cursor_positions_unavailable`; accepted hidden sessions report `positions:true`.
-Metadata-mode buffers that contain no new cursor data do not fabricate a move
-or a visibility change.
+and `capture.cursor_positions: {"x11":true,"wayland":"ext-image-copy-capture-v1"}`.
+A hidden session never fails for want of positions. `positions` is true once
+the compositor delivered one within a second of open. Otherwise the stream
+still runs, cursor hidden, and `limitation` says why: the compositor lacks the
+protocol, or it has sent nothing yet (the cursor is off the captured output,
+the seat has no pointer, or the compositor withholds positions; Hyprland
+gates them on its cursor permission). The engine logs a warning in each case
+and never reports a guessed or zero position.
+
+The compositor sends a position only when it changes and only while the
+cursor is over the source, at its own commit cadence. The engine keeps the last
+one: a quiet compositor is a still cursor. Leaving the source reports the last
+position with `visible:false`.
 
 Hidden sessions with positions emit local protocol events independently of
 pixel damage, including on a still X11 desktop:
 
 ```json
-{"event":"session.cursor","params":{"sessionId":"…","x":400,"y":300,"visible":true,"timestamp_us":123456}}
+{"event":"session.cursor","params":{"sessionId":"…","x":400,"y":300,"visible":true,"hotspot":{"x":4,"y":6},"timestamp_us":123456}}
 ```
 
 `x,y` name the pointer hotspot in the selected source's coordinates
 (`geometry.source`), before video scaling, without the desktop origin added.
-Portal buffer coordinates are mapped to that geometry. `visible` is false
-outside the source or when SPA supplies an invisible cursor bitmap.
+Compositor buffer coordinates are mapped to that geometry (Hyprland's, which
+are already logical, are taken as they are). `hotspot`, where the compositor
+reports it, is the hotspot's offset inside the cursor image, in the same
+units. `visible` is false while the cursor is outside the source.
 `timestamp_us` is a monotonic engine-process clock in microseconds, sampled
-when the capture thread observes the pointer. The same clock stamps
+when the engine observes the pointer. The same clock stamps
 `session.frame.changed` and `session.frame` metadata, so local recording
 consumers can compare cursor samples to frame handoff times. These are not
-wall-clock or RTP timestamps. SPA cursor updates accompany PipeWire buffers;
-X11 pointer queries run at the session frame cap even with no pixel damage.
-Repeated identical positions/visibility are suppressed.
+wall-clock or RTP timestamps. X11 pointer queries run at the session frame cap
+even with no pixel damage. Repeated identical samples are suppressed.
 
 X11 root GetImage/MIT-SHM never contains the server cursor and this engine
 never composites it, including for existing embedded-default callers. Its

package/engine/Cargo.lock

@@ -536,7 +536,7 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "desklink-host"
-version = "0.4.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -563,6 +563,7 @@ dependencies = [
  "tokio",
  "wayland-client",
  "wayland-protocols",
+ "wayland-protocols-wlr",
  "webrtc",
  "windows-sys 0.61.2",
  "wl-clipboard-rs",

package/engine/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "desklink-host"
-version = "0.4.0"
+version = "0.5.1"
 edition = "2021"
 rust-version = "1.97.1"
 license = "Apache-2.0"
@@ -38,11 +38,14 @@ wl-clipboard-rs = "0.9"
 openh264-sys2 = { version = "0.9.8", default-features = false, features = ["libloading"] }
 sha2 = "0.10"
 bzip2-rs = "0.1.2"
+# Hidden-cursor positions (ext-image-copy-capture-v1, a staging protocol);
+# already in the tree through wl-clipboard-rs.
+wayland-client = "0.31"
+wayland-protocols = { version = "0.32", features = ["client", "staging"] }
 
 [target.'cfg(target_os = "linux")'.dev-dependencies]
-# The Wayland stamp example only; already in the tree through wl-clipboard-rs.
-wayland-client = "0.31"
-wayland-protocols = { version = "0.32", features = ["client"] }
+# The Wayland stamp example's lab pointer; already in the tree through wl-clipboard-rs.
+wayland-protocols-wlr = { version = "0.3", features = ["client"] }
 
 [target.'cfg(target_os = "windows")'.dependencies]
 windows-sys = "0.61.2"

package/engine/src/capture.rs

@@ -13,7 +13,7 @@ use pw::spa;
 use pw::spa::pod::{serialize::PodSerializer, Pod};
 use std::io::Cursor;
 use std::os::fd::OwnedFd;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::{mpsc, Arc, Mutex};
 use std::thread::JoinHandle;
 use std::time::{Duration, Instant};
@@ -55,7 +55,9 @@ pub struct Capture {
     quit: pw::channel::Sender<()>,
     thread: Option<JoinHandle<()>>,
     pub source: SelectedSource,
-    cursor_positions: Arc<AtomicBool>,
+    /// Hidden-cursor positions, when the compositor supplies them; kept with
+    /// the capture so both stop together.
+    pub cursor: Option<crate::wl_cursor::Tracker>,
     geometry: Arc<Mutex<Option<StreamGeometry>>>,
     frames: Arc<AtomicU64>,
     dropped: Arc<AtomicU64>,
@@ -64,9 +66,6 @@ pub struct Capture {
 }
 
 impl Capture {
-    pub fn cursor_positions(&self) -> bool {
-        self.cursor_positions.load(Ordering::Relaxed)
-    }
     pub fn geometry(&self) -> Option<StreamGeometry> {
         self.geometry.lock().ok().and_then(|g| g.clone())
     }
@@ -203,23 +202,11 @@ pub fn start(
     encoded_width: usize,
     encoded_height: usize,
     max_fps: u32,
-    cursor_sink: Option<crate::cursor::CursorSink>,
     sink: FrameSink,
     indicator_position: Option<Arc<Mutex<Option<(i64, i64)>>>>,
     on_stop: Box<dyn Fn(String) + Send>,
 ) -> Result<Capture> {
-    let PortalSession {
-        fd,
-        source,
-        cursor_mode,
-        ..
-    } = session;
-    let cursor_positions = Arc::new(AtomicBool::new(false));
-    let cursor_sink = if cursor_mode == "metadata" {
-        cursor_sink
-    } else {
-        None
-    };
+    let PortalSession { fd, source, .. } = session;
     let geometry = Arc::new(Mutex::new(None));
     let frames = Arc::new(AtomicU64::new(0));
     let dropped = Arc::new(AtomicU64::new(0));
@@ -227,9 +214,7 @@ pub fn start(
     let (ready_tx, ready_rx) = mpsc::channel::<Result<(), String>>();
 
     let node_id = source.node_id;
-    let source_size = (source.width.max(1) as usize, source.height.max(1) as usize);
     let thread = {
-        let cursor_positions = cursor_positions.clone();
         let geometry = geometry.clone();
         let frames = frames.clone();
         let dropped = dropped.clone();
@@ -240,12 +225,9 @@ pub fn start(
                 let result = run_loop(
                     fd,
                     node_id,
-                    source_size,
                     encoded_width,
                     encoded_height,
                     max_fps,
-                    cursor_sink,
-                    cursor_positions,
                     sink,
                     indicator_position,
                     on_stop,
@@ -272,7 +254,7 @@ pub fn start(
         quit,
         thread: Some(thread),
         source,
-        cursor_positions,
+        cursor: None,
         geometry,
         frames,
         dropped,
@@ -291,12 +273,9 @@ pub fn start(
 fn run_loop(
     fd: OwnedFd,
     node_id: u32,
-    source_size: (usize, usize),
     encoded_width: usize,
     encoded_height: usize,
     max_fps: u32,
-    cursor_sink: Option<crate::cursor::CursorSink>,
-    cursor_positions: Arc<AtomicBool>,
     sink: FrameSink,
     indicator_position: Option<Arc<Mutex<Option<(i64, i64)>>>>,
     on_stop: Box<dyn Fn(String) + Send>,
@@ -328,8 +307,6 @@ fn run_loop(
     let stream = pw::stream::StreamBox::new(&core, "desklink-capture", props)
         .context("pw_stream_new failed")?;
 
-    let wants_cursor_meta = cursor_sink.is_some();
-    let mut cursor = cursor_sink.map(crate::cursor::Reporter::new);
     let mut state = StreamState {
         box_w: encoded_width,
         box_h: encoded_height,
@@ -395,31 +372,6 @@ fn run_loop(
             let Some(mut buffer) = stream.dequeue_buffer() else {
                 return;
             };
-            if let Some(cursor) = cursor.as_mut() {
-                if let Some(meta) = buffer.find_meta::<spa::buffer::meta::MetaCursor>() {
-                    cursor_positions.store(true, Ordering::Relaxed);
-                    // The wrapper's size check bounds the bitmap header;
-                    // never follow an unchecked bitmap offset.
-                    let bitmap = buffer
-                        .find_meta::<CursorWithBitmap>()
-                        .filter(|m| {
-                            m.cursor.bitmap_offset as usize
-                                == std::mem::size_of::<spa::sys::spa_meta_cursor>()
-                        })
-                        .map(|m| &m.bitmap);
-                    if state.logical_w == 0 || state.logical_h == 0 {
-                        return;
-                    }
-                    let mut position = *meta.as_raw();
-                    position.position.x = (i64::from(position.position.x) * source_size.0 as i64)
-                        .div_euclid(state.logical_w as i64)
-                        as i32;
-                    position.position.y = (i64::from(position.position.y) * source_size.1 as i64)
-                        .div_euclid(state.logical_h as i64)
-                        as i32;
-                    cursor.update_spa(&position, bitmap, source_size.0, source_size.1);
-                }
-            }
             let Some(format) = state.format else { return };
             let datas = buffer.datas_mut();
             if datas.is_empty() {
@@ -516,15 +468,10 @@ fn run_loop(
     format_pod(&mut format_buf, max_fps)?;
     let mut buffer_buf = Vec::new();
     buffer_pod(&mut buffer_buf)?;
-    let mut cursor_buf = Vec::new();
-    cursor_pod(&mut cursor_buf)?;
     let mut params = vec![
         Pod::from_bytes(&format_buf).context("invalid EnumFormat pod")?,
         Pod::from_bytes(&buffer_buf).context("invalid Buffers pod")?,
     ];
-    if wants_cursor_meta {
-        params.push(Pod::from_bytes(&cursor_buf).context("invalid Cursor Meta pod")?);
-    }
 
     stream
         .connect(
@@ -718,7 +665,7 @@ mod tests {
                 origin_x: 0,
                 origin_y: 0,
             },
-            cursor_positions: Arc::new(AtomicBool::new(false)),
+            cursor: None,
             geometry: Arc::new(Mutex::new(None)),
             frames: Arc::new(AtomicU64::new(0)),
             dropped: Arc::new(AtomicU64::new(0)),
@@ -739,33 +686,3 @@ mod tests {
             .expect("capture stopped and joined");
     }
 }
-
-fn cursor_pod(buffer: &mut Vec<u8>) -> Result<()> {
-    use spa::pod::{object, property, Value};
-    let obj = object!(
-        spa::utils::SpaTypes::ObjectParamMeta,
-        spa::param::ParamType::Meta,
-        property!(
-            RawKey(spa::sys::SPA_PARAM_META_type),
-            Id,
-            RawKey(spa::sys::SPA_META_Cursor)
-        ),
-        property!(
-            RawKey(spa::sys::SPA_PARAM_META_size),
-            Int,
-            (std::mem::size_of::<CursorWithBitmap>() + 256 * 256 * 4) as i32
-        )
-    );
-    PodSerializer::serialize(Cursor::new(buffer), &Value::Object(obj))
-        .map(|_| ())
-        .map_err(|e| anyhow::anyhow!("failed to build Cursor Meta pod: {e}"))
-}
-
-#[repr(C)]
-struct CursorWithBitmap {
-    cursor: spa::sys::spa_meta_cursor,
-    bitmap: spa::sys::spa_meta_bitmap,
-}
-impl spa::buffer::meta::Metadata for CursorWithBitmap {
-    const META_TYPE: u32 = spa::sys::SPA_META_Cursor;
-}

package/engine/src/cursor.rs

@@ -6,51 +6,28 @@ pub type CursorSink = Box<dyn Fn(CursorPosition) + Send + 'static>;
 
 pub struct Reporter {
     sink: CursorSink,
-    last: Option<(i32, i32, bool)>,
-    bitmap_visible: bool,
+    last: Option<(i32, i32, bool, Option<(i32, i32)>)>,
+    /// The cursor image's hotspot offset, where the source reports one.
+    pub hotspot: Option<(i32, i32)>,
 }
 impl Reporter {
     pub fn new(sink: CursorSink) -> Self {
         Self {
             sink,
             last: None,
-            bitmap_visible: true,
+            hotspot: None,
         }
     }
-    pub fn update_spa(
-        &mut self,
-        meta: &pipewire::spa::sys::spa_meta_cursor,
-        bitmap: Option<&pipewire::spa::sys::spa_meta_bitmap>,
-        width: usize,
-        height: usize,
-    ) {
-        // SPA id zero is no new data, not a visibility change.
-        if meta.id == 0 {
-            return;
-        }
-        if let Some(bitmap) = bitmap.filter(|b| b.format != 0) {
-            self.bitmap_visible = bitmap.offset != 0;
-        }
-        let (x, y) = (meta.position.x, meta.position.y);
-        self.update(
-            x,
-            y,
-            self.bitmap_visible
-                && x >= 0
-                && y >= 0
-                && (x as usize) < width
-                && (y as usize) < height,
-        );
-    }
     pub fn update(&mut self, x: i32, y: i32, visible: bool) {
-        if self.last == Some((x, y, visible)) {
+        if self.last == Some((x, y, visible, self.hotspot)) {
             return;
         }
-        self.last = Some((x, y, visible));
+        self.last = Some((x, y, visible, self.hotspot));
         (self.sink)(CursorPosition {
             x,
             y,
             visible,
+            hotspot: self.hotspot,
             timestamp_us: timestamp_us(Instant::now()),
         });
     }
@@ -59,44 +36,6 @@ impl Reporter {
 #[cfg(test)]
 mod tests {
     use super::*;
-    #[test]
-    fn spa_no_update_off_source_and_invisible_bitmap_are_distinct() {
-        use pipewire::spa::sys::{spa_meta_bitmap, spa_meta_cursor, spa_point, spa_rectangle};
-        let (tx, rx) = std::sync::mpsc::channel();
-        let mut reporter = Reporter::new(Box::new(move |p| {
-            tx.send(p).unwrap();
-        }));
-        let mut meta = spa_meta_cursor {
-            id: 1,
-            flags: 0,
-            position: spa_point { x: 40, y: 60 },
-            hotspot: spa_point { x: 2, y: 3 },
-            bitmap_offset: 0,
-        };
-        reporter.update_spa(&meta, None, 800, 600);
-        meta.id = 0;
-        reporter.update_spa(&meta, None, 800, 600);
-        assert_eq!(rx.try_iter().count(), 1);
-        meta.id = 1;
-        meta.position.x = -1;
-        reporter.update_spa(&meta, None, 800, 600);
-        assert!(!rx.try_recv().unwrap().visible);
-        meta.position.x = 40;
-        let bitmap = spa_meta_bitmap {
-            format: 1,
-            size: spa_rectangle {
-                width: 16,
-                height: 16,
-            },
-            stride: 64,
-            offset: 0,
-        };
-        reporter.update_spa(&meta, Some(&bitmap), 800, 600);
-        assert!(!rx.try_recv().unwrap().visible);
-        reporter.update_spa(&meta, None, 800, 600);
-        assert!(rx.try_recv().is_err(), "no new bitmap retains invisibility");
-    }
-
     #[test]
     fn reports_initial_motion_and_visibility_but_not_unchanged_polls() {
         let (tx, rx) = std::sync::mpsc::channel();

package/engine/src/main.rs

@@ -93,6 +93,8 @@ mod session;
 #[cfg(target_os = "windows")]
 mod win;
 #[cfg(target_os = "linux")]
+mod wl_cursor;
+#[cfg(target_os = "linux")]
 mod x11;
 #[cfg(any(target_os = "macos", target_os = "windows"))]
 #[path = "x11_mac.rs"]
@@ -391,7 +393,6 @@ 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));
         }),
@@ -558,10 +559,13 @@ 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::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::Cursor { position } => ("session.cursor", {
+            let mut params = serde_json::json!({ "sessionId": session_id, "x": position.x, "y": position.y, "visible": position.visible, "timestamp_us": position.timestamp_us });
+            if let Some((x, y)) = position.hotspot {
+                params["hotspot"] = serde_json::json!({ "x": x, "y": y });
+            }
+            params
+        }),
         session::SessionEvent::Frame {
             seq,
             damage,
@@ -892,6 +896,7 @@ mod tests {
                     x: 32,
                     y: 64,
                     visible: false,
+                    hotspot: None,
                     timestamp_us: 123456,
                 },
             },

package/engine/src/portal.rs

@@ -2,8 +2,8 @@
 //!
 //! The portal is the only capture path this engine asks the compositor for: it
 //! is what carries the user's consent, works across Wayland compositors, and
-//! hands back a PipeWire remote that [`crate::capture`] consumes. No
-//! compositor-private protocol is used.
+//! hands back a PipeWire remote that [`crate::capture`] consumes. Hidden-cursor
+//! positions come from the compositor itself, through [`crate::wl_cursor`].
 
 use anyhow::{Context, Result};
 use ashpd::desktop::screencast::{CursorMode, Screencast, SourceType};
@@ -134,24 +134,29 @@ pub async fn open(
     })
 }
 
+/// Either mode keeps cursor pixels out of the stream; positions never come
+/// from the portal.
 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")
+    [CursorMode::Hidden, CursorMode::Metadata]
+        .into_iter()
+        .find(|mode| available.contains(*mode))
+        .context("cursor-unavailable: portal cannot leave the cursor out of capture")
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
     #[test]
-    fn hidden_requires_metadata_and_refuses_hidden_only_portals() {
+    fn hidden_takes_any_cursor_free_mode_and_refuses_embedded_only_portals() {
         assert_eq!(
             choose_cursor_mode(CursorMode::Metadata | CursorMode::Hidden).unwrap(),
+            CursorMode::Hidden
+        );
+        assert_eq!(
+            choose_cursor_mode(CursorMode::Metadata.into()).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());
+        let error = choose_cursor_mode(CursorMode::Embedded.into()).unwrap_err();
+        assert!(error.to_string().contains("cursor-unavailable:"));
     }
 }

package/engine/src/protocol.rs

@@ -569,5 +569,6 @@ pub struct CursorPosition {
     pub x: i32,
     pub y: i32,
     pub visible: bool,
+    pub hotspot: Option<(i32, i32)>,
     pub timestamp_us: u64,
 }