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:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

View 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));
}
}

View 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}");
}
}