VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/_winapi.py

@@ -0,0 +1,714 @@
+"""Thin, defensive ctypes bridge to the Win32 APIs this library needs.
+
+Design rules:
+
+* Every handle opened here is closed deterministically (context managers / try-finally).
+* ``ctypes`` calls are checked for failure, and ``GetLastError`` is captured immediately.
+* Optional APIs (per-monitor DPI, ``WM_DPICHANGED`` era functions) are probed at runtime so
+  the library keeps working on older Windows builds.
+* Pure helpers (title matching, monitor selection) are kept free of Win32 calls so they can
+  be unit tested on any platform.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import re
+import sys
+from ctypes import wintypes
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ._log import get_logger
+from .errors import UnsupportedPlatformError
+
+log = get_logger("winapi")
+
+__all__ = [
+    "IS_WINDOWS",
+    "require_windows",
+    "is_admin",
+    "is_process_elevated",
+    "is_system_session",
+    "dpi_awareness_scope",
+    "MonitorInfo",
+    "enumerate_monitors",
+    "virtual_screen_rect",
+    "system_metrics_rect",
+    "display_device_map",
+    "select_virtual_monitor",
+    "title_matches",
+    "WindowRecord",
+    "list_windows",
+    "format_hresult",
+    "is_owned_window",
+    "find_hwnd_by_title",
+    "GWL_STYLE",
+    "GWL_EXSTYLE",
+    "WS_EX_APPWINDOW",
+    "WS_EX_TOOLWINDOW",
+]
+
+IS_WINDOWS = sys.platform == "win32"
+
+# --------------------------------------------------------------------------------------
+# user32 / kernel32 load
+# --------------------------------------------------------------------------------------
+
+if IS_WINDOWS:  # pragma: no branch - platform gate
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    shell32 = ctypes.WinDLL("shell32", use_last_error=True)
+    advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
+    try:  # pragma: no cover - shcore exists on Win8.1+
+        shcore = ctypes.WinDLL("shcore", use_last_error=True)
+    except OSError:  # pragma: no cover
+        shcore = None
+    try:
+        gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+    except OSError:  # pragma: no cover
+        gdi32 = None
+else:  # pragma: no cover - non-Windows import path
+    user32 = kernel32 = shell32 = advapi32 = shcore = gdi32 = None
+
+
+def require_windows(what: str = "this operation") -> None:
+    """Raise :class:`UnsupportedPlatformError` when not running on Windows."""
+    if not IS_WINDOWS:
+        raise UnsupportedPlatformError(
+            f"{what} requires Windows; current platform is {sys.platform!r}."
+        )
+
+
+def format_hresult(value: int) -> str:
+    """Render an HRESULT/NTSTATUS the way Windows documents it (``0x80070005``)."""
+    try:
+        return f"0x{value & 0xFFFFFFFF:08X}"
+    except TypeError:  # pragma: no cover - defensive
+        return repr(value)
+
+
+# --------------------------------------------------------------------------------------
+# Privilege / session state
+# --------------------------------------------------------------------------------------
+
+
+class _TokenElevation(ctypes.Structure):
+    _fields_ = [("TokenIsElevated", wintypes.DWORD)]
+
+
+def is_process_elevated() -> bool:
+    """True when the current process token is elevated (UAC-aware)."""
+    if not IS_WINDOWS:
+        return False
+    TOKEN_QUERY = 0x0008
+    TokenElevation = 20
+    token = wintypes.HANDLE()
+    if not advapi32.OpenProcessToken(
+        kernel32.GetCurrentProcess(), TOKEN_QUERY, ctypes.byref(token)
+    ):
+        return False
+    try:
+        info = _TokenElevation()
+        returned = wintypes.DWORD()
+        ok = advapi32.GetTokenInformation(
+            token,
+            TokenElevation,
+            ctypes.byref(info),
+            ctypes.sizeof(info),
+            ctypes.byref(returned),
+        )
+        return bool(ok and info.TokenIsElevated)
+    finally:
+        kernel32.CloseHandle(token)
+
+
+def is_admin() -> bool:
+    """Alias kept for readability at call sites (checks elevation, not group membership)."""
+    return is_process_elevated()
+
+
+def is_system_session() -> bool:
+    """True when the process runs in a non-interactive session (service / task scheduler)."""
+    if not IS_WINDOWS:
+        return False
+    return (os.environ.get("SESSIONNAME") or "").upper().startswith("SERVICES")
+
+
+# --------------------------------------------------------------------------------------
+# DPI awareness
+# --------------------------------------------------------------------------------------
+
+_DPI_AWARENESS_NAMES = {
+    -1: "unaware",
+    0: "system-aware",
+    1: "per-monitor-aware",
+    2: "per-monitor-v2",
+    3: "unaware-gdi-scaled",
+}
+
+
+def _current_dpi_awareness() -> Optional[int]:
+    if not IS_WINDOWS or shcore is None:
+        return None
+    try:
+        value = ctypes.c_int()
+        if shcore.GetProcessDpiAwareness(None, ctypes.byref(value)) == 0:
+            return int(value.value)
+    except Exception:  # pragma: no cover - defensive
+        return None
+    return None
+
+
+class dpi_awareness_scope:  # noqa: N801 - context-manager style name
+    """Process-wide DPI awareness, restored on exit when it can be.
+
+    ``PrintWindow`` and ``BitBlt`` return unscaled pixels only when the process is DPI
+    aware.  Failing to set this is the single most common cause of "my screenshot is
+    125 % too small / offset".
+    """
+
+    def __init__(self, awareness: str = "per_monitor_v2", *, restore: bool = True) -> None:
+        self.requested = awareness
+        self.restore = restore
+        self.previous: Optional[int] = None
+        self.applied: Optional[int] = None
+
+    def _apply(self) -> Optional[int]:
+        if not IS_WINDOWS:
+            return None
+        # Every candidate API is tried by the compatibility layer, which also handles the
+        # build-specific failure mode: on Windows 8.1 ``shcore`` exists but answers
+        # E_ACCESSDENIED once the process awareness has already been set, so an exception-free
+        # HRESULT check is required, not just an AttributeError guard.
+        from ._compat import set_process_dpi_awareness
+
+        requested = self.requested.lower()
+        context = -4 if requested in ("per_monitor_v2", "per-monitor-v2", "pmv2") else -3
+        outcome = set_process_dpi_awareness(context)
+        applied = outcome.get("applied")
+        if applied is None:
+            log.debug("could not set DPI awareness: %s", outcome.get("attempts"))
+            return None
+        return 2 if applied in (-3, -4) else 0
+
+    def __enter__(self) -> "dpi_awareness_scope":
+        self.previous = _current_dpi_awareness()
+        if self.previous is not None and self.previous >= 2:
+            self.applied = self.previous
+            return self
+        if IS_WINDOWS:
+            self.applied = self._apply()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if not self.restore or self.previous is None or self.applied is None:
+            return
+        if self.applied == self.previous:
+            return
+        if shcore is None:
+            return
+        try:
+            shcore.SetProcessDpiAwareness(self.previous)
+        except Exception:  # pragma: no cover - best effort
+            log.debug("could not restore DPI awareness to %s", self.previous)
+
+
+# --------------------------------------------------------------------------------------
+# Monitors
+# --------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MonitorInfo:
+    """One display as seen by ``EnumDisplayMonitors``."""
+
+    handle: int
+    device: str
+    monitor: Tuple[int, int, int, int]
+    work: Tuple[int, int, int, int]
+    primary: bool
+    #: PNP device instance id of the adapter driving this monitor, when resolvable.
+    pnp_device_id: str = ""
+    #: Friendly adapter description (``\\.\DISPLAY2`` -> "MttVDD").
+    device_string: str = ""
+
+    @property
+    def width(self) -> int:
+        return self.monitor[2] - self.monitor[0]
+
+    @property
+    def height(self) -> int:
+        return self.monitor[3] - self.monitor[1]
+
+    @property
+    def index(self) -> int:
+        match = re.search(r"DISPLAY(\d+)", self.device or "", re.IGNORECASE)
+        return int(match.group(1)) - 1 if match else -1
+
+    def is_decidedly_virtual(
+        self, markers: Sequence[str] = ("MttVDD", "IDD", "Virtual", "MTT")
+    ) -> bool:
+        """True when this monitor comes from a virtual/indirect display driver.
+
+        Two independent signals are checked because Windows reports them inconsistently: the
+        adapter/monitor description (``"Virtual Display Driver"``) and the device instance id
+        (``MONITOR\\MTT1337...``, ``ROOT\\MTTVDD``).  Measured on this machine: an IddCx
+        display can surface as ``\\\\.\\DISPLAY1`` on the *Intel* adapter with the VDD's EDID as
+        its monitor id, so neither signal alone is sufficient.
+        """
+        haystack = f"{self.pnp_device_id} {self.device_string} {self.device}".upper()
+        return any(marker.upper() in haystack for marker in markers)
+
+    def to_dict(self) -> dict:
+        return {
+            "device": self.device,
+            "monitor": list(self.monitor),
+            "work": list(self.work),
+            "primary": self.primary,
+            "width": self.width,
+            "height": self.height,
+            "pnp_device_id": self.pnp_device_id,
+            "device_string": self.device_string,
+        }
+
+
+class _RECT(ctypes.Structure):
+    _fields_ = [
+        ("left", wintypes.LONG),
+        ("top", wintypes.LONG),
+        ("right", wintypes.LONG),
+        ("bottom", wintypes.LONG),
+    ]
+
+
+class _MONITORINFOEXW(ctypes.Structure):
+    _fields_ = [
+        ("cbSize", wintypes.DWORD),
+        ("rcMonitor", _RECT),
+        ("rcWork", _RECT),
+        ("dwFlags", wintypes.DWORD),
+        ("szDevice", ctypes.c_wchar * 32),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    _MONITORENUMPROC = ctypes.WINFUNCTYPE(
+        wintypes.BOOL,
+        wintypes.HMONITOR,
+        wintypes.HDC,
+        ctypes.POINTER(_RECT),
+        wintypes.LPARAM,
+    )
+    user32.GetMonitorInfoW.argtypes = [wintypes.HMONITOR, ctypes.POINTER(_MONITORINFOEXW)]
+    user32.GetMonitorInfoW.restype = wintypes.BOOL
+
+
+class _DISPLAY_DEVICEW(ctypes.Structure):
+    _fields_ = [
+        ("cb", wintypes.DWORD),
+        ("DeviceName", ctypes.c_wchar * 32),
+        ("DeviceString", ctypes.c_wchar * 128),
+        ("StateFlags", wintypes.DWORD),
+        ("DeviceID", ctypes.c_wchar * 128),
+        ("DeviceKey", ctypes.c_wchar * 128),
+    ]
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.EnumDisplayDevicesW.argtypes = [
+        ctypes.c_wchar_p,
+        wintypes.DWORD,
+        ctypes.POINTER(_DISPLAY_DEVICEW),
+        wintypes.DWORD,
+    ]
+    user32.EnumDisplayDevicesW.restype = wintypes.BOOL
+
+
+def virtual_screen_rect() -> Tuple[int, int, int, int]:
+    """Canonical desktop rectangle, in the caller's DPI coordinate space.
+
+    ``GetSystemMetrics(SM_*VIRTUALSCREEN)`` and ``EnumDisplayMonitors`` are both DPI-virtualised
+    for an unaware caller, but they are *not* guaranteed to agree: measured on Windows 11 at
+    125 % scale, an unaware process reports ``1536x864`` from **both**, a per-monitor-aware one
+    ``1920x1080`` from **both** — while mixed states (awareness set after one of the two was
+    already queried, or a monitor added between the calls) can leave them one scale factor
+    apart.  A crop computed from one against a shot taken from the other is then silently
+    offset or undersized.
+
+    Preference order:
+
+    1. the union of ``EnumDisplayMonitors`` rectangles — self-consistent with every other
+       monitor measurement in this library, and correct with negative-coordinate layouts;
+    2. ``GetSystemMetrics`` — only when no window station is available (a session-0 service, or
+       a non-interactive agent) so that enumeration returns nothing.
+    """
+    if not IS_WINDOWS:  # pragma: no cover - Windows-only library
+        return (0, 0, 0, 0)
+    monitors = enumerate_monitors()
+    if monitors:
+        return (
+            min(m.monitor[0] for m in monitors),
+            min(m.monitor[1] for m in monitors),
+            max(m.monitor[2] for m in monitors),
+            max(m.monitor[3] for m in monitors),
+        )
+    return system_metrics_rect()
+
+
+def system_metrics_rect() -> Tuple[int, int, int, int]:
+    """``GetSystemMetrics`` desktop rectangle — the fallback used when enumeration is empty."""
+    SM_XVIRTUALSCREEN, SM_YVIRTUALSCREEN, SM_CXVIRTUALSCREEN, SM_CYVIRTUALSCREEN = 76, 77, 78, 79
+    if not IS_WINDOWS:  # pragma: no cover - Windows-only library
+        return (0, 0, 0, 0)
+    user32.GetSystemMetrics.argtypes = [ctypes.c_int]
+    user32.GetSystemMetrics.restype = ctypes.c_int
+    return (
+        user32.GetSystemMetrics(SM_XVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_YVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_XVIRTUALSCREEN) + user32.GetSystemMetrics(SM_CXVIRTUALSCREEN),
+        user32.GetSystemMetrics(SM_YVIRTUALSCREEN) + user32.GetSystemMetrics(SM_CYVIRTUALSCREEN),
+    )
+
+
+def display_device_map() -> Dict[str, Dict[str, str]]:
+    """Map ``\\\\.\\DISPLAYn`` to the PNP id / description of the adapter behind it.
+
+    The monitor-owning device is the *second* level of ``EnumDisplayDevices`` (the
+    "monitor" child of the display adapter), and its parent is what carries the hardware
+    id we match against.  We therefore report the monitor device's ``DeviceID`` plus the
+    adapter's, so a pattern like ``MttVDD`` matches either way.
+    """
+    if not IS_WINDOWS:
+        return {}
+    result: Dict[str, Dict[str, str]] = {}
+    index = 0
+    DISPLAY_DEVICE_ATTACHED_TO_DESKTOP = 0x00000001
+    while True:
+        adapter = _DISPLAY_DEVICEW()
+        adapter.cb = ctypes.sizeof(_DISPLAY_DEVICEW)
+        if not user32.EnumDisplayDevicesW(None, index, ctypes.byref(adapter), 0):
+            break
+        index += 1
+        if not adapter.DeviceName:
+            continue
+        entry = {
+            "adapter_string": adapter.DeviceString,
+            "adapter_id": adapter.DeviceID,
+            "monitor_string": "",
+            "monitor_id": "",
+        }
+        monitor = _DISPLAY_DEVICEW()
+        monitor.cb = ctypes.sizeof(_DISPLAY_DEVICEW)
+        if user32.EnumDisplayDevicesW(
+            adapter.DeviceName, 0, ctypes.byref(monitor), 0
+        ) and (monitor.StateFlags & DISPLAY_DEVICE_ATTACHED_TO_DESKTOP):
+            entry["monitor_string"] = monitor.DeviceString
+            entry["monitor_id"] = monitor.DeviceID
+        result[adapter.DeviceName] = entry
+    return result
+
+
+def enumerate_monitors() -> List[MonitorInfo]:
+    """Return every display monitor currently attached to the desktop."""
+    require_windows("enumerate_monitors")
+    devices = display_device_map()
+    monitors: List[MonitorInfo] = []
+
+    def _callback(hmonitor, hdc, lprect, lparam):
+        info = _MONITORINFOEXW()
+        info.cbSize = ctypes.sizeof(_MONITORINFOEXW)
+        if not user32.GetMonitorInfoW(hmonitor, ctypes.byref(info)):
+            return True
+        device = info.szDevice or ""
+        extra = devices.get(device, {})
+        monitors.append(
+            MonitorInfo(
+                handle=int(hmonitor) if hmonitor else 0,
+                device=device,
+                monitor=(
+                    int(info.rcMonitor.left),
+                    int(info.rcMonitor.top),
+                    int(info.rcMonitor.right),
+                    int(info.rcMonitor.bottom),
+                ),
+                work=(
+                    int(info.rcWork.left),
+                    int(info.rcWork.top),
+                    int(info.rcWork.right),
+                    int(info.rcWork.bottom),
+                ),
+                primary=bool(info.dwFlags & 1),
+                pnp_device_id=extra.get("monitor_id") or extra.get("adapter_id", ""),
+                device_string=extra.get("monitor_string") or extra.get("adapter_string", ""),
+            )
+        )
+        return True
+
+    callback = _MONITORENUMPROC(_callback)
+    if not user32.EnumDisplayMonitors(None, None, callback, 0):
+        log.debug("EnumDisplayMonitors returned no monitors: %s", ctypes.get_last_error())
+    monitors.sort(key=lambda m: (not m.primary, m.monitor[0], m.monitor[1]))
+    return monitors
+
+
+def select_virtual_monitor(
+    monitors: Sequence[MonitorInfo],
+    *,
+    preferred: str = "auto",
+    markers: Optional[Sequence[str]] = None,
+    exclude_primary: bool = True,
+) -> Optional[MonitorInfo]:
+    """Pick the monitor that a mounted window should live on.
+
+    ``preferred`` accepts:
+
+    * ``"auto"``  – first non-primary monitor whose adapter looks virtual, else the first
+      non-primary monitor, else ``None`` (never silently mount onto the user's primary
+      display unless ``exclude_primary=False``).
+    * ``"virtual"`` – like auto but *only* adapter-name/marker matches.
+    * ``"primary"`` – the primary monitor (useful for testing without a virtual display).
+    * ``"DISPLAY2"`` / ``"\\\\.\\DISPLAY2"`` / ``"2"`` – an explicit device name or 1-based index.
+
+    ``markers=None`` uses :meth:`MonitorInfo.is_decidedly_virtual`'s own defaults, so the two
+    can never drift apart (they did: the default list here omitted ``MTT``, and a monitor the
+    method called virtual was rejected by the selector, producing a misleading
+    ``DriverNotFoundError``).
+    """
+    if not monitors:
+        return None
+    value = (preferred or "auto").strip()
+    lowered = value.lower()
+
+    def looks_virtual(monitor: MonitorInfo) -> bool:
+        if markers is None:
+            return monitor.is_decidedly_virtual()
+        return monitor.is_decidedly_virtual(markers)
+
+    if lowered in ("primary", "main", "0"):
+        return next((m for m in monitors if m.primary), monitors[0])
+    if lowered in ("auto", "any"):
+        virtual = [m for m in monitors if looks_virtual(m)]
+        if virtual:
+            return virtual[0]
+        non_primary = [m for m in monitors if not m.primary]
+        if non_primary:
+            return non_primary[0]
+        return monitors[0] if not exclude_primary else None
+    if lowered in ("virtual", "idd", "marker"):
+        return next((m for m in monitors if looks_virtual(m)), None)
+
+    # Explicit selection.
+    if lowered.isdigit():
+        index = int(lowered)
+        for monitor in monitors:
+            if monitor.index == index:
+                return monitor
+        return None
+    needle = value.upper().lstrip("\\").lstrip(".")
+    for monitor in monitors:
+        if (monitor.device or "").upper().lstrip("\\").lstrip(".") == needle:
+            return monitor
+    for monitor in monitors:
+        if needle in (monitor.device or "").upper() or needle in (monitor.device_string or "").upper():
+            return monitor
+    return None
+
+
+# --------------------------------------------------------------------------------------
+# Windows
+# --------------------------------------------------------------------------------------
+
+
+@dataclass
+class WindowRecord:
+    hwnd: int
+    title: str
+    class_name: str
+    pid: int = 0
+    process_name: str = ""
+    visible: bool = False
+    minimized: bool = False
+    rect: Tuple[int, int, int, int] = (0, 0, 0, 0)
+    owner: int = 0
+    tool_window: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "hwnd": self.hwnd,
+            "title": self.title,
+            "class_name": self.class_name,
+            "pid": self.pid,
+            "process_name": self.process_name,
+            "visible": self.visible,
+            "minimized": self.minimized,
+            "rect": list(self.rect),
+        }
+
+
+GWL_STYLE = -16
+GWL_EXSTYLE = -20
+WS_EX_APPWINDOW = 0x00040000
+WS_EX_TOOLWINDOW = 0x00000080
+WS_EX_LAYERED = 0x00080000
+WS_EX_NOREDIRECTIONBITMAP = 0x00200000
+
+
+#: Characters that make a pattern "obviously a regular expression".  ``.`` is deliberately
+#: absent: in window titles it almost always means a literal dot (``"Notepad 1.2"``), and
+#: treating it as "any character" silently widens every match.
+_REGEX_META = frozenset("\\^$[](){}+*?|")
+
+
+def title_matches(title: str, pattern: str, *, mode: str = "auto") -> bool:
+    """Match a window title against a user-supplied pattern (pure helper, unit tested).
+
+    ``mode`` is one of ``exact``, ``substring``, ``regex`` or ``auto``.
+
+    ``auto`` (the default) is deliberately conservative, because guessing wrong is
+    expensive in both directions:
+
+    1. an exact match wins;
+    2. a literal substring match wins;
+    3. an *anchored* regex match is tried (``re.fullmatch``), so ``"Report \\\\d+"`` does not
+       need ``^...$``;
+    4. an unanchored regex search is tried **only** when the pattern contains real regex
+       syntax (see :data:`_REGEX_META`), so ``"1.2"`` can never match ``"1x2"``.
+
+    Callers who want real regex semantics regardless should pass ``mode="regex"``.
+    """
+    if pattern is None:
+        return True
+    if mode == "exact":
+        return title == pattern
+    if mode == "substring":
+        return pattern in title
+    if mode == "regex":
+        return re.search(pattern, title) is not None
+    if mode != "auto":
+        raise ValueError(f"unknown title match mode {mode!r}")
+    if pattern == title or pattern in title:
+        return True
+    try:
+        if re.fullmatch(pattern, title):
+            return True
+    except re.error:
+        return False
+    if not (_REGEX_META & set(pattern)):
+        return False
+    try:
+        return re.search(pattern, title) is not None
+    except re.error:
+        return False
+
+
+if IS_WINDOWS:  # pragma: no branch
+    _WNDENUMPROC = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
+    user32.GetWindowTextLengthW.argtypes = [wintypes.HWND]
+    user32.GetWindowTextW.argtypes = [wintypes.HWND, ctypes.c_wchar_p, ctypes.c_int]
+    user32.GetClassNameW.argtypes = [wintypes.HWND, ctypes.c_wchar_p, ctypes.c_int]
+    user32.IsWindowVisible.argtypes = [wintypes.HWND]
+    user32.IsIconic.argtypes = [wintypes.HWND]
+    user32.GetWindowThreadProcessId.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
+    user32.GetWindowLongW.argtypes = [wintypes.HWND, ctypes.c_int]
+    user32.GetWindowLongW.restype = wintypes.LONG
+
+
+_GW_OWNER = 4
+
+
+def is_owned_window(hwnd: int) -> bool:
+    """True when the window has an owner (a dialog / tool window, not a taskbar app)."""
+    if not IS_WINDOWS:
+        return False
+    return bool(user32.GetWindow(hwnd, _GW_OWNER))
+
+
+def _process_name_for_pid(pid: int, cache: Optional[dict] = None) -> str:
+    if not pid:
+        return ""
+    if cache is not None and pid in cache:
+        return cache[pid]
+    name = ""
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if handle:
+        try:
+            buf = ctypes.create_unicode_buffer(1024)
+            size = wintypes.DWORD(1024)
+            if kernel32.QueryFullProcessImageNameW(handle, 0, buf, ctypes.byref(size)):
+                name = os.path.basename(buf.value)
+        finally:
+            kernel32.CloseHandle(handle)
+    if cache is not None:
+        cache[pid] = name
+    return name
+
+
+def list_windows(*, include_hidden: bool = True) -> List[WindowRecord]:
+    """Enumerate top-level windows with the metadata needed for selection."""
+    require_windows("list_windows")
+    records: List[WindowRecord] = []
+    pid_cache: Dict[int, str] = {}
+
+    def _callback(hwnd, lparam):
+        length = user32.GetWindowTextLengthW(hwnd)
+        buf = ctypes.create_unicode_buffer(length + 1)
+        user32.GetWindowTextW(hwnd, buf, length + 1)
+        title = buf.value
+        cls = ctypes.create_unicode_buffer(256)
+        user32.GetClassNameW(hwnd, cls, 256)
+        visible = bool(user32.IsWindowVisible(hwnd))
+        if not include_hidden and not visible:
+            return True
+        pid = wintypes.DWORD()
+        user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+        rect = _RECT()
+        if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
+            rect = _RECT(0, 0, 0, 0)
+        ex_style = int(user32.GetWindowLongW(hwnd, GWL_EXSTYLE)) & 0xFFFFFFFF
+        records.append(
+            WindowRecord(
+                hwnd=int(hwnd),
+                title=title,
+                class_name=cls.value,
+                pid=int(pid.value),
+                process_name=_process_name_for_pid(int(pid.value), pid_cache),
+                visible=visible,
+                minimized=bool(user32.IsIconic(hwnd)),
+                rect=(int(rect.left), int(rect.top), int(rect.right), int(rect.bottom)),
+                owner=int(user32.GetWindow(hwnd, _GW_OWNER) or 0),
+                tool_window=bool(ex_style & WS_EX_TOOLWINDOW),
+            )
+        )
+        return True
+
+    callback = _WNDENUMPROC(_callback)
+    user32.EnumWindows(callback, 0)
+    return records
+
+
+def find_hwnd_by_title(title: str, *, limit: int = 0) -> int:
+    """Best-effort ``FindWindow(None, title)`` used by the CLI ``capture`` command.
+
+    Returns 0 when there is no *exact* top-level title match, and ``limit`` > 0 makes the
+    caller's intent explicit: the first substring match is returned instead.
+    """
+    require_windows("find_hwnd_by_title")
+    hwnd = int(user32.FindWindowW(None, title) or 0)
+    if hwnd or not limit:
+        return hwnd
+    for record in list_windows():
+        if title.lower() in (record.title or "").lower():
+            return record.hwnd
+    return 0
+
+
+if IS_WINDOWS:  # pragma: no branch
+    user32.GetWindowRect.argtypes = [wintypes.HWND, ctypes.POINTER(_RECT)]
+    user32.GetWindowRect.restype = wintypes.BOOL
+    user32.GetWindow.argtypes = [wintypes.HWND, wintypes.UINT]
+    user32.GetWindow.restype = wintypes.HWND
+    user32.FindWindowW.argtypes = [ctypes.c_wchar_p, ctypes.c_wchar_p]
+    user32.FindWindowW.restype = wintypes.HWND