@desklink/host 0.2.0 → 0.3.1

package/engine/src/session.rs

@@ -8,16 +8,18 @@
 use crate::capture::{self, Capture};
 use crate::clipboard;
 use crate::convert::{fit, I420};
-use crate::encoder::Encoder;
+use crate::encoder::{Encoder, VideoEncoder};
 use crate::input::{Button, HeldState, InputDevices};
 use crate::keymap::{self, Layout};
-use crate::peer::{h264_profile_level_id, PeerEvent, TransportOptions, VideoCodec, VideoPeer};
+use crate::peer::{
+    h264_profile_level_id, PathReport, PeerEvent, TransportOptions, VideoCodec, VideoPeer,
+};
 use crate::portal::{self, SelectedSource};
 use crate::protocol::{
     ControlMessage, ControlReply, EncodedCodec, Permission, PointerPhase, SourceRequest,
 };
 use crate::x11::X11Desktop;
-use anyhow::Result;
+use anyhow::{Context, Result};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Condvar, Mutex};
 use std::time::{Duration, Instant};
@@ -51,14 +53,41 @@ pub struct Metrics {
     pub dropped_frames: u64,
     pub encoded_frames: u64,
     pub encoded_bytes: u64,
-    /// Key frames sent: the first, and one per receiver request.
+    /// Key frames sent: the first, one per receiver request, and one each time
+    /// motion starts or stops being coded at half size.
     pub key_frames: u64,
     /// Refinement passes: a still desktop re-coded once, sharp.
     pub refined_frames: u64,
+    /// Motion frames coded at half size because full size could not keep up.
+    pub halved_frames: u64,
+    /// Fresh captures coded at the pace of change: a motion pass on a frame
+    /// the encoder had not coded yet — the population `queue_micros` is over.
+    pub motion_frames: u64,
     /// Time spent in the encoder, in microseconds, over every encoded frame.
     pub encode_micros: u64,
+    /// Time spent grabbing and converting a frame on the capture thread, in
+    /// microseconds, over every frame forwarded to the encoder. On X11 this
+    /// is `GetImage` plus the downscale to I420; unchanged polls are hashed,
+    /// recognised, and never forwarded, so their grab cost stays out; the lab
+    /// harness reads it as the grab cost L1 owns.
+    pub capture_micros: u64,
+    /// Time spent hashing a captured frame and working out its damage on the
+    /// capture thread, in microseconds, over every forwarded frame; the hash
+    /// branch runs only when `local_frames` is on.
+    pub convert_micros: u64,
+    /// Time a freshly captured frame waited between the capture handoff and
+    /// the start of its encode, in microseconds, over motion frames.
+    pub queue_micros: u64,
+    /// Time spent packetizing a frame and handing it to the transport, in
+    /// microseconds, over every sent frame.
+    pub send_micros: u64,
     /// The current rate target, after any loss back-off.
     pub target_kbps: u32,
+    /// The codec frames go out in, `vp9` or `h264`, and what codes them
+    /// (`libvpx`, `nvenc`, `vaapi`, `openh264`, `videotoolbox`); empty for an
+    /// encoded source, whose consumer is the encoder.
+    pub codec: &'static str,
+    pub encoder: &'static str,
     pub input_applied: u64,
     pub input_rejected: u64,
     /// Access units the consumer fed to an encoded source.
@@ -173,18 +202,21 @@ 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> {
     let desktop = Arc::new(Mutex::new(X11Desktop::connect(display)?));
     let (width, height) = {
         let desktop = lock(&desktop);
+        eprintln!("x11 capture path: {}", desktop.capture_path());
         desktop.screen_size()
     };
     let source = SelectedSource {
@@ -207,26 +239,81 @@ fn select_x11(
             .spawn(move || {
                 let interval = frame_interval(max_fps);
                 let mut sequence = 0u64;
-                // An X server has no damage signal here, so an unchanged screen
-                // is recognised by its pixels: handing it on would keep the
-                // encoder busy and a still desktop would never be refined.
+                let mut last_sent: Option<Instant> = None;
+                // 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 {
+                            std::thread::sleep(interval);
+                            continue;
+                        }
+                        if let Some(sent) = last_sent {
+                            let elapsed = sent.elapsed();
+                            if elapsed < interval {
+                                std::thread::sleep(interval - elapsed);
+                            }
+                        }
+                    }
                     let started = Instant::now();
+                    let grabbed = Instant::now();
                     let frame = {
                         let mut desktop = lock(&desktop);
                         desktop.capture_with_pixels(max_width, max_height)
                     };
+                    let grab_micros = grabbed.elapsed().as_micros() as u64;
                     match frame {
                         Ok((frame, raw)) => {
-                            use std::hash::{Hash, Hasher};
-                            let mut hasher = std::collections::hash_map::DefaultHasher::new();
-                            raw.hash(&mut hasher);
-                            let hash = hasher.finish();
-                            if last_hash != Some(hash) {
-                                last_hash = Some(hash);
-                                sink(frame, sequence, raw);
+                            let changed = {
+                                use std::hash::{Hash, Hasher};
+                                let mut hasher = std::collections::hash_map::DefaultHasher::new();
+                                raw.hash(&mut hasher);
+                                let hash = hasher.finish();
+                                if last_hash == Some(hash) {
+                                    false
+                                } else {
+                                    last_hash = Some(hash);
+                                    true
+                                }
+                            };
+                            if changed {
+                                // Handing an unchanged frame on would keep the
+                                // encoder busy and a still desktop would never
+                                // be refined.
+                                if let Ok(mut m) = captured.lock() {
+                                    m.capture_micros += grab_micros;
+                                }
+                                let (w, h) = (frame.width, frame.height);
+                                let (screen_w, screen_h) = (width as usize, height as usize);
+                                sink(frame, sequence, &mut || {
+                                    crate::convert::to_bgrx(
+                                        &raw,
+                                        screen_w,
+                                        screen_h,
+                                        screen_w * 4,
+                                        crate::convert::PixelFormat::Bgrx,
+                                        w,
+                                        h,
+                                    )
+                                });
                                 sequence += 1;
+                                last_sent = Some(started);
+                                first = false;
                             }
                         }
                         Err(error) => {
@@ -239,11 +326,21 @@ fn select_x11(
                                 on_stop(format!("X11 capture stopped: {error}"));
                                 break;
                             }
+                            if !hashed {
+                                let elapsed = started.elapsed();
+                                if elapsed < interval {
+                                    std::thread::sleep(interval - elapsed);
+                                }
+                            }
                         }
                     }
-                    let elapsed = started.elapsed();
-                    if elapsed < interval {
-                        std::thread::sleep(interval - elapsed);
+                    // With Damage the fps cap paced the grab above; without
+                    // it the loop keeps its old trailing sleep.
+                    if hashed {
+                        let elapsed = started.elapsed();
+                        if elapsed < interval {
+                            std::thread::sleep(interval - elapsed);
+                        }
                     }
                 }
             })
@@ -391,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"),
@@ -493,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>,
@@ -506,11 +604,17 @@ pub struct OpenRequest {
     /// Offer a passive ICE-TCP candidate on the loopback, for a forwarded client.
     pub loopback_tcp: bool,
     pub agent_indicator: bool,
+    /// Keep the latest frame and its tile hashes for `session.frame` and
+    /// `session.frame.changed`; off, a frame is converted once, for the encoder.
+    pub local_frames: bool,
 }
 
 /// Events a session raises for its consumer.
 #[derive(Debug)]
 pub enum SessionEvent {
+    Cursor {
+        position: crate::protocol::CursorPosition,
+    },
     Description {
         generation: u64,
         sdp: String,
@@ -527,6 +631,7 @@ pub enum SessionEvent {
         first_frame: bool,
     },
     Frame {
+        timestamp_us: u64,
         seq: u64,
         damage: Vec<[usize; 4]>,
     },
@@ -546,8 +651,13 @@ pub enum SessionEvent {
     CaptureStopped {
         reason: String,
     },
+    /// The session ended on the engine's side. `code` says whether a new
+    /// session may recover it: `transport` is the path to the consumer's peer
+    /// lost, which a fresh `session.open` can heal; `lease` and `error` are
+    /// the session's authority ending or a fault, which it cannot.
     Revoked {
         reason: String,
+        code: &'static str,
     },
 }
 
@@ -564,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,
@@ -579,9 +696,12 @@ struct Inner {
     /// offer has to name the profile the stream's own SPS declares.
     peer: Mutex<Option<Arc<VideoPeer>>>,
     /// Absent for an encoded source: the consumer is the encoder.
-    encoder: Mutex<Option<Encoder>>,
+    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.
@@ -595,6 +715,9 @@ struct Inner {
     events: tokio_mpsc::UnboundedSender<Notice>,
     /// Present only for an encoded source.
     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.
@@ -673,9 +796,11 @@ 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": { "codecs": ["vp9"], "hardware": false },
+        "encode": encode_capabilities(),
         "input": {
             "mechanism": "inputtino/uinput",
             "pointer": input,
@@ -725,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" },
@@ -733,7 +859,7 @@ pub fn capabilities() -> serde_json::Value {
                 "remedy": format!("Allow {} in System Settings › Privacy & Security › Screen & System Audio Recording, then reconnect.", crate::mac::tcc_responsible_app_name())
             }) }
         },
-        "encode": { "codecs": ["vp9"], "hardware": false },
+        "encode": encode_capabilities(),
         "input": {
             "mechanism": "quartz-cgevent",
             "pointer": input,
@@ -750,6 +876,34 @@ 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 {
+    let h264 = crate::h264::probe();
+    let mut codecs = vec!["vp9"];
+    if h264.is_some() {
+        codecs.push("h264");
+    }
+    serde_json::json!({
+        "codecs": codecs,
+        "hardware": false,
+        "h264": {
+            "encoder": h264.map(|info| info.encoder),
+            "hardware": h264.is_some_and(|info| info.hardware),
+        },
+    })
+}
+
 impl Session {
     pub async fn open(
         request: OpenRequest,
@@ -761,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 { .. }));
@@ -832,9 +1006,18 @@ impl Session {
         let capture_status = Arc::new(on_capture_status);
         let frame_events = events.clone();
         let frame_session_id = id.clone();
-        let sink = Box::new(move |frame: I420, _seq: u64, raw: Vec<u8>| {
-            let hashes = tile_hashes(&raw, frame.width, frame.height);
-            if let Ok(mut held) = observed.lock() {
+        let local_frames = request.local_frames;
+        let sink = Box::new(move |frame: I420, _seq: u64, pixels: capture::Pixels| {
+            // The frame's RTP time: when capture handed it over, not when it
+            // was coded, so the receiver never sees encode jitter as cadence.
+            // ponytail: stamped after the backend's grab and conversion; a
+            // grab-start instant from each backend needs a FrameSink change.
+            let captured_at = Instant::now();
+            let raw = if local_frames { pixels() } else { None };
+            let hashes = raw
+                .as_ref()
+                .map(|raw| tile_hashes(raw, frame.width, frame.height));
+            if let (Some(raw), Some(hashes), Ok(mut held)) = (raw, hashes, observed.lock()) {
                 let unchanged =
                     held.as_ref()
                         .is_some_and(|(_, _, width, height, _, current, _)| {
@@ -849,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,
@@ -859,22 +1042,42 @@ 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),
+                        },
                     });
                 }
             }
             if let Ok(mut m) = captured.lock() {
                 m.captured_frames += 1;
+                m.convert_micros += captured_at.elapsed().as_micros() as u64;
             }
             // An encoder that is behind gets the newest frame, not a queue: a
             // desktop stream is live, and the last state is the one that counts.
-            if frame_tx.put(frame) {
+            if frame_tx.put(frame, captured_at) {
                 if let Ok(mut m) = captured.lock() {
                     m.dropped_frames += 1;
                 }
             }
         });
 
+        #[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,
@@ -886,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();
@@ -898,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(),
@@ -945,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()
@@ -962,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);
                 }
@@ -972,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;
@@ -1023,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,
@@ -1046,6 +1301,16 @@ impl Session {
             SessionError::new("input", format!("no keyboard layout: {error:#}"))
         })?;
 
+        // H.264 is offered beside VP9 only when an encoder for it starts on
+        // this machine; the answer then decides which one is coded.
+        let codec = if !crate::h264::fits(width, height) {
+            VideoCodec::Vp9
+        } else {
+            match tokio::task::spawn_blocking(crate::h264::prepare).await {
+                Ok(Some(_)) => VideoCodec::Vp9OrH264,
+                _ => VideoCodec::Vp9,
+            }
+        };
         let (peer_events_tx, peer_events_rx) = tokio_mpsc::unbounded_channel::<PeerEvent>();
         let (peer, offer) = VideoPeer::offer(
             TransportOptions {
@@ -1056,7 +1321,7 @@ impl Session {
                 pace_bps: (bitrate_kbps as f64 * 3_000.0).max(20_000_000.0),
             },
             peer_events_tx,
-            VideoCodec::Vp9,
+            codec,
         )
         .await
         .map_err(|error| SessionError::new("transport", format!("{error:#}")))?;
@@ -1081,9 +1346,23 @@ impl Session {
             capture_error,
             frame_changes,
             peer: Mutex::new(Some(peer.clone())),
-            encoder: Mutex::new(Some(encoder)),
+            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),
@@ -1092,6 +1371,8 @@ impl Session {
             pipeline: pipeline.clone(),
             events: events.clone(),
             encoded: Mutex::new(None),
+            local_frames: request.local_frames,
+            cursor_info,
         });
 
         inner.notify(SessionEvent::Description {
@@ -1170,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),
@@ -1189,6 +1473,8 @@ impl Session {
                 peer_events,
                 feed,
             })),
+            local_frames: false,
+            cursor_info: serde_json::json!({"mode":"unavailable", "positions":false}),
         });
         inner.notify(SessionEvent::State {
             capture: "consented",
@@ -1246,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
     }
@@ -1254,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>,
@@ -1266,6 +1678,7 @@ impl Session {
                 "this session forwards an encoded stream and keeps no frame",
             ));
         }
+        self.keeps_frames()?;
         let mut changes = self.inner.frame_changes.clone();
         let deadline = tokio::time::Instant::now() + Duration::from_millis(timeout_ms.min(120_000));
         loop {
@@ -1302,6 +1715,16 @@ impl Session {
         }
     }
 
+    fn keeps_frames(&self) -> std::result::Result<(), SessionError> {
+        if self.inner.local_frames {
+            return Ok(());
+        }
+        Err(SessionError::new(
+            "operation",
+            "this session was opened with local_frames off and keeps no frame",
+        ))
+    }
+
     /// Write only the requested lossless frame bytes; JSON carries metadata, never pixels.
     pub fn frame(
         &self,
@@ -1321,6 +1744,7 @@ impl Session {
                 "this session forwards an encoded stream and keeps no frame",
             ));
         }
+        self.keeps_frames()?;
         if let Some(reason) = lock(&self.inner.capture_error).clone() {
             return Err(SessionError::new("stream-stopped", reason));
         }
@@ -1356,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 {
@@ -1449,7 +1873,7 @@ impl Session {
     }
 
     pub async fn close(&self, reason: &str) {
-        self.inner.close(reason).await;
+        self.inner.close(reason, "closed").await;
     }
 }
 
@@ -1464,16 +1888,24 @@ impl Inner {
 
     /// Stop everything and release whatever input this session held. Idempotent,
     /// and the one teardown both an explicit close and a lease expiry take.
-    async fn close(&self, reason: &str) {
+    async fn close(&self, reason: &str, code: &str) {
         if self.closed.swap(true, Ordering::SeqCst) {
             return;
         }
         self.control_open.store(false, Ordering::SeqCst);
         self.pipeline.store(false, Ordering::SeqCst);
         drop(lock(&self.encoded).take());
+        // The encoder goes now, not with the last handle: a hardware session
+        // still open when the process exits can hang the driver's exit
+        // handlers, and `shutdown` exits right after this. The encode thread
+        // finds it gone and stops.
+        drop(lock(&self.encoder).take());
         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() {
@@ -1485,8 +1917,8 @@ impl Inner {
         if let Some(peer) = self.peer.lock().ok().and_then(|peer| peer.clone()) {
             let _ = peer
                 .send_control(
-                    &serde_json::to_string(&ControlReply::Revoked { reason }).unwrap_or_else(
-                        |_| String::from(r#"{"kind":"revoked","reason":"closed"}"#),
+                    &serde_json::to_string(&ControlReply::Revoked { reason, code }).unwrap_or_else(
+                        |_| String::from(r#"{"kind":"revoked","reason":"closed","code":"closed"}"#),
                     ),
                 )
                 .await;
@@ -1820,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));
@@ -1937,11 +2369,13 @@ fn frame_interval(max_fps: u32) -> Duration {
     Duration::from_secs_f64(1.0 / max_fps.max(1) as f64)
 }
 
-/// The newest captured frame, handed from the capture thread to the encoder. A
-/// newer frame replaces one the encoder has not taken, so however far behind
-/// it falls, what it codes next is the desktop as it is now.
+/// The newest captured frame and when it was captured, handed from the capture
+/// thread to the encoder. A newer frame replaces one the encoder has not taken,
+/// so however far behind it falls, what it codes next is the desktop as it is
+/// now. The instant travels with the picture so the pipeline can report how
+/// long a coded frame waited for its encode.
 struct FrameSlot {
-    frame: Mutex<(Option<I420>, bool)>,
+    frame: Mutex<(Option<(I420, Instant)>, bool)>,
     ready: Condvar,
 }
 
@@ -1958,13 +2392,13 @@ fn latest_frame() -> (FrameSender, FrameReceiver) {
 
 impl FrameSender {
     /// Hand over a frame; true when it replaced one the encoder never took.
-    fn put(&self, frame: I420) -> bool {
+    fn put(&self, frame: I420, captured: Instant) -> bool {
         let mut held = self
             .0
             .frame
             .lock()
             .unwrap_or_else(|poisoned| poisoned.into_inner());
-        let replaced = held.0.replace(frame).is_some();
+        let replaced = held.0.replace((frame, captured)).is_some();
         self.0.ready.notify_one();
         replaced
     }
@@ -1984,12 +2418,22 @@ impl Drop for FrameSender {
 }
 
 enum Taken {
-    Frame(I420),
+    Frame(I420, Instant),
     Timeout,
     Ended,
 }
 
 impl FrameReceiver {
+    /// Whether a frame is waiting to be taken.
+    fn waiting(&self) -> bool {
+        self.0
+            .frame
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+            .0
+            .is_some()
+    }
+
     fn take(&self, wait: Duration) -> Taken {
         let held = self
             .0
@@ -2002,7 +2446,7 @@ impl FrameReceiver {
             .wait_timeout_while(held, wait, |(frame, ended)| frame.is_none() && !*ended)
             .unwrap_or_else(|poisoned| poisoned.into_inner());
         match held.0.take() {
-            Some(frame) => Taken::Frame(frame),
+            Some((frame, captured)) => Taken::Frame(frame, captured),
             None if held.1 => Taken::Ended,
             None => Taken::Timeout,
         }
@@ -2028,12 +2472,32 @@ fn auto_bitrate(width: usize, height: usize) -> u32 {
     (1500 + (width * height * 18 / 10_000) as u32).min(25_000)
 }
 
-/// Loss-based rate target: back off quickly when the far end reports loss,
-/// creep back when it reports none, never above what the session asked for.
+/// Queueing delay that means the link carries more than it drains: well under
+/// the latency budget, well over the noise of a busy host's scheduling.
+const QUEUE_HIGH: Duration = Duration::from_millis(25);
+/// Below this the path has room again and the target may creep back up.
+const QUEUE_LOW: Duration = Duration::from_millis(10);
+/// How often queueing delay may back the target off: long enough for the last
+/// back-off to reach the far end and show in its feedback, short enough that a
+/// queue is drained in a few steps rather than a few seconds.
+const DELAY_BACKOFF_EVERY: Duration = Duration::from_millis(300);
+
+/// The rate target: back off when the far end reports a standing queue or
+/// loss, creep back when it reports neither, never above what the session
+/// asked for.
+///
+/// Delay leads. A link with a deep buffer (most Wi-Fi and cellular ones) never
+/// loses a packet it can queue, so loss alone lets queueing delay grow to
+/// seconds before anything reacts. A standing queue backs the target off to
+/// 85% of what the path delivered, which drains it; never more than halving
+/// per step, so a stream that was idle and sent little is not taken for a
+/// slow link. Receivers without transport-wide feedback leave it loss-only.
 struct RateControl {
     ceiling: u32,
     target: u32,
     last_change: Option<Instant>,
+    /// The last queueing delay reported, while the path reports one.
+    queue: Option<Duration>,
 }
 
 impl RateControl {
@@ -2042,26 +2506,40 @@ impl RateControl {
             ceiling,
             target: ceiling,
             last_change: None,
+            queue: None,
         }
     }
 
-    /// The new target when these reports move it, at most once a second.
-    fn update(&mut self, reports: &[u8], now: Instant) -> Option<u32> {
-        let worst = *reports.iter().max()?;
-        if self
-            .last_change
-            .is_some_and(|at| now.duration_since(at) < Duration::from_secs(1))
-        {
-            return None;
+    /// The new target when these loss reports (RFC 3550 fractions, /256) or
+    /// this path report move it: down on a standing queue at most every
+    /// `DELAY_BACKOFF_EVERY`, otherwise at most once a second.
+    fn update(&mut self, reports: &[u8], path: Option<PathReport>, now: Instant) -> Option<u32> {
+        if let Some(path) = path {
+            self.queue = Some(path.queue_delay);
         }
-        let loss = worst as f64 / 256.0;
+        let since = self.last_change.map(|at| now.duration_since(at));
+        let waited = |gap: Duration| since.is_none_or(|since| since >= gap);
         let floor = (self.ceiling / 8).max(500);
-        let next = if loss > 0.10 {
-            ((self.target as f64 * 0.7) as u32).max(floor)
-        } else if loss < 0.02 {
-            ((self.target as f64 * 1.08) as u32 + 64).min(self.ceiling)
+        let next = if let Some(path) = path.filter(|path| path.queue_delay > QUEUE_HIGH) {
+            if !waited(DELAY_BACKOFF_EVERY) {
+                return None;
+            }
+            let delivered = path.delivered_kbps.clamp(self.target / 2, self.target);
+            ((delivered as f64 * 0.85) as u32).max(floor)
         } else {
-            self.target
+            let worst = *reports.iter().max()?;
+            if !waited(Duration::from_secs(1)) {
+                return None;
+            }
+            let loss = worst as f64 / 256.0;
+            let roomy = self.queue.is_none_or(|queue| queue < QUEUE_LOW);
+            if loss > 0.10 {
+                ((self.target as f64 * 0.7) as u32).max(floor)
+            } else if loss < 0.02 && roomy {
+                ((self.target as f64 * 1.08) as u32 + 64).min(self.ceiling)
+            } else {
+                self.target
+            }
         };
         if next == self.target {
             return None;
@@ -2072,9 +2550,127 @@ impl RateControl {
     }
 }
 
+/// How far the stream may run ahead of its rate target before the next frame
+/// waits: one large frame (a key frame, a refinement) goes at once, but the
+/// frames behind it hold until the link has had time to carry it, instead of
+/// queueing behind it. The frame that goes then is the newest one.
+const FRAME_BURST: Duration = Duration::from_millis(60);
+
+/// How much faster than the target the budget drains. A rate-controlled
+/// encoder averages its target but overshoots it frame to frame; drained at
+/// the target itself, that ordinary overshoot would add up and hold frames on
+/// a link with room to spare. The rate control, not this, keeps the average
+/// under what the path carries.
+const BUDGET_HEADROOM: f64 = 1.25;
+
+/// What has been sent beyond the rate target, draining a little faster than
+/// it: a leaky bucket that bounds a burst to `FRAME_BURST` plus one frame.
+#[derive(Default)]
+struct SendBudget {
+    bits: f64,
+    at: Option<Instant>,
+}
+
+impl SendBudget {
+    /// The drain rate, in bits per second.
+    fn rate(kbps: u32) -> f64 {
+        kbps.max(1) as f64 * 1000.0 * BUDGET_HEADROOM
+    }
+
+    fn drained(&self, now: Instant, kbps: u32) -> f64 {
+        let elapsed = self
+            .at
+            .map_or(0.0, |at| now.saturating_duration_since(at).as_secs_f64());
+        (self.bits - elapsed * Self::rate(kbps)).max(0.0)
+    }
+
+    /// How long until a frame may go; zero when it may go now.
+    fn wait(&self, now: Instant, kbps: u32) -> Duration {
+        let rate = Self::rate(kbps);
+        let over = self.drained(now, kbps) - FRAME_BURST.as_secs_f64() * rate;
+        Duration::from_secs_f64((over / rate).max(0.0))
+    }
+
+    fn sent(&mut self, now: Instant, bytes: usize, kbps: u32) {
+        self.bits = self.drained(now, kbps) + bytes as f64 * 8.0;
+        self.at = Some(now);
+    }
+}
+
+/// Whether motion is coded at half size. A full-size frame is slow when it
+/// took longer to code than a frame interval and the source already had a
+/// newer frame waiting: the encoder, not the source, set the pace. Content that
+/// arrives slower than the frame cap (30 fps into a 60 fps session) is never
+/// slow however long a frame takes, as long as it is done before the next one.
+/// Several slow frames that each change much of the picture (a packet over a
+/// quarter of the per-frame rate budget) mean full size cannot reach the frame
+/// rate, so the rest of the motion is coded at half size, until it stops (the
+/// refinement pass is always full size) or a run of frames that are both small
+/// and not slow shows full size would keep up again. Packet size or coding time
+/// alone never returns it to full size, so heavy motion does not flap between
+/// sizes; each change costs a key frame. Both directions need a run of frames
+/// rather than one, so a slow key frame or a busy moment on the host does not
+/// flip it, and typing never halves.
+#[derive(Default)]
+struct MotionSize {
+    half: bool,
+    run: u32,
+}
+
+impl MotionSize {
+    const SLOW_RUN: u32 = 5;
+    const SMALL_RUN: u32 = 30;
+
+    /// Account for a motion frame coded at the current size in `took`; `large`
+    /// when its packet was over a quarter of the per-frame rate budget, `behind`
+    /// when a newer frame was already waiting once it was coded.
+    fn coded(&mut self, took: Duration, large: bool, behind: bool, interval: Duration) {
+        let slow = took > interval && behind;
+        let (counts, needed) = if self.half {
+            (!large && !slow, Self::SMALL_RUN)
+        } else {
+            (large && slow, Self::SLOW_RUN)
+        };
+        self.run = if counts { self.run + 1 } else { 0 };
+        if self.run >= needed {
+            self.half = !self.half;
+            self.run = 0;
+        }
+    }
+}
+
+/// The rate cap as a deadline rather than a minimum gap. `due` is where the
+/// next frame falls on the `max_fps` cadence the stream has kept so far, and a
+/// frame may go up to one interval before it, so a late frame's lost time is
+/// made up by the next. A capture clock that jitters around the cap is then
+/// coded the moment each frame arrives, instead of beating against a second
+/// clock that delays a frame or lets the next one supersede it; the sustained
+/// rate still never exceeds the cap, and no window holds more than one frame
+/// over it.
+struct Cadence {
+    interval: Duration,
+    due: Instant,
+}
+
+impl Cadence {
+    fn new(interval: Duration, now: Instant) -> Self {
+        Self { interval, due: now }
+    }
+
+    /// How long until a frame may go; zero when it may go now.
+    fn wait(&self, now: Instant) -> Duration {
+        self.due.saturating_duration_since(now + self.interval)
+    }
+
+    fn sent(&mut self, now: Instant) {
+        self.due = self.due.max(now) + self.interval;
+    }
+}
+
 enum Pass {
     Motion {
         keyframe: bool,
+        half: bool,
     },
     Refine,
     /// The same picture again, so a still stream never looks stalled.
@@ -2107,8 +2703,11 @@ fn spawn_pipeline(
             let mut rate = RateControl::new(bitrate_kbps);
             if let Ok(mut m) = inner.metrics.lock() {
                 m.target_kbps = bitrate_kbps;
+                (m.codec, m.encoder) = ("vp9", "libvpx");
             }
-            let mut latest: Option<I420> = None;
+            // Whether motion may be coded at half size: VP9's alone.
+            let mut halves = true;
+            let mut latest: Option<(I420, Instant)> = None;
             // `pending`: the latest frame has not been coded. `refined`: it has
             // had its refinement pass, or there is nothing to refine.
             let mut pending = false;
@@ -2116,11 +2715,15 @@ fn spawn_pipeline(
             let mut keyframe = true;
             let mut still_since = Instant::now();
             let mut last_sent: Option<Instant> = None;
+            let mut size = MotionSize::default();
+            let mut cadence = Cadence::new(interval, Instant::now());
+            let mut budget = SendBudget::default();
+            // What the last frame was stamped with: the RTP clock never runs
+            // backwards, even for a re-coded picture.
+            let mut last_stamp: Option<Instant> = None;
             loop {
                 let now = Instant::now();
-                let slot = last_sent.map_or(Duration::ZERO, |at| {
-                    interval.saturating_sub(now.duration_since(at))
-                });
+                let slot = cadence.wait(now).max(budget.wait(now, rate.target));
                 let connected = peer.is_connected();
                 let wait = if !connected {
                     // Nothing sent before the transport connects arrives; the
@@ -2140,13 +2743,13 @@ fn spawn_pipeline(
                         .clamp(Duration::from_millis(10), Duration::from_millis(100))
                 };
                 match frame_rx.take(wait) {
-                    Taken::Frame(frame) => {
+                    Taken::Frame(frame, captured) => {
                         if pending {
                             if let Ok(mut m) = inner.metrics.lock() {
                                 m.dropped_frames += 1;
                             }
                         }
-                        latest = Some(frame);
+                        latest = Some((frame, captured));
                         pending = true;
                         refined = false;
                         still_since = Instant::now();
@@ -2161,7 +2764,8 @@ fn spawn_pipeline(
                     keyframe = true;
                 }
                 let reports = peer.take_loss_reports();
-                if let Some(kbps) = rate.update(&reports, Instant::now()) {
+                let path = peer.take_path_report();
+                if let Some(kbps) = rate.update(&reports, path, Instant::now()) {
                     let applied = inner.encoder.lock().map(|mut encoder| {
                         encoder
                             .as_mut()
@@ -2174,18 +2778,45 @@ fn spawn_pipeline(
                         }
                     }
                 }
-                let Some(frame) = latest.as_ref() else {
+                let Some((frame, captured)) = latest.as_ref() else {
                     continue;
                 };
                 if !connected {
                     continue;
                 }
                 let now = Instant::now();
-                if last_sent.is_some_and(|at| now.duration_since(at) < interval) {
+                if !cadence.wait(now).is_zero() || !budget.wait(now, rate.target).is_zero() {
                     continue;
                 }
+                if halves && peer.sends_h264() {
+                    // The answer asked for H.264: nothing has been sent yet,
+                    // since frames wait for the transport, which waits for it.
+                    match start_h264(&inner, rate.target, max_fps) {
+                        Ok(()) => {
+                            halves = false;
+                            size = MotionSize::default();
+                            keyframe = true;
+                        }
+                        Err(error) => {
+                            eprintln!("{error:#}");
+                            let reason = String::from("no H.264 encoder could start");
+                            inner.notify(SessionEvent::Revoked {
+                                reason: reason.clone(),
+                                code: "error",
+                            });
+                            let target = inner.clone();
+                            handle.spawn(async move {
+                                target.close(&reason, "error").await;
+                            });
+                            break;
+                        }
+                    }
+                }
                 let pass = if pending || keyframe {
-                    Pass::Motion { keyframe }
+                    Pass::Motion {
+                        keyframe,
+                        half: size.half && halves,
+                    }
                 } else if !refined && now.duration_since(still_since) >= REFINE_AFTER {
                     Pass::Refine
                 } else if refined
@@ -2206,9 +2837,9 @@ fn spawn_pipeline(
                         break;
                     };
                     match pass {
-                        Pass::Motion { keyframe } => encoder.encode(frame, keyframe),
+                        Pass::Motion { keyframe, half } => encoder.encode(frame, keyframe, half),
                         Pass::Refine => encoder.refine(frame),
-                        Pass::Keepalive => encoder.encode(frame, false),
+                        Pass::Keepalive => encoder.encode(frame, false, false),
                     }
                 };
                 let packet = match packet {
@@ -2226,22 +2857,29 @@ fn spawn_pipeline(
                         let reason = String::from("the encoder rejected a frame");
                         inner.notify(SessionEvent::Revoked {
                             reason: reason.clone(),
+                            code: "error",
                         });
                         let target = inner.clone();
                         handle.spawn(async move {
-                            target.close(&reason).await;
+                            target.close(&reason, "error").await;
                         });
                         break;
                     }
                 };
+                let took = started.elapsed();
                 if let Ok(mut m) = inner.metrics.lock() {
                     m.encoded_frames += 1;
                     m.encoded_bytes += packet.data.len() as u64;
-                    m.encode_micros += started.elapsed().as_micros() as u64;
+                    m.encode_micros += took.as_micros() as u64;
+                    m.key_frames += packet.keyframe as u64;
+                    if matches!(pass, Pass::Motion { .. }) && pending {
+                        m.queue_micros += started.duration_since(*captured).as_micros() as u64;
+                        m.motion_frames += 1;
+                    }
                     match pass {
-                        Pass::Motion { keyframe: true } => m.key_frames += 1,
+                        Pass::Motion { half: true, .. } => m.halved_frames += 1,
                         Pass::Refine => m.refined_frames += 1,
-                        Pass::Motion { keyframe: false } | Pass::Keepalive => {}
+                        Pass::Motion { half: false, .. } | Pass::Keepalive => {}
                     }
                 }
                 match pass {
@@ -2250,13 +2888,34 @@ fn spawn_pipeline(
                         keyframe = false;
                         refined = false;
                         still_since = now;
+                        let budget = rate.target as u64 * 1000 / 8 / max_fps.max(1) as u64;
+                        let large = packet.data.len() as u64 * 4 > budget;
+                        if halves {
+                            size.coded(took, large, frame_rx.waiting(), interval);
+                        }
+                    }
+                    Pass::Refine => {
+                        refined = true;
+                        size = MotionSize::default();
                     }
-                    Pass::Refine => refined = true,
                     Pass::Keepalive => {}
                 }
                 last_sent = Some(now);
+                cadence.sent(now);
+                budget.sent(now, packet.data.len(), rate.target);
+                // A new picture carries the moment it was captured, so the
+                // receiver paces playout by the desktop's clock rather than by
+                // encode time; a re-coded one (refinement, keepalive) is new
+                // content now.
+                let stamp = match pass {
+                    Pass::Motion { .. } => *captured,
+                    Pass::Refine | Pass::Keepalive => now,
+                };
+                let stamp = last_stamp.map_or(stamp, |at| stamp.max(at + Duration::from_millis(1)));
+                last_stamp = Some(stamp);
+                let sending = Instant::now();
                 if let Err(error) =
-                    handle.block_on(peer.send_frame(&packet.data, packet.keyframe, now))
+                    handle.block_on(peer.send_frame(&packet.data, packet.keyframe, stamp))
                 {
                     // The transport is gone. End the session rather than leave
                     // the desktop captured behind a picture that stopped.
@@ -2264,18 +2923,41 @@ fn spawn_pipeline(
                     let reason = String::from("the connection to the phone was lost");
                     inner.notify(SessionEvent::Revoked {
                         reason: reason.clone(),
+                        code: "transport",
                     });
                     let target = inner.clone();
                     handle.spawn(async move {
-                        target.close(&reason).await;
+                        target.close(&reason, "transport").await;
                     });
                     break;
                 }
+                if let Ok(mut m) = inner.metrics.lock() {
+                    m.send_micros += sending.elapsed().as_micros() as u64;
+                }
             }
         })
         .ok();
 }
 
+/// Replace the session's VP9 encoder with an H.264 one of the same size and
+/// rate target, on the encode thread that will drive it.
+fn start_h264(inner: &Arc<Inner>, bitrate_kbps: u32, fps: u32) -> Result<()> {
+    let mut held = lock(&inner.encoder);
+    let (width, height) = held
+        .as_ref()
+        .map(VideoEncoder::size)
+        .context("the session has no encoder")?;
+    let (backend, info) = crate::h264::open(width, height, bitrate_kbps, fps)?;
+    *held = Some(VideoEncoder::H264 {
+        backend,
+        size: (width, height),
+    });
+    if let Ok(mut m) = inner.metrics.lock() {
+        (m.codec, m.encoder) = ("h264", info.encoder);
+    }
+    Ok(())
+}
+
 /// Packetize what a consumer feeds an encoded source, building the peer on the
 /// first access unit that carries an SPS.
 ///
@@ -2338,6 +3020,7 @@ fn spawn_encoded(inner: &Arc<Inner>, mut feed: tokio_mpsc::Receiver<FedAccessUni
                         revoke(
                             &inner,
                             format!("the transport refused the encoded stream: {error:#}"),
+                            "error",
                         )
                         .await;
                         return;
@@ -2362,7 +3045,12 @@ fn spawn_encoded(inner: &Arc<Inner>, mut feed: tokio_mpsc::Receiver<FedAccessUni
                 }
                 Err(error) => {
                     eprintln!("the video track refused a fed access unit: {error:#}");
-                    revoke(&inner, String::from("the connection to the phone was lost")).await;
+                    revoke(
+                        &inner,
+                        String::from("the connection to the phone was lost"),
+                        "transport",
+                    )
+                    .await;
                     return;
                 }
             }
@@ -2376,11 +3064,12 @@ fn current_peer(inner: &Arc<Inner>) -> Option<Arc<VideoPeer>> {
 
 /// End the session with a reason the consumer can show, exactly as the encode
 /// pipeline does when its transport goes away.
-async fn revoke(inner: &Arc<Inner>, reason: String) {
+async fn revoke(inner: &Arc<Inner>, reason: String, code: &'static str) {
     inner.notify(SessionEvent::Revoked {
         reason: reason.clone(),
+        code,
     });
-    inner.close(&reason).await;
+    inner.close(&reason, code).await;
 }
 
 fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiver<PeerEvent>) {
@@ -2428,8 +3117,9 @@ fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiv
                         let reason = String::from("the connection to the phone was lost");
                         inner.notify(SessionEvent::Revoked {
                             reason: reason.clone(),
+                            code: "transport",
                         });
-                        inner.close(&reason).await;
+                        inner.close(&reason, "transport").await;
                         continue;
                     }
                     inner.notify(SessionEvent::State {
@@ -2487,10 +3177,11 @@ fn spawn_lease(inner: &Arc<Inner>, ttl: Duration) {
         let reason = String::from("the session lease expired");
         inner.notify(SessionEvent::Revoked {
             reason: reason.clone(),
+            code: "lease",
         });
         // An expiry ends the session exactly as an explicit close does; the
         // notification above is not a substitute for stopping the desktop.
-        inner.close(&reason).await;
+        inner.close(&reason, "lease").await;
     });
 }
 
@@ -2558,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),
@@ -2575,10 +3269,12 @@ mod tests {
                 peer_events,
                 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);
-        inner.close("test").await;
+        inner.close("test", "closed").await;
         for _ in 0..100 {
             if Arc::strong_count(&inner) == 1 {
                 break;
@@ -2600,6 +3296,41 @@ mod tests {
         );
     }
 
+    #[test]
+    fn frames_that_jitter_around_the_cap_go_at_once_and_a_flood_stays_capped() {
+        let interval = Duration::from_millis(20);
+        let start = Instant::now();
+        let mut cadence = Cadence::new(interval, start);
+        // Captured at the cap, each a few ms early or late: none waits, so
+        // none is delayed or superseded by the next.
+        for (n, jitter) in [0i64, -6, 5, -8, 7, -3, 0, -9, 9, -5].iter().enumerate() {
+            let at = start + interval * n as u32 + Duration::from_millis(9);
+            let at = if *jitter < 0 {
+                at - Duration::from_millis(jitter.unsigned_abs())
+            } else {
+                at + Duration::from_millis(*jitter as u64)
+            };
+            assert_eq!(cadence.wait(at), Duration::ZERO, "frame {n} waited");
+            cadence.sent(at);
+        }
+
+        // A source far above the cap: one second of 1 ms frames sends at most
+        // one frame over the cap.
+        let start = start + Duration::from_secs(10);
+        let mut cadence = Cadence::new(interval, start);
+        let sent = (0..1000)
+            .map(|ms| start + Duration::from_millis(ms))
+            .filter(|&at| {
+                let go = cadence.wait(at).is_zero();
+                if go {
+                    cadence.sent(at);
+                }
+                go
+            })
+            .count();
+        assert!((50..=51).contains(&sent), "sent {sent} at a 50 fps cap");
+    }
+
     #[test]
     fn a_small_source_is_never_upscaled() {
         assert_eq!(fit(1000, 600, 1280, 800), (1000, 600));
@@ -2658,6 +3389,149 @@ mod tests {
         )
         .await
         .expect("a peer connection builds without a network");
+        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,
+        width: usize,
+        height: usize,
+    ) -> (Arc<Inner>, Arc<Mutex<Vec<(i16, bool)>>>) {
         // The pipeline codes nothing before the transport connects.
         peer.assume_connected();
         let recorded = Arc::new(Mutex::new(Vec::new()));
@@ -2684,7 +3558,9 @@ mod tests {
             capture_error: Arc::new(Mutex::new(None)),
             frame_changes: tokio::sync::watch::channel(0).1,
             peer: Mutex::new(Some(Arc::new(peer))),
-            encoder: Mutex::new(Some(Encoder::new(64, 64, 1000, 30, 1).expect("an encoder"))),
+            encoder: Mutex::new(Some(VideoEncoder::Vp9(
+                Encoder::new(width, height, 1000, 30, 1).expect("an encoder"),
+            ))),
             input: Mutex::new(Some(InputTarget {
                 applier: Applier::Recording(recorded.clone()),
                 held: HeldState::default(),
@@ -2695,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),
@@ -2702,6 +3581,8 @@ mod tests {
             pipeline: Arc::new(AtomicBool::new(true)),
             events,
             encoded: Mutex::new(None),
+            local_frames: true,
+            cursor_info: serde_json::json!({"mode":"embedded", "positions":false}),
         });
         (inner, recorded)
     }
@@ -2711,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")),
@@ -2742,11 +3628,11 @@ mod tests {
             matches!(
                 received.try_recv(),
                 Ok(Notice {
-                    event: SessionEvent::Revoked { .. },
+                    event: SessionEvent::Revoked { code: "lease", .. },
                     ..
                 })
             ),
-            "the consumer is still told why the session ended",
+            "the consumer is still told the session's authority ended",
         );
 
         let rejected = inner.metrics.lock().unwrap().input_rejected;
@@ -2764,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;
@@ -3020,20 +3907,24 @@ mod tests {
 
         // The encoder is 64x64; a 32x32 frame is the dimension mismatch that
         // used to be counted and dropped behind a permanently black picture.
-        frame_tx.put(I420 {
-            width: 32,
-            height: 32,
-            data: vec![128u8; 32 * 32 + 2 * 16 * 16],
-        });
+        frame_tx.put(
+            I420 {
+                width: 32,
+                height: 32,
+                data: vec![128u8; 32 * 32 + 2 * 16 * 16],
+            },
+            Instant::now(),
+        );
         tokio::time::sleep(Duration::from_millis(150)).await;
 
         let mut reason = None;
         while let Ok(event) = received.try_recv() {
             if let Notice {
-                event: SessionEvent::Revoked { reason: why },
+                event: SessionEvent::Revoked { reason: why, code },
                 ..
             } = event
             {
+                assert_eq!(code, "error", "a refused frame is a fault, not a lost path");
                 reason = Some(why);
             }
         }
@@ -3059,6 +3950,7 @@ mod tests {
 
     fn encoded_open() -> OpenRequest {
         OpenRequest {
+            cursor: crate::protocol::CursorMode::Embedded,
             source: Some(SourceRequest::Encoded {
                 codec: EncodedCodec::H264,
                 width: 486,
@@ -3074,6 +3966,7 @@ mod tests {
             ttl: Some(Duration::from_secs(30)),
             loopback_tcp: false,
             agent_indicator: false,
+            local_frames: true,
         }
     }
 
@@ -3084,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();
@@ -3230,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,
@@ -3241,6 +4147,7 @@ mod tests {
                 ttl: None,
                 loopback_tcp: false,
                 agent_indicator: false,
+                local_frames: true,
             },
             events,
         )
@@ -3257,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,
@@ -3282,8 +4194,17 @@ mod tests {
         );
 
         peer_tx.send(PeerEvent::State(State::Failed)).unwrap();
+        let mut transport_lost = false;
         tokio::time::timeout(Duration::from_secs(2), async {
             while let Some(notice) = received.recv().await {
+                // A lost path is the one revocation a new session can heal.
+                transport_lost |= matches!(
+                    notice.event,
+                    SessionEvent::Revoked {
+                        code: "transport",
+                        ..
+                    }
+                );
                 if matches!(
                     notice.event,
                     SessionEvent::State {
@@ -3298,11 +4219,158 @@ mod tests {
         })
         .await
         .unwrap();
+        assert!(
+            transport_lost,
+            "a failed transport must revoke with code transport"
+        );
         assert!(inner.revoked_reason().is_some());
         assert!(!inner.pipeline.load(Ordering::SeqCst));
         assert!(inner.input.lock().unwrap().is_none());
     }
 
+    #[test]
+    fn a_standing_queue_backs_the_rate_off_to_what_the_path_delivers() {
+        let start = Instant::now();
+        let queued = |ms: u64, delivered_kbps: u32| {
+            Some(PathReport {
+                queue_delay: Duration::from_millis(ms),
+                delivered_kbps,
+            })
+        };
+        let mut rate = RateControl::new(8000);
+        // A burst's worth of queue and no loss moves nothing.
+        assert_eq!(rate.update(&[], queued(15, 3000), start), None);
+        // A standing queue on a 4 Mbps link: 85% of what got through, at once,
+        // with no loss reported at all.
+        assert_eq!(rate.update(&[], queued(80, 4000), start), Some(3400));
+        // Not again until the back-off has had time to show in the feedback.
+        assert_eq!(
+            rate.update(&[], queued(80, 3400), start + Duration::from_millis(100)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[], queued(60, 3400), start + Duration::from_millis(300)),
+            Some(2890)
+        );
+        // A stream that sent little is not taken for a slow link: at most half.
+        assert_eq!(
+            rate.update(&[], queued(60, 100), start + Duration::from_millis(600)),
+            Some(1228)
+        );
+        // Clean loss reports do not raise it while the queue has not drained...
+        assert_eq!(
+            rate.update(&[0], queued(15, 1200), start + Duration::from_secs(2)),
+            None
+        );
+        // ...and do once it has.
+        assert_eq!(
+            rate.update(&[0], queued(2, 1200), start + Duration::from_secs(3)),
+            Some(1390)
+        );
+        // Nothing drops below the floor.
+        let mut rate = RateControl::new(8000);
+        for step in 0..20u64 {
+            rate.update(
+                &[],
+                queued(200, 1),
+                start + DELAY_BACKOFF_EVERY * step as u32,
+            );
+        }
+        assert_eq!(rate.target, 1000);
+    }
+
+    #[test]
+    fn without_transport_feedback_the_rate_follows_loss_alone() {
+        let start = Instant::now();
+        let mut rate = RateControl::new(8000);
+        assert_eq!(rate.update(&[], None, start), None);
+        assert_eq!(rate.update(&[64], None, start), Some(5600));
+        assert_eq!(
+            rate.update(&[64], None, start + Duration::from_millis(500)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[10], None, start + Duration::from_secs(1)),
+            None
+        );
+        assert_eq!(
+            rate.update(&[0], None, start + Duration::from_secs(2)),
+            Some(6112)
+        );
+    }
+
+    #[test]
+    fn a_large_frame_holds_the_next_until_the_link_has_carried_it() {
+        let start = Instant::now();
+        let mut budget = SendBudget::default();
+        // Frames at the target, one per 20 ms at 4000 kbps, never wait, and
+        // neither does the ordinary overshoot of a frame at twice the budget.
+        for n in 0..50u32 {
+            let at = start + Duration::from_millis(20) * n;
+            assert_eq!(budget.wait(at, 4000), Duration::ZERO, "frame {n} waited");
+            budget.sent(at, if n % 5 == 0 { 20_000 } else { 10_000 }, 4000);
+        }
+        // A 100 kB key frame drains in 160 ms (4000 kbps and a quarter): it
+        // goes at once, and the next waits out all of it past the 60 ms burst
+        // allowance.
+        let at = start + Duration::from_secs(1);
+        assert_eq!(budget.wait(at, 4000), Duration::ZERO);
+        budget.sent(at, 100_000, 4000);
+        let wait = budget.wait(at, 4000);
+        assert!(
+            (Duration::from_millis(99)..=Duration::from_millis(101)).contains(&wait),
+            "waited {wait:?}"
+        );
+        assert_eq!(budget.wait(at + wait, 4000), Duration::ZERO);
+    }
+
+    #[test]
+    fn motion_halves_only_when_the_encoder_sets_the_pace_and_does_not_flap() {
+        let interval = Duration::from_millis(16);
+        let (slow, fast) = (Duration::from_millis(30), Duration::from_millis(2));
+        let mut size = MotionSize::default();
+        for _ in 0..MotionSize::SLOW_RUN * 4 {
+            size.coded(slow, false, true, interval);
+        }
+        assert!(
+            !size.half,
+            "slow small frames (typing on a busy host) keep full size"
+        );
+        for _ in 0..MotionSize::SLOW_RUN * 4 {
+            size.coded(slow, true, false, interval);
+        }
+        assert!(
+            !size.half,
+            "a source slower than the cap (30 fps, 30 ms encode) never halves"
+        );
+        for _ in 0..MotionSize::SLOW_RUN - 1 {
+            size.coded(slow, true, true, interval);
+        }
+        size.coded(fast, true, true, interval);
+        assert!(!size.half, "a broken run of slow frames keeps full size");
+        for _ in 0..MotionSize::SLOW_RUN {
+            size.coded(slow, true, true, interval);
+        }
+        assert!(size.half, "a run of slow large frames halves");
+        // The marginal band: half-size frames that are small but still slow,
+        // between large ones. Neither may send it back to full size.
+        for i in 0..MotionSize::SMALL_RUN * 10 {
+            size.coded(slow, i % 7 == 0, true, interval);
+            assert!(size.half, "marginal half-size motion must not flap back");
+        }
+        for _ in 0..MotionSize::SMALL_RUN * 2 {
+            size.coded(fast, true, true, interval);
+        }
+        assert!(size.half, "large half-size frames stay half, however fast");
+        for _ in 0..MotionSize::SMALL_RUN {
+            size.coded(fast, false, true, interval);
+        }
+        assert!(
+            !size.half,
+            "a run of small, fast half-size frames returns to full size"
+        );
+    }
+
     #[tokio::test]
     async fn the_pipeline_caps_the_rate_codes_the_last_frame_and_refines_a_still_desktop_once() {
         let (events, _events_rx) = tokio_mpsc::unbounded_channel();
@@ -3317,19 +4385,29 @@ 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 {
-                width: 64,
-                height: 64,
-                data: vec![128u8; 64 * 64 + 2 * 32 * 32],
-            });
+            frame_tx.put(
+                I420 {
+                    width: 64,
+                    height: 64,
+                    data: vec![128u8; 64 * 64 + 2 * 32 * 32],
+                },
+                Instant::now(),
+            );
             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,
@@ -3362,5 +4440,74 @@ mod tests {
             "a still stream still sends"
         );
         assert_eq!((later.key_frames, later.refined_frames), (1, 1));
+        assert_eq!((later.codec, later.encoder), ("vp9", "libvpx"));
+    }
+
+    #[tokio::test]
+    async fn a_receiver_that_asks_for_h264_is_sent_h264_from_the_first_frame() {
+        let Some(info) = tokio::task::spawn_blocking(crate::h264::probe)
+            .await
+            .unwrap()
+        else {
+            eprintln!("skipped: no H.264 encoder starts on this machine");
+            return;
+        };
+        let (peer, _answer) =
+            crate::peer::tests::answered(vec![crate::peer::tests::h264_receiver_codec()]).await;
+        let (events, _events_rx) = tokio_mpsc::unbounded_channel();
+        let (inner, _recorded) = test_inner_with(events, peer, 320, 240);
+        // The answer is real, so ICE runs and, with no candidates, never
+        // connects; each state it reports would take back `assume_connected`.
+        let pinned = current_peer(&inner).expect("the test's peer");
+        let pin = tokio::spawn(async move {
+            loop {
+                pinned.assume_connected();
+                tokio::time::sleep(Duration::from_millis(5)).await;
+            }
+        });
+        let (frame_tx, frame_rx) = latest_frame();
+        spawn_pipeline(
+            &inner,
+            current_peer(&inner).expect("the test's peer"),
+            frame_rx,
+            Arc::new(AtomicBool::new(true)),
+            20,
+            1000,
+        );
+        for shade in 0..10u8 {
+            frame_tx.put(
+                I420 {
+                    width: 320,
+                    height: 240,
+                    data: vec![shade * 20; 320 * 240 * 3 / 2],
+                },
+                Instant::now(),
+            );
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        // Opening a hardware session can take a good part of a second, more
+        // with other tests holding the GPU: wait for the still to be refined.
+        let deadline = Instant::now() + Duration::from_secs(10);
+        while inner.metrics.lock().unwrap().refined_frames == 0 && Instant::now() < deadline {
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        let metrics = inner.metrics.lock().unwrap().clone();
+        assert_eq!((metrics.codec, metrics.encoder), ("h264", info.encoder));
+        assert!(metrics.encoded_frames >= 2, "{metrics:?}");
+        assert_eq!(
+            metrics.key_frames, 1,
+            "one IDR, then inter frames: {metrics:?}"
+        );
+        assert_eq!(metrics.refined_frames, 1, "a still desktop is refined once");
+        assert_eq!(
+            metrics.halved_frames, 0,
+            "H.264 is always coded at full size"
+        );
+        pin.abort();
+        inner.close("done", "closed").await;
+        assert!(
+            lock(&inner.encoder).is_none(),
+            "closing releases the encoder"
+        );
     }
 }