snapmockit 1.2.0__py3-none-any.whl

snapmock/__init__.py

@@ -0,0 +1,3 @@
+"""Snapmockit — open-source multi-platform screenshot annotation & UI mockup tool."""
+
+__version__ = "1.2.0"

snapmock/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m snapmock``."""
+
+from snapmock.app import main
+
+if __name__ == "__main__":
+    main()

snapmock/app.py

@@ -0,0 +1,131 @@
+"""QApplication bootstrap, the single-instance channel, and command-line capture (PRD 3.5)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from PyQt6.QtCore import QTimer
+from PyQt6.QtWidgets import QApplication
+
+from snapmock.capture.cli import CaptureCommand, parse_command_line
+from snapmock.capture.single_instance import try_forward
+from snapmock.config.constants import APP_NAME, APP_VERSION, DESKTOP_ENTRY_ID
+from snapmock.config.migration import import_host_settings, migrate_storage
+from snapmock.main_window import MainWindow
+from snapmock.ui.icons import application_icon
+
+log = logging.getLogger("snapmock")
+
+
+def desktop_entry_installed(
+    entry_id: str = DESKTOP_ENTRY_ID, environ: Mapping[str, str] | None = None
+) -> bool:
+    """Whether ``<entry_id>.desktop`` is in an applications directory of the XDG data path.
+
+    ``$XDG_DATA_HOME`` (default ``~/.local/share``) and ``$XDG_DATA_DIRS``
+    (default ``/usr/local/share:/usr/share``), as the desktop and its portal
+    look the entry up. True from a package that installed the entry, or from an
+    AppImage integrated into the menu; false from source and from a bare AppImage.
+    """
+    env = os.environ if environ is None else environ
+    data_home = env.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    data_dirs = env.get("XDG_DATA_DIRS") or "/usr/local/share:/usr/share"
+    for base in [data_home, *data_dirs.split(":")]:
+        if base and (Path(base) / "applications" / f"{entry_id}.desktop").is_file():
+            return True
+    return False
+
+
+def version_text() -> str:
+    """What ``--version`` prints: the product's name and version (packaging silence 6)."""
+    return f"{APP_NAME} {APP_VERSION}"
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Launch the application, or forward a capture request to the running instance.
+
+    ``--version`` prints :func:`version_text` and exits before any Qt object exists,
+    so a smoke test and a bug report can read it without a display.
+    """
+    argv = list(sys.argv if argv is None else argv)
+    if "--version" in argv[1:]:
+        print(version_text())
+        sys.exit(0)
+    command, files = parse_command_line(argv)
+    # The names are set before the application exists: Qt registers the desktop
+    # entry's id with the desktop portal when the first window shows, once, from
+    # the name it holds then; a name set afterwards registers a second time and
+    # the portal refuses it ("Connection already associated with an application
+    # ID", seen from the AppImage on 09-14-26). The id is given to Qt only where
+    # the desktop entry is installed, since the portal looks the entry up and
+    # answers "App info not found" for an AppImage that is not in the menu.
+    QApplication.setApplicationName(APP_NAME)
+    QApplication.setApplicationVersion(APP_VERSION)
+    if desktop_entry_installed():
+        QApplication.setDesktopFileName(DESKTOP_ENTRY_ID)
+    # The application is created before the forward because the write to the
+    # channel completes only once an event loop is available to pump it, which
+    # is how a Windows named pipe behaves (PRD 3.5).
+    app = QApplication(argv)
+    app.setWindowIcon(application_icon())
+    if command is not None and try_forward(argv):
+        sys.exit(0)
+
+    # Before anything reads the settings or the library (packaging decision 4).
+    migration = migrate_storage()
+    # Inside a Flatpak, the store is the sandbox's own; fill it once from the home
+    # directory's on the first start (Flatpak decision 4).
+    imported = import_host_settings()
+    window = MainWindow(restore_session=True)
+    manager = window.capture_manager
+    manager.listen_for_commands()
+    manager.register_hotkeys()
+
+    hide_until_done = command is not None and window.capture_manager.settings.capture_hide_window()
+    if not hide_until_done:
+        window.show()
+        window.report_hotkey_failures()
+    startup_messages = [text for text in (migration.message(), imported.message()) if text]
+    if startup_messages:
+        window.show_startup_message(" ".join(startup_messages))
+    if files:
+        window.open_paths([Path(name) for name in files])
+    if command is not None:
+        _capture_as_first_action(window, command, show_after=hide_until_done)
+    sys.exit(app.exec())
+
+
+def _capture_as_first_action(
+    window: MainWindow, command: CaptureCommand, *, show_after: bool
+) -> None:
+    """Run ``--capture`` once the event loop starts; show the window when it is over."""
+    manager = window.capture_manager
+
+    def finish() -> None:
+        if show_after and not window.isVisible():
+            window.show()
+            window.report_hotkey_failures()
+        for signal in (
+            manager.capture_completed,
+            manager.capture_failed,
+            manager.capture_cancelled,
+        ):
+            try:
+                signal.disconnect(finish)
+            except TypeError:
+                pass
+
+    if show_after:
+        manager.capture_completed.connect(finish)
+        manager.capture_failed.connect(finish)
+        manager.capture_cancelled.connect(finish)
+
+    def start() -> None:
+        if not manager.start_from_command(command):
+            finish()
+
+    QTimer.singleShot(0, start)

snapmock/capture/__init__.py

@@ -0,0 +1,66 @@
+"""Screen capture: modes, entry points, the region overlay, and platform backends.
+
+Nothing outside this package imports a platform module. The editor talks
+to :class:`snapmock.capture.manager.CaptureManager` and nothing else.
+
+Backend selection (PRD 6.2) happens here, once, from the platform name and
+the session type. It is not user-configurable.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import sys
+
+from PyQt6.QtGui import QGuiApplication
+
+from snapmock.capture.backend import (
+    CaptureBackend,
+    HotkeyBackend,
+    NullCaptureBackend,
+    NullHotkeyBackend,
+)
+
+log = logging.getLogger("snapmock.capture")
+
+
+def is_wayland_session() -> bool:
+    """Whether Qt runs on Wayland or the session environment reports Wayland."""
+    platform = QGuiApplication.platformName().lower() if QGuiApplication.instance() else ""
+    if platform.startswith("wayland"):
+        return True
+    if platform in ("xcb", "offscreen", "minimal"):
+        return False
+    session = os.environ.get("XDG_SESSION_TYPE", "").lower()
+    return session == "wayland" or bool(os.environ.get("WAYLAND_DISPLAY"))
+
+
+def select_backends() -> tuple[CaptureBackend, HotkeyBackend]:
+    """Pick the capture and hotkey backends for this platform and session.
+
+    Linux on Wayland selects the portal backend; Linux otherwise selects X11;
+    macOS and Windows select their backends. Anything else, and any platform
+    whose module cannot activate, gets the null backends.
+    """
+    capture: CaptureBackend = NullCaptureBackend()
+    hotkeys: HotkeyBackend = NullHotkeyBackend()
+    module_name: str | None = None
+    if sys.platform.startswith("linux"):
+        module_name = "wayland_portal" if is_wayland_session() else "x11"
+    elif sys.platform == "darwin":
+        module_name = "macos"
+    elif sys.platform.startswith("win"):
+        module_name = "windows"
+    if module_name is not None:
+        try:
+            module = importlib.import_module(f"snapmock.capture.{module_name}")
+            created = module.create_backends()
+            capture, hotkeys = created
+        except (ImportError, OSError, AttributeError) as e:
+            log.warning(
+                "Capture backend %s unavailable (%s); using the null backend", module_name, e
+            )
+    log.info("Selected capture backend %s, hotkey backend %s", capture.name, hotkeys.name)
+    return capture, hotkeys

snapmock/capture/backend.py

@@ -0,0 +1,315 @@
+"""The capture backend abstraction (Screen Capture PRD Sections 6.1, 6.7).
+
+The application sees :class:`CaptureBackend` and :class:`HotkeyBackend` and
+nothing platform-specific. This module also holds the null backends used
+when nothing is supported, a Qt-based grab shared by the X11, macOS and
+Windows backends, and fake backends for the test suite.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+from PyQt6.QtCore import QObject, QPoint, QRect, QSize, pyqtSignal
+from PyQt6.QtGui import QColor, QCursor, QGuiApplication, QImage, QLinearGradient, QPainter
+
+from snapmock.capture.models import (
+    BackendCapabilities,
+    HotkeyBinding,
+    MonitorInfo,
+    PermissionState,
+    ScreenGrab,
+)
+
+log = logging.getLogger("snapmock.capture")
+
+UNSUPPORTED_PLATFORM_MESSAGE = "Screen capture is not supported on this platform."
+
+
+class CaptureError(Exception):
+    """A capture failed; ``str(error)`` is the user-readable reason (PRD 7.4)."""
+
+
+class CaptureCancelledError(CaptureError):
+    """The user cancelled inside a platform dialog (for example the portal's consent)."""
+
+
+class CaptureBackend(ABC):
+    """Platform-specific pixel reading (PRD 6.1). One instance per process."""
+
+    #: ``x11``, ``wayland_portal``, ``macos``, ``windows``, ``null`` or ``fake``.
+    name: str = "null"
+
+    @abstractmethod
+    def capabilities(self) -> BackendCapabilities:
+        """Which modes and options this backend supports on this session."""
+
+    @abstractmethod
+    def monitors(self) -> list[MonitorInfo]:
+        """Every connected monitor."""
+
+    @abstractmethod
+    def grab_screens(self, include_cursor: bool) -> ScreenGrab:
+        """One physical-pixel image per monitor. Raises :class:`CaptureError`."""
+
+    def active_window_geometry(self) -> QRect | None:
+        """Logical geometry of the focused window, excluding shadow, or None."""
+        return None
+
+    def active_window_title(self) -> str | None:
+        return None
+
+    def request_permission(self) -> PermissionState:
+        return PermissionState.NOT_REQUIRED
+
+
+class HotkeyBackend(QObject):
+    """Global hotkey registration (PRD 6.7).
+
+    Signals
+    -------
+    triggered(str)
+        A registered hotkey was pressed; carries the binding's action.
+    """
+
+    triggered = pyqtSignal(str)
+
+    name: str = "null"
+
+    @property
+    def supported(self) -> bool:
+        """Whether this backend can register hotkeys at all."""
+        return False
+
+    def register(self, binding: HotkeyBinding) -> bool:
+        """Register *binding*, updating its ``registered`` and ``failure_reason``."""
+        binding.registered = False
+        binding.failure_reason = "Global hotkeys are not available on this desktop."
+        return False
+
+    def unregister(self, binding: HotkeyBinding) -> None:
+        binding.registered = False
+
+    def unregister_all(self) -> None:
+        return None
+
+
+# --- null backends (PRD 6.2: unrecognized platform) ---
+
+
+class NullCaptureBackend(CaptureBackend):
+    """Reports nothing supported; every grab fails with the platform message."""
+
+    name = "null"
+
+    def capabilities(self) -> BackendCapabilities:
+        return BackendCapabilities()
+
+    def monitors(self) -> list[MonitorInfo]:
+        return qt_monitors()
+
+    def grab_screens(self, include_cursor: bool) -> ScreenGrab:
+        raise CaptureError(UNSUPPORTED_PLATFORM_MESSAGE)
+
+
+class NullHotkeyBackend(HotkeyBackend):
+    """Reports every registration as unsupported (Wayland, macOS in version 1)."""
+
+    name = "null"
+
+
+# --- Qt-based grab shared by the X11, macOS and Windows backends ---
+
+
+def qt_monitors() -> list[MonitorInfo]:
+    """Build the monitor list from Qt's screens."""
+    result: list[MonitorInfo] = []
+    primary = QGuiApplication.primaryScreen()
+    for screen in QGuiApplication.screens():
+        ratio = float(screen.devicePixelRatio())
+        geo = screen.geometry()
+        result.append(
+            MonitorInfo(
+                name=screen.name() or f"screen{len(result)}",
+                logical_geometry=QRect(geo),
+                physical_size=QSize(round(geo.width() * ratio), round(geo.height() * ratio)),
+                device_pixel_ratio=ratio,
+                is_primary=screen is primary,
+            )
+        )
+    return result
+
+
+def physical_to_logical(physical: QRect) -> QRect:
+    """Map a root-window (physical pixel) rectangle to Qt's logical virtual desktop."""
+    monitors = qt_monitors()
+    best = None
+    best_area = -1
+    for m in monitors:
+        area = m.physical_geometry.intersected(physical)
+        size = max(0, area.width()) * max(0, area.height())
+        if size > best_area:
+            best, best_area = m, size
+    if best is None:
+        return QRect(physical)
+    ratio = best.device_pixel_ratio
+    origin = best.physical_geometry.topLeft()
+    left = best.logical_geometry.x() + (physical.x() - origin.x()) / ratio
+    top = best.logical_geometry.y() + (physical.y() - origin.y()) / ratio
+    return QRect(
+        round(left), round(top), round(physical.width() / ratio), round(physical.height() / ratio)
+    )
+
+
+class QtScreenGrabBackend(CaptureBackend):
+    """Grabs every screen through Qt's root-window grab (PRD 6.3, 6.5, 6.6).
+
+    Subclasses add the cursor image and the active window through platform
+    calls; when ``_cursor_image`` returns None the cursor is left out.
+    """
+
+    def monitors(self) -> list[MonitorInfo]:
+        return qt_monitors()
+
+    def grab_screens(self, include_cursor: bool) -> ScreenGrab:
+        monitors = self.monitors()
+        images: dict[str, QImage] = {}
+        for screen, info in zip(QGuiApplication.screens(), monitors, strict=False):
+            pixmap = screen.grabWindow()
+            if pixmap.isNull():
+                raise CaptureError("The screen could not be read.")
+            image = pixmap.toImage()
+            if image.size() != info.physical_size and not info.physical_size.isEmpty():
+                image = image.scaled(info.physical_size)
+            image.setDevicePixelRatio(1.0)
+            images[info.name] = image
+        if not images:
+            raise CaptureError("No monitor was found to capture.")
+        grab = ScreenGrab(images=images, monitors=monitors, taken_at=datetime.now())
+        grab.cursor_position = QCursor.pos()
+        if include_cursor:
+            cursor = self._cursor_image()
+            if cursor is not None:
+                grab.cursor_image, grab.cursor_hotspot = cursor
+        return grab
+
+    def _cursor_image(self) -> tuple[QImage, QPoint] | None:
+        """Cursor bitmap with alpha and its hotspot, or None when unavailable."""
+        return None
+
+
+# --- fakes for tests (PRD 14.5: every backend-independent path runs against a fake) ---
+
+
+def synthetic_image(size: QSize, seed: int = 0) -> QImage:
+    """A gradient image whose pixels differ by position, so crops are verifiable."""
+    image = QImage(size, QImage.Format.Format_ARGB32)
+    image.fill(QColor(0, 0, 0))
+    painter = QPainter(image)
+    gradient = QLinearGradient(0, 0, size.width(), size.height())
+    gradient.setColorAt(0.0, QColor((40 * seed) % 256, 80, 200))
+    gradient.setColorAt(1.0, QColor(255, (60 * seed + 120) % 256, 30))
+    painter.fillRect(image.rect(), gradient)
+    painter.end()
+    return image
+
+
+class FakeCaptureBackend(CaptureBackend):
+    """Returns synthetic monitors and images; every knob is a plain attribute."""
+
+    name = "fake"
+
+    def __init__(self, monitors: list[MonitorInfo] | None = None) -> None:
+        self.fake_monitors: list[MonitorInfo] = monitors or [
+            MonitorInfo("fake-0", QRect(0, 0, 200, 100), QSize(200, 100), 1.0, True)
+        ]
+        self.fake_capabilities = BackendCapabilities(
+            full_screen=True, active_window=True, region=True, cursor=True, hotkeys=True, tray=True
+        )
+        self.fake_cursor_image: QImage | None = None
+        self.fake_cursor_hotspot = QPoint(0, 0)
+        self.fake_cursor_position = QPoint(10, 10)
+        self.fake_active_window: QRect | None = QRect(20, 10, 60, 40)
+        self.fake_window_title: str | None = "Fake Window"
+        self.fake_permission = PermissionState.NOT_REQUIRED
+        self.fail_with: str | None = None
+        self.grab_calls: list[bool] = []
+        self.permission_requests = 0
+
+    def capabilities(self) -> BackendCapabilities:
+        return self.fake_capabilities
+
+    def monitors(self) -> list[MonitorInfo]:
+        return list(self.fake_monitors)
+
+    def grab_screens(self, include_cursor: bool) -> ScreenGrab:
+        self.grab_calls.append(include_cursor)
+        if self.fail_with is not None:
+            raise CaptureError(self.fail_with)
+        images = {
+            m.name: synthetic_image(m.physical_size, seed=i)
+            for i, m in enumerate(self.fake_monitors)
+        }
+        grab = ScreenGrab(
+            images=images,
+            monitors=self.monitors(),
+            cursor_position=QPoint(self.fake_cursor_position),
+            taken_at=datetime.now(),
+        )
+        if include_cursor and self.fake_capabilities.cursor:
+            cursor = self.fake_cursor_image
+            if cursor is None:
+                cursor = QImage(8, 8, QImage.Format.Format_ARGB32)
+                cursor.fill(QColor(255, 255, 255, 255))
+            grab.cursor_image = cursor
+            grab.cursor_hotspot = QPoint(self.fake_cursor_hotspot)
+        return grab
+
+    def active_window_geometry(self) -> QRect | None:
+        return QRect(self.fake_active_window) if self.fake_active_window else None
+
+    def active_window_title(self) -> str | None:
+        return self.fake_window_title
+
+    def request_permission(self) -> PermissionState:
+        self.permission_requests += 1
+        return self.fake_permission
+
+
+class FakeHotkeyBackend(HotkeyBackend):
+    """Accepts every registration except keys listed in ``refused``."""
+
+    name = "fake"
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self.refused: set[str] = set()
+        self.registered: dict[str, str] = {}
+
+    @property
+    def supported(self) -> bool:
+        return True
+
+    def register(self, binding: HotkeyBinding) -> bool:
+        if binding.key_text in self.refused:
+            binding.registered = False
+            binding.failure_reason = "In use by another application"
+            return False
+        self.registered[binding.action] = binding.key_text
+        binding.registered = True
+        binding.failure_reason = None
+        return True
+
+    def unregister(self, binding: HotkeyBinding) -> None:
+        self.registered.pop(binding.action, None)
+        binding.registered = False
+
+    def unregister_all(self) -> None:
+        self.registered.clear()
+
+    def fire(self, action: str) -> None:
+        """Simulate the operating system delivering the hotkey for *action*."""
+        if action in self.registered:
+            self.triggered.emit(action)

snapmock/capture/cli.py

@@ -0,0 +1,62 @@
+"""Command-line invocation (PRD 3.5): ``snapmock --capture <mode> [--delay N]``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CaptureCommand:
+    """A capture request parsed from a command line. ``mode`` None means the default."""
+
+    mode: str | None = None
+    delay_seconds: int | None = None
+
+
+def parse_capture_args(argv: list[str]) -> CaptureCommand | None:
+    """Return the capture command in *argv*, or None when no capture was requested.
+
+    Accepts ``--capture``, ``--capture <mode>``, ``--capture=<mode>``,
+    ``--delay <seconds>`` and ``--delay=<seconds>``. Unknown arguments are ignored.
+    """
+    return parse_command_line(argv)[0]
+
+
+def parse_command_line(argv: list[str]) -> tuple[CaptureCommand | None, list[str]]:
+    """The capture command in *argv*, if any, and the files named on it.
+
+    *argv* is a whole command line; its first element is the program unless it is
+    an option. A file is any later argument that does not start with ``-`` and is
+    not the value of ``--capture`` or ``--delay``; the desktop entry's ``%F`` and
+    a shell both pass files that way (packaging silence 2). Unknown options are
+    ignored.
+    """
+    command: CaptureCommand | None = None
+    delay: int | None = None
+    files: list[str] = []
+    args = list(argv)
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--capture" or arg.startswith("--capture="):
+            command = command or CaptureCommand()
+            if "=" in arg:
+                command.mode = arg.split("=", 1)[1] or None
+            elif i + 1 < len(args) and not args[i + 1].startswith("-"):
+                command.mode = args[i + 1]
+                i += 1
+        elif arg == "--delay" or arg.startswith("--delay="):
+            text = arg.split("=", 1)[1] if "=" in arg else ""
+            if not text and i + 1 < len(args):
+                text = args[i + 1]
+                i += 1
+            try:
+                delay = max(0, min(60, int(text)))
+            except ValueError:
+                delay = None
+        elif i > 0 and not arg.startswith("-"):
+            files.append(arg)
+        i += 1
+    if command is not None:
+        command.delay_seconds = delay
+    return command, files

snapmock/capture/compositing.py

@@ -0,0 +1,99 @@
+"""Pure image operations on a :class:`ScreenGrab` (PRD Sections 2.2 to 2.4, 4.2, 4.5).
+
+Everything here is a function of the frozen grab; nothing reads the screen.
+"""
+
+from __future__ import annotations
+
+import math
+
+from PyQt6.QtCore import QBuffer, QIODevice, QPoint, QRect, QRectF
+from PyQt6.QtGui import QColor, QImage, QPainter
+
+from snapmock.capture.models import MonitorInfo, ScreenGrab
+
+
+def physical_rect_for(logical_rect: QRect, ratio: float) -> QRect:
+    """Convert a logical rectangle to physical pixels, rounding outward (PRD 4.5)."""
+    left = math.floor(logical_rect.left() * ratio)
+    top = math.floor(logical_rect.top() * ratio)
+    right = math.ceil((logical_rect.left() + logical_rect.width()) * ratio)
+    bottom = math.ceil((logical_rect.top() + logical_rect.height()) * ratio)
+    return QRect(left, top, max(0, right - left), max(0, bottom - top))
+
+
+def composite_cursor(grab: ScreenGrab) -> bool:
+    """Draw the cursor into the monitor image under it. Returns True when drawn."""
+    if grab.cursor_image is None or grab.cursor_position is None:
+        return False
+    monitor = grab.monitor_at(grab.cursor_position)
+    if monitor is None:
+        return False
+    image = grab.images.get(monitor.name)
+    if image is None or image.isNull():
+        return False
+    hotspot = grab.cursor_hotspot or QPoint(0, 0)
+    local = grab.cursor_position - monitor.logical_geometry.topLeft()
+    ratio = monitor.device_pixel_ratio
+    x = round(local.x() * ratio) - hotspot.x()
+    y = round(local.y() * ratio) - hotspot.y()
+    painter = QPainter(image)
+    painter.drawImage(QPoint(x, y), grab.cursor_image)
+    painter.end()
+    return True
+
+
+def render_region(grab: ScreenGrab, logical_rect: QRect, ratio: float) -> QImage:
+    """Render *logical_rect* of the virtual desktop at *ratio* physical pixels per logical.
+
+    Each monitor's image is drawn at its own offset; a monitor whose ratio
+    differs from *ratio* is scaled to match (only All Monitors with mixed
+    ratios reaches that path). Areas no monitor covers stay black (PRD 4.4).
+    """
+    target_rect = physical_rect_for(logical_rect, ratio)
+    image = QImage(target_rect.size(), QImage.Format.Format_ARGB32)
+    image.fill(QColor(0, 0, 0))
+    if image.isNull() or target_rect.isEmpty():
+        return image
+    painter = QPainter(image)
+    painter.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform, True)
+    for monitor in grab.monitors:
+        source = grab.images.get(monitor.name)
+        if source is None or source.isNull():
+            continue
+        if not monitor.logical_geometry.intersects(logical_rect):
+            continue
+        # Where this monitor lands in the target image, in physical pixels.
+        dest_x = monitor.logical_geometry.x() * ratio - target_rect.x()
+        dest_y = monitor.logical_geometry.y() * ratio - target_rect.y()
+        if math.isclose(monitor.device_pixel_ratio, ratio):
+            painter.drawImage(QPoint(round(dest_x), round(dest_y)), source)
+        else:
+            dest = QRectF(
+                dest_x,
+                dest_y,
+                monitor.logical_geometry.width() * ratio,
+                monitor.logical_geometry.height() * ratio,
+            )
+            painter.drawImage(dest, source, QRectF(source.rect()))
+    painter.end()
+    return image
+
+
+def monitor_region(grab: ScreenGrab, monitor: MonitorInfo) -> QImage:
+    """The physical-pixel image of one monitor, as captured."""
+    source = grab.images.get(monitor.name)
+    if source is None:
+        return QImage()
+    return source.copy()
+
+
+def max_ratio(monitors: list[MonitorInfo]) -> float:
+    return max((m.device_pixel_ratio for m in monitors), default=1.0)
+
+
+def image_to_png_bytes(image: QImage) -> bytes:
+    buf = QBuffer()
+    buf.open(QIODevice.OpenModeFlag.WriteOnly)
+    image.save(buf, "PNG")
+    return bytes(buf.data().data())