remotedesktop 0.19.0__tar.gz → 0.20.0__tar.gz

{remotedesktop-0.19.0 → remotedesktop-0.20.0}/CLAUDE.md

@@ -36,7 +36,7 @@ Managed with `uv` (hatchling build backend, src layout):
 ## Architecture
 
 - Both apps are PySide6 GUI applications. `src/remotedesktop/client.py` (`ClientWindow`) and `src/remotedesktop/server.py` (`ServerWindow`) hold the app entry points; `main()` in each is wired to the `remotedesktop-client` / `remotedesktop-server` GUI scripts in `pyproject.toml`.
-- The client-side remote desktop view is a widget, `ViewerWidget` in `src/remotedesktop/viewer.py`, hosted as `ClientWindow`'s central widget. Screen display and keyboard/mouse/clipboard forwarding belong in this widget, not in the window.
+- The client-side remote desktop view is a widget, `ViewerWidget` in `src/remotedesktop/viewer.py`. Screen display and keyboard/mouse/clipboard forwarding belong in this widget, not in the window. **The client supports multiple simultaneous server connections**: each is a `ServerSession` in `client.py` (its own `ShareClient` + `ViewerWidget`), shown as a closable tab at the front of `ClientWindow`'s central `QTabWidget`, titled with the server's reported hostname (fixed tabs get their close buttons stripped). Sessions are keyed by `host:port`; activating an already-known server reconnects in its existing tab, activating a connected one just focuses it. The window title lists the connected server names (`_update_window_title`), and the status bar follows the currently selected session tab (`status_text` per session). The `PerformanceMonitor`, `ClipboardSync`, inventory, and Connection log are shared across sessions — the monitor aggregates all attached streams, and `performance.reset()` is only called when no *other* session is connected (resetting detaches every stream). Per-session status log lines are prefixed `[name]`.
 - **Autodiscovery** (`src/remotedesktop/discovery.py`) is a stdlib-only UDP probe/response protocol, deliberately not mDNS: the client broadcasts a JSON probe to `DISCOVERY_PORT` (48653) and servers reply with `{name, port}`; datagrams with the wrong magic/version/type are dropped. The server runs a `DiscoveryResponder` thread while its window is open; the client's `DiscoveryPanel` (dock in `ClientWindow`) calls the blocking `discover_servers()` on a worker thread and delivers results to the GUI via a queued signal. `DEFAULT_CONNECT_PORT` (48654) is reserved for the future desktop connection.
 - Discovery tests run over loopback with ephemeral ports (`bind_host`/`discovery_port`/`broadcast_hosts` parameters exist for this), so they never touch the real LAN or fixed ports.
 - **Screen sharing** (`sharing.py` + `protocol.py` + `frames.py`) runs entirely on the Qt event loop — no threads or locks. `MessageStream` frames messages over a QTcpSocket (4-byte length + kind byte; JSON control messages, full frames, or inter-frame deltas; malformed input aborts the socket). `ShareServer` owns one QTimer that grabs the primary screen at full resolution via `_capture()` (a seam tests override to drive deterministic frame content) and fans out to all clients, skipping clients whose send buffer is backlogged; the timer only runs while clients are connected. Capture is DXGI desktop duplication (`dxgi.py`, hand-rolled ctypes COM — ~10 ms per changed 4K frame, ~0 when idle, and "unchanged" is signalled by returning the same QImage object so the diff is skipped) with automatic fallback to `QScreen.grabWindow` (~96 ms) whenever duplication is unavailable or lost (secure desktop, RDP, display-mode change, CI); unit tests fake the duplication (`FakeDuplication` in `tests/test_dxgi.py`) and the real-hardware test skips where DXGI is unavailable. **Frame transfer is lossless and inter-frame compressed** (`frames.py`): consecutive captures are diffed in 64-row bands (memoryview compares), and only changed bands ship as PNG in a delta payload the client patches onto its previous frame; an unchanged screen sends nothing. Full PNG keyframes go to clients that just joined, just recovered from a send backlog, or requested one (a `{"type": "keyframe"}` message — sent when a delta fails to apply, so desync self-heals). The capability is negotiated via `"delta": true` in the client hello; clients without it (0.5.0) get full JPEG frames every tick because they force-decode frames as JPEG — never send them PNG. Each variant (legacy JPEG / keyframe PNG / delta) is encoded at most once per tick and shared across clients. `ShareClient` decodes/patches to QImage for the viewer, which displays it scaled with a cached `SmoothTransformation` copy (full resolution is always delivered; scaling happens client-side only).

{remotedesktop-0.19.0 → remotedesktop-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remotedesktop
-Version: 0.19.0
+Version: 0.20.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.
 Project-URL: Homepage, https://github.com/jamesabel/remotedesktop
 Project-URL: Repository, https://github.com/jamesabel/remotedesktop
@@ -47,9 +47,11 @@ Microsoft accounts, no cloud: just two apps and your LAN.
 ![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.
+desktop live in a tab named after that computer — click into the view and
+your mouse and keyboard control the remote machine. Connect to several
+servers at once and each gets its own tab; the window title lists every
+connected computer. The *Performance* tab graphs bandwidth and round-trip
+time with live statistics.
 
 ### Server
 
@@ -62,6 +64,7 @@ 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.
+- 🗂️ **Multiple servers at once** — one client can view and control several servers simultaneously, each in its own tab named for that computer; the window title shows who you're connected to, even minimized.
 - 🖥️ **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.
@@ -115,6 +118,60 @@ 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.
 
+## How it works
+
+All of this is pure Python — the GUIs are PySide6 (Qt), and the two places
+that need to talk to Windows directly (screen capture and input injection)
+call the Win32/COM APIs through `ctypes`, so there are no native extensions
+to compile.
+
+**Screen capture.** The server grabs the desktop with the **DXGI desktop
+duplication API**, driven directly through `ctypes` COM calls. Desktop
+duplication is the mechanism Windows provides for exactly this job: the
+compositor hands over a GPU texture of the screen and tells you whether
+anything changed, so a changed 4K frame costs about 10 ms to read back and
+an idle screen costs essentially nothing. When duplication is unavailable
+or gets lost — the secure desktop (UAC/logon screen), an RDP session, a
+display-mode change — the server transparently falls back to Qt's
+`QScreen.grabWindow` (~96 ms per frame) and keeps retrying duplication in
+the background.
+
+**Screen transfer.** Frames are captured at up to 30 fps and compared with
+the previous capture in 64-row bands; only the bands that changed are
+encoded — losslessly, as PNG — and sent as a delta the client patches onto
+its last frame. An unchanged screen sends nothing at all. Full PNG
+keyframes go to clients that just connected, fell behind (a client whose
+socket backlog grows gets frames dropped, then a fresh keyframe once it
+catches up), or asked for one because a delta failed to apply — so a
+desynced stream heals itself. The frame always travels at the server's
+full resolution; scaling to the viewer window happens on the client.
+
+**Input injection.** The client's viewer widget captures your mouse and
+keyboard events, maps mouse positions to coordinates normalized 0..1 over
+the displayed frame (so window size and letterboxing don't matter), and
+sends them as small JSON messages. The server injects them with the Win32
+**`SendInput`** API: normalized coordinates map onto SendInput's 0..65535
+absolute coordinate space over the primary monitor, and keystrokes carry
+the client's native virtual-key codes, which are injected as-is — both
+ends are Windows, so no key translation is needed. The server only injects
+input from clients that have passed the approval handshake, and anything
+still held down (a dragged button, a modifier key) is released
+automatically if the viewer disconnects or loses focus.
+
+**Clipboard.** Both sides watch their local clipboard via Qt and forward
+copies (text, or images as PNG) over the same connection. Echo loops are
+prevented by content signature — an image is hashed by its canonical
+pixels, so a PNG that makes a round trip through the OS clipboard and
+comes back re-encoded is still recognized and not sent again.
+
+**Transport.** Each client talks to the server over a single TCP
+connection: TLS via the Windows schannel backend with a self-signed
+certificate the server generates and keeps, then simple length-prefixed
+messages on top — JSON for control (hello/welcome, input, clipboard,
+ping/pong for the round-trip-time graphs, log exchange) and binary
+payloads for frames and deltas. Discovery is a UDP broadcast probe that
+every server answers with its name and port (see below).
+
 ## Versioning
 
 The apps follow [semantic versioning](https://semver.org): the **major**

{remotedesktop-0.19.0 → remotedesktop-0.20.0}/readme.md

@@ -24,9 +24,11 @@ Microsoft accounts, no cloud: just two apps and your LAN.
 ![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.
+desktop live in a tab named after that computer — click into the view and
+your mouse and keyboard control the remote machine. Connect to several
+servers at once and each gets its own tab; the window title lists every
+connected computer. The *Performance* tab graphs bandwidth and round-trip
+time with live statistics.
 
 ### Server
 
@@ -39,6 +41,7 @@ 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.
+- 🗂️ **Multiple servers at once** — one client can view and control several servers simultaneously, each in its own tab named for that computer; the window title shows who you're connected to, even minimized.
 - 🖥️ **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.
@@ -92,6 +95,60 @@ 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.
 
+## How it works
+
+All of this is pure Python — the GUIs are PySide6 (Qt), and the two places
+that need to talk to Windows directly (screen capture and input injection)
+call the Win32/COM APIs through `ctypes`, so there are no native extensions
+to compile.
+
+**Screen capture.** The server grabs the desktop with the **DXGI desktop
+duplication API**, driven directly through `ctypes` COM calls. Desktop
+duplication is the mechanism Windows provides for exactly this job: the
+compositor hands over a GPU texture of the screen and tells you whether
+anything changed, so a changed 4K frame costs about 10 ms to read back and
+an idle screen costs essentially nothing. When duplication is unavailable
+or gets lost — the secure desktop (UAC/logon screen), an RDP session, a
+display-mode change — the server transparently falls back to Qt's
+`QScreen.grabWindow` (~96 ms per frame) and keeps retrying duplication in
+the background.
+
+**Screen transfer.** Frames are captured at up to 30 fps and compared with
+the previous capture in 64-row bands; only the bands that changed are
+encoded — losslessly, as PNG — and sent as a delta the client patches onto
+its last frame. An unchanged screen sends nothing at all. Full PNG
+keyframes go to clients that just connected, fell behind (a client whose
+socket backlog grows gets frames dropped, then a fresh keyframe once it
+catches up), or asked for one because a delta failed to apply — so a
+desynced stream heals itself. The frame always travels at the server's
+full resolution; scaling to the viewer window happens on the client.
+
+**Input injection.** The client's viewer widget captures your mouse and
+keyboard events, maps mouse positions to coordinates normalized 0..1 over
+the displayed frame (so window size and letterboxing don't matter), and
+sends them as small JSON messages. The server injects them with the Win32
+**`SendInput`** API: normalized coordinates map onto SendInput's 0..65535
+absolute coordinate space over the primary monitor, and keystrokes carry
+the client's native virtual-key codes, which are injected as-is — both
+ends are Windows, so no key translation is needed. The server only injects
+input from clients that have passed the approval handshake, and anything
+still held down (a dragged button, a modifier key) is released
+automatically if the viewer disconnects or loses focus.
+
+**Clipboard.** Both sides watch their local clipboard via Qt and forward
+copies (text, or images as PNG) over the same connection. Echo loops are
+prevented by content signature — an image is hashed by its canonical
+pixels, so a PNG that makes a round trip through the OS clipboard and
+comes back re-encoded is still recognized and not sent again.
+
+**Transport.** Each client talks to the server over a single TCP
+connection: TLS via the Windows schannel backend with a self-signed
+certificate the server generates and keeps, then simple length-prefixed
+messages on top — JSON for control (hello/welcome, input, clipboard,
+ping/pong for the round-trip-time graphs, log exchange) and binary
+payloads for frames and deltas. Discovery is a UDP broadcast probe that
+every server answers with its name and port (see below).
+
 ## Versioning
 
 The apps follow [semantic versioning](https://semver.org): the **major**

{remotedesktop-0.19.0 → remotedesktop-0.20.0}/src/remotedesktop/__init__.py

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

remotedesktop-0.20.0/src/remotedesktop/client.py

@@ -0,0 +1,452 @@
+"""Client GUI application: discovers servers on the LAN, connects to one or
+more of them, and shows each server's desktop in its own viewer tab."""
+
+import logging
+import sqlite3
+import sys
+import threading
+import time
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import QCloseEvent
+from PySide6.QtWidgets import (
+    QApplication,
+    QDockWidget,
+    QListWidget,
+    QListWidgetItem,
+    QMainWindow,
+    QMessageBox,
+    QPlainTextEdit,
+    QPushButton,
+    QTabBar,
+    QTabWidget,
+    QVBoxLayout,
+    QWidget,
+)
+
+from remotedesktop import __version__, compat, db, icon, logs, window_state
+from remotedesktop.about import AboutTab
+from remotedesktop.logs import PeerLogDialog, read_log_tail
+from remotedesktop.clipboard import ClipboardSync
+from remotedesktop.config import KnownServers, Settings, default_db_path, load_client_identity
+from remotedesktop.discovery import DISCOVERY_PORT, ServerInfo, discover_servers
+from remotedesktop.inventory import ConnectionInventory, InventoryTab
+from remotedesktop.performance import PerformanceMonitor, PerformanceTab
+from remotedesktop.preferences import PreferencesTab, load_performance_window_seconds
+from remotedesktop.sharing import ShareClient
+from remotedesktop.viewer import ViewerWidget
+
+_log = logging.getLogger("remotedesktop.client")
+
+
+class DiscoveryPanel(QWidget):
+    """Scans the LAN for servers and lists them for the user to pick."""
+
+    serverActivated = Signal(ServerInfo)
+    serversFound = Signal(list)
+    status = Signal(str)
+    _scanFinished = Signal(list)
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self._refresh_button = QPushButton("Refresh")
+        self.server_list = QListWidget()
+        layout = QVBoxLayout(self)
+        layout.addWidget(self._refresh_button)
+        layout.addWidget(self.server_list)
+        self._refresh_button.clicked.connect(self.refresh)
+        self.server_list.itemActivated.connect(self._on_item_activated)
+        self._scanFinished.connect(self._show_results)
+
+    def refresh(self) -> None:
+        self._refresh_button.setEnabled(False)
+        self._refresh_button.setText("Scanning…")
+        self.status.emit(f"Scanning LAN (UDP broadcast to port {DISCOVERY_PORT}) …")
+        threading.Thread(target=self._scan, name="discovery-scan", daemon=True).start()
+
+    def _scan(self) -> None:
+        # Runs on a worker thread; the signal is delivered queued on the GUI
+        # thread. Any failure must still emit, or the button stays disabled.
+        servers: list[ServerInfo] = []
+        try:
+            servers = discover_servers()
+        except Exception:
+            pass
+        self._scanFinished.emit(servers)
+
+    def _show_results(self, servers: list) -> None:
+        self._refresh_button.setEnabled(True)
+        self._refresh_button.setText("Refresh")
+        self.server_list.clear()
+        for server in servers:
+            item = QListWidgetItem(f"{server.name} ({server.host}:{server.port})")
+            item.setData(Qt.ItemDataRole.UserRole, server)
+            self.server_list.addItem(item)
+        self.serversFound.emit(servers)
+        found = ", ".join(f"{s.name} at {s.host}:{s.port}" for s in servers)
+        self.status.emit(f"Scan finished — found: {found}" if servers else "Scan finished — no servers found")
+
+    def _on_item_activated(self, item: QListWidgetItem) -> None:
+        self.serverActivated.emit(item.data(Qt.ItemDataRole.UserRole))
+
+
+class ServerSession:
+    """One server connection: its ShareClient, the viewer tab that displays
+    it, and the per-connection state the window tracks for it. The session
+    (and its tab) outlives a disconnect, so the user can reconnect in place;
+    closing the tab ends the session."""
+
+    def __init__(self, key: str, name: str, client: ShareClient, viewer: ViewerWidget) -> None:
+        self.key = key  # "host:port", the KnownServers/inventory key
+        self.name = name
+        self.client = client
+        self.viewer = viewer
+        self.connected = False
+        self.denied = False
+        self.version_mismatch = False
+        self.frame_count = 0
+        # What the status bar shows while this session's tab is current.
+        self.status_text = ""
+
+
+class ClientWindow(QMainWindow):
+    def __init__(
+        self, *, connection: sqlite3.Connection | None = None, auto_scan: bool = True
+    ) -> None:
+        super().__init__()
+        self.setWindowIcon(icon.app_icon("client"))
+        # Tests inject a connection to a temp database; the app uses the default.
+        self._db = connection if connection is not None else db.connect(default_db_path())
+        self._settings = Settings(self._db)
+        self.performance = PerformanceMonitor(
+            window_seconds=float(load_performance_window_seconds(self._settings)),
+            parent=self,
+        )
+        self.inventory = ConnectionInventory(self._db, "client_peers", self)
+        # One tab per server connection (inserted at the front, closable),
+        # followed by the fixed tabs, which never get a close button.
+        self._sessions: list[ServerSession] = []
+        self._tabs = QTabWidget()
+        self._tabs.setTabsClosable(True)
+        self._tabs.tabCloseRequested.connect(self._on_tab_close_requested)
+        self._tabs.currentChanged.connect(lambda _index: self._refresh_status_bar())
+        self._tabs.addTab(
+            InventoryTab(self.inventory, "Forget server", self._forget_server),
+            "Servers on LAN",
+        )
+        self._tabs.addTab(
+            PerformanceTab(self.performance, local="client", remote="server"),
+            "Performance",
+        )
+        self.setCentralWidget(self._tabs)
+
+        self.discovery_panel = DiscoveryPanel(self)
+        servers_dock = QDockWidget("Servers", self)
+        servers_dock.setWidget(self.discovery_panel)
+        self.addDockWidget(Qt.DockWidgetArea.LeftDockWidgetArea, servers_dock)
+
+        self.connection_log = QPlainTextEdit(self)
+        self.connection_log.setReadOnly(True)
+        self.connection_log.setMaximumBlockCount(1000)
+        self.get_log_button = QPushButton("Get server log")
+        self.get_log_button.setToolTip("Ask the connected server to send its debug log")
+        self.get_log_button.clicked.connect(self._request_server_log)
+        log_tab = QWidget()
+        log_layout = QVBoxLayout(log_tab)
+        log_layout.addWidget(self.get_log_button, alignment=Qt.AlignmentFlag.AlignLeft)
+        log_layout.addWidget(self.connection_log)
+        self._tabs.addTab(log_tab, "Connection log")
+        self._tabs.addTab(PreferencesTab(self._settings, self.performance), "Preferences")
+        self._tabs.addTab(AboutTab(), "About")
+        # Only session tabs are closable; strip the buttons the fixed tabs
+        # got from setTabsClosable (styles place them on either side).
+        bar = self._tabs.tabBar()
+        for index in range(self._tabs.count()):
+            for side in (QTabBar.ButtonPosition.LeftSide, QTabBar.ButtonPosition.RightSide):
+                bar.setTabButton(index, side, None)
+
+        self.discovery_panel.serverActivated.connect(self._on_server_activated)
+        self.discovery_panel.serversFound.connect(self._record_discovered)
+        self.discovery_panel.status.connect(self.log)
+
+        self._clipboard = ClipboardSync(parent=self)
+        self._known_servers = KnownServers(self._db)
+        self._identity = load_client_identity(self._db)
+        self._update_window_title()
+        self.statusBar().showMessage("Not connected")
+        window_state.restore_geometry(self, self._settings, window_state.CLIENT_GEOMETRY_KEY)
+        self.log("Client started")
+        # Tests pass auto_scan=False so window tests never broadcast on the LAN.
+        if auto_scan:
+            self.discovery_panel.refresh()
+
+    def log(self, message: str) -> None:
+        # Everything shown in the Connection log pane also goes to the debug
+        # log file (when main() enabled it), so it survives the window.
+        _log.info(message)
+        self.connection_log.appendPlainText(f"{time.strftime('%H:%M:%S')}  {message}")
+
+    def _update_window_title(self) -> None:
+        """Connected server names lead the title, so the taskbar (and a
+        minimized window) says who this client is viewing."""
+        names = [session.name for session in self._sessions if session.connected]
+        base = f"Remote Desktop Client {__version__}"
+        self.setWindowTitle(f"{', '.join(names)} — {base}" if names else base)
+
+    def _session_for_key(self, key: str) -> ServerSession | None:
+        for session in self._sessions:
+            if session.key == key:
+                return session
+        return None
+
+    def _session_for_viewer(self, widget) -> ServerSession | None:
+        for session in self._sessions:
+            if session.viewer is widget:
+                return session
+        return None
+
+    def _set_session_status(self, session: ServerSession, text: str) -> None:
+        session.status_text = text
+        if self._tabs.currentWidget() is session.viewer:
+            self.statusBar().showMessage(text)
+
+    def _refresh_status_bar(self) -> None:
+        session = self._session_for_viewer(self._tabs.currentWidget())
+        if session is not None:
+            self.statusBar().showMessage(session.status_text)
+            return
+        names = [s.name for s in self._sessions if s.connected]
+        self.statusBar().showMessage(
+            f"Connected to {', '.join(names)}" if names else "Not connected"
+        )
+
+    def _forget_server(self, key: str) -> None:
+        answer = QMessageBox.question(
+            self,
+            "Forget server",
+            f"Forget server {key}?\n\n"
+            "If connected it will be disconnected, and the next connection will "
+            "need the server user to approve this computer again.",
+        )
+        if answer != QMessageBox.StandardButton.Yes:
+            return
+        session = self._session_for_key(key)
+        if session is not None:
+            self._close_session(session)
+        self._known_servers.forget(key)
+        self.inventory.record(key, "forgotten")
+        self.log(f"Forgot server {key}")
+
+    def _record_discovered(self, servers: list) -> None:
+        for server in servers:
+            key = f"{server.host}:{server.port}"
+            session = self._session_for_key(key)
+            if session is not None and session.connected:
+                continue  # don't downgrade a connected server to "discovered"
+            self.inventory.record(
+                key, "discovered", name=server.name, address=key, detail=key
+            )
+
+    def _on_server_activated(self, server: ServerInfo) -> None:
+        key = f"{server.host}:{server.port}"
+        session = self._session_for_key(key)
+        if session is not None and session.connected:
+            self._tabs.setCurrentWidget(session.viewer)
+            self.log(f"Already connected to {session.name} ({key})")
+            return
+        if session is None:
+            session = self._create_session(key, server.name)
+        else:
+            session.name = server.name
+            self._tabs.setTabText(self._sessions.index(session), session.name)
+        self._connect_session(session, server.host, server.port)
+
+    def _create_session(self, key: str, name: str) -> ServerSession:
+        viewer = ViewerWidget()
+        client = ShareClient(
+            identity=self._identity,
+            known_servers=self._known_servers,
+            clipboard=self._clipboard,
+            performance=self.performance,
+            log_provider=lambda: read_log_tail("client"),
+            parent=self,
+        )
+        session = ServerSession(key, name, client, viewer)
+        viewer.inputEvent.connect(lambda event, s=session: self._on_input_event(s, event))
+        client.status.connect(lambda message, s=session: self.log(f"[{s.name}] {message}"))
+        client.connected.connect(lambda server_name, s=session: self._on_connected(s, server_name))
+        client.approvalPending.connect(lambda s=session: self._on_approval_pending(s))
+        client.denied.connect(lambda reason, s=session: self._on_denied(s, reason))
+        client.disconnected.connect(lambda s=session: self._on_disconnected(s))
+        client.frameReceived.connect(lambda image, s=session: self._on_frame(s, image))
+        client.logReceived.connect(lambda text, s=session: self._show_server_log(s.name, text))
+        self._sessions.append(session)
+        self._tabs.insertTab(len(self._sessions) - 1, viewer, session.name)
+        return session
+
+    def _connect_session(self, session: ServerSession, host: str, port: int) -> None:
+        session.frame_count = 0
+        session.connected = False
+        session.denied = False
+        session.version_mismatch = False
+        self.inventory.record(
+            session.key, "attempt", name=session.name,
+            address=session.key, detail=session.key,
+        )
+        # Graphs show only the current connection(s): clear them for a fresh
+        # start, but never while another session's stream is being sampled.
+        if not any(s.connected for s in self._sessions if s is not session):
+            self.performance.reset()
+        session.viewer.clear(f"Connecting to {session.name} …")
+        self._tabs.setCurrentWidget(session.viewer)
+        self._set_session_status(
+            session, f"Connecting to {session.name} ({session.key}) …"
+        )
+        session.client.connect_to(host, port)
+
+    def _close_session(self, session: ServerSession) -> None:
+        """Disconnect the session and remove its tab (tab close / forget)."""
+        session.client.close()  # a synchronous disconnect signal may fire here
+        index = self._sessions.index(session)
+        self._sessions.pop(index)
+        self._tabs.removeTab(index)
+        if session.connected and not session.denied:
+            self.inventory.record(session.key, "disconnected", name=session.name)
+        session.connected = False
+        session.client.deleteLater()
+        session.viewer.deleteLater()
+        self.log(f"Closed connection to {session.name} ({session.key})")
+        self._update_window_title()
+        self._refresh_status_bar()
+
+    def _on_tab_close_requested(self, index: int) -> None:
+        if index < len(self._sessions):  # fixed tabs carry no close button
+            self._close_session(self._sessions[index])
+
+    def _on_approval_pending(self, session: ServerSession) -> None:
+        if session not in self._sessions:
+            return
+        session.viewer.clear(
+            f"Waiting for approval — someone at {session.name} "
+            "must allow this connection"
+        )
+        self._set_session_status(
+            session,
+            f"Waiting for the user on {session.name} to approve this computer …",
+        )
+
+    def _server_label(self, session: ServerSession) -> str:
+        """The server's name with its app version when it reported one,
+        e.g. 'DEN-PC (0.19.0)' — flagged when its major version differs."""
+        version = session.client.server_app_version
+        if not version:
+            return session.name
+        marker = " ⚠ VERSION MISMATCH" if session.version_mismatch else ""
+        return f"{session.name} ({version}{marker})"
+
+    def _on_connected(self, session: ServerSession, server_name: str) -> None:
+        if session not in self._sessions:
+            return
+        session.name = server_name or session.name
+        self._tabs.setTabText(self._sessions.index(session), session.name)
+        session.connected = True
+        # Semver policy: matching majors are the compatibility contract. A
+        # mismatch warns loudly (log, dialog, status bar) but never blocks —
+        # the user may still try, with no guarantees.
+        warning = compat.mismatch_warning(
+            __version__, session.client.server_app_version, "server"
+        )
+        session.version_mismatch = warning is not None
+        if warning:
+            self.log(warning)
+            box = QMessageBox(
+                QMessageBox.Icon.Warning,
+                "Version mismatch",
+                warning,
+                QMessageBox.StandardButton.Ok,
+                self,
+            )
+            box.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose, True)
+            box.show()  # non-modal: streaming continues behind it
+        self.inventory.record(session.key, "connected", name=session.name)
+        session.viewer.setFocus()
+        self._set_session_status(
+            session,
+            f"Connected to {self._server_label(session)} — waiting for first frame "
+            "(click the view to control it)",
+        )
+        self._update_window_title()
+
+    def _on_input_event(self, session: ServerSession, event: dict) -> None:
+        if session.connected:
+            session.client.send_input(event)
+
+    def _on_denied(self, session: ServerSession, reason: str) -> None:
+        if session not in self._sessions:
+            return
+        session.connected = False
+        session.denied = True
+        self.inventory.record(session.key, "denied", name=session.name)
+        session.viewer.clear(f"Connection denied: {reason}")
+        self._set_session_status(session, f"Denied by {session.name}: {reason}")
+        self._update_window_title()
+
+    def _on_disconnected(self, session: ServerSession) -> None:
+        if session not in self._sessions:
+            return
+        session.connected = False
+        # After a denial, keep "denied" as the peer's state in the inventory
+        # rather than overwriting it with the trailing "disconnected".
+        if not session.denied:
+            self.inventory.record(session.key, "disconnected", name=session.name)
+            session.viewer.clear("Disconnected")
+            self._set_session_status(session, f"Disconnected from {session.name}")
+        self._update_window_title()
+
+    def _request_server_log(self) -> None:
+        session = self._session_for_viewer(self._tabs.currentWidget())
+        if session is None:
+            connected = [s for s in self._sessions if s.connected]
+            session = connected[-1] if connected else None
+        if session is None:
+            self.log("Not connected — no server to request a log from")
+            return
+        session.client.request_log()
+
+    def _show_server_log(self, server_name: str, text: str) -> None:
+        title = (
+            f'Log from server "{server_name}"' if server_name else "Log from server"
+        )
+        PeerLogDialog(title, text, self).show()
+
+    def _on_frame(self, session: ServerSession, image) -> None:
+        if session not in self._sessions:
+            return
+        session.frame_count += 1
+        session.viewer.show_frame(image)
+        self._set_session_status(
+            session,
+            f"Viewing {self._server_label(session)} — {image.width()}x{image.height()} — "
+            f"{session.frame_count} frames received",
+        )
+
+    def closeEvent(self, event: QCloseEvent) -> None:
+        window_state.save_geometry(self, self._settings, window_state.CLIENT_GEOMETRY_KEY)
+        for session in self._sessions:
+            session.client.close()
+        super().closeEvent(event)
+
+
+def main() -> None:  # pragma: no cover - runs the Qt event loop
+    log_path = logs.init_logging("client")
+    icon.set_windows_app_id("remotedesktop.client")
+    app = QApplication(sys.argv)
+    app.setWindowIcon(icon.app_icon("client"))
+    window = ClientWindow()  # auto_scan starts the first LAN scan
+    window.log(f"Detailed log: {log_path}")
+    window.show()
+    raise SystemExit(app.exec())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()