Compare commits

..

No commits in common. "7492e6c4dddd4dd79fbdce0253815c09cc1d0dd7" and "d567f3957dc685289f222d5dd92b1d8f4717de30" have entirely different histories.

12 changed files with 84 additions and 398 deletions

2
Cargo.lock generated
View file

@ -2620,8 +2620,6 @@ dependencies = [
"tauri-build", "tauri-build",
"tauri-plugin-dialog", "tauri-plugin-dialog",
"tempfile", "tempfile",
"webview2-com",
"windows 0.61.3",
"xcap", "xcap",
] ]

View file

@ -20,20 +20,11 @@ lutra-engine.workspace = true
serde_json = "1.0.154" serde_json = "1.0.154"
tauri = { version = "2.11.6", features = [] } tauri = { version = "2.11.6", features = [] }
tauri-plugin-dialog = "2.7.3" tauri-plugin-dialog = "2.7.3"
[target.'cfg(windows)'.dependencies]
webview2-com = "0.38.2"
windows = { version = "0.61.3", features = ["Win32_System_Com", "Win32_UI_Shell"] }
[target.'cfg(not(windows))'.dependencies]
xcap = "0.9.8" xcap = "0.9.8"
[dev-dependencies] [dev-dependencies]
tempfile.workspace = true tempfile.workspace = true
[target.'cfg(windows)'.dev-dependencies]
windows = { version = "0.61.3", features = ["Win32_UI_WindowsAndMessaging"] }
[build-dependencies] [build-dependencies]
png = "0.18.1" png = "0.18.1"
tauri-build = { version = "2.6.3", features = [] } tauri-build = { version = "2.6.3", features = [] }

View file

@ -8,9 +8,7 @@
//! start is a single instance (see [`instance`]): a second start forwards //! start is a single instance (see [`instance`]): a second start forwards
//! its path to the running app and exits. A start with `--data-dir`, //! its path to the running app and exits. A start with `--data-dir`,
//! `LUTRA_DATA_DIR` or `--control` keeps its files away from the user's //! `LUTRA_DATA_DIR` or `--control` keeps its files away from the user's
//! (see [`datadir`]). With `--control` the window opens without taking the //! (see [`datadir`]).
//! foreground, so an agent starting Lutra does not catch the user's typing;
//! `app.focus` brings it to the front on request.
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
@ -87,7 +85,6 @@ fn run(args: &args::Args) -> Result<(), String> {
let slot: Arc<OnceLock<Arc<Host>>> = Arc::new(OnceLock::new()); let slot: Arc<OnceLock<Arc<Host>>> = Arc::new(OnceLock::new());
let setup_slot = slot.clone(); let setup_slot = slot.clone();
let initial_path = args.path.clone(); let initial_path = args.path.clone();
let focus_on_start = args.control.is_none();
let app = tauri::Builder::default() let app = tauri::Builder::default()
.plugin(tauri_plugin_dialog::init()) .plugin(tauri_plugin_dialog::init())
.invoke_handler(tauri::generate_handler![ .invoke_handler(tauri::generate_handler![
@ -105,7 +102,6 @@ fn run(args: &args::Args) -> Result<(), String> {
.title(WINDOW_TITLE) .title(WINDOW_TITLE)
.inner_size(1200.0, 800.0) .inner_size(1200.0, 800.0)
.min_inner_size(640.0, 400.0) .min_inner_size(640.0, 400.0)
.focused(focus_on_start)
.initialization_script(theme::init_script(&setting)); .initialization_script(theme::init_script(&setting));
if let Some(dir) = &webview_dir { if let Some(dir) = &webview_dir {
window = window.data_directory(dir.clone()); window = window.data_directory(dir.clone());

View file

@ -1,45 +1,30 @@
//! Screenshots of Lutra's main window for `ui.screenshot`. //! Screenshots of Lutra's main window for `ui.screenshot`.
//! //!
//! A screenshot never focuses, raises or shows the window: `app.focus` is the //! `xcap` refuses to enumerate windows of the calling process (querying their
//! only control method that does. Taking one while the user types into //! titles can deadlock), so the screenshot is taken from the screen instead:
//! another app must not pull their keystrokes into Lutra. //! the main window is brought to the front, its client area is located in
//! //! physical pixels through Tauri, and that region of the monitor is captured.
//! - Windows: the webview renders itself into a PNG through WebView2's //! Anything covering the window at that moment shows up in the image.
//! `CapturePreview` ([`webview2`]). The image is the page as the webview
//! draws it, whether or not other windows cover Lutra; the native title bar
//! is not part of it.
//! - Other platforms (fallback): the window's client area is located in
//! physical pixels through Tauri and that region of its monitor is captured
//! with `xcap` ([`region`]). Windows covering Lutra at that moment appear in
//! the image. WKWebView's and WebKitGTK's own snapshot APIs can replace it.
use std::path::Path; use std::path::Path;
use std::time::Duration; use std::time::Duration;
use tauri::{AppHandle, Manager}; use tauri::{AppHandle, Manager};
use xcap::Monitor;
use xcap::image::ImageFormat;
#[cfg(not(windows))] /// Time for the compositor to show the window after it was focused.
mod region; const SETTLE: Duration = Duration::from_millis(150);
#[cfg(windows)]
mod webview2;
/// The eight bytes every PNG file starts with. /// Captures the client area of the window labelled `label` and writes it to
const PNG_SIGNATURE: [u8; 8] = [0x89, b'P', b'N', b'G', b'\r', b'\n', 0x1a, b'\n']; /// `path` as PNG. Must not be called on the main thread, which has to stay
/// free to answer the window queries. Focusing the window is best effort: a
/// Largest PNG accepted from the platform capture. /// failure is ignored because the capture still works when the window is
const MAX_PNG_BYTES: usize = 64 * 1024 * 1024; /// already in front.
/// How long to wait for the platform capture before giving up.
const CAPTURE_TIMEOUT: Duration = Duration::from_secs(10);
/// Captures the window labelled `label` and writes it to `path` as PNG,
/// without changing which window is in front or has the keyboard focus.
/// Must not be called on the main thread: the capture is scheduled there and
/// this function waits for it.
/// ///
/// # Errors /// # Errors
/// A message if the window does not exist or is minimised, the capture fails /// A message if the window does not exist or is minimised, the monitor
/// or times out, the result is not a PNG, or the file cannot be written. /// cannot be captured, or the PNG cannot be written.
pub fn capture_window(app: &AppHandle, label: &str, path: &Path) -> Result<(), String> { pub fn capture_window(app: &AppHandle, label: &str, path: &Path) -> Result<(), String> {
let window = app let window = app
.get_webview_window(label) .get_webview_window(label)
@ -47,43 +32,76 @@ pub fn capture_window(app: &AppHandle, label: &str, path: &Path) -> Result<(), S
if window.is_minimized().unwrap_or(false) { if window.is_minimized().unwrap_or(false) {
return Err("the main window is minimised".into()); return Err("the main window is minimised".into());
} }
#[cfg(windows)] let _ = window.set_focus();
let png = webview2::capture_png(&window)?; std::thread::sleep(SETTLE);
#[cfg(not(windows))] let pos = window.inner_position().map_err(|e| e.to_string())?;
let png = region::capture_png(&window)?; let size = window.inner_size().map_err(|e| e.to_string())?;
check_png(&png)?; let centre_x = pos
.x
.saturating_add(i32::try_from(size.width / 2).unwrap_or(0));
let centre_y = pos
.y
.saturating_add(i32::try_from(size.height / 2).unwrap_or(0));
let monitor = Monitor::from_point(centre_x, centre_y)
.map_err(|e| format!("cannot find the window's monitor: {e}"))?;
let (mx, my) = (
monitor.x().map_err(|e| e.to_string())?,
monitor.y().map_err(|e| e.to_string())?,
);
let (mw, mh) = (
monitor.width().map_err(|e| e.to_string())?,
monitor.height().map_err(|e| e.to_string())?,
);
let region = clip(
pos.x.saturating_sub(mx),
pos.y.saturating_sub(my),
size.width,
size.height,
mw,
mh,
)
.ok_or("the main window is outside its monitor")?;
let image = monitor
.capture_region(region.0, region.1, region.2, region.3)
.map_err(|e| format!("cannot capture the screen: {e}"))?;
if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) { if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
std::fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?; std::fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?;
} }
std::fs::write(path, png).map_err(|e| format!("{}: {e}", path.display())) image
.save_with_format(path, ImageFormat::Png)
.map_err(|e| format!("{}: {e}", path.display()))
} }
/// Checks that `bytes` start with the PNG signature and stay within /// Clips a rectangle given relative to a monitor's origin to the monitor's
/// [`MAX_PNG_BYTES`]. /// bounds, returning `(x, y, width, height)` or `None` if nothing is left.
/// fn clip(x: i32, y: i32, w: u32, h: u32, mw: u32, mh: u32) -> Option<(u32, u32, u32, u32)> {
/// # Errors let left = i64::from(x).max(0);
/// A message naming what is wrong. let top = i64::from(y).max(0);
fn check_png(bytes: &[u8]) -> Result<(), String> { let right = (i64::from(x) + i64::from(w)).min(i64::from(mw));
if bytes.len() > MAX_PNG_BYTES { let bottom = (i64::from(y) + i64::from(h)).min(i64::from(mh));
return Err(format!("the capture is larger than {MAX_PNG_BYTES} bytes")); if right <= left || bottom <= top {
return None;
} }
if !bytes.starts_with(&PNG_SIGNATURE) { Some((
return Err("the capture is not a PNG image".into()); u32::try_from(left).ok()?,
} u32::try_from(top).ok()?,
Ok(()) u32::try_from(right - left).ok()?,
u32::try_from(bottom - top).ok()?,
))
} }
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::clip;
#[test] #[test]
fn accepts_png_and_rejects_the_rest() { fn clips_to_the_monitor() {
let mut png = PNG_SIGNATURE.to_vec(); assert_eq!(clip(10, 20, 100, 50, 1920, 1080), Some((10, 20, 100, 50)));
png.extend_from_slice(b"rest"); assert_eq!(clip(-10, -5, 100, 50, 1920, 1080), Some((0, 0, 90, 45)));
assert!(check_png(&png).is_ok()); assert_eq!(
assert!(check_png(b"GIF89a").is_err()); clip(1900, 1000, 100, 100, 1920, 1080),
assert!(check_png(&[]).is_err()); Some((1900, 1000, 20, 80))
assert!(check_png(&vec![0; MAX_PNG_BYTES + 1]).is_err()); );
assert_eq!(clip(2000, 0, 100, 100, 1920, 1080), None);
} }
} }

View file

@ -1,91 +0,0 @@
//! Fallback for platforms without a webview capture yet (macOS, Linux):
//! capture the window's client area from the screen with `xcap`.
//!
//! `xcap` refuses to enumerate windows of the calling process (querying their
//! titles can deadlock), so the client area is located in physical pixels
//! through Tauri and that region of its monitor is captured. The window is
//! not focused or raised: anything covering it at that moment shows up in
//! the image.
use std::io::Cursor;
use tauri::WebviewWindow;
use xcap::Monitor;
use xcap::image::ImageFormat;
/// Captures the screen region under `window`'s client area as PNG bytes.
///
/// # Errors
/// A message if the window's geometry or monitor cannot be read, the window
/// is outside its monitor, or the capture or encoding fails.
pub fn capture_png(window: &WebviewWindow) -> Result<Vec<u8>, String> {
let pos = window.inner_position().map_err(|e| e.to_string())?;
let size = window.inner_size().map_err(|e| e.to_string())?;
let centre_x = pos
.x
.saturating_add(i32::try_from(size.width / 2).unwrap_or(0));
let centre_y = pos
.y
.saturating_add(i32::try_from(size.height / 2).unwrap_or(0));
let monitor = Monitor::from_point(centre_x, centre_y)
.map_err(|e| format!("cannot find the window's monitor: {e}"))?;
let (mx, my) = (
monitor.x().map_err(|e| e.to_string())?,
monitor.y().map_err(|e| e.to_string())?,
);
let (mw, mh) = (
monitor.width().map_err(|e| e.to_string())?,
monitor.height().map_err(|e| e.to_string())?,
);
let region = clip(
pos.x.saturating_sub(mx),
pos.y.saturating_sub(my),
size.width,
size.height,
mw,
mh,
)
.ok_or("the main window is outside its monitor")?;
let image = monitor
.capture_region(region.0, region.1, region.2, region.3)
.map_err(|e| format!("cannot capture the screen: {e}"))?;
let mut png = Cursor::new(Vec::new());
image
.write_to(&mut png, ImageFormat::Png)
.map_err(|e| format!("cannot encode the capture: {e}"))?;
Ok(png.into_inner())
}
/// Clips a rectangle given relative to a monitor's origin to the monitor's
/// bounds, returning `(x, y, width, height)` or `None` if nothing is left.
fn clip(x: i32, y: i32, w: u32, h: u32, mw: u32, mh: u32) -> Option<(u32, u32, u32, u32)> {
let left = i64::from(x).max(0);
let top = i64::from(y).max(0);
let right = (i64::from(x) + i64::from(w)).min(i64::from(mw));
let bottom = (i64::from(y) + i64::from(h)).min(i64::from(mh));
if right <= left || bottom <= top {
return None;
}
Some((
u32::try_from(left).ok()?,
u32::try_from(top).ok()?,
u32::try_from(right - left).ok()?,
u32::try_from(bottom - top).ok()?,
))
}
#[cfg(test)]
mod tests {
use super::clip;
#[test]
fn clips_to_the_monitor() {
assert_eq!(clip(10, 20, 100, 50, 1920, 1080), Some((10, 20, 100, 50)));
assert_eq!(clip(-10, -5, 100, 50, 1920, 1080), Some((0, 0, 90, 45)));
assert_eq!(
clip(1900, 1000, 100, 100, 1920, 1080),
Some((1900, 1000, 20, 80))
);
assert_eq!(clip(2000, 0, 100, 100, 1920, 1080), None);
}
}

View file

@ -1,110 +0,0 @@
//! Windows: the webview captures itself with WebView2's `CapturePreview`
//! (<https://learn.microsoft.com/microsoft-edge/webview2/reference/win32/icorewebview2#capturepreview>).
//!
//! The capture runs on the main thread, where Tauri hands out the WebView2
//! controller, and completes asynchronously through the main thread's message
//! loop. The caller waits on a channel for the PNG bytes. Nothing here
//! focuses, raises or shows a window.
//!
//! This module allows `unsafe` because the WebView2 COM interfaces are only
//! reachable through FFI. Every call gets valid arguments by construction:
//! the controller comes from Tauri, the stream from `SHCreateMemStream`, the
//! completion handler from `webview2-com`, and reads go into a buffer whose
//! length is passed alongside its pointer.
#![allow(unsafe_code)]
use std::sync::mpsc::{self, Sender};
use tauri::WebviewWindow;
use webview2_com::CapturePreviewCompletedHandler;
use webview2_com::Microsoft::Web::WebView2::Win32::{
COREWEBVIEW2_CAPTURE_PREVIEW_IMAGE_FORMAT_PNG, ICoreWebView2Controller,
};
use windows::Win32::System::Com::{IStream, STREAM_SEEK_SET};
use windows::Win32::UI::Shell::SHCreateMemStream;
use super::{CAPTURE_TIMEOUT, MAX_PNG_BYTES};
/// Bytes read from the memory stream per call.
const CHUNK: u32 = 64 * 1024;
/// What the main thread sends back: the PNG bytes or an error message.
type Capture = Result<Vec<u8>, String>;
/// Captures `window`'s webview as PNG bytes.
///
/// # Errors
/// A message if the capture cannot be scheduled, WebView2 reports a failure,
/// or no result arrives within [`CAPTURE_TIMEOUT`].
pub fn capture_png(window: &WebviewWindow) -> Result<Vec<u8>, String> {
let (tx, rx) = mpsc::channel::<Capture>();
window
.with_webview(move |webview| {
if let Err(e) = start(&webview.controller(), &tx) {
let _ = tx.send(Err(e));
}
})
.map_err(|e| format!("cannot reach the webview: {e}"))?;
rx.recv_timeout(CAPTURE_TIMEOUT)
.map_err(|_| "the webview did not deliver the capture in time".to_string())?
}
/// Starts `CapturePreview` into a memory stream; the completion handler
/// reads the stream and sends the result on `tx`. Runs on the main thread. A
/// failed send means the caller timed out and left, so it is ignored.
///
/// # Errors
/// A message if the webview, the stream or the capture call fails
/// synchronously; the handler then never runs.
fn start(controller: &ICoreWebView2Controller, tx: &Sender<Capture>) -> Result<(), String> {
let webview = unsafe { controller.CoreWebView2() }
.map_err(|e| format!("cannot reach the webview: {e}"))?;
let stream = unsafe { SHCreateMemStream(None) }.ok_or("cannot create a memory stream")?;
let target = stream.clone();
let tx = tx.clone();
let handler = CapturePreviewCompletedHandler::create(Box::new(move |result| {
let capture = result
.map_err(|e| format!("WebView2 could not capture the page: {e}"))
.and_then(|()| read_all(&target));
let _ = tx.send(capture);
Ok(())
}));
unsafe {
webview.CapturePreview(
COREWEBVIEW2_CAPTURE_PREVIEW_IMAGE_FORMAT_PNG,
&stream,
&handler,
)
}
.map_err(|e| format!("WebView2 could not start the capture: {e}"))
}
/// Reads `stream` from its start to its end.
///
/// # Errors
/// A message if seeking or reading fails or the data exceeds
/// [`MAX_PNG_BYTES`].
fn read_all(stream: &IStream) -> Result<Vec<u8>, String> {
unsafe { stream.Seek(0, STREAM_SEEK_SET, None) }
.map_err(|e| format!("cannot rewind the capture: {e}"))?;
let mut out = Vec::new();
let mut chunk = vec![0_u8; usize::try_from(CHUNK).unwrap_or(65_536)];
let len = u32::try_from(chunk.len()).unwrap_or(CHUNK);
loop {
let mut read = 0_u32;
unsafe { stream.Read(chunk.as_mut_ptr().cast(), len, Some(&mut read)) }
.ok()
.map_err(|e| format!("cannot read the capture: {e}"))?;
let filled = chunk
.get(..usize::try_from(read).unwrap_or(usize::MAX))
.ok_or("the capture stream reported more bytes than it read")?;
if filled.is_empty() {
return Ok(out);
}
if out.len().saturating_add(filled.len()) > MAX_PNG_BYTES {
return Err(format!("the capture is larger than {MAX_PNG_BYTES} bytes"));
}
out.extend_from_slice(filled);
}
}

View file

@ -1,111 +0,0 @@
//! Live check that `ui.screenshot` never takes the foreground (Windows).
//!
//! Starts a built desktop app (`LUTRA_DESKTOP_EXE`, built with
//! `--features bundled-ui`) with `--control` and an isolated data directory,
//! takes several screenshots over the control channel and samples the
//! foreground window every few milliseconds the whole time. The test fails
//! if the foreground window ever belongs to the app's process, or if a
//! screenshot is not a PNG. Ignored by default because it needs a desktop
//! session and a built app:
//!
//! `LUTRA_DESKTOP_EXE=… LUTRA_CONTROL_PORT=7962 cargo test -p lutra-desktop --test screenshot_focus -- --ignored`
#![cfg(windows)]
#![allow(unsafe_code)]
use std::process::{Child, Command};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use std::thread;
use std::time::{Duration, Instant};
use lutra_control::client::Client;
use serde_json::json;
use windows::Win32::UI::WindowsAndMessaging::{GetForegroundWindow, GetWindowThreadProcessId};
/// Kills the app when the test ends, also on failure.
struct App(Child);
impl Drop for App {
fn drop(&mut self) {
let _ = self.0.kill();
let _ = self.0.wait();
}
}
/// Process id owning the current foreground window, 0 if there is none.
fn foreground_pid() -> u32 {
let mut pid = 0_u32;
unsafe {
let window = GetForegroundWindow();
GetWindowThreadProcessId(window, Some(&mut pid));
}
pid
}
#[test]
#[ignore = "starts the desktop app; set LUTRA_DESKTOP_EXE and run with --ignored"]
fn screenshots_never_take_the_foreground() {
let exe = std::env::var("LUTRA_DESKTOP_EXE").expect("LUTRA_DESKTOP_EXE");
let port: u16 = std::env::var("LUTRA_CONTROL_PORT")
.unwrap_or_else(|_| "7962".into())
.parse()
.unwrap();
let data = tempfile::tempdir().unwrap();
let shots = tempfile::tempdir().unwrap();
let app = App(Command::new(exe)
.arg("--control")
.arg(port.to_string())
.arg("--data-dir")
.arg(data.path())
.spawn()
.unwrap());
let pid = app.0.id();
let stop = Arc::new(AtomicBool::new(false));
let stolen = Arc::new(AtomicU32::new(0));
let sampler = {
let (stop, stolen) = (stop.clone(), stolen.clone());
thread::spawn(move || {
while !stop.load(Ordering::Relaxed) {
if foreground_pid() == pid {
stolen.fetch_add(1, Ordering::Relaxed);
}
thread::sleep(Duration::from_millis(5));
}
})
};
let deadline = Instant::now() + Duration::from_secs(90);
let mut client = loop {
match Client::connect(port, Duration::from_secs(2)) {
Ok(client) => break client,
Err(_) if Instant::now() < deadline => thread::sleep(Duration::from_millis(250)),
Err(e) => panic!("the app did not open its control port: {e:?}"),
}
};
client.request("app.ping", json!({})).unwrap();
thread::sleep(Duration::from_secs(3));
for i in 0..5 {
let path = shots.path().join(format!("shot-{i}.png"));
client
.request("ui.screenshot", json!({ "path": path }))
.unwrap();
let png = std::fs::read(&path).unwrap();
assert!(
png.starts_with(b"\x89PNG\r\n\x1a\n"),
"shot {i} is not a PNG"
);
assert!(png.len() > 1000, "shot {i} is suspiciously small");
thread::sleep(Duration::from_millis(200));
}
stop.store(true, Ordering::Relaxed);
sampler.join().unwrap();
assert_eq!(
stolen.load(Ordering::Relaxed),
0,
"the app's window was in the foreground during the check"
);
}

View file

@ -30,8 +30,7 @@ pub trait Backend: Send + Sync + 'static {
/// Lists every command with its current enabled state. /// Lists every command with its current enabled state.
fn list_commands(&self) -> Vec<CommandInfo>; fn list_commands(&self) -> Vec<CommandInfo>;
/// Writes a PNG screenshot of the main window to `path`. It must not /// Writes a PNG screenshot of the main window to `path`.
/// focus, raise or show any window; only [`Backend::focus`] may.
/// ///
/// # Errors /// # Errors
/// A message if there is no window to capture or the file cannot be /// A message if there is no window to capture or the file cannot be
@ -42,7 +41,7 @@ pub trait Backend: Send + Sync + 'static {
fn subscribe(&self, sink: EventSink); fn subscribe(&self, sink: EventSink);
/// Brings the main window to the front, for the CLI and a second app /// Brings the main window to the front, for the CLI and a second app
/// start. The only method that changes focus. The default has no window and fails. /// start. The default has no window and fails.
/// ///
/// # Errors /// # Errors
/// A message if there is no window or it cannot be focused. /// A message if there is no window or it cannot be focused.

View file

@ -11,14 +11,13 @@ pub const APP_PING: &str = "app.ping";
pub const ENGINE_EXECUTE: &str = "engine.execute"; pub const ENGINE_EXECUTE: &str = "engine.execute";
/// `engine.listCommands`: lists the engine's commands. /// `engine.listCommands`: lists the engine's commands.
pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands"; pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands";
/// `ui.screenshot`: writes a PNG of the main window without focusing it. /// `ui.screenshot`: writes a PNG of the main window.
pub const UI_SCREENSHOT: &str = "ui.screenshot"; pub const UI_SCREENSHOT: &str = "ui.screenshot";
/// `events.subscribe`: streams engine events on this connection. /// `events.subscribe`: streams engine events on this connection.
pub const EVENTS_SUBSCRIBE: &str = "events.subscribe"; pub const EVENTS_SUBSCRIBE: &str = "events.subscribe";
/// `app.auth`: authenticates a connection to the rendezvous listener. /// `app.auth`: authenticates a connection to the rendezvous listener.
pub const APP_AUTH: &str = "app.auth"; pub const APP_AUTH: &str = "app.auth";
/// `app.focus`: brings the main window to the front; the only method that /// `app.focus`: brings the main window to the front.
/// changes focus.
pub const APP_FOCUS: &str = "app.focus"; pub const APP_FOCUS: &str = "app.focus";
/// Documentation of one method. /// Documentation of one method.
@ -62,7 +61,7 @@ pub const METHODS: &[MethodDoc] = &[
MethodDoc { MethodDoc {
name: UI_SCREENSHOT, name: UI_SCREENSHOT,
params: "{ path: string }", params: "{ path: string }",
result: "{ path }; error screenshot_failed if the window cannot be captured. Never focuses, raises or shows the window", result: "{ path }; error screenshot_failed if the window cannot be captured",
}, },
MethodDoc { MethodDoc {
name: EVENTS_SUBSCRIBE, name: EVENTS_SUBSCRIBE,

View file

@ -64,7 +64,7 @@ As built in M0:
- Methods: `app.ping`, `app.auth {token}`, `app.focus`, `engine.execute {command, params}`, `engine.listCommands`, `ui.screenshot {path}`, `events.subscribe`. Names and docs live in `crates/control/src/methods.rs`. - Methods: `app.ping`, `app.auth {token}`, `app.focus`, `engine.execute {command, params}`, `engine.listCommands`, `ui.screenshot {path}`, `events.subscribe`. Names and docs live in `crates/control/src/methods.rs`.
- `events.subscribe` answers `{subscribed: true}` and from then on writes `{"event": {...}}` lines for every engine event on that connection, between responses; a shared writer writes each line whole. Subscribing twice is a no-op. Each subscriber has a queue of 4096 events (`lutra_control::EVENT_QUEUE`); a subscriber that falls behind or disconnects is dropped by `Subscribers::publish`, and the connection gets a final `{"event": {"kind": "subscriptionLost"}}` line if it is still open. - `events.subscribe` answers `{subscribed: true}` and from then on writes `{"event": {...}}` lines for every engine event on that connection, between responses; a shared writer writes each line whole. Subscribing twice is a no-op. Each subscriber has a queue of 4096 events (`lutra_control::EVENT_QUEUE`); a subscriber that falls behind or disconnects is dropped by `Subscribers::publish`, and the connection gets a final `{"event": {"kind": "subscriptionLost"}}` line if it is still open.
- `lutra_control` defines a `Backend` trait; the desktop app implements it (engine access, effects, screenshots, event subscribers), tests implement it with a bare engine (`lutra_testkit::EngineBackend`). Hosts publish each outcome's events through `lutra_control::Subscribers`. One thread accepts connections and each connection gets its own thread; no async runtime is needed in the crate. - `lutra_control` defines a `Backend` trait; the desktop app implements it (engine access, effects, screenshots, event subscribers), tests implement it with a bare engine (`lutra_testkit::EngineBackend`). Hosts publish each outcome's events through `lutra_control::Subscribers`. One thread accepts connections and each connection gets its own thread; no async runtime is needed in the crate.
- Screenshots never focus, raise or show the window; `app.focus` is the only method that does. On Windows the webview captures itself with WebView2 `CapturePreview` (PNG into a memory stream, scheduled on the main thread through `with_webview`, the control thread waits up to 10 s), so windows covering Lutra do not appear and the native title bar is not part of the image (`apps/lutra-desktop/src/screenshot/webview2.rs`). Fallback on macOS and Linux until WKWebView's and WebKitGTK's snapshot APIs are wired: `xcap` captures the screen region under the client area (it does not enumerate windows of its own process, whose title queries can deadlock), without focusing, so covering windows appear (`screenshot/region.rs`). A `--control` instance opens its window without taking the foreground. The ignored test `apps/lutra-desktop/tests/screenshot_focus.rs` starts a built app and fails if its window is ever in the foreground while it starts and takes screenshots. - Screenshots: `xcap` does not enumerate windows of its own process (querying their titles can deadlock), so the desktop focuses its main window, reads the client area's physical position and size from Tauri and captures that region of the monitor with `xcap::Monitor::capture_region`. Windows covering Lutra at that moment appear in the image. A webview-native capture (WebView2 `CapturePreview`, WKWebView snapshots) can replace it later.
### CLI and single instance (M3.7) ### CLI and single instance (M3.7)
@ -649,7 +649,6 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 2026-10-27 | minor | F2: `ui.screenshot` through WebView2 `CapturePreview` without focus; region fallback elsewhere; `--control` windows open unfocused |
| 2026-10-26 | minor | M4.5: branches (status-bar item, popup, `vcs.branches`, `vcs.newBranch`, `vcs.checkout`) | | 2026-10-26 | minor | M4.5: branches (status-bar item, popup, `vcs.branches`, `vcs.newBranch`, `vcs.checkout`) |
| 2026-10-26 | minor | M4.3: diff viewer (`vcs.showDiff`, `vcs.nextChange`, `vcs.previousChange`, `@codemirror/merge` loaded lazily, the project tree's context menu) | | 2026-10-26 | minor | M4.3: diff viewer (`vcs.showDiff`, `vcs.nextChange`, `vcs.previousChange`, `@codemirror/merge` loaded lazily, the project tree's context menu) |
| 2026-10-25 | minor | M4.4: `git.lineChanges` (index cache, `similar` line diff off the lock), gutter change markers, Git status colours in the tree and tabs | | 2026-10-25 | minor | M4.4: `git.lineChanges` (index cache, `similar` line diff off the lock), gutter change markers, Git status colours in the tree and tabs |

View file

@ -18,7 +18,7 @@ cargo xtask ci # the full quality gate, run before every commit
cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/ cargo xtask fixtures # create Symfony and Laravel reference projects in target/fixtures/
``` ```
A `--control PORT` instance keeps its settings, recovery journal and webview data in `<temp>/lutra-control/<port>/`, never in your own data directory; `--data-dir DIR` or `LUTRA_DATA_DIR=DIR` pick another directory. Delete the folder to start fresh. Its window opens without taking the foreground, and `ui.screenshot` never focuses it; only `app.focus` does. To check that on Windows, build with `--features bundled-ui` and run `LUTRA_DESKTOP_EXE=<target>/debug/lutra-desktop.exe LUTRA_CONTROL_PORT=<port> cargo test -p lutra-desktop --test screenshot_focus -- --ignored`. A `--control PORT` instance keeps its settings, recovery journal and webview data in `<temp>/lutra-control/<port>/`, never in your own data directory; `--data-dir DIR` or `LUTRA_DATA_DIR=DIR` pick another directory. Delete the folder to start fresh.
## Robustness: Lutra never crashes ## Robustness: Lutra never crashes
@ -32,7 +32,6 @@ No inline comments. Doc comment blocks above modules, functions, types and field
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 2026-10-27 | minor | Unfocused `--control` windows and the screenshot focus check (F2) |
| 2026-10-25 | minor | Isolated data directory for `--control` instances (H6) | | 2026-10-25 | minor | Isolated data directory for `--control` instances (H6) |
| 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain | | 2026-10-14 | minor | Node.js 22.12+ required by the frontend toolchain |
| 2026-10-13 | major | Initial draft | | 2026-10-13 | major | Initial draft |

View file

@ -43,7 +43,7 @@ G5 progress: M2.3 landed the find-in-files backend: `crates/search` (parallel wa
Known smaller items from M0: Known smaller items from M0:
- The CI workflow has never run: the repository has no remote until the owner decides on hosting. - The CI workflow has never run: the repository has no remote until the owner decides on hosting.
- ~~`ui.screenshot` captures the screen region of the window and focuses it~~ (F2, C6: WebView2 `CapturePreview` on Windows, never focuses). macOS and Linux still capture the screen region (without focus), so covering windows appear there. - `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that.
- `cargo xtask fixtures` needs Composer, which the M0 machine does not have. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have.
G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. H1 (C5) put Phpactor into a kill-on-close group (`crates/proc`: a job object on Windows, a process group with a watchdog on Unix), so it no longer outlives Lutra, even when Lutra is killed. H3 (C5) made Phpactor on Windows useful sooner and more visible: a 1 ms tick while it indexes (a 2,000-class project gives a useful completion after 21–27 s instead of 72 s, measured), its progress in the status bar, its messages as notifications, and Lutra's own `php -l` for syntax errors on open and save. Still open: indexing is still bound by Phpactor's one-file-per-message loop (~110–190 files/s); superseded completion requests are not cancelled (Phpactor answers every list as incomplete, so it is asked on every keystroke; ~180 ms CPU per class-name request on 2,000 classes); quick-fixes. G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. H1 (C5) put Phpactor into a kill-on-close group (`crates/proc`: a job object on Windows, a process group with a watchdog on Unix), so it no longer outlives Lutra, even when Lutra is killed. H3 (C5) made Phpactor on Windows useful sooner and more visible: a 1 ms tick while it indexes (a 2,000-class project gives a useful completion after 21–27 s instead of 72 s, measured), its progress in the status bar, its messages as notifications, and Lutra's own `php -l` for syntax errors on open and save. Still open: indexing is still bound by Phpactor's one-file-per-message loop (~110–190 files/s); superseded completion requests are not cancelled (Phpactor answers every list as incomplete, so it is asked on every keystroke; ~180 ms CPU per class-name request on 2,000 classes); quick-fixes.
@ -52,7 +52,6 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 2026-10-27 | minor | Screenshot item shrunk: webview capture without focus on Windows (F2) |
| 2026-10-26 | minor | G8 shrunk: branch widget and popup (M4.5) | | 2026-10-26 | minor | G8 shrunk: branch widget and popup (M4.5) |
| 2026-10-26 | minor | G8 shrunk: diff viewer (M4.3) | | 2026-10-26 | minor | G8 shrunk: diff viewer (M4.3) |
| 2026-10-25 | minor | G8 shrunk: gutter markers and status colours (M4.4) | | 2026-10-25 | minor | G8 shrunk: gutter markers and status colours (M4.4) |