diff --git a/apps/lutra-desktop/src/screenshot/webview2.rs b/apps/lutra-desktop/src/screenshot/webview2.rs index 5aa661c..9bc21c3 100644 --- a/apps/lutra-desktop/src/screenshot/webview2.rs +++ b/apps/lutra-desktop/src/screenshot/webview2.rs @@ -6,6 +6,12 @@ //! loop. The caller waits on a channel for the PNG bytes. Nothing here //! focuses, raises or shows a window. //! +//! A capture that does not arrive in time is explained: either the main +//! thread never ran the request (it is blocked), or WebView2 accepted it but +//! drew no frame, which happens while the page is hidden (locked session, +//! display asleep). The page's `document.visibilityState` is then asked +//! for, so the error says which. +//! //! 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 @@ -14,18 +20,24 @@ #![allow(unsafe_code)] +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::mpsc::{self, Sender}; +use std::time::Duration; use tauri::WebviewWindow; -use webview2_com::CapturePreviewCompletedHandler; use webview2_com::Microsoft::Web::WebView2::Win32::{ COREWEBVIEW2_CAPTURE_PREVIEW_IMAGE_FORMAT_PNG, ICoreWebView2Controller, }; +use webview2_com::{CapturePreviewCompletedHandler, ExecuteScriptCompletedHandler}; use windows::Win32::System::Com::{IStream, STREAM_SEEK_SET}; use windows::Win32::UI::Shell::SHCreateMemStream; use super::{CAPTURE_TIMEOUT, MAX_PNG_BYTES}; +/// How long to wait for the page's visibility after a capture timed out. +const VISIBILITY_TIMEOUT: Duration = Duration::from_secs(2); + /// Bytes read from the memory stream per call. const CHUNK: u32 = 64 * 1024; @@ -36,18 +48,76 @@ type Capture = Result, String>; /// /// # Errors /// A message if the capture cannot be scheduled, WebView2 reports a failure, -/// or no result arrives within [`CAPTURE_TIMEOUT`]. +/// or no result arrives within [`CAPTURE_TIMEOUT`]; the last one says +/// whether the main thread was blocked or the page was hidden. pub fn capture_png(window: &WebviewWindow) -> Result, String> { let (tx, rx) = mpsc::channel::(); + let started = Arc::new(AtomicBool::new(false)); + let on_main = started.clone(); window .with_webview(move |webview| { + on_main.store(true, Ordering::SeqCst); 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())? + match rx.recv_timeout(CAPTURE_TIMEOUT) { + Ok(capture) => capture, + Err(_) if !started.load(Ordering::SeqCst) => Err(timeout_message(false, None)), + Err(_) => Err(timeout_message(true, visibility(window).as_deref())), + } +} + +/// Explains a capture that did not arrive within [`CAPTURE_TIMEOUT`]. +/// `started` says whether the main thread ran the request; `visibility` is +/// the page's `document.visibilityState` if it could be read. +fn timeout_message(started: bool, visibility: Option<&str>) -> String { + let secs = CAPTURE_TIMEOUT.as_secs(); + if !started { + return format!( + "the webview did not deliver the capture in time: Lutra's main thread did not run the request within {secs} s (it is blocked, e.g. by a native dialog)" + ); + } + match visibility { + Some("hidden") => format!( + "the webview did not deliver the capture in time: the page is hidden (locked session, display asleep, or the window minimised or on another virtual desktop), and WebView2 draws no frames while hidden; no image within {secs} s" + ), + Some(state) => format!( + "the webview did not deliver the capture in time: WebView2 accepted the request but sent no image within {secs} s (page visibility: {state})" + ), + None => format!( + "the webview did not deliver the capture in time: WebView2 accepted the request but sent no image within {secs} s, and the page did not report its visibility" + ), + } +} + +/// Reads the page's `document.visibilityState` (`"visible"` or +/// `"hidden"`), or `None` if it does not answer within +/// [`VISIBILITY_TIMEOUT`]. A send to a caller that has given up is ignored. +fn visibility(window: &WebviewWindow) -> Option { + let (tx, rx) = mpsc::channel::>(); + window + .with_webview(move |webview| { + let answer = tx.clone(); + let handler = ExecuteScriptCompletedHandler::create(Box::new(move |result, json| { + let _ = answer.send(result.ok().and_then(|()| serde_json::from_str(&json).ok())); + Ok(()) + })); + let Ok(core) = (unsafe { webview.controller().CoreWebView2() }) else { + let _ = tx.send(None); + return; + }; + if unsafe { + core.ExecuteScript(windows::core::w!("document.visibilityState"), &handler) + } + .is_err() + { + let _ = tx.send(None); + } + }) + .ok()?; + rx.recv_timeout(VISIBILITY_TIMEOUT).ok().flatten() } /// Starts `CapturePreview` into a memory stream; the completion handler @@ -108,3 +178,20 @@ fn read_all(stream: &IStream) -> Result, String> { out.extend_from_slice(filled); } } + +#[cfg(test)] +mod tests { + use super::timeout_message; + + #[test] + fn timeouts_name_their_cause() { + assert!(timeout_message(false, None).contains("main thread")); + assert!(timeout_message(true, Some("hidden")).contains("page is hidden")); + assert!(timeout_message(true, Some("visible")).contains("visibility: visible")); + assert!(timeout_message(true, None).contains("did not report")); + assert!( + timeout_message(true, Some("hidden")) + .starts_with("the webview did not deliver the capture in time") + ); + } +} diff --git a/docs/architecture.md b/docs/architecture.md index f481d6f..596e3c7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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`. - `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. -- 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 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 capture that does not arrive within 10 s is explained: the main thread never ran the request (blocked), or WebView2 accepted it but drew no frame; in that case the page's `document.visibilityState` is read and a hidden page is reported with its likely causes (locked session, display asleep, minimised or on another virtual desktop). Covered, off-screen and DWM-cloaked windows capture fine (checked on Windows 11). A `--control` instance builds its window and webview with `focused(false)`; when it is started from the foreground app's process tree it still becomes the foreground window about 1 s after start (seen 2026-10-29; see `docs/gaps.md`). 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. ### CLI and single instance (M3.7) @@ -711,6 +711,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Question | Decision | Why | |---|---|---| +| 2026-10-30 | minor | F2b: screenshot timeouts say whether the main thread was blocked or the page hidden; `--control` start can still take the foreground | | Highlighting | A Lezer grammar (`@lezer/php`, MIT) in CodeMirror highlights instantly on the UI thread. tree-sitter in `crates/syntax` stays the structural source (outline, folding, index) and later adds semantic tokens on top. | The keystroke-to-highlight budget (< 16 ms) leaves no room for an IPC round trip per keystroke; Lezer is incremental inside CodeMirror. tree-sitter gives the core one parser for every structural feature. | | Git library | `gix` (MIT OR Apache-2.0) for reading: status, log, diff, blame, refs. Writes the library doesn't cover well (push, pull, rebase, merge, hooks, signing) run the user's `git` executable. `git2`/libgit2 is not used. | gix is pure Rust and permissively licensed; libgit2 is GPL-2.0 with a linking exception, outside the permitted licences. Shelling out for writes keeps the user's hooks, credential helpers and config working. | | Terminal | `portable-pty` (MIT) in the new L3 crate `crates/terminal`; xterm.js (MIT) renders in the frontend. Output is streamed as events, input goes through commands. | ConPTY on Windows and Unix PTYs behind one API; xterm.js is the standard web terminal. A separate crate keeps PTY code out of the engine. | diff --git a/docs/gaps.md b/docs/gaps.md index 4fe0bec..a4b9fc0 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -6,6 +6,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | # | Gap | Milestone | Estimate (one agent) | |---|---|---|---| +| 2026-10-30 | minor | New item: `--control` start can take the foreground; screenshot timeouts explained (F2b) | | G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) | | G2 | Editor core: ~~engine buffers, save~~ (M1.3), ~~editor UI with tabs, undo, multi-caret~~ (M1.6, CodeMirror basics), ~~recovery journal~~ (M1.7), tab management (preview, pin, split, close others, reopen), conflict UI for files changed on disk, ~~autosave~~ (M3.10), local history | M1 | ~14 h | | G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b; string and path controls: H4), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar and display modes open) | M1 | ~24 h | @@ -46,6 +47,7 @@ Known smaller items from M0: - 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. +- A `--control` instance started from the foreground app's process tree (an agent run from Claude) still becomes the foreground window about 1 s after start, although window and webview are built with `focused(false)` (F2b, 2026-10-29; cause not found yet; screenshots themselves do not take the foreground). A hidden page (locked session, display asleep) gives WebView2 no frames to capture; the error now says so. - `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.