Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): Linux cursor overlay compositing, xrdp-family servers, and resting float (#2940)
Francesco Bonacci997d6d864332
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rsindex 33fafa5f50..ab219f3b0e 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/overlay.rs@@ -5,9 +5,25 @@//! from XComposite. The window covers the full display area.//! - A background thread renders cursor-local tiles at ~60 Hz while animation//! is active and uploads them with XPutImage + XShape clipping.-//! - XShape clips both input and visible pixels. On bare X11, the visible shape-//! quantizes the rendered alpha mask so translucent bloom pixels do not turn-//! into an opaque black disk when no compositor is present.+//! - XShape clips both input and visible pixels. On bare X11 the server never+//! blends our alpha, so the tile is software-composited over a save-under+//! copy of the real desktop backdrop and uploaded opaque; the visible shape+//! stays the alpha≠0 runs, exactly as under a compositor. When the backdrop+//! cannot be read the frame is deferred, and if that persists the shape falls+//! back to quantizing the alpha mask for the session, which keeps the cursor+//! visible at the cost of the translucent bloom.+//! - Software compositing reads the root under each tile. Our own painted+//! pixels would come back with it, so every painted rect is recorded with+//! both the desktop that was under it and the pixels we put on top; a later+//! read of that rect is only treated as desktop once it stops matching what+//! we uploaded. Whenever that record cannot be trusted — a RandR change, a+//! compositing manager arriving or leaving — the overlay blanks itself for a+//! short grace so the windows underneath repaint before it reads again.+//! - Known cost of compositing without a compositor: the alpha≠0 footprint is+//! opaque on screen, so whatever ends up under a *resting* cursor cannot be+//! observed (the server clips those pixels away from their owner) and stays+//! as it was at the last paint until the cursor moves or fades. The cutoff+//! path had the same limitation over the smaller alpha≥128 silhouette.//! - Z-ordering: `XRaiseWindow` every 80ms to stay above normal windows.//! - Wayland: when WAYLAND_DISPLAY is set but DISPLAY is also available (XWayland),//! the X11 path is used. Pure Wayland support is a TODO.@@ -19,6 +35,8 @@//! What stays here is the X11 window plumbing: connection setup,//! override-redirect visual, ShapeInput passthrough, and the XPutImage paint.+#[cfg(target_os = "linux")]+use std::collections::VecDeque;use std::collections::{HashMap, HashSet};use std::sync::{Mutex, OnceLock};#[cfg(target_os = "linux")]@@ -28,6 +46,11 @@ use std::time::{Duration, Instant};use cursor_overlay::CursorAction;#[cfg(target_os = "linux")]const X11_EVENT_POLL_INTERVAL: Duration = Duration::from_millis(50);+/// How often the `_NET_WM_CM_S{n}` owner is re-sampled. A compositing manager+/// starting or stopping emits no event we subscribe to, and it decides whether+/// the server blends our alpha, so the sample cannot be startup-only.+#[cfg(target_os = "linux")]+const X11_COMPOSITOR_POLL_INTERVAL: Duration = Duration::from_secs(1);#[cfg(target_os = "linux")]use cursor_overlay::ZOrderEnforcer;@@ -566,6 +589,17 @@ impl RenderState {|| self.core.spring.is_some()|| self.core.click_t.is_some()|| self.core.session_badge_needs_frame_tick()+ // The resting float bob (`shared_float_motion`) is part of the+ // cursor's visual identity, not a transient animation: it runs+ // whenever the cursor is on screen and reduced motion is off, so+ // a settled cursor must keep receiving frames or the bob freezes+ // mid-swing on Linux while macOS keeps levitating. The term dies+ // with `idle_alpha` once the idle fade completes, returning the+ // parked-overlay fast path to the fully hidden cursor.+ || (self.core.visible+ && self.core.pos.0 >= -100.0+ && self.core.idle_alpha >= 0.004+ && self.core.visual.reduced_motion != cursor_overlay::ReducedMotion::On)|| (self.core.motion.idle_hide_ms > 0.0&& self.core.visible&& self.core.pos.0 >= -100.0@@ -974,6 +1008,49 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMscolormap};+ // An ARGB visual is only worth having when a compositing manager will+ // blend it; the compositor-less path renders pre-blended opaque pixels+ // behind a shape mask and needs no alpha channel. It is also actively+ // hazardous on servers that accept an ARGB32 window but cannot show it —+ // xorgxrdp repaints shaped ARGB regions as solid black whenever its+ // refresh re-renders them, and answers root reads inside them with black,+ // which both blanks the cursor on screen and poisons every save-under+ // comparison into compositing the shadow over black. Those servers are+ // exactly the compositor-less ones, so the rule is simple: no compositor+ // at startup, no ARGB. `software_only` pins the software-composited path+ // for the session — a compositing manager appearing later blends the+ // opaque shaped window correctly, whereas switching paths would hand this+ // 24-bit window premultiplied translucent pixels it cannot represent.+ let (visual_id, depth, colormap, software_only) =+ if compositor_present || visual_id == screen.root_visual {+ (visual_id, depth, colormap, false)+ } else {+ conn.free_colormap(colormap).ok();+ tracing::debug!(+ "X11 overlay: no compositor at startup; using the root visual \+ with software compositing"+ );+ (+ screen.root_visual,+ screen.root_depth,+ screen.default_colormap,+ true,+ )+ };+ // Belt and braces for servers whose root reads are unreliable even for+ // the visual chosen above: `resolve_backdrop` stops treating a readback+ // mismatch as proof of a repaint.+ let readback_untrusted = !x11_visual_readback_reliable(+ &conn,+ root,+ visual_id,+ depth,+ colormap,+ scr_w as u16,+ scr_h as u16,+ )+ .unwrap_or(false);+// Create the overlay window.let win = conn.generate_id().unwrap();let win_aux = CreateWindowAux::new()@@ -1040,6 +1117,12 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMstracing::warn!("X11 overlay: cannot create graphics context: {e}");return;}+ let paint_target = X11PaintTarget {+ win,+ root,+ depth,+ gc_id,+ };// Render at ~60 Hz only while pixels can change. Quiescent cursors use// bounded channel waits so X11/RandR events are serviced without repainting;@@ -1051,6 +1134,26 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMslet mut frame_tick_needed = false;let mut maintenance_deadline = last_tick + X11_EVENT_POLL_INTERVAL;let mut last_pinned: Option<u64> = None;+ let mut last_compositor_poll = last_tick;+ // Constructed after the geometry query and the window map, so the cache can+ // never be primed against a placeholder geometry. This window has painted+ // nothing yet and its bounding shape is still empty, so its first root read+ // sees no pixels of ours. (A previous overlay instance torn down moments+ // earlier can still be on screen; that resolves itself as soon as the+ // cursor vacates the rect and its owner repaints.)+ let mut backdrop = X11BackdropCache::default();+ // Startup probe result; a property of the server, not of the compositor,+ // so it is never re-sampled when a compositing manager comes or goes.+ backdrop.readback_untrusted = readback_untrusted;+ if readback_untrusted {+ tracing::warn!(+ "X11 overlay: root reads cannot see this window's own pixels; \+ save-unders will be served without readback confirmation"+ );+ }+ // Arrivals resolve callers waiting for the destination frame to be visible,+ // so they are held back across a deferred paint instead of firing early.+ let mut pending_arrivals: Vec<CursorKey> = Vec::new();let z_enforcer = X11ZOrderEnforcer { conn: &conn, win };loop {@@ -1091,9 +1194,16 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMstracing::warn!("X11 overlay geometry repair failed; disabling overlay: {e}");break;}+ // Every saved backdrop describes the pre-resize screen. The repair+ // above emptied our bounding shape, but that only queues Expose:+ // the framebuffer still holds our last frame until the windows+ // underneath repaint it, so stay blank for the resync grace instead+ // of reading our own pixels back as desktop.+ backdrop.resync(Instant::now());#[cfg(test)]X11_RANDR_REPAIR_COUNT.fetch_add(1, std::sync::atomic::Ordering::SeqCst);compositor_present = x11_compositor_present(&conn, screen_num);+ last_compositor_poll = Instant::now();tracing::debug!(width = geometry.0,height = geometry.1,@@ -1105,6 +1215,27 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMsNone};+ // A compositing manager can start or stop without any RandR event, and+ // it decides which pixel policy is correct: with one present the server+ // blends our alpha and a root read no longer sees the windows below us.+ // Poll the selection owner rather than let a stale sample pick the path.+ let compositor_changed = if last_compositor_poll.elapsed() >= X11_COMPOSITOR_POLL_INTERVAL {+ last_compositor_poll = Instant::now();+ let present = x11_compositor_present(&conn, screen_num);+ let changed = present != compositor_present;+ if changed {+ compositor_present = present;+ // Same reasoning as the RandR repair: what we already painted is+ // still on screen, so blank and let it be repainted before the+ // next root read (and repaint now that the policy changed).+ backdrop.resync(Instant::now());+ tracing::debug!(compositor_present, "X11 overlay compositor state changed");+ }+ changed+ } else {+ false+ };+let now = Instant::now();let elapsed_dt = now.duration_since(last_tick).as_secs_f64();last_tick = now;@@ -1176,13 +1307,26 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMslast_ztick.elapsed() >= z_order_interval,) {last_ztick = Instant::now();+ // Deliberately does not invalidate the backdrop cache. Restacking+ // *us* does not change what is beneath us, and invalidating here+ // would force a fresh read inside our own silhouette every 80 ms.+ // If a window did draw over us before we raised again, the next+ // root read no longer matches the pixels we uploaded there, so+ // `resolve_backdrop` drops the save-under for those pixels on its+ // own rather than serving a backdrop that is no longer under us.z_enforcer.reassert(pinned_wid);}// Render after a command, during an active animation/fade, and once// more as the final active state settles. This leaves the X11 window in// its completed/cleared state before the next blocking receive.- if had_msg || screen_changed || hover_changed || frame_tick_needed || next_frame_tick_needed+ let mut paint_deferred = false;+ if had_msg+ || screen_changed+ || compositor_changed+ || hover_changed+ || frame_tick_needed+ || next_frame_tick_needed{let tiles = {let guard = RENDER.lock().unwrap();@@ -1190,31 +1334,43 @@ fn run_overlay_thread(cfg: CursorConfig, rx: std::sync::mpsc::Receiver<OverlayMs};if let Some(tiles) = tiles {- if let Err(e) = paint_x11_tiles(+ match paint_x11_tiles(&conn,- win,- depth,- gc_id,+ &paint_target,&tiles,- compositor_present,+ // A `software_only` window is 24-bit: handing the+ // compositor branch premultiplied translucent pixels would+ // display them as opaque dark artifacts, so the downgrade+ // pins the software-composited path for the session.+ compositor_present && !software_only,screen_changed,+ &mut backdrop,) {- // A broken X11 connection cannot recover inside this- // owner thread. Exit instead of spinning at frame cadence- // and repeatedly allocating/rendering work nobody can see.- tracing::warn!("X11 overlay paint failed; disabling overlay: {e}");- break;+ Ok(outcome) => paint_deferred = outcome == X11PaintOutcome::Deferred,+ Err(e) => {+ // A broken X11 connection cannot recover inside this+ // owner thread. Exit instead of spinning at frame cadence+ // and repeatedly allocating/rendering work nobody can see.+ tracing::warn!("X11 overlay paint failed; disabling overlay: {e}");+ break;+ }}}}// Preserve the original ordering: callers waiting on arrival only- // resume after the destination frame has reached the X11 window.- for key in &arrived {- arrival_fire(key);+ // resume after the destination frame has reached the X11 window. A+ // deferred paint has not reached it yet, so they wait for the retry.+ pending_arrivals.extend(arrived);+ if !paint_deferred {+ for key in pending_arrivals.drain(..) {+ arrival_fire(&key);+ }}- frame_tick_needed = next_frame_tick_needed;+ // A deferred frame is still owed to the window: keep ticking so it is+ // retried instead of leaving a stale cursor until the next command.+ frame_tick_needed = next_frame_tick_needed || paint_deferred;maintenance_deadline = next_maintenance_deadline(last_tick,last_ztick,@@ -1352,6 +1508,464 @@ struct X11PaintTile {pixmap: tiny_skia::Pixmap,}+/// Loop-constant X11 handles the paint path needs. Bundled so the per-frame+/// paint entry point keeps a reviewable argument list as the compositing+/// inputs grow.+#[cfg(target_os = "linux")]+struct X11PaintTarget {+ win: u32,+ root: u32,+ depth: u8,+ gc_id: u32,+}++/// One rect of screen the overlay painted over: the desktop pixels that were+/// under it, and the pixels we actually put on top of them. Both are row-major+/// BGRX, `width * height * 4` bytes, exactly as XGetImage returns a ZPixmap+/// from the root.+///+/// The pair is what makes readback decidable. A later root read of the same+/// rect is still our own paint when it equals `uploaded`, in which case the+/// true backdrop is `under`; once it differs, the window that owns those pixels+/// has serviced its Expose and the live read is the truth again.+#[cfg(target_os = "linux")]+struct X11SavedBackdrop {+ bounds: X11TileBounds,+ under: Vec<u8>,+ uploaded: Vec<u8>,+}++/// One painted frame: the root-space rects the overlay actually made visible,+/// and the save-unders covering them.+#[cfg(target_os = "linux")]+struct X11BackdropFrame {+ /// When a later frame superseded this one. `None` while the frame is the+ /// one on screen, which can never be read back as backdrop.+ vacated_at: Option<Instant>,+ painted: Vec<x11rb::protocol::xproto::Rectangle>,+ saved: Vec<X11SavedBackdrop>,+}++#[cfg(target_os = "linux")]+impl X11BackdropFrame {+ /// A vacated frame is dropped once its save-unders are old enough that+ /// serving them would be worse than reading whatever is there now. Nothing+ /// about correctness rides on the exact value: while the frame is retained,+ /// `resolve_backdrop` still prefers the live read for every pixel its owner+ /// has repainted.+ fn expired(&self, now: Instant) -> bool {+ match self.vacated_at {+ None => self.painted.is_empty(),+ Some(vacated) => now.duration_since(vacated) > X11_BACKDROP_RETENTION,+ }+ }+}++/// Save-unders for compositor-less software blending. Without a compositing+/// manager the server never blends our alpha, so we blend against the real+/// backdrop ourselves. XGetImage on the root returns our own painted pixels+/// wherever the overlay is currently shaped in, so those pixels are served from+/// here instead and everything else keeps the live read.+#[cfg(target_os = "linux")]+#[derive(Default)]+struct X11BackdropCache {+ /// Newest frame at the front.+ frames: VecDeque<X11BackdropFrame>,+ /// Set while the overlay must stay blank so the windows it uncovered can+ /// service their Expose before the next root read.+ resync_until: Option<Instant>,+ /// Whether the blanking shape for the current resync has been sent.+ resync_blanked: bool,+ slow_reads: u8,+ unbacked_frames: u8,+ disabled: bool,+ /// Set when the startup probe found that a root `GetImage` inside the+ /// overlay's own shaped-in footprint does not return the pixels we+ /// uploaded (xorgxrdp answers black there for a 32-bit ARGB child on a+ /// 24-bit root). On such a server the readback comparison in+ /// `resolve_backdrop` can never confirm our paint survived, so mismatches+ /// inside a save-under serve the saved backdrop instead of adopting the+ /// unreadable live pixels — compositing each frame over those drives a+ /// translucent shadow geometrically to black.+ readback_untrusted: bool,+}++/// After the cache is dropped wholesale — a display change, a compositing+/// manager appearing or leaving — nothing is left to tell our own pixels apart+/// from the desktop, so the overlay blanks itself for this long and lets the+/// windows underneath repaint before it reads the root again. Emptying the+/// bounding shape only queues Expose; the framebuffer still physically holds+/// our last frame until the owning clients answer it.+#[cfg(target_os = "linux")]+const X11_BACKDROP_RESYNC_GRACE: Duration = Duration::from_millis(200);+/// How long a vacated frame's save-under stays available. Long is safe:+/// `resolve_backdrop` only uses it for pixels that still hold our own paint.+#[cfg(target_os = "linux")]+const X11_BACKDROP_RETENTION: Duration = Duration::from_secs(2);+/// Memory ceiling on retained frames, ~2.3 MB per cursor at the largest badged+/// tile. This is what actually bounds the history during continuous motion:+/// 32 frames is roughly half a second at the 60 Hz frame budget.+#[cfg(target_os = "linux")]+const X11_BACKDROP_MAX_FRAMES: usize = 32;+/// A frame's whole root read (one round trip, all tiles) must fit well inside+/// the 16 ms frame budget.+#[cfg(target_os = "linux")]+const X11_BACKDROP_READ_BUDGET: Duration = Duration::from_millis(8);+/// Consecutive over-budget frames that latch software compositing off.+#[cfg(target_os = "linux")]+const X11_BACKDROP_SLOW_READ_LIMIT: u8 = 3;+/// Consecutive frames the overlay may hold still waiting for a usable backdrop+/// before compositing is latched off for the session. Three frames is ~50 ms of+/// frozen cursor, which is cheaper than either painting a tile we cannot+/// account for or losing translucency to a single transient X11 error.+#[cfg(target_os = "linux")]+const X11_BACKDROP_UNBACKED_FRAME_LIMIT: u8 = 3;++/// Software compositing is compositor-less only, and only until a slow server+/// latches it off. Split out so the hard constraint — a compositing manager+/// changes nothing about this path — is locked by a test.+#[cfg(target_os = "linux")]+fn backdrop_compositing_enabled(compositor_present: bool, cache: &X11BackdropCache) -> bool {+ !compositor_present && cache.enabled()+}++/// Intersect a root-space rect with a tile, returning tile-local+/// `(x0, y0, x1, y1)` half-open bounds, or `None` when they do not overlap.+#[cfg(target_os = "linux")]+fn clip_to_tile(+ bounds: X11TileBounds,+ x: i32,+ y: i32,+ width: i32,+ height: i32,+) -> Option<(usize, usize, usize, usize)> {+ let bx = i32::from(bounds.x);+ let by = i32::from(bounds.y);+ let x0 = x.max(bx);+ let y0 = y.max(by);+ let x1 = (x + width).min(bx + i32::from(bounds.width));+ let y1 = (y + height).min(by + i32::from(bounds.height));+ if x1 <= x0 || y1 <= y0 {+ return None;+ }+ Some((+ (x0 - bx) as usize,+ (y0 - by) as usize,+ (x1 - bx) as usize,+ (y1 - by) as usize,+ ))+}++/// Tile-local half-open bounding box of a shape, or `None` when it is empty.+#[cfg(target_os = "linux")]+fn shape_bounding_box(+ shape: &[x11rb::protocol::xproto::Rectangle],+) -> Option<(usize, usize, usize, usize)> {+ let mut bbox: Option<(usize, usize, usize, usize)> = None;+ for rect in shape {+ if rect.width == 0 || rect.height == 0 {+ continue;+ }+ let x0 = rect.x.max(0) as usize;+ let y0 = rect.y.max(0) as usize;+ let x1 = x0 + usize::from(rect.width);+ let y1 = y0 + usize::from(rect.height);+ bbox = Some(match bbox {+ None => (x0, y0, x1, y1),+ Some((bx0, by0, bx1, by1)) => (bx0.min(x0), by0.min(y0), bx1.max(x1), by1.max(y1)),+ });+ }+ bbox+}++/// Copy the `(x0, y0, x1, y1)` sub-rect out of a tile-sized BGRX buffer. Only+/// the painted bounding box is ever consulted later, so save-unders store that+/// instead of the whole tile.+#[cfg(target_os = "linux")]+fn crop_tile_pixels(+ pixels: &[u8],+ tile_width: usize,+ (x0, y0, x1, y1): (usize, usize, usize, usize),+) -> Vec<u8> {+ let mut out = Vec::with_capacity((x1 - x0) * (y1 - y0) * 4);+ for row in y0..y1 {+ let start = (row * tile_width + x0) * 4;+ out.extend_from_slice(&pixels[start..start + (x1 - x0) * 4]);+ }+ out+}++#[cfg(target_os = "linux")]+impl X11BackdropCache {+ fn enabled(&self) -> bool {+ !self.disabled+ }++ fn disable(&mut self, reason: &'static str) {+ if self.disabled {+ return;+ }+ self.disabled = true;+ self.frames.clear();+ self.resync_until = None;+ tracing::warn!(+ reason,+ "X11 overlay: falling back to the alpha-cutoff cursor shape for this session"+ );+ }++ /// Latch compositing off after repeated over-budget root reads. A loaded VM+ /// must not pay an unbounded XGetImage round trip every frame forever; the+ /// overlay falls back to the alpha-cutoff path for the rest of the session.+ fn note_read_duration(&mut self, elapsed: Duration) {+ if self.disabled {+ return;+ }+ if elapsed <= X11_BACKDROP_READ_BUDGET {+ self.slow_reads = 0;+ return;+ }+ self.slow_reads = self.slow_reads.saturating_add(1);+ if self.slow_reads >= X11_BACKDROP_SLOW_READ_LIMIT {+ self.disable("root backdrop reads exceed the frame budget");+ }+ }++ /// Record a frame the overlay could not composite. The frame is not painted+ /// at all — painting the cutoff tile instead would make pixels visible that+ /// no save-under can explain, and every later frame overlapping them would+ /// fail for the same reason, latching the cutoff look in silently. Returns+ /// `true` once the failures have persisted long enough that compositing is+ /// latched off and the caller should paint the cutoff tile after all.+ fn note_unbacked_frame(&mut self) -> bool {+ if self.disabled {+ // Already latched off — most likely by the slow-read budget during+ // this very frame. Nothing is owed to the cache; paint the cutoff+ // tile now instead of holding a frame back for nothing.+ return true;+ }+ self.unbacked_frames = self.unbacked_frames.saturating_add(1);+ if self.unbacked_frames < X11_BACKDROP_UNBACKED_FRAME_LIMIT {+ return false;+ }+ self.disable("the root backdrop could not be read for several frames");+ true+ }++ fn note_composited_frame(&mut self) {+ self.unbacked_frames = 0;+ }++ /// Drop every save-under without blanking. Only correct where nothing of+ /// ours is on screen to be read back — the compositing-manager path, which+ /// never paints an opaque tile in the first place.+ fn invalidate(&mut self) {+ self.frames.clear();+ }++ /// Drop every save-under and blank the overlay for the resync grace. Used+ /// when the screen the save-unders describe stops being the screen we are+ /// painting on: a RandR geometry change, or a compositing manager arriving+ /// or leaving.+ fn resync(&mut self, now: Instant) {+ self.frames.clear();+ self.resync_until = Some(now + X11_BACKDROP_RESYNC_GRACE);+ self.resync_blanked = false;+ }++ /// Whether painting is still suppressed. Clears the state once the grace+ /// has elapsed so the next frame reads a root nobody has our pixels on.+ fn resyncing(&mut self, now: Instant) -> bool {+ match self.resync_until {+ Some(deadline) if now < deadline => true,+ Some(_) => {+ self.resync_until = None;+ self.resync_blanked = false;+ false+ }+ None => false,+ }+ }++ /// Whether the caller still has to blank the bounding shape for this+ /// resync. Answering `true` once per resync keeps the wait from re-sending+ /// a shape the server already has.+ fn take_resync_blanking(&mut self) -> bool {+ if self.resync_blanked {+ return false;+ }+ self.resync_blanked = true;+ true+ }++ /// Retire frames that are too old to be worth keeping and cap memory. The+ /// on-screen frame is pinned while it has painted rects: those pixels are+ /// what the server is displaying right now.+ fn prune(&mut self, now: Instant) {+ while self.frames.len() > X11_BACKDROP_MAX_FRAMES {+ self.frames.pop_back();+ }+ while let Some(frame) = self.frames.back() {+ if !frame.expired(now) {+ break;+ }+ self.frames.pop_back();+ }+ }++ fn record_frame(+ &mut self,+ at: Instant,+ painted: Vec<x11rb::protocol::xproto::Rectangle>,+ saved: Vec<X11SavedBackdrop>,+ ) {+ // The frame that was on screen is only vacated now, not when it was+ // painted: a cursor that rested for a minute still leaves its pixels+ // behind for the owning client to repaint after it finally moves.+ if let Some(previous) = self.frames.front_mut() {+ previous.vacated_at.get_or_insert(at);+ }+ self.frames.push_front(X11BackdropFrame {+ vacated_at: None,+ painted,+ saved,+ });+ self.prune(at);+ }++ /// Build the true backdrop for `bounds` out of a live root read plus the+ /// save-unders.+ ///+ /// A pixel the overlay painted is only served from a save-under while the+ /// live read still matches the pixels we uploaded there; as soon as the+ /// owning window repaints, the live read wins again. That check is what+ /// keeps a cursor ghost from being blended in and re-saved frame after+ /// frame, and it needs no assumption about how fast a client answers+ /// Expose.+ ///+ /// Returns `None` when a painted pixel has no save-under at all, so callers+ /// fail closed instead of compositing against pixels that may be our own.+ fn resolve_backdrop(+ &self,+ now: Instant,+ bounds: X11TileBounds,+ fresh: &[u8],+ ) -> Option<Vec<u8>> {+ if self.disabled {+ return None;+ }+ let width = usize::from(bounds.width);+ let height = usize::from(bounds.height);+ let pixels = width.checked_mul(height)?;+ if pixels == 0 || fresh.len() != pixels * 4 {+ return None;+ }++ let mut out = fresh.to_vec();+ // `decided` is the running answer for the whole tile; `pending` is the+ // mask of pixels the frame in hand painted and still owes an answer+ // for. Newest frame first, so the most recent paint over a pixel is the+ // one its live value is compared against.+ let mut decided = vec![false; pixels];+ let mut pending = vec![false; pixels];+ for frame in &self.frames {+ if frame.expired(now) {+ continue;+ }+ let mut painted: Option<(usize, usize, usize, usize)> = None;+ for rect in &frame.painted {+ let Some(clip) = clip_to_tile(+ bounds,+ i32::from(rect.x),+ i32::from(rect.y),+ i32::from(rect.width),+ i32::from(rect.height),+ ) else {+ continue;+ };+ let (x0, y0, x1, y1) = clip;+ for row in y0..y1 {+ pending[row * width + x0..row * width + x1].fill(true);+ }+ painted = Some(match painted {+ None => clip,+ Some((px0, py0, px1, py1)) => {+ (px0.min(x0), py0.min(y0), px1.max(x1), py1.max(y1))+ }+ });+ }+ let Some((bx0, by0, bx1, by1)) = painted else {+ continue;+ };++ for saved in &frame.saved {+ let Some((x0, y0, x1, y1)) = clip_to_tile(+ bounds,+ i32::from(saved.bounds.x),+ i32::from(saved.bounds.y),+ i32::from(saved.bounds.width),+ i32::from(saved.bounds.height),+ ) else {+ continue;+ };+ let saved_width = usize::from(saved.bounds.width);+ let expected = saved_width * usize::from(saved.bounds.height) * 4;+ if saved.under.len() != expected || saved.uploaded.len() != expected {+ continue;+ }+ let dx = i32::from(bounds.x) - i32::from(saved.bounds.x);+ let dy = i32::from(bounds.y) - i32::from(saved.bounds.y);+ for row in y0..y1 {+ let saved_row = (row as i32 + dy) as usize;+ for col in x0..x1 {+ let index = row * width + col;+ if decided[index] || !pending[index] {+ continue;+ }+ let saved_col = (col as i32 + dx) as usize;+ let src = (saved_row * saved_width + saved_col) * 4;+ let dst = index * 4;+ // Compare colour only: the fourth byte is an unused pad+ // in the root read and a forced 255 in what we upload.+ // On a server whose root reads cannot see our own+ // window (`readback_untrusted`) the comparison carries+ // no information — the live pixel is unreadable, not+ // repainted — so the save-under is served regardless.+ // The cost is that a genuine repaint under the cursor+ // goes unnoticed until the save-under expires.+ if self.readback_untrusted+ || fresh[dst..dst + 3] == saved.uploaded[src..src + 3]+ {+ out[dst..dst + 4].copy_from_slice(&saved.under[src..src + 4]);+ }+ decided[index] = true;+ }+ }+ }++ // Clear this frame's mask, and fail closed on any pixel it painted+ // that no save-under covers: trusting the live read there would+ // blend our own cursor in as if it were desktop. Every painted rect+ // of a composited frame lies inside one of its save-unders, so this+ // only trips on a frame recorded without one.+ let mut unbacked = false;+ for row in by0..by1 {+ for col in bx0..bx1 {+ let index = row * width + col;+ if pending[index] {+ unbacked |= !decided[index];+ pending[index] = false;+ }+ }+ }+ if unbacked {+ return None;+ }+ }+ Some(out)+ }+}+#[cfg(target_os = "linux")]fn cursor_tile_bounds(core: &RenderStateCore,@@ -1407,7 +2021,9 @@ fn render_x11_tiles(map: &RenderMap) -> Vec<X11PaintTile> {let mut pixmap = tiny_skia::Pixmap::new(bounds.width.into(), bounds.height.into())?;// Paint every cursor into every intersecting tile. tiny-skia clips// automatically, so overlapping cursor tiles carry the same- // composite pixels regardless of upload order.+ // composite pixels regardless of upload order — and identical+ // backdrops, because every root read for a frame is issued before+ // any upload.for rs in map.cursors.values() {cursor_overlay::paint_cursor(&mut pixmap,@@ -1430,80 +2046,516 @@ fn render_x11_tiles(map: &RenderMap) -> Vec<X11PaintTile> {#[cfg(target_os = "linux")]const NONCOMPOSITED_ALPHA_CUTOFF: u8 = 128;+/// Read the true desktop pixels under every tile of one frame.+///+/// All cookies are issued before any reply is collected, so the whole frame+/// costs one round trip regardless of tile count. Callers must invoke this+/// before the first `put_image` of the frame: that ordering is what lets+/// overlapping tiles read the same pre-frame screen instead of each other's+/// freshly uploaded pixels.+///+/// A failed or unexpected read fails the whole frame. Compositing some tiles+/// and not others would upload two different pixel policies into one bounding+/// shape, so the frame is deferred (or, eventually, compositing is latched off)+/// as a unit.#[cfg(target_os = "linux")]-fn paint_x11_tiles(+fn read_root_backdrops(conn: &impl x11rb::connection::Connection,- win: u32,- depth: u8,- gc_id: u32,+ root: u32,tiles: &[X11PaintTile],- compositor_present: bool,- checked_requests: bool,-) -> anyhow::Result<()> {- use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};+ backdrop: &mut X11BackdropCache,+) -> Option<Vec<Vec<u8>>> {use x11rb::protocol::xproto::{ConnectionExt as XprotoConnectionExt, ImageFormat};- let mut payloads = Vec::with_capacity(tiles.len());- let mut visible_shape = Vec::new();- for tile in tiles {- let (bgra, mut tile_shape) = bgra_and_visible_shape(&tile.pixmap, compositor_present);- for rect in &mut tile_shape {- rect.x = rect.x.saturating_add(tile.bounds.x);- rect.y = rect.y.saturating_add(tile.bounds.y);- }- visible_shape.extend(tile_shape);- payloads.push((tile.bounds, bgra));- }+ // Tiles are pre-clamped to the screen by `cursor_tile_bounds`, so the rect+ // is in bounds by construction; a stale-geometry race after RandR simply+ // errors out into the deferral below.+ let cookies: Vec<_> = tiles+ .iter()+ .map(|tile| {+ let bounds = tile.bounds;+ conn.get_image(+ ImageFormat::Z_PIXMAP,+ root,+ bounds.x,+ bounds.y,+ bounds.width,+ bounds.height,+ !0u32,+ )+ .ok()+ })+ .collect();- for (bounds, bgra) in payloads {- let cookie = conn.put_image(+ let started = Instant::now();+ let reads: Option<Vec<Vec<u8>>> = cookies+ .into_iter()+ .zip(tiles)+ .map(|(cookie, tile)| {+ let reply = cookie?.reply().ok()?;+ let expected = usize::from(tile.bounds.width) * usize::from(tile.bounds.height) * 4;+ // Same BGRX/4-byte assumption the screen capture path decodes with;+ // anything else is a read failure, not a format to guess at. It is+ // also what makes the readback comparison in `resolve_backdrop`+ // meaningful: an 8-bit-per-channel root returns exactly the bytes+ // we uploaded.+ if !matches!(reply.depth, 24 | 32) || reply.data.len() != expected {+ return None;+ }+ Some(reply.data)+ })+ .collect();+ backdrop.note_read_duration(started.elapsed());+ reads+}++/// Whether this server can genuinely display a window of the given visual and+/// fold it into root `GetImage` reads. Both halves of the compositor-less+/// overlay ride on that: PutImage must reach the screen and *stay* there+/// (xorgxrdp repaints a 32-bit ARGB child as solid black on its 24-bit root+/// whenever the region is refreshed), and `resolve_backdrop` decides "still+/// our paint" versus "someone repainted over us" by comparing a later root+/// read against the uploaded bytes — a comparison that misfires on every+/// pixel when the read returns black instead.+///+/// Probed once per candidate visual at startup with a throwaway window that+/// mirrors the real overlay as closely as possible — full-screen,+/// override-redirect, bounding-shaped down to a 4×1 strip at the origin —+/// because the failure is not visible to a simpler probe: xorgxrdp serves a+/// small unshaped ARGB window's pixels back faithfully and only blacks out+/// shaped regions of a large one when its refresh re-renders them. Map,+/// shape, upload the strip, read it back off the root twice (immediately,+/// and again after the server has had time to reprocess the damage),+/// destroy. The round trip through `get_image` orders the reply after the+/// map and upload on this connection, so no separate sync is needed. Errors+/// report as unreliable: a server that cannot service this exchange cannot+/// service the per-frame paint either.+#[cfg(target_os = "linux")]+fn x11_visual_readback_reliable(+ conn: &impl x11rb::connection::Connection,+ root: u32,+ visual_id: u32,+ depth: u8,+ colormap: u32,+ scr_w: u16,+ scr_h: u16,+) -> anyhow::Result<bool> {+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};+ use x11rb::protocol::xproto::{+ ClipOrdering, ConnectionExt as XprotoConnectionExt, CreateGCAux, CreateWindowAux,+ EventMask, ImageFormat, Rectangle, WindowClass,+ };++ const PROBE_WIDTH: u16 = 4;+ // Distinctive opaque colours a desktop corner is unlikely to hold.+ let uploaded: Vec<u8> = (0..u32::from(PROBE_WIDTH))+ .flat_map(|i| {+ let i = i as u8;+ [+ 0x35_u8.wrapping_add(i.wrapping_mul(7)),+ 0x8C_u8.wrapping_sub(i.wrapping_mul(11)),+ 0x5A_u8.wrapping_add(i.wrapping_mul(23)),+ 0xFF,+ ]+ })+ .collect();++ let win = conn.generate_id()?;+ conn.create_window(+ depth,+ win,+ root,+ 0,+ 0,+ scr_w.max(PROBE_WIDTH),+ scr_h.max(1),+ 0,+ WindowClass::INPUT_OUTPUT,+ visual_id,+ &CreateWindowAux::new()+ .background_pixel(0)+ .border_pixel(0)+ .colormap(colormap)+ .override_redirect(1u32)+ .event_mask(EventMask::NO_EVENT),+ )?;+ let probe = (|| -> anyhow::Result<bool> {+ let gc = conn.generate_id()?;+ conn.create_gc(gc, win, &CreateGCAux::new())?;+ // Shape before mapping so only the probe strip ever shows, exactly as+ // the real overlay exposes only its painted runs.+ conn.shape_rectangles(+ SO::SET,+ SK::BOUNDING,+ ClipOrdering::UNSORTED,+ win,+ 0,+ 0,+ &[Rectangle {+ x: 0,+ y: 0,+ width: PROBE_WIDTH,+ height: 1,+ }],+ )?;+ conn.shape_rectangles(SO::SET, SK::INPUT, ClipOrdering::UNSORTED, win, 0, 0, &[])?;+ conn.map_window(win)?;+ conn.put_image(ImageFormat::Z_PIXMAP,win,- gc_id,- bounds.width,- bounds.height,- bounds.x,- bounds.y,+ gc,+ PROBE_WIDTH,+ 1,+ 0,+ 0,0,depth,- &bgra,+ &uploaded,)?;- if checked_requests {- cookie.check()?;+ // Two reads: the first is ordered right behind the upload on this+ // connection and catches servers that never see the pixels at all;+ // the second runs after a pause long enough for a deferred-refresh+ // server to reprocess the damage. xorgxrdp passes the first read —+ // the bytes are still in its shadow framebuffer — and only blacks+ // the region out when its update timer re-renders it from the window+ // tree, so an immediate-only probe would wrongly bless the visual.+ let matches_upload = |reply: &x11rb::protocol::xproto::GetImageReply| {+ // Colour only: the fourth byte is an unused pad in the root read.+ matches!(reply.depth, 24 | 32)+ && reply.data.len() == uploaded.len()+ && uploaded+ .chunks_exact(4)+ .zip(reply.data.chunks_exact(4))+ .all(|(ours, live)| ours[..3] == live[..3])+ };+ for pause in [None, Some(Duration::from_millis(80))] {+ if let Some(pause) = pause {+ std::thread::sleep(pause);+ }+ let reply = conn+ .get_image(ImageFormat::Z_PIXMAP, root, 0, 0, PROBE_WIDTH, 1, !0u32)?+ .reply()?;+ if !matches_upload(&reply) {+ conn.free_gc(gc)?;+ return Ok(false);+ }}- }+ conn.free_gc(gc)?;+ Ok(true)+ })();+ // Destroy on every exit so a failed probe cannot leave a stray mapped+ // window at the origin.+ conn.destroy_window(win).ok();+ conn.flush().ok();+ probe+}- // Keep the previous (or fail-closed empty) shape while uploading pixels,- // then expose only the freshly rendered alpha runs. This ordering prevents- // stale/zero-filled backing pixels from becoming visible during repair.- let shape_cookie = conn.shape_rectangles(+/// A composited tile: its bounds, the opaque pixels to upload, the tile-local+/// visible shape, and the backdrop they were blended over.+#[cfg(target_os = "linux")]+type X11CompositedTile = (+ X11TileBounds,+ Vec<u8>,+ Vec<x11rb::protocol::xproto::Rectangle>,+ Vec<u8>,+);++/// Compose every tile of a frame, or none of it.+#[cfg(target_os = "linux")]+fn composite_x11_tiles(+ now: Instant,+ tiles: &[X11PaintTile],+ fresh: &[Vec<u8>],+ backdrop: &X11BackdropCache,+) -> Option<Vec<X11CompositedTile>> {+ tiles+ .iter()+ .zip(fresh)+ .map(|(tile, fresh)| {+ let under = backdrop.resolve_backdrop(now, tile.bounds, fresh)?;+ let (bgra, shape) = composited_bgra_and_visible_shape(&tile.pixmap, &under)?;+ Some((tile.bounds, bgra, shape, under))+ })+ .collect()+}++/// Hide every overlay pixel. Used while a resync waits for the windows we+/// uncovered to repaint: the wait is only useful if we are not painting.+#[cfg(target_os = "linux")]+fn blank_x11_overlay_shape(+ conn: &impl x11rb::connection::Connection,+ win: u32,+ checked_requests: bool,+) -> anyhow::Result<()> {+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};+ use x11rb::protocol::xproto::ClipOrdering;++ let cookie = conn.shape_rectangles(SO::SET,SK::BOUNDING,- x11rb::protocol::xproto::ClipOrdering::UNSORTED,+ ClipOrdering::UNSORTED,win,0,0,- &visible_shape,+ &[],)?;if checked_requests {- shape_cookie.check()?;+ cookie.check()?;}-conn.flush()?;Ok(())}+/// Whether the rendered frame reached the X11 window. `Deferred` means the+/// overlay deliberately left the previous frame on screen because it could not+/// account for the pixels this one would cover; the caller must retry on the+/// next frame tick rather than treating the state as settled.#[cfg(target_os = "linux")]-fn bgra_and_visible_shape(- pm: &tiny_skia::Pixmap,- compositor_present: bool,-) -> (Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>) {- use x11rb::protocol::xproto::Rectangle;+#[derive(Clone, Copy, Debug, Eq, PartialEq)]+enum X11PaintOutcome {+ Painted,+ Deferred,+}- let width = pm.width() as usize;- let height = pm.height() as usize;- let src = pm.data();- let mut bgra = Vec::with_capacity(src.len());+#[cfg(target_os = "linux")]+fn paint_x11_tiles(+ conn: &impl x11rb::connection::Connection,+ target: &X11PaintTarget,+ tiles: &[X11PaintTile],+ compositor_present: bool,+ checked_requests: bool,+ backdrop: &mut X11BackdropCache,+) -> anyhow::Result<X11PaintOutcome> {+ use x11rb::protocol::shape::{ConnectionExt as ShapeConnectionExt, SK, SO};+ use x11rb::protocol::xproto::{ConnectionExt as XprotoConnectionExt, ImageFormat};++ // Phase A — decide, then read every root rect before any pixel is uploaded.+ // Under a compositing manager no root read is issued, no record is written+ // and the cache stays empty: that path is exactly what it was before.+ let now = Instant::now();+ let compositing_available = backdrop_compositing_enabled(compositor_present, backdrop);+ if compositing_available {+ // Retire stale save-unders before they can be consumed, not after.+ backdrop.prune(now);+ } else {+ backdrop.invalidate();+ }++ let mut payloads = Vec::with_capacity(tiles.len());+ let mut visible_shape = Vec::new();+ let mut saved = Vec::new();+ let mut composited = false;++ // Phase B — assemble the true backdrop per tile and blend, or hold the+ // previous frame until we can.+ if compositing_available && !tiles.is_empty() {+ if backdrop.resyncing(now) {+ // Nothing left describes what is under us. Stay invisible until the+ // windows we uncovered have answered their Expose; painting now+ // would recontaminate the region we are waiting on and bake our own+ // cursor into the first save-under.+ if backdrop.take_resync_blanking() {+ blank_x11_overlay_shape(conn, target.win, checked_requests)?;+ }+ return Ok(X11PaintOutcome::Deferred);+ }++ match read_root_backdrops(conn, target.root, tiles, backdrop)+ .and_then(|fresh| composite_x11_tiles(now, tiles, &fresh, backdrop))+ {+ Some(frame) => {+ composited = true;+ backdrop.note_composited_frame();+ for (bounds, bgra, mut tile_shape, under) in frame {+ // Only the painted bounding box is ever consulted again, so+ // that is all the frame keeps.+ if let Some(bbox) = shape_bounding_box(&tile_shape) {+ let width = usize::from(bounds.width);+ saved.push(X11SavedBackdrop {+ bounds: X11TileBounds {+ x: bounds.x.saturating_add(bbox.0 as i16),+ y: bounds.y.saturating_add(bbox.1 as i16),+ width: (bbox.2 - bbox.0) as u16,+ height: (bbox.3 - bbox.1) as u16,+ },+ under: crop_tile_pixels(&under, width, bbox),+ uploaded: crop_tile_pixels(&bgra, width, bbox),+ });+ }+ for rect in &mut tile_shape {+ rect.x = rect.x.saturating_add(bounds.x);+ rect.y = rect.y.saturating_add(bounds.y);+ }+ visible_shape.extend(tile_shape);+ payloads.push((bounds, bgra));+ }+ }+ // Hold the previous frame rather than paint pixels no save-under+ // can explain: doing that once guarantees the next frame fails the+ // same way, which is how a single transient X11 error would+ // otherwise latch the cutoff look in for the session. Once the+ // failures persist, compositing is latched off deliberately and+ // this frame paints the cutoff tile after all.+ None if !backdrop.note_unbacked_frame() => {+ return Ok(X11PaintOutcome::Deferred);+ }+ None => {}+ }+ }++ if !composited {+ for tile in tiles {+ let (bgra, mut tile_shape) = bgra_and_visible_shape(&tile.pixmap, compositor_present);+ for rect in &mut tile_shape {+ rect.x = rect.x.saturating_add(tile.bounds.x);+ rect.y = rect.y.saturating_add(tile.bounds.y);+ }+ visible_shape.extend(tile_shape);+ payloads.push((tile.bounds, bgra));+ }+ }++ // Phase C — expose the new shape, then upload into it. The order matters+ // and is the reverse of what it once was: output to a window is CLIPPED to+ // its current bounding shape, so uploading first silently discards every+ // pixel of the frame's frontier — the runs the new shape adds over the old+ // one — and enlarging the shape afterwards exposes the window's zero+ // backing there instead. On an ARGB window zero is transparent and the+ // loss was invisible, but it left the frontier unreadable to the+ // save-under readback (adopting black as backdrop, which composites the+ // shadow into a hard black ring), and on a 24-bit window zero shows as+ // literal black. Shaping first means the frontier briefly exposes zero+ // backing server-side, but both requests travel in one batch ahead of a+ // single flush, so no frame with the bare frontier is ever presented.+ let shape_cookie = conn.shape_rectangles(+ SO::SET,+ SK::BOUNDING,+ x11rb::protocol::xproto::ClipOrdering::UNSORTED,+ target.win,+ 0,+ 0,+ &visible_shape,+ )?;+ if checked_requests {+ shape_cookie.check()?;+ }++ // Phase D — upload. A composited buffer covers the whole tile rect; pixels+ // outside the shape are the backdrop copied back and are never displayed.+ for (bounds, bgra) in payloads {+ let cookie = conn.put_image(+ ImageFormat::Z_PIXMAP,+ target.win,+ target.gc_id,+ bounds.width,+ bounds.height,+ bounds.x,+ bounds.y,+ 0,+ target.depth,+ &bgra,+ )?;+ if checked_requests {+ cookie.check()?;+ }+ }++ conn.flush()?;++ // Phase E — record what actually landed, after the flush succeeded. The+ // rects are exactly what we SET, so the contamination record is truthful. A+ // clearing paint (no tiles) records an empty frame, which vacates the frame+ // that was on screen without discarding its save-unders: the trail it left+ // is still there until its owners repaint it.+ if compositing_available && backdrop.enabled() && (composited || tiles.is_empty()) {+ backdrop.record_frame(Instant::now(), visible_shape, saved);+ }+ Ok(X11PaintOutcome::Painted)+}++/// Software-composite a premultiplied cursor tile over the real backdrop under+/// it. Without a compositing manager the server never blends our alpha, so we+/// blend here and upload opaque pixels: translucent bloom and antialiased edges+/// survive instead of being quantized to XShape's one bit of visibility. The+/// visible region is still the α≠0 runs, exactly as on the compositing path —+/// at the shape boundary α≈0, so the blended pixel is the backdrop and the+/// 1-bit edge is invisible.+///+/// `backdrop` is a tile-sized row-major BGRX buffer as XGetImage returns it for+/// the root. Returns `None` when it does not match the tile so callers fail+/// closed onto the alpha-cutoff path rather than uploading a guess.+#[cfg(target_os = "linux")]+fn composited_bgra_and_visible_shape(+ pm: &tiny_skia::Pixmap,+ backdrop: &[u8],+) -> Option<(Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>)> {+ use x11rb::protocol::xproto::Rectangle;++ let width = pm.width() as usize;+ let height = pm.height() as usize;+ let src = pm.data();+ if backdrop.len() != src.len() || backdrop.len() != width * height * 4 {+ return None;+ }++ let mut bgra = Vec::with_capacity(src.len());+ let mut rectangles = Vec::new();++ for y in 0..height {+ let mut run_start = None;+ for x in 0..width {+ let offset = (y * width + x) * 4;+ let pixel = &src[offset..offset + 4];+ let under = &backdrop[offset..offset + 4];+ let alpha = pixel[3];+ let inverse = 255 - u32::from(alpha);+ // Premultiplied source over an opaque backdrop; the result is+ // opaque, so alpha carries no information the server has to blend.+ let over = |source: u8, back: u8| {+ source.saturating_add(((u32::from(back) * inverse + 127) / 255) as u8)+ };+ bgra.extend_from_slice(&[+ over(pixel[2], under[0]),+ over(pixel[1], under[1]),+ over(pixel[0], under[2]),+ 255,+ ]);++ if alpha != 0 {+ run_start.get_or_insert(x);+ } else if let Some(start) = run_start.take() {+ rectangles.push(Rectangle {+ x: start as i16,+ y: y as i16,+ width: (x - start) as u16,+ height: 1,+ });+ }+ }+ if let Some(start) = run_start {+ rectangles.push(Rectangle {+ x: start as i16,+ y: y as i16,+ width: (width - start) as u16,+ height: 1,+ });+ }+ }++ Some((bgra, rectangles))+}++#[cfg(target_os = "linux")]+fn bgra_and_visible_shape(+ pm: &tiny_skia::Pixmap,+ compositor_present: bool,+) -> (Vec<u8>, Vec<x11rb::protocol::xproto::Rectangle>) {+ use x11rb::protocol::xproto::Rectangle;++ let width = pm.width() as usize;+ let height = pm.height() as usize;+ let src = pm.data();+ let mut bgra = Vec::with_capacity(src.len());let mut rectangles = Vec::new();for y in 0..height {@@ -2277,23 +3329,45 @@ mod tests {assert!(!render_map_needs_z_order_tick(&map));}+ // The idle-park contract now applies to reduced-motion sessions: with the+ // float bob active (the default), a visible cursor keeps ticking so it+ // levitates at rest, and only a hidden or reduced-motion cursor parks.#[test]fn resting_visible_cursor_only_requires_cheap_z_order_ticks() {let mut map = default_render_map();let cursor = map.cursors.get_mut("default").unwrap();cursor.core.pos = (100.0, 100.0);cursor.core.motion.idle_hide_ms = 0.0;+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;assert!(!render_map_needs_frame_tick(&map));assert!(render_map_needs_z_order_tick(&map));}+ #[test]+ fn resting_visible_cursor_keeps_ticking_for_the_float_bob() {+ let mut map = default_render_map();+ let cursor = map.cursors.get_mut("default").unwrap();+ cursor.core.pos = (100.0, 100.0);+ cursor.core.motion.idle_hide_ms = 0.0;++ // Default reduced_motion (auto) floats, so frames keep flowing while+ // the cursor is visible…+ assert!(render_map_needs_frame_tick(&map));++ // …and stop once the idle fade has fully hidden it.+ let cursor = map.cursors.get_mut("default").unwrap();+ cursor.core.idle_alpha = 0.0;+ assert!(!render_map_needs_frame_tick(&map));+ }+#[test]fn disabling_settled_cursor_clears_once_then_parks() {let mut map = default_render_map();let cursor = map.cursors.get_mut("default").unwrap();cursor.core.pos = (100.0, 100.0);cursor.core.motion.idle_hide_ms = 0.0;+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;let (_tx, rx) = std::sync::mpsc::channel();assert!(!render_map_needs_frame_tick(&map));@@ -2340,6 +3414,7 @@ mod tests {// before sending MoveTo; mirror that valid on-screen starting state.cursor.core.pos = (100.0, 100.0);cursor.core.motion.idle_hide_ms = 500.0;+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;cursor.apply_command(OverlayCommand::MoveTo {x: 250.0,y: 150.0,@@ -2511,6 +3586,7 @@ mod tests {let cursor = map.cursors.get_mut("default").unwrap();cursor.core.pos = (100.0, 100.0);cursor.core.motion.idle_hide_ms = 500.0;+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;// Cheap 80 ms z-order heartbeats advance the idle clock without// requesting expensive frame paints during the opaque delay.@@ -2553,6 +3629,7 @@ mod tests {let mut map = default_render_map();let cursor = map.cursors.get_mut("default").unwrap();cursor.core.motion.idle_hide_ms = 0.0;+ cursor.core.visual.reduced_motion = cursor_overlay::ReducedMotion::On;cursor.apply_command(OverlayCommand::ClickPulse { x: 20.0, y: 30.0 });assert!(cursor.needs_frame_tick());@@ -2697,6 +3774,8 @@ mod tests {);}+ /// Golden for the documented fallback: whenever the real backdrop cannot be+ /// read (or a compositor is present), tiles still paint exactly like this.#[test]fn compositorless_shape_drops_bloom_and_unpremultiplies_visible_pixels() {let mut pixmap = tiny_skia::Pixmap::new(4, 1).unwrap();@@ -2716,6 +3795,738 @@ mod tests {(1, 0, 3));}++ // ── Save-unders / software compositing ───────────────────────────────++ /// 4×1 premultiplied cursor strip with alphas 0 / 64 / 180 / 255.+ fn composite_test_pixmap() -> tiny_skia::Pixmap {+ let mut pixmap = tiny_skia::Pixmap::new(4, 1).unwrap();+ pixmap.data_mut().copy_from_slice(&[+ 0, 0, 0, 0, // transparent+ 32, 16, 8, 64, // faint bloom+ 180, 90, 45, 180, // translucent body+ 200, 100, 50, 255, // opaque core+ ]);+ pixmap+ }++ /// Matching BGRX root read: four distinct opaque desktop pixels.+ fn composite_test_backdrop() -> Vec<u8> {+ vec![+ 10, 20, 30, 255, //+ 40, 50, 60, 255, //+ 70, 80, 90, 255, //+ 100, 110, 120, 255,+ ]+ }++ fn tile_bounds(x: i16, y: i16, width: u16, height: u16) -> X11TileBounds {+ X11TileBounds {+ x,+ y,+ width,+ height,+ }+ }++ fn painted_rect(x: i16, y: i16, width: u16, height: u16) -> x11rb::protocol::xproto::Rectangle {+ x11rb::protocol::xproto::Rectangle {+ x,+ y,+ width,+ height,+ }+ }++ #[test]+ fn composited_tile_blends_translucent_pixels_over_the_backdrop() {+ let pixmap = composite_test_pixmap();+ let backdrop = composite_test_backdrop();++ let (bgra, _) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();++ assert_eq!(&bgra[0..4], &[10, 20, 30, 255]);+ assert_eq!(&bgra[4..8], &[38, 53, 77, 255]);+ assert_eq!(&bgra[8..12], &[66, 114, 206, 255]);+ assert_eq!(&bgra[12..16], &[50, 100, 200, 255]);+ // Every uploaded pixel is opaque: the server has nothing left to blend.+ assert!(bgra.chunks_exact(4).all(|pixel| pixel[3] == 255));+ }++ #[test]+ fn composited_tile_reproduces_the_backdrop_where_the_cursor_is_transparent() {+ let pixmap = composite_test_pixmap();+ let backdrop = composite_test_backdrop();++ let (bgra, _) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();++ assert_eq!(&bgra[0..3], &backdrop[0..3]);+ }++ #[test]+ fn composited_tile_output_depends_on_the_backdrop() {+ let pixmap = composite_test_pixmap();++ let (over_white, _) = composited_bgra_and_visible_shape(&pixmap, &[0xFF; 16]).unwrap();+ let (over_black, _) = composited_bgra_and_visible_shape(&pixmap, &[0x00; 16]).unwrap();++ assert_ne!(&over_white[4..8], &over_black[4..8]);+ assert_ne!(&over_white[8..12], &over_black[8..12]);+ // The opaque core hides whatever is beneath it.+ assert_eq!(&over_white[12..16], &over_black[12..16]);+ }++ #[test]+ fn composited_tile_keeps_the_bloom_the_cutoff_path_drops() {+ let pixmap = composite_test_pixmap();+ let backdrop = composite_test_backdrop();++ let (_, cutoff_shape) = bgra_and_visible_shape(&pixmap, false);+ let (bgra, shape) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();++ // The alpha=64 bloom pixel sits at x=1: the cutoff path shapes it away.+ assert!(cutoff_shape.iter().all(|rect| rect.x > 1));+ assert!(shape+ .iter()+ .any(|rect| rect.x <= 1 && i32::from(rect.x) + i32::from(rect.width) > 1));+ // ...and its colour lands strictly between the backdrop and the+ // unpremultiplied source instead of being forced to either end.+ let unpremultiplied = [8u32 * 255 / 64, 16 * 255 / 64, 32 * 255 / 64];+ for (channel, source) in unpremultiplied.iter().enumerate() {+ let out = u32::from(bgra[4 + channel]);+ let back = u32::from(backdrop[4 + channel]);+ assert!(+ out > back.min(*source) && out < back.max(*source),+ "channel {channel}: {out} is not between {back} and {source}"+ );+ }+ }++ #[test]+ fn composited_tile_shape_matches_the_compositing_path() {+ let pixmap = composite_test_pixmap();+ let backdrop = composite_test_backdrop();++ let (_, compositing_shape) = bgra_and_visible_shape(&pixmap, true);+ let (_, composited_shape) = composited_bgra_and_visible_shape(&pixmap, &backdrop).unwrap();++ let as_tuples = |rects: Vec<x11rb::protocol::xproto::Rectangle>| {+ rects+ .into_iter()+ .map(|rect| (rect.x, rect.y, rect.width, rect.height))+ .collect::<Vec<_>>()+ };+ assert_eq!(as_tuples(compositing_shape), as_tuples(composited_shape));+ }++ #[test]+ fn composited_tile_rejects_a_mismatched_backdrop() {+ let pixmap = composite_test_pixmap();++ assert!(composited_bgra_and_visible_shape(&pixmap, &[0u8; 12]).is_none());+ assert!(composited_bgra_and_visible_shape(&pixmap, &[0u8; 20]).is_none());+ }++ /// A save-under as the paint path records one: the desktop that was under+ /// the rect, and the pixels the overlay put on top of it.+ fn saved_backdrop(+ bounds: X11TileBounds,+ under: Vec<u8>,+ uploaded: Vec<u8>,+ ) -> X11SavedBackdrop {+ X11SavedBackdrop {+ bounds,+ under,+ uploaded,+ }+ }++ #[test]+ fn saved_backdrop_serves_pixels_the_overlay_painted_last_frame() {+ let tile = tile_bounds(0, 0, 4, 1);+ let desktop: Vec<u8> = (0u8..16).collect();+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ cache.record_frame(+ now,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, desktop.clone(), vec![0xAA; 16])],+ );++ // 0xAA is what the overlay uploaded, so a root read that still returns+ // it is our own paint rather than desktop.+ let out = cache.resolve_backdrop(now, tile, &[0xAA; 16]).unwrap();++ assert_eq!(&out[0..8], &desktop[0..8]);+ assert_eq!(&out[8..16], &[0xAA; 8]);+ }++ #[test]+ fn a_repainted_pixel_is_read_live_even_inside_the_painted_rect() {+ let tile = tile_bounds(0, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ cache.record_frame(+ now,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );++ // The owner answered its Expose: the first pixel no longer holds what+ // we uploaded, so the live read is the truth and the stale save-under+ // must not be served.+ let mut live = vec![0xAAu8; 16];+ live[0..4].copy_from_slice(&[0x77, 0x77, 0x77, 0xFF]);+ let out = cache.resolve_backdrop(now, tile, &live).unwrap();++ assert_eq!(&out[0..4], &[0x77, 0x77, 0x77, 0xFF]);+ assert_eq!(&out[4..8], &[0x11; 4]);+ }++ /// The halo regression: on a server whose root reads return black inside+ /// our own footprint (xorgxrdp + ARGB32 overlay), the mismatch must serve+ /// the save-under, not adopt the unreadable black — compositing each frame+ /// over the last otherwise drives a translucent shadow to solid black.+ #[test]+ fn untrusted_readback_serves_the_save_under_on_mismatch() {+ let tile = tile_bounds(0, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ cache.readback_untrusted = true;+ let now = Instant::now();+ cache.record_frame(+ now,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );++ // Live read is black where we painted — unreadable, not repainted.+ let mut live = vec![0xAAu8; 16];+ live[0..8].fill(0x00);+ let out = cache.resolve_backdrop(now, tile, &live).unwrap();++ // Both painted pixels come from the save-under; the unpainted rest of+ // the tile keeps the live read.+ assert_eq!(&out[0..8], &[0x11; 8]);+ assert_eq!(&out[8..16], &[0xAA; 8]);+ }++ #[test]+ fn readback_comparison_ignores_the_unused_fourth_byte() {+ let tile = tile_bounds(0, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ // The overlay uploads alpha=255; a depth-24 root read pads with zero.+ let uploaded: Vec<u8> = (0..4).flat_map(|_| [0x20, 0x30, 0x40, 0xFF]).collect();+ let live: Vec<u8> = (0..4).flat_map(|_| [0x20, 0x30, 0x40, 0x00]).collect();+ cache.record_frame(+ now,+ vec![painted_rect(0, 0, 4, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], uploaded)],+ );++ assert_eq!(+ cache.resolve_backdrop(now, tile, &live).unwrap(),+ vec![0x11; 16]+ );+ }++ #[test]+ fn moving_cursor_reads_only_newly_exposed_pixels_from_the_root() {+ let first = tile_bounds(0, 0, 4, 1);+ let second = tile_bounds(2, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();++ // Frame 1: empty cache, the whole tile is read live.+ let desktop: Vec<u8> = (1u8..17).collect();+ assert_eq!(+ cache.resolve_backdrop(now, first, &desktop).unwrap(),+ desktop+ );+ cache.record_frame(+ now,+ vec![painted_rect(1, 0, 2, 1)],+ vec![saved_backdrop(first, desktop.clone(), vec![0xAA; 16])],+ );++ // Frame 2: the shifted tile. 0xAA marks everything the root read would+ // hand back, including our own frame-1 pixels.+ let out = cache.resolve_backdrop(now, second, &[0xAA; 16]).unwrap();++ // x=2 was inside frame 1's shape and still holds our pixels → served+ // from the save-under.+ assert_eq!(&out[0..4], &desktop[8..12]);+ // x=3 was inside frame 1's tile but outside its shape → read live.+ assert_eq!(&out[4..8], &[0xAA; 4]);+ // x=4,5 are the newly exposed band → read live.+ assert_eq!(&out[8..16], &[0xAA; 8]);+ }++ #[test]+ fn badge_expansion_reads_the_new_side_strips_from_the_root() {+ let narrow = tile_bounds(136, 0, 128, 1);+ let widened = tile_bounds(96, 0, 208, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ cache.record_frame(+ now,+ vec![painted_rect(136, 0, 128, 1)],+ vec![saved_backdrop(+ narrow,+ vec![0x33; 128 * 4],+ vec![0xAA; 128 * 4],+ )],+ );++ let out = cache+ .resolve_backdrop(now, widened, &vec![0xAA; 208 * 4])+ .unwrap();++ assert_eq!(&out[0..40 * 4], &vec![0xAA; 40 * 4][..]);+ assert_eq!(&out[40 * 4..168 * 4], &vec![0x33; 128 * 4][..]);+ assert_eq!(&out[168 * 4..208 * 4], &vec![0xAA; 40 * 4][..]);+ }++ #[test]+ fn resolving_fails_when_a_painted_pixel_has_no_saved_backdrop() {+ let tile = tile_bounds(0, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ cache.record_frame(now, vec![painted_rect(0, 0, 2, 1)], Vec::new());++ assert!(cache.resolve_backdrop(now, tile, &[0xAA; 16]).is_none());+ }++ #[test]+ fn a_frame_is_vacated_when_it_is_superseded_not_when_it_was_painted() {+ let tile = tile_bounds(0, 0, 4, 1);+ let elsewhere = tile_bounds(8, 0, 4, 1);+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();+ cache.record_frame(+ start,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );++ // The cursor rests for five seconds, then moves. The old frame's pixels+ // were vacated just now, so the window under them has not repainted yet+ // and the save-under has to survive the next few frames.+ let moved = start + Duration::from_secs(5);+ for step in 0..3 {+ cache.record_frame(+ moved + Duration::from_millis(16 * step),+ vec![painted_rect(8, 0, 2, 1)],+ vec![saved_backdrop(elsewhere, vec![0x22; 16], vec![0xAA; 16])],+ );+ }++ let out = cache+ .resolve_backdrop(moved + Duration::from_millis(48), tile, &[0xAA; 16])+ .unwrap();+ assert_eq!(&out[0..8], &[0x11; 8]);+ }++ #[test]+ fn a_long_vacated_frame_stops_being_consulted_without_waiting_for_a_prune() {+ let tile = tile_bounds(0, 0, 4, 1);+ let elsewhere = tile_bounds(8, 0, 4, 1);+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();+ cache.record_frame(+ start,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );+ cache.record_frame(+ start + Duration::from_millis(16),+ vec![painted_rect(8, 0, 2, 1)],+ vec![saved_backdrop(elsewhere, vec![0x22; 16], vec![0xAA; 16])],+ );++ // Nothing painted for a long while, so nothing pruned either: expiry is+ // applied where the save-unders are consumed.+ let later = start + X11_BACKDROP_RETENTION + Duration::from_secs(1);+ assert_eq!(+ cache.resolve_backdrop(later, tile, &[0xAA; 16]).unwrap(),+ vec![0xAA; 16]+ );+ }++ #[test]+ fn pruning_keeps_the_frame_that_is_still_on_screen() {+ let start = Instant::now();+ let mut visible = X11BackdropCache::default();+ visible.record_frame(+ start,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(+ tile_bounds(0, 0, 4, 1),+ vec![0x11; 16],+ vec![0xAA; 16],+ )],+ );+ visible.prune(start + Duration::from_secs(10));+ assert_eq!(visible.frames.len(), 1);++ let mut cleared = X11BackdropCache::default();+ cleared.record_frame(start, Vec::new(), Vec::new());+ cleared.prune(start + Duration::from_secs(10));+ assert!(cleared.frames.is_empty());+ }++ #[test]+ fn a_clearing_paint_vacates_the_frame_it_replaces_without_dropping_it() {+ let tile = tile_bounds(0, 0, 4, 1);+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();+ cache.record_frame(+ start,+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );+ // The cursor faded out: the tile is cleared, but the trail it leaves is+ // still on screen until its owner repaints it.+ cache.record_frame(start + Duration::from_millis(16), Vec::new(), Vec::new());++ let out = cache+ .resolve_backdrop(start + Duration::from_millis(32), tile, &[0xAA; 16])+ .unwrap();+ assert_eq!(&out[0..8], &[0x11; 8]);+ }++ #[test]+ fn retained_frames_are_capped() {+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();+ for step in 0..(X11_BACKDROP_MAX_FRAMES + 8) {+ cache.record_frame(+ start + Duration::from_millis(16 * step as u64),+ vec![painted_rect(0, 0, 2, 1)],+ vec![saved_backdrop(+ tile_bounds(0, 0, 4, 1),+ vec![0x11; 16],+ vec![0xAA; 16],+ )],+ );+ }++ assert_eq!(cache.frames.len(), X11_BACKDROP_MAX_FRAMES);+ }++ #[test]+ fn invalidate_drops_every_saved_backdrop() {+ let tile = tile_bounds(0, 0, 4, 1);+ let mut cache = X11BackdropCache::default();+ let now = Instant::now();+ cache.record_frame(+ now,+ vec![painted_rect(0, 0, 4, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );++ cache.invalidate();++ assert_eq!(+ cache.resolve_backdrop(now, tile, &[0xAA; 16]).unwrap(),+ vec![0xAA; 16]+ );+ }++ #[test]+ fn a_resync_blanks_once_and_suppresses_painting_for_the_grace() {+ let tile = tile_bounds(0, 0, 4, 1);+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();+ cache.record_frame(+ start,+ vec![painted_rect(0, 0, 4, 1)],+ vec![saved_backdrop(tile, vec![0x11; 16], vec![0xAA; 16])],+ );++ cache.resync(start);++ // The save-unders are gone and painting is suppressed, so no root read+ // can happen while our own pixels are still on screen.+ assert!(cache.frames.is_empty());+ assert!(cache.resyncing(start));+ assert!(cache.take_resync_blanking());+ assert!(!cache.take_resync_blanking());+ assert!(cache.resyncing(start + X11_BACKDROP_RESYNC_GRACE - Duration::from_millis(1)));+ assert!(!cache.resyncing(start + X11_BACKDROP_RESYNC_GRACE));+ // The next resync blanks again.+ cache.resync(start + X11_BACKDROP_RESYNC_GRACE);+ assert!(cache.take_resync_blanking());+ }++ #[test]+ fn a_transient_backdrop_failure_defers_frames_before_latching_compositing_off() {+ let mut cache = X11BackdropCache::default();++ for _ in 1..X11_BACKDROP_UNBACKED_FRAME_LIMIT {+ assert!(!cache.note_unbacked_frame());+ assert!(cache.enabled());+ }+ // A frame that composites clears the streak, so a one-off X11 error+ // cannot cost the session its translucency.+ cache.note_composited_frame();+ for _ in 1..X11_BACKDROP_UNBACKED_FRAME_LIMIT {+ assert!(!cache.note_unbacked_frame());+ }+ assert!(cache.enabled());++ assert!(cache.note_unbacked_frame());+ assert!(!cache.enabled());+ }++ #[test]+ fn slow_backdrop_reads_latch_compositing_off() {+ let over_budget = X11_BACKDROP_READ_BUDGET + Duration::from_millis(1);+ let mut cache = X11BackdropCache::default();++ cache.note_read_duration(over_budget);+ cache.note_read_duration(over_budget);+ assert!(cache.enabled());++ // A fast frame clears the streak.+ cache.note_read_duration(Duration::from_millis(1));+ cache.note_read_duration(over_budget);+ cache.note_read_duration(over_budget);+ assert!(cache.enabled());++ cache.note_read_duration(over_budget);+ assert!(!cache.enabled());+ assert!(cache+ .resolve_backdrop(Instant::now(), tile_bounds(0, 0, 4, 1), &[0xAA; 16])+ .is_none());+ }++ #[test]+ fn backdrop_compositing_is_disabled_under_a_compositor() {+ let fresh = X11BackdropCache::default();+ let latched_off = X11BackdropCache {+ disabled: true,+ ..X11BackdropCache::default()+ };++ assert!(!backdrop_compositing_enabled(true, &fresh));+ assert!(!backdrop_compositing_enabled(true, &latched_off));+ assert!(!backdrop_compositing_enabled(false, &latched_off));+ assert!(backdrop_compositing_enabled(false, &fresh));+ }++ #[test]+ fn a_save_under_keeps_only_the_painted_bounding_box() {+ let shape = vec![painted_rect(2, 1, 3, 1), painted_rect(1, 2, 2, 2)];++ let bbox = shape_bounding_box(&shape).unwrap();++ assert_eq!(bbox, (1, 1, 5, 4));+ assert!(shape_bounding_box(&[]).is_none());+ }++ #[test]+ fn cropping_a_tile_buffer_keeps_row_order() {+ // 3×3 tile, one distinct byte quad per pixel.+ let tile: Vec<u8> = (0u8..9)+ .flat_map(|index| [index, index, index, 255])+ .collect();++ let cropped = crop_tile_pixels(&tile, 3, (1, 1, 3, 3));++ assert_eq!(+ cropped,+ vec![4, 4, 4, 255, 5, 5, 5, 255, 7, 7, 7, 255, 8, 8, 8, 255]+ );+ }++ // ── Framebuffer model ────────────────────────────────────────────────+ //+ // The save-under logic is only correct against a real screen, where our own+ // paint is physically present in the pixels a root read returns. These+ // tests model that screen: paint writes the overlay's pixels into it, reads+ // come back out of it, and the windows underneath answer their Expose after+ // a configurable delay. The invariant every frame asserts is the one the+ // whole design exists for — the backdrop we composite over is the real+ // desktop, never our own previous frame.++ /// 8×1 premultiplied cursor strip: transparent edges, a translucent bloom+ /// and an opaque core, i.e. every alpha class the shape has to handle.+ fn strip_cursor_pixmap() -> tiny_skia::Pixmap {+ let mut pixmap = tiny_skia::Pixmap::new(8, 1).unwrap();+ let alphas = [0u8, 40, 120, 255, 255, 120, 40, 0];+ let data = pixmap.data_mut();+ for (index, alpha) in alphas.into_iter().enumerate() {+ let scale = |value: u32| ((value * u32::from(alpha)) / 255) as u8;+ data[index * 4..index * 4 + 4].copy_from_slice(&[+ scale(200),+ scale(120),+ scale(60),+ alpha,+ ]);+ }+ pixmap+ }++ struct ScreenModel {+ /// What the windows underneath would draw: the answer every composited+ /// backdrop has to reproduce.+ desktop: Vec<u8>,+ /// What a root read actually returns, including our own paint.+ screen: Vec<u8>,+ painted_at: Vec<Option<usize>>,+ /// Frames a vacated pixel takes to be repainted by its owner; `None`+ /// models a client that never answers its Expose at all.+ repaint_delay: Option<usize>,+ }++ impl ScreenModel {+ fn new(width: usize, repaint_delay: Option<usize>) -> Self {+ let desktop: Vec<u8> = (0..width)+ .flat_map(|x| [x as u8, (x * 3) as u8, (x * 7) as u8, 0])+ .collect();+ Self {+ screen: desktop.clone(),+ painted_at: vec![None; width],+ desktop,+ repaint_delay,+ }+ }++ fn read(&self, x: usize, width: usize) -> Vec<u8> {+ self.screen[x * 4..(x + width) * 4].to_vec()+ }++ fn desktop_slice(&self, x: usize, width: usize) -> Vec<u8> {+ self.desktop[x * 4..(x + width) * 4].to_vec()+ }++ /// Redraw part of the desktop. Pixels the overlay is currently covering+ /// keep our paint: the server clips their owner away from them.+ fn redraw_desktop(&mut self, range: std::ops::Range<usize>, tint: u8) {+ for pixel in range {+ let at = pixel * 4;+ self.desktop[at..at + 4].copy_from_slice(&[tint, tint / 2, tint / 3, 0]);+ if self.painted_at[pixel].is_none() {+ self.screen[at..at + 4].copy_from_slice(&self.desktop[at..at + 4]);+ }+ }+ }++ fn paint(+ &mut self,+ frame: usize,+ x: usize,+ bgra: &[u8],+ shape: &[x11rb::protocol::xproto::Rectangle],+ ) {+ for rect in shape {+ for col in usize::from(rect.x as u16)..usize::from(rect.x as u16 + rect.width) {+ let at = (x + col) * 4;+ // The server keeps our colour bytes; a depth-24 root read+ // pads the fourth byte with zero rather than our 255.+ self.screen[at..at + 3].copy_from_slice(&bgra[col * 4..col * 4 + 3]);+ self.screen[at + 3] = 0;+ self.painted_at[x + col] = Some(frame);+ }+ }++ let Some(delay) = self.repaint_delay else {+ return;+ };+ for pixel in 0..self.painted_at.len() {+ let Some(at_frame) = self.painted_at[pixel] else {+ continue;+ };+ if at_frame < frame && frame - at_frame > delay {+ let at = pixel * 4;+ self.screen[at..at + 4].copy_from_slice(&self.desktop[at..at + 4]);+ self.painted_at[pixel] = None;+ }+ }+ }+ }++ /// Drive the real cache and the real compositing helper across `path`,+ /// asserting on every frame that the backdrop resolves to the true desktop.+ fn run_screen_model(model: &mut ScreenModel, path: &[usize], redraw: Option<(usize, u8)>) {+ let pixmap = strip_cursor_pixmap();+ let start = Instant::now();+ let mut cache = X11BackdropCache::default();++ for (frame, &x) in path.iter().enumerate() {+ if let Some((at_frame, tint)) = redraw {+ if frame == at_frame {+ model.redraw_desktop(0..6, tint);+ }+ }+ let now = start + Duration::from_millis(16 * frame as u64);+ let bounds = tile_bounds(x as i16, 0, 8, 1);++ let fresh = model.read(x, 8);+ let under = cache+ .resolve_backdrop(now, bounds, &fresh)+ .unwrap_or_else(|| panic!("frame {frame}: no backdrop"));+ assert_eq!(+ under,+ model.desktop_slice(x, 8),+ "frame {frame} composited over something other than the desktop"+ );++ let (bgra, mut shape) = composited_bgra_and_visible_shape(&pixmap, &under).unwrap();+ model.paint(frame, x, &bgra, &shape);++ let saved: Vec<X11SavedBackdrop> = shape_bounding_box(&shape)+ .map(|bbox| X11SavedBackdrop {+ bounds: tile_bounds(+ (x + bbox.0) as i16,+ 0,+ (bbox.2 - bbox.0) as u16,+ (bbox.3 - bbox.1) as u16,+ ),+ under: crop_tile_pixels(&under, 8, bbox),+ uploaded: crop_tile_pixels(&bgra, 8, bbox),+ })+ .into_iter()+ .collect();+ for rect in &mut shape {+ rect.x = rect.x.saturating_add(x as i16);+ }+ cache.record_frame(now, shape, saved);+ }+ }++ /// One pass right and back again, so every frame's tile overlaps the trail+ /// the previous frames left behind.+ fn sweep_path(limit: usize) -> Vec<usize> {+ (0..=limit).chain((0..limit).rev()).collect()+ }++ #[test]+ fn a_moving_cursor_never_composites_over_its_own_previous_frame() {+ for delay in [Some(0), Some(1), Some(5)] {+ let mut model = ScreenModel::new(64, delay);+ run_screen_model(&mut model, &sweep_path(12), None);+ }+ }++ #[test]+ fn a_client_that_never_answers_expose_still_gets_a_clean_backdrop() {+ // The 200 ms-style timing guess is exactly what this case used to+ // break: nothing under the trail is ever repainted, so every vacated+ // pixel still holds our own paint when it is read back.+ let mut model = ScreenModel::new(64, None);+ run_screen_model(&mut model, &sweep_path(12), None);+ }++ #[test]+ fn a_backdrop_that_changed_while_uncovered_is_picked_up_again() {+ // The trail is repainted quickly and then its owner draws something+ // else there. Returning over it must show the new content, not the+ // save-under captured on the way out.+ let mut model = ScreenModel::new(64, Some(1));+ run_screen_model(&mut model, &sweep_path(12), Some((13, 0x5A)));+ }}#[cfg(not(target_os = "linux"))]diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.shindex 4893a8bda0..f59ec78afc 100755--- a/libs/cua-driver/scripts/_install-local-rust.sh+++ b/libs/cua-driver/scripts/_install-local-rust.sh@@ -501,12 +501,24 @@ INSTALLED_BIN="$BIN_DIR/cua-driver-local"# so the next invocation picks up this build. Best-effort, never# fails the install. Survivors (rare on Unix — `pkill` reaches all# user-owned procs without elevation) get a yellow hint.+#+# NOTE: do not use `pkill -x cua-driver-local`. `-x` compares against the+# kernel's truncated process name — 15 chars on Linux (`comm`) — and+# `cua-driver-local` is 16, so on Linux it silently matched nothing and+# every pre-swap daemon survived the install. Match argv[0] instead, and+# anchor it: an unanchored `-f` pattern also matches the launcher shells+# whose script *text* contains the daemon path, killing the surrounding+# session rather than the daemon.if [ "$OS" = "Darwin" ]; thenlaunchctl unload "$HOME/Library/LaunchAgents/com.trycua.cua-driver-local.plist" 2>/dev/null || trueelif [ "$OS" = "Linux" ] && command -v systemctl >/dev/null 2>&1; thensystemctl --user stop cua-driver-local.service >/dev/null 2>&1 || truefi-pkill -x cua-driver-local >/dev/null 2>&1 || true+for _daemon_bin in "$INSTALLED_BIN" "$BIN_TARGET"; do+ [ -n "$_daemon_bin" ] || continue+ pkill -f "^${_daemon_bin}([[:space:]]|\$)" >/dev/null 2>&1 || true+done+unset _daemon_bin# Agent skill pack symlinks: NOT auto-created. Run# `cua-driver skills install --local` to symlink agent dirs to thediff --git a/libs/cua-driver/scripts/uninstall-local.sh b/libs/cua-driver/scripts/uninstall-local.shindex c152ce9279..2a0258fe3f 100755--- a/libs/cua-driver/scripts/uninstall-local.sh+++ b/libs/cua-driver/scripts/uninstall-local.sh@@ -94,7 +94,15 @@ elif [[ "$OS" == "Linux" && -f "$SYSTEMD_UNIT" ]]; thenrm -f "$SYSTEMD_UNIT"log "removed systemd user unit $SYSTEMD_UNIT"fi-pkill -x cua-driver-local >/dev/null 2>&1 || true+# See the note in _install-local-rust.sh: `pkill -x cua-driver-local` never+# matches on Linux, because `-x` compares against the 15-char truncated+# `comm` and the name is 16. Match argv[0], anchored so the launcher shells+# that merely mention the path in their script text are left alone.+for _daemon_bin in "$CLI_LINK" "$HOME_DIR/packages/current/cua-driver-local"; do+ [ -n "$_daemon_bin" ] || continue+ pkill -f "^${_daemon_bin}([[:space:]]|\$)" >/dev/null 2>&1 || true+done+unset _daemon_bin# Revoke only the local bundle's TCC rows, while LaunchServices can resolve it.if [[ "$OS" == "Darwin" && "$RESET_TCC" == "1" ]] && command -v tccutil >/dev/null 2>&1; then