Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
102 KB
Raw Blame
//! The Windows desktop for computer control (S24 on Windows): input through `SendInput`, and
//! screenshots of the monitor under the pointer through GDI. Gentle Dot's own windows are
//! left out of captures by their display affinity (`WDA_EXCLUDEFROMCAPTURE`): the glow and the
//! dialogs always; the Dot and the panel, hidden during every call anyway, only for the length
//! of each capture, so the user's own screenshots show them even during a session (Windows
//! cannot leave a window out of one capture only).
//!
//! Points are physical pixels of the virtual screen: the app is per-monitor DPI aware, so the
//! pointer, the monitors, and `SendInput` all use them.
//!
//! Apps are processes with a taskbar window (`winapps`). An app's identity is its process:
//! the executable's file name stands for the macOS bundle id, and its file description for the
//! app name. Store apps draw inside a frame window owned by `ApplicationFrameHost.exe`; their
//! identity is the process of the frame's core window, so Settings is Settings, not its host.
//! An app Windows will not identify (a process that cannot be queried, a frame whose app is not
//! found) is the blocked `UNIDENTIFIED` app, so an action aimed at it is refused.
//!
//! Keys go only to the recipient the shared guard approved (`post_typed`), and never to an app
//! that runs as administrator: Windows drops input sent to a process with a higher integrity
//! level without saying so (`keyboard_refusal`).
//!
//! Elements come from UI Automation (`winaccess` maps them), with a 0.5 s timeout so a hung app
//! cannot stall the helper, as the Accessibility timeout does on macOS.

use super::coords::{fit_long_edge, Point, ScreenshotGeometry, MAX_LONG_EDGE};
use super::encode::{bgra_to_jpeg, JPEG_QUALITY};
use super::blocklist::{blocked_name, blocked_reason, AppIdentity, UNIDENTIFIED};
use super::risk::{AxElement, Focus};
use super::glow::Frame;
use super::winaccess::{element, is_default, known_chain, unreadable, UIA_BUTTON, UIA_WINDOW};
use super::winapps::{
    active_entries, answers_to, distinct_names, executable_target, fronts_same_app, hosted_page, listed_name,
    listed_windows, request, shortcut_named, strip_ci, Request, TopWindow,
};
use super::winput::{
    checks_held_modifiers, checks_typing_target, releases, send_batches, settles, steps, without_held_modifiers, Step,
    VirtualScreen,
};
use super::{
    runs_as_administrator, AppInfo, Capture, InputEvent, KeyboardRecipient, MouseButton, ScreenshotsUnsupported,
    TypedError, KEYS_CHANGED_WHILE_TYPING,
};
use std::ffi::c_void;
use std::mem::{size_of, zeroed};
use std::ptr::null_mut;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::time::Duration;
use windows_sys::Win32::Foundation::{
    CloseHandle, GetLastError, SetLastError, ERROR_TIMEOUT, HWND, LPARAM, POINT, RECT,
};
use windows_sys::Win32::Graphics::Dwm::{DwmFlush, DwmGetWindowAttribute, DWMWA_CLOAKED};
use windows_sys::Win32::Storage::FileSystem::{GetFileVersionInfoSizeW, GetFileVersionInfoW, VerQueryValueW};
use windows_sys::Win32::System::Registry::{RegGetValueW, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, RRF_RT_REG_SZ};
use windows_sys::Win32::Security::{
    GetSidSubAuthority, GetSidSubAuthorityCount, GetTokenInformation, IsValidSid, TokenIntegrityLevel,
    TOKEN_MANDATORY_LABEL, TOKEN_QUERY,
};
use windows_sys::Win32::System::Threading::{
    AttachThreadInput, GetCurrentProcess, GetCurrentThreadId, OpenProcess, OpenProcessToken,
    QueryFullProcessImageNameW, PROCESS_NAME_WIN32, PROCESS_QUERY_LIMITED_INFORMATION,
};
use windows_sys::Win32::UI::Shell::ShellExecuteW;
use windows_sys::Win32::UI::HiDpi::{GetDpiForMonitor, MDT_EFFECTIVE_DPI};
use windows_sys::Win32::Graphics::Gdi::{
    CreateCompatibleDC, CreateDIBSection, DeleteDC, DeleteObject, GdiFlush, GetDC, GetMonitorInfoW, MonitorFromPoint,
    ReleaseDC, SelectObject, SetBrushOrgEx, SetStretchBltMode, StretchBlt, BITMAPINFO, BITMAPINFOHEADER, BI_RGB,
    CAPTUREBLT, DIB_RGB_COLORS, HALFTONE, HBITMAP, HDC, HGDIOBJ, MONITORINFO, MONITOR_DEFAULTTONEAREST, SRCCOPY,
};
use windows_sys::Win32::UI::Input::KeyboardAndMouse::{
    GetAsyncKeyState, SendInput, INPUT, INPUT_KEYBOARD, INPUT_MOUSE, KEYBDINPUT, KEYEVENTF_EXTENDEDKEY, KEYEVENTF_KEYUP,
    KEYEVENTF_UNICODE, MOUSEEVENTF_ABSOLUTE, MOUSEEVENTF_HWHEEL, MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP,
    MOUSEEVENTF_MOVE, MOUSEEVENTF_RIGHTDOWN, MOUSEEVENTF_RIGHTUP, MOUSEEVENTF_VIRTUALDESK, MOUSEEVENTF_WHEEL,
    MOUSEINPUT,
};
use windows_sys::Win32::UI::WindowsAndMessaging::{
    BringWindowToTop, DrawIconEx, EnumChildWindows, EnumWindows, GetAncestor, GetClassNameW, GetCursorInfo,
    GetCursorPos, GetForegroundWindow, GetGUIThreadInfo, GetIconInfo, GetSystemMetrics, GetWindow,
    GetWindowDisplayAffinity, GetWindowLongPtrW, GetWindowTextLengthW, GetWindowTextW, GetWindowThreadProcessId,
    IsIconic, IsWindowVisible, SendMessageTimeoutW, SetForegroundWindow, SetWindowDisplayAffinity, ShowWindow,
    WindowFromPoint, CURSORINFO, CURSOR_SHOWING, DI_NORMAL, GA_ROOT, GA_ROOTOWNER, GUITHREADINFO, GWL_EXSTYLE,
    GW_OWNER, ICONINFO, SMTO_ABORTIFHUNG, SM_CXCURSOR, SM_CXVIRTUALSCREEN, SM_CYCURSOR, SM_CYVIRTUALSCREEN,
    SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN, SW_RESTORE, SW_SHOWNORMAL, WDA_EXCLUDEFROMCAPTURE, WDA_NONE,
    WM_NULL, WS_EX_APPWINDOW, WS_EX_TOOLWINDOW, SetWindowLongPtrW, SetWindowPos, HWND_TOPMOST,
    SWP_NOMOVE, SWP_NOSIZE, SWP_NOACTIVATE, SW_HIDE, SW_SHOW, SW_SHOWNOACTIVATE, WS_EX_NOACTIVATE,
};

/// Pause between the events of one action, so apps see distinct presses (as on macOS).
const EVENT_GAP: Duration = Duration::from_millis(15);

/// How long the window in front may take to handle a key before the action stops (S4).
const CATCH_UP_MS: u32 = 2000;

const NOT_CAUGHT_UP: &str =
    "The app in front did not take the keys in time, so the rest was not sent. Take a screenshot to see what arrived.";

/// A monitor's rectangle in physical pixels of the virtual screen.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MonitorFrame {
    pub x: i32,
    pub y: i32,
    pub width: i32,
    pub height: i32,
}

pub fn virtual_screen() -> VirtualScreen {
    // SAFETY: plain queries.
    unsafe {
        VirtualScreen {
            x: GetSystemMetrics(SM_XVIRTUALSCREEN),
            y: GetSystemMetrics(SM_YVIRTUALSCREEN),
            width: GetSystemMetrics(SM_CXVIRTUALSCREEN),
            height: GetSystemMetrics(SM_CYVIRTUALSCREEN),
        }
    }
}

pub fn pointer_location() -> Option<Point> {
    let mut at = POINT { x: 0, y: 0 };
    // SAFETY: `at` is a valid out-pointer.
    (unsafe { GetCursorPos(&mut at) } != 0).then(|| Point { x: f64::from(at.x), y: f64::from(at.y) })
}

/// The monitor showing `at`, or the nearest one.
pub fn monitor_at(at: Point) -> Option<MonitorFrame> {
    let point = POINT { x: at.x.round() as i32, y: at.y.round() as i32 };
    // SAFETY: plain query; `info` is a valid out-pointer whose size is set.
    unsafe {
        let monitor = MonitorFromPoint(point, MONITOR_DEFAULTTONEAREST);
        if monitor.is_null() {
            return None;
        }
        let mut info: MONITORINFO = zeroed();
        info.cbSize = size_of::<MONITORINFO>() as u32;
        if GetMonitorInfoW(monitor, &mut info) == 0 {
            return None;
        }
        let RECT { left, top, right, bottom } = info.rcMonitor;
        Some(MonitorFrame { x: left, y: top, width: right - left, height: bottom - top })
    }
}

fn input(step: Step) -> INPUT {
    let mouse = |dx, dy, data: i32, flags| INPUT {
        r#type: INPUT_MOUSE,
        Anonymous: windows_sys::Win32::UI::Input::KeyboardAndMouse::INPUT_0 {
            mi: MOUSEINPUT { dx, dy, mouseData: data as _, dwFlags: flags, time: 0, dwExtraInfo: 0 },
        },
    };
    let keyboard = |vk: u16, scan: u16, flags| INPUT {
        r#type: INPUT_KEYBOARD,
        Anonymous: windows_sys::Win32::UI::Input::KeyboardAndMouse::INPUT_0 {
            ki: KEYBDINPUT { wVk: vk, wScan: scan, dwFlags: flags, time: 0, dwExtraInfo: 0 },
        },
    };
    match step {
        Step::Move { x, y } => mouse(x, y, 0, MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_VIRTUALDESK),
        Step::Button { button, down } => {
            let flags = match (button, down) {
                (MouseButton::Left, true) => MOUSEEVENTF_LEFTDOWN,
                (MouseButton::Left, false) => MOUSEEVENTF_LEFTUP,
                (MouseButton::Right, true) => MOUSEEVENTF_RIGHTDOWN,
                (MouseButton::Right, false) => MOUSEEVENTF_RIGHTUP,
            };
            mouse(0, 0, 0, flags)
        }
        Step::Wheel { horizontal, delta } => {
            mouse(0, 0, delta, if horizontal { MOUSEEVENTF_HWHEEL } else { MOUSEEVENTF_WHEEL })
        }
        Step::Key { vk, down, extended } => {
            let mut flags = if down { 0 } else { KEYEVENTF_KEYUP };
            if extended {
                flags |= KEYEVENTF_EXTENDEDKEY;
            }
            keyboard(vk, 0, flags)
        }
        Step::Unicode { unit, down } => {
            keyboard(0, unit, KEYEVENTF_UNICODE | if down { 0 } else { KEYEVENTF_KEYUP })
        }
    }
}

fn send_batch(batch: &[Step]) -> Result<(), (usize, String)> {
    let records: Vec<INPUT> = batch.iter().copied().map(input).collect();
    // SAFETY: a contiguous array of valid INPUT records of the size passed.
    let sent = unsafe { SendInput(records.len() as u32, records.as_ptr(), size_of::<INPUT>() as i32) } as usize;
    if sent == records.len() {
        Ok(())
    } else {
        Err((sent, format!("Windows refused the input: {}", std::io::Error::last_os_error())))
    }
}

fn send(step: Step) -> Result<(), String> {
    send_batch(&[step]).map_err(|(_, error)| error)
}

/// Waits until the thread of the window in front handles messages again (S4). Keys queued while
/// it stalls reach it as other characters (a stalled Notepad turned "tres" into "eees"), so each
/// key waits for the previous one to be taken. A window that cannot be asked (another integrity
/// level) is not waited for; one that does not answer in time stops the action.
fn catch_up() -> Result<(), String> {
    // SAFETY: plain calls; `result` is a valid out-pointer.
    unsafe {
        let window = GetForegroundWindow();
        if window.is_null() {
            return Ok(());
        }
        let mut result = 0;
        if SendMessageTimeoutW(window, WM_NULL, 0, 0, SMTO_ABORTIFHUNG, CATCH_UP_MS, &mut result) == 0
            && GetLastError() == ERROR_TIMEOUT
        {
            return Err(NOT_CAUGHT_UP.into());
        }
    }
    Ok(())
}

/// The foreground root and the foreground thread's actual keyboard recipient. A failed query
/// is not a stable target, even when a later query also fails.
fn typing_windows() -> Option<(HWND, HWND)> {
    // SAFETY: plain queries; `info` is a valid out-pointer with its size set.
    unsafe {
        let foreground = GetForegroundWindow();
        if foreground.is_null() {
            return None;
        }
        let root = GetAncestor(foreground, GA_ROOT);
        let thread = GetWindowThreadProcessId(foreground, null_mut());
        let mut info: GUITHREADINFO = zeroed();
        info.cbSize = size_of::<GUITHREADINFO>() as u32;
        if root.is_null() || thread == 0 || GetGUIThreadInfo(thread, &mut info) == 0 {
            return None;
        }
        Some((root, info.hwndFocus))
    }
}

/// Posts `event` with a short gap between steps (surrogate pairs form one batch), waiting after
/// key releases or a complete pair for the window in front to take it. Text is bound to the
/// window in front and its keyboard focus when it starts, and stops when either changes. A
/// failure releases the keys and buttons left pressed by the successfully sent prefix before
/// reporting the error.
pub fn post(event: &InputEvent) -> Result<(), String> {
    post_input(event, None).map_err(|error| error.message(false))
}

/// Posts a typed chunk, a Return, or a key only to the recipient the shared guard approved: the
/// windows it is bound to must still belong to the approved front app and focused app. A refusal
/// before anything of it was sent is a `TypedError` refusal, which the helper words
/// from what earlier chunks sent.
pub fn post_typed(event: &InputEvent, recipient: &KeyboardRecipient) -> Result<(), TypedError> {
    post_input(event, Some(recipient))
}

fn post_input(event: &InputEvent, approved: Option<&KeyboardRecipient>) -> Result<(), TypedError> {
    // Bind both type chunks and their Returns. Standalone combos remain free to switch apps.
    let typing_target = if approved.is_some() || matches!(event, InputEvent::Text(_)) {
        Some(typing_windows().ok_or(TypedError::FrontUnknown)?)
    } else {
        None
    };
    if let (Some(approved), Some((root, focus))) = (approved, typing_target) {
        // The identities the shared guard approved, computed as it does (`frontmost_app` is
        // `target_of` the foreground root; a hosted app's frame belongs to its host process, so
        // raw window owners would never match). The front comes from the pinned root itself;
        // `focused_app` is a global query, so the windows are pinned again after it and must not
        // have moved in between.
        if focus.is_null() {
            return Err(TypedError::NoFocus);
        }
        let front = target_of(root).pid;
        let focused = focused_app().map(|app| app.pid).filter(|pid| *pid != front);
        // The pinned focus window itself must belong to an approved process (the root's own,
        // the front app's, or the approved focused one): the global query above could have seen
        // the focus for a moment elsewhere.
        let owner = window_pid(focus);
        let owned = owner == window_pid(root) || owner == front || Some(owner) == approved.focused_pid;
        let valid = owned
            && front == approved.front_pid
            && focused == approved.focused_pid
            && typing_windows() == Some((root, focus));
        if !valid {
            return Err(TypedError::RecipientChanged);
        }
    }
    let plan = steps(event, &virtual_screen()).map_err(TypedError::Failed)?;
    // Sample after recipient queries and before any of this event's own modifiers or buttons go
    // down (a refused drag presses nothing). Pointer refusals reach the agent through `post`.
    // Do not sample inside the step loop: ctrl+t would then observe its own injected Ctrl.
    // This is a snapshot, not an atomic fence against a user pressing a key during SendInput.
    if checks_held_modifiers(event) {
        without_held_modifiers(
            // SAFETY: plain key-state query using the Windows virtual-key codes in winput.
            |key| unsafe { GetAsyncKeyState(i32::from(key)) },
            || Ok(()),
        )?;
    }
    let mut done = 0;
    for batch in send_batches(&plan) {
        let checked = checks_typing_target(&batch[0])
            || (approved.is_some() && matches!(batch[0], Step::Key { down: true, .. }));
        let changed = checked && typing_target.is_some_and(|target| typing_windows() != Some(target));
        let failed = if changed {
            // Before the first batch nothing of this post went out; after it, part of it did.
            let error = if done == 0 { TypedError::RecipientChanged } else { TypedError::Failed(KEYS_CHANGED_WHILE_TYPING.into()) };
            Some((done, error))
        } else {
            match send_batch(batch) {
                Err((sent, error)) => Some((done + sent, TypedError::Failed(error))),
                Ok(()) => {
                    // No sleep or catch_up inside a surrogate pair's single SendInput call.
                    std::thread::sleep(EVENT_GAP);
                    if settles(batch.last().unwrap()) {
                        catch_up().err().map(|error| (done + batch.len(), TypedError::Failed(error)))
                    } else {
                        None
                    }
                }
            }
        };
        if let Some((sent, error)) = failed {
            for release in releases(&plan[..sent]) {
                let _ = send(release);
            }
            return Err(error);
        }
        done += batch.len();
    }
    Ok(())
}

/// The GDI objects of one capture, released in reverse whatever happens.
struct Canvas {
    screen: HDC,
    memory: HDC,
    bitmap: HBITMAP,
    previous: HGDIOBJ,
    bits: *mut c_void,
}

impl Canvas {
    /// A top-down 32-bit BGRA bitmap of `width × height`, selected into a memory context.
    fn new(width: u32, height: u32) -> Result<Canvas, String> {
        // SAFETY: GDI calls with valid arguments; every handle is checked and released by Drop.
        unsafe {
            let screen = GetDC(null_mut());
            if screen.is_null() {
                return Err("cannot read the screen".into());
            }
            let mut canvas = Canvas { screen, memory: null_mut(), bitmap: null_mut(), previous: null_mut(), bits: null_mut() };
            canvas.memory = CreateCompatibleDC(screen);
            if canvas.memory.is_null() {
                return Err("cannot prepare the screenshot".into());
            }
            let mut info: BITMAPINFO = zeroed();
            info.bmiHeader = BITMAPINFOHEADER {
                biSize: size_of::<BITMAPINFOHEADER>() as u32,
                biWidth: width as i32,
                // Negative: rows top to bottom, as the JPEG encoder reads them.
                biHeight: -(height as i32),
                biPlanes: 1,
                biBitCount: 32,
                biCompression: BI_RGB,
                ..zeroed()
            };
            canvas.bitmap = CreateDIBSection(screen, &info, DIB_RGB_COLORS, &mut canvas.bits, null_mut(), 0);
            if canvas.bitmap.is_null() || canvas.bits.is_null() {
                return Err("cannot prepare the screenshot bitmap".into());
            }
            let previous = SelectObject(canvas.memory, canvas.bitmap);
            // HGDI_ERROR is -1; without the bitmap selected the pixels read would not be the capture.
            if previous.is_null() || previous as isize == -1 {
                return Err("cannot prepare the screenshot bitmap".into());
            }
            canvas.previous = previous;
            Ok(canvas)
        }
    }
}

impl Drop for Canvas {
    fn drop(&mut self) {
        // SAFETY: each handle was created above and is released once.
        unsafe {
            if !self.previous.is_null() {
                SelectObject(self.memory, self.previous);
            }
            if !self.bitmap.is_null() {
                DeleteObject(self.bitmap);
            }
            if !self.memory.is_null() {
                DeleteDC(self.memory);
            }
            ReleaseDC(null_mut(), self.screen);
        }
    }
}

/// Draws the pointer where it is and at the screenshot's scale (macOS captures show it too).
fn draw_pointer(canvas: &Canvas, frame: MonitorFrame, width: u32, height: u32) {
    // SAFETY: `info` and `icon` are valid out-pointers; the icon's bitmaps are released.
    unsafe {
        let mut info: CURSORINFO = zeroed();
        info.cbSize = size_of::<CURSORINFO>() as u32;
        if GetCursorInfo(&mut info) == 0 || info.flags & CURSOR_SHOWING == 0 || info.hCursor.is_null() {
            return;
        }
        let mut icon: ICONINFO = zeroed();
        let (hot_x, hot_y) = if GetIconInfo(info.hCursor, &mut icon) != 0 {
            for bitmap in [icon.hbmMask, icon.hbmColor] {
                if !bitmap.is_null() {
                    DeleteObject(bitmap);
                }
            }
            (icon.xHotspot as i32, icon.yHotspot as i32)
        } else {
            (0, 0)
        };
        let scale = |offset: i32, length: i32, size: u32| (i64::from(offset) * i64::from(size) / i64::from(length.max(1))) as i32;
        let (cursor_w, cursor_h) = (GetSystemMetrics(SM_CXCURSOR), GetSystemMetrics(SM_CYCURSOR));
        let (draw_w, draw_h) = (scale(cursor_w, frame.width, width).max(1), scale(cursor_h, frame.height, height).max(1));
        let x = scale(info.ptScreenPos.x - frame.x, frame.width, width) - scale(hot_x, frame.width, width);
        let y = scale(info.ptScreenPos.y - frame.y, frame.height, height) - scale(hot_y, frame.height, height);
        DrawIconEx(canvas.memory, x, y, info.hCursor, draw_w, draw_h, 0, null_mut(), DI_NORMAL);
    }
}

/// A screenshot of the monitor under the pointer, downscaled to `MAX_LONG_EDGE`, Gentle Dot's
/// windows excluded.
pub fn capture() -> Result<Capture, String> {
    let baseline = capture_baseline()?;
    let changed = exclude_own_windows()?;
    let shot = super::capture_order::capture(wait_for_composition, grab);
    // A window of ours can show during the copy and be gone by now (the user opens the panel and
    // closes it again, Stop gives the Dot back, a dialog opens and closes). Every change of our
    // windows runs inside a `WindowChange`, and an image taken while one overlapped it is not
    // returned. Checked after the windows, so a change ending between the two is still seen. The
    // windows this capture excluded go back as they were, so the user's own screenshots show them
    // (#163 finding 3).
    let excluded = own_windows_excluded();
    let clean = excluded && unchanged_since(baseline);
    restore_affinity(&changed);
    let shot = shot?;
    if !clean {
        return Err(OWN_WINDOW_SHOWN.into());
    }
    Ok(shot)
}

const OWN_WINDOW_SHOWN: &str = "Gentle Dot's window could show in the screenshot, so it was not taken. Take another.";

/// The screenshot itself, once Gentle Dot's windows are out of it.
fn grab() -> Result<Capture, String> {
    let pointer = pointer_location().ok_or("cannot read the pointer position")?;
    let frame = monitor_at(pointer).ok_or("no display under the pointer")?;
    if frame.width <= 0 || frame.height <= 0 {
        return Err("the display under the pointer has no size".into());
    }
    let (width, height) = fit_long_edge(frame.width as u32, frame.height as u32, MAX_LONG_EDGE);
    let canvas = Canvas::new(width, height)?;
    // SAFETY: both contexts are valid; the bitmap holds `width × height` 32-bit pixels.
    let bytes = unsafe {
        SetStretchBltMode(canvas.memory, HALFTONE);
        SetBrushOrgEx(canvas.memory, 0, 0, null_mut());
        let copied = StretchBlt(
            canvas.memory, 0, 0, width as i32, height as i32,
            canvas.screen, frame.x, frame.y, frame.width, frame.height,
            SRCCOPY | CAPTUREBLT,
        );
        if copied == 0 {
            return Err(format!("cannot take the screenshot: {}", std::io::Error::last_os_error()));
        }
        draw_pointer(&canvas, frame, width, height);
        GdiFlush();
        std::slice::from_raw_parts(canvas.bits as *const u8, width as usize * height as usize * 4).to_vec()
    };
    drop(canvas);
    let data = bgra_to_jpeg(&bytes, width, height, width as usize * 4, JPEG_QUALITY)?;
    let origin = Point { x: f64::from(frame.x), y: f64::from(frame.y) };
    let geometry = ScreenshotGeometry::for_display(origin, f64::from(frame.width), width, height);
    Ok(Capture { data, mime_type: "image/jpeg", geometry })
}

/// The process that created `hwnd`, or 0.
fn window_pid(hwnd: HWND) -> i32 {
    let mut pid = 0u32;
    // SAFETY: `pid` is a valid out-pointer.
    unsafe { GetWindowThreadProcessId(hwnd, &mut pid) };
    pid as i32
}

/// Keeps a window out of every screenshot and screen capture, this helper's included.
pub fn exclude_from_capture(hwnd: *mut c_void) -> Result<(), String> {
    set_capture_excluded(hwnd, true)
}

/// Every top-level window, front to back, or why they cannot be listed.
fn enumerate_windows() -> Result<Vec<HWND>, String> {
    unsafe extern "system" fn collect(hwnd: HWND, state: LPARAM) -> i32 {
        // SAFETY: `state` is the vector passed below, alive for the whole enumeration.
        unsafe { (*(state as *mut Vec<HWND>)).push(hwnd) };
        1
    }
    let mut handles: Vec<HWND> = Vec::new();
    // SAFETY: the callback only appends to `handles`, which outlives the call. It never stops the
    // enumeration, so 0 is a failure, and a list that may be missing windows is no list.
    if unsafe { EnumWindows(Some(collect), &mut handles as *mut Vec<HWND> as LPARAM) } == 0 {
        return Err(enumeration_failure(std::io::Error::last_os_error()));
    }
    Ok(handles)
}

/// Why `EnumWindows` failed. It may fail without setting an error code, which would read "(os error 0)".
fn enumeration_failure(error: std::io::Error) -> String {
    match error.raw_os_error() {
        Some(0) | None => "EnumWindows failed without an error code".to_string(),
        Some(_) => error.to_string(),
    }
}

/// The visible top-level windows of this process, or why they cannot be listed.
fn own_visible_windows() -> Result<Vec<HWND>, String> {
    let mut handles = enumerate_windows().map_err(|error| format!("cannot list its windows: {error}"))?;
    let own = std::process::id() as i32;
    // SAFETY: plain queries on a window handle (a vanished window just reads as hidden).
    handles.retain(|&hwnd| window_pid(hwnd) == own && unsafe { IsWindowVisible(hwnd) } != 0);
    Ok(handles)
}

fn is_excluded(hwnd: HWND) -> bool {
    let mut affinity = 0u32;
    // SAFETY: `affinity` is a valid out-pointer.
    (unsafe { GetWindowDisplayAffinity(hwnd, &mut affinity) }) != 0 && affinity == WDA_EXCLUDEFROMCAPTURE
}

/// Wait even when no visible windows needed exclusion: a just-hidden panel may still be composed.
fn wait_for_composition() -> Result<(), String> {
    // No timeout: if DwmFlush stalls, it holds the tool call open with no ceiling.
    // SAFETY: a plain call; it waits for the next composition.
    let result = unsafe { DwmFlush() };
    if result < 0 {
        Err(format!("Cannot wait for Windows composition (DwmFlush HRESULT 0x{:08X}), so no screenshot was taken.", result as u32))
    } else {
        Ok(())
    }
}

/// Makes sure no visible window of this process shows in the capture about to be taken, and
/// returns the ones it had to exclude, for `restore_affinity` once the capture is taken.
fn exclude_own_windows() -> Result<Vec<(HWND, u32)>, String> {
    let mut changed = Vec::new();
    let windows = own_visible_windows().map_err(|error| format!("Gentle Dot's window would show in the screenshot: {error}"))?;
    for hwnd in windows.into_iter().filter(|&hwnd| !is_excluded(hwnd)) {
        let mut previous = 0;
        // SAFETY: a query on our window with a valid out-pointer.
        if unsafe { GetWindowDisplayAffinity(hwnd, &mut previous) } == 0 {
            restore_affinity(&changed);
            return Err(format!("{OWN_WINDOW_SHOWN} Cannot read its capture affinity."));
        }
        if previous == WDA_EXCLUDEFROMCAPTURE {
            continue;
        }
        if let Err(error) = set_capture_excluded(hwnd, true) {
            restore_affinity(&changed);
            return Err(format!("Gentle Dot's window would show in the screenshot: {error}"));
        }
        changed.push((hwnd, previous));
    }
    Ok(changed)
}

/// Whether every visible window of this process is still out of captures.
fn own_windows_excluded() -> bool {
    every_window_excluded(own_visible_windows())
}

/// Whether every window listed is out of captures; windows that could not be listed are not.
fn every_window_excluded(windows: Result<Vec<HWND>, String>) -> bool {
    windows.is_ok_and(|windows| windows.into_iter().all(is_excluded))
}

/// How many changes of this process's windows began or ended: one shown or hidden, let show in
/// captures again, or a dialog that could not be kept out of them, for its whole life.
static OWN_WINDOW_CHANGES: AtomicU64 = AtomicU64::new(0);
/// How many such changes are under way.
static OWN_WINDOWS_CHANGING: AtomicUsize = AtomicUsize::new(0);

const OWN_WINDOW_BUSY: &str =
    "A Gentle Dot window is opening, closing, or waiting for you, so no screenshot was taken. Take another in a moment.";

/// A change of this process's windows under way, from before it starts until after it ends (when
/// dropped). A capture that overlaps one in any way is not returned: either one is under way when
/// it starts, or the count moved by the time it ends. The order matters: a change is marked under
/// way before it is counted, and counted before it is no longer under way; a capture reads the
/// count before what is under way when it starts, and the other way round when it ends.
#[must_use]
pub(crate) struct WindowChange(());

impl WindowChange {
    pub(crate) fn begin() -> WindowChange {
        OWN_WINDOWS_CHANGING.fetch_add(1, Ordering::SeqCst);
        OWN_WINDOW_CHANGES.fetch_add(1, Ordering::SeqCst);
        WindowChange(())
    }
}

impl Drop for WindowChange {
    fn drop(&mut self) {
        OWN_WINDOW_CHANGES.fetch_add(1, Ordering::SeqCst);
        OWN_WINDOWS_CHANGING.fetch_sub(1, Ordering::SeqCst);
    }
}

/// The count a capture compares with when it ends, or why it cannot start.
fn capture_baseline() -> Result<u64, String> {
    let changes = OWN_WINDOW_CHANGES.load(Ordering::SeqCst);
    if OWN_WINDOWS_CHANGING.load(Ordering::SeqCst) > 0 {
        return Err(OWN_WINDOW_BUSY.into());
    }
    Ok(changes)
}

/// Whether no change of our windows overlapped the capture that started at `baseline`.
fn unchanged_since(baseline: u64) -> bool {
    OWN_WINDOWS_CHANGING.load(Ordering::SeqCst) == 0 && OWN_WINDOW_CHANGES.load(Ordering::SeqCst) == baseline
}

/// Lets the windows a capture excluded show in screenshots again, as they did before it. A window
/// that vanished meanwhile just fails; any failure is logged, since a window left out would be
/// missing from the user's own screenshots.
fn restore_affinity(changed: &[(HWND, u32)]) {
    let mut saved = CALL_AFFINITIES.lock().unwrap_or_else(|error| error.into_inner());
    for &(hwnd, previous) in changed {
        // A hide may have taken ownership since enumeration. Hand it the original affinity
        // instead of undoing its exclusion; it restores after showing, or at call end if left hidden.
        if let Some(index) = super::capture_order::current_window(&saved, hwnd as usize, call_handles()) {
            saved[index].1.1 = previous;
            continue;
        }
        let _change = WindowChange::begin();
        // SAFETY: restore the value read from this window before excluding it.
        if unsafe { SetWindowDisplayAffinity(hwnd, previous) } == 0 {
            eprintln!("gentle-dot: a window may stay out of screenshots: {}", std::io::Error::last_os_error());
        }
    }
}

/// Leaves a window of this process out of screenshots, or lets it show in them again.
pub fn set_capture_excluded(hwnd: *mut c_void, excluded: bool) -> Result<(), String> {
    let affinity = if excluded { WDA_EXCLUDEFROMCAPTURE } else { WDA_NONE };
    // Letting a window show again is a change a capture under way must see, whatever its result.
    let _change = (!excluded).then(WindowChange::begin);
    // SAFETY: a plain call on a window handle of this process.
    if unsafe { SetWindowDisplayAffinity(hwnd, affinity) } != 0 {
        Ok(())
    } else {
        Err(format!("cannot change whether it shows in screenshots: {}", std::io::Error::last_os_error()))
    }
}

/// The Store apps' frame window and the window of the app it hosts.
const FRAME_CLASS: &str = "ApplicationFrameWindow";
const CORE_CLASS: &str = "Windows.UI.Core.CoreWindow";
/// How deep the Start menu folders are searched for shortcuts.
const SHORTCUT_DEPTH: usize = 4;

fn wide(text: &str) -> Vec<u16> {
    text.encode_utf16().chain(Some(0)).collect()
}

/// The window's class, or none when Windows does not say (every window has one).
fn class_name(hwnd: HWND) -> Option<String> {
    let mut buffer = [0u16; 256];
    // SAFETY: the buffer's length is passed.
    let length = unsafe { GetClassNameW(hwnd, buffer.as_mut_ptr(), buffer.len() as i32) };
    (length > 0).then(|| String::from_utf16_lossy(&buffer[..length as usize]))
}

/// The window's title, `Some("")` for a window without one, or none when Windows did not answer.
fn title_checked(hwnd: HWND) -> Option<String> {
    // SAFETY: the buffer holds the reported length plus the terminator; the last error is reset
    // first, so a zero length is told apart from a failed query.
    unsafe {
        SetLastError(0);
        let length = GetWindowTextLengthW(hwnd);
        if length <= 0 {
            return (GetLastError() == 0).then(String::new);
        }
        let mut buffer = vec![0u16; length as usize + 1];
        let copied = GetWindowTextW(hwnd, buffer.as_mut_ptr(), buffer.len() as i32);
        (copied > 0 || GetLastError() == 0).then(|| String::from_utf16_lossy(&buffer[..copied.max(0) as usize]))
    }
}

fn title(hwnd: HWND) -> String {
    title_checked(hwnd).unwrap_or_default()
}

/// The app a top-level window belongs to: its own process, or for a Store app's frame the
/// process of the core window inside it (none when that window is not found).
fn app_pid(root: HWND) -> Option<i32> {
    let frame_pid = window_pid(root);
    // A window whose class Windows does not report could be a Store frame: no app is assumed.
    if class_name(root)? != FRAME_CLASS {
        return (frame_pid != 0).then_some(frame_pid);
    }
    struct Search {
        frame_pid: i32,
        found: i32,
    }
    unsafe extern "system" fn visit(child: HWND, state: LPARAM) -> i32 {
        // SAFETY: `state` is the `Search` passed below, alive for the whole enumeration.
        let search = unsafe { &mut *(state as *mut Search) };
        let pid = window_pid(child);
        if class_name(child).as_deref() == Some(CORE_CLASS) && pid != search.frame_pid {
            search.found = pid;
            return 0;
        }
        1
    }
    let mut search = Search { frame_pid, found: 0 };
    // SAFETY: the callback only reads windows and writes `search`, which outlives the call.
    unsafe { EnumChildWindows(root, Some(visit), &mut search as *mut Search as LPARAM) };
    (search.found != 0).then_some(search.found)
}

/// Every top-level window, front to back, with the app it belongs to.
fn top_windows() -> Result<Vec<(HWND, TopWindow)>, String> {
    let handles = enumerate_windows().map_err(|error| format!("cannot list the open windows: {error}"))?;
    Ok(handles
        .into_iter()
        .map(|hwnd| {
            // SAFETY: plain queries on a window handle (a vanished window just reads as empty).
            let (visible, style, owner) =
                unsafe { (IsWindowVisible(hwnd) != 0, GetWindowLongPtrW(hwnd, GWL_EXSTYLE) as u32, GetWindow(hwnd, GW_OWNER)) };
            let mut cloaked = 0u32;
            // SAFETY: `cloaked` is a valid out-pointer of the size passed.
            let read = unsafe {
                DwmGetWindowAttribute(hwnd, DWMWA_CLOAKED as u32, &mut cloaked as *mut u32 as *mut c_void, size_of::<u32>() as u32)
            };
            let window = TopWindow {
                // Listed under its host while its app is not found; never a target then.
                pid: app_pid(hwnd).unwrap_or_else(|| window_pid(hwnd)),
                title: title(hwnd),
                visible,
                cloaked: read == 0 && cloaked != 0,
                tool: style & WS_EX_TOOLWINDOW != 0,
                app_window: style & WS_EX_APPWINDOW != 0,
                owned: !owner.is_null(),
            };
            (hwnd, window)
        })
        .collect())
}

/// The executable's full path, when the process lets itself be queried.
fn process_path(pid: i32) -> Option<String> {
    // SAFETY: the handle is checked and closed; the buffer's length is passed and updated.
    unsafe {
        let process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid as u32);
        if process.is_null() {
            return None;
        }
        // The longest path Windows supports.
        let mut buffer = vec![0u16; 32768];
        let mut length = buffer.len() as u32;
        let ok = QueryFullProcessImageNameW(process, PROCESS_NAME_WIN32, buffer.as_mut_ptr(), &mut length);
        CloseHandle(process);
        (ok != 0).then(|| String::from_utf16_lossy(&buffer[..length as usize]))
    }
}

/// The executable's file description (what Task Manager shows as the app name).
fn file_description(path: &str) -> Option<String> {
    let path = wide(path);
    // SAFETY: every buffer and out-pointer is valid; `VerQueryValueW` points into `data`, which
    // lives until the strings are copied out.
    unsafe {
        let size = GetFileVersionInfoSizeW(path.as_ptr(), null_mut());
        if size == 0 {
            return None;
        }
        let mut data = vec![0u8; size as usize];
        if GetFileVersionInfoW(path.as_ptr(), 0, size, data.as_mut_ptr() as *mut c_void) == 0 {
            return None;
        }
        let query = |sub: &str| -> Option<(*const c_void, u32)> {
            let (mut pointer, mut length) = (null_mut::<c_void>(), 0u32);
            let ok = VerQueryValueW(data.as_ptr() as *const c_void, wide(sub).as_ptr(), &mut pointer, &mut length);
            (ok != 0 && !pointer.is_null() && length > 0).then_some((pointer as *const c_void, length))
        };
        let (translation, length) = query("\\VarFileInfo\\Translation")?;
        if length < 4 {
            return None;
        }
        let pair = std::slice::from_raw_parts(translation as *const u16, 2);
        let (text, length) = query(&format!("\\StringFileInfo\\{:04x}{:04x}\\FileDescription", pair[0], pair[1]))?;
        let units = std::slice::from_raw_parts(text as *const u16, length as usize);
        let description = String::from_utf16_lossy(units).trim_end_matches('\0').trim().to_string();
        (!description.is_empty()).then_some(description)
    }
}

/// An app's identity: its executable's file name and its display name, or `process <pid>`
/// when Windows does not let the process be queried (an elevated one, say).
pub fn identity(pid: i32) -> AppIdentity {
    let path = process_path(pid);
    let executable = path.as_deref().and_then(|p| p.rsplit('\\').next()).map(str::to_string);
    let stem = executable.as_deref().map(|exe| exe.rsplit_once('.').map_or(exe, |(stem, _)| stem).to_string());
    let name = path
        .as_deref()
        .and_then(file_description)
        .or(stem)
        .unwrap_or_else(|| format!("process {pid}"));
    AppIdentity { pid, bundle_id: executable, name }
}

/// An identity Windows actually gave: the executable is known.
fn known(id: AppIdentity) -> Option<AppIdentity> {
    id.bundle_id.is_some().then_some(id)
}

fn is_frame_host(id: &AppIdentity) -> bool {
    id.bundle_id.as_deref().is_some_and(|exe| exe.eq_ignore_ascii_case("ApplicationFrameHost.exe"))
}

/// The process id of an app whose process is not even known (a failed focus query).
const NO_PROCESS: i32 = 0;

/// The app Windows does not identify, which the blocklist refuses.
fn unidentified(pid: i32) -> AppIdentity {
    AppIdentity { pid, bundle_id: None, name: UNIDENTIFIED.to_string() }
}

/// The app an action aimed at a top-level window targets. A File Explorer window showing a
/// blocked page (Credential Manager) is that page; an app Windows does not identify is
/// `UNIDENTIFIED`.
fn target_of(root: HWND) -> AppIdentity {
    let Some(pid) = app_pid(root) else { return unidentified(window_pid(root)) };
    let Some(id) = known(identity(pid)) else { return unidentified(pid) };
    // The Store frame's host is never an app of its own: its app was not found.
    if is_frame_host(&id) {
        return unidentified(pid);
    }
    // A File Explorer window whose title Windows does not report could be a blocked page.
    let Some(title) = title_checked(root) else {
        let explorer = id.bundle_id.as_deref().is_some_and(|exe| exe.eq_ignore_ascii_case("explorer.exe"));
        return if explorer { unidentified(pid) } else { id };
    };
    match hosted_page(id.bundle_id.as_deref(), &title) {
        Some(page) => AppIdentity { pid: id.pid, bundle_id: None, name: page.to_string() },
        None => id,
    }
}

/// The app owning the foreground window.
pub fn frontmost_app() -> Option<AppIdentity> {
    // SAFETY: plain queries.
    let root = unsafe { GetAncestor(GetForegroundWindow(), GA_ROOT) };
    (!root.is_null()).then(|| target_of(root))
}

/// The app the keys go to: the focus window's top-level app, through the same window checks as
/// every target, and the process of the focus window itself (Windows sends keys there), the more
/// restrictive of the two. UI Automation's focused element, when it answers, is checked too: a
/// refused one, or one in another process (a panel), is what is returned. A
/// refused app other than Gentle Dot carries no process id, so the helper never drops it as the
/// front app; a focus window Windows does not report is the refused Unidentified app.
pub fn focused_app() -> Option<AppIdentity> {
    focused_app_with(focused_pid())
}

/// `focused_app` given the process of UI Automation's focused element, or none when it did not
/// answer.
fn focused_app_with(focused_pid: Option<i32>) -> Option<AppIdentity> {
    let own = std::process::id() as i32;
    let refused = |id: &AppIdentity| blocked_reason(id, own).is_some();
    // UI Automation's answer: none when it did not answer; a Store frame's host leaves it to the window.
    let from_uia = focused_pid.and_then(|pid| {
        let id = identity(pid);
        (!is_frame_host(&id)).then(|| known(id).unwrap_or_else(|| unidentified(NO_PROCESS)))
    });
    // The focus window's answer: an error when Windows did not say, none when no window has the focus.
    // SAFETY: plain queries; `info` is a valid out-pointer whose size is set.
    let from_window: Result<Option<AppIdentity>, ()> = unsafe {
        let foreground = GetForegroundWindow();
        let thread = if foreground.is_null() { 0 } else { GetWindowThreadProcessId(foreground, null_mut()) };
        let mut info: GUITHREADINFO = zeroed();
        info.cbSize = size_of::<GUITHREADINFO>() as u32;
        if thread == 0 || GetGUIThreadInfo(thread, &mut info) == 0 {
            Err(())
        } else if info.hwndFocus.is_null() {
            Ok(None)
        } else {
            // The window with the focus may be another process's (a child window it hosts): that
            // process receives the keys, so it is checked too, the more restrictive one returned.
            let root = target_of(GetAncestor(info.hwndFocus, GA_ROOT));
            let pid = window_pid(info.hwndFocus);
            let own_window = if pid == 0 {
                unidentified(NO_PROCESS)
            } else {
                let id = identity(pid);
                if is_frame_host(&id) { root.clone() } else { known(id).unwrap_or_else(|| unidentified(NO_PROCESS)) }
            };
            Ok(Some(if !refused(&root) && (refused(&own_window) || own_window.pid != root.pid) { own_window } else { root }))
        }
    };
    let answers = [from_window.clone().ok().flatten(), from_uia.clone()];
    if let Some(blocked) = answers.iter().flatten().find(|id| refused(id)) {
        // Gentle Dot keeps its own id, which is what refuses it when its executable is renamed.
        let pid = if blocked.pid == own { own } else { NO_PROCESS };
        return Some(AppIdentity { pid, ..blocked.clone() });
    }
    match from_window {
        Err(()) => Some(unidentified(NO_PROCESS)),
        // A focused element in another process (a panel) receives the keys; the helper checks it.
        Ok(Some(window)) => Some(from_uia.filter(|uia| uia.pid != window.pid).unwrap_or(window)),
        // No focus window: keys go to the foreground window, checked as the front app.
        Ok(None) => from_uia,
    }
}

/// The app owning the topmost window under `at`. Click-through windows (the glow) are skipped
/// by Windows itself; a point with no window has no owner.
pub fn window_owner_at(at: Point) -> Option<AppIdentity> {
    let point = POINT { x: at.x.round() as i32, y: at.y.round() as i32 };
    // SAFETY: plain queries.
    let root = unsafe { GetAncestor(WindowFromPoint(point), GA_ROOT) };
    (!root.is_null()).then(|| target_of(root))
}

/// The shell display name for the AppUserModelID stored on a frame (the name Start shows for the
/// app), or none when the shell does not give one. Every interface is released and every
/// PROPVARIANT and string the shell allocated is freed before the apartment is left.
fn frame_app_name(hwnd: HWND) -> Option<String> {
    use windows::core::{GUID, PCWSTR, PWSTR};
    use windows::Win32::Foundation::{HWND as ComHwnd, PROPERTYKEY};
    use windows::Win32::System::Com::CoTaskMemFree;
    use windows::Win32::System::Com::StructuredStorage::{PropVariantClear, PropVariantToStringAlloc};
    use windows::Win32::System::Variant::VT_LPWSTR;
    use windows::Win32::UI::Shell::PropertiesSystem::{IPropertyStore, SHGetPropertyStoreForWindow};
    use windows::Win32::UI::Shell::{IShellItem, SHCreateItemInKnownFolder, FOLDERID_AppsFolder, KF_FLAG_DEFAULT, SIGDN_NORMALDISPLAY};
    /// `PKEY_AppUserModel_ID` (propkey.h): declared here rather than enabling the Enhanced
    /// Storage bindings for one constant.
    const AUMID: PROPERTYKEY = PROPERTYKEY { fmtid: GUID::from_u128(0x9f4c2855_9f79_4b39_a8d0_e1d42de1d5f3), pid: 5 };
    /// A string the shell allocated, copied and then freed exactly once.
    fn take(text: PWSTR) -> Option<String> {
        // SAFETY: `text` is null or a terminated string from CoTaskMemAlloc, not used afterwards.
        unsafe {
            let copied = if text.is_null() { None } else { text.to_string().ok() };
            CoTaskMemFree(Some(text.0 as *const c_void));
            copied
        }
    }
    // Declared first so every interface below is released before COM is left.
    let _apartment = Apartment::join(Apartment::SHELL);
    // SAFETY: typed shell calls on a window handle and on the interfaces they return; each
    // HRESULT is checked by the binding, and the PROPVARIANT is cleared once it is read.
    unsafe {
        let store: IPropertyStore = SHGetPropertyStoreForWindow(ComHwnd(hwnd)).ok()?;
        let mut value = store.GetValue(&AUMID).ok()?;
        let aumid = if value.Anonymous.Anonymous.vt == VT_LPWSTR { PropVariantToStringAlloc(&value).ok() } else { None };
        let _ = PropVariantClear(&mut value);
        let aumid = take(aumid?)?;
        if aumid.trim().is_empty() {
            return None;
        }
        let path = wide(&aumid);
        let item: IShellItem = SHCreateItemInKnownFolder(&FOLDERID_AppsFolder, KF_FLAG_DEFAULT, PCWSTR(path.as_ptr())).ok()?;
        take(item.GetDisplayName(SIGDN_NORMALDISPLAY).ok()?).filter(|name| !name.trim().is_empty())
    }
}

/// The running apps, front to back, or why they cannot be listed (a partial list would read as
/// apps that are not running).
pub fn list_apps() -> Result<Vec<AppInfo>, String> {
    let active = frontmost_app().map(|app| app.pid);
    // SAFETY: plain queries.
    let front_root = unsafe { GetAncestor(GetForegroundWindow(), GA_ROOT) } as usize;
    let windows = top_windows()?;
    let listing: Vec<(TopWindow, bool)> = windows.iter().map(|(hwnd, window)| {
        let detached = class_name(*hwnd).as_deref() == Some(FRAME_CLASS)
            && app_pid(*hwnd).is_none() && is_frame_host(&identity(window.pid));
        (window.clone(), detached)
    }).collect();
    let shown = listed_windows(&listing);
    // A detached frame is only named for listing; it cannot be acted on until restored and
    // identified. target_of and every blocklist/activation check keep their existing identity.
    let ids: Vec<(AppIdentity, String)> = shown.iter().map(|&index| {
        let ((hwnd, _), (window, detached)) = (&windows[index], &listing[index]);
        let id = identity(window.pid);
        let name = listed_name(*detached, if *detached { frame_app_name(*hwnd) } else { None },
            if *detached { Some(window.title.clone()) } else { None }, id.name.clone());
        (id, name)
    }).collect();
    // Frames share the frame host's process: the one in front is told by its window handle.
    let actives = active_entries(
        &shown.iter().map(|&index| (listing[index].0.pid, listing[index].1, windows[index].0 as usize)).collect::<Vec<_>>(),
        active,
        front_root,
    );
    let names = distinct_names(
        shown.iter().zip(&ids).map(|(&index, (_, name))| (name.clone(), listing[index].1, listing[index].0.title.clone())).collect(),
    );
    Ok(ids.into_iter().zip(names).zip(actives).map(|(((id, _), name), active)| AppInfo { name, bundle_id: id.bundle_id, active }).collect())
}

/// Brings a window to the front. Windows lets only the process that received the last input
/// take the foreground: after a click on Gentle Dot's own dialog it may; for `open_app`, while
/// the user works in another app, `nudge` first sends an input that changes nothing (a mouse
/// move by zero), which gives it that right.
fn bring_to_front(hwnd: HWND, nudge: bool) {
    let zero_move = INPUT {
        r#type: INPUT_MOUSE,
        Anonymous: windows_sys::Win32::UI::Input::KeyboardAndMouse::INPUT_0 {
            mi: MOUSEINPUT { dx: 0, dy: 0, mouseData: 0, dwFlags: MOUSEEVENTF_MOVE, time: 0, dwExtraInfo: 0 },
        },
    };
    // SAFETY: plain window calls and one valid INPUT record; the input threads are detached
    // again before returning.
    unsafe {
        if IsIconic(hwnd) != 0 {
            ShowWindow(hwnd, SW_RESTORE);
        }
        if nudge {
            SendInput(1, &zero_move, size_of::<INPUT>() as i32);
        }
        if SetForegroundWindow(hwnd) == 0 {
            let foreground = GetWindowThreadProcessId(GetForegroundWindow(), null_mut());
            let own = GetCurrentThreadId();
            let attached = foreground != 0 && foreground != own && AttachThreadInput(own, foreground, 1) != 0;
            BringWindowToTop(hwnd);
            SetForegroundWindow(hwnd);
            if attached {
                AttachThreadInput(own, foreground, 0);
            }
        }
    }
}

/// Whether `hwnd`, or another window of its process under the same owner (its own dialog), is
/// in front within half a second.
fn comes_to_front(hwnd: HWND) -> bool {
    let in_front = || {
        // SAFETY: plain queries (a vanished window just reads as not in front).
        unsafe {
            let front = GetAncestor(GetForegroundWindow(), GA_ROOT);
            (!front.is_null() && front == hwnd)
                || (!front.is_null()
                    && fronts_same_app(
                        window_pid(front),
                        window_pid(hwnd),
                        GetAncestor(front, GA_ROOTOWNER) as usize,
                        GetAncestor(hwnd, GA_ROOTOWNER) as usize,
                    ))
        }
    };
    for _ in 0..10 {
        if in_front() {
            return true;
        }
        std::thread::sleep(std::time::Duration::from_millis(50));
    }
    in_front()
}

/// The frontmost app window of `pid`; none when the windows cannot be listed.
fn app_window_of(pid: i32) -> Option<HWND> {
    top_windows().ok()?.into_iter().find(|(_, window)| window.pid == pid && window.is_app()).map(|(hwnd, _)| hwnd)
}

/// Brings an app back to the front (after a dialog took the focus).
pub fn activate(pid: i32) {
    // No input is sent (the user's click on the dialog allows it), and the helper checks the
    // front app itself afterwards.
    if let Some(hwnd) = app_window_of(pid) {
        bring_to_front(hwnd, false);
    }
}

/// The `.lnk` files of the user's and everyone's Start menu.
fn start_menu_shortcuts() -> Vec<String> {
    fn walk(dir: &std::path::Path, depth: usize, found: &mut Vec<String>) {
        let Ok(entries) = std::fs::read_dir(dir) else { return };
        for entry in entries.flatten() {
            // Links are not followed: only folders and files the Start menu itself holds.
            let Ok(kind) = entry.file_type() else { continue };
            let path = entry.path();
            if kind.is_dir() && depth > 0 {
                walk(&path, depth - 1, found);
            } else if kind.is_file() && path.extension().is_some_and(|e| e.eq_ignore_ascii_case("lnk")) {
                found.push(path.to_string_lossy().into_owned());
            }
        }
    }
    let mut found = Vec::new();
    for root in ["APPDATA", "ProgramData"] {
        if let Some(base) = std::env::var_os(root) {
            let programs = std::path::Path::new(&base).join(r"Microsoft\Windows\Start Menu\Programs");
            walk(&programs, SHORTCUT_DEPTH, &mut found);
        }
    }
    found.sort();
    found
}

/// Asks the shell to start a program.
fn shell_open(program: &str) -> Result<(), String> {
    let (verb, file) = (wide("open"), wide(program));
    // The shell may need COM; it asks for a single-threaded apartment.
    let _apartment = Apartment::join(Apartment::SHELL);
    // SAFETY: valid wide strings that outlive the call.
    let result = unsafe { ShellExecuteW(null_mut(), verb.as_ptr(), file.as_ptr(), null_mut(), null_mut(), SW_SHOWNORMAL) };
    if result as isize > 32 {
        Ok(())
    } else {
        Err(format!("cannot open `{program}`: Windows could not start it"))
    }
}

/// `name` with `.exe`, as Windows names programs.
fn with_exe(name: &str) -> String {
    if strip_ci(name, ".exe").is_some() { name.to_string() } else { format!("{name}.exe") }
}

/// The program a shortcut starts, when it is a local program started with no arguments.
fn shortcut_target(path: &str) -> Result<String, String> {
    use windows::core::{Interface, PCWSTR};
    use windows::Win32::System::Com::{CoCreateInstance, IPersistFile, CLSCTX_INPROC_SERVER, STGM_READ};
    use windows::Win32::UI::Shell::{IShellLinkW, ShellLink};
    let unreadable = || format!("cannot tell what `{path}` opens, so it was not opened.");
    let utf16 = |units: &[u16]| String::from_utf16_lossy(&units[..units.iter().position(|&u| u == 0).unwrap_or(units.len())]);
    // Declared first so the shell link is released before COM is left.
    let _apartment = Apartment::join(Apartment::OBJECTS);
    let file = wide(path);
    // SAFETY: calls on live COM objects with buffers of the lengths passed.
    unsafe {
        let link: IShellLinkW = CoCreateInstance(&ShellLink, None, CLSCTX_INPROC_SERVER).map_err(|_| unreadable())?;
        link.cast::<IPersistFile>().map_err(|_| unreadable())?.Load(PCWSTR(file.as_ptr()), STGM_READ).map_err(|_| unreadable())?;
        let mut target = vec![0u16; 32768];
        link.GetPath(&mut target, null_mut(), 0).map_err(|_| unreadable())?;
        let mut arguments = vec![0u16; 32768];
        link.GetArguments(&mut arguments).map_err(|_| unreadable())?;
        let target = utf16(&target);
        if target.trim().is_empty() {
            return Err(unreadable());
        }
        executable_target(&target, &utf16(&arguments))
    }
}

/// The program registered for `name` under App Paths (the user's entry first).
fn app_path(name: &str) -> Option<String> {
    let key = wide(&format!(r"Software\Microsoft\Windows\CurrentVersion\App Paths\{}", with_exe(name)));
    for root in [HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE] {
        let mut buffer = vec![0u16; 32768];
        let mut bytes = (buffer.len() * 2) as u32;
        // SAFETY: the buffer's size in bytes is passed and updated; REG_EXPAND_SZ is expanded.
        let status = unsafe {
            RegGetValueW(root, key.as_ptr(), std::ptr::null(), RRF_RT_REG_SZ, null_mut(), buffer.as_mut_ptr() as *mut c_void, &mut bytes)
        };
        if status == 0 {
            let units = &buffer[..(bytes as usize / 2).min(buffer.len())];
            return Some(String::from_utf16_lossy(units).trim_end_matches('\0').to_string());
        }
    }
    None
}

fn off_limits(label: &str) -> String {
    format!("{label} is off limits, so it was not opened.")
}

/// Opens an app, or brings it forward when it already runs, the way `open -a` does on macOS: by a
/// running app's name or executable, else a Start menu shortcut with that name, else the program
/// App Paths names. Whatever the route, only a program on a local drive is started, with
/// no arguments, and never one the blocklist names.
pub fn open_app(name: &str) -> Result<(), String> {
    let request = request(name)?;
    let own = std::process::id() as i32;
    if let Request::Name(wanted) = &request {
        // Without the list, an app already open would be started again: refused instead.
        let windows = top_windows().map_err(|error| format!("{wanted} was not opened: Gentle Dot {error}."))?;
        for (hwnd, _) in windows.into_iter().filter(|(_, window)| window.is_app()) {
            // The same identity an action aimed at the window would get (hosted pages, Store apps).
            let id = target_of(hwnd);
            if answers_to(wanted, &id.name, id.bundle_id.as_deref()) {
                if let Some(label) = blocked_reason(&id, own) {
                    return Err(off_limits(label));
                }
                // Only inside a session: the helper checked it just before.
                bring_to_front(hwnd, true);
                return if comes_to_front(hwnd) {
                    Ok(())
                } else {
                    Err(format!("{} is open, but Windows kept another app in front, so it is not in front.", id.name))
                };
            }
        }
    }
    let program = match &request {
        Request::Path(path) if strip_ci(path, ".lnk").is_some() => shortcut_target(path)?,
        Request::Path(path) => executable_target(path, "")?,
        Request::Name(wanted) => resolve_name(wanted, &start_menu_shortcuts())?,
    };
    if !std::path::Path::new(&program).is_file() {
        return Err(format!("`{program}` does not exist, so it was not opened."));
    }
    if let Some(label) = blocked_name(&program) {
        return Err(off_limits(label));
    }
    shell_open(&program)
}

/// The program a bare app name opens: a Start menu shortcut with that name, else the program App
/// Paths registers for it. PATH is never searched, so a shell tool is not opened by its file name
/// (`cmd`, `curl`); an app that registers itself in App Paths still is, as on macOS.
fn resolve_name(wanted: &str, shortcuts: &[String]) -> Result<String, String> {
    match shortcut_named(wanted, shortcuts) {
        Some(shortcut) => shortcut_target(shortcut),
        None => {
            let found = app_path(wanted);
            executable_target(&found.ok_or_else(|| format!("cannot find an app named `{wanted}`"))?, "")
        }
    }
}

/// What reading a process's integrity level gave.
#[derive(Debug, PartialEq, Eq)]
enum Integrity {
    /// The last sub-authority of its token's mandatory label.
    Level(u32),
    /// It could not be read.
    Unknown,
}

fn integrity_level(process: *mut c_void) -> Integrity {
    // SAFETY: the token is checked and closed; the label is read from a buffer of the size Windows
    // asked for, aligned for it, and its SID is validated before its sub-authorities are read.
    unsafe {
        let mut token = null_mut();
        if OpenProcessToken(process, TOKEN_QUERY, &mut token) == 0 {
            return Integrity::Unknown;
        }
        let mut size = 0u32;
        GetTokenInformation(token, TokenIntegrityLevel, null_mut(), 0, &mut size);
        let mut buffer = vec![0u64; (size as usize).div_ceil(8)];
        let read = size != 0
            && GetTokenInformation(token, TokenIntegrityLevel, buffer.as_mut_ptr() as *mut c_void, size, &mut size) != 0;
        CloseHandle(token);
        if !read {
            return Integrity::Unknown;
        }
        let sid = (*(buffer.as_ptr() as *const TOKEN_MANDATORY_LABEL)).Label.Sid;
        if sid.is_null() || IsValidSid(sid) == 0 {
            return Integrity::Unknown;
        }
        let count = *GetSidSubAuthorityCount(sid);
        if count == 0 {
            return Integrity::Unknown;
        }
        Integrity::Level(*GetSidSubAuthority(sid, u32::from(count) - 1))
    }
}

/// Why keys must not go to `app`: Windows drops input sent to a process with a higher integrity
/// level than ours (an app run as administrator) without an error, so typing there would report
/// keys that never arrived. A process whose level cannot be read is refused too: an elevated app in
/// the user's own session lets its level be read (checked on Windows 11), so one that does not is
/// another user's or a protected process, and the reason is not guessed.
pub fn keyboard_refusal(app: &AppIdentity) -> Option<String> {
    // SAFETY: the pseudo handle needs no closing; the target's handle is checked and closed.
    let (own, target) = unsafe {
        let own = integrity_level(GetCurrentProcess());
        let process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, app.pid as u32);
        let target = if process.is_null() {
            Integrity::Unknown
        } else {
            let level = integrity_level(process);
            CloseHandle(process);
            level
        };
        (own, target)
    };
    match (own, target) {
        (Integrity::Level(own), Integrity::Level(target)) if target <= own => None,
        (Integrity::Level(_), Integrity::Level(_)) => Some(runs_as_administrator(&app.name)),
        _ => Some(format!(
            "Gentle Dot cannot tell whether {} runs as administrator, so it does not send it keys.",
            app.name
        )),
    }
}

/// How many ancestors of the element under a point are read (text inside a button), as on macOS.
const AX_ANCESTORS: usize = 4;
/// How far up the focused element its window is looked for.
const WINDOW_SEARCH: usize = 32;
/// At most this many of a window's buttons are checked for the default one; a window with more
/// has an unknown default, so Return asks. The query itself is one cross-process call, bounded by
/// the UI Automation timeout.
const DEFAULT_BUTTON_SCAN: i32 = 1024;
/// UI Automation gives up on an unresponsive app after this long.
const UIA_TIMEOUT_MS: u32 = 500;


mod uia {
    pub use windows::core::Interface;
    pub use windows::Win32::Foundation::POINT;
    pub use windows::Win32::System::Com::{CoCreateInstance, CLSCTX_INPROC_SERVER};
    pub use windows::Win32::System::Variant::VARIANT;
    pub use windows::Win32::UI::Accessibility::{
        CUIAutomation8, IUIAutomation, IUIAutomation2, IUIAutomationElement, IUIAutomationLegacyIAccessiblePattern,
        IUIAutomationValuePattern, TreeScope_Descendants, UIA_ControlTypePropertyId,
        UIA_IsLegacyIAccessiblePatternAvailablePropertyId, UIA_IsValuePatternAvailablePropertyId,
        UIA_LegacyIAccessiblePatternId, UIA_LegacyIAccessibleStatePropertyId, UIA_PROPERTY_ID, UIA_ValuePatternId,
    };
}

/// A UI Automation client and its thread's COM apartment.
struct Automation {
    client: uia::IUIAutomation,
    /// Declared after `client` so the client is released before COM is left.
    _apartment: Apartment,
}

/// This thread's COM apartment, joined for one call: the only place COM is entered. A thread
/// already in another apartment keeps it (`RPC_E_CHANGED_MODE`), and the call runs there.
struct Apartment(bool);

impl Apartment {
    /// For the shell (`ShellExecuteW`), which wants a single-threaded apartment.
    const SHELL: windows::Win32::System::Com::COINIT = windows::Win32::System::Com::COINIT(
        windows::Win32::System::Com::COINIT_APARTMENTTHREADED.0 | windows::Win32::System::Com::COINIT_DISABLE_OLE1DDE.0,
    );
    /// For COM objects called from this thread only (UI Automation, shell links).
    const OBJECTS: windows::Win32::System::Com::COINIT = windows::Win32::System::Com::COINIT_MULTITHREADED;

    fn join(model: windows::Win32::System::Com::COINIT) -> Apartment {
        // SAFETY: COM initialization on this thread, balanced by Drop when it succeeded (S_FALSE,
        // already in that apartment, counts and is balanced too).
        Apartment(unsafe { windows::Win32::System::Com::CoInitializeEx(None, model) }.is_ok())
    }
}

impl Drop for Apartment {
    fn drop(&mut self) {
        if self.0 {
            // SAFETY: balances the successful CoInitializeEx on this thread.
            unsafe { windows::Win32::System::Com::CoUninitialize() };
        }
    }
}

// The client never leaves its thread. It is released before the apartment is uninitialized at
// thread exit; an existing apartment of a different model remains owned by its original caller.
// A failed client creation or timeout configuration is cached as None for the thread's life and
// never retried: that thread's queries all read as unreadable, which stays fail-closed.
thread_local! {
    static AUTOMATION: Option<std::rc::Rc<Automation>> = Automation::create().map(std::rc::Rc::new);
}

impl Automation {
    /// This thread's client: created on its first query and kept for the thread's life (the
    /// helper serves each request on a thread of its own, so a request's queries share one).
    fn new() -> Option<std::rc::Rc<Automation>> {
        AUTOMATION.try_with(Clone::clone).ok().flatten()
    }

    fn create() -> Option<Automation> {
        let apartment = Apartment::join(Apartment::OBJECTS);
        // SAFETY: creating the system's UI Automation object.
        let client: uia::IUIAutomation =
            unsafe { uia::CoCreateInstance(&uia::CUIAutomation8, None, uia::CLSCTX_INPROC_SERVER) }.ok()?;
        // Without its timeouts a hung app could stall the helper: no client then (what it would
        // have read is unreadable, which asks for a confirmation).
        let timeouts = uia::Interface::cast::<uia::IUIAutomation2>(&client).ok()?;
        // SAFETY: plain setters on a live client.
        unsafe {
            timeouts.SetConnectionTimeout(UIA_TIMEOUT_MS).ok()?;
            timeouts.SetTransactionTimeout(UIA_TIMEOUT_MS).ok()?;
        }
        Some(Automation { client, _apartment: apartment })
    }

    fn parent(&self, of: &uia::IUIAutomationElement) -> Option<uia::IUIAutomationElement> {
        // SAFETY: calls on live COM objects.
        unsafe { self.client.ControlViewWalker().ok()?.GetParentElement(of).ok() }
    }

    /// Whether `of` ends its chain: the desktop or any Window ancestor. A nested Window still
    /// holds the element, and the risk check reads the pressable element before its ancestors.
    fn ends_chain(&self, of: &uia::IUIAutomationElement) -> bool {
        // SAFETY: calls on live COM objects.
        let root = unsafe { self.client.GetRootElement() }
            .and_then(|root| unsafe { self.client.CompareElements(&root, of) })
            .is_ok_and(|same| same.as_bool());
        root || control_type(of) == UIA_WINDOW
    }
}

fn control_type(of: &uia::IUIAutomationElement) -> i32 {
    // SAFETY: a call on a live COM object.
    unsafe { of.CurrentControlType() }.map_or(0, |t| t.0)
}

/// A boolean property; an error when UI Automation did not answer.
fn property_bool(of: &uia::IUIAutomationElement, property: uia::UIA_PROPERTY_ID) -> Result<bool, ()> {
    // SAFETY: a call on a live COM object.
    let value = unsafe { of.GetCurrentPropertyValue(property) }.map_err(|_| ())?;
    bool::try_from(&value).map_err(|_| ())
}

/// The legacy accessible state, where the default button is marked: none for an element without
/// one, an error when UI Automation did not answer.
fn legacy_state(of: &uia::IUIAutomationElement) -> Result<Option<u32>, ()> {
    if !property_bool(of, uia::UIA_IsLegacyIAccessiblePatternAvailablePropertyId)? {
        return Ok(None);
    }
    // SAFETY: calls on live COM objects.
    unsafe {
        let legacy = of
            .GetCurrentPatternAs::<uia::IUIAutomationLegacyIAccessiblePattern>(uia::UIA_LegacyIAccessiblePatternId)
            .map_err(|_| ())?;
        legacy.CurrentState().map(Some).map_err(|_| ())
    }
}

/// An element in the risk check's terms. Any property UI Automation does not report (type, name,
/// help text, whether it is a password, whether it has a value, the value) makes it an unreadable
/// element, which asks for a confirmation. A password field's value is never read.
fn describe(of: &uia::IUIAutomationElement) -> AxElement {
    // SAFETY: calls on live COM objects.
    unsafe {
        let (Ok(kind), Ok(name), Ok(help), Ok(password)) =
            (of.CurrentControlType(), of.CurrentName(), of.CurrentHelpText(), of.CurrentIsPassword())
        else {
            return unreadable();
        };
        let Ok(has_value) = property_bool(of, uia::UIA_IsValuePatternAvailablePropertyId) else { return unreadable() };
        let value = if password.as_bool() || !has_value {
            None
        } else {
            let read = of
                .GetCurrentPatternAs::<uia::IUIAutomationValuePattern>(uia::UIA_ValuePatternId)
                .and_then(|pattern| pattern.CurrentValue());
            match read {
                Ok(value) => Some(value.to_string()),
                Err(_) => return unreadable(),
            }
        };
        element(kind.0, Some(name.to_string()), Some(help.to_string()), value)
    }
}

/// The element under `at`, then its ancestors (as many as macOS reads); empty when unknown.
/// UI Automation that does not answer makes the element an unreadable one, which asks for a
/// confirmation: an action is never let through because Windows did not say what is there.
pub fn element_at(at: Point) -> Vec<AxElement> {
    let Some(automation) = Automation::new() else { return vec![unreadable()] };
    let point = uia::POINT { x: at.x.round() as i32, y: at.y.round() as i32 };
    // SAFETY: a call on a live COM object.
    let Ok(mut current) = (unsafe { automation.client.ElementFromPoint(point) }) else { return vec![unreadable()] };
    // The hit test went through Gentle Dot's click-through glow while another app owns the window
    // there: what is under the glow cannot be read, so it asks for a confirmation.
    let own = std::process::id() as i32;
    // SAFETY: a call on a live COM object.
    // A process Windows does not report (or reports as no process) counts as Gentle Dot's: the
    // element is not read either.
    let hit_own = unsafe { current.CurrentProcessId() }.map_or(true, |pid| pid <= 0 || pid == own);
    // Only Gentle Dot's own window there (whose actions are refused anyway) is described.
    if hit_own && !window_owner_at(at).is_some_and(|owner| owner.pid == own) {
        return vec![unreadable()];
    }
    let mut chain = vec![describe(&current)];
    while chain.len() <= AX_ANCESTORS {
        let Some(parent) = automation.parent(&current) else {
            // Cut short before the window: what holds the element is not known, so it asks.
            if !automation.ends_chain(&current) {
                chain.push(unreadable());
            }
            break;
        };
        chain.push(describe(&parent));
        current = parent;
    }
    known_chain(chain)
}

/// The window holding `of`: its nearest Window ancestor, as macOS reads `AXWindow`. None when
/// there is none (the desktop); an error when the way up was cut short.
fn window_of(automation: &Automation, of: &uia::IUIAutomationElement) -> Result<Option<uia::IUIAutomationElement>, ()> {
    let mut current = of.clone();
    for _ in 0..WINDOW_SEARCH {
        // SAFETY: a call on a live COM object.
        let kind = unsafe { current.CurrentControlType() }.map_err(|_| ())?;
        if kind.0 == UIA_WINDOW {
            return Ok(Some(current));
        }
        match automation.parent(&current) {
            Some(parent) => current = parent,
            None if automation.ends_chain(&current) => return Ok(None),
            None => return Err(()),
        }
    }
    Err(())
}

/// The window's default button (`AXDefaultButton` on macOS), if it has one; an error when Windows
/// did not answer. One cross-process call fetches every button of the window with its legacy
/// state, within the UI Automation timeout.
fn default_button(
    automation: &Automation,
    window: &uia::IUIAutomationElement,
) -> windows::core::Result<Option<uia::IUIAutomationElement>> {
    // SAFETY: calls on live COM objects.
    unsafe {
        let buttons = automation.client.CreatePropertyCondition(uia::UIA_ControlTypePropertyId, &uia::VARIANT::from(UIA_BUTTON))?;
        let cache = automation.client.CreateCacheRequest()?;
        cache.AddProperty(uia::UIA_LegacyIAccessibleStatePropertyId)?;
        let found = window.FindAllBuildCache(uia::TreeScope_Descendants, &buttons, &cache)?;
        let total = found.Length()?;
        // Every button is read: one that cannot be could be the default, so the scan fails.
        for i in 0..total.min(DEFAULT_BUTTON_SCAN) {
            let button = found.GetElement(i)?;
            let state = button.GetCachedPropertyValue(uia::UIA_LegacyIAccessibleStatePropertyId)?;
            let state = i32::try_from(&state)?;
            if is_default(state as u32) {
                return Ok(Some(button));
            }
        }
        // Buttons left unread could hold the default: the answer is not known, so Return asks.
        if total > DEFAULT_BUTTON_SCAN {
            return Err(windows::Win32::Foundation::E_FAIL.into());
        }
        Ok(None)
    }
}

/// The focused element, whether it is its window's default button, and that button.
/// A focus UI Automation does not report is an unreadable element (Return and Space then ask for
/// a confirmation), and a default button it does not report an unreadable one (Return asks).
pub fn focused_element() -> Option<Focus> {
    let unknown = || Some(Focus { element: unreadable(), is_default_button: false, default_button: None });
    let Some(automation) = Automation::new() else { return unknown() };
    // SAFETY: a call on a live COM object.
    let Ok(focused) = (unsafe { automation.client.GetFocusedElement() }) else { return unknown() };
    let default = match window_of(&automation, &focused) {
        Ok(Some(window)) => default_button(&automation, &window).map_err(|_| ()),
        Ok(None) => Ok(None),
        Err(()) => Err(()),
    };
    // A comparison or state UI Automation does not answer counts as the default button.
    // SAFETY: a call on a live COM object.
    let same = |button: &uia::IUIAutomationElement| unsafe { automation.client.CompareElements(button, &focused) }.map_or(true, |b| b.as_bool());
    let marked = legacy_state(&focused).map_or(true, |state| state.is_some_and(is_default));
    let is_default_button = marked || default.as_ref().is_ok_and(|d| d.as_ref().is_some_and(same));
    let default_button = match &default {
        Ok(found) => found.as_ref().map(describe),
        Err(()) => Some(unreadable()),
    };
    Some(Focus { element: describe(&focused), is_default_button, default_button })
}

/// The process of the focused UI Automation element.
fn focused_pid() -> Option<i32> {
    let automation = Automation::new()?;
    // SAFETY: calls on live COM objects.
    let pid = unsafe { automation.client.GetFocusedElement().ok()?.CurrentProcessId().ok()? };
    (pid > 0).then_some(pid)
}

/// The frame of the display containing the point, in physical pixels.
pub fn display_frame_at(at: Point) -> Option<Frame> {
    monitor_at(at).map(|m| Frame { x: f64::from(m.x), y: f64::from(m.y), width: f64::from(m.width), height: f64::from(m.height) })
}

/// Physical pixels per CSS pixel for this display.
pub fn display_scale(display: Frame) -> f64 {
    let center = POINT { x: (display.x + display.width / 2.0) as i32, y: (display.y + display.height / 2.0) as i32 };
    let (mut dpi_x, mut dpi_y) = (0u32, 0u32);
    // SAFETY: valid monitor and out-pointers.
    let read = unsafe { GetDpiForMonitor(MonitorFromPoint(center, MONITOR_DEFAULTTONEAREST), MDT_EFFECTIVE_DPI, &mut dpi_x, &mut dpi_y) };
    if read == 0 && dpi_x > 0 { f64::from(dpi_x) / 96.0 } else { 1.0 }
}

/// The focused element's frame, in physical pixels.
pub fn focused_frame() -> Option<Frame> {
    let automation = Automation::new()?;
    // SAFETY: calls on live COM objects.
    let rect = unsafe { automation.client.GetFocusedElement().ok()?.CurrentBoundingRectangle().ok()? };
    let (width, height) = (rect.right - rect.left, rect.bottom - rect.top);
    (width > 0 && height > 0).then(|| Frame { x: f64::from(rect.left), y: f64::from(rect.top), width: f64::from(width), height: f64::from(height) })
}

/// Prevent activation and capture of the click-through glow. A glow that cannot be kept out of
/// screenshots is not used: without it no call captures or acts (S5).
pub fn prepare_overlay(hwnd: *mut c_void) -> Result<(), String> {
    // These extended styles are written behind tao's back, so tao's cached flags do not have them:
    // any later tao call that sets window flags on the glow would drop WS_EX_TOOLWINDOW. Nothing
    // does today; keep it that way, or set them again after such a call.
    // SAFETY: calls on this process's window.
    unsafe {
        let style = GetWindowLongPtrW(hwnd, GWL_EXSTYLE);
        SetWindowLongPtrW(hwnd, GWL_EXSTYLE, style | (WS_EX_NOACTIVATE | WS_EX_TOOLWINDOW) as isize);
    }
    exclude_from_capture(hwnd).map_err(|error| format!("it would show in computer-control screenshots: {error}"))
}

/// Show above other windows without activation, or hide.
pub fn show_overlay(hwnd: *mut c_void, visible: bool) {
    // SAFETY: calls on this process's window.
    unsafe {
        if visible {
            ShowWindow(hwnd, SW_SHOWNOACTIVATE);
            SetWindowPos(hwnd, HWND_TOPMOST, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
        } else { ShowWindow(hwnd, SW_HIDE); }
    }
}

// Main-thread show/hide callers serialize these entries. Keep the original value, including
// WDA_MONITOR, rather than assuming every window started at WDA_NONE. Showing releases an entry;
// the owning call's restore phase releases its remainder, including a user-hidden Dot.
// A newer hide takes ownership without losing the original affinity; delayed older restores
// cannot release it. Failed dispatch restores affinity directly without showing the window.
// If native restoration fails, owner None retains the original for the next show (after showing)
// or hide (adopt, never read the still-excluded value). Logical keys bound this to one record
// per Dot/panel for the process lifetime, never per recyclable HWND or failed call.
static CALL_AFFINITIES: std::sync::Mutex<Vec<(Option<u64>, (super::working::Part, u32))>> = std::sync::Mutex::new(Vec::new());
// The Dot and panel are created once and live until process exit. Record their handles on
// the main thread at creation; worker cleanup must never query Tauri while holding our lock.
static CALL_DOT: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
static CALL_PANEL: std::sync::OnceLock<usize> = std::sync::OnceLock::new();

// An exhaustive match, so a new Part fails to compile here instead of indexing out of bounds.
fn call_slot(part: super::working::Part) -> &'static std::sync::OnceLock<usize> {
    match part {
        super::working::Part::Dot => &CALL_DOT,
        super::working::Part::Panel => &CALL_PANEL,
    }
}

// Strict on purpose: ignoring a second creation would keep the old handle, so calls would hide
// and exclude a window that no longer exists while the new one stays in screenshots.
pub fn record_call_window(part: super::working::Part, hwnd: HWND) {
    call_slot(part).set(hwnd as usize).expect("call window is created only once");
}

fn call_window(part: super::working::Part) -> Option<usize> {
    call_slot(part).get().copied()
}

fn call_handles() -> super::capture_order::CallHandles {
    super::capture_order::CallHandles {
        dot: call_window(super::working::Part::Dot),
        panel: call_window(super::working::Part::Panel),
    }
}

/// Exclude before hiding. If exclusion fails, still hide, then put this window back and fail
/// preparation: Working has not yet recorded it as hidden and cannot restore it on that error.
/// The failed call therefore never reaches capture, and no persistent failure poisons later calls.
pub fn hide_for_call(part: super::working::Part, operation: u64) -> Result<(), String> {
    let hwnd = call_window(part).ok_or_else(|| format!("window {part:?} is missing"))? as HWND;
    let _change = WindowChange::begin();
    let mut saved = CALL_AFFINITIES.lock().unwrap_or_else(|error| error.into_inner());
    let result = super::capture_order::hide(|| {
        if let Some((owner, _)) = saved.iter_mut().find(|(_, (window, _))| *window == part) {
            set_capture_excluded(hwnd, true)?;
            *owner = Some(operation);
            return Ok(());
        }
        let mut previous = 0;
        // SAFETY: a query on our window with a valid out-pointer.
        if unsafe { GetWindowDisplayAffinity(hwnd, &mut previous) } == 0 {
            return Err(format!("cannot read its capture affinity: {}", std::io::Error::last_os_error()));
        }
        set_capture_excluded(hwnd, true)?;
        saved.push((Some(operation), (part, previous)));
        Ok(())
    }, || {
        // SAFETY: a call on this process's window.
        unsafe { ShowWindow(hwnd, SW_HIDE) };
    });
    drop(saved);
    if let Err(error) = result {
        show_without_activating(hwnd);
        return Err(format!("{OWN_WINDOW_SHOWN} {error}"));
    }
    Ok(())
}

fn restore_call_affinity(hwnd: HWND) {
    let mut saved = CALL_AFFINITIES.lock().unwrap_or_else(|error| error.into_inner());
    let Some(index) = super::capture_order::current_window(&saved, hwnd as usize, call_handles()) else { return };
    let previous = saved[index].1.1;
    // This function is called only inside the showing WindowChange, after ShowWindow. Restoring
    // even a nonzero affinity must count as a change, so an overlapping capture cannot be accepted.
    // SAFETY: a call on this process's window, restoring the value read before the call.
    if unsafe { SetWindowDisplayAffinity(hwnd, previous) } != 0 {
        saved.remove(index);
    } else {
        eprintln!("gentle-dot: a window may stay out of screenshots: {}", std::io::Error::last_os_error());
    }
}

/// End the serialized call's affinity ownership after its eligible windows have been shown.
/// Remaining windows were left hidden by the user (or their show/affinity restore failed).
/// Read the recorded handles only; native failures retain ownerless recovery values.
pub fn finish_call_affinities(operation: u64) {
    let _change = WindowChange::begin();
    let mut saved = CALL_AFFINITIES.lock().unwrap_or_else(|error| error.into_inner());
    super::capture_order::release(&mut saved, operation, |(part, previous)| {
        let Some(hwnd) = call_window(part) else { return true };
        // SAFETY: the current handle of our logical window. This API requires process
        // ownership, not the window's thread, so dispatch failure can restore it directly.
        let restored = unsafe { SetWindowDisplayAffinity(hwnd as HWND, previous) } != 0;
        if !restored {
            eprintln!("gentle-dot: a window may stay out of screenshots: {}", std::io::Error::last_os_error());
        }
        restored
    });
}

/// Main-thread dispatch failed: leave windows hidden but restore their original affinity
/// inside WindowChange. The owner filter protects a newer hide; failures keep recovery values.
pub fn abandon_call_affinities(operation: u64) {
    finish_call_affinities(operation);
}

pub fn show_without_activating(hwnd: *mut c_void) {
    let _change = WindowChange::begin();
    super::capture_order::show(|| {
        // SAFETY: a call on this process's window.
        unsafe { ShowWindow(hwnd, SW_SHOWNOACTIVATE) };
    }, || restore_call_affinity(hwnd));
}

pub fn hide_window(hwnd: *mut c_void) {
    let _change = WindowChange::begin();
    // SAFETY: a call on this process's window.
    unsafe { ShowWindow(hwnd, SW_HIDE) };
}

pub fn show_window(hwnd: *mut c_void) {
    let _change = WindowChange::begin();
    super::capture_order::show(|| {
        // SAFETY: a call on this process's window.
        unsafe { ShowWindow(hwnd, SW_SHOW) };
    }, || restore_call_affinity(hwnd));
}

/// Move the glow over a display without activating it.
pub fn cover(hwnd: *mut c_void, display: Frame) {
    // SAFETY: a call on this process's window.
    unsafe { SetWindowPos(hwnd, HWND_TOPMOST, display.x as i32, display.y as i32, display.width as i32, display.height as i32, SWP_NOACTIVATE); }
}

/// The first build that can leave a window out of captures (`WDA_EXCLUDEFROMCAPTURE`): Windows
/// 10 version 2004.
const CAPTURE_EXCLUSION_BUILD: u32 = 19041;

/// This system's build number. The registry says it as it is; `GetVersionEx` answers what the
/// app's manifest names.
fn windows_build() -> Option<u32> {
    let key = wide(r"SOFTWARE\Microsoft\Windows NT\CurrentVersion");
    let value = wide("CurrentBuildNumber");
    let mut buffer = vec![0u16; 64];
    let mut bytes = (buffer.len() * 2) as u32;
    // SAFETY: the buffer's size in bytes is passed and updated.
    let status = unsafe {
        RegGetValueW(
            HKEY_LOCAL_MACHINE, key.as_ptr(), value.as_ptr(), RRF_RT_REG_SZ, null_mut(),
            buffer.as_mut_ptr() as *mut c_void, &mut bytes,
        )
    };
    if status != 0 {
        return None;
    }
    let units = &buffer[..(bytes as usize / 2).min(buffer.len())];
    String::from_utf16_lossy(units).trim_end_matches('\0').trim().parse().ok()
}

/// Why screenshots cannot leave Gentle Dot's windows out, or `None` when they can. A build that
/// cannot be read counts as unable too: before Windows 10 version 2004 the exclusion does not
/// fail, it just leaves a black box (`WDA_MONITOR`), so a failed exclusion cannot be relied on to
/// say so.
fn capture_exclusion_unsupported(build: Option<u32>) -> Option<ScreenshotsUnsupported> {
    match build {
        None => Some(ScreenshotsUnsupported::UnknownVersion),
        Some(build) if build < CAPTURE_EXCLUSION_BUILD => Some(ScreenshotsUnsupported::TooOld),
        Some(_) => None,
    }
}

/// The Windows desktop the helper drives.
pub struct WinDesktop;

impl super::Desktop for WinDesktop {
    fn keyboard_refusal(&self, app: &AppIdentity) -> Option<String> {
        keyboard_refusal(app)
    }

    fn permissions(&self) -> super::Permissions {
        // Windows asks for no permission to send input or take screenshots; leaving Gentle Dot's
        // windows out of them needs a recent enough build.
        let screenshots_unsupported = capture_exclusion_unsupported(windows_build());
        super::Permissions {
            accessibility: true,
            screen_recording: true,
            screenshots_supported: screenshots_unsupported.is_none(),
            screenshots_unsupported,
        }
    }

    fn capture(&self) -> Result<Capture, String> {
        capture()
    }

    fn post(&self, event: &InputEvent) -> Result<(), String> {
        post(event)
    }

    fn post_typed(&self, event: &InputEvent, recipient: &KeyboardRecipient) -> Result<(), TypedError> {
        post_typed(event, recipient)
    }

    fn list_apps(&self) -> Result<Vec<AppInfo>, String> {
        list_apps()
    }

    fn open_app(&self, name: &str) -> Result<(), String> {
        open_app(name)
    }

    fn element_at(&self, at: Point) -> Vec<AxElement> {
        element_at(at)
    }

    fn focused_element(&self) -> Option<Focus> {
        focused_element()
    }

    fn frontmost_app(&self) -> Option<AppIdentity> {
        frontmost_app()
    }

    fn focused_app(&self) -> Option<AppIdentity> {
        focused_app()
    }

    fn window_owner_at(&self, at: Point) -> Option<AppIdentity> {
        window_owner_at(at)
    }

    fn activate(&self, pid: i32) {
        activate(pid)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[ignore = "interactive Windows desktop: minimize Settings before running"]
    fn detached_settings_is_still_an_unidentified_refused_target() {
        let (hwnd, _) = top_windows().unwrap().into_iter().find(|(hwnd, window)| {
            window.is_app() && class_name(*hwnd).as_deref() == Some(FRAME_CLASS)
                && app_pid(*hwnd).is_none() && is_frame_host(&identity(window.pid))
                && listed_name(true, frame_app_name(*hwnd), Some(window.title.clone()), String::new())
                    .eq_ignore_ascii_case("Settings")
        }).expect("minimize Settings in an English Windows session first");
        let target = target_of(hwnd);
        assert_eq!(target.name, UNIDENTIFIED);
        assert!(target.bundle_id.is_none());
        assert!(blocked_reason(&target, std::process::id() as i32).is_some());
    }

    fn per_monitor_aware() {
        use windows_sys::Win32::UI::HiDpi::{SetProcessDpiAwarenessContext, DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2};
        // SAFETY: plain call; the app itself is already per-monitor aware.
        unsafe { SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) };
    }

    #[test]
    #[ignore = "interactive Windows desktop: run in the user's own session"]
    fn opening_a_running_app_brings_its_window_to_the_front() {
        use windows_sys::Win32::UI::WindowsAndMessaging::{PostMessageW, WM_CLOSE};
        let notepads = || -> Vec<usize> {
            top_windows()
                .expect("the windows are listed")
                .into_iter()
                .filter(|(hwnd, window)| {
                    window.is_app() && target_of(*hwnd).bundle_id.as_deref().is_some_and(|exe| exe.eq_ignore_ascii_case("Notepad.exe"))
                })
                .map(|(hwnd, _)| hwnd as usize)
                .collect()
        };
        let before = notepads();
        // It closes the windows it opens: with another Notepad open, which ones are its own is
        // unknown, so it does not run.
        assert!(before.is_empty(), "close every Notepad window first");
        let close_new = |now: &[usize]| {
            for hwnd in now.iter().filter(|hwnd| !before.contains(hwnd)) {
                // SAFETY: a plain message to a window this test opened.
                unsafe { PostMessageW(*hwnd as HWND, WM_CLOSE, 0, 0) };
            }
        };
        open_app("notepad.exe").expect("Notepad opens");
        let mut first = notepads();
        for _ in 0..50 {
            if first.len() > before.len() {
                break;
            }
            std::thread::sleep(std::time::Duration::from_millis(200));
            first = notepads();
        }
        eprintln!("before {before:x?}, after the first open {first:x?}, front {:?}", frontmost_app());
        open_app("notepad.exe").expect("Notepad is found");
        std::thread::sleep(std::time::Duration::from_secs(3));
        let second = notepads();
        let front = frontmost_app();
        eprintln!("after the second open {second:x?}, front {front:?}");
        close_new(&second);
        assert_eq!(first.len(), before.len() + 1, "the first open_app opens one window");
        assert_eq!(second, first, "the second open_app opens no other window");
        assert_eq!(front.and_then(|app| app.bundle_id).as_deref(), Some("Notepad.exe"), "Notepad is in front");
    }

    #[test]
    fn this_process_is_identified_by_its_executable_and_a_name() {
        let own = identity(std::process::id() as i32);
        let exe = own.bundle_id.expect("the test process can query itself");
        assert!(exe.to_ascii_lowercase().ends_with(".exe"), "{exe}");
        assert!(!own.name.is_empty() && !own.name.starts_with("process "), "{}", own.name);
        assert_eq!(identity(-5).name, "process -5", "an unknown process keeps its number");
    }

    /// T48: a bare name never resolves through PATH, so shell tools in System32 are not opened by
    /// name (`cmd.exe` and `curl.exe` are in System32, which is in PATH, and neither is in App
    /// Paths). No shortcut is passed, so only App Paths could answer.
    #[test]
    fn a_window_listing_failure_without_an_error_code_says_so() {
        assert_eq!(enumeration_failure(std::io::Error::from_raw_os_error(0)), "EnumWindows failed without an error code");
        let denied = std::io::Error::from_raw_os_error(5);
        assert_eq!(enumeration_failure(denied), std::io::Error::from_raw_os_error(5).to_string());
    }

    #[test]
    fn a_bare_name_is_not_resolved_through_path() {
        for name in ["cmd", "curl", "certutil"] {
            assert_eq!(resolve_name(name, &[]), Err(format!("cannot find an app named `{name}`")), "{name}");
        }
    }

    #[test]
    fn this_process_takes_its_own_keys() {
        assert_eq!(keyboard_refusal(&identity(std::process::id() as i32)), None);
    }

    #[test]
    fn a_process_whose_level_cannot_be_read_gets_no_keys() {
        let ghost = AppIdentity { pid: i32::MAX, bundle_id: None, name: "Ghost".into() };
        assert_eq!(
            keyboard_refusal(&ghost).as_deref(),
            Some("Gentle Dot cannot tell whether Ghost runs as administrator, so it does not send it keys.")
        );
    }

    /// A recipient the windows in front do not belong to gets nothing; on a desktop with nothing
    /// in front, as on CI, the front is unknown instead, so CI rarely reaches the recipient check:
    /// the interactive run covers it.
    #[test]
    fn keys_for_another_recipient_are_not_posted() {
        let elsewhere = KeyboardRecipient { front_pid: i32::MAX, focused_pid: None };
        let result = post_typed(&InputEvent::Text("x".into()), &elsewhere);
        assert!(
            matches!(result, Err(TypedError::RecipientChanged | TypedError::FrontUnknown | TypedError::NoFocus)),
            "{result:?}"
        );
    }

    /// Start an elevated console ("Run as administrator") and pass its process id in
    /// `GENTLE_DOT_ELEVATED_PID`.
    #[test]
    #[ignore = "interactive Windows desktop: run in the user's own session"]
    fn an_elevated_console_gets_no_keys() {
        let pid: i32 = std::env::var("GENTLE_DOT_ELEVATED_PID").expect("GENTLE_DOT_ELEVATED_PID").parse().unwrap();
        let console = identity(pid);
        assert_eq!(keyboard_refusal(&console), Some(runs_as_administrator(&console.name)));
    }

    /// UI Automation answers, or says it cannot, within its timeout even with no desktop in front
    /// (CI): an element it cannot read is the unreadable one, which asks for a confirmation.
    #[test]
    fn ui_automation_answers_without_a_desktop() {
        assert!(!element_at(Point { x: 0.0, y: 0.0 }).is_empty());
        assert!(focused_element().is_some());
    }

    #[test]
    fn the_desktop_wires_this_backend() {
        use super::super::Desktop;
        let desktop = WinDesktop;
        let own = identity(std::process::id() as i32);
        assert_eq!(desktop.keyboard_refusal(&own), None);
        let ghost = AppIdentity { pid: i32::MAX, bundle_id: None, name: "Ghost".into() };
        assert_eq!(desktop.keyboard_refusal(&ghost), keyboard_refusal(&ghost));
        let permissions = desktop.permissions();
        assert!(permissions.accessibility && permissions.screen_recording);
        assert_eq!(permissions.screenshots_unsupported, capture_exclusion_unsupported(windows_build()));
        assert_eq!(permissions.screenshots_supported, permissions.screenshots_unsupported.is_none());
    }

    /// The machine's own answer follows its build, so the test holds before 2004 too.
    #[test]
    fn screenshots_need_windows_10_2004() {
        assert_eq!(capture_exclusion_unsupported(Some(19040)), Some(ScreenshotsUnsupported::TooOld));
        assert_eq!(capture_exclusion_unsupported(Some(19041)), None);
        assert_eq!(capture_exclusion_unsupported(Some(26100)), None);
        assert_eq!(
            capture_exclusion_unsupported(None),
            Some(ScreenshotsUnsupported::UnknownVersion),
            "an unreadable build is not trusted, nor called too old"
        );
        let build = windows_build().expect("the build number is readable");
        use super::super::Desktop;
        let permissions = WinDesktop.permissions();
        assert_eq!(permissions.screenshots_supported, build >= CAPTURE_EXCLUSION_BUILD, "{build}");
        let too_old = (build < CAPTURE_EXCLUSION_BUILD).then_some(ScreenshotsUnsupported::TooOld);
        assert_eq!(permissions.screenshots_unsupported, too_old, "{build}");
    }

    /// Windows that could not be listed may include ours: the capture is not clean. Nothing
    /// visible is.
    #[test]
    fn unlisted_windows_are_not_excluded() {
        assert!(!every_window_excluded(Err("cannot list its windows".into())));
        assert!(every_window_excluded(Ok(Vec::new())));
        assert!(!every_window_excluded(Ok(vec![null_mut()])));
    }

    /// The message CC8 quotes to the agent.
    #[test]
    fn a_capture_our_window_could_show_in_says_so() {
        assert_eq!(OWN_WINDOW_SHOWN, "Gentle Dot's window could show in the screenshot, so it was not taken. Take another.");
    }

    /// A window of this process shown and not excluded is left out of a capture, then shows in
    /// screenshots again: the capture puts back what it changed (#163 finding 3, CC8 review).
    #[test]
    #[ignore = "interactive Windows desktop: run in the user's own session"]
    fn a_capture_puts_our_windows_back_as_it_found_them() {
        use windows_sys::Win32::UI::WindowsAndMessaging::{CreateWindowExW, DestroyWindow, WS_OVERLAPPEDWINDOW, WS_VISIBLE};
        per_monitor_aware();
        let class = wide("STATIC");
        let title = wide("Gentle Dot capture test");
        // SAFETY: a plain window of this test process, destroyed below.
        let hwnd = unsafe {
            CreateWindowExW(0, class.as_ptr(), title.as_ptr(), WS_OVERLAPPEDWINDOW | WS_VISIBLE, 100, 100, 300, 200, null_mut(), null_mut(), null_mut(), null_mut())
        };
        assert!(!hwnd.is_null());
        assert!(!is_excluded(hwnd));
        let shot = capture();
        let excluded_after = is_excluded(hwnd);
        // SAFETY: the window created above.
        unsafe { DestroyWindow(hwnd) };
        shot.expect("a screenshot");
        assert!(!excluded_after, "the capture put the window's affinity back");
    }

    /// A capture overlapping a change of our windows in any way is not returned: one under way
    /// when it starts stops it, and one that begins or ends before it ends moves the count. Every
    /// route counts: letting a window show again (even a failed attempt), a capture's own restore,
    /// showing and hiding. One test: all use the same counters.
    #[test]
    fn captures_notice_windows_changed_meanwhile() {
        // Under way when the capture starts.
        let change = WindowChange::begin();
        assert_eq!(capture_baseline(), Err(OWN_WINDOW_BUSY.to_string()));
        drop(change);
        // Begins and ends within the capture.
        let baseline = capture_baseline().expect("nothing under way");
        drop(WindowChange::begin());
        assert!(!unchanged_since(baseline));
        // Begins within the capture, still under way when it ends.
        let baseline = capture_baseline().expect("nothing under way");
        let change = WindowChange::begin();
        assert!(!unchanged_since(baseline));
        drop(change);
        // Every route is a whole change.
        let routes: [(&str, &dyn Fn()); 5] = [
            ("let show again", &|| { let _ = set_capture_excluded(null_mut(), false); }),
            ("restored after a capture", &|| restore_affinity(&[(null_mut(), WDA_NONE)])),
            ("shown", &|| show_window(null_mut())),
            ("shown without activation", &|| show_without_activating(null_mut())),
            ("hidden", &|| hide_window(null_mut())),
        ];
        for (what, route) in routes {
            let baseline = capture_baseline().expect("nothing under way");
            route();
            assert!(!unchanged_since(baseline), "{what}");
            assert!(capture_baseline().is_ok(), "{what} ended");
        }
        // Excluding a window is not a change a capture must see.
        let baseline = capture_baseline().expect("nothing under way");
        let _ = set_capture_excluded(null_mut(), true);
        assert!(unchanged_since(baseline));
    }

    #[test]
    fn each_step_becomes_the_input_record_windows_expects() {
        let mouse = |step| {
            let record = input(step);
            assert_eq!(record.r#type, INPUT_MOUSE);
            // SAFETY: `input` wrote the mouse member for a mouse step.
            let mi = unsafe { record.Anonymous.mi };
            (mi.dx, mi.dy, mi.mouseData as i32, mi.dwFlags)
        };
        let keyboard = |step| {
            let record = input(step);
            assert_eq!(record.r#type, INPUT_KEYBOARD);
            // SAFETY: `input` wrote the keyboard member for a key step.
            let ki = unsafe { record.Anonymous.ki };
            (ki.wVk, ki.wScan, ki.dwFlags)
        };
        assert_eq!(
            mouse(Step::Move { x: 10, y: 65535 }),
            (10, 65535, 0, MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_VIRTUALDESK)
        );
        assert_eq!(mouse(Step::Button { button: MouseButton::Left, down: true }), (0, 0, 0, MOUSEEVENTF_LEFTDOWN));
        assert_eq!(mouse(Step::Button { button: MouseButton::Left, down: false }), (0, 0, 0, MOUSEEVENTF_LEFTUP));
        assert_eq!(mouse(Step::Button { button: MouseButton::Right, down: true }), (0, 0, 0, MOUSEEVENTF_RIGHTDOWN));
        assert_eq!(mouse(Step::Button { button: MouseButton::Right, down: false }), (0, 0, 0, MOUSEEVENTF_RIGHTUP));
        assert_eq!(mouse(Step::Wheel { horizontal: false, delta: -240 }), (0, 0, -240, MOUSEEVENTF_WHEEL));
        assert_eq!(mouse(Step::Wheel { horizontal: true, delta: 120 }), (0, 0, 120, MOUSEEVENTF_HWHEEL));
        assert_eq!(keyboard(Step::Key { vk: 0x41, down: true, extended: false }), (0x41, 0, 0));
        assert_eq!(
            keyboard(Step::Key { vk: 0x25, down: false, extended: true }),
            (0x25, 0, KEYEVENTF_KEYUP | KEYEVENTF_EXTENDEDKEY)
        );
        assert_eq!(keyboard(Step::Unicode { unit: 0xD83E, down: true }), (0, 0xD83E, KEYEVENTF_UNICODE));
        assert_eq!(
            keyboard(Step::Unicode { unit: 0xDD80, down: false }),
            (0, 0xDD80, KEYEVENTF_UNICODE | KEYEVENTF_KEYUP)
        );
    }

    #[test]
    #[ignore = "interactive Windows desktop: run in the user's own session"]
    fn a_screenshot_is_a_jpeg_of_the_monitor_under_the_pointer() {
        per_monitor_aware();
        let capture = capture().unwrap();
        let frame = monitor_at(pointer_location().unwrap()).unwrap();
        let image = image::load_from_memory_with_format(&capture.data, image::ImageFormat::Jpeg).unwrap().to_rgb8();
        assert_eq!((image.width(), image.height()), (capture.geometry.image_width, capture.geometry.image_height));
        assert!(image.width().max(image.height()) <= MAX_LONG_EDGE);
        assert_eq!(capture.geometry.origin, Point { x: f64::from(frame.x), y: f64::from(frame.y) });
        let first = *image.get_pixel(0, 0);
        assert!(image.pixels().any(|p| *p != first), "a real desktop is not one flat color");
    }

    #[test]
    #[ignore = "interactive Windows desktop: run in the user's own session"]
    fn a_move_lands_on_the_pixel_asked_for_and_the_pointer_is_put_back() {
        per_monitor_aware();
        let start = pointer_location().unwrap();
        let frame = monitor_at(start).unwrap();
        let target = Point { x: f64::from(frame.x + frame.width / 3), y: f64::from(frame.y + frame.height / 3) };
        post(&InputEvent::Move(target)).unwrap();
        std::thread::sleep(Duration::from_millis(50));
        let landed = pointer_location().unwrap();
        post(&InputEvent::Move(start)).unwrap();
        assert!((landed.x - target.x).abs() <= 1.0 && (landed.y - target.y).abs() <= 1.0, "{landed:?} != {target:?}");
    }
}