Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
352
crates/luxe-tools/src/screenshot/browser.rs
Normal file
352
crates/luxe-tools/src/screenshot/browser.rs
Normal file
@@ -0,0 +1,352 @@
|
||||
//! Headless-browser capture for `mode=url` — renders a page (e.g. a local dev server) to PNG.
|
||||
//!
|
||||
//! Shells out to a headless Chrome/Chromium/Edge rather than embedding a CDP client, matching the
|
||||
//! native-tools philosophy of the rest of the screenshot backend.
|
||||
//!
|
||||
//! Model-supplied URLs are untrusted, so `mode=url` reuses the same [`crate::ssrf`] guard as
|
||||
//! `web_fetch`: private-network and cloud-metadata hosts are refused, `file://` is refused, and
|
||||
//! Chrome's own DNS is pinned to the address we validated so a rebind can't slip a different one past
|
||||
//! the check. **Loopback is allowed**, because capturing a dev server on this machine is the reason
|
||||
//! URL mode exists — see [`crate::ssrf`] for why that costs nothing next to an unrestricted `bash`.
|
||||
//! `LUXE_WEB_ALLOW_PRIVATE=1` remains the opt-out for a LAN host or a `file://` capture.
|
||||
|
||||
use anyhow::{anyhow, bail, Context, Result};
|
||||
use std::path::Path;
|
||||
use tokio::process::Command;
|
||||
|
||||
use super::capture::which;
|
||||
|
||||
/// Renders `url` at `width`x`height`, waiting `wait_ms` for it to settle, into the PNG at `out`.
|
||||
///
|
||||
/// Chrome runs on a throwaway profile under `<cwd>/.luxe/browser/`, removed afterwards, so a page
|
||||
/// never sees the user's cookies or a previous capture's.
|
||||
pub(super) async fn capture_url(
|
||||
url: &str,
|
||||
size: (u32, u32),
|
||||
wait_ms: u32,
|
||||
out: &Path,
|
||||
cwd: &Path,
|
||||
) -> Result<()> {
|
||||
let resolver_rule = validate_capture_url(url).await?;
|
||||
let browser = find_browser()
|
||||
.ok_or_else(|| anyhow!("no headless browser found (install Chrome, Chromium, or Edge)"))?;
|
||||
let out = out.to_str().ok_or_else(|| anyhow!("output path is not valid UTF-8"))?;
|
||||
let profile = Profile::create(cwd)?;
|
||||
let capture = ChromeCapture {
|
||||
url,
|
||||
width: size.0,
|
||||
height: size.1,
|
||||
wait_ms,
|
||||
out,
|
||||
resolver_rule,
|
||||
sandboxed: !sandbox_unavailable(
|
||||
luxe_core::isolation::running_as_root(),
|
||||
luxe_core::isolation::in_container(),
|
||||
),
|
||||
profile: &profile.0,
|
||||
};
|
||||
// `kill_on_drop` is what makes the engine's deadline and the user's interrupt actually reach
|
||||
// Chrome. Dropping this future is how a stopped tool call unwinds, and a browser aimed at a host
|
||||
// that accepts the connection and then answers nothing will otherwise sit there for the rest of
|
||||
// the session: `--virtual-time-budget` bounds the page's clock, not its network.
|
||||
let output = Command::new(&browser)
|
||||
.args(chrome_args(&capture))
|
||||
.kill_on_drop(true)
|
||||
.stdin(std::process::Stdio::null())
|
||||
.output()
|
||||
.await
|
||||
.with_context(|| format!("failed to run headless browser `{browser}`"))?;
|
||||
// Chrome exits 0 on a successful screenshot; some builds print to stderr even on success, so
|
||||
// fall back to checking the file was actually written.
|
||||
if !output.status.success() && !out_written(out) {
|
||||
bail!("headless `{browser}` failed: {}", String::from_utf8_lossy(&output.stderr).trim());
|
||||
}
|
||||
if !out_written(out) {
|
||||
bail!("headless `{browser}` produced no screenshot for {url}");
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Everything Chrome is told for one capture, apart so the flags are testable without a browser.
|
||||
struct ChromeCapture<'a> {
|
||||
url: &'a str,
|
||||
width: u32,
|
||||
height: u32,
|
||||
wait_ms: u32,
|
||||
out: &'a str,
|
||||
resolver_rule: Option<String>,
|
||||
sandboxed: bool,
|
||||
profile: &'a Path,
|
||||
}
|
||||
|
||||
fn chrome_args(capture: &ChromeCapture<'_>) -> Vec<String> {
|
||||
let mut args = vec![
|
||||
"--headless=new".to_string(),
|
||||
"--disable-gpu".to_string(),
|
||||
"--hide-scrollbars".to_string(),
|
||||
"--force-device-scale-factor=1".to_string(),
|
||||
format!("--user-data-dir={}", capture.profile.display()),
|
||||
format!("--window-size={},{}", capture.width, capture.height),
|
||||
format!("--virtual-time-budget={}", capture.wait_ms),
|
||||
format!("--screenshot={}", capture.out),
|
||||
];
|
||||
// a container workaround, not a default: the sandbox is what stands between a hostile page and
|
||||
// the user's desktop
|
||||
if !capture.sandboxed {
|
||||
args.push("--no-sandbox".to_string());
|
||||
}
|
||||
if let Some(rule) = &capture.resolver_rule {
|
||||
args.push(format!("--host-resolver-rules={rule}"));
|
||||
}
|
||||
args.push(capture.url.to_string());
|
||||
args
|
||||
}
|
||||
|
||||
/// A fresh browser profile directory, removed when the capture is done.
|
||||
struct Profile(std::path::PathBuf);
|
||||
|
||||
impl Profile {
|
||||
fn create(cwd: &Path) -> Result<Self> {
|
||||
static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
|
||||
let stamp = std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|elapsed| elapsed.as_nanos())
|
||||
.unwrap_or_default();
|
||||
let next = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
|
||||
let name = format!("profile-{}-{stamp}-{next}", std::process::id());
|
||||
let dir = cwd.join(".luxe").join("browser").join(name);
|
||||
std::fs::create_dir_all(&dir)
|
||||
.with_context(|| format!("could not create {}", dir.display()))?;
|
||||
Ok(Self(dir))
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for Profile {
|
||||
fn drop(&mut self) {
|
||||
if let Err(error) = std::fs::remove_dir_all(&self.0) {
|
||||
tracing::warn!(%error, profile = %self.0.display(), "could not remove a browser profile");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether Chrome's sandbox cannot start here: as root, or inside a container.
|
||||
fn sandbox_unavailable(root: bool, in_container: bool) -> bool {
|
||||
root || in_container
|
||||
}
|
||||
|
||||
fn out_written(out: &str) -> bool {
|
||||
std::fs::metadata(out).map(|meta| meta.len() > 0).unwrap_or(false)
|
||||
}
|
||||
|
||||
/// Validates a `mode=url` target against the SSRF guard and returns the Chrome
|
||||
/// `--host-resolver-rules` value ([`resolver_rule`]) that keeps the capture on that host.
|
||||
///
|
||||
/// Public and loopback origins pass; private-network and metadata hosts are refused, as is `file://`.
|
||||
/// When the guard is disabled wholesale we return `None` (no pinning) so an intentional LAN or file
|
||||
/// capture still works.
|
||||
async fn validate_capture_url(url: &str) -> Result<Option<String>> {
|
||||
if url.starts_with("file://") {
|
||||
if crate::ssrf::guard_disabled() {
|
||||
return Ok(None);
|
||||
}
|
||||
// Not a network fetch at all: this would hand a model-supplied path to a browser with the
|
||||
// whole filesystem in reach, which `read` already does properly, scoped to the project.
|
||||
bail!(
|
||||
"file:// captures are blocked: a browser given a local path can read anything this user \
|
||||
can. Use `read` for file contents, or serve the file over http:// and capture that. \
|
||||
LUXE_WEB_ALLOW_PRIVATE=1 overrides this."
|
||||
);
|
||||
}
|
||||
if !(url.starts_with("http://") || url.starts_with("https://")) {
|
||||
bail!("url must start with http:// or https:// (got '{url}')");
|
||||
}
|
||||
if crate::ssrf::guard_disabled() {
|
||||
return Ok(None);
|
||||
}
|
||||
let parsed = url::Url::parse(url).map_err(|e| anyhow!("invalid URL: {e}"))?;
|
||||
// Loopback allowed: a local dev server is what this mode is for.
|
||||
let addrs = crate::ssrf::resolve_validated(&parsed, crate::ssrf::LocalAccess::Allowed)
|
||||
.await
|
||||
.map_err(|e| anyhow!("{e}"))?;
|
||||
Ok(resolver_rule(&parsed, &addrs))
|
||||
}
|
||||
|
||||
/// The Chrome resolver rule for a capture of `url`: only its host resolves, so a page cannot
|
||||
/// redirect to or embed another one. The rule covers IP-literal hosts too: checked by hand against
|
||||
/// Chromium, an image at `http://127.0.0.1:<port>/` on a `localhost` page did not load under
|
||||
/// `MAP * ~NOTFOUND , EXCLUDE localhost`, and did without it.
|
||||
///
|
||||
/// A public name is pinned to the address that was checked, closing the rebinding gap. A loopback
|
||||
/// name is not pinned: Chrome's MAP takes one address, and choosing between `::1` and `127.0.0.1`
|
||||
/// on the user's behalf is how a dev server listening on the other one becomes unreachable.
|
||||
fn resolver_rule(url: &url::Url, addrs: &[std::net::SocketAddr]) -> Option<String> {
|
||||
let host = match url.host()? {
|
||||
url::Host::Domain(name) if !addrs.iter().all(|addr| addr.ip().is_loopback()) => {
|
||||
let addr = addrs.first()?;
|
||||
// bracketed, so an IPv6 replacement can never be read as host:port
|
||||
let ip = match addr.ip() {
|
||||
std::net::IpAddr::V6(ip) => format!("[{ip}]"),
|
||||
ip => ip.to_string(),
|
||||
};
|
||||
return Some(format!("MAP {name} {ip} , MAP * ~NOTFOUND"));
|
||||
}
|
||||
url::Host::Domain(name) => name.to_string(),
|
||||
url::Host::Ipv4(ip) => ip.to_string(),
|
||||
// bare, not bracketed: Chrome's EXCLUDE does not match `[::1]`
|
||||
url::Host::Ipv6(ip) => ip.to_string(),
|
||||
};
|
||||
Some(format!("MAP * ~NOTFOUND , EXCLUDE {host}"))
|
||||
}
|
||||
|
||||
/// Whether a headless browser is installed, for URL captures without a display.
|
||||
pub(super) fn is_available() -> bool {
|
||||
find_browser().is_some()
|
||||
}
|
||||
|
||||
/// Finds a headless-capable browser: PATH candidates first, then well-known OS install locations.
|
||||
fn find_browser() -> Option<String> {
|
||||
const CANDIDATES: &[&str] = &[
|
||||
"chromium",
|
||||
"chromium-browser",
|
||||
"google-chrome",
|
||||
"google-chrome-stable",
|
||||
"microsoft-edge",
|
||||
"brave",
|
||||
"brave-browser",
|
||||
];
|
||||
for candidate in CANDIDATES {
|
||||
if which(candidate) {
|
||||
return Some((*candidate).to_string());
|
||||
}
|
||||
}
|
||||
for path in well_known_paths() {
|
||||
if Path::new(path).is_file() {
|
||||
return Some(path.to_string());
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn well_known_paths() -> &'static [&'static str] {
|
||||
if cfg!(target_os = "macos") {
|
||||
&[
|
||||
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
|
||||
"/Applications/Chromium.app/Contents/MacOS/Chromium",
|
||||
"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
|
||||
]
|
||||
} else if cfg!(target_os = "windows") {
|
||||
&[
|
||||
r"C:\Program Files\Google\Chrome\Application\chrome.exe",
|
||||
r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
|
||||
r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
|
||||
]
|
||||
} else {
|
||||
&["/usr/bin/chromium", "/usr/bin/google-chrome", "/snap/bin/chromium"]
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
// These assume LUXE_WEB_ALLOW_PRIVATE is unset (the default, and the CI environment).
|
||||
#[tokio::test]
|
||||
async fn blocks_file_scheme_by_default() {
|
||||
let err = validate_capture_url("file:///etc/passwd").await.unwrap_err().to_string();
|
||||
assert!(err.contains("file://"), "file:// must be refused: {err}");
|
||||
assert!(err.contains("`read`"), "and point at the tool that does this properly: {err}");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn rejects_non_web_scheme() {
|
||||
assert!(validate_capture_url("ftp://example.com/x").await.is_err());
|
||||
assert!(validate_capture_url("data:text/html,hi").await.is_err());
|
||||
}
|
||||
|
||||
/// The capture this tool advertises: a dev server on this machine, with no env var set first and
|
||||
/// no session already running that could have inherited one. Every spelling a dev server prints,
|
||||
/// including the bracketed IPv6 literal Vite and Astro report.
|
||||
#[tokio::test]
|
||||
async fn captures_a_local_dev_server() {
|
||||
for url in ["http://127.0.0.1:4321/", "http://localhost:4321/", "http://[::1]:4321/"] {
|
||||
validate_capture_url(url)
|
||||
.await
|
||||
.unwrap_or_else(|error| panic!("{url} must be capturable: {error:#}"));
|
||||
}
|
||||
// Nothing local is pinned: Chrome's MAP takes one address, and choosing between `::1` and
|
||||
// `127.0.0.1` on the user's behalf is how a dev server on the other one becomes unreachable.
|
||||
// Every other name is unresolvable, so the page cannot pull in another host.
|
||||
for (url, host) in [
|
||||
("http://localhost:4321/", "localhost"),
|
||||
("http://127.0.0.1:4321/", "127.0.0.1"),
|
||||
("http://[::1]:4321/", "::1"),
|
||||
] {
|
||||
let rule = validate_capture_url(url).await.unwrap();
|
||||
assert_eq!(
|
||||
rule.as_deref(),
|
||||
Some(&*format!("MAP * ~NOTFOUND , EXCLUDE {host}")),
|
||||
"{url}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn blocks_private_and_metadata_hosts() {
|
||||
assert!(validate_capture_url("http://192.168.0.5/admin").await.is_err());
|
||||
assert!(validate_capture_url("http://10.0.0.1/").await.is_err());
|
||||
assert!(validate_capture_url("http://169.254.169.254/latest/meta-data").await.is_err());
|
||||
}
|
||||
|
||||
/// A public *IP literal* needs no pin — there is no lookup between us and Chrome to rebind. A
|
||||
/// `MAP 1.1.1.1 1.1.1.1` rule would map a host Chrome never resolves.
|
||||
#[tokio::test]
|
||||
async fn a_public_ip_literal_needs_no_resolver_pin() {
|
||||
let rule = validate_capture_url("http://1.1.1.1/").await.unwrap();
|
||||
assert_eq!(rule.as_deref(), Some("MAP * ~NOTFOUND , EXCLUDE 1.1.1.1"));
|
||||
}
|
||||
|
||||
/// A pinned public name resolves to the address that was checked, and nothing else resolves:
|
||||
/// a page that redirects to or embeds the metadata endpoint or a LAN host gets no answer.
|
||||
#[test]
|
||||
fn a_pinned_name_is_the_only_one_that_resolves() {
|
||||
let addr = "93.184.216.34:443".parse().unwrap();
|
||||
let rule = resolver_rule(&url::Url::parse("https://example.com/").unwrap(), &[addr]);
|
||||
assert_eq!(rule.as_deref(), Some("MAP example.com 93.184.216.34 , MAP * ~NOTFOUND"));
|
||||
// an IPv6 replacement is bracketed, or Chrome cannot tell its colons from a port
|
||||
let addr = "[2606:2800:220:1::1]:443".parse().unwrap();
|
||||
let rule = resolver_rule(&url::Url::parse("https://example.com/").unwrap(), &[addr]);
|
||||
assert_eq!(rule.as_deref(), Some("MAP example.com [2606:2800:220:1::1] , MAP * ~NOTFOUND"));
|
||||
}
|
||||
|
||||
/// The flags Chrome gets: a throwaway profile, the resolver rule, and `--no-sandbox` only where
|
||||
/// the sandbox cannot run.
|
||||
#[test]
|
||||
fn chrome_args_carry_the_profile_the_rule_and_the_sandbox_choice() {
|
||||
let profile = std::path::Path::new("/project/.luxe/browser/profile-1");
|
||||
let capture = ChromeCapture {
|
||||
url: "http://localhost:4321/",
|
||||
width: 800,
|
||||
height: 600,
|
||||
wait_ms: 500,
|
||||
out: "/project/.luxe/screenshots/shot.png",
|
||||
resolver_rule: Some("MAP * ~NOTFOUND , EXCLUDE localhost".into()),
|
||||
sandboxed: true,
|
||||
profile,
|
||||
};
|
||||
let args = chrome_args(&capture);
|
||||
assert!(args.contains(&"--user-data-dir=/project/.luxe/browser/profile-1".to_string()));
|
||||
assert!(args.contains(&"--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE localhost".into()));
|
||||
assert!(!args.contains(&"--no-sandbox".to_string()), "{args:?}");
|
||||
assert_eq!(args.last().map(String::as_str), Some("http://localhost:4321/"));
|
||||
let unsandboxed = chrome_args(&ChromeCapture { sandboxed: false, ..capture });
|
||||
assert!(unsandboxed.contains(&"--no-sandbox".to_string()), "{unsandboxed:?}");
|
||||
}
|
||||
|
||||
/// Root and containers are where Chrome's sandbox cannot start; everywhere else it stays on.
|
||||
#[test]
|
||||
fn the_sandbox_is_dropped_only_where_it_cannot_run() {
|
||||
assert!(sandbox_unavailable(true, false));
|
||||
assert!(sandbox_unavailable(false, true));
|
||||
assert!(!sandbox_unavailable(false, false));
|
||||
}
|
||||
}
|
||||
460
crates/luxe-tools/src/screenshot/capture.rs
Normal file
460
crates/luxe-tools/src/screenshot/capture.rs
Normal file
@@ -0,0 +1,460 @@
|
||||
//! Native screen capture — OS/display-server detection and per-platform capture commands.
|
||||
//!
|
||||
//! Shells out to the platform's native tool rather than linking a capture crate, keeping the
|
||||
//! dependency surface tiny and the gate clean: grim (+ hyprctl) on Wayland, maim/scrot/ImageMagick
|
||||
//! on X11, `screencapture` on macOS, and PowerShell + System.Drawing on Windows. Each writes a PNG
|
||||
//! that the tool then reads and returns inline.
|
||||
|
||||
use anyhow::{anyhow, bail, Context, Result};
|
||||
use std::path::Path;
|
||||
use tokio::process::Command;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub(super) enum DisplayBackend {
|
||||
/// Wayland compositor that is Hyprland (window geometry via `hyprctl`).
|
||||
WaylandHyprland,
|
||||
/// Any other wlroots-ish Wayland compositor (grim works; per-window needs help).
|
||||
Wayland,
|
||||
/// X11 (maim/scrot/import).
|
||||
X11,
|
||||
/// macOS (`screencapture`).
|
||||
MacOS,
|
||||
/// Windows (PowerShell + System.Drawing).
|
||||
Windows,
|
||||
/// Nothing usable detected.
|
||||
Unknown,
|
||||
}
|
||||
|
||||
pub(super) enum CaptureTarget {
|
||||
/// The whole screen, optionally a single named output/monitor.
|
||||
Fullscreen { output: Option<String> },
|
||||
/// An explicit region, given as `"X,Y WxH"`.
|
||||
Region { geometry: String },
|
||||
/// A window matched by title substring, or the active window when `None`.
|
||||
Window { title: Option<String> },
|
||||
}
|
||||
|
||||
/// Detects the display backend from the environment and target OS.
|
||||
pub(super) fn detect_backend() -> DisplayBackend {
|
||||
if cfg!(target_os = "macos") {
|
||||
return DisplayBackend::MacOS;
|
||||
}
|
||||
if cfg!(target_os = "windows") {
|
||||
return DisplayBackend::Windows;
|
||||
}
|
||||
let wayland = std::env::var_os("WAYLAND_DISPLAY").is_some();
|
||||
let hyprland = std::env::var_os("HYPRLAND_INSTANCE_SIGNATURE").is_some();
|
||||
if wayland {
|
||||
if hyprland {
|
||||
DisplayBackend::WaylandHyprland
|
||||
} else {
|
||||
DisplayBackend::Wayland
|
||||
}
|
||||
} else if std::env::var_os("DISPLAY").is_some() {
|
||||
DisplayBackend::X11
|
||||
} else {
|
||||
DisplayBackend::Unknown
|
||||
}
|
||||
}
|
||||
|
||||
/// Human-readable name for error messages.
|
||||
pub(super) fn backend_label(backend: DisplayBackend) -> &'static str {
|
||||
match backend {
|
||||
DisplayBackend::WaylandHyprland => "Wayland (Hyprland)",
|
||||
DisplayBackend::Wayland => "Wayland",
|
||||
DisplayBackend::X11 => "X11",
|
||||
DisplayBackend::MacOS => "macOS",
|
||||
DisplayBackend::Windows => "Windows",
|
||||
DisplayBackend::Unknown => "unknown display server",
|
||||
}
|
||||
}
|
||||
|
||||
/// A parsed pixel rectangle.
|
||||
struct Rect {
|
||||
x: i64,
|
||||
y: i64,
|
||||
w: i64,
|
||||
h: i64,
|
||||
}
|
||||
|
||||
/// Parses a `"X,Y WxH"` geometry string (the same shape grim accepts).
|
||||
fn parse_geometry(geometry: &str) -> Result<Rect> {
|
||||
let (pos, size) = geometry
|
||||
.split_once(' ')
|
||||
.ok_or_else(|| anyhow!("geometry must look like 'X,Y WxH', got '{geometry}'"))?;
|
||||
let (x, y) = pos.split_once(',').ok_or_else(|| anyhow!("bad position in '{geometry}'"))?;
|
||||
let (w, h) = size
|
||||
.split_once(['x', 'X'])
|
||||
.ok_or_else(|| anyhow!("bad size in '{geometry}' (want WxH)"))?;
|
||||
let parse = |v: &str, what: &str| {
|
||||
v.trim().parse::<i64>().with_context(|| format!("invalid {what} in geometry '{geometry}'"))
|
||||
};
|
||||
Ok(Rect { x: parse(x, "x")?, y: parse(y, "y")?, w: parse(w, "width")?, h: parse(h, "height")? })
|
||||
}
|
||||
|
||||
/// Whether this backend has a program that can actually take the picture.
|
||||
///
|
||||
/// A display is not a capture tool. `detect_backend` answers on the strength of `$WAYLAND_DISPLAY`
|
||||
/// or `$DISPLAY` alone, and neither Wayland nor X11 ships a screenshot binary — so a box with a
|
||||
/// desktop and no `grim` must not advertise `screenshot` to the model and then fail every desktop
|
||||
/// capture with "install `grim`". macOS and Windows carry theirs in the OS.
|
||||
pub(super) fn desktop_capture_available(backend: DisplayBackend) -> bool {
|
||||
match backend {
|
||||
DisplayBackend::WaylandHyprland | DisplayBackend::Wayland => which("grim"),
|
||||
DisplayBackend::X11 => which("maim") || which("scrot") || which("import"),
|
||||
// `screencapture` and PowerShell ship with the OS.
|
||||
DisplayBackend::MacOS | DisplayBackend::Windows => true,
|
||||
DisplayBackend::Unknown => false,
|
||||
}
|
||||
}
|
||||
|
||||
/// Captures `target` to the PNG file at `out`, routing to the backend's native tool.
|
||||
pub(super) async fn capture(
|
||||
backend: DisplayBackend,
|
||||
target: &CaptureTarget,
|
||||
out: &Path,
|
||||
) -> Result<()> {
|
||||
match backend {
|
||||
DisplayBackend::WaylandHyprland | DisplayBackend::Wayland => {
|
||||
capture_wayland(backend, target, out).await
|
||||
}
|
||||
DisplayBackend::X11 => capture_x11(target, out).await,
|
||||
DisplayBackend::MacOS => capture_macos(target, out).await,
|
||||
DisplayBackend::Windows => capture_windows(target, out).await,
|
||||
DisplayBackend::Unknown => bail!(
|
||||
"no supported display server detected (neither $WAYLAND_DISPLAY nor $DISPLAY is set)"
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
// === Wayland (grim + hyprctl) ===
|
||||
|
||||
async fn capture_wayland(
|
||||
backend: DisplayBackend,
|
||||
target: &CaptureTarget,
|
||||
out: &Path,
|
||||
) -> Result<()> {
|
||||
require("grim", "install `grim` (and `slurp` for interactive regions)")?;
|
||||
let out = path_str(out)?;
|
||||
match target {
|
||||
CaptureTarget::Fullscreen { output } => {
|
||||
let mut args: Vec<String> = Vec::new();
|
||||
if let Some(name) = output {
|
||||
args.push("-o".into());
|
||||
args.push(name.clone());
|
||||
}
|
||||
args.push(out);
|
||||
run("grim", &args).await
|
||||
}
|
||||
CaptureTarget::Region { geometry } => {
|
||||
// grim consumes the "X,Y WxH" shape directly; validate it first for a clear error.
|
||||
parse_geometry(geometry)?;
|
||||
run("grim", &["-g".into(), geometry.clone(), out]).await
|
||||
}
|
||||
CaptureTarget::Window { title } => {
|
||||
if backend != DisplayBackend::WaylandHyprland {
|
||||
bail!(
|
||||
"per-window capture on Wayland is only supported under Hyprland; \
|
||||
use mode=region with an explicit geometry instead"
|
||||
);
|
||||
}
|
||||
let geometry = hyprland_window_geometry(title.as_deref()).await?;
|
||||
run("grim", &["-g".into(), geometry, out]).await
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Reads a window's `X,Y WxH` geometry from `hyprctl` (active window, or the first title match).
|
||||
async fn hyprland_window_geometry(title: Option<&str>) -> Result<String> {
|
||||
let query = if title.is_some() { "clients" } else { "activewindow" };
|
||||
let output = Command::new("hyprctl")
|
||||
.args(["-j", query])
|
||||
.kill_on_drop(true)
|
||||
.stdin(std::process::Stdio::null())
|
||||
.output()
|
||||
.await
|
||||
.context("failed to run `hyprctl` for window geometry")?;
|
||||
if !output.status.success() {
|
||||
bail!("`hyprctl -j {query}` failed: {}", String::from_utf8_lossy(&output.stderr).trim());
|
||||
}
|
||||
let json: serde_json::Value =
|
||||
serde_json::from_slice(&output.stdout).context("could not parse hyprctl JSON")?;
|
||||
let window = match title {
|
||||
Some(needle) => json
|
||||
.as_array()
|
||||
.and_then(|clients| {
|
||||
clients
|
||||
.iter()
|
||||
.find(|client| client["title"].as_str().is_some_and(|t| t.contains(needle)))
|
||||
})
|
||||
.ok_or_else(|| anyhow!("no Hyprland window whose title contains '{needle}'"))?,
|
||||
None => &json,
|
||||
};
|
||||
let at = &window["at"];
|
||||
let size = &window["size"];
|
||||
let field = |value: &serde_json::Value, index: usize| -> Result<i64> {
|
||||
value[index].as_i64().ok_or_else(|| anyhow!("hyprctl returned no window geometry"))
|
||||
};
|
||||
Ok(format!("{},{} {}x{}", field(at, 0)?, field(at, 1)?, field(size, 0)?, field(size, 1)?))
|
||||
}
|
||||
|
||||
// === X11 (maim / scrot / ImageMagick import) ===
|
||||
|
||||
async fn capture_x11(target: &CaptureTarget, out: &Path) -> Result<()> {
|
||||
let out = path_str(out)?;
|
||||
match target {
|
||||
CaptureTarget::Fullscreen { .. } => {
|
||||
try_candidates(
|
||||
&[
|
||||
("maim", vec![out.clone()]),
|
||||
("scrot", vec!["-o".into(), out.clone()]),
|
||||
("import", vec!["-window".into(), "root".into(), out.clone()]),
|
||||
],
|
||||
"install one of: maim, scrot, or ImageMagick (`import`)",
|
||||
)
|
||||
.await
|
||||
}
|
||||
CaptureTarget::Region { geometry } => {
|
||||
let r = parse_geometry(geometry)?;
|
||||
let maim_geo = format!("{}x{}+{}+{}", r.w, r.h, r.x, r.y);
|
||||
let scrot_geo = format!("{},{},{},{}", r.x, r.y, r.w, r.h);
|
||||
let crop = format!("{}x{}+{}+{}", r.w, r.h, r.x, r.y);
|
||||
try_candidates(
|
||||
&[
|
||||
("maim", vec!["-g".into(), maim_geo, out.clone()]),
|
||||
("scrot", vec!["-a".into(), scrot_geo, "-o".into(), out.clone()]),
|
||||
(
|
||||
"import",
|
||||
vec!["-window".into(), "root".into(), "-crop".into(), crop, out.clone()],
|
||||
),
|
||||
],
|
||||
"install one of: maim, scrot, or ImageMagick (`import`)",
|
||||
)
|
||||
.await
|
||||
}
|
||||
CaptureTarget::Window { title } => {
|
||||
let id = x11_window_id(title.as_deref()).await?;
|
||||
try_candidates(
|
||||
&[
|
||||
("maim", vec!["-i".into(), id.clone(), out.clone()]),
|
||||
("import", vec!["-window".into(), id, out.clone()]),
|
||||
],
|
||||
"install `maim` (with `xdotool`) or ImageMagick (`import`)",
|
||||
)
|
||||
.await
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Resolves an X11 window id (hex) via `xdotool`, by title or the active window.
|
||||
async fn x11_window_id(title: Option<&str>) -> Result<String> {
|
||||
require("xdotool", "install `xdotool` for per-window X11 capture")?;
|
||||
let args: Vec<&str> = match title {
|
||||
Some(needle) => vec!["search", "--name", "--limit", "1", needle],
|
||||
None => vec!["getactivewindow"],
|
||||
};
|
||||
let output = Command::new("xdotool")
|
||||
.args(&args)
|
||||
.kill_on_drop(true)
|
||||
.stdin(std::process::Stdio::null())
|
||||
.output()
|
||||
.await
|
||||
.context("failed to run xdotool")?;
|
||||
if !output.status.success() {
|
||||
bail!("xdotool could not resolve the window (title match failed?)");
|
||||
}
|
||||
let id =
|
||||
String::from_utf8_lossy(&output.stdout).trim().lines().next().unwrap_or("").to_string();
|
||||
if id.is_empty() {
|
||||
bail!("no matching X11 window found");
|
||||
}
|
||||
Ok(id)
|
||||
}
|
||||
|
||||
// === macOS (screencapture) ===
|
||||
|
||||
async fn capture_macos(target: &CaptureTarget, out: &Path) -> Result<()> {
|
||||
let out = path_str(out)?;
|
||||
match target {
|
||||
CaptureTarget::Fullscreen { .. } => run("screencapture", &["-x".into(), out]).await,
|
||||
CaptureTarget::Region { geometry } => {
|
||||
let r = parse_geometry(geometry)?;
|
||||
let rect = format!("{},{},{},{}", r.x, r.y, r.w, r.h);
|
||||
run("screencapture", &["-x".into(), "-R".into(), rect, out]).await
|
||||
}
|
||||
CaptureTarget::Window { .. } => bail!(
|
||||
"per-window capture on macOS needs a window id; use mode=fullscreen or mode=region"
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
// === Windows (PowerShell + System.Drawing) ===
|
||||
|
||||
async fn capture_windows(target: &CaptureTarget, out: &Path) -> Result<()> {
|
||||
let out = path_str(out)?;
|
||||
let script = match target {
|
||||
CaptureTarget::Fullscreen { .. } => windows_capture_script("virtual", &out),
|
||||
CaptureTarget::Region { geometry } => {
|
||||
let r = parse_geometry(geometry)?;
|
||||
windows_capture_script(&format!("{},{},{},{}", r.x, r.y, r.w, r.h), &out)
|
||||
}
|
||||
CaptureTarget::Window { .. } => bail!(
|
||||
"per-window capture on Windows is not supported yet; use mode=fullscreen or mode=region"
|
||||
),
|
||||
};
|
||||
run("powershell", &["-NoProfile".into(), "-NonInteractive".into(), "-Command".into(), script])
|
||||
.await
|
||||
}
|
||||
|
||||
/// Builds a PowerShell one-liner that captures the virtual screen (or `x,y,w,h`) to `out`.
|
||||
fn windows_capture_script(rect: &str, out: &str) -> String {
|
||||
let bounds = if rect == "virtual" {
|
||||
"$r=[System.Windows.Forms.SystemInformation]::VirtualScreen".to_string()
|
||||
} else {
|
||||
let parts: Vec<&str> = rect.split(',').collect();
|
||||
format!(
|
||||
"$r=New-Object System.Drawing.Rectangle({},{},{},{})",
|
||||
parts.first().unwrap_or(&"0"),
|
||||
parts.get(1).unwrap_or(&"0"),
|
||||
parts.get(2).unwrap_or(&"0"),
|
||||
parts.get(3).unwrap_or(&"0")
|
||||
)
|
||||
};
|
||||
format!(
|
||||
"Add-Type -AssemblyName System.Windows.Forms,System.Drawing; {bounds}; \
|
||||
$bmp=New-Object System.Drawing.Bitmap($r.Width,$r.Height); \
|
||||
$g=[System.Drawing.Graphics]::FromImage($bmp); \
|
||||
$g.CopyFromScreen($r.Left,$r.Top,0,0,$bmp.Size); \
|
||||
$bmp.Save('{out}',[System.Drawing.Imaging.ImageFormat]::Png); $g.Dispose(); $bmp.Dispose()"
|
||||
)
|
||||
}
|
||||
|
||||
// === Shared helpers ===
|
||||
|
||||
/// Runs `program` with `args`, surfacing stderr on failure and a clear hint when it's missing.
|
||||
///
|
||||
/// `kill_on_drop` throughout: a stopped tool call unwinds by dropping its future, and a capture
|
||||
/// helper waiting on a compositor that never answers has to go with it rather than linger. Stdin is
|
||||
/// closed for the same reason it is in `bash` — a helper that reads it would eat the user's
|
||||
/// keystrokes out from under the TUI.
|
||||
/// How long a native capture may take. Each is sub-second on a screen that is drawing; one that is
|
||||
/// locked or asleep draws no frames, and `grim` waits for one indefinitely, so a capture that has not
|
||||
/// finished by now never will.
|
||||
const CAPTURE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(15);
|
||||
|
||||
async fn run(program: &str, args: &[String]) -> Result<()> {
|
||||
run_within(program, args, CAPTURE_DEADLINE).await
|
||||
}
|
||||
|
||||
async fn run_within(program: &str, args: &[String], deadline: std::time::Duration) -> Result<()> {
|
||||
let child = Command::new(program)
|
||||
.args(args)
|
||||
.kill_on_drop(true)
|
||||
.stdin(std::process::Stdio::null())
|
||||
.output();
|
||||
// Dropping the future on timeout kills the capture, `kill_on_drop` being what makes it so
|
||||
let Ok(output) = tokio::time::timeout(deadline, child).await else {
|
||||
bail!(
|
||||
"`{program}` produced no image within {}s. A screen that is locked or asleep draws no \
|
||||
frames to capture; wake it and try again.",
|
||||
deadline.as_secs()
|
||||
);
|
||||
};
|
||||
let output = output.map_err(|err| {
|
||||
if err.kind() == std::io::ErrorKind::NotFound {
|
||||
anyhow!("`{program}` is not installed or not on PATH")
|
||||
} else {
|
||||
anyhow!("failed to spawn `{program}`: {err}")
|
||||
}
|
||||
})?;
|
||||
if !output.status.success() {
|
||||
bail!("`{program}` failed: {}", String::from_utf8_lossy(&output.stderr).trim());
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Tries each `(program, args)` candidate in order, returning on the first success. Reports the
|
||||
/// last error (and `hint`) when they all fail or none are installed.
|
||||
async fn try_candidates(candidates: &[(&str, Vec<String>)], hint: &str) -> Result<()> {
|
||||
let mut last_error = None;
|
||||
for (program, args) in candidates {
|
||||
if !which(program) {
|
||||
continue;
|
||||
}
|
||||
match run(program, args).await {
|
||||
Ok(()) => return Ok(()),
|
||||
Err(err) => last_error = Some(err),
|
||||
}
|
||||
}
|
||||
match last_error {
|
||||
Some(err) => Err(err),
|
||||
None => bail!("no capture tool available — {hint}"),
|
||||
}
|
||||
}
|
||||
|
||||
/// Errors with an install hint when `program` isn't on PATH.
|
||||
fn require(program: &str, hint: &str) -> Result<()> {
|
||||
if which(program) {
|
||||
Ok(())
|
||||
} else {
|
||||
bail!("`{program}` is not installed or not on PATH — {hint}")
|
||||
}
|
||||
}
|
||||
|
||||
/// True when `program` can be run.
|
||||
///
|
||||
/// Defers to [`luxe_core::program`], which is the one place that knows what "runnable" means on each
|
||||
/// platform — the executable bit on unix, a `PATHEXT` suffix on Windows — and which also looks in the
|
||||
/// install directories a package manager uses but a `PATH` often misses.
|
||||
pub(super) fn which(program: &str) -> bool {
|
||||
luxe_core::program::is_available(program)
|
||||
}
|
||||
|
||||
fn path_str(path: &Path) -> Result<String> {
|
||||
path.to_str().map(str::to_string).ok_or_else(|| anyhow!("output path is not valid UTF-8"))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn parses_geometry() {
|
||||
let r = parse_geometry("10,20 300x400").unwrap();
|
||||
assert_eq!((r.x, r.y, r.w, r.h), (10, 20, 300, 400));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_bad_geometry() {
|
||||
assert!(parse_geometry("nonsense").is_err());
|
||||
assert!(parse_geometry("10,20").is_err()); // missing size
|
||||
assert!(parse_geometry("a,b cxd").is_err()); // non-numeric
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn which_resolves_installed_binaries() {
|
||||
if cfg!(unix) {
|
||||
assert!(which("sh"), "sh should resolve on unix");
|
||||
}
|
||||
assert!(!which("definitely-not-a-real-binary-xyzzy"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn backend_label_is_stable() {
|
||||
assert_eq!(backend_label(DisplayBackend::X11), "X11");
|
||||
assert_eq!(backend_label(DisplayBackend::WaylandHyprland), "Wayland (Hyprland)");
|
||||
}
|
||||
|
||||
/// A capture that never finishes — a screen asleep, for `grim` — is cut off and says why,
|
||||
/// rather than holding the tool until its network-shaped deadline.
|
||||
#[cfg(unix)]
|
||||
#[tokio::test]
|
||||
async fn a_capture_that_never_finishes_is_cut_off_with_a_reason() {
|
||||
let started = std::time::Instant::now();
|
||||
let error = run_within("sleep", &["30".into()], std::time::Duration::from_millis(200))
|
||||
.await
|
||||
.expect_err("cut off");
|
||||
assert!(started.elapsed() < std::time::Duration::from_secs(5));
|
||||
assert!(error.to_string().contains("locked or asleep"), "{error}");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user