F2b: explain screenshot timeouts (blocked main thread or hidden page)

A WebView2 capture that does not arrive within 10 s now says whether the
main thread never ran the request or WebView2 accepted it without drawing
a frame; in the latter case the page's document.visibilityState is read
and a hidden page is reported with its likely causes (locked session,
display asleep, minimised, other virtual desktop). Docs record that a
--control instance started from the foreground app's process tree can
still take the foreground at start (open, F2c).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-30 17:48:42 +01:00
parent 74c674ed12
commit 01ec7605bd
3 changed files with 95 additions and 5 deletions

View file

@ -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<Vec<u8>, 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<Vec<u8>, String> {
let (tx, rx) = mpsc::channel::<Capture>();
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<String> {
let (tx, rx) = mpsc::channel::<Option<String>>();
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<Vec<u8>, 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")
);
}
}