remotedesktop 0.16.0__tar.gz → 0.18.0__tar.gz

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/CLAUDE.md

@@ -47,7 +47,7 @@ Managed with `uv` (hatchling build backend, src layout):
 - **Revoking access**: `InventoryTab` takes an optional `(action_label, action_callback)`; the callback gets the selected peer's key. The server's tab wires "Revoke access" → `ShareServer.revoke_client(client_id)` (removes the token via `PairedClients.revoke`, disconnects any live stream with a `denied: access revoked`, and `_drop` reports state "revoked"; a `_revoked` set distinguishes it from a plain disconnect). The client's tab wires "Forget server" → `KnownServers.forget(key)` + disconnect. After either, the next connection needs a fresh approval. Server and client each use a *separate table* (`server_peers` / `client_peers`, selected via the `table=` arg) so a machine running both apps doesn't commingle them; `peers` is the default table used by tests. `ConnectionInventory` never lets a DB error break connectivity (load/save are wrapped).
 - Sharing tests drive real sockets on the GUI thread by pumping `qapp.processEvents()` until a condition holds (see `pump()` in `tests/test_sharing.py`). Use the `make_server`/`make_client` helpers there and the session-scoped `credentials` fixture (one generated cert reused across tests — generating per test is ~100ms each). Tests exercise the real pairing flow (auto-approve), so there is no "pre-approve" shortcut anymore.
 - **Input forwarding**: `ViewerWidget` captures mouse/keyboard events and emits `inputEvent` dicts with coordinates normalized 0..1 over the *displayed* frame rect (letterboxing is reversed via `_display_rect()`; events outside the frame are dropped). Keys carry the client's `nativeVirtualKey()` — since both ends are Windows, the server injects that VK directly with no key-translation table. The client sends these as `{"type": "input", ...}`; `ShareServer` only injects input from streams that completed the hello/approval handshake.
-- **Modal-loop pump** (`modal_loop.py`): a Windows title-bar drag (or click-and-hold) puts the window's thread into a native modal move/size loop where Qt's dispatcher stops — for the server this deadlocked when a *remote* click grabbed the server window's own title bar (the mouse-up sat unread on the socket). `ServerWindow.nativeEvent` feeds `ModalLoopPump`, which runs a native `SetTimer` from `WM_NCLBUTTONDOWN` (a press-and-hold that never moves blocks in DefWindowProc's click tracking without ever sending `WM_ENTERSIZEMOVE`) until `WM_CAPTURECHANGED`/`WM_EXITSIZEMOVE`, whose callback pumps Qt events (user input excluded). Tests inject a fake `timers` backend — never let them create real Win32 timers.
+- **Modal-loop pump** (`modal_loop.py`): a Windows title-bar drag (or click-and-hold) puts the window's thread into a native modal move/size loop where Qt's dispatcher stops — for the server this deadlocked when a *remote* click grabbed the server window's own title bar (the mouse-up sat unread on the socket). `ServerWindow.nativeEvent` feeds `ModalLoopPump`, which runs a native `SetTimer` from `WM_NCLBUTTONDOWN` (a press-and-hold that never moves blocks in DefWindowProc's click tracking without ever sending `WM_ENTERSIZEMOVE`) until `WM_CAPTURECHANGED`/`WM_EXITSIZEMOVE`, whose callback pumps Qt events (user input excluded). The caption buttons (min/max/close) are the exception — their tracking loop dispatches only mouse messages, so no timer can pump inside it; the pump instead performs those via its `caption_action` callback on press and consumes the message (nativeEvent must return True when `handle_native_event` does), so DefWindowProc's button tracking never starts. Tests inject a fake `timers` backend — never let them create real Win32 timers.
 - **Log exchange**: either side can fetch the peer's debug log over the connection (`{"type": "log_request"}` → `{"type": "log", "text": ...}`, admitted streams only). `ShareServer`/`ShareClient` take a `log_provider=` callable (the windows pass `logs.read_log_tail("server"/"client")`, capped at `logs.TAIL_BYTES`); a missing provider/file answers with a placeholder rather than hanging the requester. Both windows have a "Get client log"/"Get server log" button in the Connection log tab; the reply opens a `logs.PeerLogDialog`. The server requests from the most recently admitted stream.
 - **Injection is isolated behind `InputInjector`** (`input_injection.py`, Windows `SendInput` via ctypes; inert stub off-Windows). ShareServer takes an `injector=` param so tests pass a recording fake — **never let tests construct a real `InputInjector`, or they will move the host's actual mouse/keyboard.** Normalized 0..1 coords map directly to SendInput's 0..65535 absolute range over the primary monitor.
 - **Transport is TLS + a token handshake** (`tls.py`, `sharing.py`, `config.py`). The Qt SSL backend here is Windows **schannel** (no OpenSSL); it does complete server-side TLS with a `cryptography`-generated self-signed cert loaded from PEM (verified), but be wary of schannel-specific quirks if you change the config. The server persists a self-signed cert/key under the config dir (`tls.load_or_create_credentials`; `ShareServer(credentials=...)`, or ephemeral if omitted). The client connects with `connectToHostEncrypted`, ignores the expected self-signed cert errors (`PeerVerifyMode.VerifyNone`), and pins the cert fingerprint **softly** — a change is logged but does *not* block the connection (robustness over strict security, per the trusted-LAN intent). Authentication: on first connect the server user approves and the server issues a random token (`PairedClients.pair`, stored server-side by client-id; client stores it in `KnownServers` keyed by `host:port` with the fingerprint). On reconnect the client sends the token in its hello and is admitted with no prompt; a missing/invalid token just falls back to re-approval (never hard-fails). **Do not reintroduce hard cert-pinning or challenge-response** — the user explicitly wanted robust connections over maximum security.

remotedesktop-0.18.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: remotedesktop
+Version: 0.18.0
+Summary: Remote desktop client/server for Windows computers on the same LAN, with autodiscovery. Provides screen, keyboard, mouse, and clipboard sharing without RDP or Microsoft authentication.
+Author-email: James Abel <j@abel.co>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.14
+Requires-Dist: cryptography>=49.0.0
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pyside6>=6.11.1
+Description-Content-Type: text/markdown
+
+# Remote Desktop
+
+[![CI](https://github.com/jamesabel/remotedesktop/actions/workflows/ci.yml/badge.svg)](https://github.com/jamesabel/remotedesktop/actions/workflows/ci.yml)
+![Coverage](https://raw.githubusercontent.com/jamesabel/remotedesktop/badges/coverage.svg)
+[![PyPI](https://img.shields.io/pypi/v/remotedesktop)](https://pypi.org/project/remotedesktop/)
+![Python](https://img.shields.io/badge/python-3.14%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Lossless, low-latency remote desktop for Windows computers on your LAN — pure Python, zero configuration.**
+
+Run the server on the computer you want to reach and the client anywhere else
+on the network: the server is discovered automatically, the first connection
+is approved with one click on the server side, and from then on the client
+reconnects instantly whenever the server is running. The screen stream is
+pixel-exact at full resolution — built for documents, code, and terminals
+rather than video — captured with DXGI desktop duplication and delta-compressed
+so only the parts of the screen that changed are sent. No Windows RDP, no
+Microsoft accounts, no cloud: just two apps and your LAN.
+
+## See it in action
+
+### Client
+
+![Client demo](https://raw.githubusercontent.com/jamesabel/remotedesktop/master/docs/media/client-demo.gif)
+
+The client discovers the server on the LAN, connects, and streams its
+desktop live in the *Remote Screen* tab — click into the view and your mouse
+and keyboard control the remote machine. The *Performance* tab graphs
+bandwidth and round-trip time with live statistics.
+
+### Server
+
+![Server demo](https://raw.githubusercontent.com/jamesabel/remotedesktop/master/docs/media/server-demo.gif)
+
+The server's *Status* tab shows every connected viewer — who they are (login
+name, computer, OS) and how the connection is doing (bandwidth, round-trip
+time with mean/min/max/p99/jitter over the recent window).
+
+## Features
+
+- 🔍 **Autodiscovery** — servers announce themselves over UDP; the client lists every server on the LAN, no addresses to type.
+- 🖥️ **Lossless screen sharing** — pixel-exact at full resolution, DXGI desktop-duplication capture (~10 ms per 4K frame), and inter-frame delta compression: an unchanged screen sends nothing.
+- ⌨️🖱️ **Full input control** — mouse, wheel, and keyboard forwarding that is safe against interruptions: anything still held down is released on the server if the viewer loses focus or disconnects, so no stuck keys.
+- 📋 **Two-way clipboard** — text and images copied on either machine appear on the other.
+- 🔒 **TLS + approve-once pairing** — every connection is encrypted; the server user approves a new client once, after which it reconnects with a stored token and no prompt.
+- 📊 **Built-in performance monitoring** — live bandwidth and round-trip-time graphs with window statistics (mean/min/max/p99/jitter), plus a per-viewer table on the server.
+- 🔁 **Robust connections** — dead connections are detected and dropped within seconds, and approved clients reconnect automatically without ceremony.
+- 🚀 **Hands-off operation** — optional start-at-login (per-user, no admin rights) and a *Restart server* button usable from the remote session itself, so you can update the software without visiting the machine.
+- 🗃️ **Persistent peer inventory** — both apps keep a SQLite-backed history of every peer seen on the LAN, with one-click *revoke access* / *forget server*.
+
+In scope: screen, keyboard, mouse, and clipboard. Out of scope: shared
+drives, devices, and audio — and smooth playback of fast-changing
+full-screen content (video, games) is a non-goal; the stream is optimized
+for mostly-static desktop work.
+
+## Installation
+
+```
+pip install remotedesktop
+```
+
+or, with [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install remotedesktop
+```
+
+Or run straight from a clone of this repository: double-click
+`run_server.bat` on the computer to be shared and `run_client.bat` on the
+viewing computer — each prepares the environment on first use and launches
+the app.
+
+## Quick start
+
+1. On the computer to share, run `remotedesktop-server`.
+2. On the viewing computer, run `remotedesktop-client` — the server appears
+   in its *Servers* panel; double-click it.
+3. Approve the connection in the dialog that pops up on the server. That's
+   it — future connections from that client need no approval.
+
+From a terminal in a clone of this repo, the same apps run with
+`uv run remotedesktop-server` and `uv run remotedesktop-client`.
+
+## Security model
+
+Connections are TLS-encrypted with a self-signed certificate the server
+generates once and keeps. The trust model is tuned for a **trusted LAN**:
+certificates are trusted on first use and a changed fingerprint is logged
+rather than blocking the connection, favoring reliable reconnection over
+strict certificate checking. Unapproved clients are limited to small
+handshake messages until the server user admits them; access can be revoked
+at any time from the server's *Clients on LAN* tab. There is no dependency
+on Windows RDP or any Microsoft-based authentication.
+
+## Requirements
+
+- Windows
+- Python 3.14+
+
+## How discovery works
+
+The client broadcasts a small JSON probe over UDP (port 48653); each server
+on the LAN replies with its hostname and connection port. Windows Firewall
+must allow Python to receive inbound UDP on that port for a server to be
+discoverable from other machines.
+
+## Development
+
+```
+uv sync          # set up the environment
+uv run pytest    # run the tests
+```
+
+Run the tests from PowerShell or cmd, not Git Bash: Git Bash puts Git's
+MinGW OpenSSL DLLs on `PATH`, which Qt's TLS backend loads and crashes on.
+From PowerShell, Qt uses the Windows schannel backend as intended.
+
+The demo GIFs above are generated — entirely from synthetic data — by
+`uv run python tools/make_demo_gifs.py`.
+
+### The `badges` branch
+
+The coverage badge above is served from the `badges` branch
+(`raw.githubusercontent.com/.../badges/coverage.svg`). CI regenerates the
+SVG after each test run on `master` and force-pushes it there as a single
+orphan commit. It lives on its own branch because `master` only accepts
+pull requests (a repository ruleset), so CI cannot commit to it directly;
+keeping the badge in the repo avoids depending on an external coverage
+service. The branch is generated output — never branch from it or merge it.

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/pyproject.toml

@@ -1,46 +1,47 @@
-[project]
-name = "remotedesktop"
-dynamic = ["version"]
-description = "Remote desktop client/server for Windows computers on the same LAN, with autodiscovery. Provides screen, keyboard, mouse, and clipboard sharing without RDP or Microsoft authentication."
-readme = "readme.md"
-license = "MIT"
-authors = [{ name = "James Abel", email = "j@abel.co" }]
-requires-python = ">=3.14"
-classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
-    "Environment :: Win32 (MS Windows)",
-    "Intended Audience :: End Users/Desktop",
-    "Operating System :: Microsoft :: Windows",
-    "Programming Language :: Python :: 3",
-    "Topic :: System :: Networking",
-]
-dependencies = [
-    "cryptography>=49.0.0",
-    "platformdirs>=4.10.0",
-    "pyside6>=6.11.1",
-]
-
-[project.gui-scripts]
-remotedesktop-client = "remotedesktop.client:main"
-remotedesktop-server = "remotedesktop.server:main"
-
-[dependency-groups]
-dev = [
-    "pytest>=8",
-    "pytest-cov>=7.1.0",
-]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.version]
-path = "src/remotedesktop/__init__.py"
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-
-[tool.ty.environment]
-# The app targets Windows (SendInput via ctypes.windll); type-check as such
-# even when ty runs on a Linux CI runner.
-python-platform = "win32"
+[project]
+name = "remotedesktop"
+dynamic = ["version"]
+description = "Remote desktop client/server for Windows computers on the same LAN, with autodiscovery. Provides screen, keyboard, mouse, and clipboard sharing without RDP or Microsoft authentication."
+readme = "readme.md"
+license = "MIT"
+authors = [{ name = "James Abel", email = "j@abel.co" }]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "cryptography>=49.0.0",
+    "platformdirs>=4.10.0",
+    "pyside6>=6.11.1",
+]
+
+[project.gui-scripts]
+remotedesktop-client = "remotedesktop.client:main"
+remotedesktop-server = "remotedesktop.server:main"
+
+[dependency-groups]
+dev = [
+    "pillow>=12.3.0",
+    "pytest>=8",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/remotedesktop/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+# The app targets Windows (SendInput via ctypes.windll); type-check as such
+# even when ty runs on a Linux CI runner.
+python-platform = "win32"

remotedesktop-0.18.0/readme.md

@@ -0,0 +1,129 @@
+# Remote Desktop
+
+[![CI](https://github.com/jamesabel/remotedesktop/actions/workflows/ci.yml/badge.svg)](https://github.com/jamesabel/remotedesktop/actions/workflows/ci.yml)
+![Coverage](https://raw.githubusercontent.com/jamesabel/remotedesktop/badges/coverage.svg)
+[![PyPI](https://img.shields.io/pypi/v/remotedesktop)](https://pypi.org/project/remotedesktop/)
+![Python](https://img.shields.io/badge/python-3.14%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Lossless, low-latency remote desktop for Windows computers on your LAN — pure Python, zero configuration.**
+
+Run the server on the computer you want to reach and the client anywhere else
+on the network: the server is discovered automatically, the first connection
+is approved with one click on the server side, and from then on the client
+reconnects instantly whenever the server is running. The screen stream is
+pixel-exact at full resolution — built for documents, code, and terminals
+rather than video — captured with DXGI desktop duplication and delta-compressed
+so only the parts of the screen that changed are sent. No Windows RDP, no
+Microsoft accounts, no cloud: just two apps and your LAN.
+
+## See it in action
+
+### Client
+
+![Client demo](https://raw.githubusercontent.com/jamesabel/remotedesktop/master/docs/media/client-demo.gif)
+
+The client discovers the server on the LAN, connects, and streams its
+desktop live in the *Remote Screen* tab — click into the view and your mouse
+and keyboard control the remote machine. The *Performance* tab graphs
+bandwidth and round-trip time with live statistics.
+
+### Server
+
+![Server demo](https://raw.githubusercontent.com/jamesabel/remotedesktop/master/docs/media/server-demo.gif)
+
+The server's *Status* tab shows every connected viewer — who they are (login
+name, computer, OS) and how the connection is doing (bandwidth, round-trip
+time with mean/min/max/p99/jitter over the recent window).
+
+## Features
+
+- 🔍 **Autodiscovery** — servers announce themselves over UDP; the client lists every server on the LAN, no addresses to type.
+- 🖥️ **Lossless screen sharing** — pixel-exact at full resolution, DXGI desktop-duplication capture (~10 ms per 4K frame), and inter-frame delta compression: an unchanged screen sends nothing.
+- ⌨️🖱️ **Full input control** — mouse, wheel, and keyboard forwarding that is safe against interruptions: anything still held down is released on the server if the viewer loses focus or disconnects, so no stuck keys.
+- 📋 **Two-way clipboard** — text and images copied on either machine appear on the other.
+- 🔒 **TLS + approve-once pairing** — every connection is encrypted; the server user approves a new client once, after which it reconnects with a stored token and no prompt.
+- 📊 **Built-in performance monitoring** — live bandwidth and round-trip-time graphs with window statistics (mean/min/max/p99/jitter), plus a per-viewer table on the server.
+- 🔁 **Robust connections** — dead connections are detected and dropped within seconds, and approved clients reconnect automatically without ceremony.
+- 🚀 **Hands-off operation** — optional start-at-login (per-user, no admin rights) and a *Restart server* button usable from the remote session itself, so you can update the software without visiting the machine.
+- 🗃️ **Persistent peer inventory** — both apps keep a SQLite-backed history of every peer seen on the LAN, with one-click *revoke access* / *forget server*.
+
+In scope: screen, keyboard, mouse, and clipboard. Out of scope: shared
+drives, devices, and audio — and smooth playback of fast-changing
+full-screen content (video, games) is a non-goal; the stream is optimized
+for mostly-static desktop work.
+
+## Installation
+
+```
+pip install remotedesktop
+```
+
+or, with [uv](https://docs.astral.sh/uv/):
+
+```
+uv tool install remotedesktop
+```
+
+Or run straight from a clone of this repository: double-click
+`run_server.bat` on the computer to be shared and `run_client.bat` on the
+viewing computer — each prepares the environment on first use and launches
+the app.
+
+## Quick start
+
+1. On the computer to share, run `remotedesktop-server`.
+2. On the viewing computer, run `remotedesktop-client` — the server appears
+   in its *Servers* panel; double-click it.
+3. Approve the connection in the dialog that pops up on the server. That's
+   it — future connections from that client need no approval.
+
+From a terminal in a clone of this repo, the same apps run with
+`uv run remotedesktop-server` and `uv run remotedesktop-client`.
+
+## Security model
+
+Connections are TLS-encrypted with a self-signed certificate the server
+generates once and keeps. The trust model is tuned for a **trusted LAN**:
+certificates are trusted on first use and a changed fingerprint is logged
+rather than blocking the connection, favoring reliable reconnection over
+strict certificate checking. Unapproved clients are limited to small
+handshake messages until the server user admits them; access can be revoked
+at any time from the server's *Clients on LAN* tab. There is no dependency
+on Windows RDP or any Microsoft-based authentication.
+
+## Requirements
+
+- Windows
+- Python 3.14+
+
+## How discovery works
+
+The client broadcasts a small JSON probe over UDP (port 48653); each server
+on the LAN replies with its hostname and connection port. Windows Firewall
+must allow Python to receive inbound UDP on that port for a server to be
+discoverable from other machines.
+
+## Development
+
+```
+uv sync          # set up the environment
+uv run pytest    # run the tests
+```
+
+Run the tests from PowerShell or cmd, not Git Bash: Git Bash puts Git's
+MinGW OpenSSL DLLs on `PATH`, which Qt's TLS backend loads and crashes on.
+From PowerShell, Qt uses the Windows schannel backend as intended.
+
+The demo GIFs above are generated — entirely from synthetic data — by
+`uv run python tools/make_demo_gifs.py`.
+
+### The `badges` branch
+
+The coverage badge above is served from the `badges` branch
+(`raw.githubusercontent.com/.../badges/coverage.svg`). CI regenerates the
+SVG after each test run on `master` and force-pushes it there as a single
+orphan commit. It lives on its own branch because `master` only accepts
+pull requests (a repository ruleset), so CI cannot commit to it directly;
+keeping the badge in the repo avoids depending on an external coverage
+service. The branch is generated output — never branch from it or merge it.

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/src/remotedesktop/__init__.py

@@ -1,3 +1,3 @@
 """Remote desktop client/server for Windows computers on the same LAN."""
 
-__version__ = "0.16.0"
+__version__ = "0.18.0"

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/src/remotedesktop/modal_loop.py

@@ -17,9 +17,18 @@ callback pumps Qt events (user input excluded) every few milliseconds. A
 side benefit: screen sharing keeps streaming while the local user drags
 the server window.
 
+The caption buttons (minimize/maximize/close) are the exception: their
+tracking loop dispatches only mouse messages, so no timer — and therefore
+no pump — can run inside it, and a remote click on the server's own
+minimize button deadlocked just like the title-bar drag once did. Those
+presses are instead handled here directly (`caption_action` callback) and
+the message is consumed, so DefWindowProc's button tracking never starts:
+the action happens on press, for local and remote clicks alike.
+
 Feed every message from the window's `nativeEvent` to
-`handle_native_event`; the pump is inert off Windows. Tests inject a fake
-`timers` backend so no native timer is ever created.
+`handle_native_event` and consume the message when it returns True; the
+pump is inert off Windows. Tests inject a fake `timers` backend so no
+native timer is ever created.
 """
 
 import ctypes
@@ -33,9 +42,15 @@ from PySide6.QtCore import QCoreApplication, QEventLoop
 _log = logging.getLogger("remotedesktop.modal_loop")
 
 WM_NCLBUTTONDOWN = 0x00A1
+WM_NCLBUTTONUP = 0x00A2
 WM_CAPTURECHANGED = 0x0215
 WM_ENTERSIZEMOVE = 0x0231
 WM_EXITSIZEMOVE = 0x0232
+# WM_NCLBUTTONDOWN/-UP hit-test codes for the caption buttons.
+HTMINBUTTON = 8
+HTMAXBUTTON = 9
+HTCLOSE = 20
+_CAPTION_BUTTONS = (HTMINBUTTON, HTMAXBUTTON, HTCLOSE)
 _TIMER_ID = 0x5244  # arbitrary but stable; scoped to the window's hwnd
 _TIMER_INTERVAL_MS = 15  # comfortably under the 33 ms capture tick
 
@@ -65,21 +80,49 @@ class _NativeTimers:
 
 class ModalLoopPump:
     """Runs a native timer that pumps Qt events while a window of ours sits
-    in the modal move/size loop."""
-
-    def __init__(self, *, pump: Callable[[], None] | None = None, timers=None) -> None:
+    in the modal move/size loop, and short-circuits caption-button clicks
+    (whose tracking loop the timer cannot penetrate) to `caption_action`."""
+
+    def __init__(
+        self,
+        *,
+        pump: Callable[[], None] | None = None,
+        caption_action: Callable[[int], None] | None = None,
+        timers=None,
+    ) -> None:
         self._pump = pump if pump is not None else _pump_qt
+        self._caption_action = caption_action
         if timers is None and sys.platform == "win32":
             timers = _NativeTimers(self._on_timer)
         self._timers = timers  # None: inert (non-Windows)
         self._hwnd: int | None = None
         self._pumping = False
 
-    def handle_native_event(self, event_type, message) -> None:
-        """Call from QWidget.nativeEvent with its arguments verbatim."""
+    def handle_native_event(self, event_type, message) -> bool:
+        """Call from QWidget.nativeEvent with its arguments verbatim.
+
+        Returns True when the message was handled here and must be consumed
+        (returned True from nativeEvent) instead of reaching DefWindowProc.
+        """
         if self._timers is None or bytes(event_type) != b"windows_generic_MSG":
-            return
+            return False
         msg = wintypes.MSG.from_address(int(message))
+        # Minimize/maximize/close presses must never reach DefWindowProc:
+        # its caption-button tracking loop dispatches only mouse messages,
+        # so no timer can pump Qt inside it, and a remote press deadlocks
+        # exactly like the title-bar drag once did. Perform the action on
+        # press and swallow the message (the matching -UP too).
+        if (
+            self._caption_action is not None
+            and msg.message in (WM_NCLBUTTONDOWN, WM_NCLBUTTONUP)
+            and msg.wParam in _CAPTION_BUTTONS
+        ):
+            if msg.message == WM_NCLBUTTONDOWN:
+                _log.debug(
+                    "Caption button %d pressed — handled without native tracking", msg.wParam
+                )
+                self._caption_action(int(msg.wParam))
+            return True
         # WM_ENTERSIZEMOVE alone is not enough: a press-and-hold on the title
         # bar that never moves blocks the thread inside DefWindowProc's click
         # tracking WITHOUT ever sending WM_ENTERSIZEMOVE, so the pump must
@@ -90,6 +133,7 @@ class ModalLoopPump:
             self._enter(msg.hWnd or 0)
         elif msg.message in (WM_CAPTURECHANGED, WM_EXITSIZEMOVE):
             self._exit()
+        return False
 
     def _enter(self, hwnd: int) -> None:
         if self._hwnd == hwnd:  # NCLBUTTONDOWN then ENTERSIZEMOVE: already armed

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/src/remotedesktop/server.py

@@ -7,7 +7,7 @@ import sqlite3
 import sys
 import time
 
-from PySide6.QtCore import QProcess, Qt
+from PySide6.QtCore import QProcess, Qt, QTimer
 from PySide6.QtGui import QCloseEvent, QShowEvent
 from PySide6.QtWidgets import (
     QAbstractItemView,
@@ -37,7 +37,7 @@ from remotedesktop.discovery import (
 )
 from remotedesktop.inventory import ConnectionInventory, InventoryTab
 from remotedesktop.logs import PeerLogDialog, read_log_tail
-from remotedesktop.modal_loop import ModalLoopPump
+from remotedesktop.modal_loop import HTCLOSE, HTMAXBUTTON, HTMINBUTTON, ModalLoopPump
 from remotedesktop.performance import PerformanceMonitor, PerformanceTab, format_ms, format_rate
 from remotedesktop.preferences import PreferencesTab, load_performance_window_seconds
 from remotedesktop.sharing import ShareServer
@@ -167,7 +167,9 @@ class ServerWindow(QMainWindow):
         # drag — including one driven by an injected remote click), Qt stops
         # running; the pump keeps sockets and timers serviced so a remote
         # mouse-up can still arrive and end the drag instead of deadlocking.
-        self._modal_pump = ModalLoopPump()
+        # Caption-button presses (minimize/maximize/close) are handled by
+        # the pump directly — their native tracking loop cannot be pumped.
+        self._modal_pump = ModalLoopPump(caption_action=self._on_caption_button)
         self.restart_button = QPushButton("Restart server")
         self.restart_button.setToolTip(
             "Relaunch this app (e.g. after updating the software). It can be "
@@ -339,8 +341,22 @@ class ServerWindow(QMainWindow):
         title = f'Log from client "{client_name}"' if client_name else "Log from client"
         PeerLogDialog(title, text, self).show()
 
+    def _on_caption_button(self, hit_code: int) -> None:
+        # Deferred: the action (especially close) must not run inside the
+        # native message handler that reported the press.
+        if hit_code == HTMINBUTTON:
+            action = self.showMinimized
+        elif hit_code == HTMAXBUTTON:
+            action = self.showNormal if self.isMaximized() else self.showMaximized
+        elif hit_code == HTCLOSE:
+            action = self.close
+        else:
+            return
+        QTimer.singleShot(0, action)
+
     def nativeEvent(self, event_type, message):
-        self._modal_pump.handle_native_event(event_type, message)
+        if self._modal_pump.handle_native_event(event_type, message):
+            return True, 0
         return super().nativeEvent(event_type, message)
 
     def _ask_approval(self, client_id: str, client_name: str) -> bool:

{remotedesktop-0.16.0 → remotedesktop-0.18.0}/tests/test_modal_loop.py

@@ -8,10 +8,13 @@ import ctypes
 from ctypes import wintypes
 
 from remotedesktop.modal_loop import (
+    HTMAXBUTTON,
+    HTMINBUTTON,
     WM_CAPTURECHANGED,
     WM_ENTERSIZEMOVE,
     WM_EXITSIZEMOVE,
     WM_NCLBUTTONDOWN,
+    WM_NCLBUTTONUP,
     ModalLoopPump,
 )
 
@@ -27,14 +30,19 @@ class FakeTimers:
         self.calls.append(("stop", hwnd))
 
 
-def native_message(message_id, hwnd=0xBEEF):
+def native_message(message_id, hwnd=0xBEEF, wparam=0):
     """A wintypes.MSG whose address stands in for Qt's nativeEvent pointer."""
     msg = wintypes.MSG()
     msg.hWnd = hwnd
     msg.message = message_id
+    msg.wParam = wparam
     return msg
 
 
+def send(pump, msg):
+    return pump.handle_native_event(b"windows_generic_MSG", ctypes.addressof(msg))
+
+
 def test_enter_and_exit_bound_the_timer():
     timers = FakeTimers()
     pump = ModalLoopPump(pump=lambda: None, timers=timers)
@@ -102,6 +110,42 @@ def test_capture_change_without_press_is_ignored():
     assert timers.calls == []
 
 
+def test_caption_button_press_is_consumed_and_dispatched():
+    # Min/max/close tracking cannot be pumped (it dispatches only mouse
+    # messages), so the press must be handled directly and swallowed —
+    # the native tracking loop must never start.
+    timers = FakeTimers()
+    actions = []
+    pump = ModalLoopPump(pump=lambda: None, caption_action=actions.append, timers=timers)
+    assert send(pump, native_message(WM_NCLBUTTONDOWN, wparam=HTMINBUTTON)) is True
+    assert actions == [HTMINBUTTON]
+    assert timers.calls == []  # no tracking, so nothing to pump
+    assert send(pump, native_message(WM_NCLBUTTONUP, wparam=HTMINBUTTON)) is True
+    assert actions == [HTMINBUTTON]  # the release performs nothing extra
+    assert send(pump, native_message(WM_NCLBUTTONDOWN, wparam=HTMAXBUTTON)) is True
+    assert actions == [HTMINBUTTON, HTMAXBUTTON]
+
+
+def test_title_bar_press_still_arms_the_pump_not_the_caption_action():
+    timers = FakeTimers()
+    actions = []
+    pump = ModalLoopPump(pump=lambda: None, caption_action=actions.append, timers=timers)
+    # HTCAPTION (2): a title-bar press is not a caption button — the pump
+    # arms as before and the message passes through to DefWindowProc.
+    assert send(pump, native_message(WM_NCLBUTTONDOWN, wparam=2)) is False
+    assert actions == []
+    assert timers.calls == [("start", 0xBEEF)]
+
+
+def test_caption_buttons_pass_through_without_a_caption_action():
+    timers = FakeTimers()
+    pump = ModalLoopPump(pump=lambda: None, timers=timers)
+    # No handler installed: behave exactly as before (arm the pump, don't
+    # consume) so the buttons keep working for pump users without one.
+    assert send(pump, native_message(WM_NCLBUTTONDOWN, wparam=HTMINBUTTON)) is False
+    assert timers.calls == [("start", 0xBEEF)]
+
+
 def test_timer_callback_pumps_but_never_reentrantly():
     pumped = []
     pump = ModalLoopPump(pump=lambda: pumped.append(True) or pump._on_timer(), timers=FakeTimers())