Document AnyDesk-style Quick Connect + Phase 4/5 features

README.md / README_zh-TW.md / README_zh-CN.md and the corresponding
Sphinx new-features pages now cover:

- Quick Connect screen as the AnyDesk-style default landing view
- parse_remote_desktop_target() coordinator
- on_pending_viewer approval callback + view-only mode
- ip_allowlist (CIDR + exact IPs)
- single_use_tokens (one-shot share codes)
- RFC 6238 TOTP 2FA (totp_secret host param + viewer totp_code)
- list_host_monitors() + monitor_index
- Remote cursor overlay + enable_cursor_broadcast
- broadcast_chat / send_chat / on_chat (Phase 5.2)
- broadcast_viewer_cursor / on_viewer_cursor (Phase 5.1)
- mouse_move_relative input action
- Motion-aware capture (frame-hash dedup)
- viewer.stats() rolling FPS/kbps snapshot
- JpegSequenceRecorder (no PyAV) + RelayServer
- host_service install/uninstall CLI per platform

Sphinx RST parses without new warnings on top of the existing
pre-existing role / Chinese-punctuation noise.

Author: JE-Chen

README.md

@@ -577,24 +577,175 @@ viewer.send_input({"action": "type", "text": "hello"})
 viewer.disconnect()
 ```
 
-GUI: **Remote Desktop** tab with two sub-tabs.
-
-- **Host** — token field with a *Generate* button, security warning
-  about the bind address, start / stop controls, refreshing port +
-  viewer-count status, and a 4 fps preview pane below the controls so
-  the user being remoted sees what viewers see.
-- **Viewer** — address / port / token form, *Connect* / *Disconnect*,
-  and a custom frame-display widget that paints incoming JPEG frames
-  scaled with `KeepAspectRatio`. Mouse / wheel / key events on the
-  display are remapped from widget coordinates back to the remote
-  screen's pixel space using the latest frame's dimensions, then
-  forwarded as `INPUT` messages.
+GUI: **Remote Desktop** tab opens to the **Quick Connect** screen
+(AnyDesk-style) by default — huge Host ID on one side, a single input
+that accepts `host:port`, `ws://`, `wss://`, or a 9-digit Host ID on
+the other, with *Connect* and *Start hosting* as the two primary
+buttons. Recent connections are remembered across sessions. Advanced
+per-transport sub-tabs (legacy TCP / WS host + viewer, WebRTC host +
+viewer with manual SDP / custom codecs / TLS pinning) stay one click
+away. WebRTC sub-tabs lazy-load so a stock install without the
+`[webrtc]` extra still opens the tab.
 
 > ⚠️ Anyone with the host:port and token gets full mouse / keyboard
 > control of the host machine. Default bind is `127.0.0.1`; expose
 > externally only via SSH tunnel or TLS front-end. The token is the
 > only line of defence — treat it like a password.
 
+**Quick Connect headless API.** The transport coordinator that backs
+the GUI input box is also exported, so scripts can dispatch the same
+way:
+
+```python
+from je_auto_control import parse_remote_desktop_target
+parse_remote_desktop_target("192.168.1.10:5555")
+# ConnectTarget(kind='tcp', host='192.168.1.10', port=5555, ...)
+parse_remote_desktop_target("ws://hub:8765/desk")
+# ConnectTarget(kind='ws', host='hub', port=8765, path='/desk')
+parse_remote_desktop_target("123-456-789")
+# ConnectTarget(kind='webrtc_id', host_id='123456789')
+```
+
+**Connection approval + view-only mode.** Optional callback gates
+every incoming session AnyDesk-style. Returning `"view_only"` admits
+the viewer but drops their `INPUT` messages; returning a falsy value
+(or raising) sends `AUTH_FAIL` "rejected by host":
+
+```python
+from je_auto_control import RemoteDesktopHost, PendingViewer
+
+def gate(p: PendingViewer) -> str:
+    if p.address[0].startswith("10."):
+        return "view_only"
+    return "full"  # or True
+
+host = RemoteDesktopHost(token="tok", on_pending_viewer=gate)
+```
+
+**IP allowlist (CIDR + exact IPs).** Reject peers outside the
+configured ranges *before* TLS / auth runs, so attackers can't probe
+further:
+
+```python
+host = RemoteDesktopHost(
+    token="tok", ip_allowlist=["10.0.0.0/8", "192.168.1.100"],
+)
+```
+
+**One-time share codes** — extra tokens that self-destruct on first
+successful auth, ideal for client-support workflows:
+
+```python
+host = RemoteDesktopHost(token="tok", single_use_tokens=["abc123"])
+host.add_single_use_token("9k4ndx")    # rotate at runtime
+host.revoke_single_use_token("abc123") # cancel before it's used
+```
+
+**TOTP 2FA (RFC 6238, stdlib only).** Layer a 6-digit OTP on top of
+the token; host accepts ±1 step of clock drift:
+
+```python
+from je_auto_control.utils.remote_desktop.totp import (
+    generate_secret, generate_code, provisioning_uri,
+)
+secret = generate_secret()
+print(provisioning_uri(secret, account="alice"))  # otpauth:// URI for QR
+
+host = RemoteDesktopHost(token="tok", totp_secret=secret)
+viewer = RemoteDesktopViewer(
+    host=..., token="tok", totp_code=generate_code(secret),
+)
+```
+
+**Multi-monitor selection.** Capture one specific monitor instead of
+the combined virtual desktop:
+
+```python
+from je_auto_control import list_host_monitors, RemoteDesktopHost
+print(list_host_monitors())
+# [{'index': 0, 'is_combined': True, ...},
+#  {'index': 1, 'left': 0,   'top': 0, ...},
+#  {'index': 2, 'left': 1920, ...}]
+host = RemoteDesktopHost(token="tok", monitor_index=1)
+```
+
+**Remote cursor overlay.** Host broadcasts cursor position at 30 Hz
+(deduped on still desktops); the viewer's popup window draws an arrow
+on top of the JPEG stream so you can see exactly where the host's
+pointer is. Disable via `enable_cursor_broadcast=False`.
+
+**Multi-viewer collaborative cursors + chat.** Two new message types
+(`CHAT` and `CURSOR` with `viewer_id`). Use a `MultiViewerHost` to
+relay one viewer's pointer to the others; pair with the chat channel
+for ad-hoc text between operators:
+
+```python
+host = RemoteDesktopHost(
+    token="tok", on_chat=lambda sender, text: print(sender, ":", text),
+)
+host.broadcast_chat("session starts in 30s")
+host.broadcast_viewer_cursor("alice", 200, 300)
+
+viewer = RemoteDesktopViewer(
+    host=..., on_chat=lambda s, t: ...,
+    on_viewer_cursor=lambda vid, x, y: ...,
+)
+viewer.send_chat("ack")
+```
+
+**Relative mouse mode (FPS / CAD).** New input action that sends
+deltas instead of absolute coordinates:
+
+```python
+viewer.send_input({"action": "mouse_move_relative", "dx": 5, "dy": -3})
+```
+
+**Motion-aware capture.** The capture loop now hashes each encoded
+JPEG; identical frames are skipped, so a static desktop produces
+~zero bandwidth. New viewers are seeded with the latest frame on auth
+so they never see a black popup.
+
+**Live stats** (FPS / kbps / totals over a 3-second window):
+
+```python
+viewer.stats()
+# {'fps': 24.3, 'kbps': 4801.2, 'frames': 720.0, 'bytes': 1.8e7, 'uptime': 30.2}
+```
+
+**JPEG sequence recorder (no PyAV needed).** TCP-path session
+capture: each frame written to disk plus `manifest.json` so it can
+be replayed at original cadence:
+
+```python
+from je_auto_control.utils.remote_desktop.jpeg_recorder import (
+    JpegSequenceRecorder,
+)
+rec = JpegSequenceRecorder("~/recordings/2026-05-23")
+rec.start()
+viewer = RemoteDesktopViewer(host=..., on_frame=rec.record_frame)
+# ... session ...
+rec.stop()  # writes manifest.json next to the .jpg files
+```
+
+**TCP relay (WebRTC fallback).** When P2P fails (strict NAT, mobile
+CGNAT, hotel Wi-Fi), both peers connect outbound to a relay and
+exchange a shared 32-byte session ID; the relay pipes bytes between
+them. Same module ships an `encode_handshake(role, session_id)`
+helper for clients:
+
+```python
+from je_auto_control.utils.remote_desktop.relay import RelayServer
+relay = RelayServer(bind="0.0.0.0", port=9000)  # NOSONAR  # public relay
+relay.start()
+```
+
+**Service installer (unattended host).** `python -m
+je_auto_control.utils.remote_desktop.host_service ...`
+exposes `configure` / `init` / `run` plus per-platform installers:
+`install-windows-service` / `uninstall-windows-service` (pywin32),
+`generate-launchd` / `uninstall-launchd`, `generate-systemd` /
+`uninstall-systemd`.
+
 **Encrypted transports + alternate protocols.** Pass an `ssl_context`
 to either `RemoteDesktopHost` or `RemoteDesktopViewer` to wrap every
 connection in TLS. For firewall-friendly access, use the in-tree

README/README_zh-CN.md

@@ -552,13 +552,133 @@ viewer.send_input({"action": "type", "text": "hello"})
 viewer.disconnect()
 ```
 
-GUI：**Remote Desktop** 分页，内含两个子分页。
-
-- **Host**（被远程的本机）— Token 字段附 *生成* 按钮、bind 地址安全提示、启动 / 停止控制、实时刷新的 port + viewer 数量状态栏，以及 4fps 预览面板让被远程的人看到 viewer 看到的画面。
-- **Viewer**（控制他机）— 地址 / port / token 表单、*连接* / *断开*、自绘 frame display widget，会把 JPEG 等比缩放绘入。display 上的鼠标 / 滚轮 / 键盘事件会用最新 frame 的尺寸映射回原始远程屏幕的像素坐标，再用 `INPUT` 消息发回。
+GUI：**Remote Desktop** 分页默认打开的是 **快速连线**（AnyDesk 风格）— 一边是超大本机 Host ID，另一边一个输入框接受 `host:port`、`ws://`、`wss://` 或 9 位数字 Host ID，搭配 *连接* 与 *开始被远程* 两个主要按钮。近期连线会跨 session 记住。进阶的逐传输子分页（既有 TCP / WS host + viewer、WebRTC host + viewer 含手动 SDP / 自定义编码器 / TLS pinning）仍只差一个 click。WebRTC 子分页采延迟载入，没装 `[webrtc]` extra 也能正常开启整个分页。
 
 > ⚠️ 取得 host:port 与 token 的人，等同拥有本机完整鼠标 / 键盘控制权。默认仅绑 `127.0.0.1`；要对外暴露请务必搭配 SSH tunnel 或 TLS 前端。Token 是唯一防线 — 请当作密码保管。
 
+**快速连线的 headless API**。撑起 GUI 输入框的 transport coordinator 也对外开放，脚本可以走同样的解析路径：
+
+```python
+from je_auto_control import parse_remote_desktop_target
+parse_remote_desktop_target("192.168.1.10:5555")
+# ConnectTarget(kind='tcp', host='192.168.1.10', port=5555, ...)
+parse_remote_desktop_target("ws://hub:8765/desk")
+# ConnectTarget(kind='ws', host='hub', port=8765, path='/desk')
+parse_remote_desktop_target("123-456-789")
+# ConnectTarget(kind='webrtc_id', host_id='123456789')
+```
+
+**连接审批 + 仅检视模式**。可选 callback 守住每一个 incoming session，AnyDesk 风格。返回 `"view_only"` admit 但丢掉 viewer 的 `INPUT`；返回 falsy（或 raise）就送 `AUTH_FAIL "rejected by host"`：
+
+```python
+from je_auto_control import RemoteDesktopHost, PendingViewer
+
+def gate(p: PendingViewer) -> str:
+    if p.address[0].startswith("10."):
+        return "view_only"
+    return "full"  # 或 True
+
+host = RemoteDesktopHost(token="tok", on_pending_viewer=gate)
+```
+
+**IP 白名单（CIDR + 单一 IP）**。在 TLS / auth 之前就拒绝范围外的对端，攻击者连探测都不行：
+
+```python
+host = RemoteDesktopHost(
+    token="tok", ip_allowlist=["10.0.0.0/8", "192.168.1.100"],
+)
+```
+
+**一次性分享码** — 额外的 token，认证成功一次后自毁；客服支援流程很好用：
+
+```python
+host = RemoteDesktopHost(token="tok", single_use_tokens=["abc123"])
+host.add_single_use_token("9k4ndx")    # 运行时加
+host.revoke_single_use_token("abc123") # 还没被用就先撤销
+```
+
+**TOTP 2FA（RFC 6238，纯 stdlib）**。在 token 之上加一层 6 位数字 OTP；host 接受 ±1 时间步的 clock drift：
+
+```python
+from je_auto_control.utils.remote_desktop.totp import (
+    generate_secret, generate_code, provisioning_uri,
+)
+secret = generate_secret()
+print(provisioning_uri(secret, account="alice"))  # 给 QR code 用的 otpauth:// URI
+
+host = RemoteDesktopHost(token="tok", totp_secret=secret)
+viewer = RemoteDesktopViewer(
+    host=..., token="tok", totp_code=generate_code(secret),
+)
+```
+
+**多屏幕选择**。指定某一屏幕截取，而非合并虚拟桌面：
+
+```python
+from je_auto_control import list_host_monitors, RemoteDesktopHost
+print(list_host_monitors())
+# [{'index': 0, 'is_combined': True, ...},
+#  {'index': 1, ...},
+#  {'index': 2, ...}]
+host = RemoteDesktopHost(token="tok", monitor_index=1)
+```
+
+**远程光标 overlay**。host 每秒 30 Hz 广播 cursor 位置（静止桌面去重）；viewer 的弹出窗口会在 JPEG 流上叠一个箭头，看得到 host 鼠标位置。可用 `enable_cursor_broadcast=False` 关掉。
+
+**多 viewer 协作光标 + 文字 chat**。两个新 message type（`CHAT` 与 `CURSOR` 带 `viewer_id`）。搭配 `MultiViewerHost` 把一个 viewer 的指针 echo 给其他人；chat channel 给操作者之间临时对话用：
+
+```python
+host = RemoteDesktopHost(
+    token="tok", on_chat=lambda sender, text: print(sender, ":", text),
+)
+host.broadcast_chat("session starts in 30s")
+host.broadcast_viewer_cursor("alice", 200, 300)
+
+viewer = RemoteDesktopViewer(
+    host=..., on_chat=lambda s, t: ...,
+    on_viewer_cursor=lambda vid, x, y: ...,
+)
+viewer.send_chat("ack")
+```
+
+**相对鼠标模式（FPS / CAD）**。新输入 action 送 delta 而非绝对坐标：
+
+```python
+viewer.send_input({"action": "mouse_move_relative", "dx": 5, "dy": -3})
+```
+
+**动态截取**。capture loop 会 hash 每张编码后的 JPEG；重复 frame 直接跳过，所以静止桌面几乎零带宽。新 viewer 在 auth 后立即拿到最新 frame，不会看到一片黑。
+
+**即时统计**（FPS / kbps / 累计 — 3 秒滑动窗口）：
+
+```python
+viewer.stats()
+# {'fps': 24.3, 'kbps': 4801.2, 'frames': 720.0, 'bytes': 1.8e7, 'uptime': 30.2}
+```
+
+**JPEG 序列录影（不需要 PyAV）**。TCP path 的 session 录影：每张 frame 写到磁盘，再加一份 `manifest.json` 让播放器可以原速重放：
+
+```python
+from je_auto_control.utils.remote_desktop.jpeg_recorder import (
+    JpegSequenceRecorder,
+)
+rec = JpegSequenceRecorder("~/recordings/2026-05-23")
+rec.start()
+viewer = RemoteDesktopViewer(host=..., on_frame=rec.record_frame)
+# ... session ...
+rec.stop()  # 在 .jpg 旁边写出 manifest.json
+```
+
+**TCP relay（WebRTC fallback）**。当 P2P 失败（严格 NAT、移动 CGNAT、酒店 Wi-Fi），两端都向 relay 主动连线、交换一个 32-byte session ID，relay 在中间互转 bytes。同一模块附 `encode_handshake(role, session_id)` 给 client 用：
+
+```python
+from je_auto_control.utils.remote_desktop.relay import RelayServer
+relay = RelayServer(bind="0.0.0.0", port=9000)  # NOSONAR  # 对外 relay
+relay.start()
+```
+
+**服务安装器（无人值守 host）**。`python -m je_auto_control.utils.remote_desktop.host_service ...` 提供 `configure` / `init` / `run`，以及每个平台的安装命令：`install-windows-service` / `uninstall-windows-service`（需 pywin32）、`generate-launchd` / `uninstall-launchd`、`generate-systemd` / `uninstall-systemd`。
+
 **加密传输与替代协议**：传 `ssl_context` 给 `RemoteDesktopHost` 或 `RemoteDesktopViewer` 即套上 TLS。要穿墙／给浏览器接，用内置的 WebSocket 版本（无额外依赖），加 `ssl_context` 即 `wss://`：
 
 ```python