VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/window.py

@@ -0,0 +1,869 @@
+"""Window mounting: move a target window onto the virtual display and hide its traces.
+
+What "mount" means concretely:
+
+1. The window is restored from ``SW_MINIMIZE``/``SW_MAXIMIZE`` to a normal state (a
+   maximized window would snap back to the old monitor the moment it is restored).
+2. Its extended style is rewritten from ``WS_EX_APPWINDOW`` to ``WS_EX_TOOLWINDOW``, which
+   is the only reliable way to remove a *taskbar button* and remove the window from
+   Alt+Tab. ``SetWindowPos(SWP_FRAMECHANGED)`` applies the frame change, plus an optional
+   hide/show cycle that makes the shell refresh its (sometimes cached) taskbar entry.
+3. The window is moved to the virtual monitor's rectangle.
+
+Every step is reversible: :meth:`WindowMounter.unmount` restores the exact original
+rectangle, styles and minimized state, and unmount is idempotent.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import time
+from ctypes import wintypes
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from ._winapi import (
+    GWL_EXSTYLE,
+    GWL_STYLE,
+    IS_WINDOWS,
+    WS_EX_APPWINDOW,
+    WS_EX_TOOLWINDOW,
+    MonitorInfo,
+    WindowRecord,
+    is_owned_window,
+    list_windows,
+    require_windows,
+    title_matches,
+)
+from .errors import AmbiguousWindowError, WindowMountError, WindowNotFoundError
+
+log = get_logger("window")
+
+__all__ = ["Selection", "WindowSnapshot", "WindowMounter", "find_window", "window_diagnostics"]
+
+if IS_WINDOWS:  # pragma: no branch
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+else:  # pragma: no cover
+    user32 = None
+
+SW_HIDE = 0
+SW_SHOWNORMAL = 1
+SW_SHOWNA = 8
+SWP_NOSIZE = 0x0001
+SWP_NOMOVE = 0x0002
+SWP_NOZORDER = 0x0004
+SWP_NOACTIVATE = 0x0010
+SWP_FRAMECHANGED = 0x0020
+HWND_TOP = 0
+HWND_NOTOPMOST = -2
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.MoveWindow.argtypes = [
+        wintypes.HWND,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        wintypes.BOOL,
+    ]
+    user32.MoveWindow.restype = wintypes.BOOL
+    user32.SetWindowPos.argtypes = [
+        wintypes.HWND,
+        wintypes.HWND,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_int,
+        wintypes.UINT,
+    ]
+    user32.SetWindowPos.restype = wintypes.BOOL
+    user32.SetWindowLongW.argtypes = [wintypes.HWND, ctypes.c_int, wintypes.LONG]
+    user32.SetWindowLongW.restype = wintypes.LONG
+    user32.GetWindowRect.argtypes = [wintypes.HWND, ctypes.c_void_p]
+    user32.GetWindowRect.restype = wintypes.BOOL
+    user32.GetClientRect.argtypes = [wintypes.HWND, ctypes.c_void_p]
+    user32.GetClientRect.restype = wintypes.BOOL
+    user32.IsWindow.argtypes = [wintypes.HWND]
+    user32.IsWindow.restype = wintypes.BOOL
+    user32.IsWindowVisible.argtypes = [wintypes.HWND]
+    user32.ShowWindow.argtypes = [wintypes.HWND, ctypes.c_int]
+    user32.ShowWindow.restype = wintypes.BOOL
+    user32.IsIconic.argtypes = [wintypes.HWND]
+    user32.IsIconic.restype = wintypes.BOOL
+    user32.IsZoomed.argtypes = [wintypes.HWND]
+    user32.IsZoomed.restype = wintypes.BOOL
+    user32.BringWindowToTop.argtypes = [wintypes.HWND]
+    user32.BringWindowToTop.restype = wintypes.BOOL
+    user32.SetForegroundWindow.argtypes = [wintypes.HWND]
+    user32.SetForegroundWindow.restype = wintypes.BOOL
+    user32.GetWindowLongW.argtypes = [wintypes.HWND, ctypes.c_int]
+    user32.GetWindowLongW.restype = wintypes.LONG
+
+
+class _RECT(ctypes.Structure):
+    _fields_ = [
+        ("left", wintypes.LONG),
+        ("top", wintypes.LONG),
+        ("right", wintypes.LONG),
+        ("bottom", wintypes.LONG),
+    ]
+
+
+class _POINT(ctypes.Structure):
+    _fields_ = [("x", wintypes.LONG), ("y", wintypes.LONG)]
+
+
+@dataclass
+class Selection:
+    """Criteria used to pick exactly one window."""
+
+    title: Optional[str] = None
+    class_name: Optional[str] = None
+    process_name: Optional[str] = None
+    pid: Optional[int] = None
+    title_mode: str = "auto"
+    match_case: bool = False
+    require_visible: bool = True
+    include_tool_windows: bool = False
+    include_owned: bool = True
+
+    def describe(self) -> str:
+        parts = []
+        if self.title:
+            parts.append(f"title~{self.title!r} ({self.title_mode})")
+        if self.class_name:
+            parts.append(f"class={self.class_name!r}")
+        if self.process_name:
+            parts.append(f"process={self.process_name!r}")
+        if self.pid:
+            parts.append(f"pid={self.pid}")
+        return ", ".join(parts) or "<no criteria>"
+
+
+def _matches(record: WindowRecord, selection: Selection) -> bool:
+    if selection.pid and record.pid != selection.pid:
+        return False
+    if selection.process_name:
+        wanted = selection.process_name if selection.match_case else selection.process_name.lower()
+        actual = record.process_name if selection.match_case else record.process_name.lower()
+        if wanted not in actual:
+            return False
+    if selection.class_name:
+        wanted = selection.class_name if selection.match_case else selection.class_name.lower()
+        actual = record.class_name if selection.match_case else record.class_name.lower()
+        if wanted != actual:
+            return False
+    if selection.title:
+        if selection.match_case:
+            return title_matches(record.title, selection.title, mode=selection.title_mode)
+        return title_matches(record.title.lower(), selection.title.lower(), mode=selection.title_mode)
+    return True
+
+
+def _candidates(selection: Selection) -> List[WindowRecord]:
+    records = list_windows()
+    found: List[WindowRecord] = []
+    for record in records:
+        if not record.title and not selection.class_name:
+            continue
+        if selection.require_visible and not record.visible:
+            continue
+        if not selection.include_tool_windows and record.tool_window:
+            continue
+        if not selection.include_owned and record.owner:
+            continue
+        if _matches(record, selection):
+            found.append(record)
+    return found
+
+
+def find_window(
+    *,
+    title: Optional[str] = None,
+    class_name: Optional[str] = None,
+    process_name: Optional[str] = None,
+    pid: Optional[int] = None,
+    title_mode: str = "auto",
+    match_case: bool = False,
+    require_visible: bool = True,
+    include_tool_windows: bool = False,
+    include_owned: bool = True,
+    timeout: float = 0.0,
+    interval: float = 0.5,
+    allow_multiple: bool = False,
+) -> WindowRecord:
+    """Locate exactly one window, waiting up to ``timeout`` seconds for it to appear."""
+    require_windows("find_window")
+    selection = Selection(
+        title=title,
+        class_name=class_name,
+        process_name=process_name,
+        pid=pid,
+        title_mode=title_mode,
+        match_case=match_case,
+        require_visible=require_visible,
+        include_tool_windows=include_tool_windows,
+        include_owned=include_owned,
+    )
+    deadline = time.monotonic() + max(timeout, 0.0)
+    while True:
+        found = _candidates(selection)
+        if len(found) == 1:
+            return found[0]
+        if len(found) > 1:
+            if allow_multiple:
+                return found[0]
+            raise AmbiguousWindowError(
+                f"{len(found)} windows match {selection.describe()}",
+                details={"candidates": [r.to_dict() for r in found[:20]]},
+                code="window-ambiguous",
+            )
+        if time.monotonic() >= deadline:
+            raise WindowNotFoundError(
+                f"no window matched {selection.describe()}",
+                details={"waited_seconds": timeout, "windows": _summaries()},
+                hint="Use VirtualDesktop.list_windows() to inspect candidates.",
+            )
+        time.sleep(interval)
+
+
+def _summaries(limit: int = 25) -> List[dict]:
+    try:
+        return [
+            {"title": r.title, "class": r.class_name, "process": r.process_name, "pid": r.pid}
+            for r in list_windows()
+            if r.title
+        ][:limit]
+    except Exception:  # pragma: no cover - diagnostics must never raise
+        return []
+
+
+@dataclass
+class WindowSnapshot:
+    """Everything needed to put a window back exactly as it was."""
+
+    hwnd: int
+    rect: Tuple[int, int, int, int]
+    style: int
+    ex_style: int
+    was_minimized: bool = False
+    was_maximized: bool = False
+    was_visible: bool = True
+    mounted: bool = False
+    #: True when the window was hidden by parking it outside every monitor.
+    offscreen: bool = False
+    mounted_at: float = 0.0
+    target_monitor: Optional[Tuple[int, int, int, int]] = None
+    toolwindow_applied: bool = False
+    hide_taskbar_trace: bool = False
+    #: Window rectangle observed right after the move (the app may have adjusted it).
+    mounted_rect: Optional[Tuple[int, int, int, int]] = None
+    #: DPI of the window when :attr:`rect` was captured (restores across DPI changes).
+    dpi: int = 96
+    #: Monitor rectangle the window lived on before mounting (for a DPI-safe restore).
+    origin_monitor: Optional[Tuple[int, int, int, int]] = None
+    #: Window offset inside :attr:`origin_monitor`, in that monitor's coordinate space.
+    origin_offset: Optional[Tuple[int, int]] = None
+    warnings: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "hwnd": self.hwnd,
+            "rect": list(self.rect),
+            "style": hex(self.style & 0xFFFFFFFF),
+            "ex_style": hex(self.ex_style & 0xFFFFFFFF),
+            "was_minimized": self.was_minimized,
+            "was_maximized": self.was_maximized,
+            "was_visible": self.was_visible,
+            "mounted": self.mounted,
+            "offscreen": self.offscreen,
+            "target_monitor": list(self.target_monitor) if self.target_monitor else None,
+            "toolwindow_applied": self.toolwindow_applied,
+            "mounted_rect": list(self.mounted_rect) if self.mounted_rect else None,
+            "warnings": list(self.warnings),
+        }
+
+
+def _get_rect(hwnd: int) -> Tuple[int, int, int, int]:
+    rect = _RECT()
+    if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
+        raise WindowMountError(
+            f"GetWindowRect(0x{hwnd:X}) failed with Win32 error {ctypes.get_last_error()}",
+            code="get-window-rect-failed",
+        )
+    return (int(rect.left), int(rect.top), int(rect.right), int(rect.bottom))
+
+
+def window_diagnostics(hwnd: int) -> dict:
+    """Snapshot a window's geometry/style for reports and bug reports."""
+    if not IS_WINDOWS:
+        return {}
+    if not user32.IsWindow(hwnd):
+        return {"hwnd": hwnd, "valid": False}
+    rect = _RECT()
+    client = _RECT()
+    user32.GetWindowRect(hwnd, ctypes.byref(rect))
+    user32.GetClientRect(hwnd, ctypes.byref(client))
+    return {
+        "hwnd": hwnd,
+        "valid": True,
+        "rect": [rect.left, rect.top, rect.right, rect.bottom],
+        "client": [client.left, client.top, client.right, client.bottom],
+        "style": hex(int(user32.GetWindowLongW(hwnd, GWL_STYLE)) & 0xFFFFFFFF),
+        "ex_style": hex(int(user32.GetWindowLongW(hwnd, GWL_EXSTYLE)) & 0xFFFFFFFF),
+        "visible": bool(user32.IsWindowVisible(hwnd)),
+        "minimized": bool(user32.IsIconic(hwnd)),
+        "maximized": bool(user32.IsZoomed(hwnd)),
+        "owned": is_owned_window(hwnd),
+    }
+
+
+
+
+def window_dpi(hwnd: int) -> int:
+    """Effective DPI of a window (96 = 100 %).
+
+    Delegates to the compatibility layer, which knows the per-build fallback chain
+    (``GetDpiForWindow`` on Win 10 1607+, then ``GetDpiForMonitor`` on Win 8.1+, then the
+    monitor DC's ``LOGPIXELSX``).  Returning 96 unconditionally on an older build would
+    silently mis-scale every restored rectangle.
+    """
+    if not IS_WINDOWS:  # pragma: no cover - Windows-only library
+        return 96
+    from ._compat import window_dpi_compat
+
+    return window_dpi_compat(hwnd)
+
+
+def scale_rect(rect, numerator: int, denominator: int):
+    """Scale a rectangle between DPI-aware coordinate spaces."""
+    if not numerator or not denominator or numerator == denominator:
+        return tuple(rect)
+    factor = numerator / denominator
+    return tuple(int(round(value * factor)) for value in rect)
+
+
+#: Hide by parking the window *outside* every monitor, in the desktop's own coordinate space.
+#: ``PrintWindow`` paints the window into a caller-supplied DC regardless of where the window
+#: sits (or whether it is covered), so an off-screen window is still fully capturable — this is
+#: the technique used by production WeChat automation and validated by
+#: :func:`tools/offscreen_probe.py`.
+OFFSCREEN_MARGIN = 200
+
+#: How far outside the desktop to try before giving up (some apps/appcompat shims clamp the
+#: position back into the monitor; the probe measured that a plain ``SetWindowPos`` does not).
+OFFSCREEN_PROBES = (-200, -2000, -10000, -30000)
+
+#: Hide mode names, ordered by preference: the virtual display first, off-screen as
+#: fallback, plus ``auto`` which tries them in that order and reports what it used.
+HIDE_MODES = ("virtual_screen", "offscreen", "auto")
+
+
+def virtual_desktop_rect() -> Tuple[int, int, int, int]:
+    """Bounding rectangle of the whole desktop, including negative-coordinate monitors.
+
+    Delegates to :func:`VirtualDesktop._winapi.virtual_screen_rect`, which prefers the union of
+    the enumerated monitors and only falls back to ``GetSystemMetrics`` when enumeration is
+    empty.  That matters on Windows 10/11: the two accessors disagree by the monitor scale
+    factor for a DPI-unaware caller, and this rectangle is used both to test "is the window off
+    screen?" and to crop desktop captures.
+    """
+    if not IS_WINDOWS:  # pragma: no cover - Windows-only library
+        return (0, 0, 0, 0)
+    from ._winapi import virtual_screen_rect
+
+    return virtual_screen_rect()
+
+
+def rect_on_screen(rect, *, desktop: Optional[Tuple[int, int, int, int]] = None, tolerance: int = 0) -> bool:
+    """True when any part of ``rect`` overlaps the desktop (i.e. the user could see it).
+
+    The *desktop* includes virtual monitors, so a window mounted on a virtual display is
+    ``on_screen=True`` here.  Use :func:`rect_on_physical_screen` for the stronger claim "the
+    user cannot see it at all".
+    """
+    if rect is None:
+        return False
+    left, top, right, bottom = desktop or virtual_desktop_rect()
+    return not (
+        rect[2] <= left + tolerance
+        or rect[0] >= right - tolerance
+        or rect[3] <= top + tolerance
+        or rect[1] >= bottom - tolerance
+    )
+
+
+def rect_on_physical_screen(rect, tolerance: int = 0) -> bool:
+    """True when ``rect`` overlaps a monitor the user is actually looking at.
+
+    Virtual (IddCx) monitors are excluded, which is what makes "mounted on the virtual display"
+    a genuinely hidden state instead of a technically-on-desktop one.
+    """
+    if rect is None:
+        return False
+    from ._winapi import enumerate_monitors
+
+    for monitor in enumerate_monitors():
+        if monitor.is_decidedly_virtual():
+            continue
+        left, top, right, bottom = monitor.monitor
+        if not (
+            rect[2] <= left + tolerance
+            or rect[0] >= right - tolerance
+            or rect[3] <= top + tolerance
+            or rect[1] >= bottom - tolerance
+        ):
+            return True
+    return False
+
+
+def offscreen_target(hwnd: int, *, margin: int = OFFSCREEN_MARGIN) -> Tuple[int, int]:
+    desktop = virtual_desktop_rect()
+    # Negative space is unbounded in practice; place the window entirely left of and above the
+    # desktop so the taskbar, Alt+Tab preview and screenshot tools cannot show it.
+    return (desktop[0] - margin, desktop[1] - margin)
+
+
+def rects_equivalent(
+    observed,
+    original,
+    *,
+    original_dpi: int = 96,
+    observed_dpi: Optional[int] = None,
+    tolerance: int = 2,
+) -> bool:
+    """Compare two window rectangles, accounting for a DPI change between them.
+
+    A window moved between monitors with different scaling factors legitimately reports
+    different pixel dimensions: 583 px at 120 DPI is 466 px at 96 DPI.  Treating that as a
+    failed restore is wrong, so the expected physical size is scaled before comparing, and only
+    the origin must match exactly.
+    """
+    if observed is None or original is None:
+        return False
+    # Pixel-identical rectangles are always a valid restore, whatever DPI is reported now.
+    if tuple(observed) == tuple(original):
+        return True
+    current = observed_dpi if observed_dpi is not None else original_dpi
+    factor = (current / original_dpi) if original_dpi else 1.0
+    expected_width = (original[2] - original[0]) * factor
+    expected_height = (original[3] - original[1]) * factor
+    size_tolerance = max(tolerance, int(round(max(expected_width, expected_height) * 0.02)))
+    return (
+        abs(observed[0] - original[0]) <= tolerance
+        and abs(observed[1] - original[1]) <= tolerance
+        and abs((observed[2] - observed[0]) - expected_width) <= size_tolerance
+        and abs((observed[3] - observed[1]) - expected_height) <= size_tolerance
+    )
+
+
+class WindowMounter:
+    """Moves windows onto a monitor and restores them afterwards."""
+
+    def __init__(
+        self,
+        *,
+        hide_taskbar_trace: bool = True,
+        activate_on_mount: bool = False,
+        taskbar_refresh: bool = True,
+        keep_size: bool = False,
+    ) -> None:
+        self.hide_taskbar_trace = hide_taskbar_trace
+        self.activate_on_mount = activate_on_mount
+        self.taskbar_refresh = taskbar_refresh
+        #: Default for :meth:`mount`: move without resizing (safer for custom-rendered apps).
+        self.keep_size = keep_size
+        self._snapshots: Dict[int, WindowSnapshot] = {}
+
+    # -- state ----------------------------------------------------------------------
+    @property
+    def mounted_windows(self) -> List[int]:
+        return [hwnd for hwnd, snap in self._snapshots.items() if snap.mounted]
+
+    def snapshot(self, hwnd: int) -> WindowSnapshot:
+        if hwnd in self._snapshots and self._snapshots[hwnd].mounted:
+            return self._snapshots[hwnd]
+        require_windows("WindowMounter")
+        if not user32.IsWindow(hwnd):
+            raise WindowMountError(f"0x{hwnd:X} is not a window", code="invalid-hwnd")
+        snap = WindowSnapshot(
+            hwnd=hwnd,
+            rect=_get_rect(hwnd),
+            dpi=window_dpi(hwnd),
+            style=int(user32.GetWindowLongW(hwnd, GWL_STYLE)) & 0xFFFFFFFF,
+            ex_style=int(user32.GetWindowLongW(hwnd, GWL_EXSTYLE)) & 0xFFFFFFFF,
+            was_minimized=bool(user32.IsIconic(hwnd)),
+            was_maximized=bool(user32.IsZoomed(hwnd)),
+            was_visible=bool(user32.IsWindowVisible(hwnd)),
+        )
+        self._snapshots[hwnd] = snap
+        return snap
+
+    # -- mount ----------------------------------------------------------------------
+    def mount(
+        self,
+        hwnd: int,
+        monitor: MonitorInfo,
+        *,
+        padding: int = 0,
+        verify: bool = True,
+        placement_timeout: float = 3.0,
+        keep_size: Optional[bool] = None,
+    ) -> WindowSnapshot:
+        """Move ``hwnd`` onto ``monitor`` and hide its taskbar/Alt+Tab traces.
+
+        ``keep_size=True`` moves the window **without resizing it**, which is what
+        production WeChat automation does.  It matters for custom-rendered apps: WeChat's
+        login window ignores a resize request and snaps to the *physical* panel's size
+        (measured: asked for 1920x1080 on the virtual display, ended up 1536x864 = the
+        physical panel), after which a captured frame no longer matches the window.  The
+        geometry actually achieved is always recorded on the snapshot, so a mismatch is
+        visible to the caller instead of silently accepted.
+        """
+        require_windows("WindowMounter.mount")
+        if not user32.IsWindow(hwnd):
+            raise WindowMountError(
+                f"cannot mount 0x{hwnd:X}: the window no longer exists", code="invalid-hwnd"
+            )
+        snap = self.snapshot(hwnd)
+        keep_size = self.keep_size if keep_size is None else keep_size
+        left, top, right, bottom = monitor.monitor
+        if keep_size:
+            width = snap.rect[2] - snap.rect[0]
+            height = snap.rect[3] - snap.rect[1]
+        else:
+            width = (right - left) - 2 * padding
+            height = (bottom - top) - 2 * padding
+        if width <= 0 or height <= 0:  # pragma: no cover - defensive
+            raise WindowMountError(
+                f"virtual monitor {monitor.device} has a degenerate size {monitor.monitor}",
+                code="degenerate-monitor",
+            )
+
+        # (1) leave minimized / maximized state behind
+        if snap.was_minimized:
+            self._show(hwnd, SW_SHOWNORMAL)
+            time.sleep(0.1)
+        if snap.was_maximized:
+            self._show(hwnd, SW_SHOWNORMAL)
+            time.sleep(0.1)
+
+        # (2) hide taskbar / Alt+Tab traces
+        if self.hide_taskbar_trace:
+            self._apply_toolwindow(snap)
+
+        # (3) move it
+        if not user32.MoveWindow(hwnd, left + padding, top + padding, width, height, True):
+            error = ctypes.get_last_error()
+            raise WindowMountError(
+                f"MoveWindow(0x{hwnd:X}) to {monitor.device} failed with Win32 error {error}",
+                code="move-window-failed",
+                details={"win32_error": error, "target": list(monitor.monitor)},
+                hint="Windows of a *more privileged* process cannot be moved (UIPI).",
+            )
+        user32.SetWindowPos(
+            hwnd,
+            HWND_TOP if self.activate_on_mount else 0,
+            0,
+            0,
+            0,
+            0,
+            SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE | SWP_FRAMECHANGED,
+        )
+        if self.activate_on_mount:
+            user32.BringWindowToTop(hwnd)
+
+        snap.mounted = True
+        snap.mounted_at = time.time()
+        snap.target_monitor = tuple(monitor.monitor)
+        snap.mounted_rect = _get_rect(hwnd)
+        # Remember where the window started *inside* the monitor it lived on.  Restoring by
+        # absolute screen coordinates is not DPI-safe: when the window is moved back, Windows
+        # re-applies the 125 % layout and the origin drifts (measured: (14,64) instead of
+        # (18,80)).  Storing the monitor-local offset lets the restore path add it back in the
+        # coordinate space that is valid at that moment.
+        if snap.origin_monitor is None:
+            snap.origin_monitor = tuple(monitor.monitor)
+            snap.origin_offset = (
+                snap.rect[0] - monitor.monitor[0],
+                snap.rect[1] - monitor.monitor[1],
+            )
+        if verify and not self.wait_until_placed(hwnd, timeout=placement_timeout):
+            actual = _get_rect(hwnd)
+            snap.warnings.append(f"window did not settle on {monitor.device}: rect={actual}")
+            log.warning(
+                "window 0x%X is at %s, expected inside %s",
+                hwnd,
+                actual,
+                monitor.monitor,
+            )
+        log.info(
+            "mounted 0x%X on %s (%dx%d+%d+%d)",
+            hwnd,
+            monitor.device,
+            width,
+            height,
+            left,
+            top,
+        )
+        return snap
+
+    # -- off-screen parking (fallback hide mode) -------------------------------------
+    def mount_offscreen(
+        self,
+        hwnd: int,
+        *,
+        margin: int = OFFSCREEN_MARGIN,
+        verify: bool = True,
+        placement_timeout: float = 2.0,
+    ) -> WindowSnapshot:
+        """Park ``hwnd`` fully outside every monitor instead of moving it to a display.
+
+        Use when no virtual display is available: the window is kept alive (never minimized,
+        so ``PrintWindow`` keeps working) while being invisible to the user — no taskbar entry,
+        no Alt+Tab preview, and nothing on screen.  Position is verified against the whole
+        desktop rectangle, and progressively larger offsets are tried because some
+        applications clamp a move back into the work area.
+        """
+        require_windows("WindowMounter.mount_offscreen")
+        if not user32.IsWindow(hwnd):
+            raise WindowMountError(
+                f"cannot park 0x{hwnd:X}: the window no longer exists", code="invalid-hwnd"
+            )
+        snap = self.snapshot(hwnd)
+        width = snap.rect[2] - snap.rect[0]
+        height = snap.rect[3] - snap.rect[1]
+        if width <= 0 or height <= 0:  # pragma: no cover - defensive
+            raise WindowMountError(
+                f"window 0x{hwnd:X} has a degenerate size {width}x{height}",
+                code="degenerate-window",
+            )
+
+        # A minimized window cannot be captured, so leave the minimized state first.
+        if snap.was_minimized:
+            self._show(hwnd, SW_SHOWNORMAL)
+            time.sleep(0.1)
+        if snap.was_maximized:
+            self._show(hwnd, SW_SHOWNORMAL)
+            time.sleep(0.1)
+
+        if self.hide_taskbar_trace:
+            self._apply_toolwindow(snap)
+
+        desktop = virtual_desktop_rect()
+        x, y = offscreen_target(hwnd, margin=margin)
+        placed = False
+        for attempt in range(4):
+            if not user32.SetWindowPos(hwnd, 0, x, y, width, height, SWP_NOZORDER | SWP_NOACTIVATE):
+                log.debug("SetWindowPos failed while parking 0x%X: %s", hwnd, ctypes.get_last_error())
+            time.sleep(0.08)
+            rect = _get_rect(hwnd)
+            if not rect_on_screen(rect, desktop=desktop):
+                placed = True
+                break
+            # The app clamped the move: push it further out and try again.
+            x, y = offscreen_target(hwnd, margin=abs(x - desktop[0]) * 5 or margin * 5)
+            log.debug("parking attempt %d: observed %s still on screen, retrying at (%d,%d)", attempt + 1, rect, x, y)
+
+        snap.mounted = True
+        snap.mounted_at = time.time()
+        snap.mounted_rect = _get_rect(hwnd)
+        snap.offscreen = True
+        snap.target_monitor = None
+        if snap.origin_monitor is None:
+            # Remember enough to restore exactly, in a DPI-safe way.
+            snap.origin_monitor = desktop
+            snap.origin_offset = (snap.rect[0] - desktop[0], snap.rect[1] - desktop[1])
+        if not placed:
+            snap.warnings.append(
+                f"the window still overlaps the desktop after parking: rect={snap.mounted_rect}"
+            )
+            log.warning(
+                "window 0x%X could not be parked off-screen (rect=%s)", hwnd, snap.mounted_rect
+            )
+        elif verify:
+            deadline = time.monotonic() + placement_timeout
+            while time.monotonic() < deadline:
+                if not rect_on_screen(_get_rect(hwnd), desktop=desktop):
+                    break
+                time.sleep(0.1)
+        log.info("parked 0x%X off-screen at (%d,%d) size %dx%d", hwnd, x, y, width, height)
+        return snap
+
+    def _show(self, hwnd: int, command: int) -> None:
+        user32.ShowWindow(hwnd, command)
+        user32.SetWindowPos(
+            hwnd, 0, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE
+        )
+
+    def _apply_toolwindow(self, snap: WindowSnapshot) -> None:
+        hwnd = snap.hwnd
+        desired = (snap.ex_style & ~WS_EX_APPWINDOW) | WS_EX_TOOLWINDOW
+        if desired == snap.ex_style:
+            snap.toolwindow_applied = True
+            return
+        if self._set_ex_style(hwnd, desired):
+            snap.toolwindow_applied = True
+            user32.SetWindowPos(
+                hwnd, 0, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED
+            )
+            if self.taskbar_refresh:
+                # The shell caches taskbar entries; a hidden->visible cycle forces a refresh.
+                user32.ShowWindow(hwnd, SW_HIDE)
+                user32.ShowWindow(hwnd, SW_SHOWNA)
+                snap.hide_taskbar_trace = True
+        else:
+            error = ctypes.get_last_error()
+            snap.warnings.append(
+                f"SetWindowLong(GWL_EXSTYLE) failed with Win32 error {error}; the window "
+                "may keep its taskbar button"
+            )
+            log.warning(
+                "could not convert 0x%X to a tool window (Win32 error %s); continuing",
+                hwnd,
+                error,
+            )
+
+    @staticmethod
+    def _set_ex_style(hwnd: int, value: int) -> bool:
+        ctypes.set_last_error(0)
+        previous = user32.SetWindowLongW(hwnd, GWL_EXSTYLE, ctypes.c_long(value))
+        error = ctypes.get_last_error()
+        return bool(previous) or error == 0
+
+    def wait_until_placed(self, hwnd: int, *, timeout: float = 3.0, tolerance: int = 2) -> bool:
+        """Wait until the window rect sits inside the requested monitor rect.
+
+        Size is not compared: with ``keep_size=True`` the window deliberately keeps its own
+        size, so the only requirement is that its **origin** lands on the target monitor and
+        that at least part of it stays inside.  Comparing the width here produced a misleading
+        "window did not settle" warning for a perfectly placed window.
+        """
+        snap = self._snapshots.get(hwnd)
+        target = snap.target_monitor if snap else None
+        if not target:
+            return True
+        deadline = time.monotonic() + timeout
+        while True:
+            rect = _get_rect(hwnd)
+            inside_x = target[0] - tolerance <= rect[0] <= target[2] + tolerance
+            inside_y = target[1] - tolerance <= rect[1] <= target[3] + tolerance
+            if inside_x and inside_y:
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.1)
+
+    # -- unmount --------------------------------------------------------------------
+    def unmount(self, hwnd: Optional[int] = None) -> List[WindowSnapshot]:
+        """Restore one window (or all mounted windows). Idempotent and never raises."""
+        results: List[WindowSnapshot] = []
+        targets = [hwnd] if hwnd else list(self._snapshots)
+        for target in targets:
+            snap = self._snapshots.get(target)
+            if snap is None:
+                continue
+            results.append(self._restore(snap))
+        if hwnd is None:
+            for snap in results:
+                self._snapshots.pop(snap.hwnd, None)
+        return results
+
+    def _restore(self, snap: WindowSnapshot) -> WindowSnapshot:
+        hwnd = snap.hwnd
+        if not snap.mounted:
+            return snap
+        if not user32.IsWindow(hwnd):
+            log.warning("window 0x%X disappeared before it could be restored", hwnd)
+            snap.mounted = False
+            snap.warnings.append("window no longer exists")
+            return snap
+
+        # Restore the extended style first so the taskbar entry comes back before the move.
+        if snap.toolwindow_applied:
+            if not self._set_ex_style(hwnd, snap.ex_style):
+                snap.warnings.append(
+                    f"could not restore the original extended style (Win32 error {ctypes.get_last_error()})"
+                )
+            user32.SetWindowPos(
+                hwnd, 0, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED
+            )
+
+        # Restoring the exact original geometry is DPI-sensitive, and the conversions involved
+        # are not symmetric: the same window reports DPI 120 on one monitor and 96 on the other,
+        # and *both* the rectangle and the coordinates passed to SetWindowPos are interpreted in
+        # whichever space is current (measured: a naive restore of 583 px produced 747 px, then
+        # 934 px / 598 px with one-directional corrections).  Rather than guess the semantics,
+        # the restore is closed-loop: move, measure, and correct the size by the observed error
+        # ratio until the rectangle matches the original (or three attempts have been made).
+        current_dpi = window_dpi(hwnd)
+        original_dpi = snap.dpi or current_dpi
+        original_width = max(snap.rect[2] - snap.rect[0], 1)
+        original_height = max(snap.rect[3] - snap.rect[1], 1)
+        if snap.origin_monitor and snap.origin_offset:
+            left = snap.origin_monitor[0] + snap.origin_offset[0]
+            top = snap.origin_monitor[1] + snap.origin_offset[1]
+        else:  # pragma: no cover - mount always records the origin monitor
+            left, top = snap.rect[0], snap.rect[1]
+        width = int(round(original_width * original_dpi / current_dpi))
+        height = int(round(original_height * original_dpi / current_dpi))
+        flags = SWP_NOZORDER | SWP_NOACTIVATE
+
+        for attempt in range(3):
+            ok = user32.SetWindowPos(hwnd, 0, left, top, width, height, flags)
+            if not ok:
+                ok = bool(user32.MoveWindow(hwnd, left, top, width, height, True))
+            if not ok:
+                snap.warnings.append(
+                    f"could not move the window back to {snap.rect} "
+                    f"(Win32 error {ctypes.get_last_error()})"
+                )
+                log.warning("failed to restore 0x%X to %s", hwnd, snap.rect)
+                break
+            time.sleep(0.08)
+            observed = _get_rect(hwnd)
+            observed_width = max(observed[2] - observed[0], 1)
+            observed_height = max(observed[3] - observed[1], 1)
+            width_ok = abs(observed_width - original_width) <= max(2, original_width * 0.01)
+            height_ok = abs(observed_height - original_height) <= max(2, original_height * 0.01)
+            position_ok = abs(observed[0] - left) <= 2 and abs(observed[1] - top) <= 2
+            if width_ok and height_ok and position_ok:
+                break
+            # Correct both the size and the position from the measured error.
+            width = max(int(round(width * original_width / observed_width)), 1)
+            height = max(int(round(height * original_height / observed_height)), 1)
+            left += snap.rect[0] - observed[0] if not snap.origin_monitor else left - observed[0]
+            top += snap.rect[1] - observed[1] if not snap.origin_monitor else top - observed[1]
+            log.debug(
+                "restore attempt %d: observed %s, retrying with %dx%d at (%d,%d)",
+                attempt + 1, observed, width, height, left, top,
+            )
+        else:
+            snap.warnings.append(
+                f"window geometry after restore ({observed}) differs from the original "
+                f"{snap.rect}; the app enforces its own size"
+            )
+
+        if snap.was_maximized:
+            self._show(hwnd, 3)  # SW_MAXIMIZE
+        elif snap.was_minimized:
+            self._show(hwnd, 6)  # SW_MINIMIZE
+        elif snap.was_visible:
+            self._show(hwnd, SW_SHOWNA)
+        else:
+            self._show(hwnd, SW_HIDE)
+
+        snap.mounted = False
+        log.info("restored 0x%X to %s", hwnd, snap.rect)
+        return snap
+
+    def restore_styles_only(self, hwnd: int) -> bool:
+        """Undo the taskbar hiding without moving the window (used by ``unmount_window``)."""
+        snap = self._snapshots.get(hwnd)
+        if snap is None or not snap.toolwindow_applied:
+            return False
+        ok = self._set_ex_style(hwnd, snap.ex_style)
+        user32.SetWindowPos(hwnd, 0, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED)
+        snap.toolwindow_applied = not ok
+        return ok