Merge origin/main into the pf-capture sweep

Upstream landed `fc335b39` (negotiate the cursor around what the encoder can blend) on the same
files this sweep restructured. Merged rather than rebased: the sweep MOVED ~2,000 lines out of
`linux/mod.rs` into `pipewire.rs`/`portal.rs`/`pw_*.rs`, so a rebase would have re-fought the same
conflict in up to nine commits; merging resolves it once with both sides in view. The repo already
carries merge commits (`land/sweep-all`).

Two conflicts, both resolved by keeping BOTH changes:

* `linux/mod.rs` — `PortalCapturer::open` gains upstream's `want_metadata_cursor` AND keeps the
  sweep's `PortalSession` teardown, so the portal threads now take `(setup_tx, quit_rx,
  want_metadata_cursor)`. The second conflict was upstream editing inside the region Phase 5.1/5.3
  moved out; the split wins and upstream's change is ported to where the code now lives:
  `choose_cursor_mode`'s new `want_metadata` ladder (4 arms — prefer Embedded when the encoder can't
  blend, and warn-then-take Metadata when Embedded isn't advertised) is now in `portal.rs`, taken
  verbatim.
* `gamestream/stream.rs` — the pooled-capturer slot keeps upstream's third reuse key
  (`metadata_cursor`, beside HDR-ness) AND the sweep's `result.is_ok() && capturer.is_alive()`
  re-pool gate. Both guard the same slot against different failures: theirs against reusing a
  session negotiated for the wrong cursor mode, the sweep's (L2) against reusing a dead one.

Everything else auto-merged, including the `want_metadata_cursor` thread through
`host/capture.rs`'s facade and `native/stream.rs`'s `session_plan::cursor_blend_for`.

Verified after the merge: workspace `cargo test` green, `clippy --workspace --all-targets` clean on
Linux AND on x86_64-pc-windows-msvc, `cargo fmt --check --all` clean, pf-capture 38/38.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

crates/pf-capture/src/lib.rs

@@ -515,15 +515,25 @@ pub mod synthetic_nv12;
 /// `want_hdr` offers the GNOME 50+ HDR formats (10-bit PQ/BT.2020 dmabufs) instead of the SDR
 /// set — pass it only when the mirrored monitor is actually in HDR mode (the host probes
 /// DisplayConfig) or the negotiation runs into its 10 s timeout and latches the SDR downgrade.
-/// The [`ZeroCopyPolicy`] carries the pre-resolved encode-backend facts (the one-way edge).
+/// `want_metadata_cursor` asks for cursor-as-metadata (`SPA_META_Cursor`) — pass it only when
+/// the session's encode path composites `CapturedFrame::cursor` (the host consults
+/// `pf-encode`'s `cursor_blend_capable`); otherwise the portal EMBEDS the pointer so it is
+/// never silently lost. The [`ZeroCopyPolicy`] carries the pre-resolved encode-backend facts
+/// (the one-way edge).
 #[cfg(target_os = "linux")]
 pub fn open_portal_monitor(
     anchored: bool,
     want_hdr: bool,
+    want_metadata_cursor: bool,
     policy: ZeroCopyPolicy,
 ) -> Result<Box<dyn Capturer>> {
-    linux::PortalCapturer::open(anchored, want_hdr && !hdr_capture_failed(), policy)
-        .map(|c| Box::new(c) as Box<dyn Capturer>)
+    linux::PortalCapturer::open(
+        anchored,
+        want_hdr && !hdr_capture_failed(),
+        want_metadata_cursor,
+        policy,
+    )
+    .map(|c| Box::new(c) as Box<dyn Capturer>)
 }
 
 /// Open the Linux portal capturer bound to an already-created virtual output's PipeWire node. The

crates/pf-capture/src/linux/mod.rs

@@ -233,7 +233,15 @@ impl PortalCapturer {
     /// RemoteDesktop grant and never raises a separate ScreenCast dialog; `false` uses a plain
     /// ScreenCast session (wlroots, which has no RemoteDesktop portal). `want_hdr` offers the
     /// GNOME 50+ HDR formats (10-bit PQ/BT.2020, dmabuf-only) instead of the SDR set.
-    pub fn open(anchored: bool, want_hdr: bool, policy: ZeroCopyPolicy) -> Result<PortalCapturer> {
+    /// `want_metadata_cursor` picks the cursor mode — `true` asks for `SPA_META_Cursor` (this
+    /// session's encode path composites it), `false` asks the compositor to EMBED the pointer; see
+    /// `portal::choose_cursor_mode`.
+    pub fn open(
+        anchored: bool,
+        want_hdr: bool,
+        want_metadata_cursor: bool,
+        policy: ZeroCopyPolicy,
+    ) -> Result<PortalCapturer> {
         // Portal handshake (async) on its own thread; hands back the PW fd + node id.
         let (setup_tx, setup_rx) = std::sync::mpsc::channel::<Result<(OwnedFd, u32), String>>();
         // Teardown plumbing (see `PortalSession`): `quit_rx` parks the thread once the handshake is
@@ -244,9 +252,9 @@ impl PortalCapturer {
             .name("punktfunk-portal".into())
             .spawn(move || {
                 if anchored {
-                    portal_thread_remote_desktop(setup_tx, quit_rx)
+                    portal_thread_remote_desktop(setup_tx, quit_rx, want_metadata_cursor)
                 } else {
-                    portal_thread(setup_tx, quit_rx)
+                    portal_thread(setup_tx, quit_rx, want_metadata_cursor)
                 }
                 // After the runtime has been dropped inside the fn above, so a successful
                 // `recv_timeout` in `Drop` means the zbus connection is really gone. Covers the

crates/pf-capture/src/linux/portal.rs

@@ -91,19 +91,23 @@ pub fn gnome_hdr_monitor_active() -> bool {
     }
 }
 
-/// Pick the ScreenCast cursor mode from what the backend advertises (`AvailableCursorModes`),
-/// preferring **cursor-as-metadata**: the compositor keeps its cheap hardware cursor plane and
-/// ships the pointer as PipeWire `SPA_META_Cursor` metadata (position + an occasional bitmap),
-/// which the consumer composites itself. That avoids forcing the producer to burn the cursor into
-/// every frame — the `Embedded` mode — which on gamescope would defeat its HW cursor plane. Falls
-/// back to `Embedded`, then `Hidden`, and (if the property query fails, e.g. an older portal)
-/// keeps the prior `Embedded` behavior so the cursor is never silently lost.
+/// Pick the ScreenCast cursor mode from what the backend advertises (`AvailableCursorModes`).
+/// With `want_metadata` the ladder prefers **cursor-as-metadata**: the compositor keeps its cheap
+/// hardware cursor plane and ships the pointer as PipeWire `SPA_META_Cursor` metadata (position +
+/// an occasional bitmap), which the consumer composites itself — avoiding the producer burning the
+/// cursor into every frame (`Embedded`), which on gamescope would defeat its HW cursor plane.
+/// Without it — the session's encode path has no compositing stage for a metadata cursor
+/// (`pf-encode`'s `cursor_blend_capable` said the resolved backend can't blend) — the ladder
+/// prefers `Embedded`, so the pointer is in the pixels instead of in metadata nothing would draw.
+/// Both ladders fall through to the other mode, then `Hidden`; a failed property query (an older
+/// portal) keeps the prior `Embedded` behavior so the cursor is never silently lost.
 async fn choose_cursor_mode(
     proxy: &ashpd::desktop::screencast::Screencast,
+    want_metadata: bool,
 ) -> ashpd::desktop::screencast::CursorMode {
     use ashpd::desktop::screencast::CursorMode;
     match proxy.available_cursor_modes().await {
-        Ok(avail) if avail.contains(CursorMode::Metadata) => {
+        Ok(avail) if want_metadata && avail.contains(CursorMode::Metadata) => {
             tracing::info!(
                 ?avail,
                 "ScreenCast: requesting cursor-as-metadata (SPA_META_Cursor)"
@@ -111,12 +115,30 @@ async fn choose_cursor_mode(
             CursorMode::Metadata
         }
         Ok(avail) if avail.contains(CursorMode::Embedded) => {
-            tracing::info!(
-                ?avail,
-                "ScreenCast: cursor metadata unavailable — requesting Embedded cursor"
-            );
+            if want_metadata {
+                tracing::info!(
+                    ?avail,
+                    "ScreenCast: cursor metadata unavailable — requesting Embedded cursor"
+                );
+            } else {
+                tracing::info!(
+                    ?avail,
+                    "ScreenCast: requesting Embedded cursor (this session's encoder does not \
+                     composite a metadata cursor)"
+                );
+            }
             CursorMode::Embedded
         }
+        Ok(avail) if avail.contains(CursorMode::Metadata) => {
+            // Embedded wanted but not offered. Metadata still beats Hidden: the CPU capture
+            // path composites `SPA_META_Cursor` inline, so part of the matrix keeps a pointer.
+            tracing::warn!(
+                ?avail,
+                "ScreenCast: Embedded cursor not advertised — requesting cursor-as-metadata \
+                 (only CPU-path frames will composite it)"
+            );
+            CursorMode::Metadata
+        }
         Ok(avail) => {
             tracing::warn!(
                 ?avail,
@@ -140,6 +162,7 @@ async fn choose_cursor_mode(
 pub(super) fn portal_thread(
     setup_tx: std::sync::mpsc::Sender<Result<(OwnedFd, u32), String>>,
     quit_rx: tokio::sync::oneshot::Receiver<()>,
+    want_metadata_cursor: bool,
 ) {
     use ashpd::desktop::screencast::{Screencast, SelectSourcesOptions, SourceType};
     use ashpd::desktop::PersistMode;
@@ -170,7 +193,7 @@ pub(super) fn portal_thread(
                 .create_session(Default::default())
                 .await
                 .context("create_session")?;
-            let cursor_mode = choose_cursor_mode(&proxy).await;
+            let cursor_mode = choose_cursor_mode(&proxy, want_metadata_cursor).await;
             proxy
                 .select_sources(
                     &session,
@@ -236,6 +259,7 @@ pub(super) fn portal_thread(
 pub(super) fn portal_thread_remote_desktop(
     setup_tx: std::sync::mpsc::Sender<Result<(OwnedFd, u32), String>>,
     quit_rx: tokio::sync::oneshot::Receiver<()>,
+    want_metadata_cursor: bool,
 ) {
     use ashpd::desktop::remote_desktop::{DeviceType, RemoteDesktop, SelectDevicesOptions};
     use ashpd::desktop::screencast::{Screencast, SelectSourcesOptions, SourceType};
@@ -281,7 +305,7 @@ pub(super) fn portal_thread_remote_desktop(
                 .context("select_devices")?
                 .response()
                 .context("select_devices rejected")?;
-            let cursor_mode = choose_cursor_mode(&screencast).await;
+            let cursor_mode = choose_cursor_mode(&screencast, want_metadata_cursor).await;
             screencast
                 .select_sources(
                     &session,