Skip to main content

computer_use_linux/
screenshot.rs

1use crate::diagnostics::hydrate_session_bus_env;
2use crate::x11_display::{is_native_x11_session, with_x11_display, X11_CAPTURE_TIMEOUT};
3use anyhow::{anyhow, bail, Context, Result};
4use base64::{engine::general_purpose::STANDARD, Engine};
5use futures_util::StreamExt;
6use image::codecs::jpeg::JpegEncoder;
7use image::imageops::FilterType;
8use schemars::JsonSchema;
9use serde::{Deserialize, Serialize};
10use std::{
11    collections::{HashMap, HashSet},
12    fs::{self, File, OpenOptions},
13    io::{Cursor, Read},
14    os::unix::fs::{MetadataExt, OpenOptionsExt},
15    path::{Path, PathBuf},
16    process::Stdio,
17    time::{Duration, SystemTime, UNIX_EPOCH},
18};
19use tokio::process::Command;
20use zbus::{
21    message::{Message, Type as MessageType},
22    names::{BusName, OwnedUniqueName, WellKnownName},
23    zvariant::{OwnedObjectPath, OwnedValue, Value},
24    MatchRule, MessageStream, Proxy,
25};
26
27const PORTAL_DESKTOP_SERVICE: &str = "org.freedesktop.portal.Desktop";
28const PORTAL_DESKTOP_PATH: &str = "/org/freedesktop/portal/desktop";
29const PORTAL_SCREENSHOT_INTERFACE: &str = "org.freedesktop.portal.Screenshot";
30const PORTAL_REQUEST_INTERFACE: &str = "org.freedesktop.portal.Request";
31const PORTAL_REQUEST_PATH_NAMESPACE: &str = "/org/freedesktop/portal/desktop/request";
32const MAX_SCREENSHOT_SOURCE_BYTES: u64 = 64 * 1024 * 1024;
33const MAX_SCREENSHOT_SOURCE_PIXELS: u64 = 128 * 1024 * 1024;
34
35pub const DEFAULT_SCREENSHOT_MAX_DIMENSION: u32 = 1920;
36pub const DEFAULT_SCREENSHOT_MAX_BYTES: usize = 2 * 1024 * 1024;
37pub const ABSOLUTE_SCREENSHOT_MAX_DIMENSION: u32 = 4096;
38pub const ABSOLUTE_SCREENSHOT_MAX_BYTES: usize = 4 * 1024 * 1024;
39pub const DEFAULT_SCREENSHOT_JPEG_QUALITY: u8 = 80;
40pub const MIN_SCREENSHOT_JPEG_QUALITY: u8 = 1;
41pub const MAX_SCREENSHOT_JPEG_QUALITY: u8 = 95;
42const MIN_SCREENSHOT_MAX_BYTES: usize = 1024;
43
44#[derive(Debug, Clone)]
45pub struct RawScreenshotCapture {
46    pub mime_type: String,
47    pub bytes: Vec<u8>,
48    pub source: String,
49    pub width: u32,
50    pub height: u32,
51}
52
53#[derive(Debug, Clone, Serialize, JsonSchema)]
54pub struct ScreenshotCapture {
55    pub mime_type: String,
56    pub data_url: String,
57    pub source: String,
58    /// Width of the returned image payload.
59    pub width: u32,
60    /// Height of the returned image payload.
61    pub height: u32,
62    /// Coordinate-space width before payload downscaling.
63    pub coordinate_width: u32,
64    /// Coordinate-space height before payload downscaling.
65    pub coordinate_height: u32,
66    /// Returned pixels per coordinate-space pixel.
67    pub scale: f32,
68    pub resized: bool,
69    pub bytes: usize,
70    pub original_bytes: usize,
71    pub max_bytes: usize,
72    pub format: ScreenshotOutputFormat,
73    pub quality: Option<u8>,
74}
75
76#[derive(Debug, Clone, Copy, Default)]
77pub struct ScreenshotPayloadOptions {
78    pub max_width: Option<u32>,
79    pub max_height: Option<u32>,
80    pub max_bytes: Option<usize>,
81    pub scale: Option<f32>,
82    pub format: Option<ScreenshotOutputFormat>,
83    pub quality: Option<u8>,
84}
85
86#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
87#[serde(rename_all = "lowercase")]
88pub enum ScreenshotOutputFormat {
89    Png,
90    Jpeg,
91}
92
93impl ScreenshotOutputFormat {
94    fn mime_type(self) -> &'static str {
95        match self {
96            Self::Png => "image/png",
97            Self::Jpeg => "image/jpeg",
98        }
99    }
100}
101
102#[derive(Debug, Clone, Copy)]
103struct ResolvedScreenshotPayloadOptions {
104    max_width: u32,
105    max_height: u32,
106    max_bytes: usize,
107    scale: f32,
108    format: ScreenshotOutputFormat,
109    quality: u8,
110}
111
112#[derive(Debug)]
113struct PortalScreenshotRequest {
114    requested_at: SystemTime,
115    pictures: Option<PortalPicturesSnapshot>,
116}
117
118#[derive(Debug)]
119struct PortalPicturesSnapshot {
120    path: PathBuf,
121    directory: File,
122    names: HashSet<std::ffi::OsString>,
123}
124
125impl PortalPicturesSnapshot {
126    fn new(path: PathBuf) -> std::io::Result<Self> {
127        let path = fs::canonicalize(path)?;
128        let directory = File::open(&path)?;
129        let names = fs::read_dir(&path)?
130            .map(|entry| entry.map(|entry| entry.file_name()))
131            .collect::<std::io::Result<HashSet<_>>>()?;
132        Ok(Self {
133            path,
134            directory,
135            names,
136        })
137    }
138
139    fn contains_new_path(&self, path: &Path) -> bool {
140        if path.parent() != Some(self.path.as_path()) {
141            return false;
142        }
143        let same_directory = self
144            .directory
145            .metadata()
146            .ok()
147            .zip(fs::metadata(&self.path).ok())
148            .is_some_and(|(before, current)| {
149                (before.dev(), before.ino()) == (current.dev(), current.ino())
150            });
151        same_directory
152            && path
153                .file_name()
154                .is_some_and(|name| !self.names.contains(name))
155    }
156}
157
158#[derive(Debug)]
159enum ScreenshotCleanup {
160    DeletePath(PathBuf),
161    #[cfg(test)]
162    Preserve,
163    PortalPath {
164        path: PathBuf,
165        request: PortalScreenshotRequest,
166    },
167}
168
169struct OwnedScreenshotCleanup {
170    strategy: Option<ScreenshotCleanup>,
171    portal_file: Option<File>,
172}
173
174impl OwnedScreenshotCleanup {
175    fn new(strategy: ScreenshotCleanup) -> Self {
176        let portal_file = match &strategy {
177            ScreenshotCleanup::PortalPath { path, request } => OpenOptions::new()
178                .read(true)
179                .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK)
180                .open(path)
181                .ok()
182                .filter(|file| {
183                    file.metadata().is_ok_and(|metadata| {
184                        if !metadata.is_file() || metadata.uid() != unsafe { libc::geteuid() } {
185                            return false;
186                        }
187                        if let Some(pictures) = &request.pictures {
188                            if path.parent() == Some(pictures.path.as_path()) {
189                                return pictures.contains_new_path(path);
190                            }
191                        }
192                        // Unknown locations need proof of creation after the request.
193                        // Missing birth times preserve the file.
194                        metadata
195                            .created()
196                            .is_ok_and(|created| created >= request.requested_at)
197                    })
198                }),
199            _ => None,
200        };
201        Self {
202            strategy: Some(strategy),
203            portal_file,
204        }
205    }
206}
207
208impl OwnedScreenshotCleanup {
209    fn cleanup_now(&mut self) {
210        if let Some(strategy) = self.strategy.take() {
211            cleanup_screenshot_path(strategy, self.portal_file.take());
212        }
213    }
214}
215
216impl Drop for OwnedScreenshotCleanup {
217    fn drop(&mut self) {
218        let Some(strategy) = self.strategy.take() else {
219            return;
220        };
221        let portal_file = self.portal_file.take();
222        if matches!(strategy, ScreenshotCleanup::PortalPath { .. }) {
223            if let Ok(runtime) = tokio::runtime::Handle::try_current() {
224                // A queued read can be cancelled on the single-thread runtime.
225                // Keep the pinned file alive and unlink on a blocking worker.
226                runtime.spawn_blocking(move || cleanup_screenshot_path(strategy, portal_file));
227                return;
228            }
229        }
230        cleanup_screenshot_path(strategy, portal_file);
231    }
232}
233
234fn cleanup_screenshot_path(strategy: ScreenshotCleanup, portal_file: Option<File>) {
235    let path = match &strategy {
236        ScreenshotCleanup::DeletePath(path) => Some(path),
237        ScreenshotCleanup::PortalPath { path, .. } => portal_file.as_ref().and_then(|file| {
238            file.metadata()
239                .ok()
240                .zip(fs::symlink_metadata(path).ok())
241                .filter(|(original, current)| {
242                    current.file_type().is_file()
243                        && (original.dev(), original.ino()) == (current.dev(), current.ino())
244                })
245                .map(|_| path)
246        }),
247        #[cfg(test)]
248        ScreenshotCleanup::Preserve => None,
249    };
250    if let Some(path) = path {
251        if let Err(error) = fs::remove_file(path) {
252            if error.kind() != std::io::ErrorKind::NotFound {
253                eprintln!("Failed to remove screenshot capture file: {error}");
254            }
255        }
256    }
257}
258
259impl ScreenshotPayloadOptions {
260    fn resolve(self) -> ResolvedScreenshotPayloadOptions {
261        let max_width = self
262            .max_width
263            .unwrap_or(DEFAULT_SCREENSHOT_MAX_DIMENSION)
264            .clamp(1, ABSOLUTE_SCREENSHOT_MAX_DIMENSION);
265        let max_height = self
266            .max_height
267            .unwrap_or(DEFAULT_SCREENSHOT_MAX_DIMENSION)
268            .clamp(1, ABSOLUTE_SCREENSHOT_MAX_DIMENSION);
269        let max_bytes = self
270            .max_bytes
271            .unwrap_or(DEFAULT_SCREENSHOT_MAX_BYTES)
272            .clamp(MIN_SCREENSHOT_MAX_BYTES, ABSOLUTE_SCREENSHOT_MAX_BYTES);
273        let scale = self
274            .scale
275            .filter(|value| value.is_finite() && *value > 0.0)
276            .unwrap_or(1.0)
277            .min(1.0);
278        let format = self.format.unwrap_or(ScreenshotOutputFormat::Png);
279        let quality = self
280            .quality
281            .unwrap_or(DEFAULT_SCREENSHOT_JPEG_QUALITY)
282            .clamp(MIN_SCREENSHOT_JPEG_QUALITY, MAX_SCREENSHOT_JPEG_QUALITY);
283
284        ResolvedScreenshotPayloadOptions {
285            max_width,
286            max_height,
287            max_bytes,
288            scale,
289            format,
290            quality,
291        }
292    }
293}
294
295/// Environment variable forcing a single capture backend, skipping the
296/// fallback chain. Accepts `gnome-shell`, `portal`, `x11`, `gnome-screenshot`, `dms`, or `pixelflux`.
297const SCREENSHOT_BACKEND_ENV: &str = "COMPUTER_USE_LINUX_SCREENSHOT_BACKEND";
298
299#[derive(Debug, Clone, Copy, PartialEq, Eq)]
300enum ScreenshotBackend {
301    GnomeShell,
302    Portal,
303    X11,
304    GnomeScreenshot,
305    Dms,
306    Pixelflux,
307}
308
309impl ScreenshotBackend {
310    fn parse(value: &str) -> Option<Self> {
311        match value.trim().to_ascii_lowercase().as_str() {
312            "gnome-shell" | "gnome_shell" | "shell" => Some(Self::GnomeShell),
313            "portal" | "xdg-portal" | "xdg_portal" => Some(Self::Portal),
314            "x11" | "x11-native" | "x11_native" | "xgetimage" => Some(Self::X11),
315            "gnome-screenshot" | "gnome_screenshot" => Some(Self::GnomeScreenshot),
316            "dms" | "dms-screenshot" | "dms_screenshot" => Some(Self::Dms),
317            "pixelflux" => Some(Self::Pixelflux),
318            _ => None,
319        }
320    }
321
322    async fn capture(self) -> Result<RawScreenshotCapture> {
323        match self {
324            Self::GnomeShell => capture_with_gnome_shell().await,
325            Self::Portal => capture_with_portal().await,
326            Self::X11 => capture_with_x11().await,
327            Self::GnomeScreenshot => capture_with_gnome_screenshot().await,
328            Self::Dms => capture_with_dms().await,
329            Self::Pixelflux => {
330                let config = crate::pixelflux::PixelfluxConfig::from_env()
331                    .context("PIXELFLUX_CU and PIXELFLUX_CU_TOKEN are required")?;
332                capture_with_pixelflux(&config).await
333            }
334        }
335    }
336}
337
338/// Size of the latest raw capture, for a window backend whose bounds are
339/// only valid under a capture of every output.
340static LAST_CAPTURE_SIZE: std::sync::Mutex<Option<(u32, u32)>> = std::sync::Mutex::new(None);
341
342pub(crate) fn last_capture_size() -> Option<(u32, u32)> {
343    LAST_CAPTURE_SIZE.lock().ok().and_then(|guard| *guard)
344}
345
346/// Whether the next capture on an Umbriel session is expected to cover every
347/// output, in the order `capture_screenshot_raw` picks a route: a forced
348/// backend decides alone, then Pixelflux when configured, then `dms` when it
349/// is on `PATH`. A guess for before the first capture; `last_capture_size`
350/// is the fact afterwards.
351pub(crate) fn all_outputs_capture_expected() -> bool {
352    if cfg!(test) {
353        return false;
354    }
355    all_outputs_route_expected(
356        forced_backend(),
357        crate::pixelflux::PixelfluxConfig::from_env().is_some(),
358        dms_on_path(),
359    )
360}
361
362fn all_outputs_route_expected(
363    forced: Result<Option<ScreenshotBackend>>,
364    pixelflux_configured: bool,
365    dms_on_path: bool,
366) -> bool {
367    match forced {
368        Ok(Some(ScreenshotBackend::Dms)) => dms_on_path,
369        Ok(Some(_)) | Err(_) => false,
370        Ok(None) => !pixelflux_configured && dms_on_path,
371    }
372}
373
374/// Whether an executable `dms` is on `PATH`.
375pub(crate) fn dms_on_path() -> bool {
376    std::env::var_os("PATH").is_some_and(|path| {
377        std::env::split_paths(&path).any(|dir| {
378            fs::metadata(dir.join("dms"))
379                .is_ok_and(|metadata| metadata.is_file() && metadata.mode() & 0o111 != 0)
380        })
381    })
382}
383
384pub async fn capture_screenshot_raw() -> Result<RawScreenshotCapture> {
385    let capture = capture_screenshot_raw_unrecorded().await?;
386    if let Ok(mut last) = LAST_CAPTURE_SIZE.lock() {
387        *last = Some((capture.width, capture.height));
388    }
389    Ok(capture)
390}
391
392async fn capture_screenshot_raw_unrecorded() -> Result<RawScreenshotCapture> {
393    hydrate_session_bus_env();
394
395    // Explicit override: use exactly the requested backend, no fallback. Lets
396    // background/systemd contexts pin `gnome-screenshot` when the DBus paths are
397    // blocked, and aids debugging.
398    if let Some(forced) = forced_backend()? {
399        return forced.capture().await;
400    }
401
402    if let Some(config) = crate::pixelflux::PixelfluxConfig::from_env() {
403        match capture_with_pixelflux(&config).await {
404            Ok(capture) => return Ok(capture),
405            Err(error) if crate::pixelflux::is_unreachable(&error) => {}
406            Err(error) => return Err(error),
407        }
408    }
409
410    // xdg-desktop-portal-umbriel answers a non-interactive screenshot with one
411    // output, so on Umbriel a second screen would stay invisible. `dms
412    // screenshot all` stitches every output; any failure falls through to
413    // the portal.
414    let dms_error = if !cfg!(test) && crate::windowing::backends::umbriel::is_umbriel_session() {
415        match capture_with_dms().await {
416            Ok(capture) => return Ok(capture),
417            Err(error) => Some(error),
418        }
419    } else {
420        None
421    };
422
423    // The Shell and portal DBus paths can fail for background processes (systemd
424    // user services, non-interactive parent shells): GNOME Shell's
425    // DBusSenderChecker rejects unknown bus names, and a portal consent dialog
426    // may be denied when the caller is not the focused app. Response code 2
427    // can also indicate other portal failures. `gnome-screenshot` claims an
428    // allowlisted bus name, so try it as the final fallback. See issue #20.
429    let gnome_error = match capture_with_gnome_shell().await {
430        Ok(capture) => return Ok(capture),
431        Err(error) => error,
432    };
433    let portal_error = match capture_with_portal().await {
434        Ok(capture) => return Ok(capture),
435        Err(error) => error,
436    };
437    // Native X11 only, and ahead of gnome-screenshot: gnome-screenshot 41 masks
438    // everything outside the GDK monitor geometry, which is 1/4 of the frame at
439    // window-scaling-factor 2 on MATE (issue #155). GetImage has no GDK layer.
440    let x11_error = match capture_with_x11().await {
441        Ok(capture) => return Ok(capture),
442        Err(error) => error,
443    };
444    let cli_error = match capture_with_gnome_screenshot().await {
445        Ok(capture) => return Ok(capture),
446        Err(error) => error,
447    };
448
449    let dms_error = dms_error
450        .map(|error| format!("dms screenshot failed: {error:#}; "))
451        .unwrap_or_default();
452    Err(anyhow!(
453        "{dms_error}GNOME Shell screenshot failed: {gnome_error:#}; \
454         XDG portal screenshot failed: {portal_error:#}; \
455         native X11 screenshot failed: {x11_error:#}; \
456         gnome-screenshot fallback failed: {cli_error:#}"
457    ))
458}
459
460/// `GetImage` on the root window of a native X11 session. Pixels are device
461/// pixels, the space xdotool/XTEST input and X11 window origins use.
462async fn capture_with_x11() -> Result<RawScreenshotCapture> {
463    if !is_native_x11_session() {
464        bail!("not a native X11 session (needs DISPLAY on an X11, not Wayland, session)");
465    }
466    let image = with_x11_display(X11_CAPTURE_TIMEOUT, |display| display.capture_root()).await??;
467    let (width, height) = (image.width, image.height);
468    let bytes =
469        tokio::task::spawn_blocking(move || encode_rgb_png(image.width, image.height, image.rgb))
470            .await
471            .context("X11 screenshot encoder task failed")??;
472    Ok(RawScreenshotCapture {
473        mime_type: "image/png".to_string(),
474        bytes,
475        source: "x11".to_string(),
476        width,
477        height,
478    })
479}
480
481fn encode_rgb_png(width: u32, height: u32, rgb: Vec<u8>) -> Result<Vec<u8>> {
482    let buffer = image::RgbImage::from_raw(width, height, rgb)
483        .context("X11 root image did not match its dimensions")?;
484    let mut out = Vec::new();
485    image::DynamicImage::ImageRgb8(buffer)
486        .write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)
487        .context("failed to encode X11 screenshot PNG")?;
488    Ok(out)
489}
490
491async fn capture_with_pixelflux(
492    config: &crate::pixelflux::PixelfluxConfig,
493) -> Result<RawScreenshotCapture> {
494    let reply =
495        crate::pixelflux::send(config, &crate::pixelflux::PixelfluxAction::Screenshot).await?;
496    let bytes = reply.data.context("pixelflux screenshot had no image")?;
497    // Read only the PNG header: a full decode here would inflate an
498    // arbitrary-size image just to learn its dimensions.
499    let (width, height) = png_dimensions(&bytes).context("pixelflux screenshot was not a PNG")?;
500    Ok(RawScreenshotCapture {
501        mime_type: "image/png".to_string(),
502        bytes,
503        source: "pixelflux".to_string(),
504        width,
505        height,
506    })
507}
508
509fn forced_backend() -> Result<Option<ScreenshotBackend>> {
510    match std::env::var(SCREENSHOT_BACKEND_ENV) {
511        Ok(value) if !value.trim().is_empty() => {
512            ScreenshotBackend::parse(&value).map(Some).ok_or_else(|| {
513                anyhow!(
514                    "{SCREENSHOT_BACKEND_ENV}={value:?} is not a recognized backend \
515                     (expected gnome-shell, portal, x11, gnome-screenshot, dms, or pixelflux)"
516                )
517            })
518        }
519        _ => Ok(None),
520    }
521}
522
523pub async fn capture_screenshot() -> Result<ScreenshotCapture> {
524    let _pipeline = screenshot_pipeline_permit().await?;
525    let raw = capture_screenshot_raw().await?;
526    run_image_task(move || prepare_screenshot_payload(raw, ScreenshotPayloadOptions::default()))
527        .await
528}
529
530pub(crate) async fn screenshot_pipeline_permit() -> Result<tokio::sync::SemaphorePermit<'static>> {
531    static CAPTURE_PIPELINE: tokio::sync::Semaphore = tokio::sync::Semaphore::const_new(1);
532    Ok(CAPTURE_PIPELINE.acquire().await?)
533}
534
535pub(crate) async fn run_image_task<T: Send + 'static>(
536    work: impl FnOnce() -> Result<T> + Send + 'static,
537) -> Result<T> {
538    static IMAGE_WORKER: tokio::sync::Semaphore = tokio::sync::Semaphore::const_new(1);
539    let permit = IMAGE_WORKER.acquire().await?;
540    tokio::task::spawn_blocking(move || {
541        let _permit = permit;
542        work()
543    })
544    .await
545    .context("screenshot processing task failed")?
546}
547
548pub fn prepare_screenshot_payload(
549    raw: RawScreenshotCapture,
550    options: ScreenshotPayloadOptions,
551) -> Result<ScreenshotCapture> {
552    if raw.bytes.is_empty() {
553        bail!("screenshot file was empty");
554    }
555    let (coordinate_width, coordinate_height) = png_dimensions(&raw.bytes)?;
556    let original_bytes = raw.bytes.len();
557    let options = options.resolve();
558    let (target_width, target_height) =
559        target_dimensions(coordinate_width, coordinate_height, options);
560
561    let (bytes, width, height) = if options.format == ScreenshotOutputFormat::Png
562        && target_width == coordinate_width
563        && target_height == coordinate_height
564        && original_bytes <= options.max_bytes
565    {
566        (raw.bytes, coordinate_width, coordinate_height)
567    } else {
568        encode_screenshot_to_fit_bytes(
569            &raw.bytes,
570            coordinate_width,
571            coordinate_height,
572            target_width,
573            target_height,
574            options,
575        )?
576    };
577
578    let encoded = STANDARD.encode(&bytes);
579    let scale = if coordinate_width == 0 {
580        1.0
581    } else {
582        width as f32 / coordinate_width as f32
583    };
584
585    Ok(ScreenshotCapture {
586        mime_type: options.format.mime_type().to_string(),
587        data_url: format!("data:{};base64,{encoded}", options.format.mime_type()),
588        source: raw.source,
589        width,
590        height,
591        coordinate_width,
592        coordinate_height,
593        scale,
594        resized: width != coordinate_width || height != coordinate_height,
595        bytes: bytes.len(),
596        original_bytes,
597        max_bytes: options.max_bytes,
598        format: options.format,
599        quality: (options.format == ScreenshotOutputFormat::Jpeg).then_some(options.quality),
600    })
601}
602
603async fn capture_with_gnome_shell() -> Result<RawScreenshotCapture> {
604    let connection = zbus::Connection::session()
605        .await
606        .context("failed to connect to session bus")?;
607    let proxy = Proxy::new(
608        &connection,
609        "org.gnome.Shell.Screenshot",
610        "/org/gnome/Shell/Screenshot",
611        "org.gnome.Shell.Screenshot",
612    )
613    .await
614    .context("failed to create GNOME Shell screenshot proxy")?;
615    let path = temp_png_path("gnome-shell");
616    let filename = path
617        .to_str()
618        .context("temporary screenshot path is not valid UTF-8")?;
619    let result = proxy.call("Screenshot", &(false, false, filename)).await;
620    let (success, filename_used): (bool, String) = match result {
621        Ok(result) => result,
622        Err(error) => {
623            cleanup_gnome_requested_path(&path);
624            return Err(error).context("GNOME Shell Screenshot call failed");
625        }
626    };
627
628    if !success {
629        cleanup_gnome_requested_path(&path);
630        bail!("GNOME Shell reported screenshot failure");
631    }
632
633    read_png_as_capture(
634        PathBuf::from(filename_used),
635        "gnome-shell",
636        ScreenshotCleanup::DeletePath(path),
637    )
638    .await
639}
640
641async fn capture_with_portal() -> Result<RawScreenshotCapture> {
642    let connection = zbus::Connection::session()
643        .await
644        .context("failed to connect to session bus")?;
645    let portal_owner = portal_desktop_owner(&connection).await?;
646    let token = request_token();
647    // Some portals rewrite the request handle, so subscribe before calling Screenshot
648    // and filter by the returned handle instead of subscribing after the call.
649    let mut response_stream = portal_response_stream(&connection, &portal_owner).await?;
650
651    let portal_proxy = Proxy::new(
652        &connection,
653        portal_owner.clone(),
654        PORTAL_DESKTOP_PATH,
655        PORTAL_SCREENSHOT_INTERFACE,
656    )
657    .await
658    .context("failed to create XDG portal screenshot proxy")?;
659    let mut options: HashMap<&str, Value<'_>> = HashMap::new();
660    options.insert("handle_token", Value::from(token.as_str()));
661    options.insert("interactive", Value::from(false));
662    let mut pictures_command = Command::new("xdg-user-dir");
663    pictures_command.arg("PICTURES");
664    let pictures = crate::command_runner::output(pictures_command, "locate Pictures directory")
665        .await
666        .ok()
667        .filter(|output| output.status.success())
668        .and_then(|output| String::from_utf8(output.stdout).ok())
669        .map(|path| PathBuf::from(path.trim_end_matches('\n')))
670        .filter(|path| path.is_absolute());
671    let pictures = match pictures {
672        // Match the command helper's one-second metadata budget. A stalled
673        // Pictures mount must not prevent the portal request from starting.
674        Some(path) => match tokio::time::timeout(
675            Duration::from_secs(1),
676            tokio::task::spawn_blocking(move || PortalPicturesSnapshot::new(path)),
677        )
678        .await
679        {
680            Ok(Ok(Ok(snapshot))) => Some(snapshot),
681            _ => None,
682        },
683        None => None,
684    };
685    let request = PortalScreenshotRequest {
686        requested_at: SystemTime::now(),
687        pictures,
688    };
689    let handle: OwnedObjectPath = portal_proxy
690        .call("Screenshot", &("", options))
691        .await
692        .context("XDG portal Screenshot call failed")?;
693
694    let (response_code, results) = tokio::time::timeout(
695        Duration::from_secs(20),
696        wait_for_portal_response(&mut response_stream, handle.as_str(), portal_owner.as_str()),
697    )
698    .await
699    .context("timed out waiting for XDG portal screenshot response")??;
700
701    match response_code {
702        0 => {}
703        1 => bail!("XDG portal screenshot was cancelled by the user (response code 1)"),
704        2 => bail!(
705            "XDG portal screenshot ended without success (response code 2); \
706             check the desktop portal logs for permission or backend errors"
707        ),
708        _ => bail!("XDG portal screenshot returned unknown response code {response_code}"),
709    }
710
711    let uri_value = results
712        .get("uri")
713        .context("XDG portal screenshot response did not include a uri")?;
714    let uri: String = uri_value
715        .try_clone()
716        .context("failed to clone XDG portal screenshot uri")?
717        .try_into()
718        .context("XDG portal screenshot uri was not a string")?;
719    let path = file_uri_to_path(&uri)?;
720
721    read_portal_png_as_capture(path, request).await
722}
723
724async fn read_portal_png_as_capture(
725    path: PathBuf,
726    request: PortalScreenshotRequest,
727) -> Result<RawScreenshotCapture> {
728    // Portal URIs can reference user files. Snapshot names before requesting
729    // capture, and pin the returned file until cleanup to prevent inode reuse.
730    let cleanup = ScreenshotCleanup::PortalPath {
731        path: path.clone(),
732        request,
733    };
734    read_png_as_capture(path, "xdg-desktop-portal", cleanup).await
735}
736
737/// Upper bound on a `dms screenshot` run. It is tried ahead of the portal on
738/// Umbriel, so a stalled one must not hold every capture for long; a normal
739/// run of two 2880x1800 outputs takes about 150 ms.
740const DMS_SCREENSHOT_TIMEOUT: Duration = Duration::from_secs(5);
741
742/// Every output stitched into one image by the DMS shell's screenshot CLI
743/// (`dms screenshot all`), which captures through the compositor's Wayland
744/// capture protocol without a portal. The cursor is drawn so a caller can
745/// see where its last pointer action landed.
746async fn capture_with_dms() -> Result<RawScreenshotCapture> {
747    let path = temp_png_path("dms");
748    let directory = path
749        .parent()
750        .and_then(Path::to_str)
751        .context("temporary screenshot directory is not valid UTF-8")?;
752    let filename = path
753        .file_name()
754        .and_then(|name| name.to_str())
755        .context("temporary screenshot name is not valid UTF-8")?;
756
757    let mut command = Command::new("dms");
758    command
759        .args([
760            "screenshot",
761            "all",
762            "--no-clipboard",
763            "--no-notify",
764            "--cursor=on",
765            "-d",
766            directory,
767            "--filename",
768            filename,
769        ])
770        // A cancelled request drops the wait below before its kill runs.
771        .kill_on_drop(true)
772        .stdin(Stdio::null())
773        .stdout(Stdio::null())
774        .stderr(Stdio::null());
775    let mut child = match crate::command_runner::spawn_retrying_busy(&mut command).await {
776        Ok(child) => child,
777        Err(error) => {
778            cleanup_gnome_requested_path(&path);
779            return Err(error).context("failed to spawn dms screenshot");
780        }
781    };
782    let status = match tokio::time::timeout(DMS_SCREENSHOT_TIMEOUT, child.wait()).await {
783        Ok(Ok(status)) => status,
784        Ok(Err(error)) => {
785            cleanup_gnome_requested_path(&path);
786            return Err(error).context("failed to wait for dms screenshot");
787        }
788        Err(_) => {
789            let _ = child.kill().await;
790            cleanup_gnome_requested_path(&path);
791            bail!("dms screenshot timed out");
792        }
793    };
794    if !status.success() {
795        cleanup_gnome_requested_path(&path);
796        bail!("dms screenshot exited with {status}");
797    }
798
799    read_png_as_capture(path.clone(), "dms", ScreenshotCleanup::DeletePath(path)).await
800}
801
802/// Upper bound on how long we wait for `gnome-screenshot` before killing it.
803/// Matches the portal timeout: a hung capture must not block the tool forever.
804const GNOME_SCREENSHOT_TIMEOUT: Duration = Duration::from_secs(20);
805
806async fn capture_with_gnome_screenshot() -> Result<RawScreenshotCapture> {
807    let path = temp_png_path("gnome-screenshot");
808    let filename = path
809        .to_str()
810        .context("temporary screenshot path is not valid UTF-8")?;
811
812    // `-f <file>` writes a full-screen PNG without prompting; no portal, no
813    // foreground window required. `tokio::process::Command` searches PATH and
814    // provides an async, non-polling wait.
815    let mut command = Command::new("gnome-screenshot");
816    command
817        .args(["-f", filename])
818        .stdin(Stdio::null())
819        .stdout(Stdio::null())
820        .stderr(Stdio::null());
821    let mut child = match crate::command_runner::spawn_retrying_busy(&mut command).await {
822        Ok(child) => child,
823        Err(error) => {
824            cleanup_gnome_requested_path(&path);
825            return Err(error).context("failed to spawn gnome-screenshot");
826        }
827    };
828
829    // A hung capture must not block the tool forever, so bound the wait and
830    // kill the child if it outlives the deadline.
831    let status = match tokio::time::timeout(GNOME_SCREENSHOT_TIMEOUT, child.wait()).await {
832        Ok(Ok(status)) => status,
833        Ok(Err(error)) => {
834            cleanup_gnome_requested_path(&path);
835            return Err(error).context("failed to wait for gnome-screenshot");
836        }
837        Err(_) => {
838            let _ = child.kill().await;
839            cleanup_gnome_requested_path(&path);
840            bail!("gnome-screenshot timed out");
841        }
842    };
843
844    if !status.success() {
845        cleanup_gnome_requested_path(&path);
846        bail!("gnome-screenshot exited with {status}");
847    }
848
849    read_png_as_capture(
850        path.clone(),
851        "gnome-screenshot",
852        ScreenshotCleanup::DeletePath(path),
853    )
854    .await
855}
856
857async fn portal_desktop_owner(connection: &zbus::Connection) -> Result<OwnedUniqueName> {
858    let dbus = zbus::fdo::DBusProxy::new(connection)
859        .await
860        .context("failed to create session-bus identity proxy")?;
861    // A supervised portal can already own the name without an activation
862    // file, as in an isolated desktop. Use that owner before requesting start.
863    match dbus
864        .get_name_owner(BusName::try_from(PORTAL_DESKTOP_SERVICE)?)
865        .await
866    {
867        Ok(owner) => return Ok(owner),
868        Err(zbus::fdo::Error::NameHasNoOwner(_)) => {}
869        Err(error) => return Err(error).context("failed to resolve the XDG desktop portal owner"),
870    }
871    let _: u32 = dbus
872        .start_service_by_name(WellKnownName::try_from(PORTAL_DESKTOP_SERVICE)?, 0)
873        .await
874        .context("failed to activate the XDG desktop portal")?;
875    dbus.get_name_owner(BusName::try_from(PORTAL_DESKTOP_SERVICE)?)
876        .await
877        .context("failed to resolve the XDG desktop portal owner")
878}
879
880async fn portal_response_stream(
881    connection: &zbus::Connection,
882    portal_owner: &OwnedUniqueName,
883) -> Result<MessageStream> {
884    let response_rule = MatchRule::builder()
885        .msg_type(MessageType::Signal)
886        .sender(portal_owner.clone())?
887        .interface(PORTAL_REQUEST_INTERFACE)?
888        .member("Response")?
889        .path_namespace(PORTAL_REQUEST_PATH_NAMESPACE)?
890        .build();
891
892    MessageStream::for_match_rule(response_rule, connection, None)
893        .await
894        .context("failed to subscribe to XDG portal screenshot responses")
895}
896
897async fn wait_for_portal_response(
898    response_stream: &mut MessageStream,
899    request_path: &str,
900    portal_owner: &str,
901) -> Result<(u32, HashMap<String, OwnedValue>)> {
902    loop {
903        let response = response_stream
904            .next()
905            .await
906            .context("XDG portal screenshot response stream ended")?
907            .context("XDG portal screenshot response stream failed")?;
908
909        if !portal_response_matches(&response, request_path, portal_owner) {
910            continue;
911        }
912
913        return response
914            .body()
915            .deserialize()
916            .context("failed to decode XDG portal screenshot response");
917    }
918}
919
920fn portal_response_matches(response: &Message, request_path: &str, portal_owner: &str) -> bool {
921    let header = response.header();
922    header
923        .sender()
924        .is_some_and(|sender| sender.as_str() == portal_owner)
925        && header
926            .path()
927            .is_some_and(|path| path.as_str() == request_path)
928}
929
930async fn read_png_as_capture(
931    path: PathBuf,
932    source: &str,
933    cleanup: ScreenshotCleanup,
934) -> Result<RawScreenshotCapture> {
935    let source = source.to_string();
936    let (path, mut cleanup) = if matches!(cleanup, ScreenshotCleanup::PortalPath { .. }) {
937        tokio::time::timeout(
938            Duration::from_secs(1),
939            tokio::task::spawn_blocking(move || {
940                // Resolve parent aliases without following the final symlink.
941                let path = path
942                    .parent()
943                    .and_then(|parent| fs::canonicalize(parent).ok())
944                    .zip(path.file_name())
945                    .map(|(parent, name)| parent.join(name))
946                    .unwrap_or(path);
947                let cleanup = match cleanup {
948                    ScreenshotCleanup::PortalPath { request, .. } => {
949                        ScreenshotCleanup::PortalPath {
950                            path: path.clone(),
951                            request,
952                        }
953                    }
954                    other => other,
955                };
956                (path, OwnedScreenshotCleanup::new(cleanup))
957            }),
958        )
959        .await
960        .context("timed out preparing portal screenshot file")?
961        .context("portal screenshot preparation task failed")?
962    } else {
963        (path, OwnedScreenshotCleanup::new(cleanup))
964    };
965    run_image_task(move || {
966        let result = read_png_as_capture_inner(&path, &source);
967        cleanup.cleanup_now();
968        result
969    })
970    .await
971}
972
973fn read_png_as_capture_inner(path: &Path, source: &str) -> Result<RawScreenshotCapture> {
974    let file = OpenOptions::new()
975        .read(true)
976        .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK)
977        .open(path)
978        .with_context(|| format!("failed to open screenshot file {}", path.display()))?;
979    let metadata = file
980        .metadata()
981        .with_context(|| format!("failed to inspect screenshot file {}", path.display()))?;
982    if !metadata.file_type().is_file() {
983        bail!("screenshot path is not a regular file: {}", path.display());
984    }
985    if metadata.len() > MAX_SCREENSHOT_SOURCE_BYTES {
986        bail!(
987            "screenshot file is {} bytes, over the {}-byte source limit",
988            metadata.len(),
989            MAX_SCREENSHOT_SOURCE_BYTES
990        );
991    }
992    let mut bytes = Vec::with_capacity(metadata.len() as usize);
993    file.take(MAX_SCREENSHOT_SOURCE_BYTES + 1)
994        .read_to_end(&mut bytes)
995        .with_context(|| format!("failed to read screenshot file {}", path.display()))?;
996    if bytes.len() as u64 > MAX_SCREENSHOT_SOURCE_BYTES {
997        bail!(
998            "screenshot file grew beyond the {}-byte source limit",
999            MAX_SCREENSHOT_SOURCE_BYTES
1000        );
1001    }
1002    if bytes.is_empty() {
1003        bail!("screenshot file was empty: {}", path.display());
1004    }
1005    let (width, height) = png_dimensions(&bytes)?;
1006    Ok(RawScreenshotCapture {
1007        mime_type: "image/png".to_string(),
1008        bytes,
1009        source: source.to_string(),
1010        width,
1011        height,
1012    })
1013}
1014
1015fn target_dimensions(
1016    width: u32,
1017    height: u32,
1018    options: ResolvedScreenshotPayloadOptions,
1019) -> (u32, u32) {
1020    let width_scale = options.max_width as f64 / width as f64;
1021    let height_scale = options.max_height as f64 / height as f64;
1022    let scale = f64::from(options.scale)
1023        .min(width_scale)
1024        .min(height_scale)
1025        .min(1.0);
1026
1027    let target_width = ((width as f64 * scale).round() as u32).clamp(1, width);
1028    let target_height = ((height as f64 * scale).round() as u32).clamp(1, height);
1029    (target_width, target_height)
1030}
1031
1032fn encode_screenshot_to_fit_bytes(
1033    raw: &[u8],
1034    original_width: u32,
1035    original_height: u32,
1036    mut target_width: u32,
1037    mut target_height: u32,
1038    options: ResolvedScreenshotPayloadOptions,
1039) -> Result<(Vec<u8>, u32, u32)> {
1040    let img = image::load_from_memory_with_format(raw, image::ImageFormat::Png)
1041        .context("failed to decode screenshot PNG for encoding")?;
1042
1043    loop {
1044        let bytes = if options.format == ScreenshotOutputFormat::Png
1045            && target_width == original_width
1046            && target_height == original_height
1047        {
1048            raw.to_vec()
1049        } else {
1050            let output = if target_width == original_width && target_height == original_height {
1051                img.clone()
1052            } else {
1053                img.resize_exact(target_width, target_height, FilterType::Lanczos3)
1054            };
1055            encode_image(&output, options)?
1056        };
1057
1058        if bytes.len() <= options.max_bytes {
1059            return Ok((bytes, target_width, target_height));
1060        }
1061
1062        if target_width == 1 && target_height == 1 {
1063            bail!(
1064                "screenshot payload is {} bytes at 1x1, over max_bytes {}",
1065                bytes.len(),
1066                options.max_bytes
1067            );
1068        }
1069
1070        (target_width, target_height) = next_dimensions_for_byte_cap(
1071            target_width,
1072            target_height,
1073            bytes.len(),
1074            options.max_bytes,
1075        );
1076    }
1077}
1078
1079fn encode_image(
1080    img: &image::DynamicImage,
1081    options: ResolvedScreenshotPayloadOptions,
1082) -> Result<Vec<u8>> {
1083    let mut out = Vec::new();
1084    match options.format {
1085        ScreenshotOutputFormat::Png => {
1086            img.write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)
1087                .context("failed to encode screenshot PNG")?;
1088        }
1089        ScreenshotOutputFormat::Jpeg => {
1090            let rgb = img.to_rgb8();
1091            JpegEncoder::new_with_quality(&mut out, options.quality)
1092                .encode_image(&rgb)
1093                .context("failed to encode screenshot JPEG")?;
1094        }
1095    }
1096    Ok(out)
1097}
1098
1099fn next_dimensions_for_byte_cap(
1100    width: u32,
1101    height: u32,
1102    encoded_bytes: usize,
1103    max_bytes: usize,
1104) -> (u32, u32) {
1105    let shrink = ((max_bytes as f64 / encoded_bytes as f64).sqrt() * 0.9).clamp(0.1, 0.95);
1106    let mut next_width = ((width as f64 * shrink).floor() as u32).max(1);
1107    let mut next_height = ((height as f64 * shrink).floor() as u32).max(1);
1108
1109    if next_width >= width && width > 1 {
1110        next_width = width - 1;
1111    }
1112    if next_height >= height && height > 1 {
1113        next_height = height - 1;
1114    }
1115
1116    (next_width, next_height)
1117}
1118
1119fn cleanup_gnome_requested_path(path: &Path) {
1120    let _ = fs::remove_file(path);
1121}
1122
1123pub(crate) fn png_dimensions(bytes: &[u8]) -> Result<(u32, u32)> {
1124    const PNG_SIGNATURE: &[u8; 8] = b"\x89PNG\r\n\x1a\n";
1125    if bytes.len() < 24 || &bytes[..8] != PNG_SIGNATURE || &bytes[12..16] != b"IHDR" {
1126        bail!("screenshot file was not a valid PNG");
1127    }
1128    let width = u32::from_be_bytes(bytes[16..20].try_into().unwrap());
1129    let height = u32::from_be_bytes(bytes[20..24].try_into().unwrap());
1130    if width == 0 || height == 0 {
1131        bail!("screenshot PNG had invalid dimensions {width}x{height}");
1132    }
1133    let pixels = u64::from(width) * u64::from(height);
1134    if pixels > MAX_SCREENSHOT_SOURCE_PIXELS {
1135        bail!(
1136            "screenshot PNG has {pixels} pixels, over the {MAX_SCREENSHOT_SOURCE_PIXELS}-pixel source limit"
1137        );
1138    }
1139    Ok((width, height))
1140}
1141
1142fn file_uri_to_path(uri: &str) -> Result<PathBuf> {
1143    let Some(rest) = uri.strip_prefix("file://") else {
1144        bail!("unsupported screenshot uri: {uri}");
1145    };
1146    let path = PathBuf::from(percent_decode(rest));
1147    if !path.is_absolute() {
1148        bail!("screenshot uri did not contain an absolute file path: {uri}");
1149    }
1150    Ok(path)
1151}
1152
1153fn percent_decode(value: &str) -> String {
1154    let bytes = value.as_bytes();
1155    let mut decoded = Vec::with_capacity(bytes.len());
1156    let mut index = 0;
1157
1158    while index < bytes.len() {
1159        if bytes[index] == b'%' && index + 2 < bytes.len() {
1160            if let Ok(hex) = std::str::from_utf8(&bytes[index + 1..index + 3]) {
1161                if let Ok(byte) = u8::from_str_radix(hex, 16) {
1162                    decoded.push(byte);
1163                    index += 3;
1164                    continue;
1165                }
1166            }
1167        }
1168
1169        decoded.push(bytes[index]);
1170        index += 1;
1171    }
1172
1173    String::from_utf8_lossy(&decoded).into_owned()
1174}
1175
1176fn temp_png_path(source: &str) -> PathBuf {
1177    std::env::temp_dir().join(format!(
1178        "computer-use-linux-{source}-{}.png",
1179        unique_suffix()
1180    ))
1181}
1182
1183fn request_token() -> String {
1184    format!("computer_use_linux_{}", unique_suffix().replace('-', "_"))
1185}
1186
1187fn unique_suffix() -> String {
1188    let nanos = SystemTime::now()
1189        .duration_since(UNIX_EPOCH)
1190        .map(|duration| duration.as_nanos())
1191        .unwrap_or_default();
1192    format!("{}-{nanos}", std::process::id())
1193}
1194
1195#[cfg(test)]
1196mod tests {
1197    use super::*;
1198
1199    fn test_path(name: &str) -> PathBuf {
1200        std::env::temp_dir().join(format!(
1201            "computer-use-linux-screenshot-test-{name}-{}",
1202            unique_suffix()
1203        ))
1204    }
1205
1206    fn valid_png(width: u32, height: u32) -> Vec<u8> {
1207        let mut png = Vec::new();
1208        png.extend_from_slice(b"\x89PNG\r\n\x1a\n");
1209        png.extend_from_slice(&13_u32.to_be_bytes());
1210        png.extend_from_slice(b"IHDR");
1211        png.extend_from_slice(&width.to_be_bytes());
1212        png.extend_from_slice(&height.to_be_bytes());
1213        png.extend_from_slice(&[8, 6, 0, 0, 0]);
1214        png
1215    }
1216
1217    fn solid_png(width: u32, height: u32) -> Vec<u8> {
1218        let img = image::RgbaImage::from_pixel(width, height, image::Rgba([24, 96, 160, 255]));
1219        encode_test_png(img)
1220    }
1221
1222    fn noisy_png(width: u32, height: u32) -> Vec<u8> {
1223        let mut img = image::RgbaImage::new(width, height);
1224        for (x, y, pixel) in img.enumerate_pixels_mut() {
1225            let r = ((x * 31 + y * 17) % 256) as u8;
1226            let g = ((x * 13 + y * 47) % 256) as u8;
1227            let b = ((x * 97 + y * 7) % 256) as u8;
1228            *pixel = image::Rgba([r, g, b, 255]);
1229        }
1230        encode_test_png(img)
1231    }
1232
1233    fn encode_test_png(img: image::RgbaImage) -> Vec<u8> {
1234        let mut out = Vec::new();
1235        image::DynamicImage::ImageRgba8(img)
1236            .write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)
1237            .unwrap();
1238        out
1239    }
1240
1241    fn raw_capture(bytes: Vec<u8>) -> RawScreenshotCapture {
1242        let (width, height) = png_dimensions(&bytes).unwrap();
1243        RawScreenshotCapture {
1244            mime_type: "image/png".to_string(),
1245            bytes,
1246            source: "test".to_string(),
1247            width,
1248            height,
1249        }
1250    }
1251
1252    #[test]
1253    fn decodes_file_uri_percent_escapes() {
1254        assert_eq!(
1255            file_uri_to_path("file:///tmp/Codex%20Screenshot.png").unwrap(),
1256            PathBuf::from("/tmp/Codex Screenshot.png")
1257        );
1258    }
1259
1260    #[test]
1261    fn file_uri_requires_an_absolute_path() {
1262        assert!(file_uri_to_path("file://relative/path.png").is_err());
1263    }
1264
1265    #[test]
1266    fn portal_response_requires_the_pinned_sender_and_exact_path() {
1267        let request_path = "/org/freedesktop/portal/desktop/request/1_7/token";
1268        let response = Message::signal(request_path, PORTAL_REQUEST_INTERFACE, "Response")
1269            .unwrap()
1270            .sender(":1.42")
1271            .unwrap()
1272            .build(&())
1273            .unwrap();
1274
1275        assert!(portal_response_matches(&response, request_path, ":1.42"));
1276        assert!(!portal_response_matches(&response, request_path, ":1.99"));
1277        assert!(!portal_response_matches(
1278            &response,
1279            "/org/freedesktop/portal/desktop/request/1_7/other",
1280            ":1.42"
1281        ));
1282    }
1283
1284    #[test]
1285    fn parses_known_backend_names() {
1286        assert_eq!(
1287            ScreenshotBackend::parse("gnome-shell"),
1288            Some(ScreenshotBackend::GnomeShell)
1289        );
1290        assert_eq!(
1291            ScreenshotBackend::parse("  Portal "),
1292            Some(ScreenshotBackend::Portal)
1293        );
1294        assert_eq!(
1295            ScreenshotBackend::parse("GNOME_SCREENSHOT"),
1296            Some(ScreenshotBackend::GnomeScreenshot)
1297        );
1298        assert_eq!(
1299            ScreenshotBackend::parse("x11"),
1300            Some(ScreenshotBackend::X11)
1301        );
1302        assert_eq!(
1303            ScreenshotBackend::parse(" X11-Native "),
1304            Some(ScreenshotBackend::X11)
1305        );
1306        assert_eq!(ScreenshotBackend::parse("nonsense"), None);
1307    }
1308
1309    #[test]
1310    fn a_forced_backend_decides_the_all_outputs_route_ahead_of_pixelflux() {
1311        let forced = |backend| Ok(Some(backend));
1312        // Forced dms wins over a configured Pixelflux, as in the capture chain.
1313        assert!(all_outputs_route_expected(
1314            forced(ScreenshotBackend::Dms),
1315            true,
1316            true
1317        ));
1318        assert!(!all_outputs_route_expected(
1319            forced(ScreenshotBackend::Dms),
1320            false,
1321            false
1322        ));
1323        assert!(!all_outputs_route_expected(
1324            forced(ScreenshotBackend::Portal),
1325            false,
1326            true
1327        ));
1328        // Unforced: Pixelflux is tried first.
1329        assert!(!all_outputs_route_expected(Ok(None), true, true));
1330        assert!(all_outputs_route_expected(Ok(None), false, true));
1331        assert!(!all_outputs_route_expected(
1332            Err(anyhow!("bad")),
1333            false,
1334            true
1335        ));
1336    }
1337
1338    #[test]
1339    fn forced_backend_reads_env_override() {
1340        let _guard = crate::pixelflux::TEST_ENV_LOCK
1341            .lock()
1342            .unwrap_or_else(|e| e.into_inner());
1343        std::env::set_var(SCREENSHOT_BACKEND_ENV, "gnome-screenshot");
1344        assert_eq!(
1345            forced_backend().unwrap(),
1346            Some(ScreenshotBackend::GnomeScreenshot)
1347        );
1348
1349        std::env::set_var(SCREENSHOT_BACKEND_ENV, "pixelflux");
1350        assert_eq!(
1351            forced_backend().unwrap(),
1352            Some(ScreenshotBackend::Pixelflux)
1353        );
1354
1355        std::env::set_var(SCREENSHOT_BACKEND_ENV, "   ");
1356        assert_eq!(forced_backend().unwrap(), None);
1357
1358        std::env::set_var(SCREENSHOT_BACKEND_ENV, "bogus");
1359        let error = forced_backend().unwrap_err();
1360        assert!(error.to_string().contains("not a recognized backend"));
1361
1362        std::env::remove_var(SCREENSHOT_BACKEND_ENV);
1363        assert_eq!(forced_backend().unwrap(), None);
1364    }
1365
1366    #[tokio::test]
1367    #[allow(clippy::await_holding_lock)] // current-thread test: other env tests wait on the lock.
1368    async fn screenshot_prefers_pixelflux_when_configured() {
1369        let _guard = crate::pixelflux::TEST_ENV_LOCK
1370            .lock()
1371            .unwrap_or_else(|e| e.into_inner());
1372        let png = solid_png(4, 5);
1373        let payload = serde_json::json!({"data": base64::Engine::encode(
1374            &base64::engine::general_purpose::STANDARD,
1375            &png,
1376        )})
1377        .to_string();
1378        let response = format!(
1379            "HTTP/1.1 200 OK\r\nContent-Length: {len}\r\nConnection: close\r\n\r\n{payload}",
1380            len = payload.len(),
1381        );
1382        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1383        let port = listener.local_addr().unwrap().port();
1384        tokio::spawn(async move {
1385            let (mut sock, _) = listener.accept().await.unwrap();
1386            let mut buf = [0u8; 4096];
1387            let _ = tokio::io::AsyncReadExt::read(&mut sock, &mut buf).await;
1388            let _ = tokio::io::AsyncWriteExt::write_all(&mut sock, response.as_bytes()).await;
1389        });
1390        std::env::set_var("PIXELFLUX_CU", port.to_string());
1391        std::env::set_var("PIXELFLUX_CU_TOKEN", "secret");
1392        std::env::remove_var(SCREENSHOT_BACKEND_ENV);
1393        let capture = capture_screenshot_raw().await.unwrap();
1394        std::env::remove_var("PIXELFLUX_CU");
1395        std::env::remove_var("PIXELFLUX_CU_TOKEN");
1396        assert_eq!(capture.source, "pixelflux");
1397        assert_eq!((capture.width, capture.height), (4, 5));
1398    }
1399
1400    #[test]
1401    fn request_token_is_portal_safe() {
1402        let token = request_token();
1403        assert!(token.starts_with("computer_use_linux_"));
1404        assert!(token.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'));
1405    }
1406
1407    #[test]
1408    fn reads_png_dimensions_from_ihdr() {
1409        let png = valid_png(3840, 1080);
1410
1411        assert_eq!(png_dimensions(&png).unwrap(), (3840, 1080));
1412    }
1413
1414    #[test]
1415    fn default_payload_downscales_long_edge() {
1416        let capture =
1417            prepare_screenshot_payload(raw_capture(solid_png(4000, 1000)), Default::default())
1418                .unwrap();
1419
1420        assert_eq!((capture.width, capture.height), (1920, 480));
1421        assert_eq!(
1422            (capture.coordinate_width, capture.coordinate_height),
1423            (4000, 1000)
1424        );
1425        assert!(capture.resized);
1426        assert!(capture.bytes <= DEFAULT_SCREENSHOT_MAX_BYTES);
1427        assert!(capture.data_url.starts_with("data:image/png;base64,"));
1428    }
1429
1430    #[test]
1431    fn larger_bounded_request_can_keep_more_detail() {
1432        let capture = prepare_screenshot_payload(
1433            raw_capture(solid_png(3000, 1000)),
1434            ScreenshotPayloadOptions {
1435                max_width: Some(3000),
1436                max_height: Some(3000),
1437                max_bytes: Some(DEFAULT_SCREENSHOT_MAX_BYTES),
1438                ..Default::default()
1439            },
1440        )
1441        .unwrap();
1442
1443        assert_eq!((capture.width, capture.height), (3000, 1000));
1444        assert_eq!(
1445            (capture.coordinate_width, capture.coordinate_height),
1446            (3000, 1000)
1447        );
1448        assert!(!capture.resized);
1449    }
1450
1451    #[test]
1452    fn byte_cap_downscales_until_payload_fits() {
1453        let capture = prepare_screenshot_payload(
1454            raw_capture(noisy_png(512, 512)),
1455            ScreenshotPayloadOptions {
1456                max_width: Some(512),
1457                max_height: Some(512),
1458                max_bytes: Some(20_000),
1459                ..Default::default()
1460            },
1461        )
1462        .unwrap();
1463
1464        assert!(capture.bytes <= 20_000);
1465        assert!(capture.width < 512);
1466        assert_eq!(
1467            (capture.coordinate_width, capture.coordinate_height),
1468            (512, 512)
1469        );
1470        assert!(capture.resized);
1471    }
1472
1473    #[test]
1474    fn jpeg_format_compresses_when_requested() {
1475        let capture = prepare_screenshot_payload(
1476            raw_capture(noisy_png(512, 512)),
1477            ScreenshotPayloadOptions {
1478                max_width: Some(512),
1479                max_height: Some(512),
1480                max_bytes: Some(DEFAULT_SCREENSHOT_MAX_BYTES),
1481                format: Some(ScreenshotOutputFormat::Jpeg),
1482                quality: Some(60),
1483                ..Default::default()
1484            },
1485        )
1486        .unwrap();
1487
1488        assert_eq!(capture.mime_type, "image/jpeg");
1489        assert_eq!(capture.format, ScreenshotOutputFormat::Jpeg);
1490        assert_eq!(capture.quality, Some(60));
1491        assert_eq!((capture.width, capture.height), (512, 512));
1492        assert_eq!(
1493            (capture.coordinate_width, capture.coordinate_height),
1494            (512, 512)
1495        );
1496        assert!(capture.bytes < capture.original_bytes);
1497        assert!(capture.data_url.starts_with("data:image/jpeg;base64,"));
1498    }
1499
1500    #[tokio::test]
1501    async fn cancelled_queued_capture_removes_its_owned_file() {
1502        let cache = std::env::var_os("XDG_CACHE_HOME")
1503            .map(PathBuf::from)
1504            .unwrap_or_else(|| PathBuf::from(std::env::var_os("HOME").unwrap()).join(".cache"));
1505        let path = cache.join(format!(
1506            "cul-cancelled-capture-{}.png",
1507            getrandom::u64().unwrap()
1508        ));
1509        fs::create_dir_all(&cache).unwrap();
1510        fs::write(&path, valid_png(1, 1)).unwrap();
1511        let (release, wait) = std::sync::mpsc::channel();
1512        let (started, ready) = tokio::sync::oneshot::channel();
1513        let busy = tokio::spawn(run_image_task(move || {
1514            started.send(()).unwrap();
1515            wait.recv().unwrap();
1516            Ok(())
1517        }));
1518        ready.await.unwrap();
1519        let mut queued = tokio::spawn(read_png_as_capture(
1520            path.clone(),
1521            "owned-test-capture",
1522            ScreenshotCleanup::DeletePath(path.clone()),
1523        ));
1524        assert!(tokio::time::timeout(Duration::from_millis(20), &mut queued)
1525            .await
1526            .is_err());
1527        queued.abort();
1528        assert!(queued.await.unwrap_err().is_cancelled());
1529        release.send(()).unwrap();
1530        busy.await.unwrap().unwrap();
1531        let removed = !path.exists();
1532        let _ = fs::remove_file(path);
1533        assert!(removed, "cancelled screenshot left its owned file behind");
1534    }
1535
1536    #[tokio::test]
1537    async fn portal_capture_removes_new_returned_path() {
1538        let path = test_path("portal-valid");
1539        let requested_at = SystemTime::now();
1540        // Linux filesystem timestamps can lag the wall clock by one tick.
1541        // A real portal round trip also separates request and file creation.
1542        tokio::time::sleep(Duration::from_millis(20)).await;
1543        fs::write(&path, valid_png(1, 1)).unwrap();
1544        let capture = read_portal_png_as_capture(
1545            path.clone(),
1546            PortalScreenshotRequest {
1547                requested_at,
1548                pictures: None,
1549            },
1550        )
1551        .await
1552        .unwrap();
1553        assert_eq!(capture.source, "xdg-desktop-portal");
1554        let retained = path.exists();
1555        let _ = fs::remove_file(&path);
1556        assert!(!retained, "portal screenshot was left behind");
1557    }
1558
1559    #[tokio::test]
1560    async fn portal_capture_removes_new_invalid_returned_path() {
1561        let path = test_path("portal-invalid");
1562        let requested_at = SystemTime::now();
1563        // Linux filesystem timestamps can lag the wall clock by one tick.
1564        // A real portal round trip also separates request and file creation.
1565        tokio::time::sleep(Duration::from_millis(20)).await;
1566        fs::write(&path, b"").unwrap();
1567        let error = read_portal_png_as_capture(
1568            path.clone(),
1569            PortalScreenshotRequest {
1570                requested_at,
1571                pictures: None,
1572            },
1573        )
1574        .await
1575        .unwrap_err();
1576        assert!(error.to_string().contains("screenshot file was empty"));
1577        let retained = path.exists();
1578        let _ = fs::remove_file(&path);
1579        assert!(!retained, "failed portal screenshot was left behind");
1580    }
1581
1582    #[tokio::test]
1583    async fn portal_capture_preserves_preexisting_returned_path() {
1584        let path = test_path("portal-existing");
1585        fs::write(&path, valid_png(1, 1)).unwrap();
1586        let requested_at = SystemTime::now();
1587        let capture = read_portal_png_as_capture(
1588            path.clone(),
1589            PortalScreenshotRequest {
1590                requested_at,
1591                pictures: None,
1592            },
1593        )
1594        .await
1595        .unwrap();
1596        assert_eq!(capture.source, "xdg-desktop-portal");
1597        assert!(path.exists(), "preexisting user image was removed");
1598        let _ = fs::remove_file(path);
1599    }
1600
1601    #[tokio::test]
1602    async fn portal_capture_cleans_same_tick_picture_and_preserves_existing_name() {
1603        let directory = test_path("portal-pictures");
1604        fs::create_dir_all(&directory).unwrap();
1605        let existing = directory.join("existing.png");
1606        fs::write(&existing, valid_png(1, 1)).unwrap();
1607        let pictures = PortalPicturesSnapshot::new(directory.clone()).unwrap();
1608        let path = directory.join("new.png");
1609        let request = PortalScreenshotRequest {
1610            requested_at: SystemTime::now(),
1611            pictures: Some(pictures),
1612        };
1613        fs::write(&path, valid_png(1, 1)).unwrap();
1614        let capture = read_portal_png_as_capture(path.clone(), request)
1615            .await
1616            .unwrap();
1617        assert_eq!(capture.source, "xdg-desktop-portal");
1618        assert!(!path.exists(), "same-tick portal capture was left behind");
1619        let pictures = PortalPicturesSnapshot::new(directory.clone()).unwrap();
1620        fs::remove_file(&existing).unwrap();
1621        fs::write(&existing, valid_png(1, 1)).unwrap();
1622        let request = PortalScreenshotRequest {
1623            requested_at: UNIX_EPOCH,
1624            pictures: Some(pictures),
1625        };
1626        read_portal_png_as_capture(existing.clone(), request)
1627            .await
1628            .unwrap();
1629        assert!(existing.exists(), "preexisting filename was removed");
1630        fs::remove_dir_all(directory).unwrap();
1631    }
1632
1633    #[test]
1634    fn portal_cleanup_preserves_a_replacement_file() {
1635        let path = test_path("portal-replaced");
1636        fs::write(&path, valid_png(1, 1)).unwrap();
1637        let created = fs::metadata(&path).unwrap().created().unwrap();
1638        let cleanup = OwnedScreenshotCleanup::new(ScreenshotCleanup::PortalPath {
1639            path: path.clone(),
1640            request: PortalScreenshotRequest {
1641                requested_at: created,
1642                pictures: None,
1643            },
1644        });
1645        fs::remove_file(&path).unwrap();
1646        fs::write(&path, b"user replacement").unwrap();
1647        drop(cleanup);
1648        let result = fs::read(&path);
1649        let _ = fs::remove_file(&path);
1650        assert_eq!(result.unwrap(), b"user replacement");
1651    }
1652
1653    #[tokio::test]
1654    async fn screenshot_reader_rejects_symlinks() {
1655        let target = test_path("symlink-target");
1656        let link = test_path("symlink-link");
1657        fs::write(&target, valid_png(1, 1)).unwrap();
1658        std::os::unix::fs::symlink(&target, &link).unwrap();
1659
1660        let error = read_png_as_capture(link.clone(), "test", ScreenshotCleanup::Preserve)
1661            .await
1662            .unwrap_err();
1663
1664        assert!(error.to_string().contains("failed to open screenshot file"));
1665        let _ = fs::remove_file(link);
1666        let _ = fs::remove_file(target);
1667    }
1668
1669    #[tokio::test]
1670    async fn screenshot_reader_rejects_oversized_source_files() {
1671        let path = test_path("oversized-source");
1672        let file = fs::File::create(&path).unwrap();
1673        file.set_len(MAX_SCREENSHOT_SOURCE_BYTES + 1).unwrap();
1674
1675        let error = read_png_as_capture(path.clone(), "test", ScreenshotCleanup::Preserve)
1676            .await
1677            .unwrap_err();
1678
1679        assert!(error.to_string().contains("over the"));
1680        let _ = fs::remove_file(path);
1681    }
1682
1683    #[test]
1684    fn png_dimensions_reject_decompression_bomb_dimensions() {
1685        let png = valid_png(u32::MAX, u32::MAX);
1686
1687        assert!(png_dimensions(&png)
1688            .unwrap_err()
1689            .to_string()
1690            .contains("pixel source limit"));
1691    }
1692
1693    #[tokio::test]
1694    async fn gnome_capture_deletes_backend_temp_path_on_success() {
1695        let path = test_path("gnome-valid");
1696        fs::write(&path, valid_png(1, 1)).unwrap();
1697
1698        let capture = read_png_as_capture(
1699            path.clone(),
1700            "gnome-shell",
1701            ScreenshotCleanup::DeletePath(path.clone()),
1702        )
1703        .await
1704        .unwrap();
1705
1706        assert_eq!(capture.source, "gnome-shell");
1707        assert!(!path.exists());
1708    }
1709
1710    #[tokio::test]
1711    async fn gnome_capture_deletes_backend_temp_path_on_parse_failure() {
1712        let path = test_path("gnome-invalid");
1713        fs::write(&path, b"").unwrap();
1714
1715        let error = read_png_as_capture(
1716            path.clone(),
1717            "gnome-shell",
1718            ScreenshotCleanup::DeletePath(path.clone()),
1719        )
1720        .await
1721        .unwrap_err();
1722
1723        assert!(error.to_string().contains("screenshot file was empty"));
1724        assert!(!path.exists());
1725    }
1726
1727    #[test]
1728    fn gnome_failure_cleanup_removes_requested_temp_path() {
1729        let path = test_path("gnome-pre-read-failure");
1730        fs::write(&path, b"partial").unwrap();
1731
1732        cleanup_gnome_requested_path(&path);
1733
1734        assert!(!path.exists());
1735    }
1736
1737    #[tokio::test]
1738    async fn gnome_deletes_requested_temp_path_and_preserves_unexpected_returned_path() {
1739        let requested = test_path("gnome-requested");
1740        let returned = test_path("gnome-returned");
1741        fs::write(&requested, b"partial").unwrap();
1742        fs::write(&returned, valid_png(1, 1)).unwrap();
1743
1744        let capture = read_png_as_capture(
1745            returned.clone(),
1746            "gnome-shell",
1747            ScreenshotCleanup::DeletePath(requested.clone()),
1748        )
1749        .await
1750        .unwrap();
1751
1752        assert_eq!(capture.source, "gnome-shell");
1753        assert!(!requested.exists());
1754        assert!(returned.exists());
1755        let _ = fs::remove_file(returned);
1756    }
1757}