gui-remote-controll 0.1.1__tar.gz

gui_remote_controll-0.1.1/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1
+
+- Add opt-in bidirectional automatic clipboard synchronization.
+- Request browser clipboard access when the remote UI opens and retry from the switch gesture.
+- Prefer `clipboardchange` events with a focused-page polling fallback.
+- Establish independent initial baselines and suppress synchronization feedback loops.
+- Add digest-aware server polling and request-correlated clipboard write acknowledgements.
+- Redirect stale authenticated pages to PIN login after a server restart.
+- Document secure-context requirements and clipboard privacy considerations.
+
+## 0.1.0
+
+- Initial cross-platform browser remote desktop server.

gui_remote_controll-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGN_2015
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gui_remote_controll-0.1.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: gui-remote-controll
+Version: 0.1.1
+Summary: Cross-platform remote desktop control from a web browser.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: remote-desktop,screen-sharing,websocket,remote-control
+Author: GGN_2015
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Requires-Dist: fastapi (>=0.115)
+Requires-Dist: mss (>=10.0)
+Requires-Dist: pillow (>=10.4)
+Requires-Dist: py-admin-launch (>=0.1.3)
+Requires-Dist: pynput (>=1.8)
+Requires-Dist: pyperclip (>=1.9)
+Requires-Dist: uvicorn[standard] (>=0.30)
+Project-URL: Documentation, https://github.com/GGN-2015/gui-remote-controll#readme
+Project-URL: Homepage, https://github.com/GGN-2015/gui-remote-controll
+Project-URL: Repository, https://github.com/GGN-2015/gui-remote-controll
+Description-Content-Type: text/markdown
+
+# GUI Remote Controll
+
+[中文](https://github.com/GGN-2015/gui-remote-controll/blob/main/README.zh-CN.md)
+
+GUI Remote Controll shares a Windows, Linux, or macOS desktop with a web browser. The
+browser receives screen frames and can redirect mouse, touch, wheel, keyboard, text input,
+and plain-text clipboard events to the server computer.
+
+## Quick Start
+
+Python 3.10 or newer is required.
+
+1. Install the package:
+
+   ```console
+   pip install gui-remote-controll
+   ```
+
+2. Start a PIN-protected server:
+
+   ```console
+   gui-remote-controll --pin 123456
+   ```
+
+   Startup requests administrator/root privileges once. Use `--no-elevate` only when the
+   desktop permissions have already been configured or elevation is inappropriate.
+
+3. Open the control page:
+
+   - On the server computer: `http://127.0.0.1:8000`
+   - On the local network: `http://SERVER_LAN_IP:8000`
+
+The default bind address is `0.0.0.0`. Always set `--pin` when another device can reach the
+server. Use TLS or an encrypted tunnel outside a trusted LAN, and never expose the default
+HTTP service directly to the public internet.
+
+### First-run permissions
+
+- **Windows:** accept the UAC prompt. Run the server from the signed-in interactive session.
+- **Linux:** use an X11 desktop session. Native Wayland does not permit portable global
+  capture and input injection.
+- **macOS:** grant Screen Recording and Accessibility permissions to the terminal or Python
+  executable, then restart the server. Root access does not replace these permissions.
+
+See the [platform guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/platform-support.md)
+for setup and troubleshooting details.
+
+## Documentation
+
+- [Documentation index](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/README.md)
+- [Complete user guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/user-guide.md)
+- [CLI reference](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/cli-reference.md)
+- [Architecture and algorithms](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/architecture-and-algorithms.md)
+- [Platform support](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/platform-support.md)
+- [Development and release guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/development.md)
+- [Changelog](https://github.com/GGN-2015/gui-remote-controll/blob/main/CHANGELOG.md)
+- [Security policy](https://github.com/GGN-2015/gui-remote-controll/blob/main/SECURITY.md)
+
+The Python import package is `gui_remote_controll`. The PyPI distribution and command name
+intentionally follow the repository spelling, `gui-remote-controll`.
+
+## License
+
+[MIT](https://github.com/GGN-2015/gui-remote-controll/blob/main/LICENSE)
+

gui_remote_controll-0.1.1/README.md

@@ -0,0 +1,64 @@
+# GUI Remote Controll
+
+[中文](https://github.com/GGN-2015/gui-remote-controll/blob/main/README.zh-CN.md)
+
+GUI Remote Controll shares a Windows, Linux, or macOS desktop with a web browser. The
+browser receives screen frames and can redirect mouse, touch, wheel, keyboard, text input,
+and plain-text clipboard events to the server computer.
+
+## Quick Start
+
+Python 3.10 or newer is required.
+
+1. Install the package:
+
+   ```console
+   pip install gui-remote-controll
+   ```
+
+2. Start a PIN-protected server:
+
+   ```console
+   gui-remote-controll --pin 123456
+   ```
+
+   Startup requests administrator/root privileges once. Use `--no-elevate` only when the
+   desktop permissions have already been configured or elevation is inappropriate.
+
+3. Open the control page:
+
+   - On the server computer: `http://127.0.0.1:8000`
+   - On the local network: `http://SERVER_LAN_IP:8000`
+
+The default bind address is `0.0.0.0`. Always set `--pin` when another device can reach the
+server. Use TLS or an encrypted tunnel outside a trusted LAN, and never expose the default
+HTTP service directly to the public internet.
+
+### First-run permissions
+
+- **Windows:** accept the UAC prompt. Run the server from the signed-in interactive session.
+- **Linux:** use an X11 desktop session. Native Wayland does not permit portable global
+  capture and input injection.
+- **macOS:** grant Screen Recording and Accessibility permissions to the terminal or Python
+  executable, then restart the server. Root access does not replace these permissions.
+
+See the [platform guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/platform-support.md)
+for setup and troubleshooting details.
+
+## Documentation
+
+- [Documentation index](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/README.md)
+- [Complete user guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/user-guide.md)
+- [CLI reference](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/cli-reference.md)
+- [Architecture and algorithms](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/architecture-and-algorithms.md)
+- [Platform support](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/platform-support.md)
+- [Development and release guide](https://github.com/GGN-2015/gui-remote-controll/blob/main/docs/development.md)
+- [Changelog](https://github.com/GGN-2015/gui-remote-controll/blob/main/CHANGELOG.md)
+- [Security policy](https://github.com/GGN-2015/gui-remote-controll/blob/main/SECURITY.md)
+
+The Python import package is `gui_remote_controll`. The PyPI distribution and command name
+intentionally follow the repository spelling, `gui-remote-controll`.
+
+## License
+
+[MIT](https://github.com/GGN-2015/gui-remote-controll/blob/main/LICENSE)

gui_remote_controll-0.1.1/README.zh-CN.md

@@ -0,0 +1,60 @@
+# GUI Remote Controll
+
+[English](README.md)
+
+GUI Remote Controll 可以把 Windows、Linux 或 macOS 桌面共享到浏览器，并把鼠标、触摸、
+滚轮、键盘、输入法文本和纯文本剪贴板事件重定向到服务端电脑。
+
+## 快速开始
+
+需要 Python 3.10 或更高版本。
+
+1. 安装：
+
+   ```console
+   pip install gui-remote-controll
+   ```
+
+2. 启动带 PIN 保护的服务器：
+
+   ```console
+   gui-remote-controll --pin 123456
+   ```
+
+   程序默认只请求一次管理员/root 权限。只有在已经单独配置桌面权限，或当前环境不适合提权
+   时，才使用 `--no-elevate`。
+
+3. 打开控制页面：
+
+   - 服务端电脑：`http://127.0.0.1:8000`
+   - 局域网设备：`http://服务端局域网IP:8000`
+
+默认监听地址是 `0.0.0.0`。只要其他设备可以访问，就必须设置 `--pin`。离开可信局域网时，
+应使用 TLS 或加密隧道，不要把默认 HTTP 服务直接暴露到公网。
+
+### 首次运行权限
+
+- **Windows：**接受 UAC 提示，并从已登录用户的交互式会话启动。
+- **Linux：**使用 X11 桌面会话；原生 Wayland 不允许通用的全局画面抓取和输入注入。
+- **macOS：**为终端或 Python 可执行文件授予“屏幕录制”和“辅助功能”权限，然后重启服务。
+  root 权限不能代替这些隐私授权。
+
+详细设置与排错见[平台支持手册](docs/platform-support.md)。
+
+## 完整手册
+
+- [手册索引](docs/README.md)
+- [完整用户手册](docs/user-guide.md)
+- [CLI 参数手册](docs/cli-reference.md)
+- [架构、算法与协议手册](docs/architecture-and-algorithms.md)
+- [平台支持手册](docs/platform-support.md)
+- [开发与发布手册](docs/development.md)
+- [版本变更记录](CHANGELOG.md)
+- [安全策略](SECURITY.md)
+
+Python 导入包名为 `gui_remote_controll`；PyPI 分发包和命令名沿用仓库拼写
+`gui-remote-controll`。
+
+## 许可证
+
+[MIT](LICENSE)

gui_remote_controll-0.1.1/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the latest released version.
+
+## Reporting a vulnerability
+
+Do not open a public issue for an undisclosed vulnerability. Use GitHub's private security
+advisory feature for this repository, or contact the repository owner privately.
+
+Include the affected version, platform, configuration, reproduction steps, impact, and any
+suggested mitigation. Please allow a reasonable time for investigation before disclosure.
+
+## Security model
+
+GUI Remote Controll gives authenticated clients the ability to observe and operate the signed-in
+desktop. Its PIN protects the web boundary; it does not provide end-to-end encryption. Use TLS
+or an encrypted tunnel whenever traffic leaves a trusted network.
+
+The server intentionally does not persist the PIN, authentication cookies, frames, keystrokes,
+or clipboard text. Authentication tokens are signed with a random process-local secret and
+become invalid after restart. Login failures are rate-limited in memory.
+
+Automatic clipboard synchronization is disabled by default because clipboard text may contain
+passwords, tokens, private messages, or other sensitive data. Enabling it authorizes plain-text
+clipboard contents to move in both directions while the browser tab is active. Use HTTPS or an
+encrypted tunnel so that clipboard data is not exposed in transit.
+
+Administrator/root elevation increases impact if the service is exposed incorrectly. The server
+requests elevation at most once per startup and supports `--no-elevate`, but operators remain
+responsible for restricting network reachability and choosing a strong PIN.

gui_remote_controll-0.1.1/docs/README.md

@@ -0,0 +1,20 @@
+# Documentation
+
+This directory contains the complete GUI Remote Controll manual. Start with the user guide
+unless you are looking for a specific command-line option or implementation detail.
+
+| Manual | Contents |
+| --- | --- |
+| [User guide](user-guide.md) | Browser controls, sessions, displays, input, clipboard, view-only mode, reconnection, TLS, and operational workflows. |
+| [CLI reference](cli-reference.md) | Every public command-line option, defaults, validation rules, and deployment examples. |
+| [Architecture and algorithms](architecture-and-algorithms.md) | Process lifecycle, authentication, capture pipeline, frame deduplication, coordinate mapping, input algorithms, HTTP routes, and WebSocket protocol. |
+| [Platform support](platform-support.md) | Windows, Linux/X11 desktop environments, Wayland limitations, macOS permissions, and platform troubleshooting. |
+| [Development and release](development.md) | Local setup, repository layout, tests, linting, CI, building, artifact inspection, and PyPI release steps. |
+| [Security policy](../SECURITY.md) | Threat model, operational requirements, and vulnerability reporting. |
+| [Changelog](../CHANGELOG.md) | User-visible changes by package version. |
+
+## Support boundary
+
+GUI Remote Controll controls the currently signed-in interactive desktop. It is not a service
+for the Windows secure desktop, pre-login screens, native Wayland compositors, DRM-protected
+content, system audio, file transfer, or unattended operating-system installation.

gui_remote_controll-0.1.1/docs/architecture-and-algorithms.md

@@ -0,0 +1,334 @@
+# Architecture and Algorithms
+
+## System model
+
+GUI Remote Controll is a bitmap remote-control system. It does not mirror a native window tree
+or expose remote DOM elements. The server captures desktop pixels, encodes them as JPEG, and
+injects validated browser input into the signed-in operating-system session.
+
+```mermaid
+flowchart LR
+    Browser["Browser UI"] -->|"JSON control messages"| WS["FastAPI WebSocket"]
+    WS --> Validator["Protocol validator"]
+    Validator --> Desktop["Desktop backend"]
+    Desktop --> OS["Signed-in desktop"]
+    OS --> Capture["MSS capture"]
+    Capture --> JPEG["Pillow JPEG encoder"]
+    JPEG --> Dedup["BLAKE2b frame check"]
+    Dedup -->|"changed binary frames"| WS
+    WS --> Browser
+```
+
+## Package layout
+
+| Module | Responsibility |
+| --- | --- |
+| `gui_remote_controll.__main__` | CLI parsing, validation, elevation, browser opening, and Uvicorn startup. |
+| `gui_remote_controll.config` | Validated runtime settings and protocol size limits. |
+| `gui_remote_controll.auth` | PIN comparison, signed Cookie tokens, and login attempt limiting. |
+| `gui_remote_controll.protocol` | Strict normalization and validation of client JSON messages. |
+| `gui_remote_controll.desktop` | Screen enumeration/capture, JPEG encoding, input injection, clipboard, DPI, and platform diagnostics. |
+| `gui_remote_controll.app` | HTTP routes, security headers, backend lifecycle, connection gate, and WebSocket loops. |
+| `gui_remote_controll.static` | Packaged browser UI with no CDN or runtime frontend dependency. |
+
+## Process lifecycle
+
+1. Parse arguments and validate the TLS file pair.
+2. Unless disabled or already attempted, relaunch through `py-admin-launch`.
+3. Convert parsed values to `Settings` and validate ranges.
+4. Create the FastAPI application and Uvicorn server.
+5. Serve the login UI, control UI, health endpoint, and static files without opening the desktop.
+6. On the first accepted WebSocket, initialize the shared desktop backend in a worker thread.
+7. Enumerate displays and start one receive loop and one capture loop for the client.
+8. Cancel the peer loop and release held inputs when either loop finishes.
+
+Lazy desktop initialization keeps CLI help, health checks, packaging, and PIN authentication
+usable even when the process is temporarily outside a graphical session.
+
+## Elevation algorithm
+
+The public CLI implements a single-relaunch invariant:
+
+```text
+if no_elevate or elevation_attempted:
+    start server
+else:
+    launch([python, -m, gui_remote_controll,
+            --elevation-attempted, *original_arguments], wait=True)
+    exit parent
+```
+
+The marker is inserted by the program rather than stored in process environment, so it survives
+the platform launcher without requiring environment mutation support. Even when the first
+process is already administrator/root, `py-admin-launch` directly launches the marked child and
+the invariant remains at most one launch call.
+
+## Authentication algorithm
+
+### PIN comparison
+
+PIN values are compared with `hmac.compare_digest` over UTF-8 bytes. This avoids ordinary
+short-circuit string comparison behavior.
+
+### Cookie token
+
+At application creation, the server generates a random 32-byte secret. With a configured PIN:
+
+```text
+token = HMAC-SHA256(process_secret, pin_utf8)
+```
+
+The hexadecimal token is stored in `gui_remote_auth` with:
+
+- `HttpOnly` enabled;
+- `SameSite=Strict`;
+- path `/`;
+- a maximum age of seven days;
+- `Secure` enabled when direct TLS is configured.
+
+The secret is never persisted, so all authentication cookies become invalid after restart.
+Without a configured PIN, request and WebSocket authentication checks allow access.
+
+### Failed-login limiter
+
+Failures are stored in an in-memory deque per client IP. Before each attempt, timestamps at or
+before `now - 60 seconds` are discarded. A client with five remaining timestamps is rejected
+until one expires. Successful authentication clears that client's deque.
+
+This is a process-local rolling-window defense, not a replacement for firewall or proxy rate
+limiting on an internet-facing deployment.
+
+## HTTP security boundary
+
+Every HTTP response receives:
+
+- a Content Security Policy restricted to packaged same-origin resources plus WebSocket
+  connections and blob/data images;
+- `Cross-Origin-Opener-Policy: same-origin`;
+- `Referrer-Policy: no-referrer`;
+- `X-Content-Type-Options: nosniff`;
+- `X-Frame-Options: DENY`.
+
+The main and authentication pages use `Cache-Control: no-store`. Static file access uses a fixed
+filename allowlist rather than arbitrary path resolution.
+
+Authentication redirect targets must start with one `/`, must not start with `//`, and are
+truncated to 2,048 characters.
+
+## WebSocket admission
+
+Admission checks run before the socket is accepted:
+
+1. Validate the PIN Cookie, closing with `4401` on failure.
+2. Validate Origin, closing with `4403` on failure.
+3. Reserve a connection slot, closing with `4429` when full.
+4. Accept the socket.
+5. Initialize the desktop and close with `4500` if it is unavailable.
+
+An absent Origin is allowed for non-browser clients. A browser Origin is accepted when its
+network location matches the HTTP Host header or when the complete normalized origin appears in
+the configured trusted-origin set.
+
+## Connection and concurrency model
+
+`BackendManager` creates one desktop backend per FastAPI application and protects creation with
+an `asyncio.Lock`. Blocking desktop operations run through `asyncio.to_thread`, so capture,
+clipboard, and native input calls do not block the event loop.
+
+Each accepted client has:
+
+- one `ClientState` with its display selection and held keys/buttons;
+- one frame streaming task;
+- one message receiving task;
+- one lock serializing JSON and binary WebSocket sends.
+
+The first completed task cancels the other. Cleanup decrements the connection counter and asks
+the backend to release all inputs still held by that client.
+
+## Display model
+
+MSS returns an ordered monitor collection:
+
+- monitor `0` is the bounding rectangle of all monitors;
+- monitor `N > 0` is a physical display.
+
+A `Screen` contains `index`, `left`, `top`, `width`, `height`, and `name`. Negative `left` or
+`top` values are valid when a monitor is positioned to the left or above the primary display.
+
+On Windows, per-monitor DPI awareness is requested before importing input libraries. MSS is
+imported before `pynput` to keep capture and input coordinate systems aligned.
+
+## Capture and frame algorithm
+
+The capture loop runs once per WebSocket:
+
+1. Select the current monitor from the client's state.
+2. Acquire BGRA pixels through a thread-local MSS instance.
+3. Convert MSS RGB bytes to a Pillow RGB image.
+4. Encode JPEG with the configured quality and chroma subsampling.
+5. Compute `BLAKE2b(frame_bytes, digest_size=8)`.
+6. Send display metadata when the selected monitor changes.
+7. Send the JPEG as a binary WebSocket message only when its digest differs from the last sent
+   frame.
+8. Sleep for `max(0.001, 1/fps - capture_elapsed)`.
+
+Hashing encoded bytes means the comparison reflects exactly what the client would receive. The
+64-bit digest is used as a fast change detector rather than a security primitive. A theoretical
+collision would skip one changed frame; a later differing frame would resume transmission.
+
+Thread-local MSS instances avoid sharing a platform capture object across worker threads. The
+instance remains associated with that worker thread for reuse.
+
+## Pointer coordinate mapping
+
+The browser measures the rendered image rectangle and converts a pointer event into normalized
+coordinates:
+
+```text
+nx = clamp((client_x - image_left) / image_width,  0, 1)
+ny = clamp((client_y - image_top)  / image_height, 0, 1)
+```
+
+The server converts them to absolute desktop coordinates:
+
+```text
+x = screen.left + round(nx * max(0, screen.width  - 1))
+y = screen.top  + round(ny * max(0, screen.height - 1))
+```
+
+Using normalized values makes Fit and 1:1 modes equivalent and supports negative multi-monitor
+origins. Subtracting one keeps `1.0` inside the final pixel rather than one pixel beyond the
+display.
+
+## Pointer movement and buttons
+
+The browser sends at most one pending pointer movement per animation frame. Down/up events carry
+`left`, `middle`, or `right`. The server first moves the native pointer to the mapped coordinate,
+then applies the button operation.
+
+Both browser and server track held buttons. Browser blur, pointer cancellation, WebSocket
+disconnect, and server cleanup release them so a lost connection does not leave a native button
+pressed.
+
+## Wheel accumulation
+
+Browser deltas are normalized to a bounded range of -20 to 20. The backend keeps two fractional
+remainders:
+
+```text
+remainder_x -= incoming_dx
+remainder_y -= incoming_dy
+step_x = trunc(remainder_x)
+step_y = trunc(remainder_y)
+remainder_x -= step_x
+remainder_y -= step_y
+```
+
+Only nonzero integer steps are passed to `pynput`. The sign inversion converts browser-positive
+down/right deltas to the controller's native convention.
+
+## Keyboard and text algorithms
+
+The browser does not send ordinary printable characters as key events. Instead, a hidden text
+input collects regular and composed text and sends it through `text`. Named keys and modified
+shortcuts use `key` down/up messages.
+
+This avoids duplicate input from the common sequence of keydown, composition events, and input.
+Ctrl/Cmd+V is handled as local pasted text instead of forwarding both a remote shortcut and the
+local clipboard contents.
+
+The backend maps browser named keys to `pynput.keyboard.Key` and single characters to
+`KeyCode.from_char`. Repeated keydown messages are not injected again. The native operating
+system provides repeat behavior while the key remains held.
+
+## Clipboard algorithm
+
+Clipboard get/set operations run in worker threads through `pyperclip`. Text is limited to
+1,000,000 characters. A get truncates an unexpectedly longer native clipboard value; the
+protocol validator rejects an oversized set before calling the backend.
+
+Clipboard operations are independent of view-only input control. They are completely rejected
+only when clipboard synchronization is disabled.
+
+### Automatic client state machine
+
+Automatic synchronization begins with independent client and server baselines, so enabling it
+does not immediately overwrite either clipboard. The client then tracks the last observed text
+from both sides. A new local value is sent to the server and optimistically becomes the expected
+server value. A new server value is written locally while an `applyingServerClipboard` guard
+suppresses the resulting browser change event.
+
+If the client changes before the first server baseline response arrives, a baseline-pending flag
+causes that stale response to be ignored. This makes active local input win the only interval in
+which ordering is otherwise unknowable.
+
+The client prefers the standard `clipboardchange` event. When it is unavailable, a one-second
+poll reads the client clipboard. Server polling continues in either case, but only while the page
+is visible and focused. Browser permission loss disables the switch instead of silently running
+one-way synchronization.
+
+### Digest negotiation
+
+Server clipboard text is hashed as `BLAKE2b(UTF8(text), digest_size=8)`. Automatic
+`clipboard_get` messages include the last known hexadecimal digest:
+
+- a match returns `clipboard_unchanged` with only the digest;
+- a mismatch or missing digest returns `clipboard` with text and digest.
+
+This digest is a bandwidth optimization, not an authentication primitive. `clipboard_set`
+requests carry a short `requestId`; acknowledgements echo it so the UI can distinguish automatic
+writes from explicit manual writes.
+
+## Client-to-server protocol
+
+All client messages are JSON objects. The maximum encoded message size is 1,100,000 bytes.
+Numbers must be finite; booleans are not accepted as numeric values.
+
+| Type | Fields | Meaning |
+| --- | --- | --- |
+| `pointer` | `event`: `move/down/up`, `x`, `y`, and `button` for down/up | Absolute normalized pointer event. |
+| `wheel` | `dx`, `dy` in `[-20, 20]` | Normalized scroll delta. |
+| `key` | `event`: `down/up`, `key`, `code`, `repeat` | Named key or modified character event. |
+| `text` | `text` | Ordinary or composed text to type. |
+| `monitor` | nonnegative integer `index` | Change this connection's captured display. |
+| `clipboard_get` | optional `knownDigest` | Read server clipboard text, or confirm that a known digest is current. |
+| `clipboard_set` | `text`, optional `requestId` | Replace server clipboard text. |
+| `ping` | none | Application-level liveness request. |
+
+Unknown types, invalid ranges, excessive strings, NaN, infinity, and malformed JSON produce an
+`error` response without terminating the connection.
+
+## Server-to-client protocol
+
+JPEG frames are binary messages. All other messages are JSON.
+
+| Type | Important fields | Meaning |
+| --- | --- | --- |
+| `hello` | `protocol`, `platform`, `viewOnly`, `clipboard`, `screens`, `monitor` | Initial capabilities and display list. Current protocol is `1`. |
+| `screen` | screen fields | Metadata for the binary frames that follow. |
+| `clipboard` | `text`, `digest` | Changed or explicitly requested server clipboard text. |
+| `clipboard_unchanged` | `digest` | The supplied server clipboard digest is still current. |
+| `clipboard_saved` | `digest`, optional `requestId` | Confirmation of `clipboard_set`. |
+| `pong` | none | Response to `ping`. |
+| `error` | `message` | Recoverable protocol or desktop operation error. |
+| `fatal` | `message` | Desktop capture cannot continue. |
+
+## HTTP route contract
+
+| Route | Authentication | Purpose |
+| --- | --- | --- |
+| `GET /healthz` | no | Returns `status` and package `version`. |
+| `GET /` | PIN Cookie when enabled | Packaged control UI. |
+| `GET /auth` | no | Packaged PIN form. |
+| `POST /auth` | rate-limited PIN | Sets the authentication Cookie. |
+| `POST /logout` | no | Deletes the authentication Cookie. |
+| `GET /api/status` | PIN Cookie when enabled | Runtime version, platform, modes, and client counts. |
+| `GET /static/{filename}` | no | Serves four allowlisted CSS/JavaScript assets. |
+| `WS /ws` | PIN Cookie and Origin | Screen and control protocol. |
+
+## Extension points
+
+`create_app` accepts a desktop backend factory. A replacement backend implements initialize,
+screen listing, capture, input execution, input release, and clipboard methods. Tests use this
+boundary to run the full HTTP and WebSocket stack without capturing or controlling a real
+desktop.