[fix] correct video latency measurement and smooth connection RTT

[fix] reduce release log verbosity and enforce single instance
[feat] add connection latency to network statistics
2026-10-15 00:09:39 +08:00 · 2026-09-26 03:15:47 +08:00 · 2026-09-26 02:58:55 +08:00 · 2026-09-26 02:04:18 +08:00 · 2026-09-26 00:39:05 +08:00 · 2026-09-25 23:39:23 +08:00
506 changed files with 35271 additions and 28481 deletions
@@ -8,13 +8,15 @@
 # Dependency manifests and local xmake package recipes are the only project
 # files needed while pre-warming the build image.
 !xmake.lua
-!xmake/
-!xmake/**
-!thirdparty/
-!thirdparty/**
-!submodules/
-!submodules/xmake.lua
-!submodules/minirtc/
-!submodules/minirtc/xmake.lua
-!submodules/minirtc/thirdparty/
-!submodules/minirtc/thirdparty/**
+!apps/
+!apps/desktop/
+!apps/desktop/xmake/
+!apps/desktop/xmake/**
+!deps/thirdparty/
+!deps/thirdparty/**
+!deps/submodules/
+!deps/submodules/xmake.lua
+!deps/submodules/minirtc/
+!deps/submodules/minirtc/xmake.lua
+!deps/submodules/minirtc/thirdparty/
+!deps/submodules/minirtc/thirdparty/**
@@ -11,11 +11,11 @@ on:
      - docker/linux-build/**
      - xmake.lua
      - xmake/**
-      - thirdparty/**
-      - submodules/xmake.lua
-      - submodules/minirtc
-      - submodules/minirtc/xmake.lua
-      - submodules/minirtc/thirdparty/**
+      - deps/thirdparty/**
+      - deps/submodules/xmake.lua
+      - deps/submodules/minirtc
+      - deps/submodules/minirtc/xmake.lua
+      - deps/submodules/minirtc/thirdparty/**
  workflow_dispatch:

 permissions:
@@ -36,12 +36,12 @@ jobs:
          - arch: amd64
            runner: ubuntu-24.04
            image: crossdesk/ubuntu20.04:buildenv-cuda12.6.3-gcc10-cmake3.31.6-pipewire0.3.48-xmake3.0.9-rust1.92.0
-            package_script: ./scripts/linux/pkg_amd64.sh
+            package_script: ./apps/desktop/scripts/linux/pkg_amd64.sh

          - arch: arm64
            runner: ubuntu-24.04-arm
            image: crossdesk/ubuntu20.04:buildenv-cuda12.6.3-gcc10-cmake3.31.6-pipewire0.3.48-xmake3.0.9-rust1.92.0
-            package_script: ./scripts/linux/pkg_arm64.sh
+            package_script: ./apps/desktop/scripts/linux/pkg_arm64.sh

    container:
      image: ${{ matrix.image }}
@@ -138,6 +138,22 @@ jobs:
            --cc=gcc-10 --cxx=g++-10 --root -y
          xmake b -vy --root crossdesk

+      - name: Verify repository and wire boundaries
+        env:
+          XMAKE_GLOBALDIR: /data
+        run: |
+          xmake b -vy --root repository_structure_test
+          xmake b -vy --root crossdesk_wire_test
+          xmake b -vy --root keyboard_state_wire_test
+          xmake run --root repository_structure_test
+          xmake run --root crossdesk_wire_test
+          xmake run --root keyboard_state_wire_test
+
+      - name: Install Linux headless runtime dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends xvfb xfce4 dbus
+
      - name: Package
        run: |
          chmod +x ${{ matrix.package_script }}
@@ -178,13 +194,13 @@ jobs:
            runner: macos-26-intel
            cache-key: intel-macos26-xcode26.6-min14
            out-dir: ./build/macosx/x86_64/release/crossdesk
-            package_script: ./scripts/macosx/pkg_x64.sh
+            package_script: ./apps/desktop/scripts/macos/pkg_x64.sh
          - arch: arm64
            binary_arch: arm64
            runner: macos-26
            cache-key: arm-macos26-xcode26.6-min14
            out-dir: ./build/macosx/arm64/release/crossdesk
-            package_script: ./scripts/macosx/pkg_arm64.sh
+            package_script: ./apps/desktop/scripts/macos/pkg_arm64.sh

    steps:
      - name: Extract version number
@@ -260,7 +276,7 @@ jobs:

      - name: Build CrossDesk
        run: |
-          xmake f --target_minver=${MACOSX_DEPLOYMENT_TARGET} --CROSSDESK_VERSION=${VERSION_NUM} --USE_CUDA=false -y
+          xmake f --target_minver=${MACOSX_DEPLOYMENT_TARGET} --CROSSDESK_VERSION=${VERSION_NUM} --USE_CUDA=false -vyD
          xmake b -vy crossdesk

      - name: Package CrossDesk app
@@ -282,7 +298,7 @@ jobs:
            exit 1
          fi

-          ./scripts/macosx/verify_app.sh "${APP_PATH}" "${{ matrix.binary_arch }}" "${EXPECTED_MACOS_SDK}"
+          ./apps/desktop/scripts/macos/verify_app.sh "${APP_PATH}" "${{ matrix.binary_arch }}" "${EXPECTED_MACOS_SDK}"

      - name: Upload build artifacts
        uses: actions/upload-artifact@v6
@@ -295,6 +311,200 @@ jobs:
          mkdir -p release
          cp crossdesk-macos-${{ matrix.arch }}-${{ env.VERSION_NUM }}.pkg release/

+  # iOS
+  build-ios:
+    name: Build on iOS (arm64)
+    runs-on: macos-26
+    timeout-minutes: 120
+    outputs:
+      version: ${{ steps.ios_version.outputs.version }}
+    env:
+      IOS_DEPLOYMENT_TARGET: "16.0"
+      EXPECTED_IOS_SDK: "26.5"
+      XMAKE_VERSION: "3.1.1"
+      XMAKE_REPO_REVISION: "121109352da272cd1a3d4ed52f2dcda34f839955"
+
+    steps:
+      - name: Extract version number
+        shell: bash
+        run: |
+          VERSION_REF="${GITHUB_REF##*/}"
+          VERSION_BASE="${VERSION_REF#v}"
+          BUILD_DATE=$(TZ=Asia/Shanghai date +%Y%m%d)
+          PATCH_NUMBER="${{ github.event.inputs.patch }}"
+
+          if [[ ! "${PATCH_NUMBER}" =~ ^[0-9]+$ ]]; then
+            PATCH_NUMBER=0
+          fi
+
+          if [[ "${VERSION_BASE}" =~ ^([0-9]+(\.[0-9]+){1,3})-([0-9]+)-([0-9]{8})$ ]]; then
+            VERSION_BASE="${BASH_REMATCH[1]}"
+            PATCH_NUMBER="${BASH_REMATCH[3]}"
+            BUILD_DATE="${BASH_REMATCH[4]}"
+          elif [[ "${VERSION_BASE}" =~ ^([0-9]+(\.[0-9]+){1,3})-([0-9]{8})-([0-9]+)$ ]]; then
+            VERSION_BASE="${BASH_REMATCH[1]}"
+            BUILD_DATE="${BASH_REMATCH[3]}"
+            PATCH_NUMBER="${BASH_REMATCH[4]}"
+          elif [[ "${VERSION_BASE}" =~ ^([0-9]+(\.[0-9]+){1,3})-([0-9]{8})$ ]]; then
+            VERSION_BASE="${BASH_REMATCH[1]}"
+            BUILD_DATE="${BASH_REMATCH[3]}"
+          elif [[ "${VERSION_BASE}" =~ ^([0-9]+(\.[0-9]+){1,3})-([0-9]+)$ && "${PATCH_NUMBER}" == "0" ]]; then
+            VERSION_BASE="${BASH_REMATCH[1]}"
+            PATCH_NUMBER="${BASH_REMATCH[3]}"
+          fi
+
+          if [[ "${PATCH_NUMBER}" != "0" ]]; then
+            VERSION_NUM="v${VERSION_BASE}-${PATCH_NUMBER}-${BUILD_DATE}"
+          else
+            VERSION_NUM="v${VERSION_BASE}-${BUILD_DATE}"
+          fi
+
+          echo "VERSION_NUM=${VERSION_NUM}" >> "${GITHUB_ENV}"
+          echo "VERSION_NUM=${VERSION_NUM}"
+
+      - name: Select Xcode 26.6
+        shell: bash
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.6.app/Contents/Developer
+          xcodebuild -version
+          SDK_VERSION="$(xcrun --sdk iphoneos --show-sdk-version)"
+          if [[ "${SDK_VERSION}" != "${EXPECTED_IOS_SDK}" ]]; then
+            echo "Unexpected iOS SDK: expected ${EXPECTED_IOS_SDK}, got ${SDK_VERSION}" >&2
+            exit 1
+          fi
+
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Read independent iOS version
+        id: ios_version
+        shell: bash
+        run: |
+          IOS_VERSION_BASE="$(xcodebuild \
+            -project apps/ios/CrossDeskMobile.xcodeproj \
+            -scheme CrossDeskMobile \
+            -configuration Release \
+            -destination 'generic/platform=iOS' \
+            -showBuildSettings CODE_SIGNING_ALLOWED=NO | \
+            awk '$1 == "MARKETING_VERSION" && $2 == "=" { print $3 }')"
+          if [[ ! "${IOS_VERSION_BASE}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Invalid iOS marketing version: ${IOS_VERSION_BASE}" >&2
+            exit 1
+          fi
+          VERSION_NUM="v${IOS_VERSION_BASE}-${VERSION_NUM##*-}"
+          echo "IOS_VERSION_BASE=${IOS_VERSION_BASE}" >> "${GITHUB_ENV}"
+          echo "VERSION_NUM=${VERSION_NUM}" >> "${GITHUB_ENV}"
+          echo "version=${VERSION_NUM}" >> "${GITHUB_OUTPUT}"
+
+      - name: Initialize submodules
+        run: git submodule update --init --recursive
+
+      - name: Cache xmake dependencies
+        uses: actions/cache@v5
+        with:
+          path: apps/ios/.xmake/packages
+          key: "${{ runner.os }}-xmake${{ env.XMAKE_VERSION }}-deps-ios-arm64-xcode26.6-xrepo1211093-min16-${{ github.run_id }}"
+          restore-keys: |
+            ${{ runner.os }}-xmake${{ env.XMAKE_VERSION }}-deps-ios-arm64-xcode26.6-xrepo1211093-min16-
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install xmake
+        uses: xmake-io/github-action-setup-xmake@v1
+        with:
+          xmake-version: "${{ env.XMAKE_VERSION }}"
+
+      - name: Verify xmake version
+        shell: bash
+        run: |
+          XMAKE_VERSION_OUTPUT="$(xmake --version)"
+          echo "${XMAKE_VERSION_OUTPUT}"
+          if [[ "${XMAKE_VERSION_OUTPUT}" != *"xmake v${XMAKE_VERSION}"* ]]; then
+            echo "Unexpected xmake version: expected ${XMAKE_VERSION}" >&2
+            exit 1
+          fi
+
+      - name: Pin xmake package repository
+        shell: bash
+        run: |
+          xmake repo -u
+          XMAKE_REPO_DIR="${HOME}/.xmake/repositories/xmake-repo"
+          git -C "${XMAKE_REPO_DIR}" fetch --depth=1 origin "${XMAKE_REPO_REVISION}"
+          git -C "${XMAKE_REPO_DIR}" checkout --detach "${XMAKE_REPO_REVISION}"
+          test "$(git -C "${XMAKE_REPO_DIR}" rev-parse HEAD)" = "${XMAKE_REPO_REVISION}"
+
+      - name: Build CrossDesk Mobile
+        shell: bash
+        run: |
+          DERIVED_DATA="${RUNNER_TEMP}/CrossDeskMobileDerivedData"
+          echo "DERIVED_DATA=${DERIVED_DATA}" >> "${GITHUB_ENV}"
+          xcodebuild \
+            -project apps/ios/CrossDeskMobile.xcodeproj \
+            -scheme CrossDeskMobile \
+            -configuration Release \
+            -destination 'generic/platform=iOS' \
+            -derivedDataPath "${DERIVED_DATA}" \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGNING_REQUIRED=NO \
+            COMPILER_INDEX_STORE_ENABLE=NO \
+            IPHONEOS_DEPLOYMENT_TARGET="${IOS_DEPLOYMENT_TARGET}" \
+            build
+
+      - name: Verify CrossDesk Mobile
+        shell: bash
+        run: |
+          APP_PATH="${DERIVED_DATA}/Build/Products/Release-iphoneos/CrossDeskMobile.app"
+          EXECUTABLE_PATH="${APP_PATH}/CrossDeskMobile"
+          INFO_PLIST="${APP_PATH}/Info.plist"
+
+          if [[ ! -x "${EXECUTABLE_PATH}" ]]; then
+            echo "CrossDeskMobile executable is missing from ${APP_PATH}" >&2
+            exit 1
+          fi
+
+          xcrun lipo "${EXECUTABLE_PATH}" -verify_arch arm64
+          APP_VERSION=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "${INFO_PLIST}")
+          if [[ "${APP_VERSION}" != "${IOS_VERSION_BASE}" ]]; then
+            echo "Unexpected iOS app version: expected ${IOS_VERSION_BASE}, got ${APP_VERSION}" >&2
+            exit 1
+          fi
+          MINIMUM_OS=$(/usr/libexec/PlistBuddy -c 'Print :MinimumOSVersion' "${INFO_PLIST}")
+          if [[ "${MINIMUM_OS}" != "${IOS_DEPLOYMENT_TARGET}" ]]; then
+            echo "Unexpected minimum iOS version: expected ${IOS_DEPLOYMENT_TARGET}, got ${MINIMUM_OS}" >&2
+            exit 1
+          fi
+
+          xcrun lipo -info "${EXECUTABLE_PATH}"
+          echo "Minimum iOS version: ${MINIMUM_OS}"
+
+      - name: Package CrossDesk Mobile
+        shell: bash
+        run: |
+          APP_PATH="${DERIVED_DATA}/Build/Products/Release-iphoneos/CrossDeskMobile.app"
+          PACKAGE_DIR="${RUNNER_TEMP}/crossdesk-ios-arm64-unsigned-${VERSION_NUM}"
+          PACKAGE_FILE="${GITHUB_WORKSPACE}/crossdesk-ios-arm64-unsigned-${VERSION_NUM}.zip"
+
+          mkdir -p "${PACKAGE_DIR}"
+          cp -R "${APP_PATH}" "${PACKAGE_DIR}/"
+
+          DSYM_PATH="${DERIVED_DATA}/Build/Products/Release-iphoneos/CrossDeskMobile.app.dSYM"
+          if [[ -d "${DSYM_PATH}" ]]; then
+            cp -R "${DSYM_PATH}" "${PACKAGE_DIR}/"
+          fi
+
+          ditto -c -k --sequesterRsrc --keepParent "${PACKAGE_DIR}" "${PACKAGE_FILE}"
+          echo "PACKAGE_FILE=${PACKAGE_FILE}" >> "${GITHUB_ENV}"
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: crossdesk-ios-arm64-unsigned-${{ env.VERSION_NUM }}
+          path: ${{ env.PACKAGE_FILE }}
+          if-no-files-found: error
+
  # Windows
  build-windows-x64:
    name: Build on Windows x64
@@ -404,7 +614,7 @@ jobs:
      - name: Copy nsProcess plugin to NSIS folder
        run: |
          $nsisPluginDir = "C:\Program Files (x86)\NSIS\Plugins\x86-unicode"
-          copy "${{ github.workspace }}\scripts\windows\nsProcess.dll" $nsisPluginDir
+          copy "${{ github.workspace }}\apps\desktop\scripts\windows\nsProcess.dll" $nsisPluginDir

      - name: Build CrossDesk
        run: |
@@ -414,14 +624,14 @@ jobs:
      - name: Package
        shell: pwsh
        run: |
-          & "${{ github.workspace }}\scripts\windows\pkg_x64.ps1" $env:VERSION_NUM
+          & "${{ github.workspace }}\apps\desktop\scripts\windows\pkg_x64.ps1" $env:VERSION_NUM

      - name: Upload unsigned Windows installer for test signing
        if: github.event_name == 'workflow_dispatch' && inputs.sign_windows_test
        id: upload-unsigned-windows-installer
        uses: actions/upload-artifact@v7
        with:
-          path: ${{ github.workspace }}/scripts/windows/crossdesk-win-x64-${{ env.VERSION_NUM }}.exe
+          path: ${{ github.workspace }}/apps/desktop/scripts/windows/crossdesk-win-x64-${{ env.VERSION_NUM }}.exe
          archive: false
          if-no-files-found: error
          retention-days: 1
@@ -447,7 +657,7 @@ jobs:
        run: |
          $installerName = "crossdesk-win-x64-${{ env.VERSION_NUM }}.exe"
          $signedInstaller = Join-Path "${{ github.workspace }}\signpath\signed-installer" $installerName
-          $destination = Join-Path "${{ github.workspace }}\scripts\windows" $installerName
+          $destination = Join-Path "${{ github.workspace }}\apps\desktop\scripts\windows" $installerName

          if (!(Test-Path $signedInstaller)) {
            throw "SignPath did not return the signed installer: $signedInstaller"
@@ -477,7 +687,9 @@ jobs:
          $portableFiles = @(
            @("crossdesk.exe", "CrossDesk.exe"),
            @("crossdesk_service.exe", "crossdesk_service.exe"),
-            @("crossdesk_session_helper.exe", "crossdesk_session_helper.exe")
+            @("crossdesk_session_helper.exe", "crossdesk_session_helper.exe"),
+            @("crossdesk_privacy_cursor_helper.exe", "crossdesk_privacy_cursor_helper.exe"),
+            @("crossdesk_privacy_window.dll", "crossdesk_privacy_window.dll")
          )

          foreach ($file in $portableFiles) {
@@ -491,6 +703,13 @@ jobs:

          Copy-Item (Join-Path $buildDir "*.dll") $portableDir -Force

+          # Bundled Amyuni usbmmidd_v2 virtual display driver (headless hosts)
+          $driverDir = Join-Path $buildDir "usbmmidd_v2"
+          if (!(Test-Path (Join-Path $driverDir "deviceinstaller64.exe"))) {
+            throw "Missing bundled usbmmidd_v2 driver package: $driverDir"
+          }
+          Copy-Item $driverDir (Join-Path $portableDir "usbmmidd_v2") -Recurse -Force
+
          foreach ($file in $portableFiles) {
            $packagedFile = Join-Path $portableDir $file[1]
            if (!(Test-Path $packagedFile)) {
@@ -504,7 +723,7 @@ jobs:
        uses: actions/upload-artifact@v6
        with:
          name: crossdesk-win-x64-${{ env.VERSION_NUM }}
-          path: ${{ github.workspace }}/scripts/windows/crossdesk-win-x64-${{ env.VERSION_NUM }}.exe
+          path: ${{ github.workspace }}/apps/desktop/scripts/windows/crossdesk-win-x64-${{ env.VERSION_NUM }}.exe

      - name: Upload portable artifact
        uses: actions/upload-artifact@v6
@@ -515,7 +734,7 @@ jobs:
  release:
    name: Publish Release
    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build-linux, build-macos, build-windows-x64]
+    needs: [build-linux, build-macos, build-ios, build-windows-x64]
    runs-on: ubuntu-latest

    steps:
@@ -571,6 +790,25 @@ jobs:
          echo "BUILD_DATE_ISO=${BUILD_DATE_ISO}" >> $GITHUB_OUTPUT
          echo "PATCH_NUMBER=${PATCH_NUMBER}" >> $GITHUB_OUTPUT

+      - name: Prepare release notes
+        env:
+          RELEASE_TAG: ${{ steps.version.outputs.VERSION_WITH_V }}
+          VERSION_BASE: ${{ steps.version.outputs.VERSION_BASE }}
+        run: |
+          if [[ -f "docs/releases/${RELEASE_TAG}.md" ]]; then
+            cp "docs/releases/${RELEASE_TAG}.md" release-notes.md
+          elif [[ -f "docs/releases/v${VERSION_BASE}.md" ]]; then
+            cp "docs/releases/v${VERSION_BASE}.md" release-notes.md
+          else
+            cat > release-notes.md << 'EOF'
+          Binary release only. Source code is not included.
+
+          ## Code signing policy
+
+          Free code signing provided by [SignPath.io](https://signpath.io/), certificate by [SignPath Foundation](https://signpath.org/).
+          EOF
+          fi
+
      - name: Rename artifacts
        run: |
          mkdir -p release
@@ -578,6 +816,7 @@ jobs:
          cp artifacts/crossdesk-macos-arm64-${{ steps.version.outputs.VERSION_WITH_V }}/* release/crossdesk-macos-arm64-${{ steps.version.outputs.VERSION_WITH_V }}.pkg
          cp artifacts/crossdesk-linux-amd64-${{ steps.version.outputs.VERSION_WITH_V }}/* release/crossdesk-linux-amd64-${{ steps.version.outputs.VERSION_WITH_V }}.deb
          cp artifacts/crossdesk-linux-arm64-${{ steps.version.outputs.VERSION_WITH_V }}/* release/crossdesk-linux-arm64-${{ steps.version.outputs.VERSION_WITH_V }}.deb
+          cp artifacts/crossdesk-ios-arm64-unsigned-${{ needs.build-ios.outputs.version }}/* release/crossdesk-ios-arm64-unsigned-${{ needs.build-ios.outputs.version }}.zip
          cp artifacts/crossdesk-win-x64-${{ steps.version.outputs.VERSION_WITH_V }}/* release/crossdesk-win-x64-${{ steps.version.outputs.VERSION_WITH_V }}.exe
          cp artifacts/crossdesk-win-x64-portable-${{ steps.version.outputs.VERSION_WITH_V }}/* release/crossdesk-win-x64-portable-${{ steps.version.outputs.VERSION_WITH_V }}.zip

@@ -588,17 +827,13 @@ jobs:
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ steps.version.outputs.VERSION_WITH_V }}
+          target_commitish: ${{ github.sha }}
          name: Release ${{ steps.version.outputs.VERSION_WITH_V }}
          draft: false
          prerelease: false
          files: release/*
          generate_release_notes: false
-          body: |
-            Binary release only. Source code is not included.
-
-            ## Code signing policy
-
-            Free code signing provided by [SignPath.io](https://signpath.io/), certificate by [SignPath Foundation](https://signpath.org/).
+          body_path: release-notes.md

      - name: Create or update 'latest' tag
        run: |
@@ -616,12 +851,7 @@ jobs:
          prerelease: false
          files: release/*
          generate_release_notes: false
-          body: |
-            Binary release only. Source code is not included.
-
-            ## Code signing policy
-
-            Free code signing provided by [SignPath.io](https://signpath.io/), certificate by [SignPath Foundation](https://signpath.org/).
+          body_path: release-notes.md

      - name: Upload artifacts to server
        uses: burnett01/rsync-deployments@5.2
@@ -672,6 +902,11 @@ jobs:
            }
          }
          EOF
+          jq --arg release_name "Release ${{ steps.version.outputs.VERSION_WITH_V }}" \
+            --rawfile release_notes release-notes.md \
+            '.releaseName = $release_name | .releaseNotes = $release_notes' \
+            version.json > version-with-notes.json
+          mv version-with-notes.json version.json
          cat version.json

      - name: Upload version.json to server
@@ -1,9 +1,14 @@
 # Xmake cache
 .xmake/
 build/
+apps/ios/Vendor/
+apps/ios/DerivedData*/
+apps/ios/.xmake/
+xcuserdata/
+*.xcuserstate

 # MacOS Cache
 .DS_Store

 # VSCode cache
-.vscode
+.vscode
@@ -1,3 +1,3 @@
-[submodule "submodules/minirtc"]
-	path = submodules/minirtc
+[submodule "deps/submodules/minirtc"]
+	path = deps/submodules/minirtc
 	url = https://github.com/kunkundi/minirtc.git
@@ -1,429 +1,232 @@
-# CrossDesk
+<div align="center">
+  <img src="apps/desktop/resources/linux/crossdesk_128x128.png" width="80" alt="CrossDesk 标志" />
+  <h1>CrossDesk</h1>
+  <p>轻量、跨平台的远程桌面，让电脑、浏览器和 iPhone / iPad 连接到同一张桌面。</p>
+  <p><a href="https://www.crossdesk.cn/">官方网站</a> · <a href="https://github.com/kunkundi/crossdesk/releases">下载客户端</a> · <a href="https://web.crossdesk.cn/">打开 Web 客户端</a> · <a href="README_EN.md">English</a></p>
+</div>

-<a href="https://hellogithub.com/repository/kunkundi/crossdesk" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=55d41367570345f1838e02fd12be7961&claim_uid=cb0OpZRrBuGVAfL&theme=small" alt="Featured｜HelloGitHub" /></a>
+<div align="center">

-[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-brightgreen.svg)](https://www.crossdesk.cn/)
-[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![GitHub last commit](https://img.shields.io/github/last-commit/kunkundi/crossdesk)](https://github.com/kunkundi/crossdesk/commits/web-client)
-[![Build Status](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml/badge.svg)](https://github.com/kunkundi/crossdesk/actions)  
-[![Docker Pulls](https://img.shields.io/docker/pulls/crossdesk/crossdesk-server)](https://hub.docker.com/r/crossdesk/crossdesk-server/tags)
-[![GitHub issues](https://img.shields.io/github/issues/kunkundi/crossdesk.svg)](https://github.com/kunkundi/crossdesk/issues)
-[![GitHub stars](https://img.shields.io/github/stars/kunkundi/crossdesk.svg?style=social)](https://github.com/kunkundi/crossdesk/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/kunkundi/crossdesk.svg?style=social)](https://github.com/kunkundi/crossdesk/forks)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20iOS-blue)](#download)
+[![Release](https://img.shields.io/github/v/release/kunkundi/crossdesk)](https://github.com/kunkundi/crossdesk/releases)
+[![Build](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml/badge.svg)](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml)
+[![License: GPL v3](https://img.shields.io/badge/license-GPL--3.0-blue)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/kunkundi/crossdesk?style=social)](https://github.com/kunkundi/crossdesk/stargazers)

-[ [English](README_EN.md) / 中文 ]
+</div>

---
+CrossDesk 支持 Windows、macOS、Linux 之间的远程访问，也可从浏览器或原生 iOS 客户端控制电脑。项目基于 [MiniRTC](https://github.com/kunkundi/minirtc)，提供实时音视频传输、键鼠控制、文件传输与自托管能力，仍在持续开发中。
+
+> 本文按当前仓库代码整理。截图展示当前 Slint 桌面界面，使用演示 ID、密码、在线状态和连接记录；缩略图来自公开页面；下载包的功能与系统要求请同时核对对应 Release 说明。原生 iOS 客户端的构建、签名方式见下文。
+
+[界面预览](#preview) · [下载与安装](#download) · [快速连接](#quick-start) · [会话操作](#session) · [设置](#settings) · [iOS](#ios) · [自托管](#self-hosting) · [源码构建](docs/BUILD.md) · [常见问题](docs/FAQ.md)
+
+<a id="preview"></a>

 ## 界面预览

-### PC 客户端
+### 桌面客户端

-![sup_example](https://github.com/user-attachments/assets/eeb64fbe-1f07-4626-be1c-b77396beb905)
+主窗口集中展示本机 ID、连接密码、远程连接入口和近期连接记录。
+
+<p align="center">
+  <img src="docs/images/desktop-main-zh.png" width="800" alt="当前桌面客户端示例：已连接服务器，三台在线设备均显示页面缩略图" />
+</p>

 ### Web 客户端

+在浏览器中输入远程设备 ID 和密码，无需在控制端安装桌面客户端。
+
 <p align="center">
-  <img width="850" height="550" alt="6bddcbed47ffd4b9988a4037c7f4f524" src="https://github.com/user-attachments/assets/e44f73f9-24ac-46a3-a189-b7f8b6669881" />
+  <img src="docs/images/web-client.png" width="800" alt="CrossDesk Web 客户端当前连接首页" />
 </p>

---
+图片来源与更新方式见 [截图说明](docs/images/README.md)。

-## 简介
+## 主要功能

-CrossDesk 是一个轻量级的跨平台远程桌面软件，支持 Web 端控制远程设备。
-
-CrossDesk 是 [MiniRTC](https://github.com/kunkundi/minirtc.git) 实时音视频传输库的实验性应用。MiniRTC 是一个轻量级的跨平台实时音视频传输库。它具有网络透传（[RFC5245](https://datatracker.ietf.org/doc/html/rfc5245)），视频软硬编解码（H264/AV1），音频编解码（[Opus](https://github.com/xiph/opus)），信令交互，网络拥塞控制，传输加密（[SRTP](https://tools.ietf.org/html/rfc3711)）等基础能力。
-
---
-
-## 系统要求
-
-| 平台 | 最低版本 |
+| 能力 | 当前支持 |
 | --- | --- |
-| **Windows** | Windows 10 及以上 (64 位) |
-| **macOS** | macOS Intel 15.0 及以上 ( 大于 14.0 小于 15.0 的版本可自行编译实现兼容 )<br> macOS Apple Silicon 14.0 及以上 |
-| **Linux** | Ubuntu 20.04 及以上 |
+| 跨平台控制 | Windows / macOS / Linux 桌面互控；浏览器与原生 iOS 作为控制端 |
+| 实时画面与声音 | H.264 / AV1、硬件编解码、远端声音播放；会话中可调整画质、30 / 60 fps 与画面偏好 |
+| 多设备与多显示器 | 近期连接、设备别名、会话标签与远端显示器切换 |
+| 输入与协作 | 键鼠输入、远端光标同步、组合键、文本剪贴板同步、文件传输 |
+| 网络与部署 | P2P 直连、TURN 中继与强制中继、SRTP 媒体加密、自托管信令与中继服务 |
+| 隐私屏 | 被连接时自动开启，或在会话工具栏切换；可用性取决于被控端系统与采集方式 |
+| Windows 锁屏控制 | 通过 CrossDesk Service 支持锁屏、登录界面及安全桌面的输入转发 |
+| Linux 无头运行 | 复用已有桌面和应用，或创建独立 Xvfb 虚拟桌面；终端控制台可查看状态、修改密码和设置，见 [运行说明](docs/HEADLESS.md) |

---
+各客户端的入口和能力有所不同；桌面会话操作见下文，iOS 的具体功能见 [开发说明](apps/ios/README.md)。

-## 使用
+<a id="download"></a>

-在菜单栏“对端ID”处输入远端桌面的ID，点击“→”即可发起远程连接。
+## 下载与安装

-![usage1](https://github.com/user-attachments/assets/3a4bb59f-c84c-44d2-9a20-11790aac510e)
+前往 [GitHub Releases](https://github.com/kunkundi/crossdesk/releases) 或 [官方网站](https://www.crossdesk.cn/)，按系统与 CPU 架构选择安装包。

-如果远端桌面设置了连接密码，则本端需填写正确的连接密码才能成功发起远程连接。
+| 平台 | 当前源码 / CI 基线 | 安装方式 |
+| --- | --- | --- |
+| Windows | Windows 10+，x64 | `.exe` 安装包；便携构建也受支持 |
+| macOS | macOS 14.0+，Intel / Apple Silicon | 选择 x64 或 arm64 的 `.pkg` |
+| Linux | Ubuntu 20.04+，amd64 / arm64，glibc 2.31 基线 | `.deb` 安装包 |
+| iOS / iPadOS | iOS 16.0+，arm64 真机 | 原生客户端；使用 Xcode 构建并签名，CI 产物为未签名应用 |
+| Web | 支持 WebRTC 的浏览器 | 访问 [web.crossdesk.cn](https://web.crossdesk.cn/) |

-![password](https://github.com/user-attachments/assets/1beadcce-640d-4f5c-8e77-51917b5294d5)
+Linux 下载后，在下载目录中将文件名替换为实际安装包名称：

-发起连接前，可在设置中自定义配置项，如语言、视频编码格式等。
-![settings](https://github.com/user-attachments/assets/8bc5468d-7bbb-4e30-95bd-da1f352ac08c)
+```bash
+sudo apt install "./crossdesk-linux-amd64-<version>.deb"
+```

-### 使用 Web 客户端
+**macOS 首次运行：** 按应用提示，在“系统设置 → 隐私与安全性”中授予 CrossDesk **屏幕录制**（新系统可能显示为“屏幕与系统音频录制”）及 **辅助功能**权限，再按系统提示重新打开应用。前者用于捕获桌面，后者用于远程键鼠输入。

-浏览器访问 [CrossDesk Web Client](https://web.crossdesk.cn/)。
-输入 **远程设备 ID** 与 **密码**，点击连接即可接入远程设备。如图，**iOS Safari 远程控制 Win11**：
+<a id="quick-start"></a>

-<img width="645" height="300" alt="_cgi-bin_mmwebwx-bin_webwxgetmsgimg__ MsgID=932911462648581698 skey=@crypt_1f5153b1_b550ca7462b5009ce03c991cca2a92a7 mmweb_appid=wx_webfilehelper" src="https://github.com/user-attachments/assets/a5109e6f-752c-4654-9f4e-7e161bddf43e" />
+## 快速连接

-### Windows 服务（CrossDesk Service）
+### 从另一台电脑连接

-CrossDesk 在 Windows 平台提供本地辅助服务 **CrossDesk Service**，服务名为 `CrossDeskService`。该服务用于锁屏、登录界面和安全桌面等受保护场景下的远程控制增强能力，包括：
+1. **准备被控电脑。** 安装并运行 CrossDesk，等待底部显示“已连接服务器”。在左侧“本桌面”查看 **本机 ID** 和 **密码**，提供给控制端。
+2. **输入对端 ID。** 在控制端右侧“远程桌面 → 对端 ID”输入被控电脑的 ID，点击 **→**。
+3. **完成密码验证。** 按弹窗输入被控电脑当前的连接密码，确认后等待远程画面出现。需要保存密码时勾选“记住密码”。
+4. **再次连接。** 成功连接过的设备会出现在“近期连接”中，可通过卡片重连，也可编辑别名或删除记录。

- 上报远端当前是否处于锁屏、登录、凭据输入或安全桌面状态；
- 支持从控制端发送 `Ctrl+Alt+Del`（SAS）；
- 在锁屏、登录和安全桌面阶段转发键盘、鼠标输入。
+本机密码旁的眼睛按钮用于显示 / 隐藏密码，刷新按钮用于生成新的随机密码，铅笔按钮用于手动修改。密码统一为 **6 位数字或英文字母**。修改或刷新时需保持连接服务器；等待修改成功、客户端重新连接后，再复制当前密码。已保存旧密码的控制端需重新输入。

-Windows 安装包会自动打包 `crossdesk_service.exe` 和 `crossdesk_session_helper.exe`，并在安装时注册为按需启动的 Windows 服务。CrossDesk 客户端启动时会尝试启动已安装的服务；当本机没有 CrossDesk 客户端进程运行时，服务会自动退出。卸载客户端时会同步停止并移除该服务。
+### 从浏览器连接

-如果是手动编译或手动部署 Windows 版本，请确保 `CrossDesk.exe`、`crossdesk_service.exe` 和 `crossdesk_session_helper.exe` 位于同一目录。安装或卸载服务需要使用管理员权限打开 PowerShell：
+1. 保持被控电脑上的 CrossDesk 运行，并确认已连接服务器。
+2. 打开 [Web 客户端](https://web.crossdesk.cn/)，输入 **远程设备 ID** 和 **密码**，点击“连接”。
+3. 连接后使用页面提供的显示器、鼠标模式和键盘控件操作远端；手机和平板也可通过浏览器访问。
+
+如果使用自建服务器，需要让控制端与被控端接入同一服务；Web 部署配置见 [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client)。
+
+<a id="session"></a>
+
+## 会话中的常用操作
+
+远程窗口通过会话标签切换设备，控制栏提供以下操作；控制栏收起时先点击展开按钮。将鼠标悬停在图标上可查看提示。
+
+| 入口 | 用途 |
+| --- | --- |
+| 显示器 | 切换远端显示器 |
+| 键盘 | 发送组合键；Windows 的 `Ctrl+Alt+Del` 依赖远端服务 |
+| 鼠标 | 控制 / 释放远端鼠标 |
+| 扬声器 | 播放声音 / 静音 |
+| 文件夹 | 选择文件发送到远端，并查看传输进度 |
+| 画面设置 | 在当前会话中调整画面质量、采集帧率与画面偏好 |
+| 网络状态 | 查看流量、丢包率、帧率、分辨率、直连 / 中继及加密状态 |
+| 隐私屏 | 开启或关闭被控电脑的隐私屏；悬停查看当前状态与可用操作 |
+| 全屏 | 进入 / 退出全屏 |
+| 断开连接 | 结束当前远程会话 |
+
+桌面端可同步文本剪贴板。接收文件的位置可在“设置 → 文件保存路径”调整。关闭主窗口会隐藏窗口并保持程序运行；需要完全退出时使用系统托盘或菜单栏中的退出入口。
+
+### 在会话中调整画面
+
+连接成功后，点击工具栏中的 **画面设置**（滑杆图标），直接选择低 / 中 / 高画质、**30 / 60 fps**，以及帧率优先 / 画质优先 / 平衡。选项会发送给当前被控端，无需断开重连；实际画面效果取决于网络、设备与编码器能力。旧版被控端不支持时，菜单会提示并禁用选项。
+
+<p align="center">
+  <img src="docs/images/desktop-stream-video-settings-zh.png" width="800" alt="当前远程会话的画面设置菜单：画面质量、采集帧率与画面偏好；背景为公开页面演示图" />
+</p>
+
+<a id="settings"></a>
+
+## 客户端设置与更新
+
+点击主窗口右上角 **☰ → 设置**，修改后点击“确认”保存。编码与连接选项建议在建立连接前调整；会话进行中部分选项不可修改。设置列表可向下滚动，查看自托管、启动方式与文件保存路径。画质、帧率和画面偏好在远程会话工具栏中调整。
+
+<p align="center">
+  <img src="docs/images/desktop-settings-zh.png" width="720" alt="当前客户端设置：编码格式、硬件编解码、中继、强制中继与自动隐私屏" />
+</p>
+
+| 设置 | 说明 |
+| --- | --- |
+| 语言 | 中文、English、Русский |
+| 采集方式（Windows） | 自动 / DXGI / WGC / GDI；无显示器主机使用“自动”启用自动适配 |
+| 视频编码格式 | H.264 / AV1；硬件编解码是否可用取决于平台、硬件与构建选项 |
+| 启用中继服务 | 允许借助 TURN 中继建立连接；P2P 连接失败时先检查此项 |
+| 强制中继连接 | 启用中继服务后可勾选，让连接通过中继建立；关闭中继服务会同时关闭此项 |
+| 被连接时开启隐私屏 | 设置本机被远程连接时是否自动启用隐私屏；会话中可从控制端工具栏切换 |
+| 自托管配置 | 填写服务器地址和信令服务端口，并勾选启用 |
+| 开机自启 / 启用守护进程 | 调整启动与进程守护行为，按界面提示重启后生效 |
+| 文件保存路径 | 选择接收文件的目录 |
+
+### 检查更新
+
+客户端启动后会在后台检查版本。发现新版本时，主窗口菜单入口会显示更新提示；打开 **☰ → 关于** 可查看版本，也可点击 **检查更新** 手动检查。发现更新后可查看更新说明并前往下载页面。
+
+<p align="center">
+  <img src="docs/images/desktop-about-zh.png" width="720" alt="关于窗口与检查更新按钮，版本号和检查结果为演示数据" />
+</p>
+
+<a id="ios"></a>
+
+## 原生 iOS / iPadOS 客户端
+
+仓库的 [`apps/ios`](apps/ios/README.md) 提供原生控制端，与桌面端使用同一套 MiniRTC 协议。它可以控制远端电脑；当前不提供将 iPhone / iPad 作为被控桌面的功能。
+
+1. 按 [iOS 开发说明](apps/ios/README.md) 使用 Xcode 构建并签名，安装到 iOS 16+ 的真机。
+2. 在首页输入对端 ID，点击连接并填写密码；成功连接后可从“最近连接”中重连。
+3. 在设置中选择鼠标模式：**相对位置**像触控板一样移动光标，**绝对位置**将触摸位置直接映射到远端画面。
+4. 点击悬浮图标展开菜单，可切换显示器、显示键盘、控制声音或发送文件。收到的文件位于应用的 `Documents/Received`，可通过传输状态旁的分享按钮导出。
+
+当前支持接收远端文本到 iOS 剪贴板；界面暂未提供主动发送本机剪贴板的按钮。
+
+当前支持单指点击、双指右键、长按拖动与捏合缩放；缩放后的双指平移用于移动视图。原生端与浏览器端分别维护，使用入口和手势可能不同。
+
+<a id="windows-service"></a>
+
+## Windows 锁屏与登录界面
+
+**CrossDesk Service**（服务名 `CrossDeskService`）提供锁屏、登录、凭据输入及安全桌面的状态上报、`Ctrl+Alt+Del` 发送和键鼠输入转发。
+
+安装版会注册按需启动的服务，客户端启动时尝试启动它；本机没有 CrossDesk 客户端进程后服务会自动退出。便携版可在提示窗口或“设置 → 锁屏控制服务”中安装服务，需要管理员权限。该服务依赖客户端运行。
+
+<details>
+<summary>手动部署与服务管理命令</summary>
+
+保留完整安装目录；自行部署构建产物时，将 `CrossDesk.exe`、`crossdesk_service.exe`、`crossdesk_session_helper.exe` 及同次构建输出的全部 `.dll` 放在同一目录。在该目录打开管理员 PowerShell，按需执行：

 ```powershell
-# 安装
 .\CrossDesk.exe --service-install
-# 启动
 .\CrossDesk.exe --service-start
-# 查看状态
 .\CrossDesk.exe --service-status
-# 停止
+.\CrossDesk.exe --service-ping
+# 停止或卸载服务
 .\CrossDesk.exe --service-stop
-# 卸载
 .\CrossDesk.exe --service-uninstall
 ```

-如果远端 Windows 服务未安装、未启动或暂时不可用，基础远程桌面连接仍可使用，但锁屏、登录界面和安全桌面阶段的控制能力会受限，客户端会提示“远端Windows服务不可用”。
+</details>

---
+出现“远端 Windows 服务不可用”时，检查被控电脑的安装和服务状态；普通桌面连接仍可使用，受保护界面的控制能力会受限。

-## 如何编译
-
-### 构建依赖
-
- [xmake](https://xmake.io/#/guide/installation)
- [cmake](https://cmake.org/download/) 3.21 及以上（系统版本过低时由 xmake 自动安装）
-
-### Linux
-
-Linux 构建支持 Ubuntu 20.04 及以上版本的 amd64 和 arm64。发布安装包以
-Ubuntu 20.04/glibc 2.31 为兼容基线。先安装基础编译依赖：
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  git curl unzip build-essential gcc-10 g++-10 python3-pip \
-  pkg-config binutils dpkg-dev \
-  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
-  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
-  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
-  libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxcb-shm0-dev \
-  libasound2-dev libsndio-dev libpulse-dev \
-  libgl1-mesa-dev
-```
-
-Ubuntu 20.04 自带的 CMake 3.16 不满足要求时，xmake 会自动下载并使用
-CMake 3.21 或更高版本，无需手动替换系统 CMake。
-
-Ubuntu 20.04 默认的 GCC 9 缺少 Slint C++ API 所需的部分 C++20 标准库，
-因此上述命令同时安装并在后续配置中指定 GCC 10。
-
-需要启用 Wayland 捕获或 DRM 捕获时，再安装对应依赖：
-
-```bash
-sudo apt-get install -y libdbus-1-dev libdrm-dev
-
-# Ubuntu 22.04 及以上也可以直接安装系统开发包
-# sudo apt-get install -y libpipewire-0.3-dev libspa-0.2-dev
-```
-
-下载子模块并编译 Release 版本：
-
-```bash
-git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
-cd crossdesk
-
-# 已经克隆过仓库时执行这一行
-git submodule update --init --recursive
-
-# Ubuntu 20.04 没有 PipeWire 0.3 开发包，安装仅用于编译的头文件 SDK。
-# 已安装发行版 PipeWire 0.3 开发包时可跳过此步骤。
-sudo ./docker/linux-build/install-pipewire-sdk.sh
-
-xmake f -c -m release --USE_CUDA=false --toolchain=gcc-10 -y
-xmake b -vy crossdesk
-```
-
-这里应使用 `--toolchain=gcc-10`，以确保 CrossDesk 及 xmake 在配置阶段构建的
-libyuv 等第三方包都使用 GCC 10。只指定 `--cc`/`--cxx` 时，依赖安装可能仍回退到
-系统默认的 `/bin/cc` 和 `/bin/c++`。`-c` 会清除旧配置，切换编译器时必须保留。
-
-amd64 构建结果位于 `build/linux/x86_64/release/crossdesk`，arm64 构建结果位于 `build/linux/arm64/release/crossdesk`。
-
-启用 Wayland 和 DRM 的配置示例：
-
-```bash
-xmake f -c -m release --USE_WAYLAND=true --USE_DRM=true --USE_CUDA=false \
-  --toolchain=gcc-10 -y
-xmake b -vy crossdesk
-```
-
-生成 Debian 安装包（必须在对应架构上先完成 Release 编译）：
-
-```bash
-# amd64
-./scripts/linux/pkg_amd64.sh 1.0.0
-
-# arm64
-./scripts/linux/pkg_arm64.sh 1.0.0
-```
-
-打包脚本会将 Slint 共享运行库安装到软件包私有目录 `/usr/lib/crossdesk`，无需用户另外安装 `libslint_cpp.so`。
-PipeWire 不属于强制运行时依赖：程序在运行时检测宿主系统的 PipeWire 0.3，
-没有该运行库时仍可使用 X11（以及构建时启用的 DRM）捕获。
-
-### 通用编译选项
-
-```text
--USE_CUDA=true/false: 启用 CUDA 硬件编解码，默认不启用
--USE_WAYLAND=true/false: 在 Linux 上启用 Wayland/PipeWire 捕获，默认不启用
--USE_DRM=true/false: 在 Linux 上启用 DRM 捕获，默认不启用
--CROSSDESK_PORTABLE=true/false: 构建便携版本，默认不启用
--CROSSDESK_VERSION=xxx: 指定 CrossDesk 的版本
-
-# 示例
-xmake f --CROSSDESK_VERSION=1.0.0 --USE_CUDA=true
-```
-
-运行：
-
-```bash
-xmake r crossdesk
-```
-
-### 无 CUDA 环境下的开发支持
-
-对于**未安装 CUDA 环境的 Linux 开发者，如果希望编译后的成果物拥有硬件编解码能力**，这里提供了预配置的 [Ubuntu 20.04 兼容构建镜像](https://hub.docker.com/r/crossdesk/ubuntu20.04)。该镜像内置必要的构建依赖，可生成兼容 glibc 2.31 的单一 Linux 安装包。
-
-进入容器，下载工程后执行：
-
-```bash
-export CUDA_PATH=/usr/local/cuda
-export XMAKE_GLOBALDIR=/data
-
-xmake f --USE_CUDA=true
-xmake b --root -vy crossdesk
-```
-
-对于**未安装 CUDA 环境的 Windows 开发者**，执行下面的命令安装 CUDA 编译环境：
-
-```powershell
-xmake require -vy "cuda 12.6.3"
-```
-
-安装完成后执行:
-
-```powershell
-xmake require --info "cuda 12.6.3"
-```
-
-输出如下:
-
-<img width="860" height="226" alt="Image" src="https://github.com/user-attachments/assets/999ac365-581a-4b9a-806e-05eb3e4cf44d" />
-
-根据上述输出获取到 CUDA 的安装目录，即 installdir 指向的位置。将 CUDA_PATH 加入系统环境变量，或在终端中输入：
-
-```powershell
-set CUDA_PATH=path_to_cuda_installdir
-```
-
-重新执行：
-
-```powershell
-xmake f --USE_CUDA=true
-xmake b -vy crossdesk
-```
-
-#### 注意
-
-运行时如果客户端状态栏显示 **未连接服务器**，请先在 [CrossDesk 官方网站](https://www.crossdesk.cn/) 安装客户端，以便在环境中安装所需的证书文件。
-
-<img width="256" height="120" alt="image" src="https://github.com/user-attachments/assets/1812f7d6-516b-4b4f-8a3d-98bee505cc5a" />
-
-### 关于 Xmake
-
-#### 安装 Xmake
-
-使用 curl：
-
-```bash
-curl -fsSL https://xmake.io/shget.text | bash
-```
-
-使用 wget：
-
-```bash
-wget https://xmake.io/shget.text -O - | bash
-```
-
-使用 powershell：
-
-```powershell
-irm https://xmake.io/psget.text | iex
-```
-
-#### 编译选项
-
-```text
-# 切换编译模式
-xmake f -m debug/release
-
-# 可选编译参数
-r ：重新构建目标
-v ：显示详细的构建日志
-y ：自动确认提示
-
-# 示例
-xmake b -vy crossdesk
-```
-
-#### 运行选项
-
-```bash
-# 使用调试模式运行
-xmake r -d crossdesk
-```
-
-更多使用方法可参考 [Xmake 官方文档](https://xmake.io/guide/quick-start.html)。
-
---
+<a id="self-hosting"></a>

 ## 自托管服务器

-### 服务端
+可自行部署信令服务与 TURN 中继，并在桌面客户端 **☰ → 设置 → 自托管配置** 中填写连接信息。控制端与被控端都需要启用同一套配置。

-推荐使用 Docker 部署 CrossDesk Server。
+- [自托管指南](docs/SELF_HOSTING.md)：当前 Compose 部署入口、客户端设置、证书信任与排查。
+- [CrossDesk Server](https://github.com/kunkundi/crossdesk-server)：服务端源码与发布配置。
+- [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client)：浏览器端源码与自托管说明。

-```bash
-sudo docker run -d \
-  --name crossdesk_server \
-  --network host \
-  -e EXTERNAL_IP=xxx.xxx.xxx.xxx \
-  -e INTERNAL_IP=xxx.xxx.xxx.xxx \
-  -e CROSSDESK_SERVER_PORT=xxxx \
-  -e COTURN_PORT=xxxx \
-  -e MIN_PORT=xxxxx \
-  -e MAX_PORT=xxxxx \
-  -v /var/lib/crossdesk:/var/lib/crossdesk \
-  -v /var/log/crossdesk:/var/log/crossdesk \
-  crossdesk/crossdesk-server:v1.1.6
-```
+## 开发与反馈

-上述命令中，用户需注意的参数如下：
+- [源码构建](docs/BUILD.md)：Windows、macOS、Linux、可选编译参数与打包。
+- [iOS 开发说明](apps/ios/README.md)：原生端构建和真机验证。
+- [GUI 架构](docs/gui-architecture.md)：桌面 UI、平台实现与工程结构。
+- [常见问题](docs/FAQ.md)：连接失败、黑屏、文件位置与编译问题。
+- [提交问题](https://github.com/kunkundi/crossdesk/issues)：请附上两端系统、客户端版本、连接方式和可复现步骤。

-#### 配置参数
+## 致谢与许可

- EXTERNAL_IP：服务器公网 IP , 对应 CrossDesk 客户端**自托管服务器配置**中填写的**服务器地址**
- INTERNAL_IP：服务器内网 IP
- CROSSDESK_SERVER_PORT：自托管服务使用的端口，对应 CrossDesk 客户端**自托管服务器配置**中填写的**服务器端口**
- COTURN_PORT: COTURN 服务使用的端口, 对应 CrossDesk 客户端**自托管服务器配置**中填写的**中继服务端口**
- MIN_PORT/MAX_PORT：COTURN 服务使用的端口范围，例如：MIN_PORT=50000, MAX_PORT=60000，范围可根据客户端数量调整。
- `-v /var/lib/crossdesk:/var/lib/crossdesk`：持久化数据库和证书文件到宿主机
- `-v /var/log/crossdesk:/var/log/crossdesk`：持久化日志文件到宿主机
+感谢 [HelloGitHub](https://hellogithub.com/)、[阮一峰的科技爱好者周刊](https://github.com/ruanyf/weekly) 与 [LinuxDo](https://linux.do) 社区的推荐、交流与支持。

-#### 部署示例
+CrossDesk 使用 [GPL-3.0](LICENSE) 许可。隐私说明见 [隐私政策](PRIVACY.md#中文)。

-```bash
-sudo docker run -d \
-  --name crossdesk_server \
-  --network host \
-  -e EXTERNAL_IP=114.114.114.114 \
-  -e INTERNAL_IP=10.0.0.1 \
-  -e CROSSDESK_SERVER_PORT=9099 \
-  -e COTURN_PORT=3478 \
-  -e MIN_PORT=50000 \
-  -e MAX_PORT=60000 \
-  -v /var/lib/crossdesk:/var/lib/crossdesk \
-  -v /var/log/crossdesk:/var/log/crossdesk \
-  crossdesk/crossdesk-server:v1.1.6
-```
-
-#### 注意事项
-
- **服务器需开放端口：COTURN_PORT/udp，COTURN_PORT/tcp，MIN_PORT-MAX_PORT/udp，CROSSDESK_SERVER_PORT/tcp。**
- 如果不挂载 volume，容器删除后数据会丢失
- 证书文件会在首次启动时自动生成并持久化到宿主机的 `/var/lib/crossdesk/certs` 路径下。由于默认使用的是自签证书，无法保障安全性，建议在云服务商申请正式证书放到该目录下并重启服务。
- 数据库文件会自动创建并持久化到宿主机的 `/var/lib/crossdesk/db/crossdesk-server.db` 路径下
- 日志文件会自动创建并持久化到宿主机的 `/var/log/crossdesk/` 路径下
-
-#### 目录权限
-
-如果 Docker 自动创建的目录权限不足（属于 root），容器内用户无法写入，会导致：
-
- 证书生成失败，容器启动脚本会报错退出
- 数据库目录创建失败，程序会抛出异常并崩溃
- 日志目录创建失败，日志文件无法写入（但程序可能继续运行）
-
-在启动容器前手动设置权限：
-
-```bash
-sudo mkdir -p /var/lib/crossdesk /var/log/crossdesk
-sudo chown -R $(id -u):$(id -g) /var/lib/crossdesk /var/log/crossdesk
-```
-
-### 客户端
-
-1. 点击右上角设置进入设置页面。<br><br>
-<img width="600" height="210" alt="image" src="https://github.com/user-attachments/assets/6431131d-b32a-4726-8783-6788f47baa3b" /><br>
-
-2. 点击`自托管服务器配置`按钮。<br><br>
-<img width="600" height="160" alt="image" src="https://github.com/user-attachments/assets/24c761a3-1985-4d7e-84be-787383c2afb8" /><br>
-
-3. 输入`服务器地址`(**EXTERNAL_IP**)、`信令服务端口`(**CROSSDESK_SERVER_PORT**)、`中继服务端口`(**COTURN_PORT**)，点击确认按钮。
-
-4. 勾选`自托管服务器配置`选项，点击确认按钮保存设置。如果服务端使用的是正式证书，则到此步骤为止，客户端即可显示已连接服务器。
-
-5. 如果使用默认证书（正式证书忽略此步骤），则需要将服务端`/var/lib/crossdesk/certs/`目录下的`api.crossdesk.cn_root.crt`自签根证书下载到运行客户端的机器，并执行下述命令安装证书：
-
-**Windows：** 使用管理员权限打开 PowerShell 执行：
-
-```powershell
-certutil -addstore "Root" "C:\path\to\api.crossdesk.cn_root.crt"
-```
-
-**Linux：**
-
-```bash
-sudo cp /path/to/api.crossdesk.cn_root.crt /usr/local/share/ca-certificates/api.crossdesk.cn_root.crt
-sudo update-ca-certificates
-```
-
-**macOS：**
-
-```bash
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain path/to/api.crossdesk.cn_root.crt
-```
-
-### 自托管 Web 客户端
-
-详情见项目 [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client)。
-
---
-
-## 常见问题
-
-见 [常见问题](https://github.com/kunkundi/crossdesk/blob/self-hosted-server/docs/FAQ.md)。
-
---
-
-## 致谢
-
- 感谢 [HelloGitHub](https://hellogithub.com/) 的推荐与关注。
- 感谢 [阮一峰的科技爱好者周刊](https://github.com/ruanyf/weekly) 的收录与推荐。
- 感谢 [LinuxDo](https://linux.do) 社区的关注、交流与支持，为 CrossDesk 项目的完善提供了帮助。
-
---
-
-## Code signing policy
+### Code signing policy

 CrossDesk 使用 SignPath.io 为本仓库构建的官方 Windows 发布包提供代码签名。

@@ -431,4 +234,3 @@ CrossDesk 使用 SignPath.io 为本仓库构建的官方 Windows 发布包提供

 - **Committers and reviewers（代码提交与审核）：** [kunkundi](https://github.com/kunkundi)
 - **Approvers（签名审批）：** [kunkundi](https://github.com/kunkundi)
- **隐私政策：** [查看 CrossDesk 隐私政策](PRIVACY.md#中文)
@@ -1,451 +1,236 @@
-# CrossDesk
+<div align="center">
+  <img src="apps/desktop/resources/linux/crossdesk_128x128.png" width="80" alt="CrossDesk logo" />
+  <h1>CrossDesk</h1>
+  <p>A lightweight, cross-platform remote desktop for computers, browsers, and iPhone / iPad.</p>
+  <p><a href="https://www.crossdesk.cn/">Website</a> · <a href="https://github.com/kunkundi/crossdesk/releases">Download</a> · <a href="https://web.crossdesk.cn/">Open Web Client</a> · <a href="README.md">中文</a></p>
+</div>

-<a href="https://hellogithub.com/repository/kunkundi/crossdesk" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=55d41367570345f1838e02fd12be7961&claim_uid=cb0OpZRrBuGVAfL&theme=small" alt="Featured｜HelloGitHub" /></a>
+<div align="center">

-[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-brightgreen.svg)](https://www.crossdesk.cn/)
-[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![GitHub last commit](https://img.shields.io/github/last-commit/kunkundi/crossdesk)](https://github.com/kunkundi/crossdesk/commits/web-client)
-[![Build Status](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml/badge.svg)](https://github.com/kunkundi/crossdesk/actions)  
-[![Docker Pulls](https://img.shields.io/docker/pulls/crossdesk/crossdesk-server)](https://hub.docker.com/r/crossdesk/crossdesk-server/tags)
-[![GitHub issues](https://img.shields.io/github/issues/kunkundi/crossdesk.svg)](https://github.com/kunkundi/crossdesk/issues)
-[![GitHub stars](https://img.shields.io/github/stars/kunkundi/crossdesk.svg?style=social)](https://github.com/kunkundi/crossdesk/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/kunkundi/crossdesk.svg?style=social)](https://github.com/kunkundi/crossdesk/forks)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20iOS-blue)](#download)
+[![Release](https://img.shields.io/github/v/release/kunkundi/crossdesk)](https://github.com/kunkundi/crossdesk/releases)
+[![Build](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml/badge.svg)](https://github.com/kunkundi/crossdesk/actions/workflows/build.yml)
+[![License: GPL v3](https://img.shields.io/badge/license-GPL--3.0-blue)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/kunkundi/crossdesk?style=social)](https://github.com/kunkundi/crossdesk/stargazers)

-[ [中文](README.md) / English ]
+</div>

---
+CrossDesk connects Windows, macOS, and Linux desktops, with browser and native iOS clients for controlling computers. Built on [MiniRTC](https://github.com/kunkundi/minirtc), it supports real-time video and audio, keyboard and mouse control, file transfer, and self-hosting. The project is under active development.
+
+> This guide follows the current repository source. Desktop screenshots render the current Slint UI with sample IDs, passwords, online statuses, and recent devices; thumbnails show public pages. Check each release's notes for the features and requirements of its binaries. Native iOS build and signing instructions are below.
+
+[Preview](#preview) · [Download](#download) · [Quick start](#quick-start) · [Session controls](#session) · [Settings](#settings) · [iOS](#ios) · [Self-hosting](#self-hosting) · [Build](docs/BUILD_EN.md) · [FAQ](docs/FAQ.md#english)
+
+<a id="preview"></a>

 ## Preview

-### PC Client
+### Desktop client

-![sup_example](https://github.com/user-attachments/assets/3f17d8f3-7c4a-4b63-bae4-903363628687)
-
-### Web Client
+The main window brings together your device ID, connection password, remote connection entry, and recent devices.

 <p align="center">
-  <img width="850" height="550" alt="6bddcbed47ffd4b9988a4037c7f4f524" src="https://github.com/user-attachments/assets/e44f73f9-24ac-46a3-a189-b7f8b6669881" />
+  <img src="docs/images/desktop-main-en.png" width="800" alt="Current desktop UI example showing a connected server and three online devices with page thumbnails" />
 </p>

---
+### Web client

-## Introduction
+Enter a remote device ID and password in your browser without installing the desktop app on the controlling device.

-CrossDesk is a lightweight cross-platform remote desktop software.
+<p align="center">
+  <img src="docs/images/web-client.png" width="800" alt="Current CrossDesk Web Client connection page in Chinese" />
+</p>

-CrossDesk is an experimental application of [MiniRTC](https://github.com/kunkundi/minirtc.git), a lightweight cross-platform real-time audio and video transmission library. MiniRTC provides fundamental capabilities including network traversal ([RFC5245](https://datatracker.ietf.org/doc/html/rfc5245)), video software/hardware encoding and decoding (H264/AV1), audio encoding/decoding ([Opus](https://github.com/xiph/opus)), signaling interaction, network congestion control, and transmission encryption ([SRTP](https://tools.ietf.org/html/rfc3711)).
+See the [screenshot notes](docs/images/README.md) for image sources and refresh instructions.

---
+## Features

-## System Requirements
-
-| Platform | Minimum Version |
+| Capability | Current support |
 | --- | --- |
-| **Windows** | Windows 10 or later (64-bit) |
-| **macOS** | macOS Intel 15.0 or later *(versions between 14.0 and 15.0 can be built manually for compatibility)*<br>macOS Apple Silicon 14.0 or later |
-| **Linux** | Ubuntu 20.04 or later |
+| Cross-platform control | Windows / macOS / Linux desktop control; browser and native iOS controllers |
+| Live video and audio | H.264 / AV1, hardware codecs, and remote audio; adjust quality, 30 / 60 fps, and video preference during a session |
+| Devices and displays | Recent connections, device aliases, session tabs, and remote display switching |
+| Input and sharing | Keyboard/mouse input, remote cursor synchronization, shortcuts, text clipboard synchronization, and file transfer |
+| Networking and deployment | Direct P2P connections, TURN relay and forced relay, SRTP media encryption, and self-hosted signaling/relay services |
+| Privacy screen | Enable automatically when connected to, or toggle from the session toolbar; availability depends on the host OS and capture method |
+| Windows protected desktops | CrossDesk Service forwards input on lock screens, sign-in screens, and secure desktops |
+| Linux headless operation | Reuse existing desktops and applications or create separate Xvfb desktops; use the terminal console to check status and change passwords or settings; see [setup](docs/HEADLESS_EN.md) |

---
+Controls and capabilities vary by client. Desktop controls are described below; see the [iOS guide](apps/ios/README.md) for native mobile features.

-## Usage
+<a id="download"></a>

-Enter the remote desktop ID in the menu bar’s “Remote ID” field and click “→” to initiate a remote connection.
+## Download and install

-![usage1](https://github.com/user-attachments/assets/3a4bb59f-c84c-44d2-9a20-11790aac510e)
+Choose a package matching your OS and CPU architecture from [GitHub Releases](https://github.com/kunkundi/crossdesk/releases) or the [website](https://www.crossdesk.cn/).

-If the remote desktop requires a connection password, you must enter the correct password on your side to successfully establish the connection.
+| Platform | Current source / CI baseline | Installation |
+| --- | --- | --- |
+| Windows | Windows 10+, x64 | `.exe` installer; portable builds are also supported |
+| macOS | macOS 14.0+, Intel / Apple Silicon | x64 or arm64 `.pkg` |
+| Linux | Ubuntu 20.04+, amd64 / arm64, glibc 2.31 baseline | `.deb` package |
+| iOS / iPadOS | iOS 16.0+, arm64 physical device | Native controller; build and sign with Xcode, or sign the unsigned CI app |
+| Web | A WebRTC-capable browser | Open [web.crossdesk.cn](https://web.crossdesk.cn/) |

-![password](https://github.com/user-attachments/assets/1beadcce-640d-4f5c-8e77-51917b5294d5)
+On Linux, replace the example filename with the downloaded package name:

-Before connecting, you can customize configuration options in the settings, such as language and video encoding format.
+```bash
+sudo apt install "./crossdesk-linux-amd64-<version>.deb"
+```

-![settings](https://github.com/user-attachments/assets/8bc5468d-7bbb-4e30-95bd-da1f352ac08c)
+**First launch on macOS:** follow the app prompts to grant **Screen Recording** (called **Screen & System Audio Recording** on newer systems) and **Accessibility** under **System Settings → Privacy & Security**. Reopen the app if prompted. These permissions allow desktop capture and remote keyboard/mouse input respectively.

-### Using the Web Client
+<a id="quick-start"></a>

-Visit [CrossDesk Web Client](https://web.crossdesk.cn/).
-Enter the **Remote Device ID** and **Password**, then click Connect to access the remote device. As shown, **iOS Safari remotely controlling Windows 11**:
+## Quick start

-<img width="645" height="300" alt="_cgi-bin_mmwebwx-bin_webwxgetmsgimg__ MsgID=932911462648581698 skey=@crypt_1f5153b1_b550ca7462b5009ce03c991cca2a92a7 mmweb_appid=wx_webfilehelper" src="https://github.com/user-attachments/assets/a5109e6f-752c-4654-9f4e-7e161bddf43e" />
+### Connect from another computer

-### Windows Service (CrossDesk Service)
+1. **Prepare the host.** Install and run CrossDesk on the computer to control. Wait for the bottom status bar to show that the server is connected. Share the **Local ID** and **Password** shown under **Local Desktop** with the controller.
+2. **Enter the remote ID.** On the controlling computer, enter the host's ID in **Remote Desktop → Remote ID**, then click **→**.
+3. **Verify the password.** Enter the host's current connection password when prompted and confirm. Select **Remember password** if you want to save it.
+4. **Reconnect later.** Previously connected devices appear under **Recent Connections**. Reconnect from a card, edit its alias, or remove its record.

-CrossDesk provides a local helper service on Windows named **CrossDesk Service**. Its service name is `CrossDeskService`. The service improves remote control in protected Windows states such as the lock screen, sign-in UI, credential UI, and secure desktop. It provides:
+The eye button shows or hides the local password, the refresh button generates a new random password, and the pencil button lets you edit it. Passwords use **6 ASCII letters or digits**. Stay connected to the server when editing or refreshing a password. Wait for the change to succeed and the client to reconnect, then copy the current password. Controllers that saved the old password must enter it again.

- Remote status reporting for lock screen, sign-in, credential, and secure desktop states.
- Remote `Ctrl+Alt+Del` (SAS) delivery.
- Keyboard and mouse input forwarding while the remote Windows device is on the lock screen, sign-in UI, or secure desktop.
+### Connect from a browser

-The Windows installer bundles `crossdesk_service.exe` and `crossdesk_session_helper.exe`, then registers the service as an on-demand Windows service during installation. When the CrossDesk client starts, it tries to start the installed service automatically. When no CrossDesk client process is running on the machine, the service exits automatically. Uninstalling the client also stops and removes the service.
+1. Keep CrossDesk running and connected to the server on the host computer.
+2. Open the [Web Client](https://web.crossdesk.cn/), enter the **Remote Device ID** and **Password**, and click **Connect**.
+3. Use the page's display, mouse-mode, and keyboard controls during the session. Phone and tablet browsers can also connect.

-For manual Windows builds or deployments, make sure `CrossDesk.exe`, `crossdesk_service.exe`, and `crossdesk_session_helper.exe` are placed in the same directory. Open PowerShell with administrator privileges to install or uninstall the service:
+For self-hosting, connect both sides to the same service. Browser deployment is documented in [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client).
+
+<a id="session"></a>
+
+## Session controls
+
+Switch devices using session tabs. Expand the control bar if it is collapsed, and hover over icons to see their tooltips.
+
+| Control | Action |
+| --- | --- |
+| Display | Switch the remote monitor |
+| Keyboard | Send shortcuts; Windows `Ctrl+Alt+Del` requires the remote service |
+| Mouse | Enable / release remote mouse control |
+| Speaker | Play / mute remote audio |
+| Folder | Select a file to send and view transfer progress |
+| Video settings | Adjust video quality, capture frame rate, and video preference during the current session |
+| Network statistics | Inspect traffic, packet loss, frame rate, resolution, direct / relay mode, and encryption status |
+| Privacy screen | Enable or disable the host's privacy screen; hover to see its status and available actions |
+| Fullscreen | Enter / exit fullscreen |
+| Disconnect | End the current remote session |
+
+Desktop clients synchronize text clipboard contents. Configure the receiving directory under **Settings → File Save Path**. Closing the main window hides it and keeps the app running; use the system tray or menu-bar exit command to quit completely.
+
+### Adjust video during a session
+
+After connecting, open **Video settings** (the sliders icon) in the toolbar. Choose low / medium / high quality, **30 / 60 fps**, and frame-rate priority / quality priority / balanced adaptation. Changes are sent to the current host without reconnecting; actual results depend on the network, device, and encoder. For older hosts that do not support live video settings, the menu explains the limitation and disables the options.
+
+<p align="center">
+  <img src="docs/images/desktop-stream-video-settings-en.png" width="800" alt="Current session video menu with quality, capture frame rate, and video preference; the background is a public page used for demonstration" />
+</p>
+
+<a id="settings"></a>
+
+## Client settings and updates
+
+Open **☰ → Settings** in the top-right corner and click **OK** to save. Configure codecs and connections before connecting; some settings are disabled during an active session. Scroll down for self-hosting, startup behavior, and the file save path. Adjust quality, frame rate, and video preference from the remote session toolbar.
+
+<p align="center">
+  <img src="docs/images/desktop-settings-en.png" width="720" alt="Current client settings with codec, hardware codecs, TURN, forced relay, and automatic privacy screen options" />
+</p>
+
+| Setting | Purpose |
+| --- | --- |
+| Language | 中文, English, Русский |
+| Capture Method (Windows) | Auto / DXGI / WGC / GDI; choose Auto for automatic headless adaptation |
+| Video Encode Format | H.264 / AV1; hardware codec availability depends on the platform, device, and build options |
+| Enable TURN Service | Allow relay-assisted connections; check this setting if P2P fails |
+| Force Relay | Require relay connections when TURN is enabled; turning TURN off also disables this option |
+| Privacy screen on connect | Automatically enable privacy when this computer is controlled remotely; the controller can toggle it from the session toolbar |
+| Self-Hosted Config | Set the server address and signaling port, then enable the checkbox |
+| Auto Start / Enable Daemon | Configure startup and process supervision; restart as indicated by the UI |
+| File Save Path | Choose where received files are saved |
+
+### Check for updates
+
+The client checks for updates in the background after launch. A new version adds an update indicator to the main window menu. Open **☰ → About** to view the version or click **Check for updates** to check manually. When an update is available, you can view its release notes and open the download page.
+
+<p align="center">
+  <img src="docs/images/desktop-about-en.png" width="720" alt="About dialog with the Check for updates button; version and check result are demonstration data" />
+</p>
+
+<a id="ios"></a>
+
+## Native iOS / iPadOS client
+
+[`apps/ios`](apps/ios/README.md) contains a native controller using the same MiniRTC protocol as the desktop client. It controls remote computers; it does not expose an iPhone or iPad as a remotely controlled desktop.
+
+1. Follow the [iOS guide](apps/ios/README.md) to build and sign the app with Xcode, then install it on an iOS 16+ physical device.
+2. Enter a remote ID on the home screen, connect, and enter its password. Successful connections become available in the recent devices list.
+3. Choose a mouse mode in Settings: **Relative Position** works like a trackpad; **Absolute Position** maps touches directly to the remote screen.
+4. Tap the floating icon to expand the menu, then switch displays, open the keyboard, toggle audio, or send files. Received files are stored in `Documents/Received` and can be exported using the share button beside the transfer status.
+
+The app currently receives remote text into the iOS clipboard. Its UI does not yet expose a button to send the local clipboard.
+
+Gestures include one-finger click, two-finger right-click, long-press drag, and pinch-to-zoom. When zoomed in, two-finger panning moves the viewport. The native and browser clients are maintained separately, so their controls and gestures may differ. The current native UI uses Chinese labels.
+
+<a id="windows-service"></a>
+
+## Windows lock screens and sign-in
+
+**CrossDesk Service** (`CrossDeskService`) reports protected desktop states and forwards `Ctrl+Alt+Del`, keyboard, and mouse input on lock screens, sign-in screens, credential prompts, and secure desktops.
+
+The installer registers an on-demand service. CrossDesk tries to start it on launch, and the service exits when no local CrossDesk client is running. Portable builds offer service installation in the prompt or **Settings → Lock Screen Service**, with administrator privileges. The service depends on a running client.
+
+<details>
+<summary>Manual deployment and service commands</summary>
+
+Keep the complete installation directory. For manual deployment, place `CrossDesk.exe`, `crossdesk_service.exe`, `crossdesk_session_helper.exe`, and all `.dll` files from the same build together. Open an administrator PowerShell in that directory and run the commands you need:

 ```powershell
-# install
 .\CrossDesk.exe --service-install
-# start
 .\CrossDesk.exe --service-start
-# check status
 .\CrossDesk.exe --service-status
 .\CrossDesk.exe --service-ping
-# stop
+# Stop or uninstall the service
 .\CrossDesk.exe --service-stop
-# uninstall
 .\CrossDesk.exe --service-uninstall
 ```

-If the remote Windows service is not installed, not running, or temporarily unavailable, the basic remote desktop connection still works, but remote control on the lock screen, sign-in UI, and secure desktop is limited. The client will show “Remote Windows service unavailable”.
+</details>

---
+If **Remote Windows service unavailable** appears, check installation and service status on the host. Ordinary desktop connections remain available, while control of protected screens is limited.

-## How to build
+<a id="self-hosting"></a>

-### Build requirements
+## Self-hosting

- [xmake](https://xmake.io/#/guide/installation)
- [cmake](https://cmake.org/download/) 3.21 or later (installed automatically by xmake when the system version is too old)
+Host your own signaling and TURN services, then enter their connection details under **☰ → Settings → Self-Hosted Config**. Enable the same server configuration on both the controller and host.

-### Linux
+- [Self-hosting guide](docs/SELF_HOSTING_EN.md): current Compose deployment, client settings, certificate trust, and troubleshooting.
+- [CrossDesk Server](https://github.com/kunkundi/crossdesk-server): server source and release configuration.
+- [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client): browser source and deployment instructions.

-Linux builds support Ubuntu 20.04 or later on amd64 and arm64. Release packages
-use Ubuntu 20.04/glibc 2.31 as their compatibility baseline. Install the base
-build dependencies first:
+## Development and feedback

-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  git curl unzip build-essential gcc-10 g++-10 python3-pip \
-  pkg-config binutils dpkg-dev \
-  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
-  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
-  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
-  libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxcb-shm0-dev \
-  libasound2-dev libsndio-dev libpulse-dev \
-  libgl1-mesa-dev
-```
+- [Build from source](docs/BUILD_EN.md): Windows, macOS, Linux, optional flags, and packaging.
+- [iOS development](apps/ios/README.md): native build and physical-device checks.
+- [GUI architecture](docs/gui-architecture.md): desktop UI and platform organization.
+- [FAQ](docs/FAQ.md#english): connection failures, blank video, received files, and build issues.
+- [Report an issue](https://github.com/kunkundi/crossdesk/issues): include both operating systems, client versions, connection mode, and reproduction steps.

-When Ubuntu 20.04's bundled CMake 3.16 is too old, xmake automatically
-downloads and uses CMake 3.21 or later; replacing the system CMake manually is
-not required.
+## Acknowledgements and license

-Ubuntu 20.04's default GCC 9 lacks parts of the C++20 standard library needed
-by Slint's C++ API, so the commands above install GCC 10 and the configuration
-below selects it explicitly.
+Thanks to [HelloGitHub](https://hellogithub.com/), [Ruanyf Weekly](https://github.com/ruanyf/weekly), and the [LinuxDo](https://linux.do) community for featuring CrossDesk and contributing feedback.

-Install the optional dependencies when Wayland capture or DRM capture is enabled:
+CrossDesk is licensed under [GPL-3.0](LICENSE). See the [Privacy Policy](PRIVACY.md#english).

-```bash
-sudo apt-get install -y libdbus-1-dev libdrm-dev
+### Code signing policy

-# Ubuntu 22.04 and later can alternatively use the distribution packages.
-# sudo apt-get install -y libpipewire-0.3-dev libspa-0.2-dev
-```
-
-Clone the submodules and build a release binary:
-
-```bash
-git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
-cd crossdesk
-
-# Run this when the repository has already been cloned
-git submodule update --init --recursive
-
-# Ubuntu 20.04 has no PipeWire 0.3 development package. Install the
-# header-only SDK used during compilation. Skip this when the distribution's
-# PipeWire 0.3 development packages are already installed.
-sudo ./docker/linux-build/install-pipewire-sdk.sh
-
-xmake f -c -m release --USE_CUDA=false --toolchain=gcc-10 -y
-xmake b -vy crossdesk
-```
-
-Use `--toolchain=gcc-10` so that both CrossDesk and third-party packages such
-as libyuv, which xmake builds during configuration, use GCC 10. Specifying only
-`--cc`/`--cxx` may still let dependency builds fall back to the system
-`/bin/cc` and `/bin/c++`. Keep `-c` when switching compilers to clear the old
-configuration.
-
-The amd64 binary is written to `build/linux/x86_64/release/crossdesk`; the arm64 binary is written to `build/linux/arm64/release/crossdesk`.
-
-Example configuration with Wayland and DRM capture enabled:
-
-```bash
-xmake f -c -m release --USE_WAYLAND=true --USE_DRM=true --USE_CUDA=false \
-  --toolchain=gcc-10 -y
-xmake b -vy crossdesk
-```
-
-Build a Debian package after compiling a release binary on the matching architecture:
-
-```bash
-# amd64
-./scripts/linux/pkg_amd64.sh 1.0.0
-
-# arm64
-./scripts/linux/pkg_arm64.sh 1.0.0
-```
-
-The package scripts install the shared Slint runtime in the private `/usr/lib/crossdesk` directory, so users do not need to install `libslint_cpp.so` separately.
-PipeWire is not a mandatory runtime dependency. CrossDesk detects the host's
-PipeWire 0.3 runtime dynamically and can still use X11 capture (and DRM when
-enabled at build time) when it is unavailable.
-
-### Common build options
-
-```text
--USE_CUDA=true/false: Enable CUDA hardware codec acceleration, disabled by default
--USE_WAYLAND=true/false: Enable Wayland/PipeWire capture on Linux, disabled by default
--USE_DRM=true/false: Enable DRM capture on Linux, disabled by default
--CROSSDESK_PORTABLE=true/false: Build the portable variant, disabled by default
--CROSSDESK_VERSION=xxx: Set the CrossDesk version
-
-# Example
-xmake f --CROSSDESK_VERSION=1.0.0 --USE_CUDA=true
-```
-
-Run:
-
-```bash
-xmake r crossdesk
-```
-
-### Development Without CUDA Environment
-
-For **Linux developers who do not have a CUDA environment installed and want to enable hardware codec feature**, a preconfigured [Ubuntu 20.04 compatibility build image](https://hub.docker.com/r/crossdesk/ubuntu20.04) is provided.
-This image contains the required build dependencies and produces a single Linux package compatible with the glibc 2.31 baseline.
-
-After entering the container, download the project and run:
-
-```bash
-export CUDA_PATH=/usr/local/cuda
-export XMAKE_GLOBALDIR=/data
-
-xmake f --USE_CUDA=true
-xmake b --root -vy crossdesk
-```
-
-For **Windows developers without a CUDA environment** installed, run the following command to install the CUDA build environment:
-
-```powershell
-xmake require -vy "cuda 12.6.3"
-```
-
-After the installation is complete, execute:
-
-```powershell
-xmake require --info "cuda 12.6.3"
-```
-
-The output will look like this:
-
-<img width="860" height="226" alt="Image" src="https://github.com/user-attachments/assets/999ac365-581a-4b9a-806e-05eb3e4cf44d" />
-
-From the output above, locate the CUDA installation directory — this is the path pointed to by installdir.
-Add this path to your system environment variable CUDA_PATH, or set it in the terminal using:
-
-```powershell
-set CUDA_PATH=path_to_cuda_installdir
-```
-
-Then re-run:
-
-```powershell
-xmake f --USE_CUDA=true
-xmake b -vy crossdesk
-```
-
-#### Notice
-
-If the client status bar shows **Disconnected** during runtime, please first install the client from the [CrossDesk official website](https://www.crossdesk.cn/) to ensure the required certificate files are available in the environment.
-
-<img width="256" height="120" alt="image" src="https://github.com/user-attachments/assets/1812f7d6-516b-4b4f-8a3d-98bee505cc5a" />
-
-### About Xmake
-
-#### Installing Xmake
-
-You can install Xmake using one of the following methods:
-
-Using curl:
-
-```bash
-curl -fsSL https://xmake.io/shget.text | bash
-```
-
-Using wget:
-
-```bash
-wget https://xmake.io/shget.text -O - | bash
-```
-
-Using powershell:
-
-```powershell
-irm https://xmake.io/psget.text | iex
-```
-
-#### Build Options
-
-```text
-# Switch build mode
-xmake f -m debug/release
-
-# Optional build parameters
-r : Rebuild the target
-v : Show detailed build logs
-y : Automatically confirm prompts
-
-# Example
-xmake b -vy crossdesk
-```
-
-#### Run Options
-
-```bash
-# Run in debug mode
-xmake r -d crossdesk
-```
-
-For more information, please refer to the [official Xmake documentation](https://xmake.io/guide/quick-start.html).
-
---
-
-## Self-Hosted Server
-
-### Server
-
-It is recommended to deploy CrossDesk Server using Docker.
-
-```bash
-sudo docker run -d \
-  --name crossdesk_server \
-  --network host \
-  -e EXTERNAL_IP=xxx.xxx.xxx.xxx \
-  -e INTERNAL_IP=xxx.xxx.xxx.xxx \
-  -e CROSSDESK_SERVER_PORT=xxxx \
-  -e COTURN_PORT=xxxx \
-  -e MIN_PORT=xxxxx \
-  -e MAX_PORT=xxxxx \
-  -v /var/lib/crossdesk:/var/lib/crossdesk \
-  -v /var/log/crossdesk:/var/log/crossdesk \
-  crossdesk/crossdesk-server:v1.1.6
-```
-
-The parameters you need to pay attention to are as follows:
-
-#### Parameters
-
- **EXTERNAL_IP**: The server’s public IP. This corresponds to **Server Address** in the CrossDesk client’s **Self-Hosted Server Configuration**.
- **INTERNAL_IP**: The server’s internal IP.
- **CROSSDESK_SERVER_PORT**: The port used by the self-hosted service. This corresponds to **Server Port** in the CrossDesk client’s **Self-Hosted Server Configuration**.
- **COTURN_PORT**: The port used by the COTURN service. This corresponds to **Relay Service Port** in the CrossDesk client’s **Self-Hosted Server Configuration**.
- **MIN_PORT / MAX_PORT**: The port range used by the COTURN service. Example: `MIN_PORT=50000`, `MAX_PORT=60000`. Adjust the range depending on the number of clients.
- `-v /var/lib/crossdesk:/var/lib/crossdesk`: Persists database and certificate files on the host machine.
- `-v /var/log/crossdesk:/var/log/crossdesk`: Persists log files on the host machine.
-
-#### Example
-
-```bash
-sudo docker run -d \
-  --name crossdesk_server \
-  --network host \
-  -e EXTERNAL_IP=114.114.114.114 \
-  -e INTERNAL_IP=10.0.0.1 \
-  -e CROSSDESK_SERVER_PORT=9099 \
-  -e COTURN_PORT=3478 \
-  -e MIN_PORT=50000 \
-  -e MAX_PORT=60000 \
-  -v /var/lib/crossdesk:/var/lib/crossdesk \
-  -v /var/log/crossdesk:/var/log/crossdesk \
-  crossdesk/crossdesk-server:v1.1.6
-```
-
-#### Notes
-
- **The server must open the following ports: COTURN_PORT/udp, COTURN_PORT/tcp, MIN_PORT–MAX_PORT/udp, and CROSSDESK_SERVER_PORT/tcp.**
- If you don’t mount volumes, all data will be lost when the container is removed.
- Certificate files will be automatically generated on first startup and persisted to the host at `/var/lib/crossdesk/certs`. As the default certificates are self-signed and cannot guarantee security, it is strongly recommended to apply for a trusted certificate from a cloud provider, deploy it to this directory, and restart the service.
- The database file will be automatically created and stored at `/var/lib/crossdesk/db/crossdesk-server.db`.
- Log files will be created and stored at `/var/log/crossdesk/`.
-
-#### Directory permissions
-
-If the directories automatically created by Docker belong to root and have insufficient write permissions, the container user may not be able to write to them. This can cause:
-
- Certificate generation failure, leading to startup script errors and container exit.
- Database directory creation failure, causing the program to throw exceptions and crash.
- Log directory creation failure, preventing logs from being written (though the program may continue running).
-
-Manually set permissions before starting the container:
-
-```bash
-sudo mkdir -p /var/lib/crossdesk /var/log/crossdesk
-sudo chown -R $(id -u):$(id -g) /var/lib/crossdesk /var/log/crossdesk
-```
-
-#### TLS certificate
-
-Place **crossdesk.cn.key** and **crossdesk.cn_bundle.crt** into the **/path/to/your/certs** directory.
-
-### Client
-
-1. Click the settings icon in the top-right corner to enter the settings page.<br><br>
-<img width="600" height="210" alt="image" src="https://github.com/user-attachments/assets/6431131d-b32a-4726-8783-6788f47baa3b" /><br>
-
-2. Click `Self-Hosted Server Configuration` button.<br><br>
-<img width="600" height="160" alt="image" src="https://github.com/user-attachments/assets/24c761a3-1985-4d7e-84be-787383c2afb8" /><br>
-
-3. Enter the `Server Address` (**EXTERNAL_IP**), `Signaling Service Port` (**CROSSDESK_SERVER_PORT**), and `Relay Service Port` (**COTURN_PORT**) and click OK button.
-
-4. Check the `Self-hosted server configuration` option and click the OK button to save the settings. If the server is using a valid (official) certificate, the process ends here and the client will show that it is connected to the server.
-
-5. If the default certificate is used (skip this step if an official certificate is used), download the self-signed root certificate `api.crossdesk.cn_root.crt` from the server directory /var/lib/crossdesk/certs/ to the machine running the client, and install the certificate by executing the following command:
-
-**Windows:** Open PowerShell with administrator privileges and execute:
-
-```powershell
-certutil -addstore "Root" "C:\path\to\api.crossdesk.cn_root.crt"
-```
-
-**Linux:**
-
-```bash
-sudo cp /path/to/api.crossdesk.cn_root.crt /usr/local/share/ca-certificates/api.crossdesk.cn_root.crt
-sudo update-ca-certificates
-```
-
-**macOS:**
-
-```bash
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain path/to/api.crossdesk.cn_root.crt
-```
-
-### Self-Hosted Web Client
-
-See [CrossDesk Web Client](https://github.com/kunkundi/crossdesk-web-client).
-
---
-
-## FAQ
-
-See [FAQ](https://github.com/kunkundi/crossdesk/blob/self-hosted-server/docs/FAQ.md).
-
---
-
-## Acknowledgements
-
- Thanks to [HelloGitHub](https://hellogithub.com/) for the recommendation and exposure.
- Thanks to [Ruanyf Weekly](https://github.com/ruanyf/weekly) for featuring CrossDesk.
- Thanks to the [LinuxDo](https://linux.do) community for the attention, discussions, and support that helped improve CrossDesk.
-
---
-
-## Code signing policy
-
-CrossDesk uses SignPath.io to code-sign official Windows releases built from this repository.
+CrossDesk uses SignPath.io to sign official Windows releases built from this repository.

 **Free code signing provided by [SignPath.io](https://signpath.io/), certificate by [SignPath Foundation](https://signpath.org/).**

 - **Committers and reviewers:** [kunkundi](https://github.com/kunkundi)
 - **Approvers:** [kunkundi](https://github.com/kunkundi)
- **Privacy policy:** [Read the CrossDesk Privacy Policy](PRIVACY.md#english)
@@ -1,5 +1,5 @@
 // Application icon resource; load by the resource name IDI_ICON1.
-IDI_ICON1 ICON "..\\..\\icons\\windows\\crossdesk.ico"
+IDI_ICON1 ICON "crossdesk.ico"

 #define CREATEPROCESS_MANIFEST_RESOURCE_ID 1
 #define RT_MANIFEST 24
@@ -1,6 +1,6 @@
 // Portable build resource. The app itself runs as the current user; service
 // installation raises a separate UAC prompt only when the user chooses it.
-IDI_ICON1 ICON "..\\..\\icons\\windows\\crossdesk.ico"
+IDI_ICON1 ICON "crossdesk.ico"

 #define CREATEPROCESS_MANIFEST_RESOURCE_ID 1
 #define RT_MANIFEST 24
@@ -0,0 +1,13 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-11
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+IDI_CROSSDESK_LOGO ICON "crossdesk.ico"
+
+#define CROSSDESK_FILE_DESCRIPTION "CrossDesk Privacy Window"
+#define CROSSDESK_ORIGINAL_FILENAME "crossdesk_privacy_window.dll"
+#define CROSSDESK_FILE_TYPE VFT_DLL
+
+#include "version_info.rcinc"
@@ -1,5 +1,5 @@
 // Session helper icon and manifest resources.
-IDI_ICON1 ICON "..\\..\\icons\\windows\\crossdesk.ico"
+IDI_ICON1 ICON "crossdesk.ico"

 #define CREATEPROCESS_MANIFEST_RESOURCE_ID 1
 #define RT_MANIFEST 24
@@ -0,0 +1,12 @@
+Copyright 2014-2021 Amyuni Technologies Inc.
+https://www.amyuni.com
+
+This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
+By using this software, you accept to be prompted with an advertisement page which is not always under the control of the author. A fully commercial version is available for users who do not wisth to see those advertisements.
+
+Permission is granted to anyone to use this software for any purpose subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software.
+   If you use this software in a product, an acknowledgment in the product documentation would be required.
+2. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software.
+3. This notice may not be removed or altered from any distribution.
@@ -0,0 +1,50 @@
+Procedure to add a virtual monitor to your system (Windows 10 Only!)
+
+- Download our virtual display driver from https://www.amyuni.com/downloads/usbmmidd_v2.zip
+- Unpack the zip file to an empty folder, e.g. c:\temp\usbmmidd
+- Make sure you read the License.txt file as with any other software product
+- Open a command prompt window as Administrator (you cannot add a device to your system unless you "Run As Administrator")
+- Run the following commands:
+	- cd c:\temp\usbmmid (or whatever destination folder you chose)
+	- deviceinstaller64 install usbmmidd.inf usbmmidd (If you are on a 32-bit system, replace "deviceinstaller64" by "deviceinstaller")
+	- Make sure you see the message that the drivers are signed by Amyuni Technologies Inc. This is a confirmation that the drivers went through Microsoft driver signing procedure and are virus free
+	
+- Starting with version 2, the virtual monitor supports the following display resolutions by default:
+
+1024 x 768 pixels
+1360 x 768 pixels
+1440 x 900 pixels
+1600 x 900 pixels
+1600 x 1200 pixels
+1920 x 1080 pixels [Default Resolution]
+1920 x 1200 pixels
+2560 x 1440 pixels
+3840 x 2160 pixels
+
+After the first step above is executed, you can modify the list of supported resolutions by changing the following registry key:
+HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\usbmmIdd\Parameters\Monitors
+
+Up to 10 resolutions can be defined through this registry key. The keys should be named from "0" to "9". The (Default) registry value defines the default monitor resolution.
+
+Note that the list of resolutions can also be found in the usbmmidd.inf file that accompanies the printer driver. The inf file should not be modified in any way, otherwise the virtual display driver digital signature is invalidated.
+
+Once you are satisfied with the list of resolutions, you can activate the virtual monitor by running: 
+- deviceinstaller64 enableidd 1
+
+With version 2, rou can run this command multiple times to add up to 4 virtual monitors to your system.
+
+The included batch file usbmmidd.bat runs these commands automatically and selects between the 32- or 64-bit version of deviceinstaller.
+If you are not comfortable opening a command prompt and entering these commands, right-click on usbmmidd.bat and "Run As Administrator."
+
+That's it. You now have a high definition monitor in your Display Settings. You can change the display resolution, position the monitor, extend the desktop or do whatever you do with a real monitor.
+
+To deactivate the virtual monitor, run the command:
+deviceinstaller64 enableidd 0
+If ou have added more than one monitor, you should run this command multiple times to remove all monitors.
+
+to reactivate a virtual monitor:
+deviceinstaller64 enableidd 1
+
+To completely remove the drivers from your system, you can either go through the Device Manager and uninstall "USB Mobile Monitor Virtual Display", or run the commands:
+deviceinstaller64 stop usbmmidd
+deviceinstaller64 remove usbmmid
@@ -0,0 +1,16 @@
+@cd /d "%~dp0"
+
+@goto %PROCESSOR_ARCHITECTURE%
+@exit
+
+:AMD64
+@cmd /c deviceinstaller64.exe install usbmmidd.inf usbmmidd
+@cmd /c deviceinstaller64.exe enableidd 1
+@goto end
+
+:x86
+@cmd /c deviceinstaller.exe install usbmmidd.inf usbmmidd
+@cmd /c deviceinstaller.exe enableidd 1
+
+:end
+@pause
@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail

+# Keep readelf and ldd output stable for the runtime dependency checks below.
+export LC_ALL=C
+
 if [[ $# -lt 3 || $# -gt 4 ]]; then
    echo "Usage: $0 <debian-arch> <xmake-arch> <version> [extra-recommendation]" >&2
    exit 2
@@ -18,9 +21,13 @@ DESCRIPTION="A simple cross-platform remote desktop client."
 ALSA_RUNTIME_DEP="libasound2 | libasound2t64"
 PORTAL_RUNTIME_RECOMMENDS="xdg-desktop-portal, xdg-desktop-portal-gtk | xdg-desktop-portal-kde | xdg-desktop-portal-wlr"
 TRAY_RUNTIME_RECOMMENDS="libayatana-appindicator3-1 | libappindicator3-1"
+# Every published package includes the prerequisites for all Linux headless
+# paths, including a complete independent desktop. Older Ubuntu releases ship
+# dbus-run-session in dbus; newer releases split it into dbus-daemon.
+HEADLESS_RUNTIME_DEPS="xvfb, xfce4, dbus-daemon | dbus"

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"

 normalize_app_version() {
    local input="$1"
@@ -84,7 +91,7 @@ if [[ ! -x "$BUILD_BINARY" ]]; then
    exit 1
 fi

-for command_name in readelf ldd dpkg-deb; do
+for command_name in readelf ldd dpkg-deb strip; do
    if ! command -v "$command_name" >/dev/null 2>&1; then
        echo "Required packaging command is missing: $command_name" >&2
        exit 1
@@ -125,6 +132,9 @@ if [[ -n "$SLINT_NEEDED" ]]; then
        exit 1
    fi
    install -m 0755 "$SLINT_LIBRARY" "$PRIVATE_DIR/$SLINT_NEEDED"
+    # Keep dynamic exports/relocations while removing unneeded symbols from the
+    # staged copy. Never strip Xmake's cached runtime in place.
+    strip --strip-unneeded "$PRIVATE_DIR/$SLINT_NEEDED"
 fi

 cat > "$BIN_DIR/$PKG_NAME" <<'EOF'
@@ -142,7 +152,7 @@ ln -s "$PKG_NAME" "$BIN_DIR/$APP_NAME"

 for size in 16 24 32 48 64 96 128 256; do
    install -d "$ICON_BASE_DIR/${size}x${size}/apps"
-    install -m 0644 "$PROJECT_ROOT/icons/linux/crossdesk_${size}x${size}.png" \
+    install -m 0644 "$PROJECT_ROOT/apps/desktop/resources/linux/crossdesk_${size}x${size}.png" \
        "$ICON_BASE_DIR/${size}x${size}/apps/${PKG_NAME}.png"
 done

@@ -158,10 +168,11 @@ Architecture: $DEBIAN_ARCH
 Maintainer: $MAINTAINER
 Description: $DESCRIPTION
 Depends: libc6 (>= 2.31), libstdc++6 (>= 10), libx11-6, libxext6,
- libxrender1, libxft2, libxrandr2, libxfixes3, libxcursor1, libxcb1, libxcb-randr0,
+ libxrender1, libxft2, libxrandr2, libxfixes3, libxcursor1, libxi6, libxcb1, libxcb-randr0,
 libxcb-xtest0, libxcb-xinerama0, libxcb-shape0, libxcb-xkb1,
 libxcb-xfixes0, libxv1, libxtst6, $ALSA_RUNTIME_DEP, libsndio7.0,
- libxcb-shm0, libpulse0, libdrm2, libdbus-1-3, libgl1
+ libxcb-shm0, libpulse0, libdrm2, libdbus-1-3, libgl1,
+ $HEADLESS_RUNTIME_DEPS
 Recommends: $RECOMMENDS
 Priority: optional
 Section: utils
@@ -169,11 +180,12 @@ EOF

 cat > "$DESKTOP_DIR/$PKG_NAME.desktop" <<EOF
 [Desktop Entry]
-Version=$DEB_VERSION
+Version=1.0
 Name=$APP_NAME
 Comment=$DESCRIPTION
 Exec=/usr/bin/$PKG_NAME
 Icon=$PKG_NAME
+StartupWMClass=$PKG_NAME
 Terminal=false
 Type=Application
 Categories=Utility;
@@ -11,7 +11,7 @@ EXPECTED_ARCH="$2"
 APP_EXECUTABLE="$APP_BUNDLE/Contents/MacOS/CrossDesk"
 FRAMEWORKS_DIR="$APP_BUNDLE/Contents/Frameworks"

-for command_name in codesign install_name_tool lipo otool; do
+for command_name in codesign install_name_tool lipo otool strip; do
    if ! command -v "$command_name" >/dev/null 2>&1; then
        echo "Required bundling command is missing: $command_name" >&2
        exit 1
@@ -123,7 +123,11 @@ if ! otool -l "$APP_EXECUTABLE" | awk '
    install_name_tool -add_rpath "@executable_path/../Frameworks" "$APP_EXECUTABLE"
 fi

-# install_name_tool invalidates the linker's ad-hoc signature. Sign nested code
+# Strip only the staged runtime, retaining exported symbols for Slint's C ABI.
+# The package cache remains intact for debugging and other consumers.
+strip -S -x "$FRAMEWORKS_DIR/$SLINT_NAME"
+
+# install_name_tool and strip invalidate the linker's ad-hoc signature. Sign nested code
 # first, then seal the complete app bundle so local packages remain launchable.
 codesign --force --sign - "$FRAMEWORKS_DIR/$SLINT_NAME"
 codesign --force --deep --sign - "$APP_BUNDLE"
@@ -1,16 +1,19 @@
 #!/usr/bin/env bash
 set -euo pipefail

+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
 APP_NAME="crossdesk"
 APP_NAME_UPPER="CrossDesk"
-EXECUTABLE_PATH="./build/macosx/arm64/release/crossdesk"
+EXECUTABLE_PATH="${PROJECT_ROOT}/build/macosx/arm64/release/crossdesk"
 PLATFORM="macos"
 ARCH="arm64"
 BINARY_ARCH="arm64"
 IDENTIFIER="cn.crossdesk.app"
-ICON_PATH="icons/macos/crossdesk.icns"
+ICON_PATH="${PROJECT_ROOT}/apps/desktop/resources/macos/crossdesk.icns"
 MACOS_MIN_VERSION="14.0"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+cd "$PROJECT_ROOT"

 normalize_app_version() {
    local input="$1"
@@ -103,7 +106,7 @@ find "${APP_BUNDLE}" -name '._*' -delete
 echo ".app created successfully."

 mkdir -p build_pkg_scripts
-cp scripts/macosx/tcc_postinstall.sh build_pkg_scripts/postinstall
+cp "${SCRIPT_DIR}/tcc_postinstall.sh" build_pkg_scripts/postinstall
 chmod +x build_pkg_scripts/postinstall

 mkdir -p build_pkg_resources
@@ -1,16 +1,19 @@
 #!/usr/bin/env bash
 set -euo pipefail

+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
 APP_NAME="crossdesk"
 APP_NAME_UPPER="CrossDesk"
-EXECUTABLE_PATH="build/macosx/x86_64/release/crossdesk"
+EXECUTABLE_PATH="${PROJECT_ROOT}/build/macosx/x86_64/release/crossdesk"
 PLATFORM="macos"
 ARCH="x64"
 BINARY_ARCH="x86_64"
 IDENTIFIER="cn.crossdesk.app"
-ICON_PATH="icons/macos/crossdesk.icns"
+ICON_PATH="${PROJECT_ROOT}/apps/desktop/resources/macos/crossdesk.icns"
 MACOS_MIN_VERSION="14.0"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+cd "$PROJECT_ROOT"

 normalize_app_version() {
    local input="$1"
@@ -103,7 +106,7 @@ find "${APP_BUNDLE}" -name '._*' -delete
 echo ".app created successfully."

 mkdir -p build_pkg_scripts
-cp scripts/macosx/tcc_postinstall.sh build_pkg_scripts/postinstall
+cp "${SCRIPT_DIR}/tcc_postinstall.sh" build_pkg_scripts/postinstall
 chmod +x build_pkg_scripts/postinstall

 mkdir -p build_pkg_resources
@@ -12,7 +12,7 @@
 !define PRODUCT_SERVICE_NAME "CrossDeskService"

 ; Installer icon path
-!define MUI_ICON "${__FILEDIR__}\..\..\icons\windows\crossdesk.ico"
+!define MUI_ICON "${__FILEDIR__}\..\..\resources\windows\crossdesk.ico"

 ; Compression settings
 SetCompressor /FINAL lzma
@@ -84,12 +84,18 @@ installApp:
    SetOverwrite ifnewer

    ; Main application executable path
-    File /oname=CrossDesk.exe "..\..\build\windows\x64\release\crossdesk.exe"
+    File /oname=CrossDesk.exe "..\..\..\..\build\windows\x64\release\crossdesk.exe"
    ; Bundle service-side binaries required by the Windows service flow
-    File "..\..\build\windows\x64\release\crossdesk_service.exe"
-    File "..\..\build\windows\x64\release\crossdesk_session_helper.exe"
+    File "..\..\..\..\build\windows\x64\release\crossdesk_service.exe"
+    File "..\..\..\..\build\windows\x64\release\crossdesk_session_helper.exe"
+    File "..\..\..\..\build\windows\x64\release\crossdesk_privacy_cursor_helper.exe"
+    File "..\..\..\..\build\windows\x64\release\crossdesk_privacy_window.dll"
    ; Bundle runtime DLLs from the release output directory
-    File "..\..\build\windows\x64\release\*.dll"
+    File /x crossdesk_privacy_window.dll "..\..\..\..\build\windows\x64\release\*.dll"
+    ; Amyuni usbmmidd_v2 virtual display driver for headless hosts. xmake
+    ; copies apps\desktop\resources\windows\usbmmidd_v2 into the release
+    ; output directory after building crossdesk; its License.txt ships with it.
+    File /r "..\..\..\..\build\windows\x64\release\usbmmidd_v2"

    Call RegisterInstalledService

@@ -140,13 +146,19 @@ cancelUninstall:

 uninstallApp:
    Call un.UnregisterInstalledService
+    Call un.RemoveUsbmmiddDriver

    ; Delete main executable and uninstaller
    Delete "$INSTDIR\CrossDesk.exe"
    Delete "$INSTDIR\crossdesk_service.exe"
    Delete "$INSTDIR\crossdesk_session_helper.exe"
+    Delete "$INSTDIR\crossdesk_privacy_cursor_helper.exe"
+    Delete "$INSTDIR\crossdesk_privacy_window.dll"
    Delete "$INSTDIR\uninstall.exe"

+    ; Leave the install directory before removing it
+    SetOutPath "$TEMP"
+
    ; Recursively delete installation directory
    RMDir /r "$INSTDIR"

@@ -244,3 +256,50 @@ unregister_with_sc:
        Abort
    ${EndIf}
 FunctionEnd
+
+; The session helper (or an elevated CrossDesk) installs the bundled usbmmidd
+; driver on first headless use and records HKLM\SOFTWARE\CrossDesk\
+; UsbmmiddDriverInstalled in the 64-bit registry view. Only a driver CrossDesk
+; installed is removed here; one set up by the user for other software stays.
+; deviceinstaller64.exe resolves usbmmIdd.dll relative to the working
+; directory, so run it from the driver folder. Failures are logged, not fatal:
+; the driver can still be removed from Device Manager.
+Function un.RemoveUsbmmiddDriver
+    IfFileExists "$INSTDIR\usbmmidd_v2\deviceinstaller64.exe" 0 done
+
+    SetRegView 64
+    ClearErrors
+    ReadRegDWORD $0 HKLM "Software\${PRODUCT_NAME}" "UsbmmiddDriverInstalled"
+    ${If} ${Errors}
+    ${OrIf} $0 != 1
+        SetRegView lastused
+        Return
+    ${EndIf}
+
+    DetailPrint "Removing the usbmmidd virtual display driver installed by CrossDesk"
+    SetOutPath "$INSTDIR\usbmmidd_v2"
+    ; Unplug every virtual monitor first (the driver allows up to four).
+    StrCpy $1 0
+unplug_loop:
+    nsExec::ExecToLog '"$INSTDIR\usbmmidd_v2\deviceinstaller64.exe" enableidd 0'
+    Pop $2
+    IntOp $1 $1 + 1
+    ${If} $2 = 0
+    ${AndIf} $1 < 4
+        Goto unplug_loop
+    ${EndIf}
+    nsExec::ExecToLog '"$INSTDIR\usbmmidd_v2\deviceinstaller64.exe" stop usbmmidd'
+    Pop $2
+    nsExec::ExecToLog '"$INSTDIR\usbmmidd_v2\deviceinstaller64.exe" remove usbmmidd'
+    Pop $2
+    ${If} $2 != 0
+        DetailPrint "usbmmidd driver removal returned $2; remove 'USB Mobile Monitor Virtual Display' from Device Manager if it remains"
+    ${EndIf}
+    SetOutPath "$TEMP"
+
+    DeleteRegValue HKLM "Software\${PRODUCT_NAME}" "UsbmmiddDriverInstalled"
+    DeleteRegKey /ifempty HKLM "Software\${PRODUCT_NAME}"
+    SetRegView lastused
+
+done:
+FunctionEnd
@@ -0,0 +1,76 @@
+#include "daemon.h"
+
+#include <chrono>
+#include <iostream>
+#include <thread>
+#include <utility>
+
+#include "platform/daemon_backend.h"
+
+namespace {
+
+constexpr int kRestartDelayMs = 1000;
+
+}  // namespace
+
+Daemon::Daemon(const std::string& name) : name_(name), running_(false) {}
+
+void Daemon::stop() {
+  running_.store(false);
+  crossdesk::platform::RequestDaemonStop();
+}
+
+bool Daemon::isRunning() const {
+  return running_.load() && !crossdesk::platform::DaemonStopRequested();
+}
+
+bool Daemon::start(MainLoopFunc loop) {
+  crossdesk::platform::ResetDaemonStop();
+  if (!crossdesk::platform::PrepareDaemon()) return false;
+  running_.store(true);
+  return runWithRestart(std::move(loop));
+}
+
+bool Daemon::runWithRestart(MainLoopFunc loop) {
+  int restart_count = 0;
+  const std::string executable_path =
+      crossdesk::platform::GetDaemonExecutablePath();
+  if (executable_path.empty()) {
+    std::cerr
+        << "Failed to get executable path, falling back to direct execution"
+        << std::endl;
+    while (isRunning()) {
+      try {
+        loop();
+        break;
+      } catch (...) {
+        ++restart_count;
+        std::cerr << "Exception caught, restarting... (attempt "
+                  << restart_count << ")" << std::endl;
+        std::this_thread::sleep_for(
+            std::chrono::milliseconds(kRestartDelayMs));
+      }
+    }
+    return true;
+  }
+
+  while (isRunning()) {
+    const crossdesk::platform::DaemonChildResult result =
+        crossdesk::platform::RunDaemonChild(
+            executable_path, [this] { return isRunning(); });
+    if (!isRunning() || result.normal_exit) break;
+
+    ++restart_count;
+    if (!result.started) {
+      std::cerr << "Failed to create child process";
+    } else if (result.terminated_by_signal) {
+      std::cerr << "Child process crashed with signal " << result.exit_code;
+    } else {
+      std::cerr << "Child process exited with code " << result.exit_code;
+    }
+    std::cerr << ", restarting... (attempt " << restart_count << ")"
+              << std::endl;
+    std::this_thread::sleep_for(std::chrono::milliseconds(kRestartDelayMs));
+  }
+  return true;
+}
@@ -8,7 +8,6 @@
 #define _DAEMON_H_

 #include <atomic>
-#include <csignal>
 #include <functional>
 #include <string>

@@ -28,9 +27,6 @@ class Daemon {
  std::string name_;
  bool runWithRestart(MainLoopFunc loop);

-#ifndef _WIN32
-  static volatile std::sig_atomic_t stop_requested_;
-#endif
  std::atomic<bool> running_;
 };

@@ -6,6 +6,7 @@
 #endif
 #endif

+#include <cstdlib>
 #include <cstring>
 #include <filesystem>
 #include <iostream>
@@ -15,14 +16,24 @@
 #ifdef _WIN32
 #include <cstdio>

+#include "platform/windows/gui/slint_backend.h"
 #include "service_host.h"
 #endif

 #include "config_center.h"
 #include "daemon.h"
 #include "path_manager.h"
+#include "platform/single_instance.h"
+#include "rd_log.h"
 #include "render.h"

+#ifdef __linux__
+#include "SimpleIni.h"
+#include "platform/linux/headless/headless_console.h"
+#include "platform/linux/headless/headless_session.h"
+#include "platform/linux/privacy/privacy_guard.h"
+#endif
+
 #ifdef _WIN32
 namespace {

@@ -173,27 +184,37 @@ int HandleServiceCliCommand(const std::string& command) {
 }  // namespace
 #endif

-int main(int argc, char* argv[]) {
-#ifdef _WIN32
-  if (argc > 1 && IsServiceCliCommand(argv[1])) {
-    return HandleServiceCliCommand(argv[1]);
+static bool IsDaemonChild(int argc, char* argv[]) {
+  for (int i = 1; i < argc; ++i) {
+    if (std::strcmp(argv[i], "--child") == 0) return true;
  }
-#endif
+  return false;
+}

-  // check if running as child process
-  bool is_child = false;
-  for (int i = 1; i < argc; i++) {
-    if (strcmp(argv[i], "--child") == 0) {
-      is_child = true;
-      break;
-    }
+static crossdesk::platform::InstanceResult AcquireInstance(
+    crossdesk::platform::SingleInstanceGuard& guard,
+    crossdesk::platform::InstanceRole role) {
+  std::string error;
+  const auto result = guard.TryAcquire(role, error);
+  if (result == crossdesk::platform::InstanceResult::kAlreadyRunning) {
+    std::cerr << "CrossDesk is already running for this user.\n";
+  } else if (result == crossdesk::platform::InstanceResult::kError) {
+    std::cerr << "CrossDesk cannot start: " << error << '\n';
  }
+  return result;
+}

-  if (is_child) {
+static int RunApplication(
+    int argc, char* argv[],
+    crossdesk::platform::SingleInstanceGuard& client_instance) {
+  // The instance guards are held before any configuration or logger is opened.
+  auto path_manager = std::make_unique<crossdesk::PathManager>("CrossDesk");
+  crossdesk::InitLogger(path_manager->GetLogPath().string());
+
+  if (IsDaemonChild(argc, argv)) {
    // child process: run render directly
    crossdesk::Render render;
-    render.Run();
-    return 0;
+    return render.Run();
  }

 #ifdef _WIN32
@@ -201,19 +222,38 @@ int main(int argc, char* argv[]) {
 #endif

  bool enable_daemon = false;
-  auto path_manager = std::make_unique<crossdesk::PathManager>("CrossDesk");
  if (path_manager) {
    std::string cache_path = path_manager->GetCachePath().string();
    crossdesk::ConfigCenter config_center(cache_path + "/config.ini");
    enable_daemon = config_center.IsEnableDaemon();
  }

+#ifdef __linux__
+  // The headless supervisor owns the display and application lifetime. A
+  // detached daemon would outlive its display; systemd can restart the whole
+  // session instead.
+  if (std::getenv("CROSSDESK_HEADLESS_ACTIVE") ||
+      crossdesk::HeadlessConsole::Instance().active()) enable_daemon = false;
+#endif
+
  if (enable_daemon) {
+    // The launcher lease stays in main for the supervisor's entire lifetime.
+    // Each --child must acquire its own client lease, so it is neither blocked
+    // by its supervisor nor able to bypass the single-client restriction.
+    client_instance.Release();
    // start daemon with restart monitoring
    Daemon daemon("CrossDesk");

    // define main loop function: run render and stop daemon on normal exit
-    Daemon::MainLoopFunc main_loop = [&daemon]() {
+    Daemon::MainLoopFunc main_loop = [&daemon, &client_instance]() {
+      // Executable discovery can fail and make the supervisor run the GUI in
+      // process. This fallback must retain the same client ownership rule.
+      if (AcquireInstance(client_instance,
+                          crossdesk::platform::InstanceRole::kClient) !=
+          crossdesk::platform::InstanceResult::kAcquired) {
+        daemon.stop();
+        return;
+      }
      crossdesk::Render render;
      render.Run();
      daemon.stop();
@@ -226,6 +266,71 @@ int main(int argc, char* argv[]) {

  // run without daemon: direct execution
  crossdesk::Render render;
-  render.Run();
-  return 0;
-}
+  return render.Run();
+}
+
+int main(int argc, char* argv[]) {
+#ifdef __linux__
+  // Run before GUI, configuration, logging or display initialization.
+  if (argc == 2 &&
+      std::strcmp(argv[1], crossdesk::kLinuxPrivacyGuardArgument) == 0) {
+    return crossdesk::RunLinuxPrivacyGuard();
+  }
+  auto& console = crossdesk::HeadlessConsole::Instance();
+  if (argc == 2 && std::strcmp(argv[1], "--headless-help") == 0) {
+    crossdesk::PathManager paths("CrossDesk");
+    CSimpleIniA config;
+    config.SetUnicode(true);
+    config.LoadFile((paths.GetCachePath() / "config.ini").string().c_str());
+    console.SetLanguage(static_cast<int>(config.GetLongValue("Settings", "language", 0)));
+    std::cout << console.Text("console_cli_help");
+    return 0;
+  }
+#endif
+#ifdef _WIN32
+  if (argc == 2 &&
+      std::strcmp(argv[1], crossdesk::kSlintRendererProbeArgument) == 0) {
+    return crossdesk::RunSlintRendererProbe();
+  }
+  if (argc > 1 && IsServiceCliCommand(argv[1])) {
+    EnsureConsoleForCli();
+    crossdesk::platform::SingleInstanceGuard cli_instance;
+    if (AcquireInstance(cli_instance, crossdesk::platform::InstanceRole::kServiceCli) !=
+        crossdesk::platform::InstanceResult::kAcquired) return 1;
+    crossdesk::PathManager paths("CrossDesk");
+    crossdesk::InitLogger(paths.GetLogPath().string(), "crossdesk-service-cli");
+    return HandleServiceCliCommand(argv[1]);
+  }
+#endif
+
+  using crossdesk::platform::InstanceResult;
+  using crossdesk::platform::InstanceRole;
+  crossdesk::platform::SingleInstanceGuard launcher_instance;
+  crossdesk::platform::SingleInstanceGuard client_instance;
+  if (!IsDaemonChild(argc, argv)) {
+    const auto result = AcquireInstance(launcher_instance, InstanceRole::kLauncher);
+    if (result != InstanceResult::kAcquired)
+      return result == InstanceResult::kAlreadyRunning ? 0 : 1;
+  }
+  const auto result = AcquireInstance(client_instance, InstanceRole::kClient);
+  if (result != InstanceResult::kAcquired)
+    return result == InstanceResult::kAlreadyRunning ? 0 : 1;
+
+#ifdef __linux__
+  const int exit_code = crossdesk::RunWithLinuxDisplay(
+      argc, argv, [&] { return RunApplication(argc, argv, client_instance); }, [&] {
+        crossdesk::PathManager paths("CrossDesk");
+        if (console.Enable(paths.GetLogPath(), paths.GetCachePath() / "config.ini")) return true;
+        std::cerr << "无法初始化日志或控制台，启动失败。\n";
+        return false;
+      });
+  if (console.active()) {
+    console.Notify(exit_code == 0 ? console.Text("console_exited")
+        : console.Text("console_stopped") + " " + std::to_string(exit_code) +
+          "; " + console.Text("console_log_file") + ": " + console.diagnostic_path());
+  }
+  return exit_code;
+#else
+  return RunApplication(argc, argv, client_instance);
+#endif
+}
@@ -0,0 +1,21 @@
+#include "autostart.h"
+
+#include "platform/autostart_backend.h"
+
+namespace crossdesk {
+
+bool EnableAutostart(const std::string& app_name) {
+  const std::string executable_path = platform::GetAutostartExecutablePath();
+  return !executable_path.empty() &&
+         platform::EnableAutostart(app_name, executable_path);
+}
+
+bool DisableAutostart(const std::string& app_name) {
+  return platform::DisableAutostart(app_name);
+}
+
+bool IsAutostartEnabled(const std::string& app_name) {
+  return platform::IsAutostartEnabled(app_name);
+}
+
+}  // namespace crossdesk
@@ -7,7 +7,7 @@
 #ifndef _PLATFORM_H_
 #define _PLATFORM_H_

-#include <iostream>
+#include <string>

 namespace crossdesk {

@@ -1,5 +1,7 @@
 #include "shared_cursor_state.h"

+#include <remote_action.h>
+
 #include <mutex>

 namespace crossdesk {
@@ -3,7 +3,7 @@

 #include <cstdint>

-#include "remote_cursor_shape.h"
+#include <remote_cursor_shape.h>

 namespace crossdesk {

@@ -0,0 +1,88 @@
+#include "task_queue_lock_free.h"
+
+#include <concurrentqueue.h>
+
+#include <exception>
+#include <new>
+#include <stdexcept>
+#include <utility>
+
+namespace crossdesk {
+
+struct TaskQueueLockFree::QueueStorage {
+  moodycamel::ConcurrentQueue<TaskItem> tasks;
+  // All submissions share one producer so different caller threads keep FIFO.
+  moodycamel::ProducerToken producer{tasks};
+};
+
+TaskQueueLockFree::TaskQueueLockFree()
+    : queue_(std::make_unique<QueueStorage>()),
+      worker_([this] { WorkerThread(); }) {}
+
+TaskQueueLockFree::~TaskQueueLockFree() { Stop(); }
+
+std::future<void> TaskQueueLockFree::PostTask(std::function<void()> task) {
+  TaskItem item;
+  item.run = std::move(task);
+  auto result = item.completion.get_future();
+  {
+    std::lock_guard lock(mutex_);
+    if (stopping_) {
+      throw std::runtime_error("Cannot post to a stopped task queue");
+    }
+
+    // Count before publishing: the worker may dequeue as soon as enqueue returns.
+    ++pending_tasks_;
+    if (!queue_->tasks.enqueue(queue_->producer, std::move(item))) {
+      --pending_tasks_;
+      throw std::bad_alloc();
+    }
+  }
+  wake_.notify_one();
+  return result;
+}
+
+void TaskQueueLockFree::Stop() {
+  // Concurrent Stop callers all wait for the same worker shutdown to finish.
+  std::call_once(stop_once_, [this] {
+    {
+      std::lock_guard lock(mutex_);
+      stopping_ = true;
+    }
+    wake_.notify_all();
+    worker_.join();
+  });
+}
+
+void TaskQueueLockFree::WorkerThread() {
+  while (true) {
+    TaskItem item;
+    while (queue_->tasks.try_dequeue(item)) {
+      --pending_tasks_;
+
+      std::exception_ptr error;
+      try {
+        item.run();
+      } catch (...) {
+        error = std::current_exception();
+      }
+
+      // Release captured resources before marking the task complete.
+      item.run = nullptr;
+      if (error) {
+        item.completion.set_exception(error);
+      } else {
+        item.completion.set_value();
+      }
+    }
+
+    std::unique_lock lock(mutex_);
+    wake_.wait(lock, [this] { return stopping_ || pending_tasks_ > 0; });
+    // A stop request must not discard tasks submitted while the worker was idle.
+    if (stopping_ && pending_tasks_ == 0) {
+      return;
+    }
+  }
+}
+
+}  // namespace crossdesk
@@ -0,0 +1,55 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-07
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _TASK_QUEUE_LOCK_FREE_H_
+#define _TASK_QUEUE_LOCK_FREE_H_
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <functional>
+#include <future>
+#include <memory>
+#include <mutex>
+#include <thread>
+
+namespace crossdesk {
+
+// A single worker executes tasks in submission order. The concurrent queue
+// stores tasks; a mutex coordinates submissions, worker wakeups and shutdown.
+class TaskQueueLockFree {
+ public:
+  TaskQueueLockFree();
+  ~TaskQueueLockFree();
+
+  // Returns completion or the task's exception. Throws if the queue is stopped.
+  std::future<void> PostTask(std::function<void()> task);
+
+  // Rejects new tasks, finishes accepted tasks and joins the worker.
+  // May be called repeatedly, but never from the queue's own tasks.
+  void Stop();
+
+ private:
+  struct TaskItem {
+    std::function<void()> run;
+    std::promise<void> completion;
+  };
+
+  void WorkerThread();
+
+  struct QueueStorage;
+  std::unique_ptr<QueueStorage> queue_;
+  std::atomic<std::size_t> pending_tasks_{0};
+  std::mutex mutex_;
+  std::condition_variable wake_;
+  bool stopping_ = false;
+  std::once_flag stop_once_;
+  std::thread worker_;
+};
+
+}  // namespace crossdesk
+
+#endif
@@ -0,0 +1,439 @@
+#include "config_center.h"
+
+#include <algorithm>
+#include <chrono>
+#include <cstring>
+#include <filesystem>
+#include <optional>
+#include <vector>
+
+#include "SimpleIni.h"
+#include "autostart.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+struct ConfigCenter::IniStorage : CSimpleIniA {};
+
+namespace {
+
+bool IsValidTurnModeValue(long value) {
+  return value >= static_cast<long>(ConfigCenter::TURN_MODE::DISABLED) &&
+         value <= static_cast<long>(ConfigCenter::TURN_MODE::FORCE_TCP);
+}
+
+}  // namespace
+
+ConfigCenter::ConfigCenter(const std::string& config_path)
+    : config_path_(config_path), ini_(std::make_unique<IniStorage>()) {
+  ini_->SetUnicode(true);
+  Load();
+}
+
+ConfigCenter::~ConfigCenter() {}
+
+int ConfigCenter::Load() {
+  SI_Error rc = ini_->LoadFile(config_path_.c_str());
+  if (rc < 0) {
+    Save();
+    return -1;
+  }
+
+  bool persist_config_migration = false;
+  // These options now belong only to the active remote connection. Discard
+  // legacy local defaults so they cannot affect this host or new connections.
+  persist_config_migration |= ini_->Delete(section_, "video_quality");
+  persist_config_migration |= ini_->Delete(section_, "video_frame_rate");
+  persist_config_migration |= ini_->Delete(section_, "video_adaptation_policy");
+  persist_config_migration |= ini_->Delete(section_, "video_content_type");
+  persist_config_migration |= ini_->Delete(section_, "screen_content");
+  persist_config_migration |=
+      ini_->Delete(section_, "enable_desktop_quality_optimization");
+  persist_config_migration |=
+      ini_->Delete(section_, "enable_minimize_to_tray");
+
+  const long language_value =
+      ini_->GetLongValue(section_, "language", static_cast<long>(language_));
+  if (language_value < static_cast<long>(LANGUAGE::CHINESE) ||
+      language_value > static_cast<long>(LANGUAGE::RUSSIAN)) {
+    language_ = LANGUAGE::ENGLISH;
+  } else {
+    language_ = static_cast<LANGUAGE>(language_value);
+  }
+
+  const long screen_capture_method_value = ini_->GetLongValue(
+      section_, "screen_capture_method",
+      static_cast<long>(ScreenCaptureMethod::Auto));
+  screen_capture_method_ = IsValidScreenCaptureMethod(screen_capture_method_value)
+                               ? static_cast<ScreenCaptureMethod>(
+                                     screen_capture_method_value)
+                               : ScreenCaptureMethod::Auto;
+
+  video_encode_format_ = static_cast<VIDEO_ENCODE_FORMAT>(
+      ini_->GetLongValue(section_, "video_encode_format",
+                        static_cast<long>(video_encode_format_)));
+
+  hardware_video_codec_ = ini_->GetBoolValue(section_, "hardware_video_codec",
+                                            hardware_video_codec_);
+  const char* turn_mode_value = ini_->GetValue(section_, "turn_mode", nullptr);
+  if (turn_mode_value != nullptr && strlen(turn_mode_value) > 0) {
+    const long parsed_turn_mode = ini_->GetLongValue(
+        section_, "turn_mode", static_cast<long>(turn_mode_));
+    if (IsValidTurnModeValue(parsed_turn_mode)) {
+      turn_mode_ = static_cast<TURN_MODE>(parsed_turn_mode);
+    } else {
+      LOG_WARN("Invalid TURN mode [{}], using auto UDP/TCP",
+               parsed_turn_mode);
+      turn_mode_ = TURN_MODE::AUTO_UDP_TCP;
+    }
+  } else {
+    const bool legacy_enable_turn = ini_->GetBoolValue(
+        section_, "enable_turn", turn_mode_ != TURN_MODE::DISABLED);
+    turn_mode_ = legacy_enable_turn ? TURN_MODE::AUTO_UDP_TCP
+                                    : TURN_MODE::DISABLED;
+    ini_->SetLongValue(section_, "turn_mode", static_cast<long>(turn_mode_));
+    persist_config_migration = true;
+  }
+  // Migrate the former user switch. Keep true in the file for older builds,
+  // while the current application always requests encrypted native media.
+  if (!ini_->GetBoolValue(section_, "enable_srtp", false)) {
+    ini_->SetBoolValue(section_, "enable_srtp", true);
+    persist_config_migration = true;
+  }
+  enable_self_hosted_ =
+      ini_->GetBoolValue(section_, "enable_self_hosted", enable_self_hosted_);
+
+  const char* signal_server_host_value =
+      ini_->GetValue(section_, "signal_server_host", nullptr);
+  if (signal_server_host_value != nullptr &&
+      strlen(signal_server_host_value) > 0) {
+    signal_server_host_ = signal_server_host_value;
+  } else {
+    signal_server_host_ = "";
+  }
+  const char* signal_server_port_value =
+      ini_->GetValue(section_, "signal_server_port", nullptr);
+  if (signal_server_port_value != nullptr &&
+      strlen(signal_server_port_value) > 0) {
+    signal_server_port_ =
+        static_cast<int>(ini_->GetLongValue(section_, "signal_server_port", 0));
+  } else {
+    signal_server_port_ = 0;
+  }
+  enable_autostart_ =
+      ini_->GetBoolValue(section_, "enable_autostart", enable_autostart_);
+  enable_daemon_ = ini_->GetBoolValue(section_, "enable_daemon", enable_daemon_);
+  enable_privacy_screen_.store(
+      ini_->GetBoolValue(section_, "enable_privacy_screen", true));
+  portable_service_prompt_suppressed_ =
+      ini_->GetBoolValue(section_, "portable_service_prompt_suppressed",
+                        portable_service_prompt_suppressed_);
+
+  const char* file_transfer_save_path_value =
+      ini_->GetValue(section_, "file_transfer_save_path", nullptr);
+  if (file_transfer_save_path_value != nullptr &&
+      strlen(file_transfer_save_path_value) > 0) {
+    file_transfer_save_path_ = file_transfer_save_path_value;
+  } else {
+    file_transfer_save_path_ = "";
+  }
+
+  if (persist_config_migration && CommitIni() < 0) {
+    return -1;
+  }
+
+  return 0;
+}
+
+int ConfigCenter::CommitIni() {
+  // Write beside the destination and rename only after a complete save. A
+  // failed write must not truncate the last usable configuration.
+  static std::atomic<unsigned long> sequence{0};
+  const std::string temporary = config_path_ + ".tmp-" +
+      std::to_string(std::chrono::steady_clock::now().time_since_epoch().count()) +
+      "-" + std::to_string(sequence++);
+  std::error_code error;
+  if (ini_->SaveFile(temporary.c_str()) < 0) {
+    LOG_ERROR("Failed to write configuration: {}", config_path_);
+    std::filesystem::remove(temporary, error);
+    return -1;
+  }
+  const auto previous = std::filesystem::status(config_path_, error);
+  if (!error && std::filesystem::is_regular_file(previous)) {
+    std::filesystem::permissions(temporary, previous.permissions(), error);
+    if (error) {
+      LOG_ERROR("Failed to preserve configuration permissions: {}", error.message());
+      std::filesystem::remove(temporary, error);
+      return -1;
+    }
+  }
+  std::filesystem::rename(temporary, config_path_, error);
+  if (!error) return 0;
+  LOG_ERROR("Failed to replace configuration {}: {}", config_path_, error.message());
+  std::filesystem::remove(temporary, error);
+  return -1;
+}
+
+int ConfigCenter::StoreValues(
+    std::initializer_list<std::pair<const char*, std::string>> values) {
+  std::vector<std::pair<const char*, std::optional<std::string>>> previous;
+  for (const auto& value : values) {
+    const char* old = ini_->GetValue(section_, value.first, nullptr);
+    previous.emplace_back(value.first, old ? std::optional<std::string>(old) : std::nullopt);
+    ini_->SetValue(section_, value.first, value.second.c_str());
+  }
+  if (CommitIni() == 0) return 0;
+  for (const auto& value : previous) {
+    if (value.second) ini_->SetValue(section_, value.first, value.second->c_str());
+    else ini_->Delete(section_, value.first);
+  }
+  return -1;
+}
+
+int ConfigCenter::Save() {
+  ini_->SetLongValue(section_, "language", static_cast<long>(language_));
+  ini_->SetLongValue(section_, "screen_capture_method",
+                    static_cast<long>(screen_capture_method_));
+  ini_->SetLongValue(section_, "video_encode_format",
+                    static_cast<long>(video_encode_format_));
+  ini_->SetBoolValue(section_, "hardware_video_codec", hardware_video_codec_);
+  ini_->SetLongValue(section_, "turn_mode", static_cast<long>(turn_mode_));
+  ini_->SetBoolValue(section_, "enable_turn",
+                    turn_mode_ != TURN_MODE::DISABLED);
+  ini_->SetBoolValue(section_, "enable_srtp", true);
+  ini_->SetBoolValue(section_, "enable_self_hosted", enable_self_hosted_);
+
+  // only save when self hosted
+  if (enable_self_hosted_) {
+    ini_->SetValue(section_, "signal_server_host", signal_server_host_.c_str());
+    ini_->SetLongValue(section_, "signal_server_port",
+                      static_cast<long>(signal_server_port_));
+  }
+
+  ini_->SetBoolValue(section_, "enable_autostart", enable_autostart_);
+  ini_->SetBoolValue(section_, "enable_daemon", enable_daemon_);
+  ini_->SetBoolValue(section_, "enable_privacy_screen",
+                    enable_privacy_screen_.load());
+  ini_->SetBoolValue(section_, "portable_service_prompt_suppressed",
+                    portable_service_prompt_suppressed_);
+
+  ini_->SetValue(section_, "file_transfer_save_path",
+                file_transfer_save_path_.c_str());
+
+  SI_Error rc = CommitIni();
+  if (rc < 0) {
+    return -1;
+  }
+
+  return 0;
+}
+
+// setters
+
+int ConfigCenter::SetLanguage(LANGUAGE language) {
+  const int value = static_cast<int>(language);
+  if (value < 0 || value > 2 || StoreValues({{"language", std::to_string(value)}}) != 0) return -1;
+  language_ = language;
+  return 0;
+}
+
+int ConfigCenter::SetScreenCaptureMethod(ScreenCaptureMethod method) {
+  if (!IsValidScreenCaptureMethod(static_cast<long>(method))) {
+    return -1;
+  }
+  ini_->SetLongValue(section_, "screen_capture_method", static_cast<long>(method));
+  if (CommitIni() < 0) {
+    ini_->SetLongValue(section_, "screen_capture_method",
+                      static_cast<long>(screen_capture_method_));
+    return -1;
+  }
+  screen_capture_method_ = method;
+  return 0;
+}
+
+int ConfigCenter::SetVideoEncodeFormat(VIDEO_ENCODE_FORMAT format) {
+  if (format != VIDEO_ENCODE_FORMAT::H264 && format != VIDEO_ENCODE_FORMAT::AV1) return -1;
+  if (StoreValues({{"video_encode_format", std::to_string(static_cast<int>(format))}}) != 0) return -1;
+  video_encode_format_ = format;
+  return 0;
+}
+
+int ConfigCenter::SetHardwareVideoCodec(bool enabled) {
+  if (enabled && !IsHardwareVideoCodecAvailable()) return -1;
+  if (StoreValues({{"hardware_video_codec", enabled ? "true" : "false"}}) != 0) return -1;
+  hardware_video_codec_ = enabled;
+  return 0;
+}
+
+int ConfigCenter::SetTurnMode(TURN_MODE mode) {
+  if (!IsValidTurnModeValue(static_cast<long>(mode))) return -1;
+  if (StoreValues({{"turn_mode", std::to_string(static_cast<int>(mode))},
+                   {"enable_turn", mode == TURN_MODE::DISABLED ? "false" : "true"}}) != 0) return -1;
+  turn_mode_ = mode;
+  return 0;
+}
+
+int ConfigCenter::SetTurn(bool enable_turn, bool force_relay) {
+  if (!enable_turn) {
+    return SetTurnMode(TURN_MODE::DISABLED);
+  }
+  if (!force_relay) {
+    return SetTurnMode(TURN_MODE::AUTO_UDP_TCP);
+  }
+  // Use TURN/UDP by default, preserving an explicitly configured TCP relay.
+  return SetTurnMode(turn_mode_ == TURN_MODE::FORCE_TCP ? TURN_MODE::FORCE_TCP
+                                                     : TURN_MODE::FORCE_UDP);
+}
+
+int ConfigCenter::SetServerHost(const std::string& host) {
+  if (host.empty() || host.size() > 253 || host.find_first_of("/\\@?#") != std::string::npos ||
+      std::any_of(host.begin(), host.end(), [](unsigned char c) { return c <= 32 || c == 127; })) return -1;
+  if (StoreValues({{"signal_server_host", host}}) != 0) return -1;
+  signal_server_host_ = host;
+  return 0;
+}
+
+int ConfigCenter::SetServerPort(int port) {
+  if (port < 1 || port > 65535 || StoreValues({{"signal_server_port", std::to_string(port)}}) != 0) return -1;
+  signal_server_port_ = port;
+  return 0;
+}
+
+int ConfigCenter::SetSelfHosted(bool enabled) {
+  if (enabled && (signal_server_host_.empty() || signal_server_port_ < 1 || signal_server_port_ > 65535)) return -1;
+  if (StoreValues({{"enable_self_hosted", enabled ? "true" : "false"}}) != 0) return -1;
+  enable_self_hosted_ = enabled;
+  return 0;
+}
+
+int ConfigCenter::SetAutostart(bool enabled) {
+  const bool previous = IsAutostartEnabled("CrossDesk");
+  if (enabled != previous && !(enabled ? EnableAutostart("CrossDesk") : DisableAutostart("CrossDesk"))) {
+    LOG_ERROR("SetAutostart failed");
+    return -1;
+  }
+  if (StoreValues({{"enable_autostart", enabled ? "true" : "false"}}) != 0) {
+    if (enabled != previous) {
+      if (previous) EnableAutostart("CrossDesk");
+      else DisableAutostart("CrossDesk");
+    }
+    return -1;
+  }
+  enable_autostart_ = enabled;
+  return 0;
+}
+
+int ConfigCenter::SetDaemon(bool enabled) {
+  if (StoreValues({{"enable_daemon", enabled ? "true" : "false"}}) != 0) return -1;
+  enable_daemon_ = enabled;
+  return 0;
+}
+
+int ConfigCenter::SetPrivacyScreen(bool enable_privacy_screen) {
+  const bool previous = enable_privacy_screen_.load();
+  if (previous == enable_privacy_screen) return 0;
+  ini_->SetBoolValue(section_, "enable_privacy_screen", enable_privacy_screen);
+  if (CommitIni() < 0) {
+    ini_->SetBoolValue(section_, "enable_privacy_screen", previous);
+    LOG_ERROR("Failed to save automatic privacy screen preference");
+    return -1;
+  }
+  // RTC callbacks read only the value committed by the settings thread.
+  enable_privacy_screen_.store(enable_privacy_screen);
+  LOG_INFO("Privacy screen on incoming connection: {}", enable_privacy_screen);
+  return 0;
+}
+
+int ConfigCenter::SetPortableServicePromptSuppressed(bool suppressed) {
+  portable_service_prompt_suppressed_ = suppressed;
+  ini_->SetBoolValue(section_, "portable_service_prompt_suppressed",
+                    portable_service_prompt_suppressed_);
+  SI_Error rc = CommitIni();
+  if (rc < 0) {
+    return -1;
+  }
+
+  return 0;
+}
+
+// getters
+
+ConfigCenter::LANGUAGE ConfigCenter::GetLanguage() const { return language_; }
+
+ScreenCaptureMethod ConfigCenter::GetScreenCaptureMethod() const {
+  return screen_capture_method_;
+}
+
+ConfigCenter::VIDEO_ENCODE_FORMAT ConfigCenter::GetVideoEncodeFormat() const {
+  return video_encode_format_;
+}
+
+bool ConfigCenter::IsHardwareVideoCodecAvailable() {
+#if (((defined(_WIN32) || defined(__linux__)) && !defined(__aarch64__) && \
+      !defined(__arm__) && USE_CUDA) ||                                   \
+     defined(__APPLE__))
+  return true;
+#else
+  return false;
+#endif
+}
+
+bool ConfigCenter::IsHardwareVideoCodec() const {
+  return IsHardwareVideoCodecAvailable() && hardware_video_codec_;
+}
+
+ConfigCenter::TURN_MODE ConfigCenter::GetTurnMode() const {
+  return turn_mode_;
+}
+
+bool ConfigCenter::IsEnableTurn() const {
+  return turn_mode_ != TURN_MODE::DISABLED;
+}
+
+bool ConfigCenter::IsForceRelay() const {
+  return turn_mode_ == TURN_MODE::FORCE_UDP || turn_mode_ == TURN_MODE::FORCE_TCP;
+}
+
+bool ConfigCenter::IsEnableSrtp() const { return true; }
+
+std::string ConfigCenter::GetSignalServerHost() const {
+  return signal_server_host_;
+}
+
+int ConfigCenter::GetSignalServerPort() const { return signal_server_port_; }
+
+std::string ConfigCenter::GetDefaultServerHost() const {
+  return signal_server_host_default_;
+}
+
+int ConfigCenter::GetDefaultSignalServerPort() const {
+  return server_port_default_;
+}
+
+bool ConfigCenter::IsSelfHosted() const { return enable_self_hosted_; }
+
+bool ConfigCenter::IsEnableAutostart() const { return enable_autostart_; }
+
+bool ConfigCenter::IsEnableDaemon() const { return enable_daemon_; }
+
+bool ConfigCenter::IsEnablePrivacyScreen() const {
+  return enable_privacy_screen_.load();
+}
+
+bool ConfigCenter::IsPortableServicePromptSuppressed() const {
+  return portable_service_prompt_suppressed_;
+}
+
+int ConfigCenter::SetFileTransferSavePath(const std::string& path) {
+  if (path.size() >= 512 || std::any_of(path.begin(), path.end(), [](unsigned char c) { return c < 32 || c == 127; })) return -1;
+  std::lock_guard<std::mutex> lock(file_path_mutex_);
+  if (StoreValues({{"file_transfer_save_path", path}}) != 0) return -1;
+  file_transfer_save_path_ = path;
+  return 0;
+}
+
+std::string ConfigCenter::GetFileTransferSavePath() const {
+  std::lock_guard<std::mutex> lock(file_path_mutex_);
+  return file_transfer_save_path_;
+}
+}  // namespace crossdesk
@@ -7,17 +7,20 @@
 #ifndef _CONFIG_CENTER_H_
 #define _CONFIG_CENTER_H_

+#include <atomic>
+#include <initializer_list>
+#include <memory>
+#include <mutex>
+#include <utility>
 #include <string>

-#include "SimpleIni.h"
+#include "screen_capturer/screen_capture_method.h"

 namespace crossdesk {

 class ConfigCenter {
 public:
  enum class LANGUAGE { CHINESE = 0, ENGLISH = 1, RUSSIAN = 2 };
-  enum class VIDEO_QUALITY { LOW = 0, MEDIUM = 1, HIGH = 2 };
-  enum class VIDEO_FRAME_RATE { FPS_30 = 0, FPS_60 = 1 };
  enum class VIDEO_ENCODE_FORMAT { H264 = 0, AV1 = 1 };
  enum class TURN_MODE {
    DISABLED = 0,
@@ -32,41 +35,40 @@ class ConfigCenter {

  // write config
  int SetLanguage(LANGUAGE language);
-  int SetVideoQuality(VIDEO_QUALITY video_quality);
-  int SetVideoFrameRate(VIDEO_FRAME_RATE video_frame_rate);
+  int SetScreenCaptureMethod(ScreenCaptureMethod method);
  int SetVideoEncodeFormat(VIDEO_ENCODE_FORMAT video_encode_format);
  int SetHardwareVideoCodec(bool hardware_video_codec);
  int SetTurnMode(TURN_MODE turn_mode);
-  int SetTurn(bool enable_turn);
-  int SetSrtp(bool enable_srtp);
+  int SetTurn(bool enable_turn, bool force_relay);
  int SetServerHost(const std::string& signal_server_host);
  int SetServerPort(int signal_server_port);
-  int SetCoturnServerPort(int coturn_server_port);
  int SetSelfHosted(bool enable_self_hosted);
  int SetAutostart(bool enable_autostart);
  int SetDaemon(bool enable_daemon);
+  int SetPrivacyScreen(bool enable_privacy_screen);
  int SetPortableServicePromptSuppressed(bool suppressed);
  int SetFileTransferSavePath(const std::string& path);

  // read config

  LANGUAGE GetLanguage() const;
-  VIDEO_QUALITY GetVideoQuality() const;
-  VIDEO_FRAME_RATE GetVideoFrameRate() const;
+  ScreenCaptureMethod GetScreenCaptureMethod() const;
  VIDEO_ENCODE_FORMAT GetVideoEncodeFormat() const;
+  // Whether this build includes a hardware video codec backend.
+  static bool IsHardwareVideoCodecAvailable();
  bool IsHardwareVideoCodec() const;
  TURN_MODE GetTurnMode() const;
  bool IsEnableTurn() const;
+  bool IsForceRelay() const;
  bool IsEnableSrtp() const;
  std::string GetSignalServerHost() const;
  int GetSignalServerPort() const;
-  int GetCoturnServerPort() const;
  std::string GetDefaultServerHost() const;
  int GetDefaultSignalServerPort() const;
-  int GetDefaultCoturnServerPort() const;
  bool IsSelfHosted() const;
  bool IsEnableAutostart() const;
  bool IsEnableDaemon() const;
+  bool IsEnablePrivacyScreen() const;
  bool IsPortableServicePromptSuppressed() const;
  std::string GetFileTransferSavePath() const;

@@ -74,26 +76,27 @@ class ConfigCenter {
  int Save();

 private:
+  int CommitIni();
+  int StoreValues(std::initializer_list<std::pair<const char*, std::string>> values);
+  mutable std::mutex file_path_mutex_;
  std::string config_path_;
-  CSimpleIniA ini_;
+  struct IniStorage;
+  std::unique_ptr<IniStorage> ini_;
  const char* section_ = "Settings";

  LANGUAGE language_ = LANGUAGE::CHINESE;
-  VIDEO_QUALITY video_quality_ = VIDEO_QUALITY::HIGH;
-  VIDEO_FRAME_RATE video_frame_rate_ = VIDEO_FRAME_RATE::FPS_60;
+  ScreenCaptureMethod screen_capture_method_ = ScreenCaptureMethod::Auto;
  VIDEO_ENCODE_FORMAT video_encode_format_ = VIDEO_ENCODE_FORMAT::H264;
  bool hardware_video_codec_ = false;
  TURN_MODE turn_mode_ = TURN_MODE::AUTO_UDP_TCP;
-  bool enable_srtp_ = false;
  std::string signal_server_host_ = "";
  std::string signal_server_host_default_ = "api.crossdesk.cn";
  int signal_server_port_ = 0;
  int server_port_default_ = 9099;
-  int coturn_server_port_ = 0;
-  int coturn_server_port_default_ = 3478;
  bool enable_self_hosted_ = false;
  bool enable_autostart_ = false;
  bool enable_daemon_ = false;
+  std::atomic<bool> enable_privacy_screen_{true};
  bool portable_service_prompt_suppressed_ = false;
  std::string file_transfer_save_path_ = "";
 };
@@ -0,0 +1,55 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2023-12-14
+ * Copyright (c) 2023 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _DEVICE_CONTROLLER_H_
+#define _DEVICE_CONTROLLER_H_
+
+#include <cstdint>
+#include <vector>
+
+#include <remote_action.h>
+
+#include "display_info.h"
+
+namespace crossdesk {
+
+// int key_code, bool is_down, uint32_t scan_code, bool extended
+using OnKeyAction = void (*)(int, bool, uint32_t, bool, void*);
+
+class DeviceController {
+ public:
+  virtual ~DeviceController() = default;
+};
+
+class MouseController : public DeviceController {
+ public:
+  ~MouseController() override = default;
+
+  virtual int Init(std::vector<DisplayInfo> display_info_list) = 0;
+  virtual int Destroy() = 0;
+  virtual int SendMouseCommand(RemoteAction remote_action,
+                               int display_index) = 0;
+  virtual void UpdateDisplayInfoList(
+      const std::vector<DisplayInfo>&) {}
+};
+
+class KeyboardCapturer : public DeviceController {
+ public:
+  ~KeyboardCapturer() override = default;
+
+  virtual int Hook(OnKeyAction on_key_action, void* user_ptr) = 0;
+  virtual int Unhook() = 0;
+  // Backends with an asynchronous capture loop override this so the UI can
+  // fall back to window events if that loop stops unexpectedly.
+  virtual bool IsHookActive() const { return true; }
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false) = 0;
+};
+
+}  // namespace crossdesk
+
+#endif
@@ -8,8 +8,6 @@
 #define _DEVICE_CONTROLLER_FACTORY_H_

 #include "device_controller.h"
-#include "keyboard_capturer.h"
-#include "mouse_controller.h"

 namespace crossdesk {

@@ -21,16 +19,7 @@ class DeviceControllerFactory {
  virtual ~DeviceControllerFactory() {}

 public:
-  DeviceController* Create(Device device) {
-    switch (device) {
-      case Mouse:
-        return new MouseController();
-      case Keyboard:
-        return new KeyboardCapturer();
-      default:
-        return nullptr;
-    }
-  }
+  DeviceController* Create(Device device);
 };
 }  // namespace crossdesk
-#endif
+#endif
@@ -0,0 +1,98 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _APPLICATION_STATE_H_
+#define _APPLICATION_STATE_H_
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <string>
+
+namespace crossdesk::gui_detail {
+
+struct MainWindowState {
+  bool exit_ = false;
+};
+
+// Application-global interaction flags that coordinate UI events with media
+// and remote-control devices.
+struct InteractionState {
+  bool start_mouse_controller_ = false;
+  bool mouse_controller_is_started_ = false;
+  bool start_screen_capturer_ = false;
+  bool screen_capturer_is_started_ = false;
+  bool start_keyboard_capturer_ = false;
+  bool keyboard_capturer_is_started_ = false;
+  bool keyboard_capturer_uses_window_events_ = false;
+  bool focus_on_stream_window_ = false;
+  bool audio_capture_ = false;
+  int screen_width_ = 1280;
+  int screen_height_ = 720;
+  int selected_display_ = 0;
+  char remote_id_display_[12] = "";
+  unsigned char audio_buffer_[720]{};
+  int audio_len_ = 0;
+  bool audio_buffer_fresh_ = false;
+  bool need_to_rejoin_ = false;
+  std::chrono::steady_clock::time_point last_rejoin_check_time_ =
+      std::chrono::steady_clock::now();
+  std::string controlled_remote_id_;
+  std::string focused_remote_id_;
+  std::string remote_client_id_;
+};
+
+struct UpdateState {
+  bool update_available_ = false;
+  std::string latest_version_;
+  std::string release_name_;
+  std::string release_notes_;
+  std::string release_date_;
+};
+
+struct StreamWindowState {
+  bool need_to_create_stream_window_ = false;
+  bool stream_window_created_ = false;
+  bool stream_window_inited_ = false;
+  bool control_mouse_ = false;
+};
+
+struct ServerWindowState {
+  // Transport callbacks run outside the UI thread. Keep the two lifecycle
+  // requests atomic so a disconnect cannot be lost while the Slint timer is
+  // deciding whether to create or destroy the controlled-side window.
+  std::atomic<bool> need_to_create_server_window_{false};
+  std::atomic<bool> need_to_destroy_server_window_{false};
+  bool server_window_created_ = false;
+  bool server_window_inited_ = false;
+  bool server_window_collapsed_ = false;
+};
+
+struct UiState {
+  bool password_validating_ = false;
+  uint32_t password_validating_time_ = 0;
+  bool rejoin_ = false;
+  bool show_password_ = true;
+  bool show_connection_status_window_ = false;
+  bool fullscreen_button_pressed_ = false;
+  bool is_client_mode_ = false;
+  bool is_server_mode_ = false;
+  bool reload_recent_connections_ = true;
+  bool show_offline_warning_window_ = false;
+  std::string offline_warning_text_;
+  bool re_enter_remote_id_ = false;
+};
+
+struct ApplicationState : MainWindowState,
+                          InteractionState,
+                          UpdateState,
+                          StreamWindowState,
+                          ServerWindowState,
+                          UiState {};
+
+}  // namespace crossdesk::gui_detail
+
+#endif
@@ -1,15 +1,26 @@
-#ifndef CROSSDESK_GUI_APPLICATION_H_
-#define CROSSDESK_GUI_APPLICATION_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _GUI_APPLICATION_H_
+#define _GUI_APPLICATION_H_

 #include <chrono>
 #include <memory>
 #include <string>
+#include <unordered_map>
+
+#include <remote_action.h>

 #include "runtime/cursor_state_provider.h"
 #include "runtime/gui_runtime.h"

 namespace crossdesk {

+class UpdateChecker;
+
 // Slint application shell. GuiRuntime remains the owner of transport, media,
 // device, clipboard, transfer and settings behavior.
 class GuiApplication final : private GuiRuntime {
@@ -21,6 +32,12 @@ public:

 private:
  struct SlintUi;
+  struct CursorDeliveryState {
+    CursorState last_sent{};
+    bool has_sent = false;
+    bool feedback_pending = false;
+    std::chrono::steady_clock::time_point last_sent_time{};
+  };

  void InitializeLogger();
  void InitializeSettings();
@@ -33,7 +50,9 @@ private:
  void BindStreamCallbacks();
  void BindServerCallbacks();
  void Tick();
+  void PollUpdateCheck();
  void ShareLocalCursorState();
+  bool RequestPasswordChange(const std::string &password);
  void HandlePasswordChangeResult();
  void HandleCredentialRecovery();
  void SyncMainWindow();
@@ -52,6 +71,7 @@ private:
  void UpdateLocalization();
  void ResetSettingsUi();
  void SaveSettingsFromUi();
+  void ApplySettingsFromConfig(bool reconnect);
 #if _WIN32 && CROSSDESK_PORTABLE
  void CheckPortableWindowsService();
  void StartPortableWindowsServiceInstall();
@@ -72,11 +92,11 @@ private:
  bool OpenUrl(const std::string &url);

  std::unique_ptr<SlintUi> ui_;
+  std::unique_ptr<UpdateChecker> update_checker_;
  CursorStateProvider cursor_state_provider_;
-  CursorState last_shared_cursor_state_{};
-  bool has_shared_cursor_state_ = false;
+  std::unordered_map<std::string, CursorDeliveryState>
+      cursor_delivery_states_;
  uint32_t cursor_state_sequence_ = 0;
-  std::chrono::steady_clock::time_point last_cursor_state_share_time_{};
  std::chrono::steady_clock::time_point next_video_frame_time_{};
 #if defined(__linux__) && !defined(__APPLE__)
  bool use_xwayland_gui_ = false;
@@ -86,4 +106,4 @@ private:

 } // namespace crossdesk

-#endif // CROSSDESK_GUI_APPLICATION_H_
+#endif
@@ -1,4 +1,11 @@
-#pragma once
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SERVER_WINDOW_STATE_H_
+#define _SERVER_WINDOW_STATE_H_

 #include <algorithm>
 #include <iterator>
@@ -24,5 +31,6 @@ inline int ReconcileSelectedController(const std::vector<std::string>& ids,
  }
  return static_cast<int>(std::distance(ids.begin(), selected));
 }
+} // namespace crossdesk::server_window_state

-}  // namespace crossdesk::server_window_state
+#endif
@@ -1,4 +1,11 @@
-#pragma once
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _WINDOW_GEOMETRY_H_
+#define _WINDOW_GEOMETRY_H_

 #include <algorithm>

@@ -38,3 +45,5 @@ constexpr PhysicalPosition BottomRightPosition(const PhysicalRect& bounds,
 }

 }  // namespace crossdesk::window_geometry
+
+#endif
@@ -20,11 +20,78 @@ struct TranslationRow {

 // Single source of truth for all UI strings.
 #define CROSSDESK_LOCALIZATION_ALL(X)                                          \
+  X(console_cli_help, u8"Linux 无头运行选项：\n  --headless                  自动选择已有桌面并启用控制台\n  --headless-display DISPLAY  高级：指定已有显示会话\n  --headless-size WIDTHxHEIGHT 新建虚拟屏幕；默认1920x1080，偶数尺寸320..8192\n  --headless-session EXECUTABLE 启动桌面环境（startxfce4；none 仅启动裸屏幕）\n  --no-headless               禁用自动回退\n正常启动会自动选择已有桌面，无需填写显示编号。控制台输入 settings 管理设置。\n", "Linux headless options:\n  --headless                  Select an existing desktop and enable the console\n  --headless-display DISPLAY  Advanced: override desktop selection\n  --headless-size WIDTHxHEIGHT New virtual display; default 1920x1080, even 320..8192\n  --headless-session EXECUTABLE Start a desktop (startxfce4; none for a bare display)\n  --no-headless               Disable automatic fallback\nNormal startup selects your existing desktop automatically. Enter settings in the console to configure it.\n", u8"Параметры запуска без монитора:\n  --headless                  Выбрать рабочий стол и включить консоль\n  --headless-display DISPLAY  Дополнительно: указать сеанс дисплея\n  --headless-size WIDTHxHEIGHT Новый виртуальный экран; 1920x1080 по умолчанию, чётные размеры 320..8192\n  --headless-session EXECUTABLE Запустить рабочий стол (startxfce4; none — только экран)\n  --no-headless               Отключить автоматический резервный запуск\nРабочий стол выбирается автоматически. Команда settings открывает настройки консоли.\n") \
+  X(console_title, u8"CrossDesk 无头控制台", "CrossDesk headless console", u8"Консоль CrossDesk") \
+  X(console_log_file, u8"日志文件", "Log file", u8"Файл журнала") \
+  X(console_help, u8"命令: status 查看ID/密码/状态；settings 设置；password 修改密码；random 随机密码；help 帮助；quit 退出", "Commands: status, settings, password, random, help, quit", u8"Команды: status, settings, password, random, help, quit") \
+  X(console_status, u8"状态", "Status", u8"Состояние") \
+  X(console_online, u8"在线", "Online", u8"В сети") \
+  X(console_offline, u8"未连接服务器", "Disconnected from server", u8"Нет подключения к серверу") \
+  X(console_id, u8"设备 ID", "Device ID", u8"ID устройства") \
+  X(console_password, u8"连接密码", "Connection password", u8"Пароль подключения") \
+  X(console_waiting, u8"等待分配", "Waiting for assignment", u8"Ожидание назначения") \
+  X(console_password_hidden, u8"（仅在交互终端显示）", "(shown only in an interactive terminal)", u8"(виден только в интерактивном терминале)") \
+  X(console_cancelled, u8"已取消修改。", "Change cancelled.", u8"Изменение отменено.") \
+  X(console_password_invalid, u8"密码必须是6位英文字母或数字，未提交修改。", "Password must be 6 ASCII letters or digits; no change submitted.", u8"Пароль должен содержать 6 латинских букв или цифр. Изменение не отправлено.") \
+  X(console_password_offline, u8"尚未连接服务器，暂时无法修改密码。", "Connect to the server before changing the password.", u8"Для смены пароля подключитесь к серверу.") \
+  X(console_password_prompt, u8"输入新密码（6位英文字母或数字；输入 cancel 取消）:", "New password (6 ASCII letters or digits; cancel to abort):", u8"Новый пароль (6 латинских букв или цифр; cancel — отмена):") \
+  X(console_quitting, u8"正在退出 CrossDesk……", "Exiting CrossDesk...", u8"Выход из CrossDesk...") \
+  X(console_unknown_command, u8"未知命令，输入 help 查看帮助。", "Unknown command. Enter help for commands.", u8"Неизвестная команда. Введите help для справки.") \
+  X(console_line_too_long, u8"命令过长，已忽略。", "Command too long; ignored.", u8"Команда слишком длинная и проигнорирована.") \
+  X(console_random_failed, u8"无法生成随机密码，请重试。", "Unable to generate a random password; try again.", u8"Не удалось создать случайный пароль. Повторите попытку.") \
+  X(console_password_pending, u8"密码修改正在处理中，请等待服务器确认。", "Password change pending; wait for server confirmation.", u8"Смена пароля выполняется. Дождитесь подтверждения сервера.") \
+  X(console_password_stage_failed, u8"无法保存密码修改记录，未提交修改。请检查日志。", "Unable to save password recovery record; no change submitted. Check the log.", u8"Не удалось сохранить запись восстановления пароля. Изменение не отправлено. Проверьте журнал.") \
+  X(console_password_send_failed, u8"发送密码修改请求失败，请等待连接恢复后重试。", "Failed to submit password change; retry after reconnection.", u8"Не удалось отправить запрос смены пароля. Повторите после подключения.") \
+  X(console_password_submitted, u8"已提交密码修改，正在等待服务器确认……", "Password change submitted; waiting for server confirmation...", u8"Запрос смены пароля отправлен. Ожидание подтверждения...") \
+  X(console_password_uncertain, u8"密码修改结果尚未确认，正在重新连接服务器核实。", "Password change not yet confirmed; reconnecting to verify.", u8"Смена пароля не подтверждена. Повторное подключение для проверки.") \
+  X(console_password_rejected, u8"服务器未接受密码修改，原密码保持不变。详情见日志。", "Server rejected the password change; the original password remains. See the log.", u8"Сервер отклонил смену пароля. Старый пароль сохранён. См. журнал.") \
+  X(console_password_confirmed, u8"服务器已确认密码修改，正在重新连接。", "Server confirmed the password change; reconnecting.", u8"Сервер подтвердил смену пароля. Повторное подключение.") \
+  X(console_password_recovered, u8"重新连接确认：新密码已生效。", "Reconnection confirmed: the new password is active.", u8"Повторное подключение подтвердило новый пароль.") \
+  X(console_password_retained, u8"重新连接确认：继续使用原密码。", "Reconnection confirmed: the original password remains active.", u8"Повторное подключение подтвердило прежний пароль.") \
+  X(console_exited, u8"CrossDesk 已退出。", "CrossDesk exited.", u8"CrossDesk завершён.") \
+  X(console_stopped, u8"CrossDesk 已停止，退出码", "CrossDesk stopped; exit code", u8"CrossDesk остановлен; код выхода") \
+  X(console_settings_title, u8"设置（修改后立即保存）", "Settings (each change is saved immediately)", u8"Настройки (изменения сохраняются сразу)") \
+  X(console_settings_prompt, u8"输入编号或选项名称修改；back 返回。也可使用 settings set 名称 值。", "Enter an item number or key; back to return. Shortcut: settings set KEY VALUE.", u8"Введите номер или имя параметра; back — назад. Команда: settings set KEY VALUE.") \
+  X(console_settings_value, u8"输入新值（cancel 取消）", "Enter a new value (cancel to abort)", u8"Введите новое значение (cancel — отмена)") \
+  X(console_settings_unavailable, u8"设置尚未初始化，请稍后重试。", "Settings are not ready; try again shortly.", u8"Настройки ещё не готовы. Повторите позже.") \
+  X(console_settings_invalid, u8"无效的选项或值，未保存。请按菜单列出的格式输入。", "Invalid setting or value; not saved. Use the format shown in the menu.", u8"Неверный параметр или значение. Ничего не сохранено. Используйте указанный формат.") \
+  X(console_settings_save_failed, u8"保存设置失败，原设置保持不变。请检查日志。", "Failed to save settings; the previous value is retained. Check the log.", u8"Не удалось сохранить настройки. Прежнее значение сохранено. Проверьте журнал.") \
+  X(console_settings_busy, u8"有远程会话或密码修改正在进行，暂时不能更改连接设置。", "Connection settings cannot change during a remote session or password change.", u8"Нельзя менять параметры подключения во время удалённого сеанса или смены пароля.") \
+  X(console_settings_saved, u8"已保存并生效。", "Saved and applied.", u8"Сохранено и применено.") \
+  X(console_settings_unchanged, u8"设置未改变。", "Setting unchanged.", u8"Настройка не изменилась.") \
+  X(console_settings_reconnect, u8"已保存，正在重新连接服务器。", "Saved; reconnecting to the server.", u8"Сохранено. Повторное подключение к серверу.") \
+  X(console_settings_next_connection, u8"已保存，将用于后续连接。", "Saved; applies to subsequent connections.", u8"Сохранено. Будет применено к следующим подключениям.") \
+  X(console_settings_next_file, u8"已保存，将用于后续接收的文件。", "Saved; applies to subsequently received files.", u8"Сохранено. Будет применено к следующим получаемым файлам.") \
+  X(console_settings_autostart, u8"已保存，在下次图形桌面登录时生效。", "Saved; applies at the next graphical desktop login.", u8"Сохранено. Будет применено при следующем входе в графический сеанс.") \
+  X(console_settings_daemon, u8"已保存，普通模式重启后生效；无头控制台仍保持前台运行。", "Saved for the next normal-mode start; the headless console stays in the foreground.", u8"Сохранено для следующего запуска в обычном режиме. Консоль остаётся на переднем плане.") \
+  X(console_settings_hardware_unavailable, u8"当前构建不支持硬件编解码，未保存。", "Hardware codecs are unavailable in this build; not saved.", u8"Аппаратные кодеки недоступны в этой сборке. Не сохранено.") \
+  X(console_settings_server_required, u8"请先设置有效的服务器地址和端口，再启用自托管。", "Set a valid server host and port before enabling self-hosting.", u8"Укажите адрес и порт сервера перед включением собственного сервера.") \
+  X(console_settings_path_invalid, u8"请选择已存在且可写的绝对目录路径；default 使用默认目录。", "Use an existing writable absolute directory, or default for the default location.", u8"Укажите существующий доступный для записи абсолютный путь к каталогу или default.") \
+  X(console_settings_readonly, u8"该选项由系统或控制端管理，不可在此修改。", "This option is managed by the system or controller and is read-only here.", u8"Этот параметр управляется системой или клиентом и здесь недоступен для изменения.") \
+  X(console_setting_language, u8"语言", "Language", u8"Язык") \
+  X(console_setting_codec, u8"视频编码", "Video codec", u8"Видеокодек") \
+  X(console_setting_hardware, u8"硬件编解码", "Hardware codecs", u8"Аппаратные кодеки") \
+  X(console_setting_turn, u8"中继模式", "TURN relay mode", u8"Режим ретрансляции TURN") \
+  X(console_setting_self_hosted, u8"自托管", "Self-hosted server", u8"Собственный сервер") \
+  X(console_setting_host, u8"服务器地址", "Server host", u8"Адрес сервера") \
+  X(console_setting_port, u8"信令端口", "Signaling port", u8"Порт сигнализации") \
+  X(console_setting_privacy, u8"连接时自动开启隐私屏", "Privacy screen on connection", u8"Приватный экран при подключении") \
+  X(console_setting_files, u8"文件保存目录", "Received file directory", u8"Каталог получаемых файлов") \
+  X(console_setting_autostart, u8"登录桌面时自启", "Start at desktop login", u8"Запуск при входе в систему") \
+  X(console_setting_daemon, u8"守护进程（无头控制台中不生效）", "Daemon (inactive in headless console)", u8"Фоновый режим (не действует в консоли)") \
+  X(privacy_screen, u8"隐私屏", "Privacy screen", u8"Приватный экран") \
+  X(privacy_enable, u8"开启隐私屏", "Enable privacy screen", u8"Включить приватный экран") \
+  X(privacy_disable, u8"关闭隐私屏", "Disable privacy screen", u8"Выключить приватный экран") \
+  X(privacy_on, u8"隐私屏：已开启", "Privacy screen: on", u8"Приватный экран: включён") \
+  X(privacy_off, u8"隐私屏：已关闭", "Privacy screen: off", u8"Приватный экран: выключен") \
+  X(privacy_unsupported, u8"隐私屏：不可用", "Privacy screen: unavailable", u8"Приватный экран: недоступен") \
  X(local_desktop, u8"本桌面", "Local Desktop", u8"Локальный рабочий стол")    \
  X(local_id, u8"本机ID", "Local ID", u8"Локальный ID")                        \
  X(local_id_copied_to_clipboard, u8"已复制到剪贴板", "Copied to clipboard",   \
    u8"Скопировано в буфер обмена")                                            \
  X(password, u8"密码", "Password", u8"Пароль")                                \
+  X(refresh_password, u8"刷新随机密码", "Refresh random password",            \
+    u8"Обновить случайный пароль")                                           \
  X(max_password_len, u8"最大6个字符", "Max 6 chars", u8"Макс. 6 символов")    \
  X(remote_desktop, u8"远程桌面", "Remote Desktop",                            \
    u8"Удаленный рабочий стол")                                                \
@@ -120,9 +187,22 @@ struct TranslationRow {
    u8"стола")                                                                 \
  X(settings, u8"设置", "Settings", u8"Настройки")                             \
  X(language, u8"语言:", "Language:", u8"Язык:")                               \
-  X(video_quality, u8"视频质量:", "Video Quality:", u8"Качество видео:")       \
+  X(screen_capture_method, u8"采集方式:", "Capture Method:",                  \
+    u8"Способ захвата:")                                                      \
+  X(screen_capture_method_auto, u8"自动", "Auto", u8"Авто")                 \
+  X(video_settings, u8"画面设置", "Video settings", u8"Настройки видео") \
+  X(video_settings_pending, u8"正在应用…", "Applying…", u8"Применение…") \
+  X(video_settings_failed, u8"调整失败，请重试。", "Could not apply settings. Try again.", u8"Не удалось применить настройки. Повторите попытку.") \
+  X(video_settings_unavailable, u8"连接建立后可调整，需被控端支持。", "Available when connected to a supported remote device.", u8"Доступно при подключении к поддерживаемому устройству.") \
+  X(video_quality, u8"画面质量:", "Video Quality:", u8"Качество видео:")       \
  X(video_frame_rate, u8"画面采集帧率:",                                       \
    "Video Capture Frame Rate:", u8"Частота захвата видео:")                   \
+  X(video_adaptation_policy, u8"画面偏好:", "Video Preference:",              \
+    u8"Режим видео:")                                                           \
+  X(video_priority_frame_rate, u8"帧率优先", "Frame Rate",                   \
+    u8"Частота кадров")                                                         \
+  X(video_priority_quality, u8"画质优先", "Quality", u8"Качество")          \
+  X(video_priority_balanced, u8"平衡", "Balanced", u8"Баланс")              \
  X(video_quality_high, u8"高", "High", u8"Высокое")                           \
  X(video_quality_medium, u8"中", "Medium", u8"Среднее")                       \
  X(video_quality_low, u8"低", "Low", u8"Низкое")                              \
@@ -134,7 +214,7 @@ struct TranslationRow {
    "Enable Hardware Video Codec:", u8"Использовать аппаратный кодек:")        \
  X(enable_turn, u8"启用中继服务:",                                            \
    "Enable TURN Service:", u8"Включить TURN-сервис:")                         \
-  X(enable_srtp, u8"启用SRTP:", "Enable SRTP:", u8"Включить SRTP:")            \
+  X(force_relay, u8"强制中继连接:", "Force Relay:", u8"Только через реле:")   \
  X(self_hosted_server_config, u8"自托管配置", "Self-Hosted Config",           \
    u8"Конфигурация self-hosted")                                              \
  X(self_hosted_server_settings, u8"自托管设置", "Self-Hosted Settings",       \
@@ -143,8 +223,6 @@ struct TranslationRow {
    "Server Address:", u8"Адрес сервера:")                                     \
  X(self_hosted_server_port, u8"信令服务端口:",                                \
    "Signal Service Port:", u8"Порт сигнального сервиса:")                     \
-  X(self_hosted_server_coturn_server_port, u8"中继服务端口:",                  \
-    "Relay Service Port:", u8"Порт реле-сервиса:")                             \
  X(ok, u8"确认", "OK", u8"ОК")                                                \
  X(cancel, u8"取消", "Cancel", u8"Отмена")                                    \
  X(new_password, u8"请输入六位密码:",                                         \
@@ -180,6 +258,15 @@ struct TranslationRow {
  X(notification, u8"通知", "Notification", u8"Уведомление")                   \
  X(new_version_available, u8"新版本可用", "New Version Available",            \
    u8"Доступна новая версия")                                                 \
+  X(check_for_updates, u8"检查更新", "Check for updates",                     \
+    u8"Проверить обновления")                                                   \
+  X(checking_for_updates, u8"正在检查更新…", "Checking for updates…",         \
+    u8"Проверка обновлений…")                                                  \
+  X(up_to_date, u8"已是最新版本", "You're up to date",                         \
+    u8"Установлена последняя версия")                                          \
+  X(update_check_failed, u8"检查失败，请稍后重试",                             \
+    "Check failed. Please try again later.",                                    \
+    u8"Не удалось проверить обновления. Повторите позже.")                     \
  X(release_notes, u8"更新内容", "Release Notes", u8"Содержание обновления") \
  X(version, u8"版本", "Version", u8"Версия")                                  \
  X(release_date, u8"发布日期: ", "Release Date: ", u8"Дата релиза: ")         \
@@ -198,6 +285,8 @@ struct TranslationRow {
    "Confirm to delete this connection", u8"Удалить это подключение?")         \
  X(enable_autostart, u8"开机自启:", "Auto Start:", u8"Автозапуск:")           \
  X(enable_daemon, u8"启用守护进程:", "Enable Daemon:", u8"Включить демон:")   \
+  X(privacy_on_connect, u8"被连接时开启隐私屏:", "Privacy screen on connect:", \
+    u8"Приватность при подключении:")                                       \
  X(takes_effect_after_restart, u8"重启后生效", "Takes effect after restart",  \
    u8"Вступит в силу после перезапуска")                                      \
  X(select_file, u8"选择文件发送", "Select File to Send",                      \
@@ -216,9 +305,14 @@ struct TranslationRow {
    "File Transfer Save Path:", u8"Путь сохранения файлов:")                   \
  X(default_desktop, u8"桌面", "Desktop", u8"Рабочий стол")                    \
  X(resolution, u8"分辨率", "Res", u8"Разрешение")                             \
+  X(video_latency, u8"视频延时", "Video delay", u8"Задержка") \
+  X(connection_latency, u8"连接延时", "Connection RTT", u8"Задержка соединения") \
  X(connection_mode, u8"连接模式", "Mode", u8"Режим")                          \
  X(connection_mode_direct, u8"直连", "Direct", u8"Прямой")                    \
  X(connection_mode_relay, u8"中继", "Relay", u8"Релейный")                    \
+  X(transport_encryption, u8"加密传输", "Encryption", u8"Шифрование")         \
+  X(transport_encryption_enabled, u8"已开启", "Enabled", u8"Включено")         \
+  X(transport_encryption_disabled, u8"未开启", "Disabled", u8"Выключено")       \
  X(online, u8"在线", "Online", u8"Онлайн")                                    \
  X(offline, u8"离线", "Offline", u8"Офлайн")                                  \
  X(device_offline, u8"设备离线", "Device Offline", u8"Устройство офлайн")     \
@@ -233,6 +327,9 @@ struct TranslationRow {
    u8"Для работы приложения требуются следующие разрешения:")                 \
  X(show_main_window, u8"显示主界面", "Show Main Window",                    \
    u8"Показать главное окно")                                                \
+  X(privacy_screen_unlock_hint, u8"按下快捷键，解除隐私屏",                    \
+    "To turn off the privacy screen, press",                                 \
+    u8"Чтобы отключить приватный экран, нажмите")                             \
  X(exit_program, u8"退出", "Exit", u8"Выход")

 inline constexpr TranslationRow kTranslationRows[] = {
@@ -1,5 +1,9 @@
 #include "features/clipboard/clipboard_controller.h"

+#include <SDL3/SDL_clipboard.h>
+#include <SDL3/SDL_error.h>
+#include <SDL3/SDL_events.h>
+
 #include <cstring>
 #include <shared_mutex>
 #include <utility>
@@ -1,7 +1,11 @@
-#ifndef CROSSDESK_GUI_CLIPBOARD_CONTROLLER_H_
-#define CROSSDESK_GUI_CLIPBOARD_CONTROLLER_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-25
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */

-#include <SDL3/SDL.h>
+#ifndef _CLIPBOARD_CONTROLLER_H_
+#define _CLIPBOARD_CONTROLLER_H_

 #include <atomic>
 #include <cstddef>
@@ -42,4 +46,4 @@ private:

 } // namespace crossdesk

-#endif // CROSSDESK_GUI_CLIPBOARD_CONTROLLER_H_
+#endif // _CLIPBOARD_CONTROLLER_H_
@@ -1,12 +1,27 @@
 #include "features/devices/session_device_manager.h"

+#include <SDL3/SDL_audio.h>
+#include <SDL3/SDL_error.h>
+#include <SDL3/SDL_init.h>
+
+#include <display_stream_id.h>
+#include <remote_action.h>
+
+#include <algorithm>
 #include <chrono>
 #include <cstdlib>
+#include <utility>

-#include "display_stream_id.h"
+#include "device_controller_factory.h"
+#include "screen_capturer_factory.h"
 #include "platform.h"
 #include "rd_log.h"
 #include "runtime/gui_runtime.h"
+#include "speaker_capturer_factory.h"
+#ifdef _WIN32
+#include "platform/windows/screen_capturer/screen_capturer_win.h"
+#include "platform/windows/input/mouse/mouse_controller.h"
+#endif

 namespace crossdesk {
 namespace {
@@ -17,7 +32,23 @@ constexpr auto kFrameDeadlineTolerance = std::chrono::milliseconds(1);

 } // namespace

-SessionDeviceManager::SessionDeviceManager(GuiRuntime &owner) : owner_(owner) {}
+SessionDeviceManager::SessionDeviceManager(GuiRuntime &owner)
+    : owner_(owner),
+      speaker_capture_(
+          [] {
+            return std::unique_ptr<SpeakerCapturer>(
+                SpeakerCapturerFactory().Create());
+          },
+          [this](unsigned char *data, size_t size, const char *) {
+            if (!owner_.peer_) return;
+            MiniRtcAudioFrame frame{};
+            frame.data = reinterpret_cast<const char *>(data);
+            frame.size = size;
+            frame.captured_timestamp = GetSystemTimeMicros(owner_.peer_);
+            SendAudioFrame(owner_.peer_, &frame, owner_.audio_label_.c_str());
+          }) {}
+
+SessionDeviceManager::~SessionDeviceManager() { speaker_capture_.Shutdown(); }

 bool SessionDeviceManager::ShouldSendCapturedFrame(
    std::chrono::steady_clock::time_point now, int fps) {
@@ -36,10 +67,56 @@ bool SessionDeviceManager::ShouldSendCapturedFrame(
  return true;
 }

+void SessionDeviceManager::RecordCaptureCadence(
+    std::chrono::steady_clock::time_point now, int fps,
+    bool from_secure_desktop) {
+  std::lock_guard<std::mutex> lock(capture_metrics_mutex_);
+  if (capture_metrics_started_ == std::chrono::steady_clock::time_point{})
+    capture_metrics_started_ = now;
+  const auto elapsed_us = std::chrono::duration_cast<std::chrono::microseconds>(
+                              now - capture_metrics_started_)
+                              .count();
+  if (elapsed_us >= 2000000) {
+    if (capture_forwarded_) {
+      const char* source = capture_secure_callbacks_ == 0 ? "normal_desktop"
+                           : capture_secure_callbacks_ == capture_callbacks_
+                               ? "secure_desktop"
+                               : "mixed";
+      LOG_DEBUG(
+          "Capture delivery: source={} normal_callbacks={} secure_callbacks={} "
+          "target_fps={} input_fps={:.2f} "
+          "forwarded_fps={:.2f} callbacks={} rate_dropped={} "
+          "forwarded={} send_errors={} max_callback_gap_us={} "
+          "send_avg_us={} send_max_us={} window_ms={}",
+          source, capture_callbacks_ - capture_secure_callbacks_,
+          capture_secure_callbacks_, fps,
+          capture_callbacks_ * 1000000.0 / elapsed_us,
+          capture_forwarded_ * 1000000.0 / elapsed_us, capture_callbacks_,
+          capture_rate_drops_, capture_forwarded_, capture_send_errors_,
+          capture_max_gap_us_, capture_send_us_ / capture_forwarded_,
+          capture_max_send_us_, elapsed_us / 1000);
+    }
+    capture_metrics_started_ = now;
+    capture_callbacks_ = capture_rate_drops_ = capture_forwarded_ = 0;
+    capture_secure_callbacks_ = 0;
+    capture_send_errors_ = 0;
+    capture_max_gap_us_ = capture_send_us_ = capture_max_send_us_ = 0;
+  }
+  if (last_capture_callback_ != std::chrono::steady_clock::time_point{}) {
+    capture_max_gap_us_ =
+        std::max<int64_t>(capture_max_gap_us_,
+                          std::chrono::duration_cast<std::chrono::microseconds>(
+                              now - last_capture_callback_)
+                              .count());
+  }
+  last_capture_callback_ = std::max(last_capture_callback_, now);
+  ++capture_callbacks_;
+  if (from_secure_desktop) ++capture_secure_callbacks_;
+}
+
 void SessionDeviceManager::Initialize() {
  InitializeAudioOutput();
  screen_capturer_factory_ = new ScreenCapturerFactory();
-  speaker_capturer_factory_ = new SpeakerCapturerFactory();
  device_controller_factory_ = new DeviceControllerFactory();
  keyboard_capturer_ =
      static_cast<KeyboardCapturer *>(device_controller_factory_->Create(
@@ -57,24 +134,44 @@ int SessionDeviceManager::InitializeScreenCapturer() {
    screen_capturer_ =
        static_cast<ScreenCapturer *>(screen_capturer_factory_->Create());
  }
+  screen_capturer_->SetPrivacyController(&owner_.privacy_);
+#ifdef _WIN32
+  if (auto windows = dynamic_cast<ScreenCapturerWin*>(screen_capturer_)) {
+    windows->SetCaptureMethod(owner_.config_center_->GetScreenCaptureMethod());
+  }
+#endif

  last_frame_time_ = {};
  next_frame_deadline_ = {};
-  const int fps = owner_.config_center_->GetVideoFrameRate() ==
-                          ConfigCenter::VIDEO_FRAME_RATE::FPS_30
-                      ? 30
-                      : 60;
+  capture_metrics_started_ = last_capture_callback_ = {};
+  capture_callbacks_ = capture_rate_drops_ = capture_forwarded_ = 0;
+  capture_secure_callbacks_ = 0;
+  capture_send_errors_ = 0;
+  capture_max_gap_us_ = capture_send_us_ = capture_max_send_us_ = 0;
+  // Keep the shared source ready for either live rate. MiniRTC admits 30/60
+  // frames independently per viewer, so switching never restarts native
+  // capture.
+  const int fps = 60;
  LOG_INFO("Init screen capturer with {} fps", fps);
-  display_info_list_.clear();
+  SetDisplayInfoList({});
  registered_display_stream_count_ = 0;
  last_video_frame_stream_id_.clear();
  invalid_video_stream_id_logged_ = false;

  const int init_ret = screen_capturer_->Init(
      fps, [this, fps](unsigned char *data, int size, int width, int height,
-                       const char *display_name) {
+                       const char *display_name,
+                       const MiniRtcNativeVideoFrame *native_frame) {
        const auto now_time = std::chrono::steady_clock::now();
+        bool from_secure_desktop = false;
+#ifdef _WIN32
+        from_secure_desktop =
+            ScreenCapturerWin::CurrentFrameIsFromSecureDesktop();
+#endif
+        RecordCaptureCadence(now_time, fps, from_secure_desktop);
        if (!ShouldSendCapturedFrame(now_time, fps)) {
+          std::lock_guard<std::mutex> lock(capture_metrics_mutex_);
+          ++capture_rate_drops_;
          return;
        }

@@ -128,21 +225,37 @@ int SessionDeviceManager::InitializeScreenCapturer() {
                                    last_video_frame_stream_id_ != stream_id;
        if (resumed_after_gap || stream_changed) {
          if (RequestVideoKeyFrame(owner_.peer_, stream_id.c_str()) == 0) {
-            LOG_INFO("Request video key frame before sending captured frame, "
+            LOG_DEBUG("Request video key frame before sending captured frame, "
                     "stream='{}', gap_ms={}, stream_changed={}",
                     stream_id, duration_ms, stream_changed);
          }
        }

-        XVideoFrame frame{};
+        MiniRtcVideoFrame frame{};
        frame.data = reinterpret_cast<const char *>(data);
        frame.size = size;
        frame.width = width;
        frame.height = height;
        frame.captured_timestamp = GetSystemTimeMicros(owner_.peer_);
+        frame.native_frame = native_frame;
+        const auto send_started = std::chrono::steady_clock::now();
+        uint64_t send_errors = 0;
        for (const std::string &remote_id : connected_remote_ids) {
-          SendVideoFrameToPeer(owner_.peer_, &frame, stream_id.c_str(),
-                               remote_id.data(), remote_id.size());
+          if (SendVideoFrameToPeer(owner_.peer_, &frame, stream_id.c_str(),
+                                   remote_id.data(), remote_id.size()) != 0)
+            ++send_errors;
+        }
+        const auto send_us =
+            std::chrono::duration_cast<std::chrono::microseconds>(
+                std::chrono::steady_clock::now() - send_started)
+                .count();
+        {
+          std::lock_guard<std::mutex> lock(capture_metrics_mutex_);
+          ++capture_forwarded_;
+          capture_send_errors_ += send_errors;
+          capture_send_us_ += send_us;
+          capture_max_send_us_ =
+              std::max<int64_t>(capture_max_send_us_, send_us);
        }
        last_video_frame_stream_id_ = stream_id;
        last_frame_time_ = now_time;
@@ -150,11 +263,11 @@ int SessionDeviceManager::InitializeScreenCapturer() {

  if (init_ret == 0) {
    LOG_INFO("Init screen capturer success");
-    const auto latest_display_info = screen_capturer_->GetDisplayInfoList();
+    auto latest_display_info = screen_capturer_->GetDisplayInfoList();
+    registered_display_stream_count_ = latest_display_info.size();
    if (!latest_display_info.empty()) {
-      display_info_list_ = latest_display_info;
+      SetDisplayInfoList(std::move(latest_display_info));
    }
-    registered_display_stream_count_ = display_info_list_.size();
    return 0;
  }

@@ -165,6 +278,15 @@ int SessionDeviceManager::InitializeScreenCapturer() {
  return -1;
 }

+bool SessionDeviceManager::ShouldCaptureCursor() const {
+  std::shared_lock lock(owner_.connection_status_mutex_);
+  return std::any_of(owner_.connection_status_.begin(),
+                     owner_.connection_status_.end(), [](const auto& entry) {
+    return entry.second == ConnectionStatus::Connected &&
+           entry.first.find("web") != std::string::npos;
+  });
+}
+
 int SessionDeviceManager::StartScreenCapturer() {
 #ifdef __APPLE__
  if (!owner_.EnsureMacScreenRecordingPermission()) {
@@ -180,8 +302,11 @@ int SessionDeviceManager::StartScreenCapturer() {
    }
  }

-  LOG_INFO("Start screen capturer, show cursor: {}", owner_.show_cursor_);
-  const int ret = screen_capturer_->Start(owner_.show_cursor_);
+  // Clear before sampling, so a change arriving after the sample remains pending.
+  cursor_capture_dirty_.store(false, std::memory_order_relaxed);
+  const bool show_cursor = ShouldCaptureCursor();
+  LOG_INFO("Start screen capturer, show cursor: {}", show_cursor);
+  const int ret = screen_capturer_->Start(show_cursor);
  if (ret != 0) {
    LOG_ERROR("Start screen capturer failed: {}", ret);
  }
@@ -196,42 +321,46 @@ int SessionDeviceManager::StopScreenCapturer() {
  return 0;
 }

-int SessionDeviceManager::StartSpeakerCapturer() {
-  if (!speaker_capturer_) {
-    speaker_capturer_ =
-        static_cast<SpeakerCapturer *>(speaker_capturer_factory_->Create());
-    const int init_ret = speaker_capturer_->Init(
-        [this](unsigned char *data, size_t size, const char *audio_name) {
-          SendAudioFrame(owner_.peer_, reinterpret_cast<const char *>(data),
-                         size, owner_.audio_label_.c_str());
-        });
+#ifdef _WIN32
+void SessionDeviceManager::ReleaseRemoteMouseButtons() {
+  if (auto mouse = dynamic_cast<PlatformMouseController*>(mouse_controller_))
+    mouse->ReleasePressedButtons();
+}
+#endif

-    if (init_ret != 0) {
-      speaker_capturer_->Destroy();
-      delete speaker_capturer_;
-      speaker_capturer_ = nullptr;
-    }
-  }
-
-  if (!speaker_capturer_) {
-    return -1;
-  }
-
-  const int ret = speaker_capturer_->Start();
-  if (ret != 0) {
-    LOG_ERROR("Start speaker capturer failed: {}", ret);
-    return ret;
-  }
-  owner_.start_speaker_capturer_ = true;
-  return 0;
+void SessionDeviceManager::StartSpeakerCapturer() {
+  speaker_capture_.SetEnabled(true);
 }

-int SessionDeviceManager::StopSpeakerCapturer() {
-  if (speaker_capturer_) {
-    speaker_capturer_->Stop();
-    owner_.start_speaker_capturer_ = false;
+void SessionDeviceManager::StopSpeakerCapturer() {
+  speaker_capture_.SetEnabled(false);
+}
+
+bool SessionDeviceManager::SyncDisplayInfo() {
+  if (!screen_capturer_) return false;
+  auto displays = screen_capturer_->GetDisplayInfoList();
+  if (displays.empty()) return false;
+  // Called every UI tick; replace the shared list only when geometry actually
+  // changed so readers on other threads rarely contend for the lock.
+  bool changed = false;
+  {
+    std::lock_guard<std::mutex> lock(display_info_mutex_);
+    changed = !std::equal(
+        displays.begin(), displays.end(), display_info_list_.begin(),
+        display_info_list_.end(), [](const auto &a, const auto &b) {
+          return a.handle == b.handle && a.name == b.name &&
+                 a.is_primary == b.is_primary && a.left == b.left &&
+                 a.top == b.top && a.width == b.width && a.height == b.height;
+        });
+    if (changed) display_info_list_ = displays;
  }
-  return 0;
+  if (changed && mouse_controller_) mouse_controller_->UpdateDisplayInfoList(displays);
+  return true;
+}
+
+void SessionDeviceManager::SetDisplayInfoList(std::vector<DisplayInfo> displays) {
+  std::lock_guard<std::mutex> lock(display_info_mutex_);
+  display_info_list_ = std::move(displays);
 }

 int SessionDeviceManager::StartMouseController() {
@@ -258,14 +387,9 @@ int SessionDeviceManager::StartMouseController() {
    }
  }

-  if (screen_capturer_) {
-    const auto latest_display_info = screen_capturer_->GetDisplayInfoList();
-    if (!latest_display_info.empty()) {
-      display_info_list_ = latest_display_info;
-    }
-  }
 #endif

+  SyncDisplayInfo();
  mouse_controller_ =
      static_cast<MouseController *>(device_controller_factory_->Create(
          DeviceControllerFactory::Device::Mouse));
@@ -274,7 +398,7 @@ int SessionDeviceManager::StartMouseController() {
    return -1;
  }

-  const int init_ret = mouse_controller_->Init(display_info_list_);
+  const int init_ret = mouse_controller_->Init(display_info_list());
  if (init_ret != 0) {
    LOG_INFO("Destroy mouse controller");
    mouse_controller_->Destroy();
@@ -294,6 +418,7 @@ int SessionDeviceManager::StopMouseController() {
 }

 int SessionDeviceManager::StartKeyboardCapturer() {
+  ClearCapturedKeyboardInput();
  owner_.keyboard_capturer_uses_window_events_ = false;

 #ifdef __APPLE__
@@ -329,6 +454,7 @@ int SessionDeviceManager::StartKeyboardCapturer() {
      },
      this);
  if (hook_ret != 0) {
+    keyboard_capturer_->Unhook();
    owner_.keyboard_capturer_uses_window_events_ = true;
    LOG_WARN(
        "Start keyboard capturer failed, falling back to Slint keyboard events");
@@ -339,6 +465,9 @@ int SessionDeviceManager::StartKeyboardCapturer() {
 }

 int SessionDeviceManager::StopKeyboardCapturer() {
+  owner_.keyboard_capturer_is_started_ = false;
+  if (keyboard_capturer_) keyboard_capturer_->Unhook();
+  ClearCapturedKeyboardInput();
  if (owner_.keyboard_capturer_uses_window_events_) {
    owner_.keyboard_capturer_uses_window_events_ = false;
    LOG_INFO("Stop keyboard capturer with Slint keyboard backend");
@@ -346,8 +475,6 @@ int SessionDeviceManager::StopKeyboardCapturer() {
  }

  if (keyboard_capturer_) {
-    keyboard_capturer_->Unhook();
-    ClearCapturedKeyboardInput();
    LOG_INFO("Stop keyboard capturer");
  }
  return 0;
@@ -417,6 +544,15 @@ void SessionDeviceManager::PushAudio(const char *data, size_t size) {
 }

 void SessionDeviceManager::UpdateInteractions() {
+#ifdef _WIN32
+  if (owner_.screen_capturer_is_started_ &&
+      cursor_capture_dirty_.load(std::memory_order_relaxed)) {
+    if (auto* windows = dynamic_cast<ScreenCapturerWin*>(screen_capturer_)) {
+      cursor_capture_dirty_.store(false, std::memory_order_relaxed);
+      windows->SetCursorCapture(ShouldCaptureCursor());
+    }
+  }
+#endif
 #if defined(__linux__) && !defined(__APPLE__)
  const bool is_wayland_session = IsWaylandSession();
  const bool stop_wayland_mouse_before_screen =
@@ -441,16 +577,6 @@ void SessionDeviceManager::UpdateInteractions() {
    owner_.screen_capturer_is_started_ = false;
  }

-  if (owner_.start_speaker_capturer_ && !owner_.speaker_capturer_is_started_) {
-    if (StartSpeakerCapturer() == 0) {
-      owner_.speaker_capturer_is_started_ = true;
-    }
-  } else if (!owner_.start_speaker_capturer_ &&
-             owner_.speaker_capturer_is_started_) {
-    StopSpeakerCapturer();
-    owner_.speaker_capturer_is_started_ = false;
-  }
-
  if (owner_.start_mouse_controller_ && !owner_.mouse_controller_is_started_) {
    if (StartMouseController() == 0) {
      owner_.mouse_controller_is_started_ = true;
@@ -461,22 +587,33 @@ void SessionDeviceManager::UpdateInteractions() {
    owner_.mouse_controller_is_started_ = false;
  }

-#if defined(__linux__) && !defined(__APPLE__)
-  if (owner_.screen_capturer_is_started_ && screen_capturer_ &&
-      mouse_controller_) {
-    const auto latest_display_info = screen_capturer_->GetDisplayInfoList();
-    if (!latest_display_info.empty()) {
-      display_info_list_ = latest_display_info;
-      mouse_controller_->UpdateDisplayInfoList(display_info_list_);
+  if (owner_.screen_capturer_is_started_ && mouse_controller_ && SyncDisplayInfo()) {
+#ifdef _WIN32
+    const int active_display = screen_capturer_->GetCurrentMonitorIndex();
+    const auto displays = display_info_list();
+    if (active_display >= 0 &&
+        active_display < static_cast<int>(displays.size())) {
+      owner_.selected_display_ = active_display;
+      if (displays[active_display].width <= 0 ||
+          displays[active_display].height <= 0)
+        ReleaseRemoteMouseButtons();
    }
-  }
 #endif
+  }

  if (owner_.start_keyboard_capturer_ && owner_.focus_on_stream_window_) {
    if (!owner_.keyboard_capturer_is_started_ && StartKeyboardCapturer() == 0) {
      owner_.keyboard_capturer_is_started_ = true;
    }
    if (owner_.keyboard_capturer_is_started_) {
+      if (!owner_.keyboard_capturer_uses_window_events_ &&
+          (!keyboard_capturer_ || !keyboard_capturer_->IsHookActive())) {
+        StopKeyboardCapturer();
+        owner_.keyboard_.ForceReleasePressedKeys();
+        owner_.keyboard_capturer_uses_window_events_ = true;
+        owner_.keyboard_capturer_is_started_ = true;
+        LOG_WARN("Native keyboard capture stopped; using Slint keyboard events");
+      }
      DrainCapturedKeyboardInput();
      owner_.keyboard_.SendHeartbeat(false);
    }
@@ -508,6 +645,7 @@ void SessionDeviceManager::DrainCapturedKeyboardInput() {
    std::lock_guard<std::mutex> lock(captured_keyboard_inputs_mutex_);
    inputs.swap(captured_keyboard_inputs_);
  }
+  if (owner_.privacy_.Snapshot().input_blocked) return;
  for (const CapturedKeyboardInput &input : inputs) {
    owner_.keyboard_.SendKeyCommand(input.key_code, input.is_down,
                                    input.scan_code, input.extended);
@@ -534,21 +672,45 @@ void SessionDeviceManager::SendMouseCommand(const RemoteAction &action,
 }

 int SessionDeviceManager::SwitchDisplay(int display_id) {
-  return screen_capturer_ ? screen_capturer_->SwitchTo(display_id) : -1;
+  if (!screen_capturer_) return -1;
+  const int ret = screen_capturer_->SwitchTo(display_id);
+  if (ret == 0) SyncDisplayInfo();
+  return ret;
 }

 void SessionDeviceManager::ResetToInitialDisplay() {
-  if (screen_capturer_) {
-    screen_capturer_->ResetToInitialMonitor();
+  if (!screen_capturer_) {
+    return;
  }
+  const int ret = screen_capturer_->ResetToInitialMonitor();
+  if (ret != 0) {
+    LOG_WARN("Reset to initial display failed, ret={}", ret);
+    return;
+  }
+  // Capture backends start at display 0. Reset the input mapping as well so
+  // the next connection cannot show that display while controlling another.
+  owner_.selected_display_ = 0;
+  SyncDisplayInfo();
 }

-const std::vector<DisplayInfo> &
-SessionDeviceManager::display_info_list() const {
+std::vector<DisplayInfo> SessionDeviceManager::display_info_list() const {
+  std::lock_guard<std::mutex> lock(display_info_mutex_);
  return display_info_list_;
 }

+std::vector<HostDisplay> SessionDeviceManager::host_display_list() const {
+  std::lock_guard<std::mutex> lock(display_info_mutex_);
+  std::vector<HostDisplay> displays;
+  displays.reserve(display_info_list_.size());
+  for (const auto &display : display_info_list_) {
+    displays.push_back({display.name, display.left, display.top, display.right,
+                        display.bottom});
+  }
+  return displays;
+}
+
 void SessionDeviceManager::DestroyDevices() {
+  speaker_capture_.Shutdown();
  if (mouse_controller_) {
    mouse_controller_->Destroy();
    delete mouse_controller_;
@@ -559,11 +721,6 @@ void SessionDeviceManager::DestroyDevices() {
    delete screen_capturer_;
    screen_capturer_ = nullptr;
  }
-  if (speaker_capturer_) {
-    speaker_capturer_->Destroy();
-    delete speaker_capturer_;
-    speaker_capturer_ = nullptr;
-  }
  if (keyboard_capturer_) {
    delete keyboard_capturer_;
    keyboard_capturer_ = nullptr;
@@ -573,8 +730,6 @@ void SessionDeviceManager::DestroyDevices() {
 void SessionDeviceManager::DestroyFactories() {
  delete screen_capturer_factory_;
  screen_capturer_factory_ = nullptr;
-  delete speaker_capturer_factory_;
-  speaker_capturer_factory_ = nullptr;
  delete device_controller_factory_;
  device_controller_factory_ = nullptr;
 }
@@ -1,8 +1,14 @@
-#ifndef CROSSDESK_GUI_SESSION_DEVICE_MANAGER_H_
-#define CROSSDESK_GUI_SESSION_DEVICE_MANAGER_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-09
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */

-#include <SDL3/SDL.h>
+#ifndef _SESSION_DEVICE_MANAGER_H_
+#define _SESSION_DEVICE_MANAGER_H_

+
+#include <atomic>
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
@@ -11,15 +17,20 @@
 #include <string>
 #include <vector>

+#include <remote_action.h>
+
 #include "device_controller.h"
-#include "device_controller_factory.h"
 #include "display_info.h"
-#include "screen_capturer_factory.h"
-#include "speaker_capturer_factory.h"
+#include "speaker_capture_controller.h"
+
+struct SDL_AudioStream;

 namespace crossdesk {

 class GuiRuntime;
+class DeviceControllerFactory;
+class ScreenCapturerFactory;
+class ScreenCapturer;

 // Owns media capture/playback and remote input devices for the active GUI
 // session. GuiRuntime supplies application intent; this class handles device
@@ -27,17 +38,28 @@ class GuiRuntime;
 class SessionDeviceManager {
 public:
  explicit SessionDeviceManager(GuiRuntime &owner);
+  ~SessionDeviceManager();

  void Initialize();
  void UpdateInteractions();
+  // Call after changing the controller map. UpdateInteractions consumes this
+  // notification on the UI thread before reading the map under its mutex.
+  void OnControllerConnectionsChanged() {
+    cursor_capture_dirty_.store(true, std::memory_order_relaxed);
+  }
  void DestroyDevices();
  void DestroyFactories();

  int InitializeScreenCapturer();
  int StartScreenCapturer();
  int StopScreenCapturer();
-  int StartSpeakerCapturer();
-  int StopSpeakerCapturer();
+#ifdef _WIN32
+  void ReleaseRemoteMouseButtons();
+#endif
+  // Requests are asynchronous; Stop drains/revokes audio delivery before
+  // returning so the connection peer can be destroyed safely.
+  void StartSpeakerCapturer();
+  void StopSpeakerCapturer();
  int StartMouseController();
  int StopMouseController();
  int StartKeyboardCapturer();
@@ -53,7 +75,12 @@ public:
  int SwitchDisplay(int display_id);
  void ResetToInitialDisplay();

-  const std::vector<DisplayInfo> &display_info_list() const;
+  // Snapshot of the capture displays. The UI thread refreshes the list every
+  // tick while transport threads build host information and map mouse input
+  // from it, so callers get a copy taken under the lock.
+  std::vector<DisplayInfo> display_info_list() const;
+  // The same snapshot in the wire's host information form.
+  std::vector<HostDisplay> host_display_list() const;

 private:
  struct CapturedKeyboardInput {
@@ -69,26 +96,41 @@ private:
  void ClearCapturedKeyboardInput();
  bool ShouldSendCapturedFrame(std::chrono::steady_clock::time_point now,
                               int fps);
+  bool ShouldCaptureCursor() const;
+  bool SyncDisplayInfo();
+  void SetDisplayInfoList(std::vector<DisplayInfo> displays);
+  void RecordCaptureCadence(std::chrono::steady_clock::time_point now, int fps,
+                            bool from_secure_desktop);

  GuiRuntime &owner_;
  SDL_AudioStream *output_stream_ = nullptr;
  ScreenCapturerFactory *screen_capturer_factory_ = nullptr;
  ScreenCapturer *screen_capturer_ = nullptr;
-  SpeakerCapturerFactory *speaker_capturer_factory_ = nullptr;
-  SpeakerCapturer *speaker_capturer_ = nullptr;
+  std::atomic<bool> cursor_capture_dirty_{true};
+  SpeakerCaptureController speaker_capture_;
  DeviceControllerFactory *device_controller_factory_ = nullptr;
  MouseController *mouse_controller_ = nullptr;
  KeyboardCapturer *keyboard_capturer_ = nullptr;
+  // Guards display_info_list_ (UI thread writes, transport threads read).
+  mutable std::mutex display_info_mutex_;
  std::vector<DisplayInfo> display_info_list_;
  size_t registered_display_stream_count_ = 0;
  std::deque<CapturedKeyboardInput> captured_keyboard_inputs_;
  std::mutex captured_keyboard_inputs_mutex_;
  std::chrono::steady_clock::time_point last_frame_time_{};
  std::chrono::steady_clock::time_point next_frame_deadline_{};
+  std::mutex capture_metrics_mutex_;
+  std::chrono::steady_clock::time_point capture_metrics_started_{};
+  std::chrono::steady_clock::time_point last_capture_callback_{};
+  uint64_t capture_callbacks_ = 0, capture_rate_drops_ = 0;
+  uint64_t capture_secure_callbacks_ = 0;
+  uint64_t capture_forwarded_ = 0, capture_send_errors_ = 0;
+  int64_t capture_max_gap_us_ = 0;
+  int64_t capture_send_us_ = 0, capture_max_send_us_ = 0;
  std::string last_video_frame_stream_id_;
  bool invalid_video_stream_id_logged_ = false;
 };

 } // namespace crossdesk

-#endif // CROSSDESK_GUI_SESSION_DEVICE_MANAGER_H_
+#endif
@@ -2,7 +2,6 @@

 #include <algorithm>
 #include <chrono>
-#include <cstring>
 #include <filesystem>
 #include <limits>
 #include <memory>
@@ -21,6 +20,16 @@ namespace crossdesk {

 FileTransferManager::FileTransferManager(GuiRuntime &owner) : owner_(owner) {}

+FileTransferManager::~FileTransferManager() {
+  std::vector<std::future<void>> workers;
+  {
+    std::lock_guard lock(workers_mutex_);
+    stopping_ = true;
+    workers.swap(workers_);
+  }
+  for (auto& worker : workers) worker.wait();
+}
+
 FileTransferManager::FileTransferState &FileTransferManager::global_state() {
  return global_state_;
 }
@@ -93,8 +102,16 @@ void FileTransferManager::Start(
    std::shared_ptr<RemoteSession> props,
    const std::filesystem::path &file_path, const std::string &file_label,
    const std::string &remote_id) {
+  if (props && props->closing_) return;
  const bool is_global = !props;
-  PeerPtr *peer = is_global ? owner_.peer_ : props->peer_;
+  PeerPtr* peer = nullptr;
+  std::shared_ptr<PeerEventHandler> peer_events;
+  {
+    std::shared_lock lock(owner_.remote_sessions_mutex_);
+    if (props && props->closing_) return;
+    peer = is_global ? owner_.peer_ : props->peer_;
+    peer_events = is_global ? owner_.peer_events_ : props->peer_events_;
+  }
  if (!peer) {
    LOG_ERROR("StartFileTransfer: invalid peer");
    return;
@@ -109,7 +126,14 @@ void FileTransferManager::Start(
  }

  const auto props_weak = std::weak_ptr<RemoteSession>(props);
-  std::thread([this, peer, file_path, file_label, props_weak, remote_id,
+  std::lock_guard workers_lock(workers_mutex_);
+  if (stopping_) return;
+  // Reap finished senders without blocking the UI.
+  std::erase_if(workers_, [](auto& worker) {
+    return worker.wait_for(std::chrono::seconds(0)) == std::future_status::ready;
+  });
+  workers_.push_back(std::async(std::launch::async,
+      [this, peer, peer_events, file_path, file_label, props_weak, remote_id,
               is_global]() {
    auto props_locked = props_weak.lock();
    FileTransferState *state = nullptr;
@@ -167,7 +191,11 @@ void FileTransferManager::Start(

    const int ret = sender.SendFile(
        file_path, file_path.filename().string(),
-        [peer, file_label, remote_id](const char *buffer, size_t size) {
+        [peer, peer_events, file_label, remote_id, props_locked](const char *buffer, size_t size) {
+          // Close drains each in-flight send before detaching the peer.
+          if (props_locked && props_locked->closing_) return -1;
+          auto callback = peer_events->EnterCallback();
+          if (!callback) return -1;
          if (remote_id.empty()) {
            return SendReliableDataFrame(peer, buffer, size,
                                         file_label.c_str());
@@ -201,12 +229,13 @@ void FileTransferManager::Start(
    }
    LOG_ERROR("FileSender::SendFile failed for [{}], ret={}",
              file_path.string().c_str(), ret);
-    ProcessQueue(props_locked);
-  }).detach();
+    if (peer_events->IsActive()) ProcessQueue(props_locked);
+  }));
 }

 void FileTransferManager::ProcessQueue(
    std::shared_ptr<RemoteSession> props) {
+  if (props && props->closing_) return;
  FileTransferState &state = state_for(props);
  if (state.file_sending_.load()) {
    return;
@@ -236,15 +265,9 @@ void FileTransferManager::Unregister(uint32_t file_id, bool per_peer) {
 }

 void FileTransferManager::HandleAck(const char *data, size_t size) {
-  if (size < sizeof(FileTransferAck)) {
-    LOG_ERROR("FileTransferAck: buffer too small, size={}", size);
-    return;
-  }
-
  FileTransferAck ack{};
-  std::memcpy(&ack, data, sizeof(ack));
-  if (ack.magic != kFileAckMagic) {
-    LOG_ERROR("FileTransferAck: invalid magic, got 0x{:08X}", ack.magic);
+  if (!DecodeFileTransferAck(data, size, &ack)) {
+    LOG_ERROR("FileTransferAck: invalid payload, size={}", size);
    return;
  }

@@ -275,7 +298,7 @@ void FileTransferManager::HandleAck(const char *data, size_t size) {
  uint32_t rate_bps = 0;
  if (props) {
    const uint32_t bitrate =
-        props->net_traffic_stats_.data_outbound_stats.bitrate;
+        props->net_traffic_stats_.DataOutboundBitrate();
    if (bitrate > 0 && state->file_sending_.load()) {
      rate_bps = static_cast<uint32_t>(bitrate * 0.99f);
      const uint32_t current_rate = state->file_send_rate_bps_.load();
@@ -4,12 +4,15 @@
 #include <cstddef>
 #include <cstdint>
 #include <filesystem>
+#include <future>
+#include <mutex>
+#include <vector>
 #include <memory>
 #include <shared_mutex>
 #include <string>
 #include <unordered_map>

-#include "runtime/gui_state.h"
+#include "runtime/remote_session.h"

 namespace crossdesk {

@@ -21,6 +24,7 @@ public:
  using RemoteSession = gui_detail::RemoteSession;

  explicit FileTransferManager(GuiRuntime &owner);
+  ~FileTransferManager();

  FileTransferState &global_state();
  FileTransferState &
@@ -40,6 +44,9 @@ private:
  void ProcessQueue(std::shared_ptr<RemoteSession> props);
  void Unregister(uint32_t file_id, bool per_peer);

+  std::mutex workers_mutex_;
+  std::vector<std::future<void>> workers_;
+  bool stopping_ = false;
  GuiRuntime &owner_;
  FileTransferState global_state_;
  std::unordered_map<uint32_t, std::weak_ptr<RemoteSession>>
@@ -1,5 +1,7 @@
 #include "features/input/keyboard_controller.h"

+#include <remote_action.h>
+
 #include <SDL3/SDL.h>

 #include <cstdint>
@@ -50,6 +52,9 @@ void PopulateWindowsKeyMetadataFromVk(int key_code, uint32_t* scan_code_out,
  if (!scan_code_out || !extended_out) {
    return;
  }
+  if (LookupWindowsKeyMetadataFromVk(key_code, scan_code_out, extended_out)) {
+    return;
+  }
 #if _WIN32
  const UINT scan_code =
      MapVirtualKeyW(static_cast<UINT>(key_code), MAPVK_VK_TO_VSC_EX);
@@ -59,7 +64,6 @@ void PopulateWindowsKeyMetadataFromVk(int key_code, uint32_t* scan_code_out,
    return;
  }
 #endif
-  LookupWindowsKeyMetadataFromVk(key_code, scan_code_out, extended_out);
 }

 #if _WIN32
@@ -148,6 +152,7 @@ void KeyboardController::SendHeartbeat(bool force) {
  const std::string target_id = owner_.controlled_remote_id_.empty()
                                    ? owner_.focused_remote_id_
                                    : owner_.controlled_remote_id_;
+  std::shared_lock sessions_lock(owner_.remote_sessions_mutex_);
  const auto props_it = owner_.remote_sessions_.find(target_id);
  if (target_id.empty() || props_it == owner_.remote_sessions_.end() ||
      props_it->second->connection_status_.load() !=
@@ -187,6 +192,7 @@ int KeyboardController::SendKeyCommand(int key_code, bool is_down,
  const std::string target_id = owner_.controlled_remote_id_.empty()
                                    ? owner_.focused_remote_id_
                                    : owner_.controlled_remote_id_;
+  std::shared_lock sessions_lock(owner_.remote_sessions_mutex_);
  const auto props_it = owner_.remote_sessions_.find(target_id);
  if (!target_id.empty() && props_it != owner_.remote_sessions_.end() &&
      props_it->second->connection_status_.load() ==
@@ -209,6 +215,9 @@ int KeyboardController::SendKeyCommand(int key_code, bool is_down,
 bool KeyboardController::InjectRemoteKey(int key_code, bool is_down,
                                         uint32_t scan_code, bool extended) {
 #if _WIN32
+  if (owner_.privacy_.Engaged() && !IsWindowsPrivacyDesktopAvailable()) {
+    owner_.privacy_.Fail("Secure desktop or locked session; privacy screen will turn off");
+  }
  if (owner_.local_service_status_received_ &&
      IsSecureDesktopInteractionRequired(owner_.local_interactive_stage_)) {
    const std::string response = SendCrossDeskSecureDesktopKeyInput(
@@ -242,6 +251,7 @@ bool KeyboardController::InjectRemoteKey(int key_code, bool is_down,
    return true;
  }
 #endif
+  // Recheck after the desktop query; key-up cleanup remains allowed while paused.
  return owner_.devices_.SendKeyboardCommand(key_code, is_down, scan_code,
                                             extended);
 }
@@ -338,11 +348,50 @@ void KeyboardController::ReleaseRemotePressedKeys(const std::string& remote_id,
             keys_to_release.size(), remote_id, reason ? reason : "unknown");
  }
  for (const PressedKey& key : keys_to_release) {
-    InjectRemoteKey(key.key_code, false, key.scan_code, key.extended);
+    if (!InjectRemoteKey(key.key_code, false, key.scan_code, key.extended)) {
+#ifdef _WIN32
+      if (owner_.privacy_.Engaged()) {
+        std::lock_guard lock(remote_states_mutex_);
+        pending_privacy_releases_[key.key_code] = key;
+      }
+#endif
+    }
  }
 }

+void KeyboardController::ReleaseAllRemotePressedKeys(const char* reason) {
+  std::vector<std::string> remotes;
+  {
+    std::lock_guard lock(remote_states_mutex_);
+    for (const auto& [id, state] : remote_states_) remotes.push_back(id);
+  }
+  for (const auto& id : remotes) ReleaseRemotePressedKeys(id, reason);
+  CheckRemoteTimeouts();
+}
+
 void KeyboardController::CheckRemoteTimeouts() {
+#ifdef _WIN32
+  bool pending = false;
+  {
+    std::lock_guard lock(remote_states_mutex_);
+    pending = !pending_privacy_releases_.empty();
+  }
+  // A key-up rejected on the secure desktop is retained until the ordinary
+  // desktop returns. Never route cleanup through the security UI helper.
+  if (pending && IsWindowsPrivacyDesktopAvailable()) {
+    std::unordered_map<int, PressedKey> releases;
+    {
+      std::lock_guard lock(remote_states_mutex_);
+      releases.swap(pending_privacy_releases_);
+    }
+    for (const auto& [code, key] : releases) {
+      if (!owner_.devices_.SendKeyboardCommand(code, false, key.scan_code, key.extended)) {
+        std::lock_guard lock(remote_states_mutex_);
+        pending_privacy_releases_[code] = key;
+      }
+    }
+  }
+#endif
  const uint32_t now = static_cast<uint32_t>(SDL_GetTicks());
  std::vector<std::string> timed_out_remotes;
  {
@@ -6,6 +6,8 @@
 #include <string>
 #include <unordered_map>

+#include <remote_action.h>
+
 #include "device_controller.h"

 namespace crossdesk {
@@ -28,6 +30,7 @@ public:
                        const RemoteAction &remote_action);
  void ReleaseRemotePressedKeys(const std::string &remote_id,
                                const char *reason);
+  void ReleaseAllRemotePressedKeys(const char* reason);
  void CheckRemoteTimeouts();

 private:
@@ -56,6 +59,9 @@ private:
  uint32_t last_heartbeat_tick_ = 0;
  std::unordered_map<std::string, RemoteState> remote_states_;
  std::mutex remote_states_mutex_;
+#ifdef _WIN32
+  std::unordered_map<int, PressedKey> pending_privacy_releases_;
+#endif
 };

 } // namespace crossdesk
@@ -9,6 +9,7 @@
 #include <fstream>
 #include <functional>
 #include <memory>
+#include <nlohmann/json.hpp>
 #include <string>
 #include <thread>

@@ -297,16 +298,11 @@ int SettingsManager::Load() {

  owner_.language_button_value_ = localization::detail::ClampLanguageIndex(
      static_cast<int>(owner_.config_center_->GetLanguage()));
-  owner_.video_quality_button_value_ =
-      static_cast<int>(owner_.config_center_->GetVideoQuality());
-  owner_.video_frame_rate_button_value_ =
-      static_cast<int>(owner_.config_center_->GetVideoFrameRate());
  owner_.video_encode_format_button_value_ =
      static_cast<int>(owner_.config_center_->GetVideoEncodeFormat());
  owner_.enable_hardware_video_codec_ =
      owner_.config_center_->IsHardwareVideoCodec();
  owner_.enable_turn_ = owner_.config_center_->IsEnableTurn();
-  owner_.enable_srtp_ = owner_.config_center_->IsEnableSrtp();
  owner_.enable_self_hosted_ = owner_.config_center_->IsSelfHosted();
  owner_.enable_autostart_ = owner_.config_center_->IsEnableAutostart();
  owner_.enable_daemon_ = owner_.config_center_->IsEnableDaemon();
@@ -323,13 +319,11 @@ int SettingsManager::Load() {
  owner_.file_transfer_save_path_last_ = saved_path;

  owner_.language_button_value_last_ = owner_.language_button_value_;
-  owner_.video_quality_button_value_last_ = owner_.video_quality_button_value_;
  owner_.video_encode_format_button_value_last_ =
      owner_.video_encode_format_button_value_;
  owner_.enable_hardware_video_codec_last_ =
      owner_.enable_hardware_video_codec_;
  owner_.enable_turn_last_ = owner_.enable_turn_;
-  owner_.enable_srtp_last_ = owner_.enable_srtp_;
  owner_.enable_self_hosted_last_ = owner_.enable_self_hosted_;
  owner_.enable_autostart_last_ = owner_.enable_autostart_;

@@ -592,22 +586,6 @@ std::string SettingsManager::RecentConnectionDisplayName(
  return connection.remote_id;
 }

-void SettingsManager::BeginEditRecentConnectionAlias(
-    const Thumbnail::RecentConnection &connection) {
-  owner_.edit_connection_alias_remote_id_ = connection.remote_id;
-  std::memset(owner_.edit_connection_alias_, 0,
-              sizeof(owner_.edit_connection_alias_));
-
-  const auto alias_it = recent_connection_aliases_.find(connection.remote_id);
-  const std::string alias = alias_it != recent_connection_aliases_.end()
-                                ? alias_it->second
-                                : RecentConnectionDisplayName(connection);
-  CopyString(owner_.edit_connection_alias_, alias.c_str());
-
-  owner_.focus_on_input_widget_ = true;
-  owner_.show_edit_connection_alias_window_ = true;
-}
-
 void SettingsManager::SetRecentConnectionAlias(const std::string &remote_id,
                                               const std::string &alias) {
  if (!remote_id.empty()) {
@@ -25,8 +25,6 @@ public:
  int SaveRecentConnectionAliases() const;
  std::string RecentConnectionDisplayName(
      const Thumbnail::RecentConnection &connection) const;
-  void
-  BeginEditRecentConnectionAlias(const Thumbnail::RecentConnection &connection);
  void SetRecentConnectionAlias(const std::string &remote_id,
                                const std::string &alias);
  void EraseRecentConnectionAlias(const std::string &remote_id);
@@ -60,8 +58,9 @@ private:
  struct CacheV1 {
    char client_id_with_password[17];
    int language;
-    int video_quality;
-    int video_frame_rate;
+    // Reserved legacy slots: retain the on-disk cache layout.
+    int legacy_video_quality;
+    int legacy_video_frame_rate;
    int video_encode_format;
    bool enable_hardware_video_codec;
    bool enable_turn;
@@ -73,8 +72,9 @@ private:
  struct CacheV2 {
    char client_id_with_password[17];
    int language;
-    int video_quality;
-    int video_frame_rate;
+    // Reserved legacy slots: retain the on-disk cache layout.
+    int legacy_video_quality;
+    int legacy_video_frame_rate;
    int video_encode_format;
    bool enable_hardware_video_codec;
    bool enable_turn;
@@ -1,5 +1,11 @@
-#ifndef CROSSDESK_GUI_RENDER_H_
-#define CROSSDESK_GUI_RENDER_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _RENDER_H_
+#define _RENDER_H_

 #include <memory>

@@ -7,7 +13,7 @@ namespace crossdesk {

 class GuiApplication;

-// Stable application-facing facade. The SDL application and feature
+// Stable application-facing facade. The Slint application and feature
 // controllers remain private implementation details.
 class Render {
 public:
@@ -25,4 +31,4 @@ private:

 } // namespace crossdesk

-#endif // CROSSDESK_GUI_RENDER_H_
+#endif
@@ -1,4 +1,5 @@
 #include "rendering/slint_video_presenter.h"
+#include "crossdesk_ui.h"

 #include <libyuv.h>
 #include <slint.h>
@@ -14,14 +15,14 @@
 #include "rd_log.h"

 #if defined(__APPLE__)
-#include "platform/metal_video_renderer.h"
+#include "platform/macos/gui/metal_video_renderer.h"
 #else
 #if defined(_WIN32)
 #include <windows.h>
 #endif
 #include <GL/gl.h>

-#include "platform/opengl_video_renderer.h"
+#include "platform/common/gui/opengl_video_renderer.h"
 #endif

 namespace crossdesk {
@@ -86,6 +87,7 @@ struct SlintVideoPresenter::Impl {
  VideoRenderSize gl_image_size;
  VideoRenderSize gl_pending_size;
  bool gl_pending_dirty = false;
+  VideoLatencyFrame gl_pending_timing;
 #endif

  SurfaceState CurrentState() const {
@@ -154,10 +156,8 @@ struct SlintVideoPresenter::Impl {
            const auto window_size = (*stream)->window().size();
            const float scale_factor =
                std::max(1.0f, (*stream)->window().scale_factor());
-            const int top_inset =
-                !surface.fullscreen && surface.tab_count > 1
-                    ? static_cast<int>(std::lround(30.0f * scale_factor))
-                    : 0;
+            const int top_inset = static_cast<int>(std::lround(
+                (*stream)->get_video_area_top() * scale_factor));
            const bool rounded_window = (*stream)->get_custom_titlebar() &&
                                        !surface.fullscreen &&
                                        !(*stream)->window().is_maximized();
@@ -193,6 +193,7 @@ struct SlintVideoPresenter::Impl {
            glPixelStorei(GL_UNPACK_ALIGNMENT, previous_unpack_alignment);
            glBindTexture(GL_TEXTURE_2D, static_cast<GLuint>(previous_texture));
            gl_pending_dirty = false;
+            gl_pending_timing.MarkSubmitted();
            return;
          }

@@ -323,7 +324,7 @@ SlintVideoPresenter::PresentResult SlintVideoPresenter::Present(
      impl_->seeded_frame_sequence[frame.remote_id] != frame.sequence) {
    const auto submit_result = impl_->renderer.SubmitCachedNv12(
        frame.remote_id, frame.nv12->data(), frame.nv12->size(), frame.width,
-        frame.height);
+        frame.height, frame.timing);
    if (submit_result == VideoRenderer::SubmitResult::submitted ||
        submit_result == VideoRenderer::SubmitResult::dropped) {
      impl_->seeded_frame_sequence[frame.remote_id] = frame.sequence;
@@ -335,8 +336,7 @@ SlintVideoPresenter::PresentResult SlintVideoPresenter::Present(
      dynamic_cast<MacMetalVideoRenderer*>(&impl_->renderer);
  if (metal_renderer && metal_renderer->IsActive()) {
    const SurfaceState surface = impl_->CurrentState();
-    const double top_inset =
-        !surface.fullscreen && surface.tab_count > 1 ? 30.0 : 0.0;
+    const double top_inset = (*impl_->stream)->get_video_area_top();
    const auto outcome = metal_renderer->RenderLatest(
        frame.remote_id, top_inset, !surface.fullscreen);
    if (outcome.result == VideoRenderer::RenderResult::rendered) {
@@ -442,6 +442,7 @@ SlintVideoPresenter::PresentResult SlintVideoPresenter::Present(
      impl_->gl_pending_frame.swap(impl_->gl_conversion_frame);
      impl_->gl_pending_size = {output_width, output_height};
      impl_->gl_pending_dirty = true;
+      impl_->gl_pending_timing = frame.timing;
    }
    const VideoRenderSize output_size{output_width, output_height};
    if (impl_->gl_image_size != output_size) {
@@ -471,6 +472,7 @@ SlintVideoPresenter::PresentResult SlintVideoPresenter::Present(
  }

  (*impl_->stream)->set_frame(slint::Image(std::move(pixels)));
+  frame.timing.MarkSubmitted();
  (*impl_->stream)->set_has_frame(true);
  (*impl_->stream)->set_receiving_text("");
  result.width = frame.width;
@@ -1,5 +1,11 @@
-#ifndef CROSSDESK_GUI_RENDERING_SLINT_VIDEO_PRESENTER_H_
-#define CROSSDESK_GUI_RENDERING_SLINT_VIDEO_PRESENTER_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SLINT_VIDEO_PRESENTER_H_
+#define _SLINT_VIDEO_PRESENTER_H_

 #include <cstddef>
 #include <cstdint>
@@ -8,7 +14,15 @@
 #include <string>
 #include <vector>

-#include "crossdesk_ui.h"
+#include "rendering/video_latency.h"
+
+namespace slint {
+template <typename T> class ComponentHandle;
+}
+
+namespace crossdesk::ui {
+class StreamWindow;
+}

 namespace crossdesk {

@@ -22,7 +36,6 @@ public:
  struct SurfaceState {
    std::string selected_stream;
    bool fullscreen = false;
-    size_t tab_count = 0;
  };

  struct Frame {
@@ -31,6 +44,7 @@ public:
    int width = 0;
    int height = 0;
    uint64_t sequence = 0;
+    VideoLatencyFrame timing;
  };

  struct PresentResult {
@@ -72,4 +86,4 @@ private:

 }  // namespace crossdesk

-#endif  // CROSSDESK_GUI_RENDERING_SLINT_VIDEO_PRESENTER_H_
+#endif
@@ -0,0 +1,51 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-22
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _VIDEO_GEOMETRY_H_
+#define _VIDEO_GEOMETRY_H_
+
+#include <algorithm>
+#include <cmath>
+#include <optional>
+
+namespace crossdesk {
+
+struct VideoPoint {
+  float x;
+  float y;
+};
+
+// Area dimensions and pointer positions must use the same coordinate space.
+// Slint supplies both in logical pixels; remote input is resolution
+// independent.
+inline std::optional<VideoPoint> MapVideoPoint(float x, float y,
+                                               float area_width,
+                                               float area_height,
+                                               int video_width,
+                                               int video_height) {
+  if (!std::isfinite(x) || !std::isfinite(y) || !std::isfinite(area_width) ||
+      !std::isfinite(area_height) || area_width <= 0 || area_height <= 0 ||
+      video_width <= 0 || video_height <= 0) {
+    return std::nullopt;
+  }
+
+  const double scale =
+      std::min(static_cast<double>(area_width) / video_width,
+               static_cast<double>(area_height) / video_height);
+  const double width = video_width * scale;
+  const double height = video_height * scale;
+  const double left = (area_width - width) * 0.5;
+  const double top = (area_height - height) * 0.5;
+  if (x < left || x > left + width || y < top || y > top + height) {
+    return std::nullopt;
+  }
+  return VideoPoint{static_cast<float>((x - left) / width),
+                    static_cast<float>((y - top) / height)};
+}
+
+}  // namespace crossdesk
+
+#endif
@@ -0,0 +1,110 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-26
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _VIDEO_LATENCY_H_
+#define _VIDEO_LATENCY_H_
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+#include <memory>
+#include <mutex>
+#include <optional>
+
+namespace crossdesk {
+
+class VideoLatencyStats;
+
+// Travels with the exact queued pixels, including native frames. Its clock is
+// translated once at the receive callback; rendering needs no live PeerPtr.
+struct VideoLatencyFrame {
+  using Clock = std::chrono::steady_clock;
+  std::shared_ptr<VideoLatencyStats> stats;
+  uint64_t id = 0;
+  Clock::time_point capture_time{};
+  void MarkPresented(Clock::time_point now = Clock::now()) const;
+  // Fallback for renderers which expose submission but no presentation time.
+  void MarkSubmitted(Clock::time_point now = Clock::now()) const;
+};
+
+class VideoLatencyStats
+    : public std::enable_shared_from_this<VideoLatencyStats> {
+ public:
+  using Clock = VideoLatencyFrame::Clock;
+  struct Snapshot {
+    double average_ms;
+    size_t samples;
+  };
+
+  VideoLatencyFrame Frame(uint64_t captured_us, int64_t local_now_us,
+                          Clock::time_point now = Clock::now()) {
+    if (captured_us == 0 || local_now_us <= 0 ||
+        captured_us > uint64_t(local_now_us) ||
+        uint64_t(local_now_us) - captured_us > 5'000'000)
+      return {};
+    std::lock_guard lock(mutex_);
+    return {shared_from_this(), ++issued_id_,
+            now - std::chrono::microseconds(local_now_us - captured_us)};
+  }
+
+  void Record(const VideoLatencyFrame& frame, Clock::time_point now) {
+    std::lock_guard lock(mutex_);
+    // Redraws, cached snapshots and late completions must not count twice.
+    if (frame.id <= last_id_) return;
+    last_id_ = frame.id;
+    const double ms =
+        std::chrono::duration<double, std::milli>(now - frame.capture_time)
+            .count();
+    if (ms < 0 || ms > 5000) return;
+    samples_.push_back({now, ms});
+    Prune(now);
+  }
+
+  std::optional<Snapshot> Get(Clock::time_point now = Clock::now()) {
+    std::lock_guard lock(mutex_);
+    Prune(now);
+    if (samples_.empty()) return std::nullopt;
+    double sum = 0;
+    for (const auto& sample : samples_) {
+      sum += sample.ms;
+    }
+    return Snapshot{sum / samples_.size(), samples_.size()};
+  }
+
+  void Reset() {
+    std::lock_guard lock(mutex_);
+    samples_.clear();
+    last_id_ = issued_id_;  // Invalidate frames still held by a renderer.
+  }
+
+ private:
+  void Prune(Clock::time_point now) {
+    while (!samples_.empty() &&
+           (now - samples_.front().time > std::chrono::seconds(1) ||
+            samples_.size() > 240))
+      samples_.pop_front();
+  }
+  struct Sample {
+    Clock::time_point time;
+    double ms;
+  };
+  std::mutex mutex_;
+  uint64_t issued_id_ = 0;
+  uint64_t last_id_ = 0;
+  std::deque<Sample> samples_;
+};
+
+inline void VideoLatencyFrame::MarkSubmitted(Clock::time_point now) const {
+  MarkPresented(now);
+}
+
+inline void VideoLatencyFrame::MarkPresented(Clock::time_point now) const {
+  if (stats) stats->Record(*this, now);
+}
+}  // namespace crossdesk
+
+#endif
@@ -0,0 +1,59 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-26
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _CONNECTION_LATENCY_H_
+#define _CONNECTION_LATENCY_H_
+
+#include <chrono>
+#include <cmath>
+#include <mutex>
+#include <optional>
+
+namespace crossdesk::gui_detail {
+
+// Presentation-only smoothing. The transport's raw RTT remains available for
+// recovery, congestion control and diagnostics. A missing one-second report
+// does not flicker, but a disconnected/stalled peer cannot leave a stale value.
+class ConnectionLatencyStats {
+ public:
+  using Clock = std::chrono::steady_clock;
+
+  void Update(double rtt_ms, Clock::time_point now = Clock::now()) {
+    if (!std::isfinite(rtt_ms) || rtt_ms < 0 || rtt_ms > 2000) return;
+    std::lock_guard lock(mutex_);
+    if (average_ms_ && now < updated_) return;
+    if (!Fresh(now)) {
+      average_ms_ = rtt_ms;
+    } else {
+      *average_ms_ += 0.25 * (rtt_ms - *average_ms_);
+    }
+    updated_ = now;
+  }
+
+  std::optional<double> Get(Clock::time_point now = Clock::now()) const {
+    std::lock_guard lock(mutex_);
+    return Fresh(now) ? average_ms_ : std::nullopt;
+  }
+
+  void Reset() {
+    std::lock_guard lock(mutex_);
+    average_ms_.reset();
+  }
+
+ private:
+  bool Fresh(Clock::time_point now) const {
+    // The UI may snapshot `now` just before the report thread updates us.
+    // A newer valid report must not cause a one-frame unavailable flicker.
+    return average_ms_ && now - updated_ < std::chrono::seconds(3);
+  }
+  mutable std::mutex mutex_;
+  std::optional<double> average_ms_;
+  Clock::time_point updated_{};
+};
+
+}  // namespace crossdesk::gui_detail
+
+#endif
@@ -6,49 +6,57 @@
 #include <shared_mutex>
 #include <string>
 #include <thread>
+#include <utility>
 #include <vector>

-#include "display_stream_id.h"
+#include <display_stream_id.h>
 #include "localization.h"
 #include "platform.h"
 #include "platform/video_renderer.h"
 #include "rd_log.h"
+#include "runtime/device_presence_request.h"
 #include "runtime/gui_runtime.h"

 namespace crossdesk {

 namespace {
 constexpr auto kPresenceProbeTimeout = std::chrono::seconds(5);
+constexpr auto kPresenceRefreshInterval = std::chrono::seconds(30);
+constexpr auto kPresenceRetryInterval = std::chrono::seconds(1);
 }  // namespace

+bool GuiRuntime::HasActiveSession() {
+  if (stream_window_inited_) return true;
+  std::shared_lock lock(connection_status_mutex_);
+  return std::any_of(connection_status_.begin(), connection_status_.end(),
+                     [](const auto& entry) {
+                       return entry.second == ConnectionStatus::Connecting ||
+                              entry.second == ConnectionStatus::Connected;
+                     });
+}
+
 void GuiRuntime::HandleConnectionStatusChange() {
-  if (signal_connected_ && peer_ && need_to_send_recent_connections_) {
-    if (!recent_connection_ids_.empty()) {
-      nlohmann::json j;
-      j["type"] = "recent_connections_presence";
-      j["user_id"] = client_id_;
-      j["devices"] = nlohmann::json::array();
-      for (const auto& id : recent_connection_ids_) {
-        std::string pure_id = id;
-        size_t pos_y = pure_id.find('Y');
-        size_t pos_n = pure_id.find('N');
-        size_t pos = std::string::npos;
-        if (pos_y != std::string::npos &&
-            (pos_n == std::string::npos || pos_y < pos_n)) {
-          pos = pos_y;
-        } else if (pos_n != std::string::npos) {
-          pos = pos_n;
-        }
-        if (pos != std::string::npos) {
-          pure_id = pure_id.substr(0, pos);
-        }
-        j["devices"].push_back(pure_id);
-      }
-      auto s = j.dump();
-      SendSignalMessage(peer_, s.data(), s.size());
-    }
+  if (!signal_connected_ || !peer_) {
+    return;
+  }
+  const auto now = std::chrono::steady_clock::now();
+  if (now - last_presence_request_attempt_at_ < kPresenceRetryInterval) {
+    return;
+  }
+  // Consume the flag before sending so a concurrent reconnect cannot lose its
+  // refresh request. Keep it pending while disconnected or after a send error.
+  const bool requested = need_to_send_recent_connections_.exchange(false);
+  if (!requested && now < next_presence_refresh_at_) {
+    return;
+  }
+  last_presence_request_attempt_at_ = now;
+  const auto message =
+      BuildDevicePresenceRequest(client_id_, recent_connection_ids_, true).dump();
+  if (SendSignalMessage(peer_, message.data(), message.size()) == 0) {
+    next_presence_refresh_at_ = now + kPresenceRefreshInterval;
+  } else {
+    need_to_send_recent_connections_ = true;
  }
-  need_to_send_recent_connections_ = false;
 }

 void GuiRuntime::HandlePendingPresenceProbe() {
@@ -123,32 +131,41 @@ void GuiRuntime::HandlePresenceProbeTimeout() {
 void GuiRuntime::HandleServerControllerDisconnected(
    const std::string& remote_id, const char* reason) {
  keyboard_.ReleaseRemotePressedKeys(remote_id, reason);
+#ifdef _WIN32
+  devices_.ReleaseRemoteMouseButtons();
+#endif
+  {
+    std::lock_guard lock(remote_pointer_input_mutex_);
+    last_remote_pointer_input_time_.erase(remote_id);
+  }

  bool has_connected_controller = false;
-  bool has_web_controller = false;
  std::string remaining_controller_id;
  {
    std::unique_lock lock(connection_status_mutex_);
    connection_status_.erase(remote_id);
+    devices_.OnControllerConnectionsChanged();
    connection_host_names_.erase(remote_id);
+    privacy_sessions_.Disconnected(remote_id);
    for (const auto& [id, status] : connection_status_) {
      if (status != ConnectionStatus::Connected) {
        continue;
      }
      has_connected_controller = true;
-      has_web_controller =
-          has_web_controller || id.find("web") != std::string::npos;
      if (remaining_controller_id.empty()) {
        remaining_controller_id = id;
      }
    }
  }
-  show_cursor_ = has_web_controller;
  if (has_connected_controller) {
    remote_client_id_ = remaining_controller_id;
    return;
  }

+  LOG_INFO("Last remote controller disconnected; recovering privacy, reason={}",
+           reason ? reason : "unknown");
+  privacy_.Disconnected();
+
  need_to_create_server_window_.store(false, std::memory_order_release);
  need_to_destroy_server_window_.store(true, std::memory_order_release);
  is_server_mode_ = false;
@@ -166,14 +183,11 @@ void GuiRuntime::HandleServerControllerDisconnected(
 #else
  start_screen_capturer_ = false;
 #endif
-  start_speaker_capturer_ = false;
+  devices_.StopSpeakerCapturer();
  start_mouse_controller_ = false;
  start_keyboard_capturer_ = false;
  remote_client_id_.clear();
-  if (audio_capture_) {
-    devices_.StopSpeakerCapturer();
-    audio_capture_ = false;
-  }
+  audio_capture_ = false;
  devices_.ResetToInitialDisplay();
 }

@@ -195,11 +209,9 @@ int GuiRuntime::RequestSingleDevicePresence(const std::string& remote_id,
    pending_presence_remember_password_ = remember_password;
  }

-  nlohmann::json j;
-  j["type"] = "recent_connections_presence";
-  j["user_id"] = client_id_;
-  j["devices"] = nlohmann::json::array({remote_id});
-  auto s = j.dump();
+  const auto s = BuildDevicePresenceRequest(
+                     client_id_, recent_connection_ids_, false, remote_id)
+                     .dump();

  int ret = SendSignalMessage(peer_, s.data(), s.size());
  if (ret != 0) {
@@ -216,6 +228,11 @@ int GuiRuntime::RequestSingleDevicePresence(const std::string& remote_id,
 }

 void GuiRuntime::CloseRemoteSession(std::shared_ptr<RemoteSession> props) {
+  if (!props || props->closing_.exchange(true)) return;
+  if (props->peer_events_) props->peer_events_->Deactivate();
+  props->connection_established_ = false;
+  props->streaming_ = false;
+  props->connection_status_.store(ConnectionStatus::Closed);
  std::shared_ptr<std::vector<unsigned char>> frame_snapshot;
  int video_width = 0;
  int video_height = 0;
@@ -241,91 +258,170 @@ void GuiRuntime::CloseRemoteSession(std::shared_ptr<RemoteSession> props) {
    }
  }

-  if (frame_snapshot && !frame_snapshot->empty() && video_width > 0 &&
-      video_height > 0) {
-    std::vector<unsigned char> buffer_copy(*frame_snapshot);
-    std::string remote_id = props->remote_id_;
-    std::string remote_host_name = props->remote_host_name_;
-    std::string password =
-        props->remember_password_ ? props->remote_password_ : "";
-
-    std::thread save_thread([buffer_copy, video_width, video_height, remote_id,
-                             remote_host_name, password,
-                             thumbnail = thumbnail_]() {
-      thumbnail->SaveToThumbnail((char*)buffer_copy.data(), video_width,
-                                 video_height, remote_id, remote_host_name,
-                                 password);
-    });
-
-    {
-      std::lock_guard<std::mutex> lock(thumbnail_save_threads_mutex_);
-      thumbnail_save_threads_.emplace_back(std::move(save_thread));
-    }
-  }
-
  if (native_renderer) {
    native_renderer->DiscardStream(props->remote_id_);
    video_frame_dirty_.store(true, std::memory_order_release);
  }

-  if (props->peer_) {
-    LOG_INFO("[{}] Leave connection [{}]", props->local_id_, props->remote_id_);
-    LeaveConnection(props->peer_, props->remote_id_.c_str());
-    LOG_INFO("Destroy peer [{}]", props->local_id_);
-    DestroyPeer(&props->peer_);
+  PeerPtr* peer = nullptr;
+  {
+    // Audio/clipboard senders hold a shared map lock while using this pointer.
+    std::unique_lock lock(remote_sessions_mutex_);
+    peer = std::exchange(props->peer_, nullptr);
  }
+  const auto queued_at = std::chrono::steady_clock::now();
+  session_cleanup_tasks_[props->remote_id_] = session_cleanup_queue_.PostTask(
+      [props, peer, frame_snapshot, video_width, video_height,
+       thumbnail = thumbnail_, queued_at]() mutable {
+        if (peer) {
+          LOG_INFO("[{}] Background leave connection [{}]", props->local_id_,
+                   props->remote_id_);
+          LeaveConnection(peer, props->remote_id_.c_str());
+          DestroyPeer(&peer);
+        }
+        if (thumbnail && frame_snapshot && !frame_snapshot->empty() &&
+            video_width > 0 && video_height > 0) {
+          thumbnail->SaveToThumbnail(
+              reinterpret_cast<char*>(frame_snapshot->data()), video_width,
+              video_height, props->remote_id_, props->remote_host_name_,
+              props->remember_password_ ? props->remote_password_ : "");
+        }
+        const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+            std::chrono::steady_clock::now() - queued_at).count();
+        LOG_INFO("[{}] Session cleanup completed in {} ms", props->remote_id_,
+                 elapsed);
+      });
+}
+
+void GuiRuntime::CloseServerController(const std::string& remote_id) {
+  if (!peer_ || remote_id.empty() || controller_cleanup_tasks_.count(remote_id))
+    return;
+  controller_cleanup_tasks_[remote_id] = session_cleanup_queue_.PostTask(
+      [peer = peer_, remote_id] { LeaveConnection(peer, remote_id.c_str()); });
+}
+
+void GuiRuntime::CloseConnectionPeer() {
+  if (!peer_) return;
+  peer_events_->Deactivate();
+  std::vector<std::string> controllers;
+  {
+    std::shared_lock lock(connection_status_mutex_);
+    for (const auto& [id, status] : connection_status_) controllers.push_back(id);
+  }
+  for (const auto& id : controllers)
+    HandleServerControllerDisconnected(id, "peer_closed");
+  devices_.StopMouseController();
+  devices_.StopScreenCapturer();
+  devices_.StopSpeakerCapturer();
+  devices_.StopKeyboardCapturer();
+  signal_connected_ = false;
+  device_presence_cache_.SetSignalConnected(false);
+  signal_status_ = SignalStatus::SignalClosed;
+  PeerPtr* peer;
+  {
+    std::unique_lock lock(remote_sessions_mutex_);
+    peer = std::exchange(peer_, nullptr);
+  }
+  // The same serial queue also owns outstanding controller disconnects, so
+  // these finish before the shared peer is destroyed.
+  connection_peer_cleanup_ = session_cleanup_queue_.PostTask(
+      [peer, handler = peer_events_, id = std::string(client_id_)]() mutable {
+        LOG_INFO("[{}] Background connection peer cleanup", id);
+        LeaveConnection(peer, id.c_str());
+        DestroyPeer(&peer);
+      });
 }

 void GuiRuntime::CloseAllRemoteSessions() {
-  if (peer_) {
-    LOG_INFO("[{}] Leave connection [{}]", client_id_, client_id_);
-    LeaveConnection(peer_, client_id_);
-    is_client_mode_ = false;
-    devices_.StopMouseController();
-    devices_.StopScreenCapturer();
-    devices_.StopSpeakerCapturer();
-    devices_.StopKeyboardCapturer();
-    LOG_INFO("Destroy peer [{}]", client_id_);
-    DestroyPeer(&peer_);
-  }
-
+  CloseConnectionPeer();
+  is_client_mode_ = false;
+  pending_reconnects_.clear();
+  std::vector<std::shared_ptr<RemoteSession>> sessions;
  {
-    // std::shared_lock lock(remote_sessions_mutex_);
-    for (auto& it : remote_sessions_) {
-      auto props = it.second;
-      CloseRemoteSession(props);
-    }
+    std::shared_lock lock(remote_sessions_mutex_);
+    for (const auto& [id, props] : remote_sessions_) sessions.push_back(props);
  }
-
+  for (const auto& props : sessions) CloseRemoteSession(props);
  {
-    // std::unique_lock lock(remote_sessions_mutex_);
+    std::unique_lock lock(remote_sessions_mutex_);
    remote_sessions_.clear();
  }
 }

-void GuiRuntime::WaitForThumbnailSaveTasks() {
-  std::vector<std::thread> threads_to_join;
-
-  {
-    std::lock_guard<std::mutex> lock(thumbnail_save_threads_mutex_);
-    threads_to_join.swap(thumbnail_save_threads_);
+void GuiRuntime::HandleSessionCleanup() {
+  auto completed = [](std::future<void>& task) {
+    if (!task.valid() || task.wait_for(std::chrono::seconds(0)) !=
+                             std::future_status::ready) return false;
+    try {
+      task.get();
+    } catch (const std::exception& error) {
+      LOG_ERROR("Connection cleanup failed: {}", error.what());
+    }
+    return true;
+  };
+  completed(connection_peer_cleanup_);
+  for (auto it = controller_cleanup_tasks_.begin();
+       it != controller_cleanup_tasks_.end();) {
+    if (completed(it->second)) it = controller_cleanup_tasks_.erase(it);
+    else ++it;
  }
-
-  if (threads_to_join.empty()) {
-    return;
+  std::vector<std::pair<std::string, PendingReconnect>> reconnects;
+  for (auto it = session_cleanup_tasks_.begin();
+       it != session_cleanup_tasks_.end();) {
+    if (it->second.wait_for(std::chrono::seconds(0)) !=
+        std::future_status::ready) {
+      ++it;
+      continue;
+    }
+    try {
+      it->second.get();
+    } catch (const std::exception& error) {
+      LOG_ERROR("[{}] Session cleanup failed: {}", it->first, error.what());
+    }
+    if (auto pending = pending_reconnects_.find(it->first);
+        pending != pending_reconnects_.end()) {
+      reconnects.emplace_back(pending->first, std::move(pending->second));
+      pending_reconnects_.erase(pending);
+    }
+    it = session_cleanup_tasks_.erase(it);
+    reload_recent_connections_ = true;
+    recent_connection_image_save_time_ = 0;
  }
+  for (const auto& [id, request] : reconnects) {
+    ConnectTo(id, request.password.c_str(), request.remember_password);
+  }
+}

-  for (auto& thread : threads_to_join) {
-    if (thread.joinable()) {
-      thread.join();
+void GuiRuntime::WaitForSessionCleanup() {
+  pending_reconnects_.clear();
+  auto drain = [](std::future<void>& task) {
+    if (!task.valid()) return;
+    try {
+      task.get();
+    } catch (const std::exception& error) {
+      LOG_ERROR("Connection cleanup failed: {}", error.what());
+    }
+  };
+  drain(connection_peer_cleanup_);
+  for (auto& [id, task] : controller_cleanup_tasks_) drain(task);
+  controller_cleanup_tasks_.clear();
+  for (auto& [id, task] : session_cleanup_tasks_) {
+    try {
+      task.get();
+    } catch (const std::exception& error) {
+      LOG_ERROR("[{}] Session cleanup failed: {}", id, error.what());
    }
  }
+  session_cleanup_tasks_.clear();
 }

 void GuiRuntime::ResetRemoteSessionResources(
    std::shared_ptr<RemoteSession> props) {
+  props->net_traffic_stats_.Reset();
  {
    std::lock_guard<std::mutex> lock(props->video_frame_mutex_);
+    props->video_latency_->Reset();
+    props->video_frame_timing_ = {};
    props->front_frame_.reset();
    props->back_frame_.reset();
    props->thumbnail_frame_.reset();
@@ -342,6 +438,7 @@ void GuiRuntime::ResetRemoteSessionResources(
    std::lock_guard<std::mutex> lock(props->remote_cursor_state_mutex_);
    props->remote_cursor_state_ = {};
    props->remote_cursor_state_received_ = false;
+    props->cursor_presentation_ = {};
  }
 }

@@ -361,6 +458,11 @@ std::shared_ptr<GuiRuntime::RemoteSession> GuiRuntime::FindRemoteSession(

 int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
                          bool remember_password, bool bypass_presence_check) {
+  if (session_cleanup_tasks_.count(remote_id)) {
+    pending_reconnects_[remote_id] = {password ? password : "", remember_password};
+    LOG_INFO("[{}] Reconnect queued until previous peer is destroyed", remote_id);
+    return 0;
+  }
  if (!bypass_presence_check && !device_presence_cache_.IsOnline(remote_id)) {
    int ret =
        RequestSingleDevicePresence(remote_id, password, remember_password);
@@ -378,16 +480,49 @@ int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
  LOG_INFO("Connect to [{}]", remote_id);
  focused_remote_id_ = remote_id;

-  // std::shared_lock shared_lock(remote_sessions_mutex_);
-  bool exists = (remote_sessions_.find(remote_id) != remote_sessions_.end());
-  // shared_lock.unlock();
+  auto stale = FindRemoteSession(remote_id);
+  bool exists = stale != nullptr;
+  if (stale) {
+    // A failed CreatePeer or a completed close can leave a session record
+    // without a reusable peer. Recreate it instead of leaving the UI in
+    // Connecting forever while JoinConnection has nothing to call.
+    if (stale->peer_ == nullptr) {
+      std::unique_lock lock(remote_sessions_mutex_);
+      auto it = remote_sessions_.find(remote_id);
+      if (it != remote_sessions_.end() && it->second == stale) {
+        remote_sessions_.erase(it);
+        exists = false;
+        LOG_INFO("[{}] Recreating stale remote session before connect",
+                 remote_id);
+      }
+    }
+    if (exists && !stale->closing_.load() &&
+        !stale->connection_established_) {
+      const auto status = stale->connection_status_.load();
+      if (status == ConnectionStatus::Disconnected ||
+          status == ConnectionStatus::Failed ||
+          status == ConnectionStatus::Closed) {
+        // The recreated session starts with an empty password; callers that
+        // pass none expect the one stored by the previous attempt to be reused.
+        const bool keep_stored_password = !password || !*password;
+        pending_reconnects_[remote_id] = {
+            keep_stored_password ? std::string(stale->remote_password_)
+                                 : std::string(password),
+            remember_password};
+        CloseRemoteSession(stale);
+        LOG_INFO("[{}] Reconnecting after terminal peer status {}", remote_id,
+                 static_cast<int>(status));
+        return 0;
+      }
+    }
+  }

  if (!exists) {
    PeerPtr* peer_to_init = nullptr;
    std::string local_id;

    {
-      // std::unique_lock unique_lock(remote_sessions_mutex_);
+      std::unique_lock unique_lock(remote_sessions_mutex_);
      if (remote_sessions_.find(remote_id) == remote_sessions_.end()) {
        remote_sessions_[remote_id] = std::make_shared<RemoteSession>();
        auto props = remote_sessions_[remote_id];
@@ -395,15 +530,10 @@ int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
        props->remote_id_ = remote_id;
        memcpy(&props->params_, &params_, sizeof(Params));
        props->params_.user_id = props->local_id_.c_str();
+        props->peer_events_ = std::make_shared<PeerEventHandler>(*this);
+        props->params_.user_data = props->peer_events_.get();
        props->peer_ = CreatePeer(&props->params_);

-        props->control_window_width_ = title_bar_height_ * 10.0f;
-        props->control_window_height_ = title_bar_height_ * 1.3f;
-        props->control_window_min_width_ = title_bar_height_ * 0.65f;
-        props->control_window_min_height_ = title_bar_height_ * 1.3f;
-        props->control_window_max_width_ = title_bar_height_ * 10.0f;
-        props->control_window_max_height_ = title_bar_height_ * 7.0f;
-
        props->connection_status_.store(ConnectionStatus::Connecting);
        show_connection_status_window_ = true;

@@ -419,7 +549,7 @@ int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
        }
        AddAudioStream(props->peer_, props->audio_label_.c_str());
        AddDataStream(props->peer_, props->data_label_.c_str(), false);
-        AddDataStream(props->peer_, props->mouse_label_.c_str(), false);
+        AddDataStream(props->peer_, props->mouse_label_.c_str(), true);
        AddDataStream(props->peer_, props->keyboard_label_.c_str(), true);
        AddDataStream(props->peer_, props->control_data_label_.c_str(), true);
        AddDataStream(props->peer_, props->file_label_.c_str(), true);
@@ -441,8 +571,8 @@ int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
  }

  int ret = -1;
-  // std::shared_lock read_lock(remote_sessions_mutex_);
-  auto props = remote_sessions_[remote_id];
+  auto props = FindRemoteSession(remote_id);
+  if (!props || props->closing_) return -1;
  if (!props->connection_established_) {
    props->connection_status_.store(ConnectionStatus::Connecting);
    show_connection_status_window_ = true;
@@ -466,7 +596,6 @@ int GuiRuntime::ConnectTo(const std::string& remote_id, const char* password,
      }
    }
  }
-  // read_lock.unlock();

  return 0;
 }
@@ -0,0 +1,73 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _CURSOR_POSITION_H_
+#define _CURSOR_POSITION_H_
+
+#include <algorithm>
+#include <vector>
+
+#include <remote_action.h>
+
+#include "display_info.h"
+
+namespace crossdesk {
+
+inline void ResetCursorPosition(CursorState* state) {
+  if (!state) return;
+  state->position_update = true;
+  state->position_valid = false;
+  state->x = 0.5f;
+  state->y = 0.5f;
+  state->visual_offset_x = 0.0f;
+  state->visual_offset_y = 0.0f;
+  state->display_id = -1;
+}
+
+inline bool NormalizeCursorPosition(
+    double screen_x, double screen_y,
+    const std::vector<DisplayInfo>& displays, int preferred_display,
+    CursorState* state) {
+  if (!state) return false;
+  ResetCursorPosition(state);
+
+  auto contains = [&](int index) {
+    if (index < 0 || index >= static_cast<int>(displays.size())) return false;
+    const auto& display = displays[index];
+    return display.width > 0 && display.height > 0 &&
+           screen_x >= display.left && screen_x < display.right &&
+           screen_y >= display.top && screen_y < display.bottom;
+  };
+
+  int display_id = contains(preferred_display) ? preferred_display : -1;
+  if (display_id < 0) {
+    for (int index = 0; index < static_cast<int>(displays.size()); ++index) {
+      if (contains(index)) {
+        display_id = index;
+        break;
+      }
+    }
+  }
+  if (display_id < 0) return false;
+
+  const auto& display = displays[display_id];
+  // Screen coordinates describe a continuous rectangle with an exclusive
+  // right/bottom edge. Use its full extent so feedback is the exact inverse of
+  // normalized input instead of accumulating a one-pixel edge convention.
+  const double horizontal_extent = std::max(display.width, 1);
+  const double vertical_extent = std::max(display.height, 1);
+  state->position_valid = true;
+  state->x = static_cast<float>(std::clamp(
+      (screen_x - display.left) / horizontal_extent, 0.0, 1.0));
+  state->y = static_cast<float>(std::clamp(
+      (screen_y - display.top) / vertical_extent, 0.0, 1.0));
+  state->display_id = display_id;
+  return true;
+}
+
+}  // namespace crossdesk
+
+#endif
@@ -0,0 +1,77 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-16
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _CURSOR_PRESENTATION_H_
+#define _CURSOR_PRESENTATION_H_
+
+#include <remote_action.h>
+
+#include <cstdint>
+#include <optional>
+
+namespace crossdesk {
+
+// All times use one monotonic millisecond clock. The owning session's cursor
+// mutex protects this policy from the transport and UI threads.
+class CursorPresentation {
+ public:
+  static constexpr uint64_t kStateTimeoutMs = 1500;  // Three 500ms heartbeats.
+  static constexpr uint64_t kInputActivityMs = 1500;
+
+  void Observe(const CursorState& state, uint64_t now) {
+    if (state.render_mode == CursorRenderMode::unknown) {
+      // Repeated unavailable samples must not extend the recovery deadline.
+      if (!sample_unavailable_) stale_at_ = now + kStateTimeoutMs;
+      sample_unavailable_ = true;
+      return;
+    }
+    sample_unavailable_ = false;
+    stale_at_ = now + kStateTimeoutMs;
+    const bool separate =
+        state.render_mode == CursorRenderMode::separate ||
+        (state.render_mode == CursorRenderMode::legacy && state.visible);
+    // Old senders cannot distinguish embedded from hidden. Only explicit
+    // metadata from a new sender can establish the no-device compatibility
+    // case.
+    no_device_ = state.render_mode == CursorRenderMode::hidden &&
+                 state.hidden_reason == CursorHiddenReason::no_pointing_device;
+    held_shape_ = separate ? state.shape : RemoteCursorShape::none;
+    if (held_shape_ != RemoteCursorShape::none) {
+      last_visible_shape_ = held_shape_;
+    }
+    if (!no_device_) fallback_engaged_ = false;
+  }
+
+  void NoteInput(uint64_t now) { last_input_ = now; }
+
+  RemoteCursorShape Resolve(uint64_t now) {
+    if (!stale_at_) return RemoteCursorShape::default_cursor;
+
+    const bool recent_input =
+        last_input_ && now - *last_input_ < kInputActivityMs;
+    const bool can_recover =
+        now >= *stale_at_ || (!sample_unavailable_ && no_device_);
+    if (can_recover && recent_input) {
+      fallback_engaged_ = true;
+    }
+    // Once needed, retain the locator while idle until a good non-compatibility
+    // sample arrives. Otherwise it would blink off whenever input pauses.
+    return fallback_engaged_ ? last_visible_shape_ : held_shape_;
+  }
+
+ private:
+  bool sample_unavailable_ = false;
+  bool no_device_ = false;
+  bool fallback_engaged_ = false;
+  std::optional<uint64_t> stale_at_;
+  std::optional<uint64_t> last_input_;
+  RemoteCursorShape held_shape_ = RemoteCursorShape::default_cursor;
+  RemoteCursorShape last_visible_shape_ = RemoteCursorShape::default_cursor;
+};
+
+}  // namespace crossdesk
+
+#endif
@@ -0,0 +1,137 @@
+#include "runtime/cursor_state_provider.h"
+
+#include <remote_action.h>
+
+#if defined(_WIN32)
+
+#include <windows.h>
+
+#include "platform/windows/input/windows_cursor_state.h"
+#include "platform/windows/screen_capturer/captured_cursor_state.h"
+#include "platform/windows/screen_capturer/dxgi_cursor_state.h"
+#include "platform/windows/screen_capturer/secure_desktop_cursor_state.h"
+#include "runtime/cursor_position.h"
+
+namespace crossdesk {
+
+struct CursorStateProvider::Impl {
+  WindowsCursorState cursor;
+};
+
+CursorStateProvider::CursorStateProvider() : impl_(std::make_unique<Impl>()) {}
+CursorStateProvider::~CursorStateProvider() = default;
+
+bool CursorStateProvider::Sample(const std::vector<DisplayInfo>& displays,
+                                 int preferred_display, CursorState* state) {
+  if (!state) return false;
+
+  SecureDesktopCursorSnapshot secure_cursor{};
+  if (SharedSecureDesktopCursorState().Get(&secure_cursor)) {
+    if (!secure_cursor.valid) {
+      state->hidden_reason = CursorHiddenReason::secure_desktop_pending;
+      return false;
+    }
+    state->seq = 0;
+    NormalizeCursorPosition(secure_cursor.x, secure_cursor.y, displays,
+                            preferred_display, state);
+    state->visible = secure_cursor.visible != 0;
+    state->render_mode = static_cast<CursorRenderMode>(secure_cursor.render_mode);
+    state->hidden_reason =
+        static_cast<CursorHiddenReason>(secure_cursor.hidden_reason);
+    state->shape = state->visible
+                       ? static_cast<RemoteCursorShape>(secure_cursor.shape)
+                       : RemoteCursorShape::none;
+    return true;
+  }
+
+  CURSORINFO info{};
+  info.cbSize = sizeof(info);
+  if (!GetCursorInfo(&info)) return false;
+
+  state->seq = 0;
+  NormalizeCursorPosition(info.ptScreenPos.x, info.ptScreenPos.y, displays,
+                          preferred_display, state);
+  void* cursor_monitor = state->position_valid
+                             ? displays[state->display_id].handle
+                             : nullptr;
+  const bool embedded = SharedCapturedCursorState().IsEmbedded(cursor_monitor) ||
+      ((info.flags & CURSOR_SHOWING) != 0 &&
+       !SharedDxgiCursorState().ShouldDrawCursor(true, cursor_monitor));
+  impl_->cursor.Sample(info, embedded, state);
+  return true;
+}
+
+}  // namespace crossdesk
+
+#elif defined(__linux__) && !defined(__APPLE__)
+
+#include <X11/Xlib.h>
+#include <X11/extensions/Xfixes.h>
+
+#include <string>
+
+#include "linux_cursor_shape.h"
+#include "platform.h"
+#include "shared_cursor_state.h"
+#include "runtime/cursor_position.h"
+
+namespace crossdesk {
+namespace {
+
+bool CursorHasVisiblePixel(const XFixesCursorImage& image) {
+  const size_t pixel_count =
+      static_cast<size_t>(image.width) * static_cast<size_t>(image.height);
+  for (size_t index = 0; index < pixel_count; ++index) {
+    if (((image.pixels[index] >> 24U) & 0xffU) != 0) return true;
+  }
+  return false;
+}
+
+}  // namespace
+
+struct CursorStateProvider::Impl {
+  Display* display = XOpenDisplay(nullptr);
+
+  ~Impl() {
+    if (display) XCloseDisplay(display);
+  }
+};
+
+CursorStateProvider::CursorStateProvider() : impl_(std::make_unique<Impl>()) {}
+CursorStateProvider::~CursorStateProvider() = default;
+
+bool CursorStateProvider::Sample(const std::vector<DisplayInfo>& displays,
+                                 int preferred_display, CursorState* state) {
+  if (!state || !impl_) return false;
+  ResetCursorPosition(state);
+
+  if (IsWaylandSession()) {
+    SharedCursorState shared{};
+    if (GetSharedCursorState(&shared)) {
+      state->seq = 0;
+      state->visible = shared.visible;
+      state->shape = shared.visible ? shared.shape : RemoteCursorShape::none;
+      return true;
+    }
+  }
+
+  if (!impl_->display) return false;
+
+  XFixesCursorImage* image = XFixesGetCursorImage(impl_->display);
+  if (!image) return false;
+
+  const std::string name = image->name ? image->name : "";
+
+  state->seq = 0;
+  state->visible = CursorHasVisiblePixel(*image);
+  state->shape = state->visible ? ShapeFromLinuxCursorName(name)
+                                : RemoteCursorShape::none;
+  NormalizeCursorPosition(image->x, image->y, displays, preferred_display,
+                          state);
+  XFree(image);
+  return true;
+}
+
+}  // namespace crossdesk
+
+#endif
@@ -1,9 +1,18 @@
-#ifndef CROSSDESK_GUI_CURSOR_STATE_PROVIDER_H_
-#define CROSSDESK_GUI_CURSOR_STATE_PROVIDER_H_
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _CURSOR_STATE_PROVIDER_H_
+#define _CURSOR_STATE_PROVIDER_H_

 #include <memory>
+#include <vector>

-#include "device_controller.h"
+#include <remote_action.h>
+
+#include "display_info.h"

 namespace crossdesk {

@@ -17,7 +26,8 @@ class CursorStateProvider {
  CursorStateProvider(const CursorStateProvider&) = delete;
  CursorStateProvider& operator=(const CursorStateProvider&) = delete;

-  bool Sample(CursorState* state);
+  bool Sample(const std::vector<DisplayInfo>& displays,
+              int preferred_display, CursorState* state);

 private:
  struct Impl;
@@ -26,4 +36,4 @@ class CursorStateProvider {

 }  // namespace crossdesk

-#endif  // CROSSDESK_GUI_CURSOR_STATE_PROVIDER_H_
+#endif
@@ -0,0 +1,61 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-09-04
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _DEVICE_PRESENCE_CACHE_H_
+#define _DEVICE_PRESENCE_CACHE_H_
+
+#include <chrono>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+
+namespace crossdesk {
+
+class DevicePresenceCache {
+public:
+  using Clock = std::chrono::steady_clock;
+  static constexpr auto kMaxAge = std::chrono::seconds(60);
+
+  void SetSignalConnected(bool connected) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    signal_connected_ = connected;
+    cache_.clear();
+  }
+
+  void SetOnline(const std::string &device_id, bool online,
+                 Clock::time_point now = Clock::now()) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (signal_connected_) {
+      cache_[device_id] = {online, now};
+    }
+  }
+
+  bool IsOnline(const std::string &device_id,
+                Clock::time_point now = Clock::now()) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    const auto it = cache_.find(device_id);
+    return signal_connected_ && it != cache_.end() && it->second.online &&
+           now - it->second.updated_at < kMaxAge;
+  }
+
+  void Clear() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    cache_.clear();
+  }
+
+private:
+  struct Entry {
+    bool online;
+    Clock::time_point updated_at;
+  };
+  bool signal_connected_ = false;
+  std::unordered_map<std::string, Entry> cache_;
+  mutable std::mutex mutex_;
+};
+
+} // namespace crossdesk
+
+#endif
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
dijunkun	bbbcfb9d6f	[fix] correct video latency measurement and smooth connection RTT	2026-09-26 03:15:47 +08:00
dijunkun	9ef64cc00f	[fix] reduce release log verbosity and enforce single instance	2026-09-26 02:58:55 +08:00
dijunkun	b8389a8aa0	[feat] add connection latency to network statistics	2026-09-26 02:04:18 +08:00
dijunkun	7ac8163931	[feat] add video latency to network statistics	2026-09-26 00:39:05 +08:00
dijunkun	704938a157	[feat] update minirtc with adaptive media FEC	2026-09-25 23:39:23 +08:00
dijunkun	572a018a72	[docs] refresh README guides and desktop and web screenshots	2026-09-25 03:26:57 +08:00
dijunkun	41cab6fa0b	[fix] render toolbar off-state slashes correctly in software mode	2026-09-25 03:26:49 +08:00
dijunkun	f73a57baaa	[fix] restore missing includes for Linux and Windows builds	2026-09-25 02:20:02 +08:00
dijunkun	e62d473b64	[perf] reduce desktop build dependencies and binary size	2026-09-25 01:47:20 +08:00
dijunkun	3c5b3f8e38	[fix] add missing JSON include for Windows service runtime	2026-09-25 00:51:08 +08:00
kunkundi	191ba26772	[feat] add Linux headless mode and interactive console	2026-09-25 00:29:24 +08:00
dijunkun	c661319890	[feat] add background and manual update checks	2026-09-24 17:36:41 +08:00
dijunkun	e0cd4c0567	[feat] add live remote video settings to the toolbar	2026-09-24 15:44:02 +08:00
dijunkun	88da1081ef	[release] prepare v1.5.2 release notes	2026-09-24 11:15:58 +08:00
dijunkun	b9efb5944c	[fix] recover headless capture and use WGC for usbmmidd displays	2026-09-23 14:40:58 +08:00
dijunkun	5f26a0e239	[feat] add force relay connection option to settings	2026-09-22 11:03:51 +08:00
dijunkun	938ce01513	[fix] align password reset input style and limit it to six characters	2026-09-22 10:47:42 +08:00
dijunkun	2235d5cb62	[fix] place the cursor at the end of the password on retry	2026-09-22 10:39:27 +08:00
dijunkun	7e3e050edf	[feat] add random password refresh to the main window	2026-09-22 10:33:28 +08:00
dijunkun	b610a0ec7e	[fix] anchor display menu to the toolbar when network stats are expanded	2026-09-22 10:19:16 +08:00
dijunkun	120368e4f7	[fix] align remote mouse coordinates with the displayed video area	2026-09-22 10:06:41 +08:00
dijunkun	b34755c5ee	[chore] bundle the usbmmidd_v2 virtual display driver with Windows packages	2026-09-21 01:10:31 +08:00
dijunkun	6387f2e555	[feat] add headless compatibility capture and usbmmidd virtual display plugging	2026-09-21 01:10:30 +08:00
dijunkun	fb556a763d	[fix] keep Windows privacy screen across display changes and validate covers	2026-09-21 01:10:30 +08:00
dijunkun	276385b816	[fix] keep Windows display slots and input mapping stable across hotplug	2026-09-21 01:09:12 +08:00
dijunkun	1a59a6ac2e	[refactor] build host information in the wire library	2026-09-21 00:56:16 +08:00
dijunkun	485e347337	[fix] render CPU NV12 native frames rejected by the native renderer	2026-09-21 00:51:50 +08:00
dijunkun	89b39803e8	[fix] reuse stale sessions and stored passwords when reconnecting	2026-09-21 00:51:50 +08:00
dijunkun	4797af9260	[fix] correct Windows remote control session routing and key mapping	2026-09-19 03:59:35 +08:00
dijunkun	000b2e44e3	[fix] restore Windows cursor capture and web input control	2026-09-18 23:26:06 +08:00
dijunkun	26217f9d18	[fix] reset mouse input display when restoring initial capture display	2026-09-18 22:40:51 +08:00
dijunkun	c2ea90c740	[chore] remove unused ImGui code and old release notes	2026-09-18 19:54:47 +08:00
dijunkun	0eadcf2855	[fix] diagnose and serialize Linux image dependency installation	2026-09-17 12:42:44 +08:00
dijunkun	e263aab10d	[fix] keep Windows privacy screen active when running as administrator	2026-09-17 09:55:34 +08:00
dijunkun	9abdfbf684	[release] prepare v1.5.1 release notes	2026-09-17 02:56:49 +08:00
dijunkun	31a0b86cee	[fix] refine network stats layout and alignment	2026-09-17 02:45:35 +08:00
dijunkun	fb34f42744	[fix] show encryption status and simplify network stats labels	2026-09-17 02:01:55 +08:00
dijunkun	4302ab291c	[fix] overlay control bar tooltips on expanded network stats	2026-09-17 01:39:09 +08:00
dijunkun	4bf92c9e2c	[fix] use reliable transport for mouse input and cursor state	2026-09-17 01:31:54 +08:00
dijunkun	28de4cf938	[fix] improve Windows taskbar icon clarity at small sizes	2026-09-16 23:19:12 +08:00
dijunkun	ce7a3c178e	[fix] correct WGC and GDI cursor capture and positioning	2026-09-16 23:03:36 +08:00
dijunkun	d9116200fe	[fix] restore remote cursors on Windows without a physical mouse	2026-09-16 22:20:36 +08:00
dijunkun	1d9242515a	[fix] restore remote cursor visibility during Windows privacy screen	2026-09-16 20:27:59 +08:00
dijunkun	ad62e60b9a	[fix] restore shared capture on Windows secure desktop	2026-09-16 15:31:27 +08:00
dijunkun	c4aca303c8	[fix] restore cursor visibility on Windows lock screen	2026-09-16 14:48:39 +08:00
dijunkun	57bb91dba3	[fix] prevent duplicate cursors during Windows window dragging	2026-09-16 13:51:35 +08:00
dijunkun	57cab3979e	[fix] initialize logging before startup operations and update MiniRTC	2026-09-16 12:54:07 +08:00
dijunkun	d8ccdbaa38	[fix] add capture delivery diagnostics	2026-09-16 12:54:06 +08:00
dijunkun	f3e67d7d6e	[fix] recognize macOS window resize cursors	2026-09-15 16:44:19 +08:00
dijunkun	d648585891	[fix] restore Linux X11 remote keyboard capture	2026-09-15 16:23:42 +08:00
dijunkun	e40c7fca98	[fix] disable privacy screen for legacy and web clients	2026-09-15 13:04:53 +08:00
dijunkun	f6324416ec	[fix] update MiniRTC legacy DTLS-SRTP compatibility	2026-09-15 12:20:00 +08:00
dijunkun	0977bd4195	[fix] update MiniRTC SRTP replay handling and bandwidth accounting	2026-09-15 03:38:29 +08:00
dijunkun	f4e094cb35	[fix] update MiniRTC packet validation and SRTP buffering	2026-09-15 03:16:18 +08:00
dijunkun	1fe706c5fc	[fix] update MiniRTC SRTP initialization	2026-09-15 03:03:47 +08:00
dijunkun	5fd928ddba	[fix] update MiniRTC DTLS-SRTP key layout and profiles	2026-09-15 02:53:25 +08:00
dijunkun	977899b240	[feat] enable iOS punching and preserve connection errors	2026-09-15 02:37:30 +08:00
dijunkun	7fc1344756	[feat] enable enhanced UDP punching on desktop	2026-09-15 02:37:30 +08:00
dijunkun	73e3bf709d	[perf] exclude optional libaom from default builds	2026-09-13 06:43:29 +08:00
dijunkun	6d90c28513	[perf] strip packaged Slint runtime symbols	2026-09-13 06:39:26 +08:00
dijunkun	c944db6519	[perf] scope desktop build variant and version defines	2026-09-13 06:39:23 +08:00
dijunkun	fc921c9ca1	[perf] avoid redundant iOS native archive rebuilds	2026-09-13 06:36:05 +08:00
dijunkun	ba2afc982b	[fix] repair macOS Intel OpenH264 CI build	2026-09-13 06:04:23 +08:00
dijunkun	c6635fbdc8	[feat] add Linux X11 privacy screen and automatic recovery	2026-09-13 03:49:17 +08:00
dijunkun	3c403f6162	[fix] update minirtc for SIMD and frame rate fixes	2026-09-13 02:40:44 +08:00
dijunkun	b54d32ef41	[fix] disable and uncheck hardware codec setting in unsupported builds	2026-09-13 01:40:44 +08:00
dijunkun	28e9626e0d	[fix] preserve Windows privacy startup and server window	2026-09-13 01:23:30 +08:00
kunkundi	a6e325f190	[feat] add macOS privacy screen and keep remote sessions running	2026-09-13 00:38:40 +08:00
dijunkun	23bf2ff8b8	[feat] add compact tooltips for all control bar buttons	2026-09-12 22:39:44 +08:00
dijunkun	56ebfdf8e7	[feat] add dedicated privacy screen controls	2026-09-12 22:24:09 +08:00
kunkundi	99ae0fc811	[fix] avoid false Windows privacy screen obstruction failures	2026-09-11 17:43:04 +08:00
dijunkun	9af7417c46	[feat] add Windows screen capture method setting	2026-09-11 16:41:16 +08:00
dijunkun	ceb0a1654a	[feat] add Windows privacy screen and prefer DXGI capture	2026-09-11 16:11:50 +08:00
dijunkun	4f200095f4	[fix] improve OpenGL video clarity when downscaling	2026-09-09 17:28:48 +08:00
dijunkun	bd0a7aa2f6	[fix] prevent system audio capture hangs across desktop platforms	2026-09-09 11:34:47 +08:00
dijunkun	b87ab025be	[feat] use server-issued ICE configuration across clients	2026-09-08 17:07:16 +08:00
dijunkun	5b60695a52	[fix] restore Linux Dock icons in packaged builds	2026-09-08 15:03:32 +08:00
dijunkun	0002bcea74	[fix] hide macOS Dock icon when closing to the tray	2026-09-08 00:22:08 +08:00
dijunkun	58225de7ea	[release] prepare v1.5.0 release notes and iOS version	2026-09-07 23:24:53 +08:00
dijunkun	5f37d0e753	[docs] update MiniRTC submodule documentation	2026-09-07 23:13:49 +08:00
dijunkun	b518ea82e2	[docs] refresh README screenshots and platform guides	2026-09-07 22:53:30 +08:00
dijunkun	abc8f907f3	[fix] restore iOS video after returning to the foreground	2026-09-07 21:31:08 +08:00
dijunkun	d498d3f0ef	[feat] show video resolution in the iOS floating status bar	2026-09-07 21:17:54 +08:00
dijunkun	55806d9e82	[fix] allow iOS relative mouse control outside the video area	2026-09-07 21:14:53 +08:00
dijunkun	2d3f1bb475	[fix] prevent iOS relative cursor jumps after movement	2026-09-07 21:11:27 +08:00
dijunkun	5d97d5a393	[fix] keep iOS floating controls clear of the Dynamic Island	2026-09-07 21:04:14 +08:00
dijunkun	19218a57f9	[fix] prevent stale device online status on iOS	2026-09-07 20:57:30 +08:00
dijunkun	af729144fe	[fix] prevent stale device online status	2026-09-07 20:02:19 +08:00
dijunkun	d381cbaa9b	[fix] show system tray icon on application startup	2026-09-07 17:42:25 +08:00
dijunkun	5aedb09c55	[feat] enable CUDA/OpenGL video rendering on Linux	2026-09-07 17:31:48 +08:00
dijunkun	fe1178e26f	[fix] move connection cleanup off the UI thread	2026-09-07 10:54:18 +08:00
dijunkun	e0cd761bdc	[fix] restore Windows lock-screen control and improve capture performance, fixes #98	2026-09-07 05:29:42 +08:00
dijunkun	2000654792	[fix] prevent Windows startup crashes from OpenGL failures, fixes #97	2026-09-07 04:20:54 +08:00
dijunkun	19800ef350	[fix] update MiniRTC iOS UPnP dependencies	2026-09-07 02:57:40 +08:00
dijunkun	d10b65cc19	[fix] update MiniRTC relay to P2P upgrades	2026-09-07 02:30:26 +08:00
dijunkun	3a0179968c	[fix] update MiniRTC ICE connectivity	2026-09-07 02:04:34 +08:00
dijunkun	55f389b834	[fix] update MiniRTC recovery tuning	2026-09-04 18:45:57 +08:00
dijunkun	8a58166c59	[fix] update MiniRtc video recovery timing	2026-09-04 17:35:14 +08:00
dijunkun	aa2ee8ce7f	[fix] update MiniRtc video recovery handling	2026-09-04 17:07:39 +08:00
dijunkun	b150d46501	[fix] align MiniRtc media interfaces and timestamps	2026-09-04 15:45:26 +08:00
dijunkun	010064d5b7	[feat] optimize Windows native video encoding	2026-09-04 02:23:16 +08:00
dijunkun	db3b26efe7	[feat] optimize macOS native video encoding	2026-09-04 02:06:44 +08:00
dijunkun	cd1b53ee65	[chore] standardize source file headers	2026-09-04 02:06:36 +08:00
dijunkun	b031a3953e	[feat] optimize macOS native video rendering	2026-09-04 01:28:13 +08:00
dijunkun	3f537ae63c	[feat] optimize Windows native video rendering	2026-09-03 18:01:09 +08:00
dijunkun	e716346b26	[fix] stabilize frame rate priority adaptation	2026-09-02 11:05:13 +08:00
dijunkun	b7e1adbec6	[feat] add video adaptation preference setting	2026-09-02 01:05:30 +08:00
dijunkun	58f2daa9c1	[fix] prioritize remote desktop resolution quality	2026-09-01 20:21:03 +08:00
dijunkun	8752e51921	[fix] build CI test targets separately	2026-09-01 08:33:59 +08:00
dijunkun	a8cb0e21ce	[fix] load desktop options on first configuration	2026-09-01 01:43:09 +08:00
dijunkun	90184f5251	[refactor] reorganize platform and wire sources	2026-09-01 01:29:30 +08:00
dijunkun	fb0ab4f14e	[fix] isolate iOS native build environment	2026-08-31 10:49:38 +08:00
dijunkun	0e3f3cec00	[fix] pin iOS CI xmake version	2026-08-31 10:39:36 +08:00
dijunkun	72af49eb80	[fix] use isolated iOS host build tools	2026-08-31 10:31:49 +08:00
dijunkun	36f05834b5	[fix] stabilize clean iOS dependency builds	2026-08-31 10:19:35 +08:00
dijunkun	1a190fbaf5	[fix] integrate iOS build workflow	2026-08-31 10:03:07 +08:00
dijunkun	1fe236da76	[fix] pin iOS CI package repository	2026-08-31 09:49:59 +08:00
dijunkun	3b989fb70d	[fix] set up Python for iOS CI	2026-08-31 02:20:46 +08:00
dijunkun	7595ab8bd8	[feat] add native iOS client support	2026-08-31 02:14:27 +08:00