@desklink/host 0.1.0 → 0.1.1

package/engine/src/session.rs

@@ -61,11 +61,81 @@ pub struct Metrics {
     pub input_rejected: u64,
 }
 
-/// Which desktop is being captured.
-///
-/// Dropping either variant stops its capture: the portal variant drops the
-/// PipeWire stream, which is what releases the compositor's consent, and the X11
-/// variant stops reading the server.
+fn tile_hashes(raw: &[u8], width: usize, height: usize) -> Vec<u64> {
+    use std::hash::{Hash, Hasher};
+    let mut hashes = Vec::new();
+    for y in (0..height).step_by(32) {
+        for x in (0..width).step_by(32) {
+            let mut hash = std::collections::hash_map::DefaultHasher::new();
+            for row in y..(y + 32).min(height) {
+                raw[(row * width + x) * 4..(row * width + (x + 32).min(width)) * 4].hash(&mut hash);
+            }
+            hashes.push(hash.finish());
+        }
+    }
+    hashes
+}
+
+/// Group changed 32-pixel tiles without merging unrelated regions.
+fn dirty_regions(hashes: &[u64], previous: &[u64], width: usize, height: usize) -> Vec<[usize; 4]> {
+    if hashes.len() != previous.len() {
+        return vec![[0, 0, width, height]];
+    }
+    let columns = width.div_ceil(32);
+    let mut dirty: Vec<bool> = hashes
+        .iter()
+        .zip(previous)
+        .map(|(now, before)| now != before)
+        .collect();
+    let mut regions = Vec::new();
+    for index in 0..dirty.len() {
+        if !dirty[index] {
+            continue;
+        }
+        dirty[index] = false;
+        let mut stack = vec![index];
+        let (mut left, mut top, mut right, mut bottom) = (
+            index % columns,
+            index / columns,
+            index % columns,
+            index / columns,
+        );
+        while let Some(tile) = stack.pop() {
+            let col = tile % columns;
+            let row = tile / columns;
+            left = left.min(col);
+            right = right.max(col);
+            top = top.min(row);
+            bottom = bottom.max(row);
+            for neighbor in [
+                tile.checked_sub(columns),
+                (row + 1 < height.div_ceil(32)).then_some(tile + columns),
+                (col > 0).then(|| tile - 1),
+                (col + 1 < columns).then_some(tile + 1),
+            ]
+            .into_iter()
+            .flatten()
+            {
+                if dirty[neighbor] {
+                    dirty[neighbor] = false;
+                    stack.push(neighbor);
+                }
+            }
+        }
+        let x = left * 32;
+        let y = top * 32;
+        regions.push([
+            x,
+            y,
+            ((right + 1) * 32).min(width) - x,
+            ((bottom + 1) * 32).min(height) - y,
+        ]);
+    }
+    regions
+}
+
+/// Dropping either variant stops its capture: the portal releases consent and
+/// the X11 variant stops reading its server.
 enum FrameSource {
     Portal(Capture),
     X11(X11Capture),
@@ -103,6 +173,7 @@ fn select_x11(
     max_fps: u32,
     metrics: Arc<Mutex<Metrics>>,
     sink: capture::FrameSink,
+    on_stop: Box<dyn Fn(String) + Send>,
 ) -> Result<Selected> {
     let desktop = Arc::new(Mutex::new(X11Desktop::connect(display)?));
     let (width, height) = {
@@ -137,17 +208,17 @@ fn select_x11(
                     let started = Instant::now();
                     let frame = {
                         let mut desktop = lock(&desktop);
-                        desktop.capture(max_width, max_height)
+                        desktop.capture_with_pixels(max_width, max_height)
                     };
                     match frame {
-                        Ok(frame) => {
+                        Ok((frame, raw)) => {
                             use std::hash::{Hash, Hasher};
                             let mut hasher = std::collections::hash_map::DefaultHasher::new();
-                            frame.data.hash(&mut hasher);
+                            raw.hash(&mut hasher);
                             let hash = hasher.finish();
                             if last_hash != Some(hash) {
                                 last_hash = Some(hash);
-                                sink(frame, sequence);
+                                sink(frame, sequence, raw);
                                 sequence += 1;
                             }
                         }
@@ -158,6 +229,7 @@ fn select_x11(
                             // A display that has gone away is not recoverable by
                             // retrying, so stop rather than spin on the error.
                             if error.to_string().contains("the X11 connection dropped") {
+                                on_stop(format!("X11 capture stopped: {error}"));
                                 break;
                             }
                         }
@@ -312,6 +384,19 @@ impl InputTarget {
         Ok(())
     }
 
+    #[cfg(target_os = "macos")]
+    fn unicode_text(&mut self, text: &str) -> Result<()> {
+        match &mut self.applier {
+            #[cfg(target_os = "macos")]
+            Applier::Uinput(devices) => devices.unicode_text(text),
+            #[cfg(target_os = "linux")]
+            Applier::Uinput(_) => anyhow::bail!("Unicode text input is unavailable on Linux"),
+            Applier::X11(_) => anyhow::bail!("Unicode text input is unavailable for X11"),
+            #[cfg(test)]
+            Applier::Recording(_) => Ok(()),
+        }
+    }
+
     fn chord(&mut self, code: i16, modifiers: Vec<i16>, down: bool) -> Result<()> {
         if down {
             if self.chord_keys.iter().any(|(held, _)| *held == code) {
@@ -412,6 +497,7 @@ pub struct OpenRequest {
     pub ttl: Option<Duration>,
     /// Offer a passive ICE-TCP candidate on the loopback, for a forwarded client.
     pub loopback_tcp: bool,
+    pub agent_indicator: bool,
 }
 
 /// Events a session raises for its consumer.
@@ -432,7 +518,12 @@ pub enum SessionEvent {
         transport: String,
         first_frame: bool,
     },
+    Frame {
+        seq: u64,
+        damage: Vec<[usize; 4]>,
+    },
     RestoreToken(String),
+    CaptureStopped { reason: String },
     Revoked {
         reason: String,
     },
@@ -447,6 +538,8 @@ pub struct Notice {
     pub event: SessionEvent,
 }
 
+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.
 struct Inner {
@@ -456,9 +549,13 @@ struct Inner {
     source: SelectedSource,
     geometry: serde_json::Value,
     metrics: Arc<Mutex<Metrics>>,
+    latest: Arc<Mutex<Option<FrameSnapshot>>>,
+    capture_error: Arc<Mutex<Option<String>>>,
+    frame_changes: tokio::sync::watch::Receiver<u64>,
     peer: Arc<VideoPeer>,
     encoder: Mutex<Encoder>,
     input: Mutex<Option<InputTarget>>,
+    indicator: Mutex<Option<crate::indicator::Indicator>>,
     capture: Mutex<Option<FrameSource>>,
     layout: Mutex<Layout>,
     last_seq: Mutex<u64>,
@@ -474,12 +571,14 @@ pub struct Session {
     inner: Arc<Inner>,
 }
 
+#[cfg(target_os = "linux")]
 fn wayland_clipboard_available() -> bool {
     std::env::var("XDG_SESSION_TYPE").as_deref() == Ok("wayland")
         && std::env::var_os("WAYLAND_DISPLAY").is_some()
 }
 
 /// What the engine can actually do on this machine right now.
+#[cfg(target_os = "linux")]
 pub fn capabilities() -> serde_json::Value {
     let session_kind = if std::env::var_os("WAYLAND_DISPLAY").is_some() {
         "wayland"
@@ -537,32 +636,149 @@ pub fn capabilities() -> serde_json::Value {
     })
 }
 
+#[cfg(target_os = "macos")]
+fn wayland_clipboard_available() -> bool {
+    true
+}
+
+#[cfg(target_os = "macos")]
+pub fn capabilities() -> serde_json::Value {
+    let capture_granted = unsafe { crate::mac::CGPreflightScreenCaptureAccess() };
+    let (input, input_grant, unavailable) = match crate::input::probe() {
+        Ok(()) => (true, "granted", serde_json::Value::Null),
+        Err(error) => (
+            false,
+            "missing-accessibility",
+            serde_json::json!({
+                "reason": error.reason,
+                "remedy": error.remedy,
+            }),
+        ),
+    };
+    serde_json::json!({
+        "protocol": crate::protocol::PROTOCOL_VERSION,
+        "engine": format!("desklink-host/{}", env!("CARGO_PKG_VERSION")),
+        "platform": "macos",
+        "session": { "kind": "quartz", "on_console": crate::mac::on_console() },
+        "x11": { "available": false, "size": null },
+        "capture": {
+            "mechanism": "screencapturekit",
+            "backends": ["screencapturekit"],
+            "formats": ["bgra"],
+            "cursor": "embedded",
+            "audio": false,
+            "displays": crate::mac::displays(),
+            "grant": if capture_granted { "granted" } else { "missing-screen-recording" },
+            "unavailable_reason": if capture_granted { serde_json::Value::Null } else { serde_json::json!({
+                "reason": format!("Screen Recording permission has not been granted to {}.", crate::mac::tcc_responsible_app_name()),
+                "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 },
+        "input": {
+            "mechanism": "quartz-cgevent",
+            "pointer": input,
+            "wheel": input,
+            "keyboard": input,
+            "text": ["unicode", "us-ansi-keymap"],
+            "layout": keymap::LayoutNames::from_environment().identity(),
+            "unavailable_reason": unavailable,
+            "grant": input_grant,
+        },
+        "clipboard": { "read": true, "write": true, "mime": ["text/plain;charset=utf-8"],
+            "maxBytes": clipboard::MAX_CLIPBOARD_BYTES },
+    })
+}
+
 impl Session {
     pub async fn open(
         request: OpenRequest,
         events: tokio_mpsc::UnboundedSender<Notice>,
     ) -> std::result::Result<Self, SessionError> {
+        if !request.permissions.contains(&Permission::View) {
+            return Err(SessionError::new(
+                "permission",
+                "session.open requires the view permission",
+            ));
+        }
         let id = opaque_id();
         let wants_control = request.permissions.contains(&Permission::Control);
         let wants_x11 = matches!(request.source, Some(SourceRequest::X11 { .. }));
+        let max_fps = request.max_fps.clamp(1, 60);
         // Which desktop decides which input path is even available: an X display
         // takes XTest, which cannot reach any other session, while a portal
         // desktop needs kernel input access.
         if wants_control && !wants_x11 {
             // Refuse up front rather than presenting a control surface that
             // silently does nothing.
-            if let Err(unavailable) = crate::input::probe() {
-                return Err(SessionError::new(
-                    "input-unavailable",
-                    format!("{}; {}", unavailable.reason, unavailable.remedy),
-                ));
+            if crate::input::probe().is_err() {
+                #[cfg(target_os = "macos")]
+                let _ = crate::input::request_access();
+                if let Err(unavailable) = crate::input::probe() {
+                    return Err(SessionError::new(
+                        "input-unavailable",
+                        format!("{}; {}", unavailable.reason, unavailable.remedy),
+                    ));
+                }
             }
         }
 
         let metrics = Arc::new(Mutex::new(Metrics::default()));
+        let mut indicator = None;
         let (frame_tx, frame_rx) = latest_frame();
+        let latest = Arc::new(Mutex::new(None::<FrameSnapshot>));
+        let observed = latest.clone();
+        let frame_sequence = Arc::new(std::sync::atomic::AtomicU64::new(0));
+        let capture_error = Arc::new(Mutex::new(None::<String>));
+        let stopped_error = capture_error.clone();
+        let stopped_latest = latest.clone();
+        let stopped_events = events.clone();
+        let stopped_id = id.clone();
+        let (frame_tx_signal, frame_changes) = tokio::sync::watch::channel(0u64);
         let captured = metrics.clone();
-        let sink = Box::new(move |frame: I420, _seq: u64| {
+        let stop_signal = frame_tx_signal.clone();
+        let on_capture_status = move |running: bool, reason: String| {
+            if let Ok(mut error) = stopped_error.lock() { *error = if running { None } else { Some(reason.clone()) }; }
+            if let Ok(mut frame) = stopped_latest.lock() { *frame = None; }
+            stop_signal.send_replace(0);
+            let _ = stopped_events.send(Notice { session_id: stopped_id.clone(),
+                event: if running { SessionEvent::State { capture: "streaming", transport: String::from("connected"), first_frame: false } }
+                    else { SessionEvent::CaptureStopped { reason } } });
+        };
+        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 unchanged =
+                    held.as_ref()
+                        .is_some_and(|(_, _, width, height, _, current, _)| {
+                            *width == frame.width && *height == frame.height && current == &hashes
+                        });
+                if !unchanged {
+                    let seq = frame_sequence.fetch_add(1, Ordering::Relaxed) + 1;
+                    let previous = held
+                        .as_ref()
+                        .map(|(_, _, _, _, _, current, _)| current.clone())
+                        .unwrap_or_default();
+                    let damage = dirty_regions(&hashes, &previous, frame.width, frame.height);
+                    *held = Some((
+                        seq,
+                        Instant::now(),
+                        frame.width,
+                        frame.height,
+                        raw,
+                        hashes,
+                        previous,
+                    ));
+                    frame_tx_signal.send_replace(seq);
+                    let _ = frame_events.send(Notice {
+                        session_id: frame_session_id.clone(),
+                        event: SessionEvent::Frame { seq, damage },
+                    });
+                }
+            }
             if let Ok(mut m) = captured.lock() {
                 m.captured_frames += 1;
             }
@@ -584,15 +800,20 @@ impl Session {
                 display.as_deref(),
                 request.max_width,
                 request.max_height,
-                request.max_fps,
+                max_fps,
                 metrics.clone(),
                 sink,
+                Box::new({ let status = capture_status.clone(); move |reason| status(false, reason) }),
             )
             .map_err(|error| SessionError::new("source", format!("{error:#}")))?,
             _ => {
-                let portal = portal::open(request.restore_token.as_deref())
-                    .await
-                    .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
+                let portal = match request.source.as_ref() {
+                    Some(SourceRequest::Display { display_id }) => {
+                        portal::open_display(*display_id).await
+                    }
+                    _ => portal::open(request.restore_token.as_deref()).await,
+                }
+                .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
                 if let Some(token) = &portal.restore_token {
                     let _ = events.send(Notice {
                         session_id: id.clone(),
@@ -604,8 +825,53 @@ impl Session {
                 let source_h = source.height.max(1) as usize;
                 let (width, height) =
                     fit(source_w, source_h, request.max_width, request.max_height);
-                let capture = capture::start(portal, width, height, request.max_fps, sink)
-                    .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
+                #[cfg(target_os = "linux")]
+                if request.agent_indicator && wants_control {
+                    indicator = Some(
+                        crate::indicator::Indicator::start_wayland(source_w, source_h).map_err(
+                            |error| {
+                                SessionError::new("indicator-unavailable", format!("{error:#}"))
+                            },
+                        )?,
+                    );
+                }
+                #[cfg(target_os = "macos")]
+                if request.agent_indicator && wants_control {
+                    indicator = Some(
+                        crate::indicator::Indicator::start(source.node_id, source_w, source_h)
+                            .map_err(|error| {
+                                SessionError::new("indicator", format!("{error:#}"))
+                            })?,
+                    );
+                }
+                #[cfg(target_os = "macos")]
+                let capture = capture::start(
+                    portal,
+                    width,
+                    height,
+                    max_fps,
+                    sink,
+                    indicator.as_ref().map(crate::indicator::Indicator::pid),
+                    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,
+                    sink,
+                    indicator
+                        .as_ref()
+                        .map(crate::indicator::Indicator::position),
+                    Box::new({ let status = capture_status.clone(); move |reason| status(false, reason) }),
+                )
+                .map_err(|error| SessionError::new("source", format!("{error:#}")))?;
+                #[cfg(target_os = "linux")]
+                if let Some(indicator) = indicator.as_mut() {
+                    indicator.event('A', -1, -1);
+                }
                 Selected {
                     source,
                     capture: FrameSource::Portal(capture),
@@ -616,6 +882,20 @@ impl Session {
 
         let source_w = source.width.max(1) as usize;
         let source_h = source.height.max(1) as usize;
+        #[cfg(target_os = "linux")]
+        if request.agent_indicator && wants_control && wants_x11 {
+            let display = match &request.source {
+                Some(SourceRequest::X11 {
+                    display: Some(display),
+                }) => display.clone(),
+                _ => std::env::var("DISPLAY")
+                    .map_err(|_| SessionError::new("indicator-unavailable", "no X display"))?,
+            };
+            indicator = Some(
+                crate::indicator::Indicator::start(&display, source_w, source_h)
+                    .map_err(|error| SessionError::new("indicator", format!("{error:#}")))?,
+            );
+        }
         let (width, height) = fit(source_w, source_h, request.max_width, request.max_height);
 
         let bitrate_kbps = if request.bitrate_kbps == 0 {
@@ -627,7 +907,7 @@ impl Session {
             width,
             height,
             bitrate_kbps,
-            request.max_fps,
+            max_fps,
             available_parallelism().min(8) as u32,
         )
         .map_err(|error| SessionError::new("encode", format!("{error:#}")))?;
@@ -647,11 +927,19 @@ impl Session {
                     wheel_rest: (0.0, 0.0),
                 },
                 None => InputTarget {
-                    applier: Applier::Uinput(
-                        InputDevices::create(source_w as i32, source_h as i32).map_err(
-                            |error| SessionError::new("input-unavailable", format!("{error:#}")),
-                        )?,
-                    ),
+                    applier: Applier::Uinput({
+                        #[cfg(target_os = "linux")]
+                        let devices = InputDevices::create(source_w as i32, source_h as i32);
+                        #[cfg(target_os = "macos")]
+                        let devices = InputDevices::create_for_display(
+                            source_w as i32,
+                            source_h as i32,
+                            source.node_id,
+                        );
+                        devices.map_err(|error| {
+                            SessionError::new("input-unavailable", format!("{error:#}"))
+                        })?
+                    }),
                     held: HeldState::default(),
                     explicit_modifiers: Vec::new(),
                     chord_modifiers: Vec::new(),
@@ -694,9 +982,13 @@ impl Session {
             source,
             geometry,
             metrics,
+            latest,
+            capture_error,
+            frame_changes,
             peer: Arc::new(peer),
             encoder: Mutex::new(encoder),
             input: Mutex::new(input),
+            indicator: Mutex::new(indicator),
             capture: Mutex::new(Some(capture)),
             layout: Mutex::new(layout),
             last_seq: Mutex::new(0),
@@ -716,7 +1008,7 @@ impl Session {
             first_frame: false,
         });
 
-        spawn_pipeline(&inner, frame_rx, pipeline, request.max_fps, bitrate_kbps);
+        spawn_pipeline(&inner, frame_rx, pipeline, max_fps, bitrate_kbps);
         spawn_peer_events(&inner, peer_events_rx);
         spawn_lease(&inner, request.ttl.unwrap_or(Duration::from_secs(3600)));
 
@@ -739,6 +1031,106 @@ impl Session {
         &self.inner.source
     }
 
+    pub async fn wait_frame(
+        &self,
+        after_seq: Option<u64>,
+        still_ms: Option<u64>,
+        timeout_ms: u64,
+    ) -> std::result::Result<(), SessionError> {
+        let mut changes = self.inner.frame_changes.clone();
+        let deadline = tokio::time::Instant::now() + Duration::from_millis(timeout_ms.min(120_000));
+        loop {
+            if let Some(reason) = lock(&self.inner.capture_error).clone() {
+                return Err(SessionError::new("stream-stopped", reason));
+            }
+            let (seq, still) = self
+                .inner
+                .latest
+                .lock()
+                .ok()
+                .and_then(|held| held.as_ref().map(|(seq, at, ..)| (*seq, at.elapsed())))
+                .unwrap_or((0, Duration::ZERO));
+            let target = still_ms.or(if after_seq.is_none() { Some(150) } else { None });
+            let advanced = after_seq.is_none_or(|after| seq > after);
+            if seq > 0 && advanced && target.is_none_or(|ms| still >= Duration::from_millis(ms)) {
+                return Ok(());
+            }
+            let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
+            if remaining.is_zero() {
+                return Err(SessionError::new(
+                    "frame-timeout",
+                    "frame condition not met before deadline",
+                ));
+            }
+            let until_still = if seq > 0 && advanced {
+                target.map_or(remaining, |ms| {
+                    Duration::from_millis(ms).saturating_sub(still)
+                })
+            } else {
+                remaining
+            };
+            let _ = tokio::time::timeout(remaining.min(until_still), changes.changed()).await;
+        }
+    }
+
+    /// Write only the requested lossless frame bytes; JSON carries metadata, never pixels.
+    pub fn frame(
+        &self,
+        since: Option<u64>,
+        path: &str,
+        region: Option<[usize; 4]>,
+    ) -> std::result::Result<serde_json::Value, SessionError> {
+        if !self.inner.permissions.contains(&Permission::View) {
+            return Err(SessionError::new(
+                "permission",
+                "view permission is required",
+            ));
+        }
+        if let Some(reason) = lock(&self.inner.capture_error).clone() {
+            return Err(SessionError::new("stream-stopped", reason));
+        }
+        let held = lock(&self.inner.latest);
+        let (seq, at, width, height, raw, hashes, previous) = held
+            .as_ref()
+            .ok_or_else(|| SessionError::new("frame", "the first frame has not arrived"))?;
+        let [x, y, w, h] = region.unwrap_or([0, 0, *width, *height]);
+        if w == 0
+            || h == 0
+            || x.checked_add(w).is_none_or(|end| end > *width)
+            || y.checked_add(h).is_none_or(|end| end > *height)
+        {
+            return Err(SessionError::new(
+                "coordinates",
+                "region exceeds the encoded surface",
+            ));
+        }
+        let damage = if since == Some(*seq) {
+            Vec::new()
+        } else if since == seq.checked_sub(1) && previous.len() == hashes.len() {
+            dirty_regions(hashes, previous, *width, *height)
+        } else {
+            vec![[0, 0, *width, *height]]
+        };
+        // An empty path asks for metadata only; no pixels are copied or written.
+        let pixels = if path.is_empty() {
+            None
+        } else {
+            let mut pixels = Vec::with_capacity(w * h * 4);
+            for row in y..y + h {
+                pixels.extend_from_slice(&raw[(row * width + x) * 4..(row * width + x + w) * 4]);
+            }
+            Some(pixels)
+        };
+        let result = serde_json::json!({ "seq": seq, "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 {
+            std::fs::write(path, pixels)
+                .map_err(|error| SessionError::new("frame", error.to_string()))?;
+        }
+        Ok(result)
+    }
+
     pub fn metrics(&self) -> Metrics {
         self.inner
             .metrics
@@ -819,6 +1211,9 @@ impl Inner {
         }
         self.control_open.store(false, Ordering::SeqCst);
         self.pipeline.store(false, Ordering::SeqCst);
+        if let Ok(mut indicator) = self.indicator.lock() {
+            indicator.take();
+        }
         // 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() {
@@ -922,6 +1317,23 @@ impl Inner {
             }
             *last = seq;
         }
+        let feedback = match &message {
+            ControlMessage::Pointer { phase, x, y, .. } => {
+                let (x, y) = to_source_pixels(*x, *y, self.encoded_size(), &self.source);
+                Some((
+                    if matches!(phase, PointerPhase::Down) {
+                        'C'
+                    } else {
+                        'M'
+                    },
+                    x,
+                    y,
+                ))
+            }
+            ControlMessage::Text { text, .. } if !text.is_empty() => Some(('T', -1, -1)),
+            ControlMessage::Key { down: true, .. } => Some(('T', -1, -1)),
+            _ => None,
+        };
         let outcome = match message {
             ControlMessage::Pointer {
                 phase,
@@ -958,6 +1370,13 @@ impl Inner {
         };
         match outcome {
             Ok(()) => {
+                if let Some((kind, x, y)) = feedback {
+                    if let Ok(mut indicator) = self.indicator.lock() {
+                        if let Some(indicator) = indicator.as_mut() {
+                            indicator.event(kind, x, y);
+                        }
+                    }
+                }
                 if let Ok(mut m) = self.metrics.lock() {
                     m.input_applied += 1;
                 }
@@ -1051,10 +1470,16 @@ impl Inner {
                 keymap::named_key(&name)
                     .ok_or(("text-unsupported", format!("unknown key {name}")))?
             } else if let Some(character) = character {
-                let wanted = character
-                    .chars()
+                let mut characters = character.chars();
+                let wanted = characters
                     .next()
                     .ok_or(("text-unsupported", String::from("empty character")))?;
+                if characters.next().is_some() {
+                    return Err((
+                        "text-unsupported",
+                        String::from("character must contain exactly one Unicode scalar"),
+                    ));
+                }
                 layout.keystroke_for_char(wanted).ok_or((
                     "text-unsupported",
                     format!("the active layout cannot produce {wanted:?}"),
@@ -1080,42 +1505,60 @@ impl Inner {
         if text.len() > 4096 {
             return Err(("text-too-large", String::from("text exceeds 4096 bytes")));
         }
-        let layout = self
-            .layout
-            .lock()
-            .map_err(|_| ("session", String::from("no keyboard layout")))?;
-        let (plan, unreachable) = layout.plan_text(text);
-        drop(layout);
-        if !unreachable.is_empty() {
-            return Err((
-                "text-unsupported",
-                format!("the active layout cannot produce {unreachable:?}; use the clipboard"),
-            ));
+        #[cfg(target_os = "macos")]
+        {
+            let _ = seq;
+            return self.with_input(|target| target.unicode_text(text));
         }
-        let _ = seq;
-        self.with_input(|target| {
-            // Refuse an unsupported physical key before typing any prefix or
-            // holding a modifier. X11 already consumes evdev identities.
-            target.check_keys(
-                plan.iter()
-                    .flatten()
-                    .flat_map(|stroke| std::iter::once(stroke.code).chain(stroke.modifiers())),
-            )?;
-            for keystroke in plan {
-                for stroke in keystroke {
-                    let modifiers = stroke.modifiers();
-                    for modifier in &modifiers {
-                        target.modifier(*modifier, true, false)?;
+        #[cfg(target_os = "linux")]
+        {
+            let layout = self
+                .layout
+                .lock()
+                .map_err(|_| ("session", String::from("no keyboard layout")))?;
+            let (plan, unreachable) = layout.plan_text(text);
+            drop(layout);
+            if !unreachable.is_empty() {
+                return Err((
+                    "text-unsupported",
+                    format!("the active layout cannot produce {unreachable:?}; use the clipboard"),
+                ));
+            }
+            let _ = seq;
+            self.with_input(|target| {
+                // Uinput's immediate down/up pairs can be collapsed by a compositor's
+                // event loop. XTest flushes each edge, so pace only the virtual device.
+                let paced = matches!(&target.applier, Applier::Uinput(_));
+                let pause = || {
+                    if paced {
+                        std::thread::sleep(std::time::Duration::from_millis(5));
                     }
-                    target.key(stroke.code, true)?;
-                    target.key(stroke.code, false)?;
-                    for modifier in modifiers.iter().rev() {
-                        target.modifier(*modifier, false, false)?;
+                };
+                target.check_keys(
+                    plan.iter()
+                        .flatten()
+                        .flat_map(|stroke| std::iter::once(stroke.code).chain(stroke.modifiers())),
+                )?;
+                for keystroke in plan {
+                    for stroke in keystroke {
+                        let modifiers = stroke.modifiers();
+                        for modifier in &modifiers {
+                            target.modifier(*modifier, true, false)?;
+                            pause();
+                        }
+                        target.key(stroke.code, true)?;
+                        pause();
+                        target.key(stroke.code, false)?;
+                        pause();
+                        for modifier in modifiers.iter().rev() {
+                            target.modifier(*modifier, false, false)?;
+                            pause();
+                        }
                     }
                 }
-            }
-            Ok(())
-        })
+                Ok(())
+            })
+        }
     }
 
     fn clipboard_read(self: &Arc<Self>, request: String) {
@@ -1639,6 +2082,14 @@ fn opaque_id() -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn tile_damage_at_origin_does_not_underflow_or_hide_other_tiles() {
+        assert_eq!(
+            dirty_regions(&[1, 0, 0, 1], &[0; 4], 64, 64),
+            vec![[0, 0, 32, 32], [32, 32, 32, 32]]
+        );
+    }
+
     #[test]
     fn a_small_source_is_never_upscaled() {
         assert_eq!(fit(1000, 600, 1280, 800), (1000, 600));
@@ -1718,6 +2169,9 @@ mod tests {
                 "origin": { "x": 0, "y": 0 },
             }),
             metrics: Arc::new(Mutex::new(Metrics::default())),
+            latest: Arc::new(Mutex::new(None)),
+            capture_error: Arc::new(Mutex::new(None)),
+            frame_changes: tokio::sync::watch::channel(0).1,
             peer: Arc::new(peer),
             encoder: Mutex::new(Encoder::new(64, 64, 1000, 30, 1).expect("an encoder")),
             input: Mutex::new(Some(InputTarget {
@@ -1729,6 +2183,7 @@ mod tests {
                 wheel_rest: (0.0, 0.0),
             })),
             capture: Mutex::new(None),
+            indicator: Mutex::new(None),
             layout: Mutex::new(Layout::from_environment().expect("a keymap")),
             last_seq: Mutex::new(0),
             control_open: AtomicBool::new(true),
@@ -2015,6 +2470,18 @@ mod tests {
         assert_eq!(inner.metrics.lock().unwrap().input_rejected, 2);
     }
 
+    #[tokio::test]
+    async fn a_stopped_capture_never_serves_the_last_frame() {
+        let (events, _) = tokio_mpsc::unbounded_channel();
+        let (mut inner, _) = test_inner(events).await;
+        Arc::get_mut(&mut inner).unwrap().permissions.push(Permission::View);
+        let session = Session { inner };
+        *lock(&session.inner.latest) = Some((1, Instant::now(), 2, 2, vec![0;16], vec![1], vec![]));
+        *lock(&session.inner.capture_error) = Some(String::from("SCStreamErrorDomain -3821"));
+        assert_eq!(session.frame(None, "", None).unwrap_err().code, "stream-stopped");
+        assert_eq!(session.wait_frame(None, None, 10).await.unwrap_err().code, "stream-stopped");
+    }
+
     #[tokio::test]
     async fn a_frame_the_encoder_refuses_ends_the_session_with_a_reason() {
         let (events, mut received) = tokio_mpsc::unbounded_channel();
@@ -2052,6 +2519,33 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn opening_without_view_permission_is_refused_before_capture() {
+        let (events, _received) = tokio_mpsc::unbounded_channel();
+        let result = Session::open(
+            OpenRequest {
+                source: None,
+                permissions: vec![Permission::Control],
+                max_width: 640,
+                max_height: 480,
+                bitrate_kbps: 0,
+                max_fps: 30,
+                ice_servers: Vec::new(),
+                restore_token: None,
+                ttl: None,
+                loopback_tcp: false,
+                agent_indicator: false,
+            },
+            events,
+        )
+        .await;
+        let error = match result {
+            Ok(_) => panic!("a viewless session must not open"),
+            Err(error) => error,
+        };
+        assert_eq!(error.code, "permission");
+    }
+
     #[tokio::test]
     async fn a_lost_transport_releases_input_then_ends_the_session_without_sctp_close() {
         use webrtc::peer_connection::RTCPeerConnectionState as State;