remotedesktop 0.16.0__tar.gz → 0.17.0__tar.gz

remotedesktop-0.17.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: remotedesktop
+Version: 0.17.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.17.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.17.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.17.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.17.0"

remotedesktop-0.17.0/tools/make_demo_gifs.py

@@ -0,0 +1,287 @@
+"""Generate the README demo GIFs (docs/media/*.gif) from synthetic data.
+
+Runs the real client and server GUI apps in one process, connected over
+loopback TLS with temp-file databases, and drives a short scripted session:
+discovery, approval, live streaming of a *drawn* fake desktop (the
+ShareServer._capture test seam — no real screen content is ever captured),
+tab switches. Both windows are rendered with WA_DontShowOnScreen, grabbed on
+a timer, and assembled into GIFs with Pillow.
+
+Machine identities are synthetic too ("DEN-PC" serving, "LAPTOP" viewing,
+user "alex"), so nothing about the generating machine leaks into the README.
+
+Usage:  uv run python tools/make_demo_gifs.py [output_dir]
+        (default output_dir: docs/media)
+"""
+
+import io
+import math
+import socket
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+from PIL import Image
+from PySide6.QtCore import QBuffer, QPointF, Qt
+from PySide6.QtGui import QColor, QFont, QImage, QLinearGradient, QPainter, QPolygonF
+from PySide6.QtWidgets import QApplication, QMessageBox, QTabWidget
+
+from remotedesktop import db, sharing, tls
+from remotedesktop.autostart import Autostart
+from remotedesktop.client import ClientWindow
+from remotedesktop.config import PairedClients, Settings
+from remotedesktop.discovery import ServerInfo
+from remotedesktop.server import ServerWindow
+from remotedesktop import client as client_module
+
+SCREEN_W, SCREEN_H = 1280, 800
+GIF_WIDTH = 900
+CAPTURE_INTERVAL = 0.15  # seconds per frame, also the GIF frame duration
+TOTAL_SECONDS = 11.0
+_CODE_LINES = [
+    "def changed_bands(previous, current):",
+    '    """Bands of `current` that differ from `previous`."""',
+    "    stride = current.bytesPerLine()",
+    "    bands, y = [], 0",
+    "    while y < current.height():",
+    "        h = min(BAND_HEIGHT, height - y)",
+    "        if prev[y*stride:(y+h)*stride] != cur[y*stride:(y+h)*stride]:",
+    "            bands.append((y, h))",
+    "        y += h",
+    "    return bands",
+    "",
+    "class ShareServer(QObject):",
+    "    clientCountChanged = Signal(int)",
+    "    def listen(self, port):",
+    "        return self._server.listen(Any, port)",
+]
+
+
+class SyntheticDesktop:
+    """Draws an animated fake desktop: wallpaper, an editor window with
+    scrolling code, a terminal appending lines, a clock, a gliding cursor."""
+
+    def __init__(self) -> None:
+        self._start = time.monotonic()
+        self._background = self._draw_background()
+
+    @staticmethod
+    def _draw_background() -> QImage:
+        image = QImage(SCREEN_W, SCREEN_H, QImage.Format.Format_RGB32)
+        painter = QPainter(image)
+        gradient = QLinearGradient(0, 0, SCREEN_W, SCREEN_H)
+        gradient.setColorAt(0.0, QColor(16, 42, 84))
+        gradient.setColorAt(1.0, QColor(52, 18, 90))
+        painter.fillRect(0, 0, SCREEN_W, SCREEN_H, gradient)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        painter.setPen(Qt.PenStyle.NoPen)
+        for i, radius in enumerate((260, 180, 120)):
+            painter.setBrush(QColor(255, 255, 255, 10 + i * 4))
+            painter.drawEllipse(QPointF(1020 + i * 40, 190 - i * 20), radius, radius)
+        painter.end()
+        return image
+
+    def grab(self) -> QImage:
+        t = time.monotonic() - self._start
+        image = self._background.copy()
+        painter = QPainter(image)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        self._editor(painter, t)
+        self._terminal(painter, t)
+        self._taskbar(painter, t)
+        self._cursor(painter, t)
+        painter.end()
+        return image
+
+    def _window_frame(self, painter: QPainter, x: int, y: int, w: int, h: int, title: str) -> None:
+        painter.setPen(QColor(70, 70, 70))
+        painter.setBrush(QColor(32, 33, 36))
+        painter.drawRoundedRect(x, y, w, h, 6, 6)
+        painter.fillRect(x + 1, y + 1, w - 2, 30, QColor(48, 49, 52))
+        painter.setPen(QColor(220, 220, 220))
+        painter.setFont(QFont("Segoe UI", 10))
+        painter.drawText(x + 12, y + 21, title)
+        for i, color in enumerate(("#ff5f57", "#febc2e", "#28c840")):
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.setBrush(QColor(color))
+            painter.drawEllipse(QPointF(x + w - 20 - i * 22, y + 15), 6, 6)
+
+    def _editor(self, painter: QPainter, t: float) -> None:
+        x, y, w, h = 60, 60, 720, 520
+        self._window_frame(painter, x, y, w, h, "frames.py — editor")
+        painter.setClipRect(x + 1, y + 32, w - 2, h - 40)
+        painter.setFont(QFont("Consolas", 11))
+        offset = int(t * 22) % (len(_CODE_LINES) * 24)
+        for i in range(24):
+            line = _CODE_LINES[(i + offset // 24) % len(_CODE_LINES)]
+            line_y = y + 56 + i * 24 - offset % 24
+            painter.setPen(QColor(90, 96, 105))
+            painter.drawText(x + 16, line_y, f"{(i + offset // 24) % 99 + 1:>3}")
+            keyword = line.lstrip().startswith(("def ", "class ", "return", "while", "if "))
+            painter.setPen(QColor("#c586c0") if keyword else QColor("#9cdcfe"))
+            painter.drawText(x + 56, line_y, line)
+        painter.setClipping(False)
+
+    def _terminal(self, painter: QPainter, t: float) -> None:
+        x, y, w, h = 620, 320, 580, 360
+        self._window_frame(painter, x, y, w, h, "PowerShell")
+        painter.setClipRect(x + 1, y + 32, w - 2, h - 40)
+        painter.setFont(QFont("Consolas", 10))
+        lines = int(t * 2) + 1
+        for i in range(min(lines, 12)):
+            step = lines - min(lines, 12) + i
+            painter.setPen(QColor("#4ec9b0"))
+            painter.drawText(x + 14, y + 54 + i * 26, f"PS> uv run pytest -q  # run {step}")
+            painter.setPen(QColor(200, 200, 200))
+            painter.drawText(x + 300, y + 54 + i * 26, f"{170 + step} passed")
+        painter.setClipping(False)
+
+    def _taskbar(self, painter: QPainter, t: float) -> None:
+        painter.fillRect(0, SCREEN_H - 44, SCREEN_W, 44, QColor(24, 24, 28))
+        painter.setPen(Qt.PenStyle.NoPen)
+        for i in range(6):
+            painter.setBrush(QColor(70 + i * 12, 120, 200, 180))
+            painter.drawRoundedRect(16 + i * 52, SCREEN_H - 36, 40, 28, 4, 4)
+        painter.setPen(QColor(230, 230, 230))
+        painter.setFont(QFont("Segoe UI", 10))
+        clock = f"{(14 + int(t) // 3600) % 24:02d}:{(31 + int(t) // 60) % 60:02d}:{int(t) % 60:02d}"
+        painter.drawText(SCREEN_W - 90, SCREEN_H - 16, clock)
+
+    def _cursor(self, painter: QPainter, t: float) -> None:
+        cx = 640 + 380 * math.sin(t * 0.9)
+        cy = 400 + 240 * math.sin(t * 0.6 + 1.3)
+        arrow = QPolygonF(
+            [
+                QPointF(cx, cy),
+                QPointF(cx, cy + 21),
+                QPointF(cx + 6, cy + 16),
+                QPointF(cx + 13, cy + 15),
+            ]
+        )
+        painter.setPen(QColor(0, 0, 0))
+        painter.setBrush(QColor(255, 255, 255))
+        painter.drawPolygon(arrow)
+
+
+def free_udp_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
+        probe.bind(("", 0))
+        return probe.getsockname()[1]
+
+
+def tab_index(tabs: QTabWidget, label: str) -> int:
+    for index in range(tabs.count()):
+        if tabs.tabText(index) == label:
+            return index
+    raise LookupError(label)
+
+
+def to_gif_frame(window) -> Image.Image:
+    image = window.grab().toImage().scaledToWidth(
+        GIF_WIDTH, Qt.TransformationMode.SmoothTransformation
+    )
+    buffer = QBuffer()
+    buffer.open(QBuffer.OpenModeFlag.WriteOnly)
+    image.save(buffer, "PNG")
+    png = bytes(buffer.data())  # ty: ignore[invalid-argument-type]
+    return Image.open(io.BytesIO(png)).convert("RGB")
+
+
+def save_gif(frames: list[Image.Image], path: Path) -> None:
+    quantized = [f.convert("P", palette=Image.Palette.ADAPTIVE, colors=128) for f in frames]
+    quantized[0].save(
+        path,
+        save_all=True,
+        append_images=quantized[1:],
+        duration=int(CAPTURE_INTERVAL * 1000),
+        loop=0,
+        optimize=True,
+    )
+    print(f"{path}: {len(frames)} frames, {path.stat().st_size // 1024} KB")
+
+
+def main() -> None:
+    out_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("docs/media")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    app = QApplication(sys.argv)
+
+    # Everything below is synthetic: names, users, databases, screen content.
+    socket.gethostname = lambda: "DEN-PC"  # ty: ignore[invalid-assignment]
+    sharing._client_details = lambda: {  # ty: ignore[invalid-assignment]
+        "user": "alex",
+        "host": "LAPTOP",
+        "os": "Windows 11 (10.0.26200)",
+    }
+    QMessageBox.show = lambda self: None  # approval prompt answers itself
+    QMessageBox.exec = lambda self: QMessageBox.StandardButton.Yes
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        credentials = tls.load_or_create_credentials(
+            tmp_path / "cert.pem", tmp_path / "key.pem"
+        )
+        server_db = db.connect(tmp_path / "server.db")
+        server_window = ServerWindow(
+            discovery_port=free_udp_port(),  # ephemeral: invisible to the real LAN
+            connect_port=0,
+            paired=PairedClients(server_db),
+            credentials=credentials,
+            connection=server_db,
+            autostart=Autostart(key_path=r"Software\remotedesktop-tests\Demo", value_name="demo"),
+        )
+        desktop = SyntheticDesktop()
+        server_window.share_server._capture = desktop.grab  # the test seam  # ty: ignore[invalid-assignment]
+
+        client_db = db.connect(tmp_path / "client.db")
+        client_settings = Settings(client_db)
+        client_settings.set("client_id", str(uuid.uuid4()))
+        client_settings.set("client_name", "LAPTOP")
+        client_window = ClientWindow(connection=client_db, auto_scan=False)
+
+        for window, size in ((server_window, (1180, 620)), (client_window, (1180, 760))):
+            window.setAttribute(Qt.WidgetAttribute.WA_DontShowOnScreen, True)
+            window.resize(*size)
+            window.show()
+
+        info = ServerInfo(name="DEN-PC", host="127.0.0.1", port=server_window.share_server.port)
+        client_module.discover_servers = lambda: [info]  # ty: ignore[invalid-assignment]
+        client_tabs = client_window.centralWidget()
+        server_tabs = server_window.centralWidget()
+        assert isinstance(client_tabs, QTabWidget) and isinstance(server_tabs, QTabWidget)
+
+        script = [
+            (0.8, lambda: client_window.discovery_panel.refresh()),
+            (2.0, lambda: client_window.discovery_panel.serverActivated.emit(info)),
+            (6.8, lambda: client_tabs.setCurrentIndex(tab_index(client_tabs, "Performance"))),
+            (7.2, lambda: server_tabs.setCurrentIndex(tab_index(server_tabs, "Performance"))),
+            (9.2, lambda: client_tabs.setCurrentIndex(tab_index(client_tabs, "Remote Screen"))),
+            (9.6, lambda: server_tabs.setCurrentIndex(tab_index(server_tabs, "Status"))),
+        ]
+        client_frames: list[Image.Image] = []
+        server_frames: list[Image.Image] = []
+        start = time.monotonic()
+        next_capture = 0.0
+        while (elapsed := time.monotonic() - start) < TOTAL_SECONDS:
+            while script and elapsed >= script[0][0]:
+                script.pop(0)[1]()
+            if elapsed >= next_capture:
+                client_frames.append(to_gif_frame(client_window))
+                server_frames.append(to_gif_frame(server_window))
+                next_capture += CAPTURE_INTERVAL
+            app.processEvents()
+            time.sleep(0.005)
+
+        save_gif(client_frames, out_dir / "client-demo.gif")
+        save_gif(server_frames, out_dir / "server-demo.gif")
+        client_window.close()
+        server_window.close()
+        app.processEvents()
+        # The temp dir can't be removed while the SQLite files are open.
+        client_db.close()
+        server_db.close()
+
+
+if __name__ == "__main__":
+    main()