@desklink/host 0.1.0 → 0.2.0

package/engine/src/session.rs

@@ -11,9 +11,11 @@ use crate::convert::{fit, I420};
 use crate::encoder::Encoder;
 use crate::input::{Button, HeldState, InputDevices};
 use crate::keymap::{self, Layout};
-use crate::peer::{PeerEvent, TransportOptions, VideoPeer};
+use crate::peer::{h264_profile_level_id, PeerEvent, TransportOptions, VideoCodec, VideoPeer};
 use crate::portal::{self, SelectedSource};
-use crate::protocol::{ControlMessage, ControlReply, Permission, PointerPhase, SourceRequest};
+use crate::protocol::{
+    ControlMessage, ControlReply, EncodedCodec, Permission, PointerPhase, SourceRequest,
+};
 use crate::x11::X11Desktop;
 use anyhow::Result;
 use std::sync::atomic::{AtomicBool, Ordering};
@@ -59,13 +61,88 @@ pub struct Metrics {
     pub target_kbps: u32,
     pub input_applied: u64,
     pub input_rejected: u64,
+    /// Access units the consumer fed to an encoded source.
+    pub fed_frames: u64,
+    /// Control messages forwarded back to the consumer that owns the device,
+    /// instead of being applied to a desktop this engine holds.
+    pub input_forwarded: 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 +180,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 +215,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 +236,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 +391,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) {
@@ -375,7 +467,7 @@ fn x11_button(button: Button) -> u8 {
     }
 }
 
-fn lock<T>(mutex: &Arc<Mutex<T>>) -> std::sync::MutexGuard<'_, T> {
+fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
     // A poisoned lock means a previous input call panicked while applying; the
     // desktop is then in unknown state, so the session is closed rather than
     // continuing to drive it.
@@ -385,6 +477,7 @@ fn lock<T>(mutex: &Arc<Mutex<T>>) -> std::sync::MutexGuard<'_, T> {
 }
 
 /// Why a session could not do what was asked, in the protocol's own vocabulary.
+#[derive(Debug)]
 pub struct SessionError {
     pub code: &'static str,
     pub message: String,
@@ -412,6 +505,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 +526,26 @@ pub enum SessionEvent {
         transport: String,
         first_frame: bool,
     },
+    Frame {
+        seq: u64,
+        damage: Vec<[usize; 4]>,
+    },
+    /// One control-channel message from the client, for a source whose device
+    /// the consumer drives. The engine applied nothing locally.
+    Input {
+        input: serde_json::Value,
+    },
+    /// The far end needs a fresh reference frame and only the consumer can make
+    /// one: the encoder for this track is on its side. Raised by an RTCP PLI or
+    /// FIR, and once when the transport connects, because everything sent before
+    /// that was dropped.
+    KeyframeRequest {
+        generation: u64,
+    },
     RestoreToken(String),
+    CaptureStopped {
+        reason: String,
+    },
     Revoked {
         reason: String,
     },
@@ -447,6 +560,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,11 +571,21 @@ struct Inner {
     source: SelectedSource,
     geometry: serde_json::Value,
     metrics: Arc<Mutex<Metrics>>,
-    peer: Arc<VideoPeer>,
-    encoder: Mutex<Encoder>,
+    latest: Arc<Mutex<Option<FrameSnapshot>>>,
+    capture_error: Arc<Mutex<Option<String>>>,
+    frame_changes: tokio::sync::watch::Receiver<u64>,
+    /// Built when the codec is known: with `session.open` for a captured
+    /// desktop, and with the first fed access unit for an encoded source, whose
+    /// 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>>,
     input: Mutex<Option<InputTarget>>,
+    indicator: Mutex<Option<crate::indicator::Indicator>>,
     capture: Mutex<Option<FrameSource>>,
-    layout: Mutex<Layout>,
+    /// Absent for an encoded source: there is no local keyboard to translate a
+    /// character through, because the client's keys are forwarded instead.
+    layout: Mutex<Option<Layout>>,
     last_seq: Mutex<u64>,
     control_open: AtomicBool,
     closed: AtomicBool,
@@ -468,18 +593,47 @@ struct Inner {
     /// from the lease as well as from the consumer.
     pipeline: Arc<AtomicBool>,
     events: tokio_mpsc::UnboundedSender<Notice>,
+    /// Present only for an encoded source.
+    encoded: Mutex<Option<Encoded>>,
 }
 
+/// A source whose video arrives already encoded.
+struct Encoded {
+    /// What the consumer said it would feed. Only H.264 exists today; the offer
+    /// is built from this rather than assumed, so a second codec is one arm here.
+    codec: EncodedCodec,
+    /// The transport settings the consumer chose in `session.open`, kept until
+    /// the peer that uses them can be built.
+    transport: TransportOptions,
+    /// Where the peer's events go once it exists.
+    peer_events: tokio_mpsc::UnboundedSender<PeerEvent>,
+    /// Access units waiting to be packetized.
+    feed: tokio_mpsc::Sender<FedAccessUnit>,
+}
+
+/// One access unit a consumer fed, with the keyframe flag it declared.
+struct FedAccessUnit {
+    keyframe: bool,
+    data: Vec<u8>,
+}
+
+/// How many fed access units may wait. A live stream drops the newest rather
+/// than queue: the packetizer is the only consumer, and a backlog of
+/// milliseconds-old pictures is worse than a gap the receiver asks to repair.
+const FEED_BACKLOG: usize = 8;
+
 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"
@@ -534,6 +688,65 @@ pub fn capabilities() -> serde_json::Value {
         },
         "clipboard": { "read": clipboard, "write": clipboard && clipboard::writer_available(), "mime": ["text/plain;charset=utf-8"],
                        "maxBytes": clipboard::MAX_CLIPBOARD_BYTES },
+        // Video this engine does not capture or encode but can carry, so a
+        // consumer can tell an old engine from one that takes `session.feed`
+        // without guessing from a version string.
+        "encoded": { "codecs": ["h264"] },
+    })
+}
+
+#[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 },
+        "encoded": { "codecs": ["h264"] },
     })
 }
 
@@ -542,27 +755,114 @@ impl Session {
         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);
+        // A source the consumer feeds needs no capture backend, no encoder and
+        // no local input device: the device the client drives is the consumer's,
+        // and the offer has to wait for the stream's own SPS.
+        if let Some(SourceRequest::Encoded {
+            codec,
+            width,
+            height,
+        }) = request.source.clone()
+        {
+            return Self::open_encoded(request, codec, width, height, events).await;
+        }
         // 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 +884,23 @@ 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 +912,59 @@ 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 +975,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 +1000,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 +1020,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(),
@@ -675,9 +1056,11 @@ impl Session {
                 pace_bps: (bitrate_kbps as f64 * 3_000.0).max(20_000_000.0),
             },
             peer_events_tx,
+            VideoCodec::Vp9,
         )
         .await
         .map_err(|error| SessionError::new("transport", format!("{error:#}")))?;
+        let peer = Arc::new(peer);
 
         let generation = 1u64;
         let geometry = serde_json::json!({
@@ -694,16 +1077,21 @@ impl Session {
             source,
             geometry,
             metrics,
-            peer: Arc::new(peer),
-            encoder: Mutex::new(encoder),
+            latest,
+            capture_error,
+            frame_changes,
+            peer: Mutex::new(Some(peer.clone())),
+            encoder: Mutex::new(Some(encoder)),
             input: Mutex::new(input),
+            indicator: Mutex::new(indicator),
             capture: Mutex::new(Some(capture)),
-            layout: Mutex::new(layout),
+            layout: Mutex::new(Some(layout)),
             last_seq: Mutex::new(0),
             control_open: AtomicBool::new(false),
             closed: AtomicBool::new(false),
             pipeline: pipeline.clone(),
             events: events.clone(),
+            encoded: Mutex::new(None),
         });
 
         inner.notify(SessionEvent::Description {
@@ -716,13 +1104,140 @@ impl Session {
             first_frame: false,
         });
 
-        spawn_pipeline(&inner, frame_rx, pipeline, request.max_fps, bitrate_kbps);
+        spawn_pipeline(&inner, peer, 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)));
 
         Ok(Self { inner })
     }
 
+    /// Open a session over video the consumer already encoded.
+    ///
+    /// Nothing is captured, encoded or driven locally: the engine packetizes
+    /// what it is fed and sends the client's control messages back to the
+    /// consumer, which owns the device. The peer is deliberately absent here —
+    /// the offer must name the profile-level-id of the stream's own SPS, and
+    /// that only exists once the first access unit arrives.
+    async fn open_encoded(
+        request: OpenRequest,
+        codec: EncodedCodec,
+        width: usize,
+        height: usize,
+        events: tokio_mpsc::UnboundedSender<Notice>,
+    ) -> std::result::Result<Self, SessionError> {
+        if width == 0 || height == 0 || width > 7680 || height > 4320 {
+            return Err(SessionError::new(
+                "source",
+                format!(
+                    "an encoded surface must be 1..7680 by 1..4320 pixels, not {width}x{height}"
+                ),
+            ));
+        }
+        let id = opaque_id();
+        let generation = 1u64;
+        let metrics = Arc::new(Mutex::new(Metrics::default()));
+        // Nothing raises it, and nothing waits for it: an encoded source has no
+        // frame to read, only an encoded stream to forward.
+        let (_frame_signal, frame_changes) = tokio::sync::watch::channel(0u64);
+        let (peer_events, peer_events_rx) = tokio_mpsc::unbounded_channel::<PeerEvent>();
+        let (feed, feed_rx) = tokio_mpsc::channel::<FedAccessUnit>(FEED_BACKLOG);
+        let geometry = serde_json::json!({
+            "source": { "width": width, "height": height },
+            // Nothing is scaled: the client aims at the stream's own pixels, and
+            // the consumer maps them to its device.
+            "encoded": { "width": width, "height": height },
+            "origin": { "x": 0, "y": 0 },
+        });
+        let inner = Arc::new(Inner {
+            id,
+            generation,
+            permissions: request.permissions,
+            source: SelectedSource {
+                node_id: 0,
+                width: width as i32,
+                height: height as i32,
+                position: Some((0, 0)),
+                source_type: Some(String::from("encoded")),
+                origin_x: 0,
+                origin_y: 0,
+            },
+            geometry,
+            metrics,
+            latest: Arc::new(Mutex::new(None)),
+            capture_error: Arc::new(Mutex::new(None)),
+            frame_changes,
+            peer: Mutex::new(None),
+            encoder: Mutex::new(None),
+            input: Mutex::new(None),
+            indicator: Mutex::new(None),
+            capture: Mutex::new(None),
+            layout: Mutex::new(None),
+            last_seq: Mutex::new(0),
+            control_open: AtomicBool::new(false),
+            closed: AtomicBool::new(false),
+            pipeline: Arc::new(AtomicBool::new(false)),
+            events: events.clone(),
+            encoded: Mutex::new(Some(Encoded {
+                codec,
+                transport: TransportOptions {
+                    ice_servers: request.ice_servers,
+                    loopback_tcp: request.loopback_tcp,
+                    // A device stream is a few megabits; pacing exists to spread
+                    // a large frame, not to shape a rate this engine does not set.
+                    pace_bps: 20_000_000.0,
+                },
+                peer_events,
+                feed,
+            })),
+        });
+        inner.notify(SessionEvent::State {
+            capture: "consented",
+            transport: String::from("new"),
+            first_frame: false,
+        });
+        spawn_peer_events(&inner, peer_events_rx);
+        spawn_encoded(&inner, feed_rx);
+        spawn_lease(&inner, request.ttl.unwrap_or(Duration::from_secs(3600)));
+        Ok(Self { inner })
+    }
+
+    /// Take one access unit of an encoded source.
+    ///
+    /// The reply acknowledges the hand-off, not the picture: the unit is
+    /// packetized behind this request, and `session.metrics` reports what was
+    /// sent and what was dropped.
+    pub fn feed(&self, keyframe: bool, data: Vec<u8>) -> std::result::Result<(), SessionError> {
+        if self.inner.closed.load(Ordering::Relaxed) {
+            return Err(SessionError::new("session", "the session has ended"));
+        }
+        let encoded = lock(&self.inner.encoded);
+        let Some(encoded) = encoded.as_ref() else {
+            return Err(SessionError::new(
+                "operation",
+                "this session has no encoded source to feed",
+            ));
+        };
+        if data.is_empty() {
+            return Err(SessionError::new(
+                "operation",
+                "an access unit cannot be empty",
+            ));
+        }
+        if let Ok(mut m) = self.inner.metrics.lock() {
+            m.fed_frames += 1;
+        }
+        if encoded
+            .feed
+            .try_send(FedAccessUnit { keyframe, data })
+            .is_err()
+        {
+            if let Ok(mut m) = self.inner.metrics.lock() {
+                m.dropped_frames += 1;
+            }
+        }
+        Ok(())
+    }
+
     pub fn id(&self) -> &str {
         &self.inner.id
     }
@@ -739,6 +1254,118 @@ 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> {
+        if lock(&self.inner.encoded).is_some() {
+            return Err(SessionError::new(
+                "operation",
+                "this session forwards an encoded stream and keeps no frame",
+            ));
+        }
+        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 lock(&self.inner.encoded).is_some() {
+            return Err(SessionError::new(
+                "operation",
+                "this session forwards an encoded stream and keeps no frame",
+            ));
+        }
+        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
@@ -748,7 +1375,32 @@ impl Session {
     }
 
     pub async fn accept_answer(&self, sdp: String) -> Result<()> {
-        self.inner.peer.accept_answer(sdp).await.map(|_applied| ())
+        self.current_peer()?
+            .accept_answer(sdp)
+            .await
+            .map(|_applied| ())
+    }
+
+    /// The peer for this session, which an encoded source does not have until
+    /// its first access unit has named the codec.
+    fn current_peer(&self) -> Result<Arc<VideoPeer>> {
+        self.inner
+            .peer
+            .lock()
+            .ok()
+            .and_then(|peer| peer.clone())
+            .ok_or_else(|| anyhow::anyhow!("no offer has been made for this session yet"))
+    }
+
+    /// Restart ICE: a fresh offer on the same peer, announced as a new
+    /// `session.description` event for the client to answer as usual.
+    pub async fn restart_ice(&self) -> Result<()> {
+        let offer = self.current_peer()?.restart_ice().await?;
+        self.inner.notify(SessionEvent::Description {
+            generation: self.inner.generation,
+            sdp: offer,
+        });
+        Ok(())
     }
 
     pub async fn add_candidate(
@@ -757,8 +1409,7 @@ impl Session {
         sdp_mid: Option<String>,
         sdp_m_line_index: Option<u16>,
     ) -> Result<()> {
-        self.inner
-            .peer
+        self.current_peer()?
             .add_candidate(candidate, sdp_mid, sdp_m_line_index)
             .await
     }
@@ -819,6 +1470,10 @@ impl Inner {
         }
         self.control_open.store(false, Ordering::SeqCst);
         self.pipeline.store(false, Ordering::SeqCst);
+        drop(lock(&self.encoded).take());
+        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() {
@@ -827,14 +1482,16 @@ impl Inner {
             }
             *input = None;
         }
-        let _ = self
-            .peer
-            .send_control(
-                &serde_json::to_string(&ControlReply::Revoked { reason })
-                    .unwrap_or_else(|_| String::from(r#"{"kind":"revoked","reason":"closed"}"#)),
-            )
-            .await;
-        self.peer.close().await;
+        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"}"#),
+                    ),
+                )
+                .await;
+            peer.close().await;
+        }
         // Dropping the capture stops the PipeWire stream and joins its thread,
         // which is what releases the compositor's consent for this session. It
         // has to happen synchronously, not when the last handle happens to fall
@@ -861,7 +1518,10 @@ impl Inner {
     }
 
     fn clipboard_refusal(&self) -> Option<(&'static str, &'static str)> {
-        if self.source.source_type.as_deref() == Some("x11-root") || !wayland_clipboard_available()
+        if matches!(
+            self.source.source_type.as_deref(),
+            Some("x11-root") | Some("encoded")
+        ) || !wayland_clipboard_available()
         {
             return Some((
                 "clipboard-unsupported",
@@ -884,9 +1544,14 @@ impl Inner {
 
     fn reply(&self, payload: &ControlReply<'_>) -> Result<()> {
         let text = serde_json::to_string(payload)?;
+        let Some(peer) = self.peer.lock().ok().and_then(|peer| peer.clone()) else {
+            // An encoded source has no peer until its first access unit, so a
+            // rejection raised before then has nowhere to go; the request that
+            // caused it is refused in the same breath.
+            return Ok(());
+        };
         // The channel is asynchronous; a failure here means the peer is gone,
         // which the connection-state handler closes anyway.
-        let peer = self.peer.clone();
         tokio::spawn(async move {
             let _ = peer.send_control(&text).await;
         });
@@ -922,6 +1587,30 @@ impl Inner {
             }
             *last = seq;
         }
+        let feedback = match &message {
+            ControlMessage::Pointer { phase, x, y, .. } if lock(&self.encoded).is_none() => {
+                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,
+        };
+        // A source the consumer feeds is a device the consumer drives. Nothing is
+        // applied to this machine: the message travels back as an event, and the
+        // consumer injects it where the picture actually came from.
+        if lock(&self.encoded).is_some() {
+            self.forward(message);
+            return;
+        }
         let outcome = match message {
             ControlMessage::Pointer {
                 phase,
@@ -958,6 +1647,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;
                 }
@@ -967,6 +1663,41 @@ impl Inner {
         }
     }
 
+    /// Hand one client action back to the consumer, which owns the device this
+    /// stream came from. The audit trail is the event itself and the count in
+    /// `session.metrics`; nothing was applied here.
+    fn forward(&self, message: ControlMessage) {
+        let seq = message.seq();
+        // The clipboard belongs to the device the consumer drives, and this
+        // engine has none for this source; saying so is better than a request
+        // that never answers.
+        match &message {
+            ControlMessage::ClipboardRead { request, .. }
+            | ControlMessage::ClipboardWrite { request, .. } => {
+                let _ = self.reply(&ControlReply::Clipboard {
+                    request,
+                    text: String::new(),
+                    truncated: false,
+                    error: Some("this source's clipboard belongs to the consumer"),
+                });
+                return;
+            }
+            _ => {}
+        }
+        let input = match serde_json::to_value(&message) {
+            Ok(input) => input,
+            Err(_) => {
+                self.reject(seq, "operation", "unrecognised control message");
+                return;
+            }
+        };
+        self.notify(SessionEvent::Input { input });
+        if let Ok(mut m) = self.metrics.lock() {
+            m.input_forwarded += 1;
+        }
+        let _ = self.reply(&ControlReply::Ack { seq });
+    }
+
     fn with_input<T>(
         &self,
         action: impl FnOnce(&mut InputTarget) -> Result<T>,
@@ -1043,18 +1774,27 @@ impl Inner {
         }
 
         let stroke = {
-            let layout = self
+            let held = self
                 .layout
                 .lock()
                 .map_err(|_| ("session", String::from("no keyboard layout")))?;
+            let layout = held
+                .as_ref()
+                .ok_or(("session", String::from("no keyboard layout")))?;
             if let Some(name) = name {
                 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 +1820,63 @@ 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 held = self
+                .layout
+                .lock()
+                .map_err(|_| ("session", String::from("no keyboard layout")))?;
+            let layout = held
+                .as_ref()
+                .ok_or(("session", String::from("no keyboard layout")))?;
+            let (plan, unreachable) = layout.plan_text(text);
+            drop(held);
+            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) {
@@ -1331,6 +2092,7 @@ enum Pass {
 /// the desktop goes still the last frame is coded once more, sharp.
 fn spawn_pipeline(
     inner: &Arc<Inner>,
+    peer: Arc<VideoPeer>,
     frame_rx: FrameReceiver,
     running: Arc<AtomicBool>,
     max_fps: u32,
@@ -1359,7 +2121,7 @@ fn spawn_pipeline(
                 let slot = last_sent.map_or(Duration::ZERO, |at| {
                     interval.saturating_sub(now.duration_since(at))
                 });
-                let connected = inner.peer.is_connected();
+                let connected = peer.is_connected();
                 let wait = if !connected {
                     // Nothing sent before the transport connects arrives; the
                     // first frame after it is a key frame.
@@ -1395,15 +2157,17 @@ fn spawn_pipeline(
                 if !running.load(Ordering::Relaxed) {
                     break;
                 }
-                if inner.peer.take_keyframe_request() || !connected {
+                if peer.take_keyframe_request() || !connected {
                     keyframe = true;
                 }
-                let reports = inner.peer.take_loss_reports();
+                let reports = peer.take_loss_reports();
                 if let Some(kbps) = rate.update(&reports, Instant::now()) {
-                    let applied = inner
-                        .encoder
-                        .lock()
-                        .map(|mut encoder| encoder.set_bitrate(kbps));
+                    let applied = inner.encoder.lock().map(|mut encoder| {
+                        encoder
+                            .as_mut()
+                            .map(|encoder| encoder.set_bitrate(kbps))
+                            .unwrap_or(Ok(()))
+                    });
                     if matches!(applied, Ok(Ok(()))) {
                         if let Ok(mut m) = inner.metrics.lock() {
                             m.target_kbps = kbps;
@@ -1434,10 +2198,13 @@ fn spawn_pipeline(
 
                 let started = Instant::now();
                 let packet = {
-                    let mut encoder = match inner.encoder.lock() {
-                        Ok(encoder) => encoder,
+                    let mut held = match inner.encoder.lock() {
+                        Ok(held) => held,
                         Err(_) => break,
                     };
+                    let Some(encoder) = held.as_mut() else {
+                        break;
+                    };
                     match pass {
                         Pass::Motion { keyframe } => encoder.encode(frame, keyframe),
                         Pass::Refine => encoder.refine(frame),
@@ -1488,7 +2255,6 @@ fn spawn_pipeline(
                     Pass::Keepalive => {}
                 }
                 last_sent = Some(now);
-                let peer = inner.peer.clone();
                 if let Err(error) =
                     handle.block_on(peer.send_frame(&packet.data, packet.keyframe, now))
                 {
@@ -1510,6 +2276,113 @@ fn spawn_pipeline(
         .ok();
 }
 
+/// Packetize what a consumer feeds an encoded source, building the peer on the
+/// first access unit that carries an SPS.
+///
+/// That order is forced by the contract: the offer must name the profile the
+/// stream actually is, and the only place that is written down is the stream's
+/// own SPS. Until one arrives there is nothing that could be offered.
+fn spawn_encoded(inner: &Arc<Inner>, mut feed: tokio_mpsc::Receiver<FedAccessUnit>) {
+    let inner = inner.clone();
+    tokio::spawn(async move {
+        while let Some(unit) = feed.recv().await {
+            if inner.closed.load(Ordering::SeqCst) {
+                return;
+            }
+            if current_peer(&inner).is_none() {
+                let Some(profile) = h264_profile_level_id(&unit.data) else {
+                    if let Ok(mut m) = inner.metrics.lock() {
+                        m.dropped_frames += 1;
+                    }
+                    continue;
+                };
+                let (transport, peer_events, codec) = {
+                    let encoded = lock(&inner.encoded);
+                    let Some(encoded) = encoded.as_ref() else {
+                        return;
+                    };
+                    let codec = match encoded.codec {
+                        EncodedCodec::H264 => VideoCodec::H264 {
+                            profile_level_id: profile,
+                        },
+                    };
+                    (
+                        encoded.transport.clone(),
+                        encoded.peer_events.clone(),
+                        codec,
+                    )
+                };
+                let offered = VideoPeer::offer(transport, peer_events, codec).await;
+                match offered {
+                    Ok((peer, offer)) => {
+                        let peer = Arc::new(peer);
+                        let stored = {
+                            let mut held = lock(&inner.peer);
+                            if inner.closed.load(Ordering::SeqCst) {
+                                false
+                            } else {
+                                *held = Some(peer.clone());
+                                true
+                            }
+                        };
+                        if !stored {
+                            peer.close().await;
+                            return;
+                        }
+                        inner.notify(SessionEvent::Description {
+                            generation: inner.generation,
+                            sdp: offer,
+                        });
+                    }
+                    Err(error) => {
+                        revoke(
+                            &inner,
+                            format!("the transport refused the encoded stream: {error:#}"),
+                        )
+                        .await;
+                        return;
+                    }
+                }
+            }
+            let Some(peer) = current_peer(&inner) else {
+                return;
+            };
+            let started = Instant::now();
+            let sent = peer.send_frame(&unit.data, unit.keyframe, started).await;
+            match sent {
+                Ok(()) => {
+                    if let Ok(mut m) = inner.metrics.lock() {
+                        m.encoded_frames += 1;
+                        m.encoded_bytes += unit.data.len() as u64;
+                        m.encode_micros += started.elapsed().as_micros() as u64;
+                        if unit.keyframe {
+                            m.key_frames += 1;
+                        }
+                    }
+                }
+                Err(error) => {
+                    eprintln!("the video track refused a fed access unit: {error:#}");
+                    revoke(&inner, String::from("the connection to the phone was lost")).await;
+                    return;
+                }
+            }
+        }
+    });
+}
+
+fn current_peer(inner: &Arc<Inner>) -> Option<Arc<VideoPeer>> {
+    inner.peer.lock().ok().and_then(|peer| peer.clone())
+}
+
+/// 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) {
+    inner.notify(SessionEvent::Revoked {
+        reason: reason.clone(),
+    });
+    inner.close(&reason).await;
+}
+
 fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiver<PeerEvent>) {
     let inner = inner.clone();
     tokio::spawn(async move {
@@ -1532,6 +2405,16 @@ fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiv
                 }
                 PeerEvent::State(state) => {
                     use webrtc::peer_connection::RTCPeerConnectionState as State;
+                    // The far end needs a reference frame to start from, and only
+                    // the consumer can make one for a stream it encodes. A
+                    // captured desktop manages this in its encode loop; a fed one
+                    // has to ask — and everything sent before the transport
+                    // connected was dropped, so this is not optional.
+                    if lock(&inner.encoded).is_some() && matches!(state, State::Connected) {
+                        inner.notify(SessionEvent::KeyframeRequest {
+                            generation: inner.generation,
+                        });
+                    }
                     // ICE loss need not close SCTP. Never leave a drag or chord
                     // held while waiting for that independent notification.
                     if matches!(state, State::Disconnected | State::Failed | State::Closed) {
@@ -1578,6 +2461,11 @@ fn spawn_peer_events(inner: &Arc<Inner>, mut events: tokio_mpsc::UnboundedReceiv
                         }
                     }
                 }
+                PeerEvent::KeyframeRequest => {
+                    inner.notify(SessionEvent::KeyframeRequest {
+                        generation: inner.generation,
+                    });
+                }
                 PeerEvent::ControlMessage(text) => {
                     match serde_json::from_str::<ControlMessage>(&text) {
                         Ok(message) => inner.apply(message),
@@ -1639,6 +2527,79 @@ fn opaque_id() -> String {
 mod tests {
     use super::*;
 
+    #[tokio::test]
+    async fn a_closed_encoded_session_ends_the_tasks_its_channels_park() {
+        let (events, _received) = tokio_mpsc::unbounded_channel();
+        let (peer_events, peer_events_rx) = tokio_mpsc::unbounded_channel::<PeerEvent>();
+        let (feed, feed_rx) = tokio_mpsc::channel::<FedAccessUnit>(FEED_BACKLOG);
+        let inner = Arc::new(Inner {
+            id: String::from("encoded-session"),
+            generation: 1,
+            permissions: Vec::new(),
+            source: SelectedSource {
+                node_id: 0,
+                width: 640,
+                height: 480,
+                position: None,
+                source_type: Some(String::from("encoded")),
+                origin_x: 0,
+                origin_y: 0,
+            },
+            geometry: serde_json::json!({
+                "source": { "width": 640, "height": 480 },
+                "encoded": { "width": 640, "height": 480 },
+                "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: Mutex::new(None),
+            encoder: Mutex::new(None),
+            input: Mutex::new(None),
+            indicator: Mutex::new(None),
+            capture: Mutex::new(None),
+            layout: Mutex::new(None),
+            last_seq: Mutex::new(0),
+            control_open: AtomicBool::new(false),
+            closed: AtomicBool::new(false),
+            pipeline: Arc::new(AtomicBool::new(false)),
+            events,
+            encoded: Mutex::new(Some(Encoded {
+                codec: EncodedCodec::H264,
+                transport: TransportOptions {
+                    ice_servers: Vec::new(),
+                    loopback_tcp: false,
+                    pace_bps: 20_000_000.0,
+                },
+                peer_events,
+                feed,
+            })),
+        });
+        spawn_peer_events(&inner, peer_events_rx);
+        spawn_encoded(&inner, feed_rx);
+        inner.close("test").await;
+        for _ in 0..100 {
+            if Arc::strong_count(&inner) == 1 {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+        assert_eq!(
+            Arc::strong_count(&inner),
+            1,
+            "closing must end the tasks whose channels the close takes away",
+        );
+    }
+
+    #[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));
@@ -1693,6 +2654,7 @@ mod tests {
                 pace_bps: 20_000_000.0,
             },
             peer_events,
+            VideoCodec::Vp9,
         )
         .await
         .expect("a peer connection builds without a network");
@@ -1718,8 +2680,11 @@ mod tests {
                 "origin": { "x": 0, "y": 0 },
             }),
             metrics: Arc::new(Mutex::new(Metrics::default())),
-            peer: Arc::new(peer),
-            encoder: Mutex::new(Encoder::new(64, 64, 1000, 30, 1).expect("an encoder")),
+            latest: Arc::new(Mutex::new(None)),
+            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"))),
             input: Mutex::new(Some(InputTarget {
                 applier: Applier::Recording(recorded.clone()),
                 held: HeldState::default(),
@@ -1729,12 +2694,14 @@ mod tests {
                 wheel_rest: (0.0, 0.0),
             })),
             capture: Mutex::new(None),
-            layout: Mutex::new(Layout::from_environment().expect("a keymap")),
+            indicator: Mutex::new(None),
+            layout: Mutex::new(Some(Layout::from_environment().expect("a keymap"))),
             last_seq: Mutex::new(0),
             control_open: AtomicBool::new(true),
             closed: AtomicBool::new(false),
             pipeline: Arc::new(AtomicBool::new(true)),
             events,
+            encoded: Mutex::new(None),
         });
         (inner, recorded)
     }
@@ -2015,12 +2982,41 @@ 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();
         let (inner, _recorded) = test_inner(events).await;
         let (frame_tx, frame_rx) = latest_frame();
-        spawn_pipeline(&inner, frame_rx, Arc::new(AtomicBool::new(true)), 30, 1000);
+        spawn_pipeline(
+            &inner,
+            current_peer(&inner).expect("the test's peer"),
+            frame_rx,
+            Arc::new(AtomicBool::new(true)),
+            30,
+            1000,
+        );
 
         // The encoder is 64x64; a 32x32 frame is the dimension mismatch that
         // used to be counted and dropped behind a permanently black picture.
@@ -2052,6 +3048,210 @@ mod tests {
         );
     }
 
+    /// A consumer-fed stream: a keyframe carrying SPS, PPS and an IDR slice.
+    fn fed_keyframe() -> Vec<u8> {
+        let mut stream = vec![0x00, 0x00, 0x00, 0x01];
+        stream.extend_from_slice(&[0x67, 0x42, 0xc0, 0x29, 0x8c, 0x8d]);
+        stream.extend_from_slice(&[0x00, 0x00, 0x01, 0x68, 0xce, 0x3c, 0x80]);
+        stream.extend_from_slice(&[0x00, 0x00, 0x01, 0x65, 0x88, 0x84, 0x00]);
+        stream
+    }
+
+    fn encoded_open() -> OpenRequest {
+        OpenRequest {
+            source: Some(SourceRequest::Encoded {
+                codec: EncodedCodec::H264,
+                width: 486,
+                height: 1080,
+            }),
+            permissions: vec![Permission::View, Permission::Control],
+            max_width: 3840,
+            max_height: 2160,
+            bitrate_kbps: 0,
+            max_fps: 30,
+            ice_servers: Vec::new(),
+            restore_token: None,
+            ttl: Some(Duration::from_secs(30)),
+            loopback_tcp: false,
+            agent_indicator: false,
+        }
+    }
+
+    async fn next_notice(received: &mut tokio_mpsc::UnboundedReceiver<Notice>) -> Notice {
+        tokio::time::timeout(Duration::from_secs(5), received.recv())
+            .await
+            .expect("a notification arrives")
+            .expect("the channel stays open")
+    }
+
+    #[tokio::test]
+    async fn an_encoded_session_opens_without_capture_encoder_or_input() {
+        let (events, _received) = tokio_mpsc::unbounded_channel();
+        let session = Session::open(encoded_open(), events)
+            .await
+            .expect("an encoded source needs no display and no input device");
+        let inner = &session.inner;
+        assert_eq!(session.restore_source(), "encoded");
+        assert_eq!(session.geometry()["encoded"]["width"], 486);
+        assert_eq!(session.geometry()["encoded"]["height"], 1080);
+        assert!(
+            inner.encoder.lock().unwrap().is_none(),
+            "the consumer is the encoder for this source"
+        );
+        assert!(
+            inner.capture.lock().unwrap().is_none(),
+            "there is nothing to capture"
+        );
+        assert!(
+            inner.input.lock().unwrap().is_none(),
+            "the client's input belongs to the consumer's device"
+        );
+        assert!(
+            inner.peer.lock().unwrap().is_none(),
+            "the offer waits for the stream's own SPS"
+        );
+    }
+
+    #[tokio::test]
+    async fn the_offer_for_a_fed_stream_names_that_streams_own_profile() {
+        let (events, mut received) = tokio_mpsc::unbounded_channel();
+        let session = Session::open(encoded_open(), events)
+            .await
+            .expect("an encoded session");
+        let first = next_notice(&mut received).await;
+        assert!(
+            matches!(
+                first.event,
+                SessionEvent::State {
+                    capture: "consented",
+                    ..
+                }
+            ),
+            "the session is open before any offer exists: {:?}",
+            first.event,
+        );
+
+        session
+            .feed(true, fed_keyframe())
+            .expect("a keyframe is taken");
+        let offered = loop {
+            let notice = next_notice(&mut received).await;
+            if let SessionEvent::Description { sdp, .. } = notice.event {
+                break sdp;
+            }
+        };
+        assert!(
+            offered.contains("H264/90000"),
+            "the fed track is offered as H.264: {offered}"
+        );
+        assert!(
+            offered.contains("profile-level-id=42c029"),
+            "the profile-level-id comes from the fed SPS, not a default: {offered}"
+        );
+        assert_eq!(session.metrics().fed_frames, 1);
+    }
+
+    #[tokio::test]
+    async fn a_fed_stream_forwards_its_controls_instead_of_applying_them() {
+        let (events, mut received) = tokio_mpsc::unbounded_channel();
+        let session = Session::open(encoded_open(), events)
+            .await
+            .expect("an encoded session");
+        session.inner.control_open.store(true, Ordering::SeqCst);
+
+        session.inner.apply(ControlMessage::Pointer {
+            phase: PointerPhase::Down,
+            x: 10,
+            y: 20,
+            button: 1,
+            seq: 1,
+        });
+
+        let forwarded = loop {
+            let notice = next_notice(&mut received).await;
+            if let SessionEvent::Input { input } = notice.event {
+                break input;
+            }
+        };
+        assert_eq!(forwarded["kind"], "pointer");
+        assert_eq!(forwarded["phase"], "down");
+        assert_eq!(forwarded["x"], 10);
+        assert_eq!(forwarded["seq"], 1);
+        assert_eq!(session.metrics().input_forwarded, 1);
+        assert_eq!(
+            session.metrics().input_applied,
+            0,
+            "nothing was applied to this machine"
+        );
+
+        // The stream's own coordinates are what travels, so an encoded surface
+        // cannot be driven by a coordinate the far end never rendered.
+        session.inner.apply(ControlMessage::Pointer {
+            phase: PointerPhase::Move,
+            x: 9_000,
+            y: 20,
+            button: 1,
+            seq: 2,
+        });
+        assert_eq!(session.metrics().input_forwarded, 2);
+    }
+
+    #[tokio::test]
+    async fn a_capture_session_refuses_a_fed_stream() {
+        let (events, _received) = tokio_mpsc::unbounded_channel();
+        let (inner, _recorded) = test_inner(events).await;
+        let session = Session { inner };
+        assert_eq!(
+            session.feed(true, fed_keyframe()).unwrap_err().code,
+            "operation",
+            "only an encoded source takes access units",
+        );
+    }
+
+    #[tokio::test]
+    async fn an_encoded_session_has_no_frame_to_read() {
+        let (events, _received) = tokio_mpsc::unbounded_channel();
+        let session = Session::open(encoded_open(), events)
+            .await
+            .expect("an encoded session");
+        assert_eq!(session.frame(None, "", None).unwrap_err().code, "operation");
+        assert_eq!(
+            session.wait_frame(None, None, 10).await.unwrap_err().code,
+            "operation"
+        );
+        assert_eq!(
+            session.read_clipboard().await.unwrap_err(),
+            "clipboard is unavailable for this desktop source",
+        );
+    }
+
+    #[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;
@@ -2108,7 +3308,14 @@ mod tests {
         let (events, _events_rx) = tokio_mpsc::unbounded_channel();
         let (inner, _recorded) = test_inner(events).await;
         let (frame_tx, frame_rx) = latest_frame();
-        spawn_pipeline(&inner, frame_rx, Arc::new(AtomicBool::new(true)), 20, 1000);
+        spawn_pipeline(
+            &inner,
+            current_peer(&inner).expect("the test's peer"),
+            frame_rx,
+            Arc::new(AtomicBool::new(true)),
+            20,
+            1000,
+        );
 
         // 40 frames over 200 ms is 200 fps; the requested 20 fps caps what leaves.
         for _ in 0..40 {