[refactor] reorganize platform and wire sources

apps/desktop/src/platform/autostart_backend.h

@@ -0,0 +1,16 @@
+#ifndef CROSSDESK_PLATFORM_AUTOSTART_BACKEND_H_
+#define CROSSDESK_PLATFORM_AUTOSTART_BACKEND_H_
+
+#include <string>
+
+namespace crossdesk::platform {
+
+std::string GetAutostartExecutablePath();
+bool EnableAutostart(const std::string& app_name,
+                     const std::string& executable_path);
+bool DisableAutostart(const std::string& app_name);
+bool IsAutostartEnabled(const std::string& app_name);
+
+}  // namespace crossdesk::platform
+
+#endif  // CROSSDESK_PLATFORM_AUTOSTART_BACKEND_H_

apps/desktop/src/platform/clipboard_backend.h

@@ -0,0 +1,13 @@
+#ifndef CROSSDESK_PLATFORM_CLIPBOARD_BACKEND_H_
+#define CROSSDESK_PLATFORM_CLIPBOARD_BACKEND_H_
+
+namespace crossdesk::platform {
+
+bool ClipboardMonitoring();
+void HandleClipboardChange();
+void RunClipboardMonitor(int check_interval_ms);
+void WakeClipboardMonitor();
+
+}  // namespace crossdesk::platform
+
+#endif  // CROSSDESK_PLATFORM_CLIPBOARD_BACKEND_H_

apps/desktop/src/platform/common/gui/opengl_video_renderer.cpp

@@ -0,0 +1,928 @@
+#include "platform/common/gui/opengl_video_renderer.h"
+
+#if !defined(_WIN32) && !defined(__linux__)
+#error "OpenGlVideoRenderer is only available on Windows and Linux"
+#endif
+
+#if defined(_WIN32)
+#include <windows.h>
+#elif defined(__linux__)
+#include <dlfcn.h>
+#endif
+
+#include <GL/gl.h>
+#include <GL/glext.h>
+#if defined(__linux__)
+#include <GL/glx.h>
+#endif
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cstring>
+#include <limits>
+#include <mutex>
+#include <string>
+#include <utility>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+namespace {
+
+constexpr size_t kFrameSlotCount = 3;
+
+enum class SlotUse {
+  available,
+  pending,
+  uploading,
+};
+
+struct FrameSlot {
+  std::vector<unsigned char> bytes;
+  int width = 0;
+  int height = 0;
+  std::string remote_id;
+  uint64_t sequence = 0;
+  SlotUse use = SlotUse::available;
+  bool valid = false;
+};
+
+struct SharedFrameState {
+  mutable std::mutex mutex;
+  std::array<FrameSlot, kFrameSlotCount> slots;
+  std::string selected_stream;
+  uint64_t next_sequence = 1;
+};
+
+template <typename T> bool LoadOpenGlFunction(T *function, const char *name) {
+#if defined(_WIN32)
+  PROC address = wglGetProcAddress(name);
+  if (address == nullptr || address == reinterpret_cast<PROC>(1) ||
+      address == reinterpret_cast<PROC>(2) ||
+      address == reinterpret_cast<PROC>(3) ||
+      address == reinterpret_cast<PROC>(-1)) {
+    HMODULE module = GetModuleHandleW(L"opengl32.dll");
+    address = module ? GetProcAddress(module, name) : nullptr;
+  }
+  *function = reinterpret_cast<T>(address);
+#elif defined(__linux__)
+  void *address = dlsym(RTLD_DEFAULT, name);
+  if (address == nullptr) {
+    address = reinterpret_cast<void *>(
+        glXGetProcAddressARB(reinterpret_cast<const GLubyte *>(name)));
+  }
+  *function = reinterpret_cast<T>(address);
+#endif
+  return *function != nullptr;
+}
+
+struct OpenGlFunctions {
+  PFNGLACTIVETEXTUREPROC active_texture = nullptr;
+  PFNGLATTACHSHADERPROC attach_shader = nullptr;
+  PFNGLBINDBUFFERPROC bind_buffer = nullptr;
+  PFNGLBUFFERDATAPROC buffer_data = nullptr;
+  PFNGLCOMPILESHADERPROC compile_shader = nullptr;
+  PFNGLCREATEPROGRAMPROC create_program = nullptr;
+  PFNGLCREATESHADERPROC create_shader = nullptr;
+  PFNGLDELETEBUFFERSPROC delete_buffers = nullptr;
+  PFNGLDELETEPROGRAMPROC delete_program = nullptr;
+  PFNGLDELETESHADERPROC delete_shader = nullptr;
+  PFNGLDISABLEVERTEXATTRIBARRAYPROC disable_vertex_attrib_array = nullptr;
+  PFNGLENABLEVERTEXATTRIBARRAYPROC enable_vertex_attrib_array = nullptr;
+  PFNGLGENBUFFERSPROC gen_buffers = nullptr;
+  PFNGLGETATTRIBLOCATIONPROC get_attrib_location = nullptr;
+  PFNGLGETPROGRAMINFOLOGPROC get_program_info_log = nullptr;
+  PFNGLGETPROGRAMIVPROC get_program_iv = nullptr;
+  PFNGLGETSHADERINFOLOGPROC get_shader_info_log = nullptr;
+  PFNGLGETSHADERIVPROC get_shader_iv = nullptr;
+  PFNGLGETUNIFORMLOCATIONPROC get_uniform_location = nullptr;
+  PFNGLGETVERTEXATTRIBIVPROC get_vertex_attrib_iv = nullptr;
+  PFNGLGETVERTEXATTRIBPOINTERVPROC get_vertex_attrib_pointer_v = nullptr;
+  PFNGLLINKPROGRAMPROC link_program = nullptr;
+  PFNGLSHADERSOURCEPROC shader_source = nullptr;
+  PFNGLUNIFORM1FPROC uniform_1f = nullptr;
+  PFNGLUNIFORM1IPROC uniform_1i = nullptr;
+  PFNGLUNIFORM2FPROC uniform_2f = nullptr;
+  PFNGLUNIFORM4FPROC uniform_4f = nullptr;
+  PFNGLUSEPROGRAMPROC use_program = nullptr;
+  PFNGLVERTEXATTRIBPOINTERPROC vertex_attrib_pointer = nullptr;
+
+  bool Load() {
+    return LoadOpenGlFunction(&active_texture, "glActiveTexture") &&
+           LoadOpenGlFunction(&attach_shader, "glAttachShader") &&
+           LoadOpenGlFunction(&bind_buffer, "glBindBuffer") &&
+           LoadOpenGlFunction(&buffer_data, "glBufferData") &&
+           LoadOpenGlFunction(&compile_shader, "glCompileShader") &&
+           LoadOpenGlFunction(&create_program, "glCreateProgram") &&
+           LoadOpenGlFunction(&create_shader, "glCreateShader") &&
+           LoadOpenGlFunction(&delete_buffers, "glDeleteBuffers") &&
+           LoadOpenGlFunction(&delete_program, "glDeleteProgram") &&
+           LoadOpenGlFunction(&delete_shader, "glDeleteShader") &&
+           LoadOpenGlFunction(&disable_vertex_attrib_array,
+                              "glDisableVertexAttribArray") &&
+           LoadOpenGlFunction(&enable_vertex_attrib_array,
+                              "glEnableVertexAttribArray") &&
+           LoadOpenGlFunction(&gen_buffers, "glGenBuffers") &&
+           LoadOpenGlFunction(&get_attrib_location, "glGetAttribLocation") &&
+           LoadOpenGlFunction(&get_program_info_log, "glGetProgramInfoLog") &&
+           LoadOpenGlFunction(&get_program_iv, "glGetProgramiv") &&
+           LoadOpenGlFunction(&get_shader_info_log, "glGetShaderInfoLog") &&
+           LoadOpenGlFunction(&get_shader_iv, "glGetShaderiv") &&
+           LoadOpenGlFunction(&get_uniform_location, "glGetUniformLocation") &&
+           LoadOpenGlFunction(&get_vertex_attrib_iv, "glGetVertexAttribiv") &&
+           LoadOpenGlFunction(&get_vertex_attrib_pointer_v,
+                              "glGetVertexAttribPointerv") &&
+           LoadOpenGlFunction(&link_program, "glLinkProgram") &&
+           LoadOpenGlFunction(&shader_source, "glShaderSource") &&
+           LoadOpenGlFunction(&uniform_1f, "glUniform1f") &&
+           LoadOpenGlFunction(&uniform_1i, "glUniform1i") &&
+           LoadOpenGlFunction(&uniform_2f, "glUniform2f") &&
+           LoadOpenGlFunction(&uniform_4f, "glUniform4f") &&
+           LoadOpenGlFunction(&use_program, "glUseProgram") &&
+           LoadOpenGlFunction(&vertex_attrib_pointer, "glVertexAttribPointer");
+  }
+};
+
+GLuint CompileShader(const OpenGlFunctions &gl, GLenum type,
+                     const char *source) {
+  const GLuint shader = gl.create_shader(type);
+  if (shader == 0) {
+    return 0;
+  }
+  gl.shader_source(shader, 1, &source, nullptr);
+  gl.compile_shader(shader);
+
+  GLint compiled = GL_FALSE;
+  gl.get_shader_iv(shader, GL_COMPILE_STATUS, &compiled);
+  if (compiled == GL_TRUE) {
+    return shader;
+  }
+
+  GLint log_length = 0;
+  gl.get_shader_iv(shader, GL_INFO_LOG_LENGTH, &log_length);
+  std::string log(static_cast<size_t>(std::max(log_length, 1)), '\0');
+  GLsizei written = 0;
+  gl.get_shader_info_log(shader, static_cast<GLsizei>(log.size()), &written,
+                         log.data());
+  if (written >= 0 && static_cast<size_t>(written) < log.size()) {
+    log.resize(static_cast<size_t>(written));
+  }
+  LOG_ERROR("OpenGL NV12 {} shader compilation failed: {}",
+            type == GL_VERTEX_SHADER ? "vertex" : "fragment", log);
+  gl.delete_shader(shader);
+  return 0;
+}
+
+bool IsEnabled(GLenum capability) { return glIsEnabled(capability) == GL_TRUE; }
+
+void RestoreCapability(GLenum capability, bool enabled) {
+  if (enabled) {
+    glEnable(capability);
+  } else {
+    glDisable(capability);
+  }
+}
+
+struct VertexAttribState {
+  GLint enabled = GL_FALSE;
+  GLint size = 4;
+  GLint stride = 0;
+  GLint type = GL_FLOAT;
+  GLint normalized = GL_FALSE;
+  GLint buffer = 0;
+  void *pointer = nullptr;
+};
+
+VertexAttribState CaptureVertexAttrib(const OpenGlFunctions &gl, GLuint index) {
+  VertexAttribState state;
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_ENABLED,
+                          &state.enabled);
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_SIZE, &state.size);
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_STRIDE, &state.stride);
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_TYPE, &state.type);
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_NORMALIZED,
+                          &state.normalized);
+  gl.get_vertex_attrib_iv(index, GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING,
+                          &state.buffer);
+  gl.get_vertex_attrib_pointer_v(index, GL_VERTEX_ATTRIB_ARRAY_POINTER,
+                                 &state.pointer);
+  return state;
+}
+
+void RestoreVertexAttrib(const OpenGlFunctions &gl, GLuint index,
+                         const VertexAttribState &state) {
+  if (state.buffer != 0 || state.pointer != nullptr) {
+    gl.bind_buffer(GL_ARRAY_BUFFER, static_cast<GLuint>(state.buffer));
+    gl.vertex_attrib_pointer(index, state.size, static_cast<GLenum>(state.type),
+                             static_cast<GLboolean>(state.normalized),
+                             state.stride, state.pointer);
+  }
+  if (state.enabled == GL_TRUE) {
+    gl.enable_vertex_attrib_array(index);
+  } else {
+    gl.disable_vertex_attrib_array(index);
+  }
+}
+
+} // namespace
+
+struct OpenGlVideoRenderer::Impl {
+  OpenGlFunctions gl;
+  std::shared_ptr<SharedFrameState> frames =
+      std::make_shared<SharedFrameState>();
+  std::atomic<bool> ready{false};
+  GLuint program = 0;
+  GLuint vertex_buffer = 0;
+  GLuint y_texture = 0;
+  GLuint uv_texture = 0;
+  GLint position_location = -1;
+  GLint texcoord_location = -1;
+  GLint y_texture_location = -1;
+  GLint uv_texture_location = -1;
+  GLint target_size_location = -1;
+  GLint video_rect_location = -1;
+  GLint corner_radius_location = -1;
+  GLint video_enabled_location = -1;
+  int texture_width = 0;
+  int texture_height = 0;
+  std::string uploaded_stream;
+  uint64_t uploaded_sequence = 0;
+
+  void ResetGlHandles() {
+    program = 0;
+    vertex_buffer = 0;
+    y_texture = 0;
+    uv_texture = 0;
+    position_location = -1;
+    texcoord_location = -1;
+    y_texture_location = -1;
+    uv_texture_location = -1;
+    target_size_location = -1;
+    video_rect_location = -1;
+    corner_radius_location = -1;
+    video_enabled_location = -1;
+    texture_width = 0;
+    texture_height = 0;
+    uploaded_stream.clear();
+    uploaded_sequence = 0;
+  }
+};
+
+OpenGlVideoRenderer::OpenGlVideoRenderer()
+    : impl_(std::make_unique<Impl>()) {}
+
+OpenGlVideoRenderer::~OpenGlVideoRenderer() = default;
+
+bool OpenGlVideoRenderer::Setup() {
+  if (IsReady()) {
+    return true;
+  }
+  impl_->ready.store(false, std::memory_order_release);
+  impl_->ResetGlHandles();
+  if (!impl_->gl.Load()) {
+    LOG_WARN("OpenGL NV12 underlay unavailable: required functions missing");
+    return false;
+  }
+
+  static constexpr char kGlesVertexShader[] = R"glsl(
+#version 100
+attribute vec2 position;
+attribute vec2 texcoord;
+varying vec2 video_texcoord;
+void main() {
+  video_texcoord = texcoord;
+  gl_Position = vec4(position, 0.0, 1.0);
+}
+)glsl";
+  static constexpr char kGlesFragmentShader[] = R"glsl(
+#version 100
+#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+uniform sampler2D y_texture;
+uniform sampler2D uv_texture;
+uniform vec2 target_size;
+uniform vec4 video_rect;
+uniform float corner_radius;
+uniform float video_enabled;
+varying vec2 video_texcoord;
+void main() {
+  vec2 surface_point = video_texcoord * target_size;
+  vec3 rgb = vec3(0.0);
+  if (video_enabled > 0.5 &&
+      surface_point.x >= video_rect.x &&
+      surface_point.x <= video_rect.x + video_rect.z &&
+      surface_point.y >= video_rect.y &&
+      surface_point.y <= video_rect.y + video_rect.w) {
+    vec2 frame_texcoord =
+        (surface_point - video_rect.xy) / video_rect.zw;
+    float y = 1.16438356 *
+              (texture2D(y_texture, frame_texcoord).r - 16.0 / 255.0);
+    vec2 uv =
+        texture2D(uv_texture, frame_texcoord).ra - vec2(0.5, 0.5);
+    rgb = clamp(vec3(y + 1.59602678 * uv.y,
+                     y - 0.39176229 * uv.x - 0.81296764 * uv.y,
+                     y + 2.01723214 * uv.x),
+                0.0, 1.0);
+  }
+  float coverage = 1.0;
+  if (corner_radius > 0.0) {
+    vec2 half_size = target_size * 0.5;
+    vec2 corner = abs(surface_point - half_size) -
+                  (half_size - vec2(corner_radius));
+    float distance_to_edge =
+        length(max(corner, vec2(0.0))) +
+        min(max(corner.x, corner.y), 0.0) - corner_radius;
+    coverage = clamp(0.5 - distance_to_edge, 0.0, 1.0);
+  }
+  gl_FragColor = vec4(rgb * coverage, coverage);
+}
+)glsl";
+  static constexpr char kDesktopVertexShader[] = R"glsl(
+#version 110
+attribute vec2 position;
+attribute vec2 texcoord;
+varying vec2 video_texcoord;
+void main() {
+  video_texcoord = texcoord;
+  gl_Position = vec4(position, 0.0, 1.0);
+}
+)glsl";
+  static constexpr char kDesktopFragmentShader[] = R"glsl(
+#version 110
+uniform sampler2D y_texture;
+uniform sampler2D uv_texture;
+uniform vec2 target_size;
+uniform vec4 video_rect;
+uniform float corner_radius;
+uniform float video_enabled;
+varying vec2 video_texcoord;
+void main() {
+  vec2 surface_point = video_texcoord * target_size;
+  vec3 rgb = vec3(0.0);
+  if (video_enabled > 0.5 &&
+      surface_point.x >= video_rect.x &&
+      surface_point.x <= video_rect.x + video_rect.z &&
+      surface_point.y >= video_rect.y &&
+      surface_point.y <= video_rect.y + video_rect.w) {
+    vec2 frame_texcoord =
+        (surface_point - video_rect.xy) / video_rect.zw;
+    float y = 1.16438356 *
+              (texture2D(y_texture, frame_texcoord).r - 16.0 / 255.0);
+    vec2 uv =
+        texture2D(uv_texture, frame_texcoord).ra - vec2(0.5, 0.5);
+    rgb = clamp(vec3(y + 1.59602678 * uv.y,
+                     y - 0.39176229 * uv.x - 0.81296764 * uv.y,
+                     y + 2.01723214 * uv.x),
+                0.0, 1.0);
+  }
+  float coverage = 1.0;
+  if (corner_radius > 0.0) {
+    vec2 half_size = target_size * 0.5;
+    vec2 corner = abs(surface_point - half_size) -
+                  (half_size - vec2(corner_radius));
+    float distance_to_edge =
+        length(max(corner, vec2(0.0))) +
+        min(max(corner.x, corner.y), 0.0) - corner_radius;
+    coverage = clamp(0.5 - distance_to_edge, 0.0, 1.0);
+  }
+  gl_FragColor = vec4(rgb * coverage, coverage);
+}
+)glsl";
+
+  const auto *version = reinterpret_cast<const char *>(glGetString(GL_VERSION));
+  const bool is_gles = version && std::strstr(version, "OpenGL ES") != nullptr;
+  const char *vertex_source =
+      is_gles ? kGlesVertexShader : kDesktopVertexShader;
+  const char *fragment_source =
+      is_gles ? kGlesFragmentShader : kDesktopFragmentShader;
+
+  const GLuint vertex_shader =
+      CompileShader(impl_->gl, GL_VERTEX_SHADER, vertex_source);
+  const GLuint fragment_shader =
+      CompileShader(impl_->gl, GL_FRAGMENT_SHADER, fragment_source);
+  if (vertex_shader == 0 || fragment_shader == 0) {
+    if (vertex_shader != 0)
+      impl_->gl.delete_shader(vertex_shader);
+    if (fragment_shader != 0)
+      impl_->gl.delete_shader(fragment_shader);
+    return false;
+  }
+
+  impl_->program = impl_->gl.create_program();
+  impl_->gl.attach_shader(impl_->program, vertex_shader);
+  impl_->gl.attach_shader(impl_->program, fragment_shader);
+  impl_->gl.link_program(impl_->program);
+  impl_->gl.delete_shader(vertex_shader);
+  impl_->gl.delete_shader(fragment_shader);
+
+  GLint linked = GL_FALSE;
+  impl_->gl.get_program_iv(impl_->program, GL_LINK_STATUS, &linked);
+  if (linked != GL_TRUE) {
+    GLint log_length = 0;
+    impl_->gl.get_program_iv(impl_->program, GL_INFO_LOG_LENGTH, &log_length);
+    std::string log(static_cast<size_t>(std::max(log_length, 1)), '\0');
+    GLsizei written = 0;
+    impl_->gl.get_program_info_log(
+        impl_->program, static_cast<GLsizei>(log.size()), &written, log.data());
+    if (written >= 0 && static_cast<size_t>(written) < log.size()) {
+      log.resize(static_cast<size_t>(written));
+    }
+    LOG_ERROR("OpenGL NV12 program link failed: {}", log);
+    impl_->gl.delete_program(impl_->program);
+    impl_->ResetGlHandles();
+    return false;
+  }
+
+  impl_->position_location =
+      impl_->gl.get_attrib_location(impl_->program, "position");
+  impl_->texcoord_location =
+      impl_->gl.get_attrib_location(impl_->program, "texcoord");
+  impl_->y_texture_location =
+      impl_->gl.get_uniform_location(impl_->program, "y_texture");
+  impl_->uv_texture_location =
+      impl_->gl.get_uniform_location(impl_->program, "uv_texture");
+  impl_->target_size_location =
+      impl_->gl.get_uniform_location(impl_->program, "target_size");
+  impl_->video_rect_location =
+      impl_->gl.get_uniform_location(impl_->program, "video_rect");
+  impl_->corner_radius_location =
+      impl_->gl.get_uniform_location(impl_->program, "corner_radius");
+  impl_->video_enabled_location =
+      impl_->gl.get_uniform_location(impl_->program, "video_enabled");
+  if (impl_->position_location < 0 || impl_->texcoord_location < 0 ||
+      impl_->y_texture_location < 0 || impl_->uv_texture_location < 0 ||
+      impl_->target_size_location < 0 || impl_->video_rect_location < 0 ||
+      impl_->corner_radius_location < 0 ||
+      impl_->video_enabled_location < 0) {
+    LOG_ERROR("OpenGL NV12 program is missing required shader bindings");
+    impl_->gl.delete_program(impl_->program);
+    impl_->ResetGlHandles();
+    return false;
+  }
+
+  static constexpr GLfloat kVertices[] = {
+      -1.0f, 1.0f,  0.0f, 0.0f, // top-left
+      -1.0f, -1.0f, 0.0f, 1.0f, // bottom-left
+      1.0f,  1.0f,  1.0f, 0.0f, // top-right
+      1.0f,  -1.0f, 1.0f, 1.0f, // bottom-right
+  };
+  GLint previous_array_buffer = 0;
+  glGetIntegerv(GL_ARRAY_BUFFER_BINDING, &previous_array_buffer);
+  impl_->gl.gen_buffers(1, &impl_->vertex_buffer);
+  impl_->gl.bind_buffer(GL_ARRAY_BUFFER, impl_->vertex_buffer);
+  impl_->gl.buffer_data(GL_ARRAY_BUFFER, sizeof(kVertices), kVertices,
+                        GL_STATIC_DRAW);
+  impl_->gl.bind_buffer(GL_ARRAY_BUFFER,
+                        static_cast<GLuint>(previous_array_buffer));
+
+  GLint previous_active_texture = GL_TEXTURE0;
+  glGetIntegerv(GL_ACTIVE_TEXTURE, &previous_active_texture);
+  impl_->gl.active_texture(GL_TEXTURE0);
+  GLint previous_texture_0 = 0;
+  glGetIntegerv(GL_TEXTURE_BINDING_2D, &previous_texture_0);
+  impl_->gl.active_texture(GL_TEXTURE1);
+  GLint previous_texture_1 = 0;
+  glGetIntegerv(GL_TEXTURE_BINDING_2D, &previous_texture_1);
+  while (glGetError() != GL_NO_ERROR) {
+  }
+  glGenTextures(1, &impl_->y_texture);
+  glGenTextures(1, &impl_->uv_texture);
+  for (const auto [unit, texture] :
+       {std::pair{GL_TEXTURE0, impl_->y_texture},
+        std::pair{GL_TEXTURE1, impl_->uv_texture}}) {
+    impl_->gl.active_texture(unit);
+    glBindTexture(GL_TEXTURE_2D, texture);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+  }
+  impl_->gl.active_texture(GL_TEXTURE0);
+  glBindTexture(GL_TEXTURE_2D, static_cast<GLuint>(previous_texture_0));
+  impl_->gl.active_texture(GL_TEXTURE1);
+  glBindTexture(GL_TEXTURE_2D, static_cast<GLuint>(previous_texture_1));
+  impl_->gl.active_texture(static_cast<GLenum>(previous_active_texture));
+
+  const GLenum setup_error = glGetError();
+  if (impl_->program == 0 || impl_->vertex_buffer == 0 ||
+      impl_->y_texture == 0 || impl_->uv_texture == 0 ||
+      setup_error != GL_NO_ERROR) {
+    LOG_ERROR("OpenGL NV12 resource setup failed, error={}", setup_error);
+    Teardown();
+    return false;
+  }
+
+  impl_->ready.store(true, std::memory_order_release);
+  LOG_INFO("OpenGL NV12 underlay initialized ({})",
+           version ? version : "unknown OpenGL version");
+  return true;
+}
+
+void OpenGlVideoRenderer::Teardown() {
+  impl_->ready.store(false, std::memory_order_release);
+  if (impl_->y_texture != 0)
+    glDeleteTextures(1, &impl_->y_texture);
+  if (impl_->uv_texture != 0)
+    glDeleteTextures(1, &impl_->uv_texture);
+  if (impl_->vertex_buffer != 0 && impl_->gl.delete_buffers) {
+    impl_->gl.delete_buffers(1, &impl_->vertex_buffer);
+  }
+  if (impl_->program != 0 && impl_->gl.delete_program) {
+    impl_->gl.delete_program(impl_->program);
+  }
+  impl_->ResetGlHandles();
+}
+
+bool OpenGlVideoRenderer::IsReady() const {
+  return impl_->ready.load(std::memory_order_acquire);
+}
+
+bool OpenGlVideoRenderer::IsActive() const { return IsReady(); }
+
+bool OpenGlVideoRenderer::SetSelectedStream(std::string remote_id) {
+  std::lock_guard lock(impl_->frames->mutex);
+  if (impl_->frames->selected_stream == remote_id) {
+    return false;
+  }
+  impl_->frames->selected_stream = std::move(remote_id);
+  for (auto &slot : impl_->frames->slots) {
+    if (slot.use == SlotUse::pending &&
+        slot.remote_id != impl_->frames->selected_stream) {
+      slot.use = SlotUse::available;
+    }
+  }
+  return true;
+}
+
+void OpenGlVideoRenderer::DiscardStream(std::string_view remote_id) {
+  std::lock_guard lock(impl_->frames->mutex);
+  for (auto &slot : impl_->frames->slots) {
+    if (slot.remote_id == remote_id && slot.use != SlotUse::uploading) {
+      slot.valid = false;
+      slot.use = SlotUse::available;
+      slot.remote_id.clear();
+    }
+  }
+  if (impl_->frames->selected_stream == remote_id) {
+    impl_->frames->selected_stream.clear();
+  }
+}
+
+OpenGlVideoRenderer::SubmitResult
+OpenGlVideoRenderer::SubmitNv12(std::string_view remote_id,
+                                       const uint8_t *data, size_t size,
+                                       int width, int height) {
+  return SubmitNv12Internal(remote_id, data, size, width, height, true);
+}
+
+OpenGlVideoRenderer::SubmitResult
+OpenGlVideoRenderer::SubmitCachedNv12(std::string_view remote_id,
+                                             const uint8_t *data, size_t size,
+                                             int width, int height) {
+  return SubmitNv12Internal(remote_id, data, size, width, height, false);
+}
+
+OpenGlVideoRenderer::SubmitResult
+OpenGlVideoRenderer::SubmitNv12Internal(std::string_view remote_id,
+                                               const uint8_t *data, size_t size,
+                                               int width, int height,
+                                               bool replace_pending) {
+  if (!IsReady()) {
+    return SubmitResult::failed;
+  }
+  if (data == nullptr || width <= 0 || height <= 0 || (width & 1) != 0 ||
+      (height & 1) != 0) {
+    return SubmitResult::failed;
+  }
+  const size_t y_size = static_cast<size_t>(width) * height;
+  const size_t required_size = y_size + y_size / 2;
+  if (size < required_size) {
+    return SubmitResult::failed;
+  }
+
+  auto &frames = *impl_->frames;
+  std::lock_guard lock(frames.mutex);
+  if (frames.selected_stream != remote_id) {
+    return SubmitResult::not_selected;
+  }
+
+  FrameSlot *target = nullptr;
+  if (replace_pending) {
+    for (auto &slot : frames.slots) {
+      if (slot.use == SlotUse::pending) {
+        target = &slot;
+        break;
+      }
+    }
+  } else {
+    for (const auto &slot : frames.slots) {
+      if (slot.valid && slot.remote_id == remote_id &&
+          (slot.use == SlotUse::pending || slot.use == SlotUse::uploading)) {
+        return SubmitResult::dropped;
+      }
+    }
+  }
+  if (target == nullptr) {
+    uint64_t oldest_sequence = std::numeric_limits<uint64_t>::max();
+    for (auto &slot : frames.slots) {
+      if (slot.use != SlotUse::available) {
+        continue;
+      }
+      if (!slot.valid) {
+        target = &slot;
+        break;
+      }
+      if (slot.sequence < oldest_sequence) {
+        oldest_sequence = slot.sequence;
+        target = &slot;
+      }
+    }
+  }
+  if (target == nullptr) {
+    return SubmitResult::dropped;
+  }
+
+  target->bytes.resize(required_size);
+  std::memcpy(target->bytes.data(), data, required_size);
+  target->width = width;
+  target->height = height;
+  target->remote_id.assign(remote_id);
+  target->sequence = frames.next_sequence++;
+  target->use = SlotUse::pending;
+  target->valid = true;
+  return SubmitResult::submitted;
+}
+
+OpenGlVideoRenderer::RenderOutcome
+OpenGlVideoRenderer::RenderLatest(std::string_view remote_id,
+                                  int target_width, int target_height,
+                                  int top_inset_pixels,
+                                  int corner_radius_pixels) {
+  if (!IsReady() || target_width <= 0 || target_height <= 0) {
+    return {RenderResult::failed};
+  }
+
+  size_t slot_index = kFrameSlotCount;
+  uint64_t sequence = 0;
+  int source_width = 0;
+  int source_height = 0;
+  const unsigned char *frame_data = nullptr;
+  {
+    std::lock_guard lock(impl_->frames->mutex);
+    for (size_t index = 0; index < impl_->frames->slots.size(); ++index) {
+      const auto &slot = impl_->frames->slots[index];
+      if (slot.valid && slot.use == SlotUse::pending &&
+          slot.remote_id == remote_id &&
+          (slot_index == kFrameSlotCount || slot.sequence > sequence)) {
+        slot_index = index;
+        sequence = slot.sequence;
+      }
+    }
+    if (slot_index != kFrameSlotCount) {
+      auto &selected = impl_->frames->slots[slot_index];
+      selected.use = SlotUse::uploading;
+      source_width = selected.width;
+      source_height = selected.height;
+      frame_data = selected.bytes.data();
+      for (size_t index = 0; index < impl_->frames->slots.size(); ++index) {
+        auto &slot = impl_->frames->slots[index];
+        if (index != slot_index && slot.use == SlotUse::pending &&
+            slot.remote_id == remote_id) {
+          slot.use = SlotUse::available;
+        }
+      }
+    }
+  }
+
+  GLint previous_program = 0;
+  GLint previous_active_texture = GL_TEXTURE0;
+  GLint previous_array_buffer = 0;
+  GLint previous_unpack_alignment = 4;
+  GLint previous_viewport[4] = {};
+  GLint previous_scissor_box[4] = {};
+  GLfloat previous_clear_color[4] = {};
+  GLboolean previous_color_mask[4] = {};
+  glGetIntegerv(GL_CURRENT_PROGRAM, &previous_program);
+  glGetIntegerv(GL_ACTIVE_TEXTURE, &previous_active_texture);
+  glGetIntegerv(GL_ARRAY_BUFFER_BINDING, &previous_array_buffer);
+  glGetIntegerv(GL_UNPACK_ALIGNMENT, &previous_unpack_alignment);
+  glGetIntegerv(GL_VIEWPORT, previous_viewport);
+  glGetIntegerv(GL_SCISSOR_BOX, previous_scissor_box);
+  glGetFloatv(GL_COLOR_CLEAR_VALUE, previous_clear_color);
+  glGetBooleanv(GL_COLOR_WRITEMASK, previous_color_mask);
+  const bool blend_enabled = IsEnabled(GL_BLEND);
+  const bool cull_enabled = IsEnabled(GL_CULL_FACE);
+  const bool depth_enabled = IsEnabled(GL_DEPTH_TEST);
+  const bool scissor_enabled = IsEnabled(GL_SCISSOR_TEST);
+  const bool stencil_enabled = IsEnabled(GL_STENCIL_TEST);
+
+  impl_->gl.active_texture(GL_TEXTURE0);
+  GLint previous_texture_0 = 0;
+  glGetIntegerv(GL_TEXTURE_BINDING_2D, &previous_texture_0);
+  impl_->gl.active_texture(GL_TEXTURE1);
+  GLint previous_texture_1 = 0;
+  glGetIntegerv(GL_TEXTURE_BINDING_2D, &previous_texture_1);
+
+  const auto position_state = CaptureVertexAttrib(
+      impl_->gl, static_cast<GLuint>(impl_->position_location));
+  const auto texcoord_state = CaptureVertexAttrib(
+      impl_->gl, static_cast<GLuint>(impl_->texcoord_location));
+
+  glDisable(GL_BLEND);
+  glDisable(GL_CULL_FACE);
+  glDisable(GL_DEPTH_TEST);
+  glDisable(GL_SCISSOR_TEST);
+  glDisable(GL_STENCIL_TEST);
+  glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
+  glViewport(0, 0, target_width, target_height);
+  // The Slint items above this underlay are transparent around the custom
+  // window corners. Keep those pixels transparent so the compositor can show
+  // the desktop instead of an opaque black framebuffer clear.
+  glClearColor(0.0f, 0.0f, 0.0f, 0.0f);
+  glClear(GL_COLOR_BUFFER_BIT);
+
+  bool upload_succeeded = true;
+  if (slot_index != kFrameSlotCount) {
+    while (glGetError() != GL_NO_ERROR) {
+    }
+    const size_t y_size = static_cast<size_t>(source_width) * source_height;
+    glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+    impl_->gl.active_texture(GL_TEXTURE0);
+    glBindTexture(GL_TEXTURE_2D, impl_->y_texture);
+    impl_->gl.active_texture(GL_TEXTURE1);
+    glBindTexture(GL_TEXTURE_2D, impl_->uv_texture);
+    if (impl_->texture_width != source_width ||
+        impl_->texture_height != source_height) {
+      impl_->gl.active_texture(GL_TEXTURE0);
+      glTexImage2D(GL_TEXTURE_2D, 0, GL_LUMINANCE, source_width, source_height,
+                   0, GL_LUMINANCE, GL_UNSIGNED_BYTE, frame_data);
+      impl_->gl.active_texture(GL_TEXTURE1);
+      glTexImage2D(GL_TEXTURE_2D, 0, GL_LUMINANCE_ALPHA, source_width / 2,
+                   source_height / 2, 0, GL_LUMINANCE_ALPHA, GL_UNSIGNED_BYTE,
+                   frame_data + y_size);
+    } else {
+      impl_->gl.active_texture(GL_TEXTURE0);
+      glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, source_width, source_height,
+                      GL_LUMINANCE, GL_UNSIGNED_BYTE, frame_data);
+      impl_->gl.active_texture(GL_TEXTURE1);
+      glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, source_width / 2,
+                      source_height / 2, GL_LUMINANCE_ALPHA, GL_UNSIGNED_BYTE,
+                      frame_data + y_size);
+    }
+    const GLenum upload_error = glGetError();
+    upload_succeeded = upload_error == GL_NO_ERROR;
+    if (upload_succeeded) {
+      impl_->texture_width = source_width;
+      impl_->texture_height = source_height;
+      impl_->uploaded_stream.assign(remote_id);
+      impl_->uploaded_sequence = sequence;
+    } else {
+      LOG_WARN("OpenGL NV12 texture upload failed, error={}", upload_error);
+    }
+  }
+
+  {
+    std::lock_guard lock(impl_->frames->mutex);
+    if (slot_index != kFrameSlotCount) {
+      auto &slot = impl_->frames->slots[slot_index];
+      if (slot.sequence == sequence && slot.use == SlotUse::uploading) {
+        slot.use = SlotUse::available;
+      }
+    }
+  }
+
+  const int content_y = std::clamp(top_inset_pixels, 0, target_height);
+  const int content_height = target_height - content_y;
+  const bool has_video =
+      upload_succeeded && impl_->uploaded_stream == remote_id &&
+      impl_->texture_width > 0 && impl_->texture_height > 0 &&
+      content_height > 0;
+  int video_x = 0;
+  int video_y = content_y;
+  int video_width = target_width;
+  int video_height = content_height;
+  if (has_video) {
+    source_width = impl_->texture_width;
+    source_height = impl_->texture_height;
+    sequence = impl_->uploaded_sequence;
+    const double source_aspect =
+        static_cast<double>(source_width) / source_height;
+    const double target_aspect =
+        static_cast<double>(target_width) / content_height;
+    if (source_aspect > target_aspect) {
+      video_height =
+          std::max(1, static_cast<int>(target_width / source_aspect + 0.5));
+      video_y = content_y + (content_height - video_height) / 2;
+    } else {
+      video_width =
+          std::max(1, static_cast<int>(content_height * source_aspect + 0.5));
+      video_x = (target_width - video_width) / 2;
+    }
+  }
+
+  while (glGetError() != GL_NO_ERROR) {
+  }
+  impl_->gl.use_program(impl_->program);
+  impl_->gl.active_texture(GL_TEXTURE0);
+  glBindTexture(GL_TEXTURE_2D, impl_->y_texture);
+  impl_->gl.uniform_1i(impl_->y_texture_location, 0);
+  impl_->gl.active_texture(GL_TEXTURE1);
+  glBindTexture(GL_TEXTURE_2D, impl_->uv_texture);
+  impl_->gl.uniform_1i(impl_->uv_texture_location, 1);
+  impl_->gl.uniform_2f(impl_->target_size_location,
+                       static_cast<GLfloat>(target_width),
+                       static_cast<GLfloat>(target_height));
+  impl_->gl.uniform_4f(
+      impl_->video_rect_location, static_cast<GLfloat>(video_x),
+      static_cast<GLfloat>(video_y), static_cast<GLfloat>(video_width),
+      static_cast<GLfloat>(video_height));
+  impl_->gl.uniform_1f(
+      impl_->corner_radius_location,
+      static_cast<GLfloat>(std::clamp(
+          corner_radius_pixels, 0, std::min(target_width, target_height) / 2)));
+  impl_->gl.uniform_1f(impl_->video_enabled_location, has_video ? 1.0f : 0.0f);
+  impl_->gl.bind_buffer(GL_ARRAY_BUFFER, impl_->vertex_buffer);
+  impl_->gl.vertex_attrib_pointer(
+      static_cast<GLuint>(impl_->position_location), 2, GL_FLOAT, GL_FALSE,
+      4 * static_cast<GLsizei>(sizeof(GLfloat)), nullptr);
+  impl_->gl.vertex_attrib_pointer(
+      static_cast<GLuint>(impl_->texcoord_location), 2, GL_FLOAT, GL_FALSE,
+      4 * static_cast<GLsizei>(sizeof(GLfloat)),
+      reinterpret_cast<const void *>(2 * sizeof(GLfloat)));
+  impl_->gl.enable_vertex_attrib_array(
+      static_cast<GLuint>(impl_->position_location));
+  impl_->gl.enable_vertex_attrib_array(
+      static_cast<GLuint>(impl_->texcoord_location));
+  glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
+  const GLenum draw_error = glGetError();
+  RenderOutcome outcome{
+      !upload_succeeded || draw_error != GL_NO_ERROR
+          ? RenderResult::failed
+          : has_video ? RenderResult::rendered : RenderResult::empty,
+      has_video ? source_width : 0, has_video ? source_height : 0,
+      has_video ? sequence : 0};
+
+  RestoreVertexAttrib(impl_->gl, static_cast<GLuint>(impl_->position_location),
+                      position_state);
+  RestoreVertexAttrib(impl_->gl, static_cast<GLuint>(impl_->texcoord_location),
+                      texcoord_state);
+  impl_->gl.bind_buffer(GL_ARRAY_BUFFER,
+                        static_cast<GLuint>(previous_array_buffer));
+  impl_->gl.active_texture(GL_TEXTURE0);
+  glBindTexture(GL_TEXTURE_2D, static_cast<GLuint>(previous_texture_0));
+  impl_->gl.active_texture(GL_TEXTURE1);
+  glBindTexture(GL_TEXTURE_2D, static_cast<GLuint>(previous_texture_1));
+  impl_->gl.active_texture(static_cast<GLenum>(previous_active_texture));
+  impl_->gl.use_program(static_cast<GLuint>(previous_program));
+  glPixelStorei(GL_UNPACK_ALIGNMENT, previous_unpack_alignment);
+  glViewport(previous_viewport[0], previous_viewport[1], previous_viewport[2],
+             previous_viewport[3]);
+  glScissor(previous_scissor_box[0], previous_scissor_box[1],
+            previous_scissor_box[2], previous_scissor_box[3]);
+  glClearColor(previous_clear_color[0], previous_clear_color[1],
+               previous_clear_color[2], previous_clear_color[3]);
+  glColorMask(previous_color_mask[0], previous_color_mask[1],
+              previous_color_mask[2], previous_color_mask[3]);
+  RestoreCapability(GL_BLEND, blend_enabled);
+  RestoreCapability(GL_CULL_FACE, cull_enabled);
+  RestoreCapability(GL_DEPTH_TEST, depth_enabled);
+  RestoreCapability(GL_SCISSOR_TEST, scissor_enabled);
+  RestoreCapability(GL_STENCIL_TEST, stencil_enabled);
+  const GLenum restore_error = glGetError();
+  if (restore_error != GL_NO_ERROR) {
+    LOG_WARN("OpenGL NV12 state restoration failed, error={}", restore_error);
+    if (outcome.result == RenderResult::rendered) {
+      outcome.result = RenderResult::failed;
+    }
+  }
+  return outcome;
+}
+
+bool OpenGlVideoRenderer::CopyLatestNv12(
+    std::string_view remote_id, std::vector<unsigned char> *output, int *width,
+    int *height) const {
+  if (!output || !width || !height) {
+    return false;
+  }
+  std::lock_guard lock(impl_->frames->mutex);
+  const FrameSlot *newest = nullptr;
+  for (const auto &slot : impl_->frames->slots) {
+    if (slot.valid && slot.remote_id == remote_id &&
+        (!newest || slot.sequence > newest->sequence)) {
+      newest = &slot;
+    }
+  }
+  if (!newest || newest->bytes.empty()) {
+    return false;
+  }
+  *output = newest->bytes;
+  *width = newest->width;
+  *height = newest->height;
+  return true;
+}
+
+} // namespace crossdesk

apps/desktop/src/platform/common/gui/opengl_video_renderer.h

@@ -0,0 +1,70 @@
+#ifndef CROSSDESK_GUI_PLATFORM_OPENGL_VIDEO_RENDERER_H_
+#define CROSSDESK_GUI_PLATFORM_OPENGL_VIDEO_RENDERER_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "platform/video_renderer.h"
+
+namespace crossdesk {
+
+// NV12 underlay for Slint's FemtoVG OpenGL renderer on Windows and Linux.
+// MiniRTC submits tightly packed CPU NV12 frames from its decode callback
+// thread. The Slint UI thread uploads the newest frame as Y and UV textures and
+// performs color conversion and scaling in a fragment shader before Slint
+// draws its overlay.
+class OpenGlVideoRenderer final : public VideoRenderer {
+public:
+  OpenGlVideoRenderer();
+  ~OpenGlVideoRenderer() override;
+
+  OpenGlVideoRenderer(const OpenGlVideoRenderer &) = delete;
+  OpenGlVideoRenderer &operator=(const OpenGlVideoRenderer &) = delete;
+
+  // These methods must run while Slint's OpenGL context is current, from the
+  // RenderingSetup and RenderingTeardown notifier states respectively.
+  bool Setup();
+  void Teardown();
+  bool IsReady() const override;
+  bool IsActive() const override;
+
+  // Only the selected stream is queued for upload. Frames for other tabs are
+  // retained by GuiRuntime at a throttled rate for thumbnail/tab restoration.
+  bool SetSelectedStream(std::string remote_id) override;
+  void DiscardStream(std::string_view remote_id) override;
+
+  // Thread-safe; called from MiniRTC's decode callback thread.
+  SubmitResult SubmitNv12(std::string_view remote_id, const uint8_t *data,
+                          size_t size, int width, int height) override;
+  SubmitResult SubmitCachedNv12(std::string_view remote_id, const uint8_t *data,
+                                size_t size, int width, int height) override;
+
+  // Draws below Slint while its OpenGL context is current. All dimensions are
+  // physical pixels in the window client area. corner_radius_pixels clips the
+  // underlay to Slint's custom rounded window surface.
+  RenderOutcome RenderLatest(std::string_view remote_id, int target_width,
+                             int target_height, int top_inset_pixels,
+                             int corner_radius_pixels);
+
+  // Used during disconnect cleanup so thumbnail generation does not require a
+  // second per-frame CPU copy during normal playback.
+  bool CopyLatestNv12(std::string_view remote_id,
+                      std::vector<unsigned char> *output, int *width,
+                      int *height) const override;
+
+private:
+  SubmitResult SubmitNv12Internal(std::string_view remote_id,
+                                  const uint8_t *data, size_t size, int width,
+                                  int height, bool replace_pending);
+
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+} // namespace crossdesk
+
+#endif // CROSSDESK_GUI_PLATFORM_OPENGL_VIDEO_RENDERER_H_

apps/desktop/src/platform/common/gui/service_status_runtime.cpp

@@ -0,0 +1,42 @@
+#include "runtime/gui_runtime.h"
+
+namespace crossdesk {
+
+void GuiRuntime::ResetRemoteServiceStatus(RemoteSession& props) {
+  props.remote_service_status_received_ = false;
+  props.remote_service_available_ = false;
+  props.remote_interactive_stage_.clear();
+}
+
+void GuiRuntime::ApplyRemoteServiceStatus(RemoteSession& props,
+                                          const ServiceStatus& status) {
+  props.remote_service_status_received_ = true;
+  props.remote_service_available_ = status.available;
+  props.remote_interactive_stage_ = status.interactive_stage;
+}
+
+GuiRuntime::RemoteUnlockState GuiRuntime::GetRemoteUnlockState(
+    const RemoteSession& props) const {
+  if (!props.remote_service_status_received_) {
+    return RemoteUnlockState::none;
+  }
+  if (!props.remote_service_available_) {
+    return RemoteUnlockState::service_unavailable;
+  }
+  if (props.remote_interactive_stage_ == "credential-ui") {
+    return RemoteUnlockState::credential_ui;
+  }
+  if (props.remote_interactive_stage_ == "lock-screen") {
+    return RemoteUnlockState::lock_screen;
+  }
+  if (props.remote_interactive_stage_ == "secure-desktop") {
+    return RemoteUnlockState::secure_desktop;
+  }
+  return RemoteUnlockState::none;
+}
+
+#if !defined(_WIN32)
+void GuiRuntime::HandleWindowsServiceIntegration() {}
+#endif
+
+}  // namespace crossdesk

apps/desktop/src/platform/common/gui/video_renderer_factory_opengl.cpp

@@ -0,0 +1,12 @@
+#include <memory>
+
+#include "platform/common/gui/opengl_video_renderer.h"
+#include "platform/video_renderer.h"
+
+namespace crossdesk {
+
+std::unique_ptr<VideoRenderer> CreateVideoRenderer() {
+  return std::make_unique<OpenGlVideoRenderer>();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/common/input/windows_key_metadata.h

@@ -0,0 +1,89 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-05-07
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _WINDOWS_KEY_METADATA_H_
+#define _WINDOWS_KEY_METADATA_H_
+
+#include <cstdint>
+
+namespace crossdesk {
+
+inline bool LookupWindowsKeyMetadataFromVk(int key_code,
+                                           uint32_t* scan_code_out,
+                                           bool* extended_out) {
+  if (scan_code_out == nullptr || extended_out == nullptr) {
+    return false;
+  }
+
+  switch (key_code) {
+    case 0x21:  // Page Up
+      *scan_code_out = 0x49;
+      *extended_out = true;
+      return true;
+    case 0x22:  // Page Down
+      *scan_code_out = 0x51;
+      *extended_out = true;
+      return true;
+    case 0x23:  // End
+      *scan_code_out = 0x4F;
+      *extended_out = true;
+      return true;
+    case 0x24:  // Home
+      *scan_code_out = 0x47;
+      *extended_out = true;
+      return true;
+    case 0x25:  // Left Arrow
+      *scan_code_out = 0x4B;
+      *extended_out = true;
+      return true;
+    case 0x26:  // Up Arrow
+      *scan_code_out = 0x48;
+      *extended_out = true;
+      return true;
+    case 0x27:  // Right Arrow
+      *scan_code_out = 0x4D;
+      *extended_out = true;
+      return true;
+    case 0x28:  // Down Arrow
+      *scan_code_out = 0x50;
+      *extended_out = true;
+      return true;
+    case 0x2D:  // Insert
+      *scan_code_out = 0x52;
+      *extended_out = true;
+      return true;
+    case 0x2E:  // Delete
+      *scan_code_out = 0x53;
+      *extended_out = true;
+      return true;
+    case 0x6F:  // Numpad /
+      *scan_code_out = 0x35;
+      *extended_out = true;
+      return true;
+    case 0xA3:  // Right Ctrl
+      *scan_code_out = 0x1D;
+      *extended_out = true;
+      return true;
+    case 0xA5:  // Right Alt
+      *scan_code_out = 0x38;
+      *extended_out = true;
+      return true;
+    case 0x5B:  // Left Win
+      *scan_code_out = 0x5B;
+      *extended_out = true;
+      return true;
+    case 0x5C:  // Right Win
+      *scan_code_out = 0x5C;
+      *extended_out = true;
+      return true;
+    default:
+      return false;
+  }
+}
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/common/posix_daemon_backend.cpp

@@ -0,0 +1,56 @@
+#include "platform/daemon_backend.h"
+
+#include <errno.h>
+#include <signal.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <chrono>
+#include <thread>
+
+namespace crossdesk::platform {
+
+volatile std::sig_atomic_t g_daemon_stop_requested = 0;
+
+void ResetDaemonStop() { g_daemon_stop_requested = 0; }
+
+void RequestDaemonStop() { g_daemon_stop_requested = 1; }
+
+bool DaemonStopRequested() { return g_daemon_stop_requested != 0; }
+
+DaemonChildResult RunDaemonChild(const std::string& executable_path,
+                                 const std::function<bool()>& keep_running) {
+  DaemonChildResult result;
+  const pid_t child = fork();
+  if (child == 0) {
+    execl(executable_path.c_str(), executable_path.c_str(), "--child",
+          nullptr);
+    _exit(1);
+  }
+  if (child < 0) return result;
+
+  result.started = true;
+  int status = 0;
+  pid_t waited = -1;
+  while (keep_running()) {
+    waited = waitpid(child, &status, WNOHANG);
+    if (waited == child || (waited < 0 && errno != EINTR)) break;
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+  }
+  if (!keep_running() && waited != child) {
+    kill(child, SIGTERM);
+    waited = waitpid(child, &status, 0);
+  }
+  if (waited < 0) return result;
+
+  if (WIFEXITED(status)) {
+    result.exit_code = WEXITSTATUS(status);
+    result.normal_exit = result.exit_code == 0;
+  } else if (WIFSIGNALED(status)) {
+    result.terminated_by_signal = true;
+    result.exit_code = WTERMSIG(status);
+  }
+  return result;
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/daemon_backend.h

@@ -0,0 +1,29 @@
+#ifndef CROSSDESK_PLATFORM_DAEMON_BACKEND_H_
+#define CROSSDESK_PLATFORM_DAEMON_BACKEND_H_
+
+#include <csignal>
+#include <functional>
+#include <string>
+
+namespace crossdesk::platform {
+
+extern volatile std::sig_atomic_t g_daemon_stop_requested;
+
+struct DaemonChildResult {
+  bool started = false;
+  bool normal_exit = false;
+  bool terminated_by_signal = false;
+  int exit_code = 0;
+};
+
+void ResetDaemonStop();
+void RequestDaemonStop();
+bool DaemonStopRequested();
+bool PrepareDaemon();
+std::string GetDaemonExecutablePath();
+DaemonChildResult RunDaemonChild(const std::string& executable_path,
+                                 const std::function<bool()>& keep_running);
+
+}  // namespace crossdesk::platform
+
+#endif  // CROSSDESK_PLATFORM_DAEMON_BACKEND_H_

apps/desktop/src/platform/linux/autostart.cpp

@@ -0,0 +1,65 @@
+#include "platform/autostart_backend.h"
+
+#include <limits.h>
+#include <unistd.h>
+
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+
+namespace crossdesk::platform {
+namespace {
+
+std::filesystem::path AutostartPath(const std::string& app_name) {
+  const char* home = std::getenv("HOME");
+  if (!home || !home[0]) return {};
+  return std::filesystem::path(home) / ".config" / "autostart" /
+         (app_name + ".desktop");
+}
+
+}  // namespace
+
+std::string GetAutostartExecutablePath() {
+  char path[PATH_MAX] = {};
+  const ssize_t count = readlink("/proc/self/exe", path, sizeof(path) - 1);
+  return count > 0 ? std::string(path, static_cast<size_t>(count))
+                   : std::string();
+}
+
+bool EnableAutostart(const std::string& app_name,
+                     const std::string& executable_path) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  if (path.empty()) return false;
+
+  std::error_code error;
+  std::filesystem::create_directories(path.parent_path(), error);
+  if (error) return false;
+
+  std::ofstream file(path);
+  if (!file.is_open()) return false;
+  file << "[Desktop Entry]\n"
+       << "Type=Application\n"
+       << "Exec=" << executable_path << "\n"
+       << "Hidden=false\n"
+       << "NoDisplay=false\n"
+       << "X-GNOME-Autostart-enabled=true\n"
+       << "Terminal=false\n"
+       << "StartupNotify=false\n"
+       << "Name=" << app_name << "\n";
+  file.close();
+  return file.good();
+}
+
+bool DisableAutostart(const std::string& app_name) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  if (path.empty()) return false;
+  std::error_code error;
+  return std::filesystem::remove(path, error) && !error;
+}
+
+bool IsAutostartEnabled(const std::string& app_name) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  return !path.empty() && std::filesystem::is_regular_file(path);
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/linux/clipboard.cpp

@@ -0,0 +1,202 @@
+#include "clipboard.h"
+
+#include <X11/Xatom.h>
+#include <X11/Xlib.h>
+#include <X11/extensions/Xfixes.h>
+
+#include <chrono>
+#include <climits>
+#include <string>
+#include <thread>
+
+#include "platform/clipboard_backend.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+std::string Clipboard::GetText() {
+  Display* display = XOpenDisplay(nullptr);
+  if (!display) {
+    LOG_ERROR("Clipboard::GetText: failed to open X display");
+    return {};
+  }
+
+  Window owner = XGetSelectionOwner(display, XA_PRIMARY);
+  if (owner == None) {
+    owner =
+        XGetSelectionOwner(display, XInternAtom(display, "CLIPBOARD", False));
+    if (owner == None) {
+      XCloseDisplay(display);
+      return {};
+    }
+  }
+
+  Atom selection = XA_PRIMARY;
+  Atom target = XInternAtom(display, "UTF8_STRING", False);
+  if (target == None) target = XA_STRING;
+  const Window window = XCreateSimpleWindow(
+      display, DefaultRootWindow(display), 0, 0, 1, 1, 0, 0, 0);
+  XSelectInput(display, window, PropertyChangeMask);
+  XConvertSelection(display, selection, target, XA_PRIMARY, window,
+                    CurrentTime);
+
+  std::string result;
+  bool done = false;
+  while (!done) {
+    XEvent event = {};
+    XNextEvent(display, &event);
+    if (event.type != SelectionNotify) continue;
+    if (event.xselection.property == None) {
+      if (selection == XA_PRIMARY) {
+        selection = XInternAtom(display, "CLIPBOARD", False);
+        XConvertSelection(display, selection, target, XA_PRIMARY, window,
+                          CurrentTime);
+        continue;
+      }
+      break;
+    }
+
+    Atom actual_type = None;
+    int actual_format = 0;
+    unsigned long item_count = 0;
+    unsigned long bytes_after = 0;
+    unsigned char* data = nullptr;
+    if (XGetWindowProperty(display, window, XA_PRIMARY, 0, LONG_MAX / 4,
+                           False, AnyPropertyType, &actual_type,
+                           &actual_format, &item_count, &bytes_after,
+                           &data) == Success) {
+      if (data) {
+        result.assign(reinterpret_cast<char*>(data), item_count);
+        XFree(data);
+      }
+      done = true;
+    }
+  }
+
+  XDestroyWindow(display, window);
+  XCloseDisplay(display);
+  return result;
+}
+
+bool Clipboard::SetText(const std::string& text) {
+  Display* display = XOpenDisplay(nullptr);
+  if (!display) {
+    LOG_ERROR("Clipboard::SetText: failed to open X display");
+    return false;
+  }
+
+  const Window window = XCreateSimpleWindow(
+      display, DefaultRootWindow(display), 0, 0, 1, 1, 0, 0, 0);
+  const Atom clipboard = XInternAtom(display, "CLIPBOARD", False);
+  const Atom utf8 = XInternAtom(display, "UTF8_STRING", False);
+  const Atom targets = XInternAtom(display, "TARGETS", False);
+  XSetSelectionOwner(display, clipboard, window, CurrentTime);
+  if (XGetSelectionOwner(display, clipboard) != window) {
+    XDestroyWindow(display, window);
+    XCloseDisplay(display);
+    return false;
+  }
+
+  XChangeProperty(display, window, XA_PRIMARY, utf8, 8, PropModeReplace,
+                  reinterpret_cast<const unsigned char*>(text.data()),
+                  static_cast<int>(text.size()));
+  while (true) {
+    XEvent event = {};
+    XNextEvent(display, &event);
+    if (event.type == SelectionClear) break;
+    if (event.type != SelectionRequest) continue;
+
+    const XSelectionRequestEvent& request = event.xselectionrequest;
+    XSelectionEvent response = {};
+    response.type = SelectionNotify;
+    response.display = request.display;
+    response.requestor = request.requestor;
+    response.selection = request.selection;
+    response.time = request.time;
+    response.target = request.target;
+    response.property = request.property;
+    if (request.target == targets) {
+      Atom supported[] = {utf8, XA_STRING, targets};
+      XChangeProperty(display, request.requestor, request.property, XA_ATOM,
+                      32, PropModeReplace,
+                      reinterpret_cast<unsigned char*>(supported), 3);
+    } else if (request.target == utf8 || request.target == XA_STRING) {
+      XChangeProperty(display, request.requestor, request.property,
+                      request.target, 8, PropModeReplace,
+                      reinterpret_cast<const unsigned char*>(text.data()),
+                      static_cast<int>(text.size()));
+    } else {
+      response.property = None;
+    }
+    XSendEvent(display, request.requestor, False, 0,
+               reinterpret_cast<XEvent*>(&response));
+    XSync(display, False);
+  }
+
+  XDestroyWindow(display, window);
+  XCloseDisplay(display);
+  return true;
+}
+
+bool Clipboard::HasText() {
+  Display* display = XOpenDisplay(nullptr);
+  if (!display) return false;
+  const Atom clipboard = XInternAtom(display, "CLIPBOARD", False);
+  Window owner = XGetSelectionOwner(display, clipboard);
+  if (owner == None) owner = XGetSelectionOwner(display, XA_PRIMARY);
+  XCloseDisplay(display);
+  return owner != None;
+}
+
+namespace platform {
+
+void RunClipboardMonitor(int check_interval_ms) {
+  Display* display = XOpenDisplay(nullptr);
+  if (!display) {
+    LOG_ERROR("Failed to open X display for clipboard monitoring");
+    return;
+  }
+
+  int event_base = 0;
+  int error_base = 0;
+  if (!XFixesQueryExtension(display, &event_base, &error_base)) {
+    LOG_WARN("XFixes extension not available, falling back to polling");
+    XCloseDisplay(display);
+    while (ClipboardMonitoring()) {
+      std::this_thread::sleep_for(
+          std::chrono::milliseconds(check_interval_ms > 0 ? check_interval_ms
+                                                           : 100));
+      if (ClipboardMonitoring()) HandleClipboardChange();
+    }
+    return;
+  }
+
+  const Atom clipboard = XInternAtom(display, "CLIPBOARD", False);
+  const Window event_window = XCreateSimpleWindow(
+      display, DefaultRootWindow(display), 0, 0, 1, 1, 0, 0, 0);
+  XFixesSelectSelectionInput(display, event_window, clipboard,
+                             XFixesSetSelectionOwnerNotifyMask |
+                                 XFixesSelectionWindowDestroyNotifyMask |
+                                 XFixesSelectionClientCloseNotifyMask);
+  LOG_INFO("Clipboard event monitoring started (Linux XFixes)");
+
+  while (ClipboardMonitoring()) {
+    while (ClipboardMonitoring() && XPending(display) > 0) {
+      XEvent event = {};
+      XNextEvent(display, &event);
+      if (event.type == event_base + XFixesSelectionNotify) {
+        HandleClipboardChange();
+      }
+    }
+    std::this_thread::sleep_for(std::chrono::milliseconds(20));
+  }
+
+  XFixesSelectSelectionInput(display, event_window, clipboard, 0);
+  XDestroyWindow(display, event_window);
+  XCloseDisplay(display);
+}
+
+void WakeClipboardMonitor() {}
+
+}  // namespace platform
+}  // namespace crossdesk

apps/desktop/src/platform/linux/common/linux_cursor_shape.cpp

@@ -0,0 +1,404 @@
+#include "linux_cursor_shape.h"
+
+#include <remote_action.h>
+
+#include <algorithm>
+#include <array>
+#include <cctype>
+#include <cmath>
+#include <cstring>
+#include <limits>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+#if defined(__linux__) && !defined(__APPLE__)
+#include <X11/Xcursor/Xcursor.h>
+#include <X11/Xlib.h>
+#endif
+
+namespace crossdesk {
+namespace {
+
+constexpr LinuxCursorAlias kCursorAliases[] = {
+    {"help", RemoteCursorShape::help},
+    {"question-arrow", RemoteCursorShape::help},
+    {"left-ptr-help", RemoteCursorShape::help},
+    {"whats-this", RemoteCursorShape::help},
+    {"dnd-ask", RemoteCursorShape::help},
+    {"pointer", RemoteCursorShape::pointer},
+    {"hand", RemoteCursorShape::pointer},
+    {"hand1", RemoteCursorShape::pointer},
+    {"hand2", RemoteCursorShape::pointer},
+    {"link", RemoteCursorShape::pointer},
+    {"pointing-hand", RemoteCursorShape::pointer},
+    {"progress", RemoteCursorShape::progress},
+    {"left-ptr-watch", RemoteCursorShape::progress},
+    {"half-busy", RemoteCursorShape::progress},
+    {"wait", RemoteCursorShape::wait},
+    {"watch", RemoteCursorShape::wait},
+    {"crosshair", RemoteCursorShape::crosshair},
+    {"cross", RemoteCursorShape::crosshair},
+    {"cross-reverse", RemoteCursorShape::crosshair},
+    {"tcross", RemoteCursorShape::crosshair},
+    {"cell", RemoteCursorShape::crosshair},
+    {"plus", RemoteCursorShape::crosshair},
+    {"target", RemoteCursorShape::crosshair},
+    {"dotbox", RemoteCursorShape::crosshair},
+    {"dot-box-mask", RemoteCursorShape::crosshair},
+    {"text", RemoteCursorShape::text},
+    {"xterm", RemoteCursorShape::text},
+    {"ibeam", RemoteCursorShape::text},
+    {"vertical-text", RemoteCursorShape::text},
+    {"alias", RemoteCursorShape::alias},
+    {"dnd-link", RemoteCursorShape::alias},
+    {"copy", RemoteCursorShape::copy},
+    {"dnd-copy", RemoteCursorShape::copy},
+    {"move", RemoteCursorShape::move},
+    {"fleur", RemoteCursorShape::move},
+    {"size-all", RemoteCursorShape::move},
+    {"all-scroll", RemoteCursorShape::move},
+    {"dnd-move", RemoteCursorShape::move},
+    {"no-drop", RemoteCursorShape::no_drop},
+    {"dnd-no-drop", RemoteCursorShape::no_drop},
+    {"dnd-none", RemoteCursorShape::no_drop},
+    {"not-allowed", RemoteCursorShape::not_allowed},
+    {"forbidden", RemoteCursorShape::not_allowed},
+    {"crossed-circle", RemoteCursorShape::not_allowed},
+    {"circle", RemoteCursorShape::not_allowed},
+    {"pirate", RemoteCursorShape::not_allowed},
+    {"grab", RemoteCursorShape::grab},
+    {"openhand", RemoteCursorShape::grab},
+    {"open-hand", RemoteCursorShape::grab},
+    {"grabbing", RemoteCursorShape::grabbing},
+    {"closedhand", RemoteCursorShape::grabbing},
+    {"closed-hand", RemoteCursorShape::grabbing},
+    {"col-resize", RemoteCursorShape::col_resize},
+    {"row-resize", RemoteCursorShape::row_resize},
+    {"n-resize", RemoteCursorShape::n_resize},
+    {"top-side", RemoteCursorShape::n_resize},
+    {"top-tee", RemoteCursorShape::n_resize},
+    {"sb-up-arrow", RemoteCursorShape::n_resize},
+    {"e-resize", RemoteCursorShape::e_resize},
+    {"right-side", RemoteCursorShape::e_resize},
+    {"right-tee", RemoteCursorShape::e_resize},
+    {"sb-right-arrow", RemoteCursorShape::e_resize},
+    {"s-resize", RemoteCursorShape::s_resize},
+    {"bottom-side", RemoteCursorShape::s_resize},
+    {"bottom-tee", RemoteCursorShape::s_resize},
+    {"sb-down-arrow", RemoteCursorShape::s_resize},
+    {"w-resize", RemoteCursorShape::w_resize},
+    {"left-side", RemoteCursorShape::w_resize},
+    {"left-tee", RemoteCursorShape::w_resize},
+    {"sb-left-arrow", RemoteCursorShape::w_resize},
+    {"ne-resize", RemoteCursorShape::ne_resize},
+    {"top-right-corner", RemoteCursorShape::ne_resize},
+    {"ur-angle", RemoteCursorShape::ne_resize},
+    {"nw-resize", RemoteCursorShape::nw_resize},
+    {"top-left-corner", RemoteCursorShape::nw_resize},
+    {"ul-angle", RemoteCursorShape::nw_resize},
+    {"se-resize", RemoteCursorShape::se_resize},
+    {"bottom-right-corner", RemoteCursorShape::se_resize},
+    {"lr-angle", RemoteCursorShape::se_resize},
+    {"sw-resize", RemoteCursorShape::sw_resize},
+    {"bottom-left-corner", RemoteCursorShape::sw_resize},
+    {"ll-angle", RemoteCursorShape::sw_resize},
+    {"ew-resize", RemoteCursorShape::ew_resize},
+    {"sb-h-double-arrow", RemoteCursorShape::ew_resize},
+    {"h-double-arrow", RemoteCursorShape::ew_resize},
+    {"size-hor", RemoteCursorShape::ew_resize},
+    {"split-h", RemoteCursorShape::ew_resize},
+    {"exchange", RemoteCursorShape::ew_resize},
+    {"ns-resize", RemoteCursorShape::ns_resize},
+    {"sb-v-double-arrow", RemoteCursorShape::ns_resize},
+    {"v-double-arrow", RemoteCursorShape::ns_resize},
+    {"double-arrow", RemoteCursorShape::ns_resize},
+    {"size-ver", RemoteCursorShape::ns_resize},
+    {"split-v", RemoteCursorShape::ns_resize},
+    {"nesw-resize", RemoteCursorShape::nesw_resize},
+    {"fd-double-arrow", RemoteCursorShape::nesw_resize},
+    {"size-bdiag", RemoteCursorShape::nesw_resize},
+    {"nwse-resize", RemoteCursorShape::nwse_resize},
+    {"bd-double-arrow", RemoteCursorShape::nwse_resize},
+    {"size-fdiag", RemoteCursorShape::nwse_resize},
+    {"default", RemoteCursorShape::default_cursor},
+    {"left-ptr", RemoteCursorShape::default_cursor},
+    {"left-arrow", RemoteCursorShape::default_cursor},
+    {"arrow", RemoteCursorShape::default_cursor},
+    {"top-left-arrow", RemoteCursorShape::default_cursor},
+    {"right-ptr", RemoteCursorShape::default_cursor},
+    {"center-ptr", RemoteCursorShape::default_cursor},
+    {"context-menu", RemoteCursorShape::default_cursor},
+};
+
+std::string NormalizeCursorName(const std::string& raw_name) {
+  std::string normalized;
+  normalized.reserve(raw_name.size());
+  for (unsigned char ch : raw_name) {
+    if (ch == '_' || std::isspace(ch)) {
+      normalized.push_back('-');
+    } else {
+      normalized.push_back(static_cast<char>(std::tolower(ch)));
+    }
+  }
+  return normalized;
+}
+
+#if defined(__linux__) && !defined(__APPLE__)
+
+struct CursorCandidate {
+  RemoteCursorShape shape = RemoteCursorShape::default_cursor;
+  uint32_t width = 0;
+  uint32_t height = 0;
+  uint32_t xhot = 0;
+  uint32_t yhot = 0;
+  std::vector<uint32_t> argb;
+};
+
+uint8_t Alpha(uint32_t argb) {
+  return static_cast<uint8_t>((argb >> 24U) & 0xffU);
+}
+
+double BilinearAlpha(const CursorCandidate& candidate, double x, double y) {
+  if (candidate.width == 0 || candidate.height == 0) {
+    return 0.0;
+  }
+
+  x = std::max(0.0, std::min(x, static_cast<double>(candidate.width - 1)));
+  y = std::max(0.0, std::min(y, static_cast<double>(candidate.height - 1)));
+  const uint32_t x0 = static_cast<uint32_t>(std::floor(x));
+  const uint32_t y0 = static_cast<uint32_t>(std::floor(y));
+  const uint32_t x1 = std::min(x0 + 1, candidate.width - 1);
+  const uint32_t y1 = std::min(y0 + 1, candidate.height - 1);
+  const double fx = x - x0;
+  const double fy = y - y0;
+
+  const auto sample = [&](uint32_t px, uint32_t py) {
+    return static_cast<double>(
+        Alpha(candidate.argb[static_cast<size_t>(py) * candidate.width + px]));
+  };
+  const double top = sample(x0, y0) * (1.0 - fx) + sample(x1, y0) * fx;
+  const double bottom = sample(x0, y1) * (1.0 - fx) + sample(x1, y1) * fx;
+  return top * (1.0 - fy) + bottom * fy;
+}
+
+double SimilarityError(const LinuxCursorImageView& image,
+                       const CursorCandidate& candidate) {
+  if (!image.argb || image.width == 0 || image.height == 0 ||
+      candidate.argb.empty()) {
+    return std::numeric_limits<double>::infinity();
+  }
+
+  double alpha_error = 0.0;
+  for (uint32_t y = 0; y < image.height; ++y) {
+    const double source_y =
+        (static_cast<double>(y) + 0.5) * candidate.height / image.height - 0.5;
+    for (uint32_t x = 0; x < image.width; ++x) {
+      const double source_x = (static_cast<double>(x) + 0.5) *
+                                  candidate.width / image.width -
+                              0.5;
+      const double expected = BilinearAlpha(candidate, source_x, source_y);
+      const double actual = static_cast<double>(
+          Alpha(image.argb[static_cast<size_t>(y) * image.width + x]));
+      alpha_error += std::abs(actual - expected) / 255.0;
+    }
+  }
+  alpha_error /= static_cast<double>(image.width) * image.height;
+
+  const double observed_hot_x =
+      static_cast<double>(image.xhot) / std::max(1u, image.width);
+  const double observed_hot_y =
+      static_cast<double>(image.yhot) / std::max(1u, image.height);
+  const double candidate_hot_x =
+      static_cast<double>(candidate.xhot) / std::max(1u, candidate.width);
+  const double candidate_hot_y =
+      static_cast<double>(candidate.yhot) / std::max(1u, candidate.height);
+  const double hotspot_error =
+      std::abs(observed_hot_x - candidate_hot_x) +
+      std::abs(observed_hot_y - candidate_hot_y);
+
+  const double observed_aspect =
+      static_cast<double>(image.width) / image.height;
+  const double candidate_aspect =
+      static_cast<double>(candidate.width) / candidate.height;
+  const double aspect_error =
+      std::abs(std::log(observed_aspect / candidate_aspect));
+
+  return alpha_error + hotspot_error * 0.12 + aspect_error * 0.08;
+}
+
+bool SameImage(const LinuxCursorImageView& image,
+               const CursorCandidate& candidate) {
+  if (image.width != candidate.width || image.height != candidate.height ||
+      image.xhot != candidate.xhot || image.yhot != candidate.yhot) {
+    return false;
+  }
+  const size_t pixel_count =
+      static_cast<size_t>(image.width) * static_cast<size_t>(image.height);
+  return std::equal(image.argb, image.argb + pixel_count,
+                    candidate.argb.begin());
+}
+
+#endif
+
+}  // namespace
+
+const LinuxCursorAlias* LinuxCursorAliases(size_t* count) {
+  if (count) {
+    *count = sizeof(kCursorAliases) / sizeof(kCursorAliases[0]);
+  }
+  return kCursorAliases;
+}
+
+RemoteCursorShape ShapeFromLinuxCursorName(const std::string& raw_name) {
+  const std::string name = NormalizeCursorName(raw_name);
+  for (const auto& alias : kCursorAliases) {
+    if (name == alias.name) {
+      return alias.shape;
+    }
+  }
+
+  // Some toolkits prefix a theme or toolkit name to the standard cursor name.
+  // Restrict the fallback to separators so names such as "pointer-progress"
+  // still prefer their exact semantic alias above.
+  for (const auto& alias : kCursorAliases) {
+    const std::string suffix = std::string("-") + alias.name;
+    if (name.size() > suffix.size() &&
+        name.compare(name.size() - suffix.size(), suffix.size(), suffix) == 0) {
+      return alias.shape;
+    }
+  }
+  return RemoteCursorShape::default_cursor;
+}
+
+#if defined(__linux__) && !defined(__APPLE__)
+
+struct LinuxCursorThemeMatcher::Impl {
+  Display* display = XOpenDisplay(nullptr);
+  std::string theme;
+  int default_size = 24;
+  std::unordered_map<int, std::vector<CursorCandidate>> candidates_by_size;
+
+  Impl() {
+    if (!display) {
+      return;
+    }
+    if (const char* active_theme = XcursorGetTheme(display)) {
+      theme = active_theme;
+    }
+    const int active_size = XcursorGetDefaultSize(display);
+    if (active_size > 0) {
+      default_size = active_size;
+    }
+  }
+
+  ~Impl() {
+    if (display) {
+      XCloseDisplay(display);
+    }
+  }
+
+  const std::vector<CursorCandidate>& Candidates(int requested_size) {
+    requested_size = std::max(1, requested_size);
+    auto existing = candidates_by_size.find(requested_size);
+    if (existing != candidates_by_size.end()) {
+      return existing->second;
+    }
+
+    std::vector<CursorCandidate> candidates;
+    const char* theme_name = theme.empty() ? nullptr : theme.c_str();
+    for (const auto& alias : kCursorAliases) {
+      XcursorImages* images =
+          XcursorLibraryLoadImages(alias.name, theme_name, requested_size);
+      if (!images) {
+        continue;
+      }
+      for (int index = 0; index < images->nimage; ++index) {
+        const XcursorImage* image = images->images[index];
+        if (!image || !image->pixels || image->width == 0 ||
+            image->height == 0) {
+          continue;
+        }
+
+        CursorCandidate candidate;
+        candidate.shape = alias.shape;
+        candidate.width = image->width;
+        candidate.height = image->height;
+        candidate.xhot = image->xhot;
+        candidate.yhot = image->yhot;
+        const size_t pixel_count = static_cast<size_t>(image->width) *
+                                   static_cast<size_t>(image->height);
+        candidate.argb.assign(image->pixels, image->pixels + pixel_count);
+
+        const bool duplicate =
+            std::any_of(candidates.begin(), candidates.end(),
+                        [&](const CursorCandidate& current) {
+                          return current.shape == candidate.shape &&
+                                 current.width == candidate.width &&
+                                 current.height == candidate.height &&
+                                 current.xhot == candidate.xhot &&
+                                 current.yhot == candidate.yhot &&
+                                 current.argb == candidate.argb;
+                        });
+        if (!duplicate) {
+          candidates.push_back(std::move(candidate));
+        }
+      }
+      XcursorImagesDestroy(images);
+    }
+
+    return candidates_by_size
+        .emplace(requested_size, std::move(candidates))
+        .first->second;
+  }
+};
+
+#else
+
+struct LinuxCursorThemeMatcher::Impl {};
+
+#endif
+
+LinuxCursorThemeMatcher::LinuxCursorThemeMatcher()
+    : impl_(std::make_unique<Impl>()) {}
+
+LinuxCursorThemeMatcher::~LinuxCursorThemeMatcher() = default;
+
+RemoteCursorShape LinuxCursorThemeMatcher::Match(
+    const LinuxCursorImageView& image) {
+#if defined(__linux__) && !defined(__APPLE__)
+  if (!impl_ || !image.argb || image.width == 0 || image.height == 0) {
+    return RemoteCursorShape::default_cursor;
+  }
+
+  const int requested_size =
+      static_cast<int>(std::max(image.width, image.height));
+  const auto& candidates = impl_->Candidates(requested_size);
+  for (const auto& candidate : candidates) {
+    if (SameImage(image, candidate)) {
+      return candidate.shape;
+    }
+  }
+
+  double best_error = std::numeric_limits<double>::infinity();
+  RemoteCursorShape best_shape = RemoteCursorShape::default_cursor;
+  for (const auto& candidate : candidates) {
+    const double error = SimilarityError(image, candidate);
+    if (error < best_error) {
+      best_error = error;
+      best_shape = candidate.shape;
+    }
+  }
+
+  // Scaled theme cursors normally remain well below this threshold, while an
+  // unrelated custom application cursor should fall back to the default.
+  return best_error <= 0.20 ? best_shape
+                            : RemoteCursorShape::default_cursor;
+#else
+  (void)image;
+  return RemoteCursorShape::default_cursor;
+#endif
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/common/linux_cursor_shape.h

@@ -0,0 +1,49 @@
+#ifndef CROSSDESK_COMMON_LINUX_CURSOR_SHAPE_H_
+#define CROSSDESK_COMMON_LINUX_CURSOR_SHAPE_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include <remote_cursor_shape.h>
+
+namespace crossdesk {
+
+struct LinuxCursorAlias {
+  const char* name;
+  RemoteCursorShape shape;
+};
+
+const LinuxCursorAlias* LinuxCursorAliases(size_t* count);
+RemoteCursorShape ShapeFromLinuxCursorName(const std::string& name);
+
+struct LinuxCursorImageView {
+  uint32_t width = 0;
+  uint32_t height = 0;
+  uint32_t xhot = 0;
+  uint32_t yhot = 0;
+  const uint32_t* argb = nullptr;
+};
+
+// Matches a compositor-provided cursor bitmap against the active Xcursor
+// theme. This is needed on Wayland, where XFixes only observes XWayland
+// cursors and cannot report cursors owned by native Wayland surfaces.
+class LinuxCursorThemeMatcher {
+ public:
+  LinuxCursorThemeMatcher();
+  ~LinuxCursorThemeMatcher();
+
+  LinuxCursorThemeMatcher(const LinuxCursorThemeMatcher&) = delete;
+  LinuxCursorThemeMatcher& operator=(const LinuxCursorThemeMatcher&) = delete;
+
+  RemoteCursorShape Match(const LinuxCursorImageView& image);
+
+ private:
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+}  // namespace crossdesk
+
+#endif  // CROSSDESK_COMMON_LINUX_CURSOR_SHAPE_H_

apps/desktop/src/platform/linux/common/wayland_portal_shared.cpp

@@ -0,0 +1,279 @@
+#include "wayland_portal_shared.h"
+
+#include <chrono>
+#include <mutex>
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+#include <dbus/dbus.h>
+#endif
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+namespace {
+
+std::mutex& SharedSessionMutex() {
+  static std::mutex mutex;
+  return mutex;
+}
+
+SharedWaylandPortalSessionInfo& SharedSessionInfo() {
+  static SharedWaylandPortalSessionInfo info;
+  return info;
+}
+
+bool& SharedSessionActive() {
+  static bool active = false;
+  return active;
+}
+
+int& SharedSessionRefs() {
+  static int refs = 0;
+  return refs;
+}
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+constexpr const char* kPortalBusName = "org.freedesktop.portal.Desktop";
+constexpr const char* kPortalSessionInterface =
+    "org.freedesktop.portal.Session";
+constexpr int kPortalCloseWaitMs = 100;
+
+void LogCloseDbusError(const char* action, DBusError* error) {
+  if (error && dbus_error_is_set(error)) {
+    LOG_ERROR("{} failed: {} ({})", action,
+              error->message ? error->message : "unknown",
+              error->name ? error->name : "unknown");
+  } else {
+    LOG_ERROR("{} failed", action);
+  }
+}
+
+struct SessionClosedState {
+  std::string session_handle;
+  bool received = false;
+};
+
+DBusHandlerResult HandleSessionClosedSignal(DBusConnection* connection,
+                                            DBusMessage* message,
+                                            void* user_data) {
+  (void)connection;
+  auto* state = static_cast<SessionClosedState*>(user_data);
+  if (!state || !message) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  if (!dbus_message_is_signal(message, kPortalSessionInterface, "Closed")) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  const char* path = dbus_message_get_path(message);
+  if (!path || state->session_handle != path) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  state->received = true;
+  return DBUS_HANDLER_RESULT_HANDLED;
+}
+
+bool BeginSessionClosedWatch(DBusConnection* connection,
+                             const std::string& session_handle,
+                             SessionClosedState* state,
+                             std::string* match_rule_out) {
+  if (!connection || session_handle.empty() || !state || !match_rule_out) {
+    return false;
+  }
+
+  state->session_handle = session_handle;
+  state->received = false;
+  DBusError error;
+  dbus_error_init(&error);
+  const std::string match_rule =
+      "type='signal',interface='" + std::string(kPortalSessionInterface) +
+      "',member='Closed',path='" + session_handle + "'";
+  dbus_bus_add_match(connection, match_rule.c_str(), &error);
+  if (dbus_error_is_set(&error)) {
+    LogCloseDbusError("dbus_bus_add_match(Session.Closed)", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  dbus_connection_add_filter(connection, HandleSessionClosedSignal, state,
+                             nullptr);
+  *match_rule_out = match_rule;
+  return true;
+}
+
+void EndSessionClosedWatch(DBusConnection* connection, SessionClosedState* state,
+                           const std::string& match_rule) {
+  if (!connection || !state || match_rule.empty()) {
+    return;
+  }
+
+  dbus_connection_remove_filter(connection, HandleSessionClosedSignal, state);
+
+  DBusError remove_error;
+  dbus_error_init(&remove_error);
+  dbus_bus_remove_match(connection, match_rule.c_str(), &remove_error);
+  if (dbus_error_is_set(&remove_error)) {
+    dbus_error_free(&remove_error);
+  }
+}
+
+void WaitForSessionClosed(DBusConnection* connection, SessionClosedState* state,
+                          int timeout_ms = kPortalCloseWaitMs) {
+  if (!connection || !state) {
+    return;
+  }
+
+  const auto deadline =
+      std::chrono::steady_clock::now() + std::chrono::milliseconds(timeout_ms);
+  while (!state->received && std::chrono::steady_clock::now() < deadline) {
+    dbus_connection_read_write(connection, 100);
+    while (dbus_connection_dispatch(connection) == DBUS_DISPATCH_DATA_REMAINS) {
+    }
+  }
+}
+#endif
+
+}  // namespace
+
+bool PublishSharedWaylandPortalSession(
+    const SharedWaylandPortalSessionInfo& info) {
+  if (!info.connection || info.session_handle.empty() || info.stream_id == 0) {
+    return false;
+  }
+
+  std::lock_guard<std::mutex> lock(SharedSessionMutex());
+  if (SharedSessionActive()) {
+    const auto& active_info = SharedSessionInfo();
+    if (active_info.session_handle != info.session_handle &&
+        SharedSessionRefs() > 0) {
+      return false;
+    }
+  }
+
+  const bool same_session =
+      SharedSessionActive() &&
+      SharedSessionInfo().session_handle == info.session_handle;
+  SharedSessionInfo() = info;
+  SharedSessionActive() = true;
+  if (!same_session || SharedSessionRefs() <= 0) {
+    SharedSessionRefs() = 1;
+  }
+  return true;
+}
+
+bool AcquireSharedWaylandPortalSession(bool require_pointer,
+                                       SharedWaylandPortalSessionInfo* out) {
+  if (!out) {
+    return false;
+  }
+
+  std::lock_guard<std::mutex> lock(SharedSessionMutex());
+  if (!SharedSessionActive()) {
+    return false;
+  }
+
+  const auto& info = SharedSessionInfo();
+  if (require_pointer && !info.pointer_granted) {
+    return false;
+  }
+
+  ++SharedSessionRefs();
+  *out = info;
+  return true;
+}
+
+bool ReleaseSharedWaylandPortalSession(DBusConnection** connection_out,
+                                       std::string* session_handle_out) {
+  if (connection_out) {
+    *connection_out = nullptr;
+  }
+  if (session_handle_out) {
+    session_handle_out->clear();
+  }
+
+  std::lock_guard<std::mutex> lock(SharedSessionMutex());
+  if (!SharedSessionActive()) {
+    return false;
+  }
+
+  if (SharedSessionRefs() > 0) {
+    --SharedSessionRefs();
+  }
+
+  if (SharedSessionRefs() > 0) {
+    return true;
+  }
+
+  if (connection_out) {
+    *connection_out = SharedSessionInfo().connection;
+  }
+  if (session_handle_out) {
+    *session_handle_out = SharedSessionInfo().session_handle;
+  }
+
+  SharedSessionInfo() = SharedWaylandPortalSessionInfo{};
+  SharedSessionActive() = false;
+  SharedSessionRefs() = 0;
+  return true;
+}
+
+void CloseWaylandPortalSessionAndConnection(DBusConnection* connection,
+                                            const std::string& session_handle,
+                                            const char* close_action) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  if (!connection) {
+    return;
+  }
+
+  if (!session_handle.empty()) {
+    SessionClosedState close_state;
+    std::string close_match_rule;
+    const bool watching_closed = BeginSessionClosedWatch(
+        connection, session_handle, &close_state, &close_match_rule);
+
+    DBusMessage* message = dbus_message_new_method_call(
+        kPortalBusName, session_handle.c_str(), kPortalSessionInterface,
+        "Close");
+    if (message) {
+      DBusError error;
+      dbus_error_init(&error);
+      DBusMessage* reply = dbus_connection_send_with_reply_and_block(
+          connection, message, 1000, &error);
+      if (!reply && dbus_error_is_set(&error)) {
+        LogCloseDbusError(close_action, &error);
+        dbus_error_free(&error);
+      }
+      if (reply) {
+        dbus_message_unref(reply);
+      }
+      dbus_message_unref(message);
+    }
+
+    if (watching_closed) {
+      WaitForSessionClosed(connection, &close_state);
+      if (!close_state.received) {
+        LOG_WARN("Timed out waiting for portal session to close: {}",
+                 session_handle);
+        LOG_WARN("Forcing local teardown without waiting for Session.Closed: {}",
+                 session_handle);
+        EndSessionClosedWatch(connection, &close_state, close_match_rule);
+      } else {
+        EndSessionClosedWatch(connection, &close_state, close_match_rule);
+        LOG_INFO("Portal session closed: {}", session_handle);
+      }
+    }
+  }
+
+  dbus_connection_close(connection);
+  dbus_connection_unref(connection);
+#else
+  (void)connection;
+  (void)session_handle;
+  (void)close_action;
+#endif
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/common/wayland_portal_shared.h

@@ -0,0 +1,37 @@
+/*
+ * Shared Wayland portal session state used by the Linux Wayland capturer and
+ * mouse controller so they can reuse one RemoteDesktop session.
+ */
+
+#ifndef _WAYLAND_PORTAL_SHARED_H_
+#define _WAYLAND_PORTAL_SHARED_H_
+
+#include <cstdint>
+#include <string>
+
+struct DBusConnection;
+
+namespace crossdesk {
+
+struct SharedWaylandPortalSessionInfo {
+  DBusConnection* connection = nullptr;
+  std::string session_handle;
+  uint32_t stream_id = 0;
+  int width = 0;
+  int height = 0;
+  bool pointer_granted = false;
+};
+
+bool PublishSharedWaylandPortalSession(
+    const SharedWaylandPortalSessionInfo& info);
+bool AcquireSharedWaylandPortalSession(bool require_pointer,
+                                       SharedWaylandPortalSessionInfo* out);
+bool ReleaseSharedWaylandPortalSession(DBusConnection** connection_out,
+                                       std::string* session_handle_out);
+void CloseWaylandPortalSessionAndConnection(DBusConnection* connection,
+                                            const std::string& session_handle,
+                                            const char* close_action);
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/daemon_backend.cpp

@@ -0,0 +1,58 @@
+#include "platform/daemon_backend.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <signal.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <cstring>
+#include <iostream>
+
+namespace crossdesk::platform {
+
+bool PrepareDaemon() {
+  const bool from_terminal =
+      isatty(STDIN_FILENO) != 0 || isatty(STDOUT_FILENO) != 0;
+  pid_t process = fork();
+  if (process < 0) return false;
+  if (process > 0) _exit(0);
+  if (setsid() < 0) return false;
+
+  process = fork();
+  if (process < 0) return false;
+  if (process > 0) _exit(0);
+
+  umask(0);
+  if (chdir("/") != 0) {
+    std::cerr << "Failed to change daemon working directory to /: "
+              << std::strerror(errno) << std::endl;
+    return false;
+  }
+
+  const int null_fd = open("/dev/null", O_RDWR);
+  if (null_fd >= 0) {
+    dup2(null_fd, STDIN_FILENO);
+    if (!from_terminal) {
+      dup2(null_fd, STDOUT_FILENO);
+      dup2(null_fd, STDERR_FILENO);
+    }
+    if (null_fd > STDERR_FILENO) close(null_fd);
+  }
+
+  signal(SIGTERM, [](int) { g_daemon_stop_requested = 1; });
+  signal(SIGINT, [](int) { g_daemon_stop_requested = 1; });
+  signal(SIGPIPE, SIG_IGN);
+  return true;
+}
+
+std::string GetDaemonExecutablePath() {
+  char path[PATH_MAX] = {};
+  const ssize_t count = readlink("/proc/self/exe", path, sizeof(path) - 1);
+  return count > 0 ? std::string(path, static_cast<size_t>(count))
+                   : std::string();
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/linux/gui/tray/linux_tray.h

@@ -0,0 +1,46 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-06-23
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _LINUX_TRAY_H_
+#define _LINUX_TRAY_H_
+
+#if defined(__linux__) && !defined(__APPLE__)
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+
+struct SDL_Window;
+
+namespace crossdesk {
+
+struct LinuxTrayImpl;
+
+class LinuxTray {
+ public:
+  LinuxTray(::SDL_Window* app_window, const std::string& tooltip,
+            int language_index, uint32_t exit_event_type);
+  LinuxTray(std::function<void()> show_window,
+            std::function<void()> hide_window,
+            std::function<void()> open_settings,
+            std::function<void()> exit_app,
+            const std::string& tooltip, int language_index);
+  ~LinuxTray();
+
+  bool MinimizeToTray();
+  void RemoveTrayIcon();
+  void ProcessEvents();
+
+ private:
+  std::unique_ptr<LinuxTrayImpl> impl_;
+};
+
+}  // namespace crossdesk
+
+#endif  // defined(__linux__) && !defined(__APPLE__)
+
+#endif  // _LINUX_TRAY_H_

apps/desktop/src/platform/linux/input/device_controller_factory.cpp

@@ -0,0 +1,19 @@
+#include "device_controller_factory.h"
+
+#include "keyboard_capturer.h"
+#include "mouse_controller.h"
+
+namespace crossdesk {
+
+DeviceController* DeviceControllerFactory::Create(Device device) {
+  switch (device) {
+    case Mouse:
+      return new PlatformMouseController();
+    case Keyboard:
+      return new PlatformKeyboardCapturer();
+    default:
+      return nullptr;
+  }
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/input/keyboard/keyboard_capturer.cpp

@@ -0,0 +1,257 @@
+#include "keyboard_capturer.h"
+
+#include <X11/Xlib.h>
+#include <X11/extensions/XTest.h>
+#include <X11/keysym.h>
+
+#include <errno.h>
+#include <poll.h>
+
+#include "keyboard_converter.h"
+#include "linux_evdev_keycode.h"
+#include "platform.h"
+#include "rd_log.h"
+#include "windows_key_metadata.h"
+
+namespace crossdesk {
+
+static OnKeyAction g_on_key_action = nullptr;
+static void* g_user_ptr = nullptr;
+
+static KeyCode ResolveX11Keycode(Display* display, int key_code,
+                                 uint32_t scan_code, bool extended) {
+  if (!display) {
+    return 0;
+  }
+
+  const auto key_it = vkCodeToX11KeySym.find(key_code);
+  if (key_it != vkCodeToX11KeySym.end()) {
+    const KeyCode x11_keycode =
+        XKeysymToKeycode(display, static_cast<KeySym>(key_it->second));
+    if (x11_keycode != 0) {
+      return x11_keycode;
+    }
+  }
+
+  // Some controllers can preserve the physical Windows scan code even when
+  // they cannot resolve a Windows virtual-key value. Xorg's evdev keycodes use
+  // the Linux input code plus the protocol-reserved offset of 8.
+  const int evdev_keycode =
+      ResolveLinuxEvdevKeycodeFromWindowsKey(key_code, scan_code, extended);
+  if (evdev_keycode < 0) {
+    return 0;
+  }
+
+  int min_keycode = 0;
+  int max_keycode = 0;
+  XDisplayKeycodes(display, &min_keycode, &max_keycode);
+  const int x11_keycode = evdev_keycode + 8;
+  if (x11_keycode < min_keycode || x11_keycode > max_keycode) {
+    return 0;
+  }
+  return static_cast<KeyCode>(x11_keycode);
+}
+
+static KeySym NormalizeKeySym(KeySym key_sym) {
+  if (key_sym >= XK_a && key_sym <= XK_z) {
+    return key_sym - XK_a + XK_A;
+  }
+  return key_sym;
+}
+
+static int KeyboardEventHandler(Display* display, XEvent* event) {
+  (void)display;
+  if (event->xkey.type == KeyPress || event->xkey.type == KeyRelease) {
+    KeySym key_sym = NormalizeKeySym(XLookupKeysym(&event->xkey, 0));
+    auto key_it = x11KeySymToVkCode.find(static_cast<int>(key_sym));
+    if (key_it == x11KeySymToVkCode.end()) {
+      key_sym = NormalizeKeySym(XLookupKeysym(&event->xkey, 1));
+      key_it = x11KeySymToVkCode.find(static_cast<int>(key_sym));
+    }
+
+    if (key_it == x11KeySymToVkCode.end()) {
+      return 0;
+    }
+
+    int key_code = key_it->second;
+    bool is_key_down = (event->xkey.type == KeyPress);
+    uint32_t scan_code = 0;
+    bool extended = false;
+    LookupWindowsKeyMetadataFromVk(key_code, &scan_code, &extended);
+
+    if (g_on_key_action) {
+      g_on_key_action(key_code, is_key_down, scan_code, extended, g_user_ptr);
+    }
+  }
+  return 0;
+}
+
+PlatformKeyboardCapturer::PlatformKeyboardCapturer()
+    : display_(nullptr),
+      root_(0),
+      running_(false),
+      use_wayland_portal_(false),
+      wayland_init_attempted_(false),
+      dbus_connection_(nullptr) {
+  XInitThreads();
+  display_ = XOpenDisplay(nullptr);
+  if (!display_) {
+    LOG_ERROR("Failed to open X display.");
+    return;
+  }
+
+  int event_base = 0;
+  int error_base = 0;
+  int major_version = 0;
+  int minor_version = 0;
+  x11_xtest_available_ =
+      XTestQueryExtension(display_, &event_base, &error_base, &major_version,
+                          &minor_version) != 0;
+}
+
+PlatformKeyboardCapturer::~PlatformKeyboardCapturer() {
+  Unhook();
+  CleanupWaylandPortal();
+
+  if (display_) {
+    std::lock_guard<std::mutex> lock(x11_injection_mutex_);
+    XCloseDisplay(display_);
+    display_ = nullptr;
+    x11_xtest_available_ = false;
+  }
+}
+
+int PlatformKeyboardCapturer::Hook(OnKeyAction on_key_action, void* user_ptr) {
+  if (!display_) {
+    LOG_ERROR("Display not initialized.");
+    return -1;
+  }
+
+  g_on_key_action = on_key_action;
+  g_user_ptr = user_ptr;
+
+  if (running_) {
+    return 0;
+  }
+
+  root_ = DefaultRootWindow(display_);
+  XSelectInput(display_, root_, KeyPressMask | KeyReleaseMask);
+  XFlush(display_);
+
+  running_ = true;
+  const int x11_fd = ConnectionNumber(display_);
+  event_thread_ = std::thread([this, x11_fd]() {
+    while (running_) {
+      while (running_ && XPending(display_) > 0) {
+        XEvent event;
+        XNextEvent(display_, &event);
+        KeyboardEventHandler(display_, &event);
+      }
+
+      if (!running_) {
+        break;
+      }
+
+      struct pollfd pfd = {x11_fd, POLLIN, 0};
+      int poll_ret = poll(&pfd, 1, 50);
+      if (poll_ret < 0) {
+        if (errno == EINTR) {
+          continue;
+        }
+        LOG_ERROR("poll for X11 events failed.");
+        running_ = false;
+        break;
+      }
+
+      if (poll_ret == 0) {
+        continue;
+      }
+
+      if ((pfd.revents & (POLLERR | POLLHUP | POLLNVAL)) != 0) {
+        LOG_ERROR("poll got invalid X11 event fd state.");
+        running_ = false;
+        break;
+      }
+
+      if ((pfd.revents & POLLIN) == 0) {
+        continue;
+      }
+    }
+  });
+
+  return 0;
+}
+
+int PlatformKeyboardCapturer::Unhook() {
+  running_ = false;
+
+  if (event_thread_.joinable()) {
+    event_thread_.join();
+  }
+
+  g_on_key_action = nullptr;
+  g_user_ptr = nullptr;
+
+  if (display_ && root_ != 0) {
+    XSelectInput(display_, root_, 0);
+    XFlush(display_);
+  }
+
+  return 0;
+}
+
+int PlatformKeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down,
+                                          uint32_t scan_code, bool extended) {
+  if (IsWaylandSession()) {
+    if (!use_wayland_portal_ && !wayland_init_attempted_) {
+      wayland_init_attempted_ = true;
+      if (InitWaylandPortal()) {
+        use_wayland_portal_ = true;
+        LOG_INFO("Keyboard controller initialized with Wayland portal backend");
+      } else {
+        LOG_WARN(
+            "Wayland keyboard control init failed, falling back to X11/XTest "
+            "backend");
+      }
+    }
+
+    if (use_wayland_portal_) {
+      return SendWaylandKeyboardCommand(key_code, is_down, scan_code, extended);
+    }
+  }
+
+  if (!display_) {
+    LOG_ERROR("Display not initialized.");
+    return -1;
+  }
+
+  std::lock_guard<std::mutex> lock(x11_injection_mutex_);
+  if (!x11_xtest_available_) {
+    LOG_ERROR("XTest extension not available for keyboard injection");
+    return -2;
+  }
+
+  const KeyCode x11_keycode =
+      ResolveX11Keycode(display_, key_code, scan_code, extended);
+  if (x11_keycode == 0) {
+    LOG_WARN(
+        "Cannot map remote keyboard event to X11 keycode, vk_code={}, "
+        "scan_code={}, extended={}",
+        key_code, scan_code, extended);
+    return -3;
+  }
+
+  if (!XTestFakeKeyEvent(display_, x11_keycode, is_down, CurrentTime)) {
+    LOG_ERROR(
+        "XTest keyboard injection failed, vk_code={}, scan_code={}, "
+        "extended={}, x11_keycode={}, is_down={}",
+        key_code, scan_code, extended, static_cast<int>(x11_keycode), is_down);
+    return -4;
+  }
+
+  // Complete the request before reporting success to the keyboard-state
+  // reconciler. This also makes X11 protocol errors observable immediately.
+  XSync(display_, False);
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/linux/input/keyboard/keyboard_capturer.h

@@ -0,0 +1,61 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2024-11-22
+ * Copyright (c) 2024 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _KEYBOARD_CAPTURER_H_
+#define _KEYBOARD_CAPTURER_H_
+
+#include <atomic>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <thread>
+
+#include "device_controller.h"
+
+struct DBusConnection;
+struct DBusMessageIter;
+struct _XDisplay;
+
+namespace crossdesk {
+
+class PlatformKeyboardCapturer final : public KeyboardCapturer {
+ public:
+  PlatformKeyboardCapturer();
+  virtual ~PlatformKeyboardCapturer();
+
+ public:
+  virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
+  virtual int Unhook();
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false);
+
+ private:
+  bool InitWaylandPortal();
+  void CleanupWaylandPortal();
+  int SendWaylandKeyboardCommand(int key_code, bool is_down, uint32_t scan_code,
+                                 bool extended);
+  bool NotifyWaylandKeyboardKeysym(int keysym, uint32_t state);
+  bool NotifyWaylandKeyboardKeycode(int keycode, uint32_t state);
+  bool SendWaylandPortalVoidCall(const char* method_name,
+                                 const std::function<void(DBusMessageIter*)>&
+                                     append_args);
+
+ private:
+  _XDisplay* display_;
+  unsigned long root_;
+  std::atomic<bool> running_;
+  std::thread event_thread_;
+  std::mutex x11_injection_mutex_;
+  bool x11_xtest_available_ = false;
+  bool use_wayland_portal_ = false;
+  bool wayland_init_attempted_ = false;
+  DBusConnection* dbus_connection_ = nullptr;
+  std::string wayland_session_handle_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/linux/input/keyboard/keyboard_capturer_wayland.cpp

@@ -0,0 +1,735 @@
+#include "keyboard_capturer.h"
+
+#include <chrono>
+#include <cstring>
+#include <map>
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+#include <X11/Xlib.h>
+#include <X11/keysym.h>
+
+#include <dbus/dbus.h>
+#endif
+
+#include "linux_evdev_keycode.h"
+#include "rd_log.h"
+#include "wayland_portal_shared.h"
+
+namespace crossdesk {
+
+extern std::map<int, int> vkCodeToX11KeySym;
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+namespace {
+
+constexpr const char* kPortalBusName = "org.freedesktop.portal.Desktop";
+constexpr const char* kPortalObjectPath = "/org/freedesktop/portal/desktop";
+constexpr const char* kPortalRemoteDesktopInterface =
+    "org.freedesktop.portal.RemoteDesktop";
+constexpr const char* kPortalRequestInterface =
+    "org.freedesktop.portal.Request";
+constexpr const char* kPortalRequestPathPrefix =
+    "/org/freedesktop/portal/desktop/request/";
+constexpr const char* kPortalSessionPathPrefix =
+    "/org/freedesktop/portal/desktop/session/";
+
+constexpr uint32_t kRemoteDesktopDeviceKeyboard = 1u;
+constexpr uint32_t kKeyboardReleased = 0u;
+constexpr uint32_t kKeyboardPressed = 1u;
+
+int NormalizeFallbackKeysym(int keysym) {
+  if (keysym >= XK_A && keysym <= XK_Z) {
+    return keysym - XK_A + XK_a;
+  }
+  return keysym;
+}
+
+std::string MakeToken(const char* prefix) {
+  const auto now = std::chrono::steady_clock::now().time_since_epoch().count();
+  return std::string(prefix) + "_" + std::to_string(now);
+}
+
+void LogDbusError(const char* action, DBusError* error) {
+  if (error && dbus_error_is_set(error)) {
+    LOG_ERROR("{} failed: {} ({})", action,
+              error->message ? error->message : "unknown",
+              error->name ? error->name : "unknown");
+  } else {
+    LOG_ERROR("{} failed", action);
+  }
+}
+
+void AppendDictEntryString(DBusMessageIter* dict, const char* key,
+                           const std::string& value) {
+  DBusMessageIter entry;
+  DBusMessageIter variant;
+  const char* key_cstr = key;
+  const char* value_cstr = value.c_str();
+
+  dbus_message_iter_open_container(dict, DBUS_TYPE_DICT_ENTRY, nullptr, &entry);
+  dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key_cstr);
+  dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT, "s", &variant);
+  dbus_message_iter_append_basic(&variant, DBUS_TYPE_STRING, &value_cstr);
+  dbus_message_iter_close_container(&entry, &variant);
+  dbus_message_iter_close_container(dict, &entry);
+}
+
+void AppendDictEntryUint32(DBusMessageIter* dict, const char* key,
+                           uint32_t value) {
+  DBusMessageIter entry;
+  DBusMessageIter variant;
+  const char* key_cstr = key;
+
+  dbus_message_iter_open_container(dict, DBUS_TYPE_DICT_ENTRY, nullptr, &entry);
+  dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key_cstr);
+  dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT, "u", &variant);
+  dbus_message_iter_append_basic(&variant, DBUS_TYPE_UINT32, &value);
+  dbus_message_iter_close_container(&entry, &variant);
+  dbus_message_iter_close_container(dict, &entry);
+}
+
+void AppendEmptyOptionsDict(DBusMessageIter* iter) {
+  DBusMessageIter options;
+  dbus_message_iter_open_container(iter, DBUS_TYPE_ARRAY, "{sv}", &options);
+  dbus_message_iter_close_container(iter, &options);
+}
+
+bool ReadPathLikeVariant(DBusMessageIter* variant, std::string* value) {
+  if (!variant || !value) {
+    return false;
+  }
+
+  const int type = dbus_message_iter_get_arg_type(variant);
+  if (type == DBUS_TYPE_OBJECT_PATH || type == DBUS_TYPE_STRING) {
+    const char* temp = nullptr;
+    dbus_message_iter_get_basic(variant, &temp);
+    if (temp && temp[0] != '\0') {
+      *value = temp;
+      return true;
+    }
+  }
+
+  return false;
+}
+
+bool ReadUint32Like(DBusMessageIter* iter, uint32_t* value) {
+  if (!iter || !value) {
+    return false;
+  }
+
+  const int type = dbus_message_iter_get_arg_type(iter);
+  if (type == DBUS_TYPE_UINT32) {
+    uint32_t temp = 0;
+    dbus_message_iter_get_basic(iter, &temp);
+    *value = temp;
+    return true;
+  }
+
+  if (type == DBUS_TYPE_INT32) {
+    int32_t temp = 0;
+    dbus_message_iter_get_basic(iter, &temp);
+    if (temp < 0) {
+      return false;
+    }
+    *value = static_cast<uint32_t>(temp);
+    return true;
+  }
+
+  return false;
+}
+
+std::string BuildSessionHandleFromRequestPath(
+    const std::string& request_path, const std::string& session_handle_token) {
+  if (request_path.rfind(kPortalRequestPathPrefix, 0) != 0 ||
+      session_handle_token.empty()) {
+    return "";
+  }
+
+  const size_t sender_start = strlen(kPortalRequestPathPrefix);
+  const size_t token_sep = request_path.find('/', sender_start);
+  if (token_sep == std::string::npos || token_sep <= sender_start) {
+    return "";
+  }
+
+  const std::string sender =
+      request_path.substr(sender_start, token_sep - sender_start);
+  if (sender.empty()) {
+    return "";
+  }
+
+  return std::string(kPortalSessionPathPrefix) + sender + "/" +
+         session_handle_token;
+}
+
+struct PortalResponseState {
+  std::string request_path;
+  bool received = false;
+  DBusMessage* message = nullptr;
+};
+
+DBusHandlerResult HandlePortalResponseSignal(DBusConnection* connection,
+                                             DBusMessage* message,
+                                             void* user_data) {
+  (void)connection;
+  auto* state = static_cast<PortalResponseState*>(user_data);
+  if (!state || !message) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  if (!dbus_message_is_signal(message, kPortalRequestInterface, "Response")) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  const char* path = dbus_message_get_path(message);
+  if (!path || state->request_path != path) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  if (state->message) {
+    dbus_message_unref(state->message);
+    state->message = nullptr;
+  }
+
+  state->message = dbus_message_ref(message);
+  state->received = true;
+  return DBUS_HANDLER_RESULT_HANDLED;
+}
+
+DBusMessage* WaitForPortalResponse(DBusConnection* connection,
+                                   const std::string& request_path,
+                                   int timeout_ms = 120000) {
+  if (!connection || request_path.empty()) {
+    return nullptr;
+  }
+
+  PortalResponseState state;
+  state.request_path = request_path;
+
+  DBusError error;
+  dbus_error_init(&error);
+
+  const std::string match_rule =
+      "type='signal',interface='" + std::string(kPortalRequestInterface) +
+      "',member='Response',path='" + request_path + "'";
+  dbus_bus_add_match(connection, match_rule.c_str(), &error);
+  if (dbus_error_is_set(&error)) {
+    LogDbusError("dbus_bus_add_match", &error);
+    dbus_error_free(&error);
+    return nullptr;
+  }
+
+  dbus_connection_add_filter(connection, HandlePortalResponseSignal, &state,
+                             nullptr);
+
+  auto deadline =
+      std::chrono::steady_clock::now() + std::chrono::milliseconds(timeout_ms);
+  while (!state.received && std::chrono::steady_clock::now() < deadline) {
+    dbus_connection_read_write(connection, 100);
+    while (dbus_connection_dispatch(connection) == DBUS_DISPATCH_DATA_REMAINS) {
+    }
+  }
+
+  dbus_connection_remove_filter(connection, HandlePortalResponseSignal, &state);
+
+  DBusError remove_error;
+  dbus_error_init(&remove_error);
+  dbus_bus_remove_match(connection, match_rule.c_str(), &remove_error);
+  if (dbus_error_is_set(&remove_error)) {
+    dbus_error_free(&remove_error);
+  }
+
+  return state.message;
+}
+
+bool ExtractRequestPath(DBusMessage* reply, std::string* request_path) {
+  if (!reply || !request_path) {
+    return false;
+  }
+
+  const char* path = nullptr;
+  DBusError error;
+  dbus_error_init(&error);
+  const dbus_bool_t ok = dbus_message_get_args(
+      reply, &error, DBUS_TYPE_OBJECT_PATH, &path, DBUS_TYPE_INVALID);
+  if (!ok || !path) {
+    LogDbusError("dbus_message_get_args(request_path)", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  *request_path = path;
+  return true;
+}
+
+bool ExtractPortalResponse(DBusMessage* message, uint32_t* response_code,
+                           DBusMessageIter* results_array) {
+  if (!message || !response_code || !results_array) {
+    return false;
+  }
+
+  DBusMessageIter iter;
+  if (!dbus_message_iter_init(message, &iter) ||
+      dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_UINT32) {
+    return false;
+  }
+
+  dbus_message_iter_get_basic(&iter, response_code);
+  if (!dbus_message_iter_next(&iter) ||
+      dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_ARRAY) {
+    return false;
+  }
+
+  *results_array = iter;
+  return true;
+}
+
+bool SendPortalRequestAndHandleResponse(
+    DBusConnection* connection, const char* interface_name,
+    const char* method_name, const char* action_name,
+    const std::function<bool(DBusMessage*)>& append_message_args,
+    const std::function<bool(uint32_t, DBusMessageIter*)>& handle_results,
+    std::string* request_path_out = nullptr) {
+  if (!connection || !interface_name || interface_name[0] == '\0' ||
+      !method_name || method_name[0] == '\0') {
+    return false;
+  }
+
+  DBusMessage* message = dbus_message_new_method_call(
+      kPortalBusName, kPortalObjectPath, interface_name, method_name);
+  if (!message) {
+    LOG_ERROR("Failed to allocate {} message", method_name);
+    return false;
+  }
+
+  if (append_message_args && !append_message_args(message)) {
+    dbus_message_unref(message);
+    LOG_ERROR("{} arguments are malformed", method_name);
+    return false;
+  }
+
+  DBusError error;
+  dbus_error_init(&error);
+  DBusMessage* reply =
+      dbus_connection_send_with_reply_and_block(connection, message, -1, &error);
+  dbus_message_unref(message);
+  if (!reply) {
+    LogDbusError(action_name ? action_name : method_name, &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  std::string request_path;
+  const bool got_request_path = ExtractRequestPath(reply, &request_path);
+  dbus_message_unref(reply);
+  if (!got_request_path) {
+    return false;
+  }
+  if (request_path_out) {
+    *request_path_out = request_path;
+  }
+
+  DBusMessage* response = WaitForPortalResponse(connection, request_path);
+  if (!response) {
+    LOG_ERROR("Timed out waiting for {} response", method_name);
+    return false;
+  }
+
+  uint32_t response_code = 1;
+  DBusMessageIter results;
+  const bool parsed = ExtractPortalResponse(response, &response_code, &results);
+  if (!parsed) {
+    dbus_message_unref(response);
+    LOG_ERROR("{} response was malformed", method_name);
+    return false;
+  }
+
+  const bool ok = handle_results ? handle_results(response_code, &results)
+                                 : (response_code == 0);
+  dbus_message_unref(response);
+  return ok;
+}
+
+}  // namespace
+#endif
+
+bool PlatformKeyboardCapturer::InitWaylandPortal() {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  CleanupWaylandPortal();
+
+  DBusError error;
+  dbus_error_init(&error);
+
+  DBusConnection* check_connection = dbus_bus_get(DBUS_BUS_SESSION, &error);
+  if (!check_connection) {
+    LogDbusError("dbus_bus_get", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  const dbus_bool_t has_owner =
+      dbus_bus_name_has_owner(check_connection, kPortalBusName, &error);
+  if (dbus_error_is_set(&error)) {
+    LogDbusError("dbus_bus_name_has_owner", &error);
+    dbus_error_free(&error);
+    dbus_connection_unref(check_connection);
+    return false;
+  }
+  dbus_connection_unref(check_connection);
+
+  if (!has_owner) {
+    LOG_ERROR("xdg-desktop-portal is not available on session bus");
+    return false;
+  }
+
+  dbus_connection_ = dbus_bus_get_private(DBUS_BUS_SESSION, &error);
+  if (!dbus_connection_) {
+    LogDbusError("dbus_bus_get_private", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+  dbus_connection_set_exit_on_disconnect(dbus_connection_, FALSE);
+
+  const std::string session_handle_token =
+      MakeToken("crossdesk_keyboard_session");
+  std::string request_path;
+  const bool create_ok = SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "CreateSession",
+      "CreateSession",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryString(&options, "session_handle_token",
+                              session_handle_token);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_keyboard_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      [&](uint32_t response_code, DBusMessageIter* results) {
+        if (response_code != 0) {
+          LOG_ERROR("RemoteDesktop.CreateSession denied, response={}",
+                    response_code);
+          return false;
+        }
+
+        DBusMessageIter dict;
+        dbus_message_iter_recurse(results, &dict);
+        while (dbus_message_iter_get_arg_type(&dict) != DBUS_TYPE_INVALID) {
+          if (dbus_message_iter_get_arg_type(&dict) == DBUS_TYPE_DICT_ENTRY) {
+            DBusMessageIter entry;
+            dbus_message_iter_recurse(&dict, &entry);
+
+            const char* key = nullptr;
+            dbus_message_iter_get_basic(&entry, &key);
+            if (key && dbus_message_iter_next(&entry) &&
+                dbus_message_iter_get_arg_type(&entry) == DBUS_TYPE_VARIANT &&
+                strcmp(key, "session_handle") == 0) {
+              DBusMessageIter variant;
+              std::string parsed_handle;
+              dbus_message_iter_recurse(&entry, &variant);
+              if (ReadPathLikeVariant(&variant, &parsed_handle) &&
+                  !parsed_handle.empty()) {
+                wayland_session_handle_ = parsed_handle;
+                break;
+              }
+            }
+          }
+          dbus_message_iter_next(&dict);
+        }
+        return true;
+      },
+      &request_path);
+
+  if (!create_ok) {
+    CleanupWaylandPortal();
+    return false;
+  }
+
+  if (wayland_session_handle_.empty()) {
+    wayland_session_handle_ =
+        BuildSessionHandleFromRequestPath(request_path, session_handle_token);
+  }
+
+  if (wayland_session_handle_.empty()) {
+    LOG_ERROR("RemoteDesktop.CreateSession did not return session handle");
+    CleanupWaylandPortal();
+    return false;
+  }
+
+  const char* session_handle = wayland_session_handle_.c_str();
+  const bool select_ok = SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "SelectDevices",
+      "SelectDevices",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryUint32(&options, "types", kRemoteDesktopDeviceKeyboard);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_keyboard_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      [](uint32_t response_code, DBusMessageIter*) {
+        if (response_code != 0) {
+          LOG_ERROR("RemoteDesktop.SelectDevices denied, response={}",
+                    response_code);
+          return false;
+        }
+        return true;
+      });
+
+  if (!select_ok) {
+    CleanupWaylandPortal();
+    return false;
+  }
+
+  const char* parent_window = "";
+  bool keyboard_granted = false;
+  const bool start_ok = SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "Start", "Start",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &parent_window);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_keyboard_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      [&](uint32_t response_code, DBusMessageIter* results) {
+        if (response_code != 0) {
+          LOG_ERROR("RemoteDesktop.Start denied, response={}", response_code);
+          return false;
+        }
+
+        uint32_t granted_devices = 0;
+        DBusMessageIter dict;
+        dbus_message_iter_recurse(results, &dict);
+        while (dbus_message_iter_get_arg_type(&dict) != DBUS_TYPE_INVALID) {
+          if (dbus_message_iter_get_arg_type(&dict) == DBUS_TYPE_DICT_ENTRY) {
+            DBusMessageIter entry;
+            dbus_message_iter_recurse(&dict, &entry);
+
+            const char* key = nullptr;
+            dbus_message_iter_get_basic(&entry, &key);
+            if (key && dbus_message_iter_next(&entry) &&
+                dbus_message_iter_get_arg_type(&entry) == DBUS_TYPE_VARIANT) {
+              DBusMessageIter variant;
+              dbus_message_iter_recurse(&entry, &variant);
+              if (strcmp(key, "devices") == 0) {
+                ReadUint32Like(&variant, &granted_devices);
+              }
+            }
+          }
+          dbus_message_iter_next(&dict);
+        }
+
+        keyboard_granted =
+            (granted_devices & kRemoteDesktopDeviceKeyboard) != 0;
+        if (!keyboard_granted) {
+          LOG_ERROR(
+              "RemoteDesktop.Start granted devices mask={}, keyboard not allowed",
+              granted_devices);
+          return false;
+        }
+        return true;
+      });
+
+  if (!start_ok) {
+    CleanupWaylandPortal();
+    return false;
+  }
+
+  if (!keyboard_granted) {
+    LOG_ERROR("RemoteDesktop session started without keyboard permission");
+    CleanupWaylandPortal();
+    return false;
+  }
+
+  return true;
+#else
+  return false;
+#endif
+}
+
+void PlatformKeyboardCapturer::CleanupWaylandPortal() {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  if (dbus_connection_) {
+    CloseWaylandPortalSessionAndConnection(dbus_connection_,
+                                           wayland_session_handle_,
+                                           "RemoteDesktop.Session.Close");
+    dbus_connection_ = nullptr;
+  }
+#endif
+
+  use_wayland_portal_ = false;
+  wayland_session_handle_.clear();
+}
+
+int PlatformKeyboardCapturer::SendWaylandKeyboardCommand(int key_code, bool is_down,
+                                                 uint32_t scan_code,
+                                                 bool extended) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  if (!dbus_connection_ || wayland_session_handle_.empty()) {
+    return -1;
+  }
+
+  const uint32_t key_state = is_down ? kKeyboardPressed : kKeyboardReleased;
+
+  const int evdev_keycode =
+      ResolveLinuxEvdevKeycodeFromWindowsKey(key_code, scan_code, extended);
+  if (evdev_keycode >= 0 &&
+      NotifyWaylandKeyboardKeycode(evdev_keycode, key_state)) {
+    return 0;
+  }
+
+  const auto key_it = vkCodeToX11KeySym.find(key_code);
+  if (key_it == vkCodeToX11KeySym.end()) {
+    if (evdev_keycode >= 0) {
+      LOG_ERROR(
+          "Failed to send Wayland keyboard keycode event, vk_code={}, "
+          "evdev_keycode={}, is_down={}",
+          key_code, evdev_keycode, is_down);
+      return -3;
+    }
+    return 0;
+  }
+
+  // Prefer keycode injection to preserve physical-key semantics and avoid
+  // implicit Shift interpretation for uppercase keysyms.
+  if (display_) {
+    std::lock_guard<std::mutex> lock(x11_injection_mutex_);
+    const int keysym = key_it->second;
+    const KeyCode x11_keycode =
+        XKeysymToKeycode(display_, static_cast<KeySym>(keysym));
+    if (x11_keycode > 8) {
+      const int x11_evdev_keycode = static_cast<int>(x11_keycode) - 8;
+      if (NotifyWaylandKeyboardKeycode(x11_evdev_keycode, key_state)) {
+        return 0;
+      }
+    }
+  }
+
+  const int keysym = key_it->second;
+  const int fallback_keysym = NormalizeFallbackKeysym(keysym);
+  if (NotifyWaylandKeyboardKeysym(fallback_keysym, key_state)) {
+    return 0;
+  }
+
+  LOG_ERROR("Failed to send Wayland keyboard event, vk_code={}, is_down={}",
+            key_code, is_down);
+  return -3;
+#else
+  (void)key_code;
+  (void)is_down;
+  (void)scan_code;
+  (void)extended;
+  return -1;
+#endif
+}
+
+bool PlatformKeyboardCapturer::NotifyWaylandKeyboardKeysym(int keysym, uint32_t state) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  return SendWaylandPortalVoidCall(
+      "NotifyKeyboardKeysym", [&](DBusMessageIter* iter) {
+        const char* session_handle = wayland_session_handle_.c_str();
+        int32_t key_sym = keysym;
+        uint32_t key_state = state;
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        AppendEmptyOptionsDict(iter);
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_INT32, &key_sym);
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT32, &key_state);
+      });
+#else
+  (void)keysym;
+  (void)state;
+  return false;
+#endif
+}
+
+bool PlatformKeyboardCapturer::NotifyWaylandKeyboardKeycode(int keycode,
+                                                    uint32_t state) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  return SendWaylandPortalVoidCall(
+      "NotifyKeyboardKeycode", [&](DBusMessageIter* iter) {
+        const char* session_handle = wayland_session_handle_.c_str();
+        int32_t key_code = keycode;
+        uint32_t key_state = state;
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        AppendEmptyOptionsDict(iter);
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_INT32, &key_code);
+        dbus_message_iter_append_basic(iter, DBUS_TYPE_UINT32, &key_state);
+      });
+#else
+  (void)keycode;
+  (void)state;
+  return false;
+#endif
+}
+
+bool PlatformKeyboardCapturer::SendWaylandPortalVoidCall(
+    const char* method_name,
+    const std::function<void(DBusMessageIter*)>& append_args) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  if (!dbus_connection_ || !method_name || method_name[0] == '\0') {
+    return false;
+  }
+
+  DBusMessage* message = dbus_message_new_method_call(
+      kPortalBusName, kPortalObjectPath, kPortalRemoteDesktopInterface,
+      method_name);
+  if (!message) {
+    LOG_ERROR("Failed to allocate {} message", method_name);
+    return false;
+  }
+
+  DBusMessageIter iter;
+  dbus_message_iter_init_append(message, &iter);
+  if (append_args) {
+    append_args(&iter);
+  }
+
+  DBusError error;
+  dbus_error_init(&error);
+  DBusMessage* reply = dbus_connection_send_with_reply_and_block(
+      dbus_connection_, message, 5000, &error);
+  dbus_message_unref(message);
+  if (!reply) {
+    LogDbusError(method_name, &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  if (dbus_message_get_type(reply) == DBUS_MESSAGE_TYPE_ERROR) {
+    const char* error_name = dbus_message_get_error_name(reply);
+    LOG_ERROR("{} returned DBus error: {}", method_name,
+              error_name ? error_name : "unknown");
+    dbus_message_unref(reply);
+    return false;
+  }
+
+  dbus_message_unref(reply);
+  return true;
+#else
+  (void)method_name;
+  (void)append_args;
+  return false;
+#endif
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/input/linux_evdev_keycode.h

@@ -0,0 +1,295 @@
+#ifndef _LINUX_EVDEV_KEYCODE_H_
+#define _LINUX_EVDEV_KEYCODE_H_
+
+#include <linux/input-event-codes.h>
+
+#include <cstdint>
+
+namespace crossdesk {
+
+inline int LinuxEvdevKeycodeFromWindowsScanCode(uint32_t scan_code,
+                                                bool extended) {
+  const uint32_t base_scan_code = scan_code & 0xFFu;
+  if (base_scan_code == 0) {
+    return -1;
+  }
+
+  if (extended) {
+    switch (base_scan_code) {
+      case 0x1C:
+        return KEY_KPENTER;
+      case 0x1D:
+        return KEY_RIGHTCTRL;
+      case 0x35:
+        return KEY_KPSLASH;
+      case 0x38:
+        return KEY_RIGHTALT;
+      case 0x47:
+        return KEY_HOME;
+      case 0x48:
+        return KEY_UP;
+      case 0x49:
+        return KEY_PAGEUP;
+      case 0x4B:
+        return KEY_LEFT;
+      case 0x4D:
+        return KEY_RIGHT;
+      case 0x4F:
+        return KEY_END;
+      case 0x50:
+        return KEY_DOWN;
+      case 0x51:
+        return KEY_PAGEDOWN;
+      case 0x52:
+        return KEY_INSERT;
+      case 0x53:
+        return KEY_DELETE;
+      case 0x5B:
+        return KEY_LEFTMETA;
+      case 0x5C:
+        return KEY_RIGHTMETA;
+      default:
+        return -1;
+    }
+  }
+
+  // For the common PC set-1 keys, Linux evdev key codes intentionally line up
+  // with the low byte of the Windows scan code.
+  if ((base_scan_code >= 0x01 && base_scan_code <= 0x53) ||
+      base_scan_code == 0x56 || base_scan_code == 0x57 ||
+      base_scan_code == 0x58) {
+    return static_cast<int>(base_scan_code);
+  }
+
+  return -1;
+}
+
+inline int LinuxEvdevKeycodeFromWindowsVk(int key_code) {
+  switch (key_code) {
+    case 0x08:
+      return KEY_BACKSPACE;
+    case 0x09:
+      return KEY_TAB;
+    case 0x0D:
+      return KEY_ENTER;
+    case 0x10:
+    case 0xA0:
+      return KEY_LEFTSHIFT;
+    case 0x11:
+    case 0xA2:
+      return KEY_LEFTCTRL;
+    case 0x12:
+    case 0xA4:
+      return KEY_LEFTALT;
+    case 0x13:
+      return KEY_PAUSE;
+    case 0x14:
+      return KEY_CAPSLOCK;
+    case 0x1B:
+      return KEY_ESC;
+    case 0x20:
+      return KEY_SPACE;
+    case 0x21:
+      return KEY_PAGEUP;
+    case 0x22:
+      return KEY_PAGEDOWN;
+    case 0x23:
+      return KEY_END;
+    case 0x24:
+      return KEY_HOME;
+    case 0x25:
+      return KEY_LEFT;
+    case 0x26:
+      return KEY_UP;
+    case 0x27:
+      return KEY_RIGHT;
+    case 0x28:
+      return KEY_DOWN;
+    case 0x2C:
+      return KEY_SYSRQ;
+    case 0x2D:
+      return KEY_INSERT;
+    case 0x2E:
+      return KEY_DELETE;
+    case 0x30:
+      return KEY_0;
+    case 0x31:
+      return KEY_1;
+    case 0x32:
+      return KEY_2;
+    case 0x33:
+      return KEY_3;
+    case 0x34:
+      return KEY_4;
+    case 0x35:
+      return KEY_5;
+    case 0x36:
+      return KEY_6;
+    case 0x37:
+      return KEY_7;
+    case 0x38:
+      return KEY_8;
+    case 0x39:
+      return KEY_9;
+    case 0x41:
+      return KEY_A;
+    case 0x42:
+      return KEY_B;
+    case 0x43:
+      return KEY_C;
+    case 0x44:
+      return KEY_D;
+    case 0x45:
+      return KEY_E;
+    case 0x46:
+      return KEY_F;
+    case 0x47:
+      return KEY_G;
+    case 0x48:
+      return KEY_H;
+    case 0x49:
+      return KEY_I;
+    case 0x4A:
+      return KEY_J;
+    case 0x4B:
+      return KEY_K;
+    case 0x4C:
+      return KEY_L;
+    case 0x4D:
+      return KEY_M;
+    case 0x4E:
+      return KEY_N;
+    case 0x4F:
+      return KEY_O;
+    case 0x50:
+      return KEY_P;
+    case 0x51:
+      return KEY_Q;
+    case 0x52:
+      return KEY_R;
+    case 0x53:
+      return KEY_S;
+    case 0x54:
+      return KEY_T;
+    case 0x55:
+      return KEY_U;
+    case 0x56:
+      return KEY_V;
+    case 0x57:
+      return KEY_W;
+    case 0x58:
+      return KEY_X;
+    case 0x59:
+      return KEY_Y;
+    case 0x5A:
+      return KEY_Z;
+    case 0x5B:
+      return KEY_LEFTMETA;
+    case 0x5C:
+      return KEY_RIGHTMETA;
+    case 0x60:
+      return KEY_KP0;
+    case 0x61:
+      return KEY_KP1;
+    case 0x62:
+      return KEY_KP2;
+    case 0x63:
+      return KEY_KP3;
+    case 0x64:
+      return KEY_KP4;
+    case 0x65:
+      return KEY_KP5;
+    case 0x66:
+      return KEY_KP6;
+    case 0x67:
+      return KEY_KP7;
+    case 0x68:
+      return KEY_KP8;
+    case 0x69:
+      return KEY_KP9;
+    case 0x6A:
+      return KEY_KPASTERISK;
+    case 0x6B:
+      return KEY_KPPLUS;
+    case 0x6D:
+      return KEY_KPMINUS;
+    case 0x6E:
+      return KEY_KPDOT;
+    case 0x6F:
+      return KEY_KPSLASH;
+    case 0x70:
+      return KEY_F1;
+    case 0x71:
+      return KEY_F2;
+    case 0x72:
+      return KEY_F3;
+    case 0x73:
+      return KEY_F4;
+    case 0x74:
+      return KEY_F5;
+    case 0x75:
+      return KEY_F6;
+    case 0x76:
+      return KEY_F7;
+    case 0x77:
+      return KEY_F8;
+    case 0x78:
+      return KEY_F9;
+    case 0x79:
+      return KEY_F10;
+    case 0x7A:
+      return KEY_F11;
+    case 0x7B:
+      return KEY_F12;
+    case 0x90:
+      return KEY_NUMLOCK;
+    case 0x91:
+      return KEY_SCROLLLOCK;
+    case 0xA1:
+      return KEY_RIGHTSHIFT;
+    case 0xA3:
+      return KEY_RIGHTCTRL;
+    case 0xA5:
+      return KEY_RIGHTALT;
+    case 0xBA:
+      return KEY_SEMICOLON;
+    case 0xBB:
+      return KEY_EQUAL;
+    case 0xBC:
+      return KEY_COMMA;
+    case 0xBD:
+      return KEY_MINUS;
+    case 0xBE:
+      return KEY_DOT;
+    case 0xBF:
+      return KEY_SLASH;
+    case 0xC0:
+      return KEY_GRAVE;
+    case 0xDB:
+      return KEY_LEFTBRACE;
+    case 0xDC:
+      return KEY_BACKSLASH;
+    case 0xDD:
+      return KEY_RIGHTBRACE;
+    case 0xDE:
+      return KEY_APOSTROPHE;
+    default:
+      return -1;
+  }
+}
+
+inline int ResolveLinuxEvdevKeycodeFromWindowsKey(int key_code,
+                                                  uint32_t scan_code,
+                                                  bool extended) {
+  const int scan_keycode =
+      LinuxEvdevKeycodeFromWindowsScanCode(scan_code, extended);
+  if (scan_keycode >= 0) {
+    return scan_keycode;
+  }
+
+  return LinuxEvdevKeycodeFromWindowsVk(key_code);
+}
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/input/mouse/mouse_controller.cpp

@@ -0,0 +1,201 @@
+#include "mouse_controller.h"
+
+#include <remote_action.h>
+
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <X11/extensions/XTest.h>
+#include <unistd.h>
+
+#include "platform.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+PlatformMouseController::PlatformMouseController() {}
+
+PlatformMouseController::~PlatformMouseController() { Destroy(); }
+
+int PlatformMouseController::Init(std::vector<DisplayInfo> display_info_list) {
+  display_info_list_ = display_info_list;
+
+  if (IsWaylandSession()) {
+    if (InitWaylandPortal()) {
+      use_wayland_portal_ = true;
+      LOG_INFO("Mouse controller initialized with Wayland portal backend");
+      return 0;
+    }
+    LOG_WARN(
+        "Wayland mouse control init failed, falling back to X11/XTest backend");
+  }
+
+  display_ = XOpenDisplay(NULL);
+  if (!display_) {
+    LOG_ERROR("Cannot connect to X server");
+    return -1;
+  }
+
+  root_ = DefaultRootWindow(display_);
+
+  int event_base, error_base, major_version, minor_version;
+  if (!XTestQueryExtension(display_, &event_base, &error_base, &major_version,
+                           &minor_version)) {
+    LOG_ERROR("XTest extension not available");
+    XCloseDisplay(display_);
+    display_ = nullptr;
+    return -2;
+  }
+
+  return 0;
+}
+
+void PlatformMouseController::UpdateDisplayInfoList(
+    const std::vector<DisplayInfo>& display_info_list) {
+  if (display_info_list.empty()) {
+    return;
+  }
+
+  display_info_list_ = display_info_list;
+  if (use_wayland_portal_) {
+    OnWaylandDisplayInfoListUpdated();
+  }
+
+  if (last_display_index_ < 0 ||
+      last_display_index_ >= static_cast<int>(display_info_list_.size())) {
+    last_display_index_ = -1;
+    last_norm_x_ = -1.0;
+    last_norm_y_ = -1.0;
+  }
+}
+
+int PlatformMouseController::Destroy() {
+  CleanupWaylandPortal();
+
+  if (display_) {
+    XCloseDisplay(display_);
+    display_ = nullptr;
+  }
+
+  return 0;
+}
+
+int PlatformMouseController::SendMouseCommand(RemoteAction remote_action,
+                                      int display_index) {
+  if (remote_action.type != ControlType::mouse) {
+    return 0;
+  }
+
+  if (use_wayland_portal_) {
+    return SendWaylandMouseCommand(remote_action, display_index);
+  }
+
+  if (!display_) {
+    LOG_ERROR("X11 display not initialized");
+    return -1;
+  }
+
+  switch (remote_action.type) {
+    case mouse:
+      switch (remote_action.m.flag) {
+        case MouseFlag::move: {
+          if (display_index < 0 ||
+              display_index >= static_cast<int>(display_info_list_.size())) {
+            LOG_ERROR("Invalid display index: {}", display_index);
+            return -2;
+          }
+
+          SetMousePosition(
+              static_cast<int>(remote_action.m.x *
+                                   display_info_list_[display_index].width +
+                               display_info_list_[display_index].left),
+              static_cast<int>(remote_action.m.y *
+                                   display_info_list_[display_index].height +
+                               display_info_list_[display_index].top));
+          break;
+        }
+        case MouseFlag::left_down:
+          XTestFakeButtonEvent(display_, 1, True, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::left_up:
+          XTestFakeButtonEvent(display_, 1, False, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::right_down:
+          XTestFakeButtonEvent(display_, 3, True, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::right_up:
+          XTestFakeButtonEvent(display_, 3, False, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::middle_down:
+          XTestFakeButtonEvent(display_, 2, True, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::middle_up:
+          XTestFakeButtonEvent(display_, 2, False, CurrentTime);
+          XFlush(display_);
+          break;
+        case MouseFlag::wheel_vertical: {
+          if (remote_action.m.s > 0) {
+            SimulateMouseWheel(4, remote_action.m.s);
+          } else if (remote_action.m.s < 0) {
+            SimulateMouseWheel(5, -remote_action.m.s);
+          }
+          break;
+        }
+        case MouseFlag::wheel_horizontal: {
+          if (remote_action.m.s > 0) {
+            SimulateMouseWheel(6, remote_action.m.s);
+          } else if (remote_action.m.s < 0) {
+            SimulateMouseWheel(7, -remote_action.m.s);
+          }
+          break;
+        }
+      }
+      break;
+    default:
+      break;
+  }
+
+  return 0;
+}
+
+void PlatformMouseController::SetMousePosition(int x, int y) {
+  if (!display_) {
+    return;
+  }
+  XWarpPointer(display_, None, root_, 0, 0, 0, 0, x, y);
+  XFlush(display_);
+}
+
+void PlatformMouseController::SimulateKeyDown(int kval) {
+  if (!display_) {
+    return;
+  }
+  XTestFakeKeyEvent(display_, kval, True, CurrentTime);
+  XFlush(display_);
+}
+
+void PlatformMouseController::SimulateKeyUp(int kval) {
+  if (!display_) {
+    return;
+  }
+  XTestFakeKeyEvent(display_, kval, False, CurrentTime);
+  XFlush(display_);
+}
+
+void PlatformMouseController::SimulateMouseWheel(int direction_button, int count) {
+  if (!display_) {
+    return;
+  }
+
+  for (int i = 0; i < count; ++i) {
+    XTestFakeButtonEvent(display_, direction_button, True, CurrentTime);
+    XTestFakeButtonEvent(display_, direction_button, False, CurrentTime);
+  }
+  XFlush(display_);
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/input/mouse/mouse_controller.h

@@ -0,0 +1,80 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2025-05-07
+ * Copyright (c) 2025 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _MOUSE_CONTROLLER_H_
+#define _MOUSE_CONTROLLER_H_
+
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <vector>
+
+#include <remote_action.h>
+
+#include "device_controller.h"
+#include "display_info.h"
+
+struct DBusConnection;
+struct DBusMessageIter;
+struct _XDisplay;
+
+namespace crossdesk {
+
+class PlatformMouseController final : public MouseController {
+ public:
+  PlatformMouseController();
+  virtual ~PlatformMouseController();
+
+ public:
+  virtual int Init(std::vector<DisplayInfo> display_info_list);
+  virtual int Destroy();
+  virtual int SendMouseCommand(RemoteAction remote_action, int display_index);
+  void UpdateDisplayInfoList(const std::vector<DisplayInfo>& display_info_list);
+
+ private:
+  void SimulateKeyDown(int kval);
+  void SimulateKeyUp(int kval);
+  void SetMousePosition(int x, int y);
+  void SimulateMouseWheel(int direction_button, int count);
+  bool InitWaylandPortal();
+  void CleanupWaylandPortal();
+  int SendWaylandMouseCommand(RemoteAction remote_action, int display_index);
+  void OnWaylandDisplayInfoListUpdated();
+  bool NotifyWaylandPointerMotion(double dx, double dy);
+  bool NotifyWaylandPointerMotionAbsolute(uint32_t stream, double x, double y);
+  bool NotifyWaylandPointerButton(int button, uint32_t state);
+  bool NotifyWaylandPointerAxisDiscrete(uint32_t axis, int32_t steps);
+  bool SendWaylandPortalVoidCall(
+      const char* method_name,
+      const std::function<void(DBusMessageIter*)>& append_args);
+
+  enum class WaylandAbsoluteMode { kUnknown, kPixels, kNormalized, kDisabled };
+
+  _XDisplay* display_ = nullptr;
+  unsigned long root_ = 0;
+  std::vector<DisplayInfo> display_info_list_;
+  int screen_width_ = 0;
+  int screen_height_ = 0;
+  bool use_wayland_portal_ = false;
+
+  DBusConnection* dbus_connection_ = nullptr;
+  std::string wayland_session_handle_;
+  int last_display_index_ = -1;
+  double last_norm_x_ = -1.0;
+  double last_norm_y_ = -1.0;
+  bool logged_wayland_display_info_ = false;
+  uintptr_t last_logged_wayland_stream_ = 0;
+  int last_logged_wayland_width_ = 0;
+  int last_logged_wayland_height_ = 0;
+  WaylandAbsoluteMode wayland_absolute_mode_ = WaylandAbsoluteMode::kUnknown;
+  bool wayland_absolute_disabled_logged_ = false;
+  uint32_t wayland_absolute_stream_id_ = 0;
+  int wayland_portal_space_width_ = 0;
+  int wayland_portal_space_height_ = 0;
+  bool using_shared_wayland_session_ = false;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/linux/path_backend.cpp

@@ -0,0 +1,51 @@
+#include "platform/path_backend.h"
+
+#include <limits.h>
+#include <unistd.h>
+
+#include <cstdlib>
+#include <vector>
+
+namespace crossdesk::platform {
+namespace {
+
+std::filesystem::path Home() {
+  const char* value = std::getenv("HOME");
+  return value ? std::filesystem::path(value) : std::filesystem::path();
+}
+
+std::filesystem::path EnvOrDefault(const char* name,
+                                   const std::filesystem::path& fallback) {
+  const char* value = std::getenv(name);
+  return value ? std::filesystem::path(value) : fallback;
+}
+
+}  // namespace
+
+std::filesystem::path GetExecutableDirectory() {
+  std::vector<char> buffer(PATH_MAX);
+  while (true) {
+    const ssize_t length =
+        readlink("/proc/self/exe", buffer.data(), buffer.size() - 1);
+    if (length <= 0) return {};
+    if (static_cast<size_t>(length) < buffer.size() - 1) {
+      buffer[static_cast<size_t>(length)] = '\0';
+      return std::filesystem::path(buffer.data()).parent_path();
+    }
+    buffer.resize(buffer.size() * 2);
+  }
+}
+
+std::filesystem::path GetConfigPath(const std::string& app_name) {
+  return EnvOrDefault("XDG_CONFIG_HOME", Home() / ".config") / app_name;
+}
+
+std::filesystem::path GetCachePath(const std::string& app_name) {
+  return EnvOrDefault("XDG_CACHE_HOME", Home() / ".cache") / app_name;
+}
+
+std::filesystem::path GetLogPath(const std::string& app_name) {
+  return GetCachePath(app_name) / "logs";
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_drm.cpp

@@ -0,0 +1,575 @@
+#include "screen_capturer_drm.h"
+
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM && \
+    defined(__has_include) && __has_include(<xf86drm.h>) && \
+    __has_include(<xf86drmMode.h>)
+#define CROSSDESK_DRM_BUILD_ENABLED 1
+#include <xf86drm.h>
+#include <xf86drmMode.h>
+#elif defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM && \
+    defined(__has_include) && __has_include(<libdrm/xf86drm.h>) && \
+    __has_include(<libdrm/xf86drmMode.h>)
+#define CROSSDESK_DRM_BUILD_ENABLED 1
+#include <libdrm/xf86drm.h>
+#include <libdrm/xf86drmMode.h>
+#else
+#define CROSSDESK_DRM_BUILD_ENABLED 0
+#endif
+
+#if CROSSDESK_DRM_BUILD_ENABLED
+
+#include <fcntl.h>
+#include <sys/mman.h>
+#include <unistd.h>
+
+#include <algorithm>
+#include <chrono>
+#include <thread>
+
+#include <display_stream_id.h>
+#include "libyuv.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+namespace {
+
+constexpr int kMaxDrmCards = 16;
+
+const char* ConnectorTypeName(uint32_t type) {
+  switch (type) {
+    case DRM_MODE_CONNECTOR_VGA:
+      return "VGA";
+    case DRM_MODE_CONNECTOR_DVII:
+      return "DVI-I";
+    case DRM_MODE_CONNECTOR_DVID:
+      return "DVI-D";
+    case DRM_MODE_CONNECTOR_DVIA:
+      return "DVI-A";
+    case DRM_MODE_CONNECTOR_HDMIA:
+      return "HDMI-A";
+    case DRM_MODE_CONNECTOR_HDMIB:
+      return "HDMI-B";
+    case DRM_MODE_CONNECTOR_DisplayPort:
+      return "DP";
+    case DRM_MODE_CONNECTOR_eDP:
+      return "eDP";
+    case DRM_MODE_CONNECTOR_LVDS:
+      return "LVDS";
+#ifdef DRM_MODE_CONNECTOR_VIRTUAL
+    case DRM_MODE_CONNECTOR_VIRTUAL:
+      return "Virtual";
+#endif
+    default:
+      return "Display";
+  }
+}
+
+}  // namespace
+
+ScreenCapturerDrm::ScreenCapturerDrm() {}
+
+ScreenCapturerDrm::~ScreenCapturerDrm() { Destroy(); }
+
+int ScreenCapturerDrm::Init(const int fps, cb_desktop_data cb) {
+  Destroy();
+
+  if (!cb) {
+    LOG_ERROR("DRM screen capturer callback is null");
+    return -1;
+  }
+
+  fps_ = std::max(1, fps);
+  callback_ = cb;
+  monitor_index_ = 0;
+  initial_monitor_index_ = 0;
+  consecutive_failures_ = 0;
+  display_info_list_.clear();
+  outputs_.clear();
+  y_plane_.clear();
+  uv_plane_.clear();
+
+  if (!DiscoverOutputs()) {
+    LOG_ERROR("DRM screen capturer could not find active outputs");
+    callback_ = nullptr;
+    CloseDevices();
+    return -1;
+  }
+
+  return 0;
+}
+
+int ScreenCapturerDrm::Destroy() {
+  Stop();
+  callback_ = nullptr;
+  display_info_list_.clear();
+  outputs_.clear();
+  y_plane_.clear();
+  uv_plane_.clear();
+  CloseDevices();
+  return 0;
+}
+
+int ScreenCapturerDrm::Start(bool show_cursor) {
+  if (running_) {
+    return 0;
+  }
+
+  if (outputs_.empty()) {
+    LOG_ERROR("DRM screen capturer has no output to capture");
+    return -1;
+  }
+
+  show_cursor_ = show_cursor;
+  paused_ = false;
+
+  int probe_index = monitor_index_.load();
+  if (probe_index < 0 || probe_index >= static_cast<int>(outputs_.size())) {
+    probe_index = 0;
+  }
+
+  if (!CaptureOutputFrame(outputs_[probe_index], false)) {
+    LOG_ERROR("DRM start probe failed on output {}", outputs_[probe_index].name);
+    return -1;
+  }
+
+  running_ = true;
+  thread_ = std::thread([this]() { CaptureLoop(); });
+  return 0;
+}
+
+int ScreenCapturerDrm::Stop() {
+  if (!running_) {
+    return 0;
+  }
+
+  running_ = false;
+  if (thread_.joinable()) {
+    thread_.join();
+  }
+  return 0;
+}
+
+int ScreenCapturerDrm::Pause([[maybe_unused]] int monitor_index) {
+  paused_ = true;
+  return 0;
+}
+
+int ScreenCapturerDrm::Resume([[maybe_unused]] int monitor_index) {
+  paused_ = false;
+  return 0;
+}
+
+int ScreenCapturerDrm::SwitchTo(int monitor_index) {
+  if (monitor_index < 0 ||
+      monitor_index >= static_cast<int>(display_info_list_.size())) {
+    LOG_ERROR("Invalid DRM monitor index: {}", monitor_index);
+    return -1;
+  }
+
+  monitor_index_ = monitor_index;
+  return 0;
+}
+
+int ScreenCapturerDrm::ResetToInitialMonitor() {
+  monitor_index_ = initial_monitor_index_;
+  return 0;
+}
+
+std::vector<DisplayInfo> ScreenCapturerDrm::GetDisplayInfoList() {
+  return display_info_list_;
+}
+
+bool ScreenCapturerDrm::DiscoverOutputs() {
+  for (int card_index = 0; card_index < kMaxDrmCards; ++card_index) {
+    const std::string card_path = "/dev/dri/card" + std::to_string(card_index);
+    const int fd = open(card_path.c_str(), O_RDWR | O_CLOEXEC);
+    if (fd < 0) {
+      continue;
+    }
+
+    drmModeRes* resources = drmModeGetResources(fd);
+    if (!resources) {
+      close(fd);
+      continue;
+    }
+
+    DrmDevice device;
+    device.fd = fd;
+    device.path = card_path;
+    devices_.push_back(device);
+    const int device_slot = static_cast<int>(devices_.size()) - 1;
+    const size_t output_count_before = outputs_.size();
+
+    for (int i = 0; i < resources->count_connectors; ++i) {
+      drmModeConnector* connector =
+          drmModeGetConnector(fd, resources->connectors[i]);
+      if (!connector) {
+        continue;
+      }
+
+      if (connector->connection != DRM_MODE_CONNECTED ||
+          connector->count_modes <= 0) {
+        drmModeFreeConnector(connector);
+        continue;
+      }
+
+      uint32_t crtc_id = 0;
+      if (connector->encoder_id != 0) {
+        drmModeEncoder* encoder = drmModeGetEncoder(fd, connector->encoder_id);
+        if (encoder) {
+          crtc_id = encoder->crtc_id;
+          drmModeFreeEncoder(encoder);
+        }
+      }
+
+      if (crtc_id == 0) {
+        for (int enc_idx = 0; enc_idx < connector->count_encoders; ++enc_idx) {
+          drmModeEncoder* encoder =
+              drmModeGetEncoder(fd, connector->encoders[enc_idx]);
+          if (!encoder) {
+            continue;
+          }
+          if (encoder->crtc_id != 0) {
+            crtc_id = encoder->crtc_id;
+            drmModeFreeEncoder(encoder);
+            break;
+          }
+          drmModeFreeEncoder(encoder);
+        }
+      }
+
+      if (crtc_id == 0) {
+        drmModeFreeConnector(connector);
+        continue;
+      }
+
+      drmModeCrtc* crtc = drmModeGetCrtc(fd, crtc_id);
+      if (!crtc || !crtc->mode_valid || crtc->width <= 0 || crtc->height <= 0) {
+        if (crtc) {
+          drmModeFreeCrtc(crtc);
+        }
+        drmModeFreeConnector(connector);
+        continue;
+      }
+
+      DrmOutput output;
+      output.device_index = device_slot;
+      output.connector_id = connector->connector_id;
+      output.crtc_id = crtc_id;
+      output.left = crtc->x;
+      output.top = crtc->y;
+      output.width = static_cast<int>(crtc->width);
+      output.height = static_cast<int>(crtc->height);
+      output.name = std::string(ConnectorTypeName(connector->connector_type)) +
+                    std::to_string(connector->connector_type_id);
+      output.stream_id = MakeDisplayStreamId(outputs_.size());
+
+      outputs_.push_back(output);
+      display_info_list_.push_back(
+          DisplayInfo(output.name, output.left, output.top,
+                      output.left + output.width, output.top + output.height));
+
+      LOG_INFO("DRM output found: {} on {}, {}x{} @ ({}, {})", output.name,
+               card_path, output.width, output.height, output.left, output.top);
+
+      drmModeFreeCrtc(crtc);
+      drmModeFreeConnector(connector);
+    }
+
+    drmModeFreeResources(resources);
+
+    if (outputs_.size() == output_count_before) {
+      close(fd);
+      devices_.pop_back();
+    }
+  }
+
+  if (outputs_.empty()) {
+    return false;
+  }
+
+  LOG_INFO("DRM screen capturer discovered {} output(s)", outputs_.size());
+  return true;
+}
+
+void ScreenCapturerDrm::CloseDevices() {
+  for (auto& device : devices_) {
+    if (device.fd >= 0) {
+      close(device.fd);
+      device.fd = -1;
+    }
+  }
+  devices_.clear();
+}
+
+void ScreenCapturerDrm::CaptureLoop() {
+  using clock = std::chrono::steady_clock;
+  const auto frame_interval =
+      std::chrono::milliseconds(std::max(1, 1000 / std::max(1, fps_)));
+
+  while (running_) {
+    const auto frame_start = clock::now();
+    if (!paused_) {
+      int index = monitor_index_.load();
+      if (index >= 0 && index < static_cast<int>(outputs_.size())) {
+        const bool ok = CaptureOutputFrame(outputs_[index], true);
+        if (!ok) {
+          ++consecutive_failures_;
+          if (consecutive_failures_ == 1 || consecutive_failures_ % 60 == 0) {
+            LOG_WARN("DRM capture failed (consecutive={})",
+                     consecutive_failures_);
+          }
+        } else {
+          consecutive_failures_ = 0;
+        }
+      }
+    }
+
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+        clock::now() - frame_start);
+    if (elapsed < frame_interval) {
+      std::this_thread::sleep_for(frame_interval - elapsed);
+    }
+  }
+}
+
+bool ScreenCapturerDrm::CaptureOutputFrame(const DrmOutput& output,
+                                           bool emit_callback) {
+  if (output.device_index < 0 ||
+      output.device_index >= static_cast<int>(devices_.size())) {
+    return false;
+  }
+
+  const int fd = devices_[output.device_index].fd;
+  if (fd < 0) {
+    return false;
+  }
+
+  drmModeCrtc* crtc = drmModeGetCrtc(fd, output.crtc_id);
+  if (!crtc) {
+    return false;
+  }
+
+  const uint32_t fb_id = crtc->buffer_id;
+  drmModeFreeCrtc(crtc);
+  if (fb_id == 0) {
+    return false;
+  }
+
+  drmModeFB* fb = drmModeGetFB(fd, fb_id);
+  if (!fb) {
+    return false;
+  }
+
+  const uint32_t handle = fb->handle;
+  const uint32_t pitch = fb->pitch;
+  const int src_width = static_cast<int>(fb->width);
+  const int src_height = static_cast<int>(fb->height);
+  const int bpp = static_cast<int>(fb->bpp);
+  drmModeFreeFB(fb);
+
+  if (handle == 0 || pitch == 0 || src_width <= 1 || src_height <= 1) {
+    return false;
+  }
+
+  if (bpp != 32) {
+    LOG_WARN("DRM capture unsupported bpp: {}", bpp);
+    return false;
+  }
+
+  const size_t map_size =
+      static_cast<size_t>(pitch) * static_cast<size_t>(src_height);
+  uint8_t* mapped_ptr = nullptr;
+  size_t mapped_size = 0;
+  int prime_fd = -1;
+  if (!MapFramebuffer(fd, handle, map_size, &mapped_ptr, &mapped_size,
+                      &prime_fd)) {
+    return false;
+  }
+
+  int capture_width = std::min(src_width, output.width);
+  int capture_height = std::min(src_height, output.height);
+  if (capture_width <= 0 || capture_height <= 0) {
+    capture_width = src_width;
+    capture_height = src_height;
+  }
+
+  capture_width &= ~1;
+  capture_height &= ~1;
+  if (capture_width <= 1 || capture_height <= 1) {
+    UnmapFramebuffer(mapped_ptr, mapped_size, prime_fd);
+    return false;
+  }
+
+  const size_t y_size =
+      static_cast<size_t>(capture_width) * static_cast<size_t>(capture_height);
+  const size_t uv_size = y_size / 2;
+  if (y_plane_.size() != y_size) {
+    y_plane_.resize(y_size);
+  }
+  if (uv_plane_.size() != uv_size) {
+    uv_plane_.resize(uv_size);
+  }
+
+  const int convert_ret =
+      libyuv::ARGBToNV12(mapped_ptr, static_cast<int>(pitch), y_plane_.data(),
+                         capture_width, uv_plane_.data(), capture_width,
+                         capture_width, capture_height);
+
+  if (convert_ret != 0) {
+    UnmapFramebuffer(mapped_ptr, mapped_size, prime_fd);
+    return false;
+  }
+
+  std::vector<uint8_t> nv12;
+  nv12.reserve(y_plane_.size() + uv_plane_.size());
+  nv12.insert(nv12.end(), y_plane_.begin(), y_plane_.end());
+  nv12.insert(nv12.end(), uv_plane_.begin(), uv_plane_.end());
+
+  if (emit_callback && callback_) {
+    callback_(nv12.data(), static_cast<int>(nv12.size()), capture_width,
+              capture_height, output.stream_id.c_str());
+  }
+
+  UnmapFramebuffer(mapped_ptr, mapped_size, prime_fd);
+  return true;
+}
+
+bool ScreenCapturerDrm::MapFramebuffer(int fd, uint32_t handle, size_t map_size,
+                                       uint8_t** mapped_ptr,
+                                       size_t* mapped_size,
+                                       int* prime_fd) const {
+  if (!mapped_ptr || !mapped_size || !prime_fd || map_size == 0) {
+    return false;
+  }
+
+  *mapped_ptr = nullptr;
+  *mapped_size = 0;
+  *prime_fd = -1;
+
+  drm_mode_map_dumb map_arg{};
+  map_arg.handle = handle;
+  if (drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &map_arg) == 0) {
+    void* mapped = mmap(nullptr, map_size, PROT_READ, MAP_SHARED, fd,
+                        static_cast<off_t>(map_arg.offset));
+    if (mapped != MAP_FAILED) {
+      *mapped_ptr = static_cast<uint8_t*>(mapped);
+      *mapped_size = map_size;
+      return true;
+    }
+  }
+
+  int dma_fd = -1;
+  if (drmPrimeHandleToFD(fd, handle, DRM_CLOEXEC, &dma_fd) == 0) {
+    size_t dma_map_size = map_size;
+    const off_t fd_size = lseek(dma_fd, 0, SEEK_END);
+    if (fd_size > 0) {
+      dma_map_size = std::min(map_size, static_cast<size_t>(fd_size));
+    }
+
+    void* mapped =
+        mmap(nullptr, dma_map_size, PROT_READ, MAP_SHARED, dma_fd, 0);
+    if (mapped != MAP_FAILED) {
+      *mapped_ptr = static_cast<uint8_t*>(mapped);
+      *mapped_size = dma_map_size;
+      *prime_fd = dma_fd;
+      return true;
+    }
+
+    close(dma_fd);
+  }
+
+  return false;
+}
+
+void ScreenCapturerDrm::UnmapFramebuffer(uint8_t* mapped_ptr, size_t mapped_size,
+                                         int prime_fd) const {
+  if (mapped_ptr && mapped_size > 0) {
+    munmap(mapped_ptr, mapped_size);
+  }
+
+  if (prime_fd >= 0) {
+    close(prime_fd);
+  }
+}
+
+}  // namespace crossdesk
+
+#else
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+ScreenCapturerDrm::ScreenCapturerDrm() {}
+
+ScreenCapturerDrm::~ScreenCapturerDrm() { Destroy(); }
+
+int ScreenCapturerDrm::Init([[maybe_unused]] const int fps, cb_desktop_data cb) {
+  Destroy();
+  callback_ = cb;
+  LOG_WARN("DRM screen capturer disabled: libdrm headers not available");
+  return -1;
+}
+
+int ScreenCapturerDrm::Destroy() {
+  Stop();
+  callback_ = nullptr;
+  display_info_list_.clear();
+  outputs_.clear();
+  return 0;
+}
+
+int ScreenCapturerDrm::Start([[maybe_unused]] bool show_cursor) { return -1; }
+
+int ScreenCapturerDrm::Stop() {
+  running_ = false;
+  if (thread_.joinable()) {
+    thread_.join();
+  }
+  return 0;
+}
+
+int ScreenCapturerDrm::Pause([[maybe_unused]] int monitor_index) { return 0; }
+
+int ScreenCapturerDrm::Resume([[maybe_unused]] int monitor_index) { return 0; }
+
+int ScreenCapturerDrm::SwitchTo([[maybe_unused]] int monitor_index) {
+  return -1;
+}
+
+int ScreenCapturerDrm::ResetToInitialMonitor() { return 0; }
+
+std::vector<DisplayInfo> ScreenCapturerDrm::GetDisplayInfoList() {
+  return display_info_list_;
+}
+
+bool ScreenCapturerDrm::DiscoverOutputs() { return false; }
+
+void ScreenCapturerDrm::CloseDevices() {}
+
+void ScreenCapturerDrm::CaptureLoop() {}
+
+bool ScreenCapturerDrm::CaptureOutputFrame(
+    [[maybe_unused]] const DrmOutput& output,
+    [[maybe_unused]] bool emit_callback) {
+  return false;
+}
+
+bool ScreenCapturerDrm::MapFramebuffer([[maybe_unused]] int fd,
+                                       [[maybe_unused]] uint32_t handle,
+                                       [[maybe_unused]] size_t map_size,
+                                       [[maybe_unused]] uint8_t** mapped_ptr,
+                                       [[maybe_unused]] size_t* mapped_size,
+                                       [[maybe_unused]] int* prime_fd) const {
+  return false;
+}
+
+void ScreenCapturerDrm::UnmapFramebuffer([[maybe_unused]] uint8_t* mapped_ptr,
+                                         [[maybe_unused]] size_t mapped_size,
+                                         [[maybe_unused]] int prime_fd) const {}
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_drm.h

@@ -0,0 +1,88 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-03-22
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_DRM_H_
+#define _SCREEN_CAPTURER_DRM_H_
+
+#include <atomic>
+#include <cstdint>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerDrm : public ScreenCapturer {
+ public:
+  ScreenCapturerDrm();
+  ~ScreenCapturerDrm();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override;
+
+ private:
+  struct DrmDevice {
+    int fd = -1;
+    std::string path;
+  };
+
+  struct DrmOutput {
+    int device_index = -1;
+    uint32_t connector_id = 0;
+    uint32_t crtc_id = 0;
+    std::string name;
+    std::string stream_id;
+    int left = 0;
+    int top = 0;
+    int width = 0;
+    int height = 0;
+  };
+
+ private:
+  bool DiscoverOutputs();
+  void CloseDevices();
+  void CaptureLoop();
+  bool CaptureOutputFrame(const DrmOutput& output, bool emit_callback = true);
+  bool MapFramebuffer(int fd, uint32_t handle, size_t map_size,
+                      uint8_t** mapped_ptr, size_t* mapped_size,
+                      int* prime_fd) const;
+  void UnmapFramebuffer(uint8_t* mapped_ptr, size_t mapped_size,
+                        int prime_fd) const;
+
+ private:
+  std::vector<DrmDevice> devices_;
+  std::vector<DrmOutput> outputs_;
+  std::vector<DisplayInfo> display_info_list_;
+  std::thread thread_;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  std::atomic<int> monitor_index_{0};
+  int initial_monitor_index_ = 0;
+  std::atomic<bool> show_cursor_{true};
+  int fps_ = 60;
+  cb_desktop_data callback_;
+  int consecutive_failures_ = 0;
+
+  std::vector<uint8_t> y_plane_;
+  std::vector<uint8_t> uv_plane_;
+};
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_factory.cpp

@@ -0,0 +1,11 @@
+#include "screen_capturer_factory.h"
+
+#include "screen_capturer_linux.h"
+
+namespace crossdesk {
+
+ScreenCapturer* ScreenCapturerFactory::Create() {
+  return new ScreenCapturerLinux();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_linux.cpp

@@ -0,0 +1,576 @@
+#include "screen_capturer_linux.h"
+
+#include <cstdlib>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include <display_stream_id.h>
+#include "platform.h"
+#include "rd_log.h"
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+#include "screen_capturer_drm.h"
+#endif
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+#include "screen_capturer_wayland.h"
+#endif
+#include "screen_capturer_x11.h"
+
+namespace crossdesk {
+
+namespace {
+
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+constexpr bool kDrmBuildEnabled = true;
+#else
+constexpr bool kDrmBuildEnabled = false;
+#endif
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+constexpr bool kWaylandBuildEnabled = true;
+#else
+constexpr bool kWaylandBuildEnabled = false;
+#endif
+
+}  // namespace
+
+ScreenCapturerLinux::ScreenCapturerLinux() {}
+
+ScreenCapturerLinux::~ScreenCapturerLinux() { Destroy(); }
+
+int ScreenCapturerLinux::Init(const int fps, cb_desktop_data cb) {
+  Destroy();
+
+  if (!cb) {
+    LOG_ERROR("Linux screen capturer callback is null");
+    return -1;
+  }
+
+  fps_ = fps;
+  callback_orig_ = std::move(cb);
+  callback_ = [this](unsigned char* data, int size, int width, int height,
+                     const char* reported_stream_id) {
+    const std::string mapped_stream_id = MapStreamId(reported_stream_id);
+    if (mapped_stream_id.empty()) {
+      if (!invalid_stream_id_logged_.exchange(true,
+                                              std::memory_order_relaxed)) {
+        LOG_WARN("Linux capturer dropping frame without a registered stream "
+                 "id: reported='{}', size={}x{}, bytes={}",
+                 reported_stream_id ? reported_stream_id : "", width, height,
+                 size);
+      }
+      return;
+    }
+    invalid_stream_id_logged_.store(false, std::memory_order_relaxed);
+    if (callback_orig_) {
+      callback_orig_(data, size, width, height, mapped_stream_id.c_str());
+    }
+  };
+
+  const char* force_backend = getenv("CROSSDESK_SCREEN_BACKEND");
+  if (force_backend && force_backend[0] != '\0') {
+    if (strcmp(force_backend, "drm") == 0) {
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+      LOG_INFO("Linux screen capturer forced backend: DRM");
+      return InitDrm();
+#else
+      LOG_ERROR(
+          "Linux screen capturer forced backend DRM is disabled at build time");
+      return -1;
+#endif
+    }
+
+    if (strcmp(force_backend, "x11") == 0) {
+      LOG_INFO("Linux screen capturer forced backend: X11");
+      return InitX11();
+    }
+    if (strcmp(force_backend, "wayland") == 0) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+      LOG_INFO("Linux screen capturer forced backend: Wayland");
+      return InitWayland();
+#else
+      LOG_ERROR(
+          "Linux screen capturer forced backend Wayland is disabled at build "
+          "time");
+      return -1;
+#endif
+    }
+
+    LOG_WARN("Unknown CROSSDESK_SCREEN_BACKEND={}, using auto strategy",
+             force_backend);
+  }
+
+  const bool wayland_session = IsWaylandSession();
+  if (wayland_session) {
+    if (kDrmBuildEnabled) {
+      LOG_INFO("Wayland session detected, prefer DRM -> X11 -> Wayland");
+      if (InitDrm() == 0) {
+        return 0;
+      }
+    } else {
+      LOG_INFO("Wayland session detected, DRM disabled, prefer X11 -> Wayland");
+    }
+
+    if (InitX11() == 0) {
+      return 0;
+    }
+
+    if (kDrmBuildEnabled) {
+      LOG_WARN(
+          "DRM and X11 init failed in Wayland session, trying Wayland portal");
+    } else {
+      LOG_WARN("X11 init failed in Wayland session, trying Wayland portal");
+    }
+    if (kWaylandBuildEnabled) {
+      return InitWayland();
+    }
+    LOG_ERROR("Wayland session detected but Wayland backend is disabled");
+    return -1;
+  }
+
+  if (InitX11() == 0) {
+    return 0;
+  }
+
+  if (kDrmBuildEnabled) {
+    LOG_WARN("X11 init failed, trying DRM fallback");
+    return InitDrm();
+  }
+
+  LOG_ERROR("X11 init failed and DRM backend is disabled");
+  return -1;
+}
+
+int ScreenCapturerLinux::Destroy() {
+  if (impl_) {
+    impl_->Destroy();
+    impl_.reset();
+  }
+
+  backend_ = BackendType::kNone;
+  callback_ = nullptr;
+  callback_orig_ = nullptr;
+  current_monitor_index_.store(0, std::memory_order_relaxed);
+  invalid_stream_id_logged_.store(false, std::memory_order_relaxed);
+  {
+    std::lock_guard<std::mutex> lock(alias_mutex_);
+    canonical_displays_.clear();
+    stream_id_alias_.clear();
+  }
+  return 0;
+}
+
+int ScreenCapturerLinux::Start(bool show_cursor) {
+  if (!impl_) {
+    LOG_ERROR("Linux screen capturer backend is not initialized");
+    return -1;
+  }
+
+  // X11 output names, DRM connectors and Wayland stream handles may all change
+  // after an HDMI hotplug, so rebuild the current backend before each session.
+  const int refresh_ret = RefreshCurrentBackend();
+  if (refresh_ret != 0) {
+    LOG_WARN("Linux screen capturer backend refresh failed: {}", refresh_ret);
+  }
+
+  const int ret = impl_->Start(show_cursor);
+  if (ret == 0) {
+    return 0;
+  }
+
+  const char* backend_name = "None";
+  if (backend_ == BackendType::kX11) {
+    backend_name = "X11";
+  } else if (backend_ == BackendType::kDrm) {
+    backend_name = "DRM";
+  } else if (backend_ == BackendType::kWayland) {
+    backend_name = "Wayland";
+  }
+
+  LOG_WARN("Linux screen capturer backend {} start failed: {}", backend_name,
+           ret);
+
+  if (backend_ == BackendType::kX11 && kDrmBuildEnabled &&
+      TryFallbackToDrm(show_cursor)) {
+    return 0;
+  }
+  if (backend_ == BackendType::kX11 && kWaylandBuildEnabled &&
+      TryFallbackToWayland(show_cursor)) {
+    return 0;
+  }
+  if (backend_ == BackendType::kDrm && kDrmBuildEnabled) {
+    if (TryFallbackToX11(show_cursor)) {
+      return 0;
+    }
+    if (kWaylandBuildEnabled && TryFallbackToWayland(show_cursor)) {
+      return 0;
+    }
+  }
+  if (backend_ == BackendType::kWayland && kWaylandBuildEnabled) {
+    if (kDrmBuildEnabled && TryFallbackToDrm(show_cursor)) {
+      return 0;
+    }
+    if (TryFallbackToX11(show_cursor)) {
+      return 0;
+    }
+  }
+
+  return ret;
+}
+
+int ScreenCapturerLinux::Stop() {
+  if (!impl_) {
+    return 0;
+  }
+  const int ret = impl_->Stop();
+  UpdateAliasesFromBackend(impl_.get());
+  return ret;
+}
+
+int ScreenCapturerLinux::Pause(int monitor_index) {
+  if (!impl_) {
+    return -1;
+  }
+  return impl_->Pause(monitor_index);
+}
+
+int ScreenCapturerLinux::Resume(int monitor_index) {
+  if (!impl_) {
+    return -1;
+  }
+  return impl_->Resume(monitor_index);
+}
+
+int ScreenCapturerLinux::SwitchTo(int monitor_index) {
+  if (!impl_) {
+    return -1;
+  }
+  const int ret = impl_->SwitchTo(monitor_index);
+  if (ret == 0) {
+    current_monitor_index_.store(monitor_index, std::memory_order_relaxed);
+  }
+  return ret;
+}
+
+int ScreenCapturerLinux::ResetToInitialMonitor() {
+  if (!impl_) {
+    return -1;
+  }
+  const int ret = impl_->ResetToInitialMonitor();
+  if (ret == 0) {
+    current_monitor_index_.store(initial_monitor_index_,
+                                 std::memory_order_relaxed);
+  }
+  return ret;
+}
+
+std::vector<DisplayInfo> ScreenCapturerLinux::GetDisplayInfoList() {
+  if (!impl_) {
+    return std::vector<DisplayInfo>();
+  }
+
+  // Wayland backend may update display geometry/stream handle asynchronously
+  // after Start(). Refresh aliases every time to keep canonical displays fresh.
+  UpdateAliasesFromBackend(impl_.get());
+
+  std::lock_guard<std::mutex> lock(alias_mutex_);
+  if (!canonical_displays_.empty()) {
+    return canonical_displays_;
+  }
+
+  return impl_->GetDisplayInfoList();
+}
+
+int ScreenCapturerLinux::InitX11() {
+  auto backend = std::make_unique<ScreenCapturerX11>();
+  const int ret = backend->Init(fps_, callback_);
+  if (ret != 0) {
+    backend->Destroy();
+    LOG_WARN("Linux screen capturer X11 init failed: {}", ret);
+    return ret;
+  }
+
+  UpdateAliasesFromBackend(backend.get());
+  impl_ = std::move(backend);
+  backend_ = BackendType::kX11;
+  LOG_INFO("Linux screen capturer backend selected: X11");
+  return 0;
+}
+
+int ScreenCapturerLinux::InitDrm() {
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+  auto backend = std::make_unique<ScreenCapturerDrm>();
+  const int ret = backend->Init(fps_, callback_);
+  if (ret != 0) {
+    backend->Destroy();
+    LOG_WARN("Linux screen capturer DRM init failed: {}", ret);
+    return ret;
+  }
+
+  UpdateAliasesFromBackend(backend.get());
+  impl_ = std::move(backend);
+  backend_ = BackendType::kDrm;
+  LOG_INFO("Linux screen capturer backend selected: DRM");
+  return 0;
+#else
+  LOG_WARN("Linux screen capturer DRM backend is disabled at build time");
+  return -1;
+#endif
+}
+
+int ScreenCapturerLinux::InitWayland() {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  auto backend = std::make_unique<ScreenCapturerWayland>();
+  const int ret = backend->Init(fps_, callback_);
+  if (ret != 0) {
+    backend->Destroy();
+    LOG_WARN("Linux screen capturer Wayland init failed: {}", ret);
+    return ret;
+  }
+
+  UpdateAliasesFromBackend(backend.get());
+  impl_ = std::move(backend);
+  backend_ = BackendType::kWayland;
+  LOG_INFO("Linux screen capturer backend selected: Wayland");
+  return 0;
+#else
+  LOG_WARN("Linux screen capturer Wayland backend is disabled at build time");
+  return -1;
+#endif
+}
+
+int ScreenCapturerLinux::RefreshCurrentBackend() {
+  std::unique_ptr<ScreenCapturer> backend;
+  const char* backend_name = "unknown";
+  switch (backend_) {
+    case BackendType::kX11:
+      backend = std::make_unique<ScreenCapturerX11>();
+      backend_name = "X11";
+      break;
+    case BackendType::kDrm:
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+      backend = std::make_unique<ScreenCapturerDrm>();
+      backend_name = "DRM";
+      break;
+#else
+      return -1;
+#endif
+    case BackendType::kWayland:
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+      backend = std::make_unique<ScreenCapturerWayland>();
+      backend_name = "Wayland";
+      break;
+#else
+      return -1;
+#endif
+    case BackendType::kNone:
+      return -1;
+  }
+
+  const int ret = backend->Init(fps_, callback_);
+  if (ret != 0) {
+    backend->Destroy();
+    return ret;
+  }
+
+  const int requested_monitor =
+      current_monitor_index_.load(std::memory_order_relaxed);
+  UpdateAliasesFromBackend(backend.get());
+  if (requested_monitor > 0 && backend->SwitchTo(requested_monitor) != 0) {
+    current_monitor_index_.store(0, std::memory_order_relaxed);
+  }
+
+  if (impl_) {
+    impl_->Destroy();
+  }
+
+  impl_ = std::move(backend);
+  LOG_INFO("Linux screen capturer {} backend refreshed before start",
+           backend_name);
+  return 0;
+}
+
+bool ScreenCapturerLinux::TryFallbackToDrm(bool show_cursor) {
+#if defined(CROSSDESK_HAS_DRM) && CROSSDESK_HAS_DRM
+  auto drm_backend = std::make_unique<ScreenCapturerDrm>();
+  int ret = drm_backend->Init(fps_, callback_);
+  if (ret != 0) {
+    LOG_ERROR("Linux screen capturer fallback DRM init failed: {}", ret);
+    return false;
+  }
+
+  UpdateAliasesFromBackend(drm_backend.get());
+  ret = drm_backend->Start(show_cursor);
+  if (ret != 0) {
+    drm_backend->Destroy();
+    LOG_ERROR("Linux screen capturer fallback DRM start failed: {}", ret);
+    return false;
+  }
+
+  if (impl_) {
+    impl_->Stop();
+    impl_->Destroy();
+  }
+
+  impl_ = std::move(drm_backend);
+  backend_ = BackendType::kDrm;
+  LOG_INFO("Linux screen capturer fallback switched to DRM");
+  return true;
+#else
+  (void)show_cursor;
+  LOG_WARN("Linux screen capturer DRM fallback is disabled at build time");
+  return false;
+#endif
+}
+
+bool ScreenCapturerLinux::TryFallbackToX11(bool show_cursor) {
+  auto x11_backend = std::make_unique<ScreenCapturerX11>();
+  int ret = x11_backend->Init(fps_, callback_);
+  if (ret != 0) {
+    LOG_ERROR("Linux screen capturer fallback X11 init failed: {}", ret);
+    return false;
+  }
+
+  UpdateAliasesFromBackend(x11_backend.get());
+  ret = x11_backend->Start(show_cursor);
+  if (ret != 0) {
+    x11_backend->Destroy();
+    LOG_ERROR("Linux screen capturer fallback X11 start failed: {}", ret);
+    return false;
+  }
+
+  if (impl_) {
+    impl_->Stop();
+    impl_->Destroy();
+  }
+
+  impl_ = std::move(x11_backend);
+  backend_ = BackendType::kX11;
+  LOG_INFO("Linux screen capturer fallback switched to X11");
+  return true;
+}
+
+bool ScreenCapturerLinux::TryFallbackToWayland(bool show_cursor) {
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  auto wayland_backend = std::make_unique<ScreenCapturerWayland>();
+  int ret = wayland_backend->Init(fps_, callback_);
+  if (ret != 0) {
+    LOG_ERROR("Linux screen capturer fallback Wayland init failed: {}", ret);
+    return false;
+  }
+
+  UpdateAliasesFromBackend(wayland_backend.get());
+  ret = wayland_backend->Start(show_cursor);
+  if (ret != 0) {
+    wayland_backend->Destroy();
+    LOG_ERROR("Linux screen capturer fallback Wayland start failed: {}", ret);
+    return false;
+  }
+
+  if (impl_) {
+    impl_->Stop();
+    impl_->Destroy();
+  }
+
+  impl_ = std::move(wayland_backend);
+  backend_ = BackendType::kWayland;
+  LOG_INFO("Linux screen capturer fallback switched to Wayland");
+  return true;
+#else
+  (void)show_cursor;
+  LOG_WARN("Linux screen capturer Wayland fallback is disabled at build time");
+  return false;
+#endif
+}
+
+void ScreenCapturerLinux::UpdateAliasesFromBackend(ScreenCapturer* backend) {
+  if (!backend) {
+    return;
+  }
+
+  const auto backend_displays = backend->GetDisplayInfoList();
+  if (backend_displays.empty()) {
+    return;
+  }
+
+  std::lock_guard<std::mutex> lock(alias_mutex_);
+  stream_id_alias_.clear();
+
+  if (canonical_displays_.empty()) {
+    canonical_displays_ = backend_displays;
+    for (size_t i = 0; i < backend_displays.size(); ++i) {
+      auto& canonical = canonical_displays_[i];
+      const std::string stream_id = MakeDisplayStreamId(i);
+      if (canonical.name.empty()) {
+        canonical.name = stream_id;
+      }
+      stream_id_alias_[stream_id] = stream_id;
+    }
+    return;
+  }
+
+  if (canonical_displays_.size() < backend_displays.size()) {
+    LOG_WARN("Linux capturer detected {} additional display(s); they remain "
+             "unavailable until peer streams are reinitialized",
+             backend_displays.size() - canonical_displays_.size());
+  }
+
+  auto similar = [](const DisplayInfo& current, const DisplayInfo& canonical) {
+    return std::abs(current.left - canonical.left) <= 10 &&
+           std::abs(current.top - canonical.top) <= 10 &&
+           std::abs(current.width - canonical.width) <= 20 &&
+           std::abs(current.height - canonical.height) <= 20;
+  };
+  std::vector<bool> used(canonical_displays_.size(), false);
+  for (size_t current_index = 0; current_index < backend_displays.size();
+       ++current_index) {
+    const auto& backend_display = backend_displays[current_index];
+    int canonical_index = -1;
+    for (size_t i = 0; i < canonical_displays_.size(); ++i) {
+      if (!used[i] && similar(backend_display, canonical_displays_[i])) {
+        canonical_index = static_cast<int>(i);
+        break;
+      }
+    }
+    if (canonical_index < 0 && current_index < canonical_displays_.size() &&
+        !used[current_index]) {
+      canonical_index = static_cast<int>(current_index);
+    }
+    if (canonical_index < 0) {
+      continue;
+    }
+
+    used[canonical_index] = true;
+    const std::string backend_stream_id =
+        MakeDisplayStreamId(current_index);
+    const std::string stable_stream_id =
+        MakeDisplayStreamId(static_cast<size_t>(canonical_index));
+    stream_id_alias_[backend_stream_id] = stable_stream_id;
+
+    // Refresh the user-visible label and geometry. The MiniRTC stream ID is
+    // derived independently from this stable logical index.
+    canonical_displays_[canonical_index] = backend_display;
+    if (canonical_displays_[canonical_index].name.empty()) {
+      canonical_displays_[canonical_index].name = stable_stream_id;
+    }
+  }
+}
+
+std::string ScreenCapturerLinux::MapStreamId(
+    const char* reported_stream_id) const {
+  std::string input_id = reported_stream_id ? reported_stream_id : "";
+  std::lock_guard<std::mutex> lock(alias_mutex_);
+  auto it = stream_id_alias_.find(input_id);
+  if (it != stream_id_alias_.end()) {
+    input_id = it->second;
+  } else {
+    input_id.clear();
+  }
+
+  return ResolveDisplayStreamId(
+      input_id.c_str(), canonical_displays_.size(),
+      current_monitor_index_.load(std::memory_order_relaxed));
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_linux.h

@@ -0,0 +1,70 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-03-22
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_LINUX_H_
+#define _SCREEN_CAPTURER_LINUX_H_
+
+#include <atomic>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerLinux : public ScreenCapturer {
+ public:
+  ScreenCapturerLinux();
+  ~ScreenCapturerLinux();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override;
+
+ private:
+  enum class BackendType { kNone, kX11, kDrm, kWayland };
+
+ private:
+  int InitX11();
+  int InitDrm();
+  int InitWayland();
+  int RefreshCurrentBackend();
+  bool TryFallbackToDrm(bool show_cursor);
+  bool TryFallbackToX11(bool show_cursor);
+  bool TryFallbackToWayland(bool show_cursor);
+  void UpdateAliasesFromBackend(ScreenCapturer* backend);
+  std::string MapStreamId(const char* reported_stream_id) const;
+
+ private:
+  std::unique_ptr<ScreenCapturer> impl_;
+  BackendType backend_ = BackendType::kNone;
+  int fps_ = 60;
+  cb_desktop_data callback_;
+  cb_desktop_data callback_orig_;
+  std::vector<DisplayInfo> canonical_displays_;
+  mutable std::mutex alias_mutex_;
+  std::unordered_map<std::string, std::string> stream_id_alias_;
+  std::atomic<int> current_monitor_index_{0};
+  int initial_monitor_index_ = 0;
+  mutable std::atomic<bool> invalid_stream_id_logged_{false};
+};
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_wayland.cpp

@@ -0,0 +1,265 @@
+#include "screen_capturer_wayland.h"
+
+#include "screen_capturer_wayland_build.h"
+
+#if !CROSSDESK_WAYLAND_BUILD_ENABLED
+#error \
+    "Wayland capturer requires USE_WAYLAND=true and Wayland development headers"
+#endif
+
+#include <chrono>
+#include <cstdlib>
+#include <cstring>
+#include <thread>
+
+#include "linux_cursor_shape.h"
+#include "platform.h"
+#include "rd_log.h"
+#include "shared_cursor_state.h"
+#include "wayland_portal_shared.h"
+
+namespace crossdesk {
+
+namespace {
+
+int64_t NowMs() {
+  return std::chrono::duration_cast<std::chrono::milliseconds>(
+             std::chrono::steady_clock::now().time_since_epoch())
+      .count();
+}
+
+struct PipeWireRecoveryConfig {
+  ScreenCapturerWayland::PipeWireConnectMode mode;
+  bool relaxed_connect = false;
+};
+
+constexpr auto kPipeWireCloseSettleDelay = std::chrono::milliseconds(200);
+
+}  // namespace
+
+ScreenCapturerWayland::ScreenCapturerWayland()
+    : cursor_theme_matcher_(std::make_unique<LinuxCursorThemeMatcher>()) {}
+
+ScreenCapturerWayland::~ScreenCapturerWayland() { Destroy(); }
+
+int ScreenCapturerWayland::Init(const int fps, cb_desktop_data cb) {
+  Destroy();
+
+  if (!IsWaylandSession()) {
+    LOG_ERROR("Wayland screen capturer requires a Wayland session");
+    return -1;
+  }
+
+  if (!cb) {
+    LOG_ERROR("Wayland screen capturer callback is null");
+    return -1;
+  }
+
+  if (!CheckPortalAvailability()) {
+    LOG_ERROR("xdg-desktop-portal screencast service is unavailable");
+    return -1;
+  }
+
+  if (!EnsurePipeWireRuntimeAvailable()) {
+    LOG_ERROR("Wayland screen capturer requires PipeWire 0.3 runtime");
+    return -1;
+  }
+
+  fps_ = fps;
+  callback_ = cb;
+  pointer_granted_ = false;
+  shared_session_registered_ = false;
+  cursor_metadata_enabled_ = false;
+  cursor_metadata_seen_ = false;
+  cursor_metadata_missing_buffers_ = 0;
+  ClearSharedCursorState();
+  display_info_list_.clear();
+  display_info_list_.push_back(
+      DisplayInfo(display_name_, 0, 0, kFallbackWidth, kFallbackHeight));
+  monitor_index_ = 0;
+  initial_monitor_index_ = 0;
+  frame_width_ = kFallbackWidth;
+  frame_height_ = kFallbackHeight;
+  frame_stride_ = kFallbackWidth * 4;
+  portal_has_logical_size_ = false;
+  portal_stream_width_ = 0;
+  portal_stream_height_ = 0;
+  logical_width_ = kFallbackWidth;
+  logical_height_ = kFallbackHeight;
+  y_plane_.resize(kFallbackWidth * kFallbackHeight);
+  uv_plane_.resize((kFallbackWidth / 2) * (kFallbackHeight / 2) * 2);
+
+  return 0;
+}
+
+int ScreenCapturerWayland::Destroy() {
+  Stop();
+  y_plane_.clear();
+  uv_plane_.clear();
+  display_info_list_.clear();
+  callback_ = nullptr;
+  return 0;
+}
+
+int ScreenCapturerWayland::Start(bool show_cursor) {
+  if (running_) {
+    return 0;
+  }
+
+  show_cursor_ = show_cursor;
+  cursor_metadata_enabled_ = false;
+  cursor_metadata_seen_ = false;
+  cursor_metadata_missing_buffers_ = 0;
+  ClearSharedCursorState();
+  paused_ = false;
+  pipewire_node_id_ = 0;
+  UpdateDisplayGeometry(
+      logical_width_ > 0 ? logical_width_ : kFallbackWidth,
+      logical_height_ > 0 ? logical_height_ : kFallbackHeight);
+  pipewire_format_ready_.store(false);
+  pipewire_stream_start_ms_.store(0);
+  pipewire_last_frame_ms_.store(0);
+  running_ = true;
+  thread_ = std::thread([this]() { Run(); });
+  return 0;
+}
+
+int ScreenCapturerWayland::Stop() {
+  running_ = false;
+  if (thread_.joinable()) {
+    thread_.join();
+  }
+  pipewire_node_id_ = 0;
+  cursor_metadata_enabled_ = false;
+  cursor_metadata_seen_ = false;
+  cursor_metadata_missing_buffers_ = 0;
+  ClearSharedCursorState();
+  UpdateDisplayGeometry(
+      logical_width_ > 0 ? logical_width_ : kFallbackWidth,
+      logical_height_ > 0 ? logical_height_ : kFallbackHeight);
+  return 0;
+}
+
+int ScreenCapturerWayland::Pause([[maybe_unused]] int monitor_index) {
+  paused_ = true;
+  return 0;
+}
+
+int ScreenCapturerWayland::Resume([[maybe_unused]] int monitor_index) {
+  paused_ = false;
+  return 0;
+}
+
+int ScreenCapturerWayland::SwitchTo(int monitor_index) {
+  if (monitor_index != 0) {
+    LOG_WARN("Wayland screencast currently supports one logical display");
+    return -1;
+  }
+
+  monitor_index_ = 0;
+  return 0;
+}
+
+int ScreenCapturerWayland::ResetToInitialMonitor() {
+  monitor_index_ = initial_monitor_index_;
+  return 0;
+}
+
+std::vector<DisplayInfo> ScreenCapturerWayland::GetDisplayInfoList() {
+  return display_info_list_;
+}
+
+void ScreenCapturerWayland::Run() {
+  static constexpr PipeWireRecoveryConfig kRecoveryConfigs[] = {
+      {PipeWireConnectMode::kTargetObject, false},
+      {PipeWireConnectMode::kAny, true},
+      {PipeWireConnectMode::kNodeId, false},
+      {PipeWireConnectMode::kNodeId, true},
+  };
+
+  int recovery_index = 0;
+  auto setup_pipewire = [this, &recovery_index]() -> bool {
+    const auto& config = kRecoveryConfigs[recovery_index];
+    return OpenPipeWireRemote() &&
+           SetupPipeWireStream(config.relaxed_connect, config.mode);
+  };
+  auto setup_pipeline = [this, &setup_pipewire]() -> bool {
+    return ConnectSessionBus() && CreatePortalSession() &&
+           SelectPortalDevices() && SelectPortalSource() &&
+           StartPortalSession() && setup_pipewire();
+  };
+
+  if (!setup_pipeline()) {
+    running_ = false;
+    CleanupPipeWire();
+    ClosePortalSession();
+    CleanupDbus();
+    return;
+  }
+  while (running_) {
+    if (!paused_) {
+      const int64_t now = NowMs();
+      const int64_t stream_start = pipewire_stream_start_ms_.load();
+      const int64_t last_frame = pipewire_last_frame_ms_.load();
+      const bool format_ready = pipewire_format_ready_.load();
+
+      const bool format_timeout =
+          stream_start > 0 && !format_ready && (now - stream_start) > 1200;
+      const bool first_frame_timeout = stream_start > 0 && format_ready &&
+                                       last_frame == 0 &&
+                                       (now - stream_start) > 4000;
+      const bool frame_stall = last_frame > 0 && (now - last_frame) > 5000;
+
+      if (format_timeout || first_frame_timeout || frame_stall) {
+        if (recovery_index + 1 >=
+            static_cast<int>(sizeof(kRecoveryConfigs) /
+                             sizeof(kRecoveryConfigs[0]))) {
+          LOG_ERROR(
+              "Wayland capture stalled and recovery limit reached, "
+              "format_ready={}, stream_start={}, last_frame={}, attempts={}",
+              format_ready, stream_start, last_frame, recovery_index);
+          running_ = false;
+          break;
+        }
+
+        ++recovery_index;
+        const char* reason =
+            format_timeout
+                ? "format-timeout"
+                : (first_frame_timeout ? "first-frame-timeout" : "frame-stall");
+        const auto& config = kRecoveryConfigs[recovery_index];
+        LOG_WARN(
+            "Wayland capture stalled ({}) - retrying PipeWire only, "
+            "attempt {}/{}, mode={}, relaxed_connect={}",
+            reason, recovery_index,
+            static_cast<int>(sizeof(kRecoveryConfigs) /
+                             sizeof(kRecoveryConfigs[0])) -
+                1,
+            config.mode == PipeWireConnectMode::kTargetObject
+                ? "target-object"
+                : (config.mode == PipeWireConnectMode::kNodeId ? "node-id"
+                                                               : "any"),
+            config.relaxed_connect);
+
+        CleanupPipeWire();
+        if (!setup_pipewire()) {
+          LOG_ERROR("Wayland PipeWire-only recovery failed at attempt {}",
+                    recovery_index);
+          running_ = false;
+          break;
+        }
+      }
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+  }
+
+  CleanupPipeWire();
+  if (!session_handle_.empty()) {
+    std::this_thread::sleep_for(kPipeWireCloseSettleDelay);
+  }
+  ClosePortalSession();
+  CleanupDbus();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_wayland.h

@@ -0,0 +1,122 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-03-22
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_WAYLAND_H_
+#define _SCREEN_CAPTURER_WAYLAND_H_
+
+struct DBusConnection;
+struct pw_context;
+struct pw_core;
+struct pw_stream;
+struct pw_thread_loop;
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class LinuxCursorThemeMatcher;
+
+class ScreenCapturerWayland : public ScreenCapturer {
+ public:
+  enum class PipeWireConnectMode { kTargetObject, kNodeId, kAny };
+
+ public:
+  ScreenCapturerWayland();
+  ~ScreenCapturerWayland();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override;
+
+ private:
+  bool CheckPortalAvailability() const;
+  bool ConnectSessionBus();
+  bool CreatePortalSession();
+  bool SelectPortalDevices();
+  bool SelectPortalSource();
+  bool GetAvailableCursorModes(uint32_t* modes) const;
+  bool StartPortalSession();
+  bool EnsurePipeWireRuntimeAvailable() const;
+  bool OpenPipeWireRemote();
+  bool SetupPipeWireStream(bool relaxed_connect, PipeWireConnectMode mode);
+
+  void Run();
+  void CleanupPipeWire();
+  void CleanupDbus();
+  void ClosePortalSession();
+  void HandlePipeWireBuffer();
+  void UpdateDisplayGeometry(int width, int height);
+
+ private:
+  static constexpr int kFallbackWidth = 1920;
+  static constexpr int kFallbackHeight = 1080;
+
+  std::thread thread_;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  std::atomic<int> monitor_index_{0};
+  std::atomic<bool> pipewire_format_ready_{false};
+  std::atomic<int64_t> pipewire_stream_start_ms_{0};
+  std::atomic<int64_t> pipewire_last_frame_ms_{0};
+  int initial_monitor_index_ = 0;
+  std::atomic<bool> show_cursor_{true};
+  int fps_ = 60;
+  cb_desktop_data callback_ = nullptr;
+  std::vector<DisplayInfo> display_info_list_;
+
+  DBusConnection* dbus_connection_ = nullptr;
+  std::string session_handle_;
+  std::string display_name_ = "WAYLAND0";
+  uint32_t pipewire_node_id_ = 0;
+  int pipewire_fd_ = -1;
+
+  pw_thread_loop* pw_thread_loop_ = nullptr;
+  pw_context* pw_context_ = nullptr;
+  pw_core* pw_core_ = nullptr;
+  pw_stream* pw_stream_ = nullptr;
+  void* stream_listener_ = nullptr;
+  bool pipewire_initialized_ = false;
+  bool pipewire_thread_loop_started_ = false;
+  bool pointer_granted_ = false;
+  bool shared_session_registered_ = false;
+  bool cursor_metadata_enabled_ = false;
+  bool cursor_metadata_seen_ = false;
+  uint32_t cursor_metadata_missing_buffers_ = 0;
+  bool portal_has_logical_size_ = false;
+  uint32_t spa_video_format_ = 0;
+  int frame_width_ = 0;
+  int frame_height_ = 0;
+  int frame_stride_ = 0;
+  int portal_stream_width_ = 0;
+  int portal_stream_height_ = 0;
+  int logical_width_ = 0;
+  int logical_height_ = 0;
+  std::unique_ptr<LinuxCursorThemeMatcher> cursor_theme_matcher_;
+
+  std::vector<uint8_t> y_plane_;
+  std::vector<uint8_t> uv_plane_;
+};
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_wayland_build.h

@@ -0,0 +1,46 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-03-22
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_WAYLAND_BUILD_H_
+#define _SCREEN_CAPTURER_WAYLAND_BUILD_H_
+
+#if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+
+#define CROSSDESK_WAYLAND_BUILD_ENABLED 1
+
+#include <dbus/dbus.h>
+#include <pipewire/keys.h>
+#include <pipewire/pipewire.h>
+#include <pipewire/stream.h>
+#include <pipewire/thread-loop.h>
+#include <spa/param/param.h>
+#include <spa/param/format-utils.h>
+#include <spa/param/video/format-utils.h>
+#include <spa/param/video/raw.h>
+#include <spa/buffer/meta.h>
+#include <spa/utils/result.h>
+
+#if defined(__has_include)
+#if __has_include(<spa/param/buffers.h>)
+#include <spa/param/buffers.h>
+#endif
+#endif
+
+#define CROSSDESK_SPA_PARAM_BUFFERS_BUFFERS 1u
+#define CROSSDESK_SPA_PARAM_BUFFERS_BLOCKS 2u
+#define CROSSDESK_SPA_PARAM_BUFFERS_SIZE 3u
+#define CROSSDESK_SPA_PARAM_BUFFERS_STRIDE 4u
+
+#define CROSSDESK_SPA_PARAM_META_TYPE 1u
+#define CROSSDESK_SPA_PARAM_META_SIZE 2u
+
+#else
+
+#define CROSSDESK_WAYLAND_BUILD_ENABLED 0
+
+#endif
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_wayland_portal.cpp

@@ -0,0 +1,911 @@
+#include "screen_capturer_wayland.h"
+
+#include <remote_action.h>
+#include "screen_capturer_wayland_build.h"
+#include "wayland_portal_shared.h"
+
+#if CROSSDESK_WAYLAND_BUILD_ENABLED
+
+#include <unistd.h>
+
+#include <chrono>
+#include <cstring>
+#include <functional>
+#include <string>
+
+#include "rd_log.h"
+#include "shared_cursor_state.h"
+
+namespace crossdesk {
+
+namespace {
+
+constexpr const char* kPortalBusName = "org.freedesktop.portal.Desktop";
+constexpr const char* kPortalObjectPath = "/org/freedesktop/portal/desktop";
+constexpr const char* kPortalRemoteDesktopInterface =
+    "org.freedesktop.portal.RemoteDesktop";
+constexpr const char* kPortalScreenCastInterface =
+    "org.freedesktop.portal.ScreenCast";
+constexpr const char* kPortalRequestInterface =
+    "org.freedesktop.portal.Request";
+constexpr const char* kPortalSessionInterface =
+    "org.freedesktop.portal.Session";
+constexpr const char* kPortalRequestPathPrefix =
+    "/org/freedesktop/portal/desktop/request/";
+constexpr const char* kPortalSessionPathPrefix =
+    "/org/freedesktop/portal/desktop/session/";
+
+constexpr uint32_t kScreenCastSourceMonitor = 1u;
+constexpr uint32_t kCursorModeHidden = 1u;
+constexpr uint32_t kCursorModeEmbedded = 2u;
+constexpr uint32_t kCursorModeMetadata = 4u;
+constexpr uint32_t kRemoteDesktopDevicePointer = 2u;
+
+std::string MakeToken(const char* prefix) {
+  const auto now = std::chrono::steady_clock::now().time_since_epoch().count();
+  return std::string(prefix) + "_" + std::to_string(now);
+}
+
+void LogDbusError(const char* action, DBusError* error) {
+  if (error && dbus_error_is_set(error)) {
+    LOG_ERROR("{} failed: {} ({})", action,
+              error->message ? error->message : "unknown",
+              error->name ? error->name : "unknown");
+  } else {
+    LOG_ERROR("{} failed", action);
+  }
+}
+
+void AppendDictEntryString(DBusMessageIter* dict, const char* key,
+                           const std::string& value) {
+  DBusMessageIter entry;
+  DBusMessageIter variant;
+  const char* key_cstr = key;
+  const char* value_cstr = value.c_str();
+
+  dbus_message_iter_open_container(dict, DBUS_TYPE_DICT_ENTRY, nullptr, &entry);
+  dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key_cstr);
+  dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT, "s", &variant);
+  dbus_message_iter_append_basic(&variant, DBUS_TYPE_STRING, &value_cstr);
+  dbus_message_iter_close_container(&entry, &variant);
+  dbus_message_iter_close_container(dict, &entry);
+}
+
+void AppendDictEntryUint32(DBusMessageIter* dict, const char* key,
+                           uint32_t value) {
+  DBusMessageIter entry;
+  DBusMessageIter variant;
+  const char* key_cstr = key;
+
+  dbus_message_iter_open_container(dict, DBUS_TYPE_DICT_ENTRY, nullptr, &entry);
+  dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key_cstr);
+  dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT, "u", &variant);
+  dbus_message_iter_append_basic(&variant, DBUS_TYPE_UINT32, &value);
+  dbus_message_iter_close_container(&entry, &variant);
+  dbus_message_iter_close_container(dict, &entry);
+}
+
+void AppendDictEntryBool(DBusMessageIter* dict, const char* key, bool value) {
+  DBusMessageIter entry;
+  DBusMessageIter variant;
+  const char* key_cstr = key;
+  dbus_bool_t bool_value = value ? TRUE : FALSE;
+
+  dbus_message_iter_open_container(dict, DBUS_TYPE_DICT_ENTRY, nullptr, &entry);
+  dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key_cstr);
+  dbus_message_iter_open_container(&entry, DBUS_TYPE_VARIANT, "b", &variant);
+  dbus_message_iter_append_basic(&variant, DBUS_TYPE_BOOLEAN, &bool_value);
+  dbus_message_iter_close_container(&entry, &variant);
+  dbus_message_iter_close_container(dict, &entry);
+}
+
+bool ReadIntLike(DBusMessageIter* iter, int* value) {
+  if (!iter || !value) {
+    return false;
+  }
+
+  const int type = dbus_message_iter_get_arg_type(iter);
+  if (type == DBUS_TYPE_INT32) {
+    int32_t temp = 0;
+    dbus_message_iter_get_basic(iter, &temp);
+    *value = static_cast<int>(temp);
+    return true;
+  }
+
+  if (type == DBUS_TYPE_UINT32) {
+    uint32_t temp = 0;
+    dbus_message_iter_get_basic(iter, &temp);
+    *value = static_cast<int>(temp);
+    return true;
+  }
+
+  return false;
+}
+
+bool ReadPathLikeVariant(DBusMessageIter* variant, std::string* value) {
+  if (!variant || !value) {
+    return false;
+  }
+
+  const int type = dbus_message_iter_get_arg_type(variant);
+  if (type == DBUS_TYPE_OBJECT_PATH || type == DBUS_TYPE_STRING) {
+    const char* temp = nullptr;
+    dbus_message_iter_get_basic(variant, &temp);
+    if (temp && temp[0] != '\0') {
+      *value = temp;
+      return true;
+    }
+  }
+
+  return false;
+}
+
+std::string BuildSessionHandleFromRequestPath(
+    const std::string& request_path, const std::string& session_handle_token) {
+  if (request_path.rfind(kPortalRequestPathPrefix, 0) != 0 ||
+      session_handle_token.empty()) {
+    return "";
+  }
+
+  const size_t sender_start = strlen(kPortalRequestPathPrefix);
+  const size_t token_sep = request_path.find('/', sender_start);
+  if (token_sep == std::string::npos || token_sep <= sender_start) {
+    return "";
+  }
+
+  const std::string sender =
+      request_path.substr(sender_start, token_sep - sender_start);
+  if (sender.empty()) {
+    return "";
+  }
+
+  return std::string(kPortalSessionPathPrefix) + sender + "/" +
+         session_handle_token;
+}
+
+struct PortalResponseState {
+  std::string request_path;
+  bool received = false;
+  DBusMessage* message = nullptr;
+};
+
+DBusHandlerResult HandlePortalResponseSignal(DBusConnection* connection,
+                                             DBusMessage* message,
+                                             void* user_data) {
+  auto* state = static_cast<PortalResponseState*>(user_data);
+  if (!state || !message) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  if (!dbus_message_is_signal(message, kPortalRequestInterface, "Response")) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  const char* path = dbus_message_get_path(message);
+  if (!path || state->request_path != path) {
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+  }
+
+  if (state->message) {
+    dbus_message_unref(state->message);
+    state->message = nullptr;
+  }
+
+  state->message = dbus_message_ref(message);
+  state->received = true;
+  return DBUS_HANDLER_RESULT_HANDLED;
+}
+
+DBusMessage* WaitForPortalResponse(DBusConnection* connection,
+                                   const std::string& request_path,
+                                   const std::atomic<bool>& running,
+                                   int timeout_ms = 120000) {
+  if (!connection || request_path.empty()) {
+    return nullptr;
+  }
+
+  PortalResponseState state;
+  state.request_path = request_path;
+
+  DBusError error;
+  dbus_error_init(&error);
+
+  const std::string match_rule =
+      "type='signal',interface='" + std::string(kPortalRequestInterface) +
+      "',member='Response',path='" + request_path + "'";
+  dbus_bus_add_match(connection, match_rule.c_str(), &error);
+  if (dbus_error_is_set(&error)) {
+    LogDbusError("dbus_bus_add_match", &error);
+    dbus_error_free(&error);
+    return nullptr;
+  }
+
+  dbus_connection_add_filter(connection, HandlePortalResponseSignal, &state,
+                             nullptr);
+
+  auto deadline =
+      std::chrono::steady_clock::now() + std::chrono::milliseconds(timeout_ms);
+  while (running.load() && !state.received &&
+         std::chrono::steady_clock::now() < deadline) {
+    dbus_connection_read_write(connection, 100);
+    while (dbus_connection_dispatch(connection) == DBUS_DISPATCH_DATA_REMAINS) {
+    }
+  }
+
+  dbus_connection_remove_filter(connection, HandlePortalResponseSignal, &state);
+
+  DBusError remove_error;
+  dbus_error_init(&remove_error);
+  dbus_bus_remove_match(connection, match_rule.c_str(), &remove_error);
+  if (dbus_error_is_set(&remove_error)) {
+    dbus_error_free(&remove_error);
+  }
+
+  return state.message;
+}
+
+bool ExtractRequestPath(DBusMessage* reply, std::string* request_path) {
+  if (!reply || !request_path) {
+    return false;
+  }
+
+  const char* path = nullptr;
+  DBusError error;
+  dbus_error_init(&error);
+  const dbus_bool_t ok = dbus_message_get_args(
+      reply, &error, DBUS_TYPE_OBJECT_PATH, &path, DBUS_TYPE_INVALID);
+  if (!ok || !path) {
+    LogDbusError("dbus_message_get_args(request_path)", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  *request_path = path;
+  return true;
+}
+
+bool ExtractPortalResponse(DBusMessage* message, uint32_t* response_code,
+                           DBusMessageIter* results_array) {
+  if (!message || !response_code || !results_array) {
+    return false;
+  }
+
+  DBusMessageIter iter;
+  if (!dbus_message_iter_init(message, &iter) ||
+      dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_UINT32) {
+    return false;
+  }
+
+  dbus_message_iter_get_basic(&iter, response_code);
+  if (!dbus_message_iter_next(&iter) ||
+      dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_ARRAY) {
+    return false;
+  }
+
+  *results_array = iter;
+  return true;
+}
+
+bool SendPortalRequestAndHandleResponse(
+    DBusConnection* connection, const char* interface_name,
+    const char* method_name, const char* action_name,
+    const std::function<bool(DBusMessage*)>& append_message_args,
+    const std::atomic<bool>& running,
+    const std::function<bool(uint32_t, DBusMessageIter*)>& handle_results,
+    std::string* request_path_out = nullptr) {
+  if (!connection || !interface_name || interface_name[0] == '\0' ||
+      !method_name || method_name[0] == '\0') {
+    return false;
+  }
+
+  DBusMessage* message = dbus_message_new_method_call(
+      kPortalBusName, kPortalObjectPath, interface_name, method_name);
+  if (!message) {
+    LOG_ERROR("Failed to allocate {} message", method_name);
+    return false;
+  }
+
+  if (append_message_args && !append_message_args(message)) {
+    dbus_message_unref(message);
+    LOG_ERROR("{} arguments are malformed", method_name);
+    return false;
+  }
+
+  DBusError error;
+  dbus_error_init(&error);
+  DBusMessage* reply = dbus_connection_send_with_reply_and_block(
+      connection, message, -1, &error);
+  dbus_message_unref(message);
+  if (!reply) {
+    LogDbusError(action_name ? action_name : method_name, &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  std::string request_path;
+  const bool got_request_path = ExtractRequestPath(reply, &request_path);
+  dbus_message_unref(reply);
+  if (!got_request_path) {
+    return false;
+  }
+  if (request_path_out) {
+    *request_path_out = request_path;
+  }
+
+  DBusMessage* response =
+      WaitForPortalResponse(connection, request_path, running);
+  if (!response) {
+    LOG_ERROR("Timed out waiting for {} response", method_name);
+    return false;
+  }
+
+  uint32_t response_code = 1;
+  DBusMessageIter results;
+  const bool parsed = ExtractPortalResponse(response, &response_code, &results);
+  if (!parsed) {
+    dbus_message_unref(response);
+    LOG_ERROR("{} response was malformed", method_name);
+    return false;
+  }
+
+  const bool ok = handle_results ? handle_results(response_code, &results)
+                                 : (response_code == 0);
+  dbus_message_unref(response);
+  return ok;
+}
+
+}  // namespace
+
+bool ScreenCapturerWayland::CheckPortalAvailability() const {
+  DBusError error;
+  dbus_error_init(&error);
+
+  DBusConnection* connection = dbus_bus_get(DBUS_BUS_SESSION, &error);
+  if (!connection) {
+    LogDbusError("dbus_bus_get", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  const dbus_bool_t has_owner =
+      dbus_bus_name_has_owner(connection, kPortalBusName, &error);
+  if (dbus_error_is_set(&error)) {
+    LogDbusError("dbus_bus_name_has_owner", &error);
+    dbus_error_free(&error);
+    dbus_connection_unref(connection);
+    return false;
+  }
+
+  dbus_connection_unref(connection);
+  return has_owner == TRUE;
+}
+
+bool ScreenCapturerWayland::ConnectSessionBus() {
+  if (dbus_connection_) {
+    return true;
+  }
+
+  DBusError error;
+  dbus_error_init(&error);
+
+  dbus_connection_ = dbus_bus_get_private(DBUS_BUS_SESSION, &error);
+  if (!dbus_connection_) {
+    LogDbusError("dbus_bus_get_private", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  dbus_connection_set_exit_on_disconnect(dbus_connection_, FALSE);
+  return true;
+}
+
+bool ScreenCapturerWayland::CreatePortalSession() {
+  if (!dbus_connection_) {
+    return false;
+  }
+
+  const std::string session_handle_token = MakeToken("crossdesk_session");
+  std::string request_path;
+  const bool ok = SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "CreateSession",
+      "CreateSession",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryString(&options, "session_handle_token",
+                              session_handle_token);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      running_,
+      [&](uint32_t response_code, DBusMessageIter* results) {
+        if (response_code != 0) {
+          LOG_ERROR("CreateSession was denied or malformed, response={}",
+                    response_code);
+          return false;
+        }
+
+        DBusMessageIter dict;
+        dbus_message_iter_recurse(results, &dict);
+        while (dbus_message_iter_get_arg_type(&dict) != DBUS_TYPE_INVALID) {
+          if (dbus_message_iter_get_arg_type(&dict) == DBUS_TYPE_DICT_ENTRY) {
+            DBusMessageIter entry;
+            dbus_message_iter_recurse(&dict, &entry);
+
+            const char* key = nullptr;
+            dbus_message_iter_get_basic(&entry, &key);
+            if (key && dbus_message_iter_next(&entry) &&
+                dbus_message_iter_get_arg_type(&entry) == DBUS_TYPE_VARIANT &&
+                strcmp(key, "session_handle") == 0) {
+              DBusMessageIter variant;
+              std::string parsed_handle;
+              dbus_message_iter_recurse(&entry, &variant);
+              if (ReadPathLikeVariant(&variant, &parsed_handle) &&
+                  !parsed_handle.empty()) {
+                session_handle_ = parsed_handle;
+                break;
+              }
+            }
+          }
+          dbus_message_iter_next(&dict);
+        }
+        return true;
+      },
+      &request_path);
+  if (!ok) {
+    return false;
+  }
+
+  if (session_handle_.empty()) {
+    const std::string fallback_handle =
+        BuildSessionHandleFromRequestPath(request_path, session_handle_token);
+    if (!fallback_handle.empty()) {
+      LOG_WARN(
+          "CreateSession response missing session_handle, using derived handle "
+          "{}",
+          fallback_handle);
+      session_handle_ = fallback_handle;
+    }
+  }
+
+  if (session_handle_.empty()) {
+    LOG_ERROR("CreateSession response did not include a session handle");
+    return false;
+  }
+
+  return true;
+}
+
+bool ScreenCapturerWayland::SelectPortalSource() {
+  if (!dbus_connection_ || session_handle_.empty()) {
+    return false;
+  }
+
+  uint32_t available_cursor_modes = kCursorModeHidden | kCursorModeEmbedded;
+  if (!GetAvailableCursorModes(&available_cursor_modes)) {
+    LOG_WARN(
+        "Unable to query portal cursor modes; using embedded cursor fallback");
+  }
+
+  uint32_t cursor_mode = 0;
+  cursor_metadata_enabled_ = false;
+  if (!show_cursor_ && (available_cursor_modes & kCursorModeMetadata) != 0) {
+    cursor_mode = kCursorModeMetadata;
+    cursor_metadata_enabled_ = true;
+  } else if ((available_cursor_modes & kCursorModeEmbedded) != 0) {
+    cursor_mode = kCursorModeEmbedded;
+  } else if ((available_cursor_modes & kCursorModeMetadata) != 0) {
+    cursor_mode = kCursorModeMetadata;
+    cursor_metadata_enabled_ = true;
+  } else if ((available_cursor_modes & kCursorModeHidden) != 0) {
+    cursor_mode = kCursorModeHidden;
+  }
+
+  if (cursor_mode == 0) {
+    LOG_ERROR("Wayland portal reports no supported cursor mode");
+    return false;
+  }
+
+  if (cursor_mode == kCursorModeEmbedded) {
+    // When metadata is unavailable, embedding is the only way to preserve the
+    // exact Wayland cursor. Hide the controller-side cursor to avoid a double
+    // cursor over the video stream.
+    PublishSharedCursorState(false, RemoteCursorShape::none);
+  } else if (!cursor_metadata_enabled_) {
+    // A portal without metadata or embedded cursor support cannot expose the
+    // native Wayland shape. Keep a visible default cursor on the controller.
+    PublishSharedCursorState(true, RemoteCursorShape::default_cursor);
+  }
+
+  LOG_INFO("Wayland portal cursor mode: {}",
+           cursor_mode == kCursorModeMetadata
+               ? "metadata"
+               : (cursor_mode == kCursorModeEmbedded ? "embedded" : "hidden"));
+
+  const char* session_handle = session_handle_.c_str();
+  return SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalScreenCastInterface, "SelectSources",
+      "SelectSources",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryUint32(&options, "types", kScreenCastSourceMonitor);
+        AppendDictEntryBool(&options, "multiple", false);
+        AppendDictEntryUint32(&options, "cursor_mode", cursor_mode);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      running_,
+      [](uint32_t response_code, DBusMessageIter*) {
+        if (response_code != 0) {
+          LOG_ERROR("SelectSources was denied or malformed, response={}",
+                    response_code);
+          return false;
+        }
+        return true;
+      });
+}
+
+bool ScreenCapturerWayland::GetAvailableCursorModes(uint32_t* modes) const {
+  if (!dbus_connection_ || !modes) {
+    return false;
+  }
+
+  DBusMessage* message = dbus_message_new_method_call(
+      kPortalBusName, kPortalObjectPath, "org.freedesktop.DBus.Properties",
+      "Get");
+  if (!message) {
+    return false;
+  }
+
+  const char* interface_name = kPortalScreenCastInterface;
+  const char* property_name = "AvailableCursorModes";
+  dbus_message_append_args(message, DBUS_TYPE_STRING, &interface_name,
+                           DBUS_TYPE_STRING, &property_name,
+                           DBUS_TYPE_INVALID);
+
+  DBusError error;
+  dbus_error_init(&error);
+  DBusMessage* reply = dbus_connection_send_with_reply_and_block(
+      dbus_connection_, message, -1, &error);
+  dbus_message_unref(message);
+  if (!reply) {
+    LogDbusError("Get AvailableCursorModes", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  DBusMessageIter iter;
+  bool parsed = false;
+  if (dbus_message_iter_init(reply, &iter) &&
+      dbus_message_iter_get_arg_type(&iter) == DBUS_TYPE_VARIANT) {
+    DBusMessageIter variant;
+    dbus_message_iter_recurse(&iter, &variant);
+    if (dbus_message_iter_get_arg_type(&variant) == DBUS_TYPE_UINT32) {
+      dbus_message_iter_get_basic(&variant, modes);
+      parsed = true;
+    }
+  }
+  dbus_message_unref(reply);
+  return parsed;
+}
+
+bool ScreenCapturerWayland::SelectPortalDevices() {
+  if (!dbus_connection_ || session_handle_.empty()) {
+    return false;
+  }
+
+  const char* session_handle = session_handle_.c_str();
+  return SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "SelectDevices",
+      "SelectDevices",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryUint32(&options, "types", kRemoteDesktopDevicePointer);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      running_,
+      [](uint32_t response_code, DBusMessageIter*) {
+        if (response_code != 0) {
+          LOG_ERROR("SelectDevices was denied or malformed, response={}",
+                    response_code);
+          return false;
+        }
+        return true;
+      });
+}
+
+bool ScreenCapturerWayland::StartPortalSession() {
+  if (!dbus_connection_ || session_handle_.empty()) {
+    return false;
+  }
+
+  const char* session_handle = session_handle_.c_str();
+  const char* parent_window = "";
+  pointer_granted_ = false;
+  const bool ok = SendPortalRequestAndHandleResponse(
+      dbus_connection_, kPortalRemoteDesktopInterface, "Start", "Start",
+      [&](DBusMessage* message) {
+        DBusMessageIter iter;
+        DBusMessageIter options;
+        dbus_message_iter_init_append(message, &iter);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH,
+                                       &session_handle);
+        dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &parent_window);
+        dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}",
+                                         &options);
+        AppendDictEntryString(&options, "handle_token",
+                              MakeToken("crossdesk_req"));
+        dbus_message_iter_close_container(&iter, &options);
+        return true;
+      },
+      running_,
+      [&](uint32_t response_code, DBusMessageIter* results) {
+        if (response_code != 0) {
+          LOG_ERROR("Start was denied or malformed, response={}",
+                    response_code);
+          return false;
+        }
+
+        uint32_t granted_devices = 0;
+        DBusMessageIter dict;
+        dbus_message_iter_recurse(results, &dict);
+        while (dbus_message_iter_get_arg_type(&dict) != DBUS_TYPE_INVALID) {
+          if (dbus_message_iter_get_arg_type(&dict) == DBUS_TYPE_DICT_ENTRY) {
+            DBusMessageIter entry;
+            dbus_message_iter_recurse(&dict, &entry);
+
+            const char* key = nullptr;
+            dbus_message_iter_get_basic(&entry, &key);
+            if (key && dbus_message_iter_next(&entry) &&
+                dbus_message_iter_get_arg_type(&entry) == DBUS_TYPE_VARIANT) {
+              DBusMessageIter variant;
+              dbus_message_iter_recurse(&entry, &variant);
+              if (strcmp(key, "devices") == 0) {
+                int granted_devices_int = 0;
+                if (ReadIntLike(&variant, &granted_devices_int) &&
+                    granted_devices_int >= 0) {
+                  granted_devices = static_cast<uint32_t>(granted_devices_int);
+                }
+              } else if (strcmp(key, "streams") == 0) {
+                DBusMessageIter streams;
+                dbus_message_iter_recurse(&variant, &streams);
+
+                if (dbus_message_iter_get_arg_type(&streams) ==
+                    DBUS_TYPE_STRUCT) {
+                  DBusMessageIter stream;
+                  dbus_message_iter_recurse(&streams, &stream);
+
+                  if (dbus_message_iter_get_arg_type(&stream) ==
+                      DBUS_TYPE_UINT32) {
+                    dbus_message_iter_get_basic(&stream, &pipewire_node_id_);
+                  }
+
+                  if (dbus_message_iter_next(&stream) &&
+                      dbus_message_iter_get_arg_type(&stream) ==
+                          DBUS_TYPE_ARRAY) {
+                    DBusMessageIter props;
+                    int stream_width = 0;
+                    int stream_height = 0;
+                    int logical_width = 0;
+                    int logical_height = 0;
+                    dbus_message_iter_recurse(&stream, &props);
+                    while (dbus_message_iter_get_arg_type(&props) !=
+                           DBUS_TYPE_INVALID) {
+                      if (dbus_message_iter_get_arg_type(&props) ==
+                          DBUS_TYPE_DICT_ENTRY) {
+                        DBusMessageIter prop_entry;
+                        dbus_message_iter_recurse(&props, &prop_entry);
+
+                        const char* prop_key = nullptr;
+                        dbus_message_iter_get_basic(&prop_entry, &prop_key);
+                        if (prop_key && dbus_message_iter_next(&prop_entry) &&
+                            dbus_message_iter_get_arg_type(&prop_entry) ==
+                                DBUS_TYPE_VARIANT) {
+                          DBusMessageIter prop_variant;
+                          dbus_message_iter_recurse(&prop_entry, &prop_variant);
+                          if (dbus_message_iter_get_arg_type(&prop_variant) ==
+                              DBUS_TYPE_STRUCT) {
+                            DBusMessageIter size_iter;
+                            int width = 0;
+                            int height = 0;
+                            dbus_message_iter_recurse(&prop_variant,
+                                                      &size_iter);
+                            if (ReadIntLike(&size_iter, &width) &&
+                                dbus_message_iter_next(&size_iter) &&
+                                ReadIntLike(&size_iter, &height)) {
+                              if (strcmp(prop_key, "logical_size") == 0) {
+                                logical_width = width;
+                                logical_height = height;
+                              } else if (strcmp(prop_key, "size") == 0) {
+                                stream_width = width;
+                                stream_height = height;
+                              }
+                            }
+                          }
+                        }
+                      }
+                      dbus_message_iter_next(&props);
+                    }
+
+                    const int picked_width =
+                        logical_width > 0 ? logical_width : stream_width;
+                    const int picked_height =
+                        logical_height > 0 ? logical_height : stream_height;
+                    LOG_INFO(
+                        "Wayland portal stream geometry: stream_size={}x{}, "
+                        "logical_size={}x{}, pointer_space={}x{}",
+                        stream_width, stream_height, logical_width,
+                        logical_height, picked_width, picked_height);
+
+                    portal_stream_width_ = stream_width;
+                    portal_stream_height_ = stream_height;
+                    portal_has_logical_size_ =
+                        logical_width > 0 && logical_height > 0;
+
+                    if (logical_width > 0 && logical_height > 0) {
+                      logical_width_ = logical_width;
+                      logical_height_ = logical_height;
+                      UpdateDisplayGeometry(logical_width_, logical_height_);
+                    } else if (stream_width > 0 && stream_height > 0) {
+                      logical_width_ = stream_width;
+                      logical_height_ = stream_height;
+                      UpdateDisplayGeometry(logical_width_, logical_height_);
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          dbus_message_iter_next(&dict);
+        }
+        pointer_granted_ = (granted_devices & kRemoteDesktopDevicePointer) != 0;
+        return true;
+      });
+  if (!ok) {
+    return false;
+  }
+
+  if (pipewire_node_id_ == 0) {
+    LOG_ERROR("Start response did not include a PipeWire node id");
+    return false;
+  }
+  if (!pointer_granted_) {
+    LOG_ERROR("Start response did not grant pointer control");
+    return false;
+  }
+
+  shared_session_registered_ =
+      PublishSharedWaylandPortalSession(SharedWaylandPortalSessionInfo{
+          dbus_connection_, session_handle_, pipewire_node_id_, logical_width_,
+          logical_height_, pointer_granted_});
+  if (!shared_session_registered_) {
+    LOG_WARN("Failed to publish shared Wayland portal session");
+  }
+
+  LOG_INFO("Wayland screencast ready, node_id={}", pipewire_node_id_);
+  return true;
+}
+
+bool ScreenCapturerWayland::OpenPipeWireRemote() {
+  if (!dbus_connection_ || session_handle_.empty()) {
+    return false;
+  }
+
+  DBusMessage* message = dbus_message_new_method_call(
+      kPortalBusName, kPortalObjectPath, kPortalScreenCastInterface,
+      "OpenPipeWireRemote");
+  if (!message) {
+    LOG_ERROR("Failed to allocate OpenPipeWireRemote message");
+    return false;
+  }
+
+  DBusMessageIter iter;
+  DBusMessageIter options;
+  const char* session_handle = session_handle_.c_str();
+  dbus_message_iter_init_append(message, &iter);
+  dbus_message_iter_append_basic(&iter, DBUS_TYPE_OBJECT_PATH, &session_handle);
+  dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{sv}", &options);
+  dbus_message_iter_close_container(&iter, &options);
+
+  DBusError error;
+  dbus_error_init(&error);
+  DBusMessage* reply = dbus_connection_send_with_reply_and_block(
+      dbus_connection_, message, -1, &error);
+  dbus_message_unref(message);
+  if (!reply) {
+    LogDbusError("OpenPipeWireRemote", &error);
+    dbus_error_free(&error);
+    return false;
+  }
+
+  DBusMessageIter reply_iter;
+  if (!dbus_message_iter_init(reply, &reply_iter) ||
+      dbus_message_iter_get_arg_type(&reply_iter) != DBUS_TYPE_UNIX_FD) {
+    LOG_ERROR("OpenPipeWireRemote returned an unexpected payload");
+    dbus_message_unref(reply);
+    return false;
+  }
+
+  int received_fd = -1;
+  dbus_message_iter_get_basic(&reply_iter, &received_fd);
+  dbus_message_unref(reply);
+
+  if (received_fd < 0) {
+    LOG_ERROR("OpenPipeWireRemote returned an invalid fd");
+    return false;
+  }
+
+  pipewire_fd_ = dup(received_fd);
+  if (pipewire_fd_ < 0) {
+    LOG_ERROR("Failed to duplicate PipeWire remote fd");
+    return false;
+  }
+
+  return true;
+}
+
+void ScreenCapturerWayland::CleanupDbus() {
+  if (!dbus_connection_) {
+    return;
+  }
+
+  if (shared_session_registered_) {
+    return;
+  }
+
+  dbus_connection_close(dbus_connection_);
+  dbus_connection_unref(dbus_connection_);
+  dbus_connection_ = nullptr;
+}
+
+void ScreenCapturerWayland::ClosePortalSession() {
+  if (shared_session_registered_) {
+    DBusConnection* close_connection = nullptr;
+    std::string close_session_handle;
+    ReleaseSharedWaylandPortalSession(&close_connection, &close_session_handle);
+    shared_session_registered_ = false;
+    if (close_connection) {
+      CloseWaylandPortalSessionAndConnection(
+          close_connection, close_session_handle, "Session.Close");
+    }
+    dbus_connection_ = nullptr;
+  } else if (dbus_connection_ && !session_handle_.empty()) {
+    CloseWaylandPortalSessionAndConnection(dbus_connection_, session_handle_,
+                                           "Session.Close");
+    dbus_connection_ = nullptr;
+  }
+
+  session_handle_.clear();
+  pipewire_node_id_ = 0;
+  UpdateDisplayGeometry(
+      logical_width_ > 0 ? logical_width_ : kFallbackWidth,
+      logical_height_ > 0 ? logical_height_ : kFallbackHeight);
+  pointer_granted_ = false;
+}
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_x11.cpp

@@ -0,0 +1,437 @@
+#include "screen_capturer_x11.h"
+
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <X11/extensions/Xfixes.h>
+#include <X11/extensions/Xrandr.h>
+
+#include <algorithm>
+#include <chrono>
+#include <mutex>
+#include <thread>
+
+#include <display_stream_id.h>
+#include "libyuv.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+namespace {
+
+std::atomic<int> g_x11_last_error_code{0};
+std::mutex g_x11_error_handler_mutex;
+
+int CaptureX11ErrorHandler([[maybe_unused]] Display* display,
+                           XErrorEvent* error_event) {
+  if (error_event) {
+    g_x11_last_error_code.store(error_event->error_code);
+  } else {
+    g_x11_last_error_code.store(-1);
+  }
+  return 0;
+}
+
+class ScopedX11ErrorTrap {
+ public:
+  explicit ScopedX11ErrorTrap(Display* display)
+      : display_(display), lock_(g_x11_error_handler_mutex) {
+    g_x11_last_error_code.store(0);
+    previous_handler_ = XSetErrorHandler(CaptureX11ErrorHandler);
+  }
+
+  ~ScopedX11ErrorTrap() {
+    if (display_) {
+      XSync(display_, False);
+    }
+    XSetErrorHandler(previous_handler_);
+  }
+
+  int SyncAndGetError() const {
+    if (display_) {
+      XSync(display_, False);
+    }
+    return g_x11_last_error_code.load();
+  }
+
+ private:
+  Display* display_ = nullptr;
+  int (*previous_handler_)(Display*, XErrorEvent*) = nullptr;
+  std::unique_lock<std::mutex> lock_;
+};
+
+}  // namespace
+
+ScreenCapturerX11::ScreenCapturerX11() {}
+
+ScreenCapturerX11::~ScreenCapturerX11() { Destroy(); }
+
+int ScreenCapturerX11::Init(const int fps, cb_desktop_data cb) {
+  Destroy();
+
+  display_ = XOpenDisplay(nullptr);
+  if (!display_) {
+    LOG_ERROR("Cannot connect to X server");
+    return -1;
+  }
+
+  root_ = DefaultRootWindow(display_);
+  screen_res_ = XRRGetScreenResources(display_, root_);
+  if (!screen_res_) {
+    LOG_ERROR("Failed to get screen resources");
+    XCloseDisplay(display_);
+    display_ = nullptr;
+    return 1;
+  }
+
+  for (int i = 0; i < screen_res_->noutput; ++i) {
+    RROutput output = screen_res_->outputs[i];
+    XRROutputInfo* output_info =
+        XRRGetOutputInfo(display_, screen_res_, output);
+
+    if (output_info->connection == RR_Connected && output_info->crtc != 0) {
+      XRRCrtcInfo* crtc_info =
+          XRRGetCrtcInfo(display_, screen_res_, output_info->crtc);
+
+      std::string name(output_info->name);
+
+      if (name.empty()) {
+        name = "Display" + std::to_string(i + 1);
+      }
+
+      display_info_list_.push_back(DisplayInfo(
+          (void*)display_, name, true, crtc_info->x, crtc_info->y,
+          crtc_info->x + crtc_info->width, crtc_info->y + crtc_info->height));
+
+      XRRFreeCrtcInfo(crtc_info);
+    }
+
+    if (output_info) {
+      XRRFreeOutputInfo(output_info);
+    }
+  }
+
+  XWindowAttributes attr;
+  XGetWindowAttributes(display_, root_, &attr);
+
+  width_ = attr.width;
+  height_ = attr.height;
+
+  if ((width_ & 1) != 0 || (height_ & 1) != 0) {
+    LOG_WARN("X11 root size {}x{} is not even, aligning down to {}x{} for NV12",
+             width_, height_, width_ & ~1, height_ & ~1);
+    width_ &= ~1;
+    height_ &= ~1;
+  }
+
+  if (width_ <= 1 || height_ <= 1) {
+    LOG_ERROR("Invalid capture size after alignment: {}x{}", width_, height_);
+    return -2;
+  }
+
+  fps_ = fps;
+  callback_ = cb;
+
+  y_plane_.resize(width_ * height_);
+  uv_plane_.resize((width_ / 2) * (height_ / 2) * 2);
+
+  if (!ProbeCapture()) {
+    LOG_ERROR("X11 backend probe failed, XGetImage is not usable");
+    return -3;
+  }
+
+  return 0;
+}
+
+int ScreenCapturerX11::Destroy() {
+  Stop();
+
+  y_plane_.clear();
+  uv_plane_.clear();
+
+  if (screen_res_) {
+    XRRFreeScreenResources(screen_res_);
+    screen_res_ = nullptr;
+  }
+
+  if (display_) {
+    XCloseDisplay(display_);
+    display_ = nullptr;
+  }
+  return 0;
+}
+
+int ScreenCapturerX11::Start(bool show_cursor) {
+  if (running_) return 0;
+  show_cursor_ = show_cursor;
+  running_ = true;
+  paused_ = false;
+  capture_error_count_ = 0;
+  thread_ = std::thread([this]() {
+    using clock = std::chrono::steady_clock;
+    const auto frame_interval =
+        std::chrono::milliseconds(std::max(1, 1000 / std::max(1, fps_)));
+
+    while (running_) {
+      const auto frame_start = clock::now();
+      if (!paused_) {
+        OnFrame();
+      }
+
+      const auto elapsed =
+          std::chrono::duration_cast<std::chrono::milliseconds>(clock::now() -
+                                                                frame_start);
+      if (elapsed < frame_interval) {
+        std::this_thread::sleep_for(frame_interval - elapsed);
+      }
+    }
+  });
+  return 0;
+}
+
+int ScreenCapturerX11::Stop() {
+  if (!running_) return 0;
+  running_ = false;
+  if (thread_.joinable()) thread_.join();
+  return 0;
+}
+
+int ScreenCapturerX11::Pause(int monitor_index) {
+  paused_ = true;
+  return 0;
+}
+
+int ScreenCapturerX11::Resume(int monitor_index) {
+  paused_ = false;
+  return 0;
+}
+
+int ScreenCapturerX11::SwitchTo(int monitor_index) {
+  monitor_index_ = monitor_index;
+  return 0;
+}
+
+int ScreenCapturerX11::ResetToInitialMonitor() {
+  monitor_index_ = initial_monitor_index_;
+  return 0;
+}
+std::vector<DisplayInfo> ScreenCapturerX11::GetDisplayInfoList() {
+  return display_info_list_;
+}
+
+void ScreenCapturerX11::OnFrame() {
+  if (!display_) {
+    LOG_ERROR("Display is not initialized");
+    return;
+  }
+
+  const int monitor_index = monitor_index_.load();
+  if (monitor_index < 0 ||
+      monitor_index >= static_cast<int>(display_info_list_.size())) {
+    LOG_ERROR("Invalid monitor index: {}", monitor_index);
+    return;
+  }
+
+  left_ = display_info_list_[monitor_index].left;
+  top_ = display_info_list_[monitor_index].top;
+  width_ = display_info_list_[monitor_index].width & ~1;
+  height_ = display_info_list_[monitor_index].height & ~1;
+
+  if (width_ <= 1 || height_ <= 1) {
+    LOG_ERROR("Invalid capture size: {}x{}", width_, height_);
+    return;
+  }
+
+  XImage* image = nullptr;
+  int x11_error = 0;
+  {
+    ScopedX11ErrorTrap trap(display_);
+    image = XGetImage(display_, root_, left_, top_, width_, height_, AllPlanes,
+                      ZPixmap);
+    x11_error = trap.SyncAndGetError();
+  }
+
+  if (x11_error != 0 || !image) {
+    if (image) {
+      XDestroyImage(image);
+    }
+    ++capture_error_count_;
+    if (capture_error_count_ == 1 || capture_error_count_ % 120 == 0) {
+      LOG_WARN("X11 capture failed: x11_error={}, image={}, consecutive={}",
+               x11_error, image ? "valid" : "null", capture_error_count_);
+    }
+    return;
+  }
+  capture_error_count_ = 0;
+
+  // if enable show cursor, draw cursor
+  if (show_cursor_) {
+    Window root_return, child_return;
+    int root_x, root_y, win_x, win_y;
+    unsigned int mask;
+    if (XQueryPointer(display_, root_, &root_return, &child_return, &root_x,
+                      &root_y, &win_x, &win_y, &mask)) {
+      if (root_x >= left_ && root_x < left_ + width_ && root_y >= top_ &&
+          root_y < top_ + height_) {
+        DrawCursor(image, root_x - left_, root_y - top_);
+      }
+    }
+  }
+
+  if (image->bits_per_pixel != 32 || image->bytes_per_line <= 0) {
+    LOG_WARN(
+        "Unsupported X11 image layout: bits_per_pixel={}, bytes_per_line={}",
+        image->bits_per_pixel, image->bytes_per_line);
+    XDestroyImage(image);
+    return;
+  }
+
+  const uint8_t* src_argb = reinterpret_cast<const uint8_t*>(image->data);
+  const int src_stride_argb = image->bytes_per_line;
+
+  const size_t y_size =
+      static_cast<size_t>(width_) * static_cast<size_t>(height_);
+  const size_t uv_size = y_size / 2;
+  if (y_plane_.size() != y_size) {
+    y_plane_.resize(y_size);
+  }
+  if (uv_plane_.size() != uv_size) {
+    uv_plane_.resize(uv_size);
+  }
+
+  const int convert_ret =
+      use_abgr_to_nv12_
+          ? libyuv::ABGRToNV12(src_argb, src_stride_argb, y_plane_.data(),
+                               width_, uv_plane_.data(), width_, width_,
+                               height_)
+          : libyuv::ARGBToNV12(src_argb, src_stride_argb, y_plane_.data(),
+                               width_, uv_plane_.data(), width_, width_,
+                               height_);
+  if (convert_ret != 0) {
+    LOG_WARN("X11 {} failed: {}",
+             use_abgr_to_nv12_ ? "ABGRToNV12" : "ARGBToNV12", convert_ret);
+    XDestroyImage(image);
+    return;
+  }
+
+  std::vector<uint8_t> nv12;
+  nv12.reserve(y_plane_.size() + uv_plane_.size());
+  nv12.insert(nv12.end(), y_plane_.begin(), y_plane_.end());
+  nv12.insert(nv12.end(), uv_plane_.begin(), uv_plane_.end());
+
+  if (callback_) {
+    const std::string stream_id = MakeDisplayStreamId(monitor_index);
+    callback_(nv12.data(), width_ * height_ * 3 / 2, width_, height_,
+              stream_id.c_str());
+  }
+
+  XDestroyImage(image);
+}
+
+void ScreenCapturerX11::DrawCursor(XImage* image, int x, int y) {
+  if (!display_ || !image) {
+    return;
+  }
+
+  // check XFixes extension
+  int event_base, error_base;
+  if (!XFixesQueryExtension(display_, &event_base, &error_base)) {
+    return;
+  }
+
+  XFixesCursorImage* cursor_image = XFixesGetCursorImage(display_);
+  if (!cursor_image) {
+    return;
+  }
+
+  int cursor_width = cursor_image->width;
+  int cursor_height = cursor_image->height;
+
+  int draw_x = x - cursor_image->xhot;
+  int draw_y = y - cursor_image->yhot;
+
+  // draw cursor on image
+  for (int cy = 0; cy < cursor_height; ++cy) {
+    for (int cx = 0; cx < cursor_width; ++cx) {
+      int img_x = draw_x + cx;
+      int img_y = draw_y + cy;
+
+      if (img_x < 0 || img_x >= image->width || img_y < 0 ||
+          img_y >= image->height) {
+        continue;
+      }
+
+      unsigned long cursor_pixel = cursor_image->pixels[cy * cursor_width + cx];
+      unsigned char a = (cursor_pixel >> 24) & 0xFF;
+
+      // if alpha is 0, skip
+      if (a == 0) {
+        continue;
+      }
+
+      unsigned long img_pixel = XGetPixel(image, img_x, img_y);
+
+      unsigned char img_r = (img_pixel >> 16) & 0xFF;
+      unsigned char img_g = (img_pixel >> 8) & 0xFF;
+      unsigned char img_b = img_pixel & 0xFF;
+
+      unsigned char cursor_r = (cursor_pixel >> 16) & 0xFF;
+      unsigned char cursor_g = (cursor_pixel >> 8) & 0xFF;
+      unsigned char cursor_b = cursor_pixel & 0xFF;
+
+      // alpha mix
+      unsigned char final_r, final_g, final_b;
+      if (a == 255) {
+        // if alpha is 255, use cursor color
+        final_r = cursor_r;
+        final_g = cursor_g;
+        final_b = cursor_b;
+      } else {
+        float alpha = a / 255.0f;
+        float inv_alpha = 1.0f - alpha;
+        final_r =
+            static_cast<unsigned char>(cursor_r * alpha + img_r * inv_alpha);
+        final_g =
+            static_cast<unsigned char>(cursor_g * alpha + img_g * inv_alpha);
+        final_b =
+            static_cast<unsigned char>(cursor_b * alpha + img_b * inv_alpha);
+      }
+
+      // set pixel
+      unsigned long new_pixel = (final_r << 16) | (final_g << 8) | final_b;
+      XPutPixel(image, img_x, img_y, new_pixel);
+    }
+  }
+
+  XFree(cursor_image);
+}
+
+bool ScreenCapturerX11::ProbeCapture() {
+  if (!display_ || display_info_list_.empty()) {
+    return false;
+  }
+
+  const auto& first_display = display_info_list_[0];
+  XImage* probe_image = nullptr;
+  int x11_error = 0;
+  {
+    ScopedX11ErrorTrap trap(display_);
+    probe_image = XGetImage(display_, root_, first_display.left,
+                            first_display.top, 1, 1, AllPlanes, ZPixmap);
+    x11_error = trap.SyncAndGetError();
+  }
+
+  if (x11_error != 0 || !probe_image) {
+    LOG_WARN("X11 probe XGetImage failed: x11_error={}, image={}", x11_error,
+             probe_image ? "valid" : "null");
+    return false;
+  }
+
+  const bool red_in_low_byte = (probe_image->red_mask & 0x000000FFu) != 0;
+  const bool blue_in_low_byte = (probe_image->blue_mask & 0x000000FFu) != 0;
+  use_abgr_to_nv12_ = red_in_low_byte && !blue_in_low_byte;
+
+  XDestroyImage(probe_image);
+
+  return true;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/linux/screen_capturer/screen_capturer_x11.h

@@ -0,0 +1,80 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2025-05-07
+ * Copyright (c) 2025 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_X11_H_
+#define _SCREEN_CAPTURER_X11_H_
+
+// forward declarations for X11 types
+struct _XDisplay;
+typedef struct _XDisplay Display;
+typedef unsigned long Window;
+struct _XRRScreenResources;
+typedef struct _XRRScreenResources XRRScreenResources;
+struct _XImage;
+typedef struct _XImage XImage;
+
+#include <atomic>
+#include <cctype>
+#include <cstring>
+#include <functional>
+#include <iostream>
+#include <thread>
+#include <vector>
+
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerX11 : public ScreenCapturer {
+ public:
+  ScreenCapturerX11();
+  ~ScreenCapturerX11();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override;
+
+  void OnFrame();
+
+ private:
+  void DrawCursor(XImage* image, int x, int y);
+  bool ProbeCapture();
+
+ private:
+  Display* display_ = nullptr;
+  Window root_ = 0;
+  XRRScreenResources* screen_res_ = nullptr;
+  int left_ = 0;
+  int top_ = 0;
+  int width_ = 0;
+  int height_ = 0;
+  std::thread thread_;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  std::atomic<int> monitor_index_{0};
+  int initial_monitor_index_ = 0;
+  std::atomic<bool> show_cursor_{true};
+  int fps_ = 60;
+  cb_desktop_data callback_;
+  std::vector<DisplayInfo> display_info_list_;
+  int capture_error_count_ = 0;
+  bool use_abgr_to_nv12_ = false;
+
+  std::vector<uint8_t> y_plane_;
+  std::vector<uint8_t> uv_plane_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/linux/speaker_capturer/speaker_capturer_factory.cpp

@@ -0,0 +1,11 @@
+#include "speaker_capturer_factory.h"
+
+#include "speaker_capturer_linux.h"
+
+namespace crossdesk {
+
+SpeakerCapturer* SpeakerCapturerFactory::Create() {
+  return new SpeakerCapturerLinux();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/linux/speaker_capturer/speaker_capturer_linux.cpp

@@ -0,0 +1,271 @@
+#include "speaker_capturer_linux.h"
+
+#include <pulse/error.h>
+#include <pulse/introspect.h>
+
+#include <condition_variable>
+#include <iostream>
+#include <thread>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+constexpr int kSampleRate = 48000;
+constexpr pa_sample_format_t kFormat = PA_SAMPLE_S16LE;
+constexpr int kChannels = 1;
+constexpr size_t kFrameSizeBytes = 480 * sizeof(int16_t);
+
+SpeakerCapturerLinux::SpeakerCapturerLinux()
+    : inited_(false), paused_(false), stop_flag_(false) {}
+SpeakerCapturerLinux::~SpeakerCapturerLinux() {
+  Stop();
+  Destroy();
+}
+
+int SpeakerCapturerLinux::Init(speaker_data_cb cb) {
+  if (inited_) return 0;
+  cb_ = cb;
+  inited_ = true;
+  return 0;
+}
+
+int SpeakerCapturerLinux::Destroy() {
+  inited_ = false;
+  return 0;
+}
+
+std::string SpeakerCapturerLinux::GetDefaultMonitorSourceName() {
+  std::string monitor_name;
+  std::mutex mtx;
+  std::condition_variable cv;
+  bool ready = false;
+
+  pa_mainloop* mainloop = pa_mainloop_new();
+  pa_mainloop_api* api = pa_mainloop_get_api(mainloop);
+  pa_context* context = pa_context_new(api, "GetMonitor");
+
+  struct CallbackState {
+    std::string* name;
+    std::mutex* mtx;
+    std::condition_variable* cv;
+    bool* ready;
+  } state{&monitor_name, &mtx, &cv, &ready};
+
+  pa_context_set_state_callback(
+      context,
+      [](pa_context* c, void* userdata) {
+        auto* state = static_cast<CallbackState*>(userdata);
+        if (pa_context_get_state(c) == PA_CONTEXT_READY) {
+          pa_operation* operation = pa_context_get_server_info(
+              c,
+              [](pa_context*, const pa_server_info* info, void* userdata) {
+                auto* state = static_cast<CallbackState*>(userdata);
+                if (info && info->default_sink_name) {
+                  *(state->name) =
+                      std::string(info->default_sink_name) + ".monitor";
+                }
+                {
+                  std::lock_guard<std::mutex> lock(*(state->mtx));
+                  *(state->ready) = true;
+                }
+                state->cv->notify_one();
+              },
+              userdata);
+          if (operation) {
+            pa_operation_unref(operation);
+          }
+        }
+      },
+      &state);
+
+  pa_context_connect(context, nullptr, PA_CONTEXT_NOFLAGS, nullptr);
+
+  std::thread loop_thread([&]() {
+    int ret = 0;
+    pa_mainloop_run(mainloop, &ret);
+  });
+
+  {
+    std::unique_lock<std::mutex> lock(mtx);
+    cv.wait_for(lock, std::chrono::seconds(2), [&] { return ready; });
+  }
+
+  pa_context_disconnect(context);
+  pa_context_unref(context);
+  pa_mainloop_quit(mainloop, 0);
+  loop_thread.join();
+  pa_mainloop_free(mainloop);
+
+  return monitor_name;
+}
+
+int SpeakerCapturerLinux::Start() {
+  if (!inited_ || mainloop_thread_.joinable()) return -1;
+  stop_flag_ = false;
+
+  mainloop_thread_ = std::thread([this]() {
+    std::string monitor_name = GetDefaultMonitorSourceName();
+    if (monitor_name.empty()) {
+      LOG_ERROR("Failed to get monitor source");
+      return;
+    }
+
+    mainloop_ = pa_threaded_mainloop_new();
+    pa_mainloop_api* api = pa_threaded_mainloop_get_api(mainloop_);
+    context_ = pa_context_new(api, "SpeakerCapturer");
+
+    pa_context_set_state_callback(
+        context_,
+        [](pa_context* c, void* userdata) {
+          auto self = static_cast<SpeakerCapturerLinux*>(userdata);
+          pa_context_state_t state = pa_context_get_state(c);
+          if (state == PA_CONTEXT_READY || state == PA_CONTEXT_FAILED ||
+              state == PA_CONTEXT_TERMINATED) {
+            pa_threaded_mainloop_signal(self->mainloop_, 0);
+          }
+        },
+        this);
+
+    if (pa_threaded_mainloop_start(mainloop_) < 0) {
+      LOG_ERROR("Failed to start mainloop");
+      Cleanup();
+      return;
+    }
+
+    pa_threaded_mainloop_lock(mainloop_);
+
+    if (pa_context_connect(context_, nullptr, PA_CONTEXT_NOFLAGS, nullptr) <
+        0) {
+      LOG_ERROR("Failed to connect context");
+      pa_threaded_mainloop_unlock(mainloop_);
+      Cleanup();
+      return;
+    }
+
+    while (true) {
+      pa_context_state_t state = pa_context_get_state(context_);
+      if (state == PA_CONTEXT_READY) break;
+      if (!PA_CONTEXT_IS_GOOD(state) || stop_flag_) {
+        pa_threaded_mainloop_unlock(mainloop_);
+        Cleanup();
+        return;
+      }
+      pa_threaded_mainloop_wait(mainloop_);
+    }
+
+    pa_sample_spec ss = {kFormat, kSampleRate, kChannels};
+    stream_ = pa_stream_new(context_, "Capture", &ss, nullptr);
+
+    pa_stream_set_read_callback(
+        stream_,
+        [](pa_stream* s, size_t len, void* u) {
+          auto self = static_cast<SpeakerCapturerLinux*>(u);
+          if (self->paused_ || self->stop_flag_) return;
+
+          const void* data = nullptr;
+          if (pa_stream_peek(s, &data, &len) < 0 || !data) return;
+
+          const uint8_t* p = static_cast<const uint8_t*>(data);
+          self->frame_cache_.insert(self->frame_cache_.end(), p, p + len);
+
+          while (self->frame_cache_.size() >= kFrameSizeBytes) {
+            std::vector<uint8_t> temp_frame(
+                self->frame_cache_.begin(),
+                self->frame_cache_.begin() + kFrameSizeBytes);
+            self->cb_(temp_frame.data(), kFrameSizeBytes, "audio");
+            self->frame_cache_.erase(
+                self->frame_cache_.begin(),
+                self->frame_cache_.begin() + kFrameSizeBytes);
+          }
+
+          pa_stream_drop(s);
+        },
+        this);
+
+    pa_buffer_attr attr = {.maxlength = (uint32_t)-1,
+                           .tlength = 0,
+                           .prebuf = 0,
+                           .minreq = 0,
+                           .fragsize = (uint32_t)kFrameSizeBytes};
+
+    if (pa_stream_connect_record(stream_, monitor_name.c_str(), &attr,
+                                 PA_STREAM_ADJUST_LATENCY) < 0) {
+      LOG_ERROR("Failed to connect stream");
+      pa_threaded_mainloop_unlock(mainloop_);
+      Cleanup();
+      return;
+    }
+
+    while (true) {
+      pa_stream_state_t s = pa_stream_get_state(stream_);
+      if (s == PA_STREAM_READY) break;
+      if (!PA_STREAM_IS_GOOD(s) || stop_flag_) {
+        pa_threaded_mainloop_unlock(mainloop_);
+        Cleanup();
+        return;
+      }
+      pa_threaded_mainloop_wait(mainloop_);
+    }
+
+    pa_threaded_mainloop_unlock(mainloop_);
+
+    while (!stop_flag_)
+      std::this_thread::sleep_for(std::chrono::milliseconds(100));
+  });
+
+  return 0;
+}
+
+int SpeakerCapturerLinux::Stop() {
+  stop_flag_ = true;
+
+  if (mainloop_) {
+    pa_threaded_mainloop_lock(mainloop_);
+    pa_threaded_mainloop_signal(mainloop_, 0);
+    pa_threaded_mainloop_unlock(mainloop_);
+  }
+
+  if (mainloop_thread_.joinable()) {
+    mainloop_thread_.join();
+  }
+
+  Cleanup();
+  return 0;
+}
+
+void SpeakerCapturerLinux::Cleanup() {
+  if (mainloop_) {
+    pa_threaded_mainloop_stop(mainloop_);
+    pa_threaded_mainloop_lock(mainloop_);
+
+    if (stream_) {
+      pa_stream_disconnect(stream_);
+      pa_stream_unref(stream_);
+      stream_ = nullptr;
+    }
+
+    if (context_) {
+      pa_context_disconnect(context_);
+      pa_context_unref(context_);
+      context_ = nullptr;
+    }
+
+    pa_threaded_mainloop_unlock(mainloop_);
+    pa_threaded_mainloop_free(mainloop_);
+    mainloop_ = nullptr;
+  }
+
+  frame_cache_.clear();
+}
+
+int SpeakerCapturerLinux::Pause() {
+  paused_ = true;
+  return 0;
+}
+
+int SpeakerCapturerLinux::Resume() {
+  paused_ = false;
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/linux/speaker_capturer/speaker_capturer_linux.h

@@ -0,0 +1,56 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2025-07-15
+ * Copyright (c) 2025 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SPEAKER_CAPTURER_LINUX_H_
+#define _SPEAKER_CAPTURER_LINUX_H_
+
+#include <pulse/pulseaudio.h>
+
+#include <atomic>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "speaker_capturer.h"
+
+namespace crossdesk {
+
+class SpeakerCapturerLinux : public SpeakerCapturer {
+ public:
+  SpeakerCapturerLinux();
+  ~SpeakerCapturerLinux();
+
+  int Init(speaker_data_cb cb) override;
+  int Destroy() override;
+  int Start() override;
+  int Stop() override;
+
+  int Pause();
+  int Resume();
+
+ private:
+  std::string GetDefaultMonitorSourceName();
+  void Cleanup();
+
+ private:
+  speaker_data_cb cb_ = nullptr;
+
+  std::atomic<bool> inited_;
+  std::atomic<bool> paused_;
+  std::atomic<bool> stop_flag_;
+
+  std::thread mainloop_thread_;
+  pa_threaded_mainloop* mainloop_ = nullptr;
+  pa_context* context_ = nullptr;
+  pa_stream* stream_ = nullptr;
+
+  std::mutex state_mtx_;
+  std::vector<uint8_t> frame_cache_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/linux/system_info.cpp

@@ -0,0 +1,81 @@
+#include "platform.h"
+
+#include <fcntl.h>
+#include <net/if.h>
+#include <sys/ioctl.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+std::string GetMac() {
+  const int socket_fd = socket(AF_INET, SOCK_DGRAM, 0);
+  if (socket_fd < 0) return {};
+
+  char buffer[1024] = {};
+  struct ifconf config = {};
+  config.ifc_len = sizeof(buffer);
+  config.ifc_buf = buffer;
+  if (ioctl(socket_fd, SIOCGIFCONF, &config) < 0) {
+    close(socket_fd);
+    return {};
+  }
+
+  std::string result;
+  struct ifreq request = {};
+  struct ifreq* cursor = config.ifc_req;
+  const struct ifreq* end = cursor + config.ifc_len / sizeof(struct ifreq);
+  for (; cursor != end; ++cursor) {
+    std::strncpy(request.ifr_name, cursor->ifr_name,
+                 sizeof(request.ifr_name) - 1);
+    if (ioctl(socket_fd, SIOCGIFFLAGS, &request) < 0 ||
+        (request.ifr_flags & IFF_LOOPBACK) ||
+        ioctl(socket_fd, SIOCGIFHWADDR, &request) < 0) {
+      continue;
+    }
+    char address[16] = {};
+    int length = 0;
+    for (int index = 0; index < 6; ++index) {
+      length += std::snprintf(
+          address + length, sizeof(address) - length, "%.2X",
+          static_cast<unsigned char>(request.ifr_hwaddr.sa_data[index]));
+    }
+    result = address;
+    break;
+  }
+  close(socket_fd);
+  return result;
+}
+
+std::string GetHostName() {
+  char hostname[256] = {};
+  if (gethostname(hostname, sizeof(hostname)) == -1) {
+    LOG_ERROR("gethostname failed");
+    return {};
+  }
+  return hostname;
+}
+
+bool IsWaylandSession() {
+  const char* session_type = std::getenv("XDG_SESSION_TYPE");
+  if (session_type) {
+    if (std::strcmp(session_type, "wayland") == 0 ||
+        std::strcmp(session_type, "Wayland") == 0) {
+      return true;
+    }
+    if (std::strcmp(session_type, "x11") == 0 ||
+        std::strcmp(session_type, "X11") == 0) {
+      return false;
+    }
+  }
+  const char* display = std::getenv("WAYLAND_DISPLAY");
+  return display && display[0] != '\0';
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/macos/autostart.cpp

@@ -0,0 +1,74 @@
+#include "platform/autostart_backend.h"
+
+#include <limits.h>
+#include <mach-o/dyld.h>
+
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+
+namespace crossdesk::platform {
+namespace {
+
+std::filesystem::path AutostartPath(const std::string& app_name) {
+  const char* home = std::getenv("HOME");
+  if (!home || !home[0]) return {};
+  return std::filesystem::path(home) / "Library" / "LaunchAgents" /
+         (app_name + ".plist");
+}
+
+}  // namespace
+
+std::string GetAutostartExecutablePath() {
+  char path[PATH_MAX] = {};
+  uint32_t size = sizeof(path);
+  if (_NSGetExecutablePath(path, &size) != 0) return {};
+  char resolved[PATH_MAX] = {};
+  return realpath(path, resolved) ? std::string(resolved) : std::string(path);
+}
+
+bool EnableAutostart(const std::string& app_name,
+                     const std::string& executable_path) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  if (path.empty()) return false;
+
+  std::error_code error;
+  std::filesystem::create_directories(path.parent_path(), error);
+  if (error) return false;
+
+  std::ofstream file(path);
+  if (!file.is_open()) return false;
+  file << R"(<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>)"
+       << app_name << R"(</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>)"
+       << executable_path << R"(</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>)";
+  file.close();
+  return file.good();
+}
+
+bool DisableAutostart(const std::string& app_name) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  if (path.empty()) return false;
+  std::error_code error;
+  return std::filesystem::remove(path, error) && !error;
+}
+
+bool IsAutostartEnabled(const std::string& app_name) {
+  const std::filesystem::path path = AutostartPath(app_name);
+  return !path.empty() && std::filesystem::is_regular_file(path);
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/macos/clipboard.mm

@@ -0,0 +1,114 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2025-12-18
+ * Copyright (c) 2025 by DI JUNKUN, All Rights Reserved.
+ */
+
+#include "clipboard.h"
+
+#include <AppKit/AppKit.h>
+#include <CoreFoundation/CoreFoundation.h>
+#include <string>
+
+#include "platform/clipboard_backend.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+static CFRunLoopRef g_monitor_runloop = nullptr;
+
+std::string Clipboard::GetText() {
+  @autoreleasepool {
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    NSString* string = [pasteboard stringForType:NSPasteboardTypeString];
+    if (string == nil) {
+      return "";
+    }
+    return std::string([string UTF8String]);
+  }
+}
+
+bool Clipboard::SetText(const std::string& text) {
+  @autoreleasepool {
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    [pasteboard clearContents];
+    NSString* string = [NSString stringWithUTF8String:text.c_str()];
+    if (string == nil) {
+      LOG_ERROR("Clipboard::SetText: failed to create NSString");
+      return false;
+    }
+    BOOL success = [pasteboard setString:string forType:NSPasteboardTypeString];
+    return success == YES;
+  }
+}
+
+bool Clipboard::HasText() {
+  @autoreleasepool {
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    NSArray* types = [pasteboard types];
+    return [types containsObject:NSPasteboardTypeString];
+  }
+}
+
+namespace platform {
+
+void RunClipboardMonitor(int) {
+  @autoreleasepool {
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+
+    // Store RunLoop reference for waking up
+    NSRunLoop* runLoop = [NSRunLoop currentRunLoop];
+    g_monitor_runloop = [runLoop getCFRunLoop];
+    if (g_monitor_runloop) {
+      CFRetain(g_monitor_runloop);
+    }
+
+    // Track changeCount to detect clipboard changes
+    // Use __block to allow modification inside the block
+    __block NSInteger lastChangeCount = [pasteboard changeCount];
+
+    LOG_INFO("Clipboard event monitoring started (macOS)");
+
+    // Use a timer to periodically check changeCount
+    // This is more reliable than NSPasteboardDidChangeNotification which may not be available
+    NSTimer* timer =
+        [NSTimer scheduledTimerWithTimeInterval:0.1
+                                        repeats:YES
+                                          block:^(NSTimer* timer) {
+                                            if (!ClipboardMonitoring()) {
+                                              [timer invalidate];
+                                              return;
+                                            }
+                                            NSInteger currentChangeCount = [pasteboard changeCount];
+                                            if (currentChangeCount != lastChangeCount) {
+                                              lastChangeCount = currentChangeCount;
+                                              HandleClipboardChange();
+                                            }
+                                          }];
+
+    while (ClipboardMonitoring()) {
+      @autoreleasepool {
+        NSDate* date = [NSDate dateWithTimeIntervalSinceNow:0.1];
+        [runLoop runMode:NSDefaultRunLoopMode beforeDate:date];
+      }
+    }
+
+    // Cleanup
+    [timer invalidate];
+    if (g_monitor_runloop) {
+      CFRelease(g_monitor_runloop);
+      g_monitor_runloop = nullptr;
+    }
+  }
+}
+
+void WakeClipboardMonitor() {
+  // Wake up the RunLoop immediately so it can observe monitoring shutdown.
+  // This ensures the RunLoop exits promptly instead of waiting up to 0.1 seconds
+  if (g_monitor_runloop) {
+    CFRunLoopWakeUp(g_monitor_runloop);
+  }
+}
+
+}  // namespace platform
+}  // namespace crossdesk

apps/desktop/src/platform/macos/daemon_backend.cpp

@@ -0,0 +1,20 @@
+#include "platform/daemon_backend.h"
+
+#include <limits.h>
+#include <mach-o/dyld.h>
+
+#include <cstdlib>
+
+namespace crossdesk::platform {
+
+bool PrepareDaemon() { return true; }
+
+std::string GetDaemonExecutablePath() {
+  char path[PATH_MAX] = {};
+  uint32_t size = sizeof(path);
+  if (_NSGetExecutablePath(path, &size) != 0) return {};
+  char resolved[PATH_MAX] = {};
+  return realpath(path, resolved) ? std::string(resolved) : std::string(path);
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/macos/gui/metal_video_renderer.h

@@ -0,0 +1,82 @@
+#ifndef CROSSDESK_GUI_PLATFORM_METAL_VIDEO_RENDERER_H_
+#define CROSSDESK_GUI_PLATFORM_METAL_VIDEO_RENDERER_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+#include "platform/video_renderer.h"
+
+namespace crossdesk {
+
+// macOS video compositor used by CrossDesk only. MiniRTC continues to expose
+// tightly packed CPU NV12 frames; this renderer performs the single required
+// copy into shared Metal buffers and converts NV12 to RGB in the fragment
+// shader. AppKit attachment and rendering are main-thread operations, while
+// SubmitNv12() is safe to call from MiniRTC's decode callback thread.
+class MacMetalVideoRenderer final : public VideoRenderer {
+ public:
+  MacMetalVideoRenderer();
+  ~MacMetalVideoRenderer() override;
+
+  MacMetalVideoRenderer(const MacMetalVideoRenderer&) = delete;
+  MacMetalVideoRenderer& operator=(const MacMetalVideoRenderer&) = delete;
+
+  bool IsReady() const override;
+  bool IsActive() const override;
+
+  // The selected stream is the only stream uploaded. Frames for background
+  // tabs are intentionally dropped to avoid wasting memory bandwidth.
+  bool SetSelectedStream(std::string remote_id) override;
+  void DiscardStream(std::string_view remote_id) override;
+
+  // Copies one tightly packed NV12 frame into a free shared Metal slot.
+  SubmitResult SubmitNv12(std::string_view remote_id, const uint8_t* data,
+                          size_t size, int width, int height) override;
+
+  // Seeds a newly selected stream from its retained CPU snapshot without
+  // replacing a newer decoded frame that is already queued or rendering.
+  SubmitResult SubmitCachedNv12(std::string_view remote_id,
+                                const uint8_t* data, size_t size, int width,
+                                int height) override;
+
+  // Attaches a native CAMetalLayer-backed sibling below Slint's NSView and
+  // restores the containing AppKit window's ordinary opaque titlebar.
+  // |slint_view| is an NSView* kept opaque so this header remains valid C++.
+  bool Attach(void* slint_view);
+  void Detach();
+  bool IsAttached() const;
+
+  // Cheap main-thread geometry check used by the UI frame timer. New decoded
+  // frames are tracked by GuiRuntime's dirty flag; this covers native resize,
+  // scale, stream selection, and retry work without a full session sync.
+  bool NeedsSurfaceRedraw() const;
+
+  // Draws the newest queued frame for |remote_id|. top_inset_points reserves
+  // Slint's tab strip above the native video surface. A rendered outcome
+  // carries metadata from the exact slot submitted to the command buffer.
+  RenderOutcome RenderLatest(std::string_view remote_id,
+                             double top_inset_points,
+                             bool native_titlebar_visible);
+
+  // Used only when a session closes, so thumbnail generation does not require
+  // a second per-frame CPU copy during normal playback.
+  bool CopyLatestNv12(std::string_view remote_id,
+                      std::vector<unsigned char>* output, int* width,
+                      int* height) const override;
+
+ private:
+  SubmitResult SubmitNv12Internal(std::string_view remote_id,
+                                  const uint8_t* data, size_t size, int width,
+                                  int height, bool replace_pending);
+
+  struct Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+}  // namespace crossdesk
+
+#endif  // CROSSDESK_GUI_PLATFORM_METAL_VIDEO_RENDERER_H_

apps/desktop/src/platform/macos/gui/runtime/cursor_state_provider_mac.mm

@@ -0,0 +1,193 @@
+#include "runtime/cursor_state_provider.h"
+
+#include <remote_action.h>
+
+#if defined(__APPLE__)
+
+#import <AppKit/AppKit.h>
+#import <CoreGraphics/CGRemoteOperation.h>
+
+#include <cstdint>
+#include <vector>
+
+#include "runtime/cursor_position.h"
+
+namespace crossdesk {
+namespace {
+
+// Quartz reports the arrow cursor's event hotspot. The visible apex in the
+// current macOS system artwork is about 1.6 logical points above that hotspot
+// (NSCursor.arrowCursor has a (5, 5) hotspot). Send this as presentation-only
+// metadata so controllers can align their glyph without changing input.
+constexpr double kDefaultArrowVisualTipYOffset = -1.6;
+
+struct CursorFingerprint {
+  uint64_t pixel_hash = 0;
+  size_t width = 0;
+  size_t height = 0;
+  size_t bytes_per_row = 0;
+  CFIndex pixel_bytes = 0;
+  NSPoint hot_spot = NSZeroPoint;
+};
+
+struct KnownCursor {
+  CursorFingerprint fingerprint;
+  RemoteCursorShape shape = RemoteCursorShape::default_cursor;
+};
+
+bool FingerprintCursor(NSCursor* cursor, CursorFingerprint* fingerprint) {
+  if (!cursor || !fingerprint || !cursor.image) return false;
+
+  NSRect proposed_rect = {NSZeroPoint, cursor.image.size};
+  CGImageRef image =
+      [cursor.image CGImageForProposedRect:&proposed_rect
+                                   context:nil
+                                     hints:nil];
+  if (!image) return false;
+
+  CGDataProviderRef provider = CGImageGetDataProvider(image);
+  if (!provider) return false;
+
+  CFDataRef data = CGDataProviderCopyData(provider);
+  if (!data) return false;
+
+  // NSCursor.currentSystemCursor returns a fresh NSCursor/NSImage wrapper on
+  // each query. Hash the decoded CGImage pixels so it can still be matched to
+  // AppKit's semantic cursor instances without encoding a large TIFF every
+  // frame.
+  constexpr uint64_t kFnvOffsetBasis = 1469598103934665603ULL;
+  constexpr uint64_t kFnvPrime = 1099511628211ULL;
+  uint64_t hash = kFnvOffsetBasis;
+  const UInt8* bytes = CFDataGetBytePtr(data);
+  const CFIndex length = CFDataGetLength(data);
+  for (CFIndex index = 0; index < length; ++index) {
+    hash ^= bytes[index];
+    hash *= kFnvPrime;
+  }
+
+  fingerprint->pixel_hash = hash;
+  fingerprint->width = CGImageGetWidth(image);
+  fingerprint->height = CGImageGetHeight(image);
+  fingerprint->bytes_per_row = CGImageGetBytesPerRow(image);
+  fingerprint->pixel_bytes = length;
+  fingerprint->hot_spot = cursor.hotSpot;
+  CFRelease(data);
+  return true;
+}
+
+bool SameCursor(const CursorFingerprint& left,
+                const CursorFingerprint& right) {
+  return left.pixel_hash == right.pixel_hash && left.width == right.width &&
+         left.height == right.height &&
+         left.bytes_per_row == right.bytes_per_row &&
+         left.pixel_bytes == right.pixel_bytes &&
+         NSEqualPoints(left.hot_spot, right.hot_spot);
+}
+
+void AddKnownCursor(std::vector<KnownCursor>* cursors, NSCursor* cursor,
+                    RemoteCursorShape shape) {
+  CursorFingerprint fingerprint;
+  if (FingerprintCursor(cursor, &fingerprint)) {
+    cursors->push_back({fingerprint, shape});
+  }
+}
+
+std::vector<KnownCursor> BuildKnownCursors() {
+  std::vector<KnownCursor> cursors;
+  cursors.reserve(16);
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+  AddKnownCursor(&cursors, NSCursor.arrowCursor,
+                 RemoteCursorShape::default_cursor);
+  AddKnownCursor(&cursors, NSCursor.pointingHandCursor,
+                 RemoteCursorShape::pointer);
+  AddKnownCursor(&cursors, NSCursor.crosshairCursor,
+                 RemoteCursorShape::crosshair);
+  AddKnownCursor(&cursors, NSCursor.IBeamCursor, RemoteCursorShape::text);
+  AddKnownCursor(&cursors, NSCursor.IBeamCursorForVerticalLayout,
+                 RemoteCursorShape::text);
+  AddKnownCursor(&cursors, NSCursor.operationNotAllowedCursor,
+                 RemoteCursorShape::not_allowed);
+  AddKnownCursor(&cursors, NSCursor.dragLinkCursor, RemoteCursorShape::alias);
+  AddKnownCursor(&cursors, NSCursor.dragCopyCursor, RemoteCursorShape::copy);
+  AddKnownCursor(&cursors, NSCursor.openHandCursor, RemoteCursorShape::grab);
+  AddKnownCursor(&cursors, NSCursor.closedHandCursor,
+                 RemoteCursorShape::grabbing);
+  AddKnownCursor(&cursors, NSCursor.resizeLeftRightCursor,
+                 RemoteCursorShape::ew_resize);
+  AddKnownCursor(&cursors, NSCursor.resizeUpDownCursor,
+                 RemoteCursorShape::ns_resize);
+  AddKnownCursor(&cursors, NSCursor.resizeUpCursor,
+                 RemoteCursorShape::n_resize);
+  AddKnownCursor(&cursors, NSCursor.resizeRightCursor,
+                 RemoteCursorShape::e_resize);
+  AddKnownCursor(&cursors, NSCursor.resizeDownCursor,
+                 RemoteCursorShape::s_resize);
+  AddKnownCursor(&cursors, NSCursor.resizeLeftCursor,
+                 RemoteCursorShape::w_resize);
+#pragma clang diagnostic pop
+
+  return cursors;
+}
+
+RemoteCursorShape ShapeFromMacCursor(NSCursor* cursor) {
+  CursorFingerprint fingerprint;
+  if (!FingerprintCursor(cursor, &fingerprint)) {
+    return RemoteCursorShape::default_cursor;
+  }
+
+  // Sampling begins from the UI tick, after AppKit has initialized its cursor
+  // catalog. Cache those fingerprints because only the current cursor needs
+  // to be decoded on subsequent frames.
+  static const std::vector<KnownCursor> known_cursors = BuildKnownCursors();
+  for (const KnownCursor& known : known_cursors) {
+    if (SameCursor(fingerprint, known.fingerprint)) return known.shape;
+  }
+  return RemoteCursorShape::default_cursor;
+}
+
+}  // namespace
+
+struct CursorStateProvider::Impl {};
+
+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;
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+  NSCursor* cursor = NSCursor.currentSystemCursor;
+  const bool visible = CGCursorIsVisible();
+#pragma clang diagnostic pop
+
+  state->seq = 0;
+  state->visible = visible && cursor != nil;
+  state->shape = state->visible ? ShapeFromMacCursor(cursor)
+                                : RemoteCursorShape::none;
+  ResetCursorPosition(state);
+  CGEventRef event = CGEventCreate(nullptr);
+  if (event) {
+    const CGPoint location = CGEventGetLocation(event);
+    NormalizeCursorPosition(location.x, location.y, displays,
+                            preferred_display, state);
+    if (state->position_valid && state->visible &&
+        state->shape == RemoteCursorShape::default_cursor &&
+        state->display_id >= 0 &&
+        state->display_id < static_cast<int>(displays.size())) {
+      const double display_height =
+          std::max(displays[state->display_id].height, 1);
+      state->visual_offset_y = static_cast<float>(
+          kDefaultArrowVisualTipYOffset / display_height);
+    }
+    CFRelease(event);
+  }
+  return true;
+}
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/macos/gui/runtime/mac_permission_runtime.mm

@@ -0,0 +1,113 @@
+#include "runtime/gui_runtime.h"
+
+#include "rd_log.h"
+
+#include <ApplicationServices/ApplicationServices.h>
+#include <CoreGraphics/CoreGraphics.h>
+#import <Foundation/Foundation.h>
+#include <cstdlib>
+#include <string>
+
+namespace crossdesk {
+
+namespace {
+constexpr uint32_t kPermissionRefreshIntervalVisibleMs = 500;
+
+void OpenPrivacyPreferences(const char *pane) {
+  if (pane == nullptr || pane[0] == '\0') {
+    return;
+  }
+
+  std::string command =
+      "open \"x-apple.systempreferences:com.apple.preference.security?";
+  command += pane;
+  command += "\"";
+  system(command.c_str());
+}
+} // namespace
+
+bool GuiRuntime::CheckScreenRecordingPermission() {
+  // CGPreflightScreenCaptureAccess is available on macOS 10.15+
+  if (@available(macOS 10.15, *)) {
+    bool granted = CGPreflightScreenCaptureAccess();
+    return granted;
+  }
+  // for older macOS versions, assume permission is granted
+  return true;
+}
+
+bool GuiRuntime::CheckAccessibilityPermission() {
+  NSDictionary *options = @{(__bridge id)kAXTrustedCheckOptionPrompt : @NO};
+  bool trusted =
+      AXIsProcessTrustedWithOptions((__bridge CFDictionaryRef)options);
+  return trusted;
+}
+
+void GuiRuntime::OpenAccessibilityPreferences() {
+  if (!mac_accessibility_permission_requested_) {
+    NSDictionary *options = @{(__bridge id)kAXTrustedCheckOptionPrompt : @YES};
+    AXIsProcessTrustedWithOptions((__bridge CFDictionaryRef)options);
+  } else {
+    OpenPrivacyPreferences("Privacy_Accessibility");
+  }
+}
+
+void GuiRuntime::OpenScreenRecordingPreferences() {
+  if (@available(macOS 10.15, *)) {
+    if (!mac_screen_recording_permission_requested_) {
+      CGRequestScreenCaptureAccess();
+    } else {
+      OpenPrivacyPreferences("Privacy_ScreenCapture");
+    }
+  } else {
+    OpenPrivacyPreferences("Privacy_ScreenCapture");
+  }
+}
+
+void GuiRuntime::RefreshMacPermissionStatus(bool force) {
+  const uint32_t now = static_cast<uint32_t>(SDL_GetTicks());
+  if (!force && mac_permission_status_initialized_ &&
+      now - mac_permission_last_check_tick_ <
+          kPermissionRefreshIntervalVisibleMs) {
+    return;
+  }
+
+  const bool old_screen_recording_granted =
+      mac_screen_recording_permission_granted_;
+  const bool old_accessibility_granted = mac_accessibility_permission_granted_;
+
+  mac_screen_recording_permission_granted_ = CheckScreenRecordingPermission();
+  mac_accessibility_permission_granted_ = CheckAccessibilityPermission();
+  mac_permission_last_check_tick_ = now;
+  mac_permission_status_initialized_ = true;
+
+  if (old_screen_recording_granted !=
+          mac_screen_recording_permission_granted_ ||
+      old_accessibility_granted != mac_accessibility_permission_granted_) {
+    LOG_INFO("macOS permission status: screen_recording={}, accessibility={}",
+             mac_screen_recording_permission_granted_,
+             mac_accessibility_permission_granted_);
+  }
+}
+
+bool GuiRuntime::EnsureMacScreenRecordingPermission() {
+  RefreshMacPermissionStatus(false);
+  if (mac_screen_recording_permission_granted_) {
+    return true;
+  }
+
+  show_request_permission_window_ = true;
+  return false;
+}
+
+bool GuiRuntime::EnsureMacAccessibilityPermission() {
+  RefreshMacPermissionStatus(false);
+  if (mac_accessibility_permission_granted_) {
+    return true;
+  }
+
+  show_request_permission_window_ = true;
+  return false;
+}
+
+} // namespace crossdesk

apps/desktop/src/platform/macos/gui/tray/mac_tray.h

@@ -0,0 +1,40 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-06-23
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _MAC_TRAY_H_
+#define _MAC_TRAY_H_
+
+#include <functional>
+#include <memory>
+#include <string>
+
+struct SDL_Window;
+
+namespace crossdesk {
+
+struct MacTrayImpl;
+
+class MacTray {
+ public:
+  MacTray(::SDL_Window* app_window, const std::string& tooltip,
+          int language_index);
+  MacTray(std::function<void()> show_window,
+          std::function<void()> hide_window,
+          std::function<void()> open_settings,
+          std::function<void()> exit_app,
+          const std::string& tooltip, int language_index);
+  ~MacTray();
+
+  void MinimizeToTray();
+  void RemoveTrayIcon();
+
+ private:
+  std::unique_ptr<MacTrayImpl> impl_;
+};
+
+}  // namespace crossdesk
+
+#endif  // _MAC_TRAY_H_

apps/desktop/src/platform/macos/gui/tray/mac_tray.mm

@@ -0,0 +1,331 @@
+#include "mac_tray.h"
+
+#if defined(__APPLE__)
+
+#include <SDL3/SDL.h>
+
+#import <Cocoa/Cocoa.h>
+
+#include "localization.h"
+
+#include <utility>
+
+@interface CrossDeskMacTrayTarget : NSObject
+- (instancetype)initWithOwner:(crossdesk::MacTrayImpl *)owner;
+- (void)statusItemClicked:(id)sender;
+- (void)showMainWindow:(id)sender;
+- (void)openSettings:(id)sender;
+- (void)exitApplication:(id)sender;
+@end
+
+namespace crossdesk {
+
+struct MacTrayImpl {
+  explicit MacTrayImpl(::SDL_Window *window, std::string tray_tooltip,
+                       int language_index_value)
+      : app_window(window),
+        tooltip(std::move(tray_tooltip)),
+        language_index(language_index_value),
+        target([[CrossDeskMacTrayTarget alloc] initWithOwner:this]) {
+    EnsureStatusItem();
+  }
+
+  explicit MacTrayImpl(std::function<void()> show_window_callback,
+                       std::function<void()> hide_window_callback,
+                       std::function<void()> open_settings_callback,
+                       std::function<void()> exit_callback,
+                       std::string tray_tooltip, int language_index_value)
+      : show_window(std::move(show_window_callback)),
+        hide_window(std::move(hide_window_callback)),
+        open_settings(std::move(open_settings_callback)),
+        exit_app(std::move(exit_callback)),
+        tooltip(std::move(tray_tooltip)),
+        language_index(language_index_value),
+        target([[CrossDeskMacTrayTarget alloc] initWithOwner:this]) {
+    EnsureStatusItem();
+  }
+
+  ~MacTrayImpl() {
+    RemoveTrayIcon();
+    target = nil;
+  }
+
+  void MinimizeToTray() {
+    EnsureStatusItem();
+    if (hide_window) {
+      hide_window();
+    } else if (app_window) {
+      SDL_HideWindow(app_window);
+    }
+  }
+
+  void RemoveTrayIcon() {
+    if (!status_item) {
+      return;
+    }
+
+    [[NSStatusBar systemStatusBar] removeStatusItem:status_item];
+    status_item = nil;
+  }
+
+  void ShowWindow() {
+    if (show_window) {
+      show_window();
+    } else if (app_window) {
+      SDL_ShowWindow(app_window);
+      SDL_RaiseWindow(app_window);
+    }
+    [NSApp activateIgnoringOtherApps:YES];
+  }
+
+  void ShowMenu() {
+    EnsureStatusItem();
+    if (!status_item) {
+      return;
+    }
+
+    NSMenu *menu = [[NSMenu alloc] initWithTitle:@"CrossDesk"];
+    [menu setAppearance:[NSAppearance appearanceNamed:NSAppearanceNameAqua]];
+
+    NSString *show_main_window_title =
+        NSStringFromUtf8(localization::show_main_window
+                             [localization::detail::ClampLanguageIndex(
+                                 language_index)]);
+    NSMenuItem *show_main_window_item =
+        [[NSMenuItem alloc] initWithTitle:show_main_window_title
+                                  action:@selector(showMainWindow:)
+                           keyEquivalent:@""];
+    [show_main_window_item setTarget:target];
+    [menu addItem:show_main_window_item];
+
+    NSString *settings_title =
+        NSStringFromUtf8(localization::settings
+                             [localization::detail::ClampLanguageIndex(
+                                 language_index)]);
+    NSMenuItem *settings_item =
+        [[NSMenuItem alloc] initWithTitle:settings_title
+                                  action:@selector(openSettings:)
+                           keyEquivalent:@""];
+    [settings_item setTarget:target];
+    [menu addItem:settings_item];
+    [menu addItem:[NSMenuItem separatorItem]];
+
+    NSString *exit_title =
+        NSStringFromUtf8(localization::exit_program
+                             [localization::detail::ClampLanguageIndex(
+                                 language_index)]);
+    NSMenuItem *exit_item = [[NSMenuItem alloc] initWithTitle:exit_title
+                                                       action:@selector(exitApplication:)
+                                                keyEquivalent:@""];
+    [exit_item setTarget:target];
+    [menu addItem:exit_item];
+
+    NSStatusBarButton *button = [status_item button];
+    if (!button) {
+      return;
+    }
+
+    const NSRect bounds = [button bounds];
+    [menu popUpMenuPositioningItem:nil
+                        atLocation:NSMakePoint(NSMinX(bounds), NSMinY(bounds))
+                            inView:button];
+  }
+
+  void RequestExit() {
+    if (exit_app) {
+      exit_app();
+      return;
+    }
+    SDL_Event event;
+    event.type = SDL_EVENT_QUIT;
+    SDL_PushEvent(&event);
+  }
+
+  void OpenSettings() {
+    if (open_settings) {
+      open_settings();
+    } else {
+      ShowWindow();
+      return;
+    }
+    [NSApp activateIgnoringOtherApps:YES];
+  }
+
+ private:
+  void EnsureStatusItem() {
+    if (status_item) {
+      return;
+    }
+
+    status_item = [[NSStatusBar systemStatusBar]
+        statusItemWithLength:NSSquareStatusItemLength];
+    NSStatusBarButton *button = [status_item button];
+    if (!button) {
+      return;
+    }
+
+    [button setToolTip:NSStringFromUtf8(tooltip)];
+
+    NSImage *crossdesk_icon = LoadCrossDeskIcon();
+    if (crossdesk_icon) {
+      NSImage *status_icon = [crossdesk_icon copy];
+      [status_icon setSize:NSMakeSize(18.0, 18.0)];
+      [status_icon setTemplate:NO];
+      [button setImage:status_icon];
+      [button setImagePosition:NSImageOnly];
+    } else {
+      [button setTitle:@"CD"];
+    }
+
+    [button setTarget:target];
+    [button setAction:@selector(statusItemClicked:)];
+    [button sendActionOn:NSEventMaskLeftMouseUp | NSEventMaskRightMouseUp];
+  }
+
+  NSString *NSStringFromUtf8(const std::string &text) {
+    return [NSString stringWithUTF8String:text.c_str()];
+  }
+
+  NSImage *LoadCrossDeskIcon() {
+    NSImage *icon = LoadIconFromBundleResource(@"crossdesk");
+    if (!icon) {
+      icon = LoadIconFromBundleResource(@"crossedesk");
+    }
+    if (!icon) {
+      icon = LoadIconFromDevelopmentPath();
+    }
+    if (!icon) {
+      icon = [NSApp applicationIconImage];
+    }
+    return icon;
+  }
+
+  NSImage *LoadIconFromBundleResource(NSString *resource_name) {
+    NSString *icon_path =
+        [[NSBundle mainBundle] pathForResource:resource_name ofType:@"icns"];
+    return LoadIconFromPath(icon_path);
+  }
+
+  NSImage *LoadIconFromDevelopmentPath() {
+    NSMutableArray<NSString *> *candidate_paths = [NSMutableArray array];
+
+    NSString *current_directory =
+        [[NSFileManager defaultManager] currentDirectoryPath];
+    [candidate_paths
+        addObject:[current_directory
+                      stringByAppendingPathComponent:
+                          @"apps/desktop/resources/macos/crossdesk.icns"]];
+
+    const char *base_path = SDL_GetBasePath();
+    if (base_path && base_path[0] != '\0') {
+      NSString *base_directory = NSStringFromUtf8(base_path);
+      [candidate_paths
+          addObject:[base_directory
+                        stringByAppendingPathComponent:
+                            @"apps/desktop/resources/macos/crossdesk.icns"]];
+      [candidate_paths
+          addObject:[base_directory
+                        stringByAppendingPathComponent:
+                            @"../../../../apps/desktop/resources/macos/"
+                             "crossdesk.icns"]];
+    }
+
+    for (NSString *candidate_path in candidate_paths) {
+      NSImage *icon = LoadIconFromPath(
+          [candidate_path stringByStandardizingPath]);
+      if (icon) {
+        return icon;
+      }
+    }
+
+    return nil;
+  }
+
+  NSImage *LoadIconFromPath(NSString *icon_path) {
+    if (![icon_path length]) {
+      return nil;
+    }
+    if (![[NSFileManager defaultManager] fileExistsAtPath:icon_path]) {
+      return nil;
+    }
+    return [[NSImage alloc] initWithContentsOfFile:icon_path];
+  }
+
+  ::SDL_Window *app_window = nullptr;
+  std::function<void()> show_window;
+  std::function<void()> hide_window;
+  std::function<void()> open_settings;
+  std::function<void()> exit_app;
+  std::string tooltip;
+  int language_index = 0;
+  NSStatusItem *status_item = nil;
+  CrossDeskMacTrayTarget *target = nil;
+};
+
+MacTray::MacTray(::SDL_Window *app_window, const std::string &tooltip,
+                 int language_index)
+    : impl_(
+          std::make_unique<MacTrayImpl>(app_window, tooltip, language_index)) {}
+
+MacTray::MacTray(std::function<void()> show_window,
+                 std::function<void()> hide_window,
+                 std::function<void()> open_settings,
+                 std::function<void()> exit_app, const std::string &tooltip,
+                 int language_index)
+    : impl_(std::make_unique<MacTrayImpl>(
+          std::move(show_window), std::move(hide_window),
+          std::move(open_settings), std::move(exit_app), tooltip,
+          language_index)) {}
+
+MacTray::~MacTray() = default;
+
+void MacTray::MinimizeToTray() { impl_->MinimizeToTray(); }
+
+void MacTray::RemoveTrayIcon() { impl_->RemoveTrayIcon(); }
+
+}  // namespace crossdesk
+
+@implementation CrossDeskMacTrayTarget {
+  crossdesk::MacTrayImpl *owner_;
+}
+
+- (instancetype)initWithOwner:(crossdesk::MacTrayImpl *)owner {
+  self = [super init];
+  if (self) {
+    owner_ = owner;
+  }
+  return self;
+}
+
+- (void)statusItemClicked:(id)sender {
+  (void)sender;
+  if (!owner_) {
+    return;
+  }
+  owner_->ShowMenu();
+}
+
+- (void)exitApplication:(id)sender {
+  (void)sender;
+  if (owner_) {
+    owner_->RequestExit();
+  }
+}
+
+- (void)showMainWindow:(id)sender {
+  (void)sender;
+  if (owner_) {
+    owner_->ShowWindow();
+  }
+}
+
+- (void)openSettings:(id)sender {
+  (void)sender;
+  if (owner_) {
+    owner_->OpenSettings();
+  }
+}
+
+@end
+
+#endif  // __APPLE__

apps/desktop/src/platform/macos/gui/video_renderer_factory_metal.mm

@@ -0,0 +1,13 @@
+#include "platform/video_renderer.h"
+
+#include <memory>
+
+#include "platform/macos/gui/metal_video_renderer.h"
+
+namespace crossdesk {
+
+std::unique_ptr<VideoRenderer> CreateVideoRenderer() {
+  return std::make_unique<MacMetalVideoRenderer>();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/macos/gui/views/request_permission_window.mm

@@ -0,0 +1,187 @@
+#include "application/gui_application.h"
+#include "layout.h"
+#include "localization.h"
+
+namespace crossdesk {
+
+bool GuiApplication::DrawToggleSwitch(const char *id, bool active,
+                                      bool enabled) {
+  const float TRACK_HEIGHT = ImGui::GetFrameHeight();
+  const float TRACK_WIDTH = TRACK_HEIGHT * 1.8f;
+  const float TRACK_RADIUS = TRACK_HEIGHT * 0.5f;
+  const float KNOB_PADDING = 2.0f;
+  const float KNOB_HEIGHT = TRACK_HEIGHT - 4.0f;
+  const float KNOB_WIDTH = KNOB_HEIGHT * 1.2f;
+  const float KNOB_RADIUS = KNOB_HEIGHT * 0.5f;
+  const float DISABLED_ALPHA = 0.6f;
+  const float KNOB_ALPHA_DISABLED = 0.9f;
+
+  const ImVec4 COLOR_ACTIVE = ImVec4(0.0f, 0.0f, 1.0f, 1.0f);
+  const ImVec4 COLOR_ACTIVE_HOVER = ImVec4(0.26f, 0.59f, 0.98f, 1.0f);
+  const ImVec4 COLOR_INACTIVE = ImVec4(0.60f, 0.60f, 0.60f, 1.0f);
+  const ImVec4 COLOR_INACTIVE_HOVER = ImVec4(0.70f, 0.70f, 0.70f, 1.0f);
+  const ImVec4 COLOR_KNOB = ImVec4(1.0f, 1.0f, 1.0f, 1.0f);
+
+  ImDrawList *draw_list = ImGui::GetWindowDrawList();
+  ImVec2 track_pos = ImGui::GetCursorScreenPos();
+
+  ImGui::InvisibleButton(id, ImVec2(TRACK_WIDTH, TRACK_HEIGHT));
+  bool hovered = ImGui::IsItemHovered();
+  bool clicked = ImGui::IsItemClicked() && enabled;
+
+  ImVec4 track_color =
+      active ? (hovered && enabled ? COLOR_ACTIVE_HOVER : COLOR_ACTIVE)
+             : (hovered && enabled ? COLOR_INACTIVE_HOVER : COLOR_INACTIVE);
+
+  if (!enabled) {
+    track_color.w *= DISABLED_ALPHA;
+  }
+
+  ImVec2 track_min = ImVec2(track_pos.x, track_pos.y + 0.5f);
+  ImVec2 track_max =
+      ImVec2(track_pos.x + TRACK_WIDTH, track_pos.y + TRACK_HEIGHT - 0.5f);
+  draw_list->AddRectFilled(track_min, track_max,
+                           ImGui::GetColorU32(track_color), TRACK_RADIUS);
+
+  float knob_position = active ? 1.0f : 0.0f;
+  float knob_min_x = track_pos.x + KNOB_PADDING;
+  float knob_max_x = track_pos.x + TRACK_WIDTH - KNOB_WIDTH - KNOB_PADDING;
+  float knob_x = knob_min_x + knob_position * (knob_max_x - knob_min_x);
+  float knob_y = track_pos.y + (TRACK_HEIGHT - KNOB_HEIGHT) * 0.5f;
+
+  ImVec4 knob_color = COLOR_KNOB;
+  if (!enabled) {
+    knob_color.w = KNOB_ALPHA_DISABLED;
+  }
+
+  ImVec2 knob_min = ImVec2(knob_x, knob_y);
+  ImVec2 knob_max = ImVec2(knob_x + KNOB_WIDTH, knob_y + KNOB_HEIGHT);
+  draw_list->AddRectFilled(knob_min, knob_max, ImGui::GetColorU32(knob_color),
+                           KNOB_RADIUS);
+
+  return clicked;
+}
+
+int GuiApplication::RequestPermissionWindow() {
+  RefreshMacPermissionStatus(false);
+
+  const bool screen_recording_granted =
+      mac_screen_recording_permission_granted_;
+  const bool accessibility_granted = mac_accessibility_permission_granted_;
+
+  show_request_permission_window_ =
+      !screen_recording_granted || !accessibility_granted;
+
+  if (!show_request_permission_window_) {
+    return 0;
+  }
+
+  const ImGuiViewport *viewport = ImGui::GetMainViewport();
+  float window_width = localization_language_index_ == 0
+                           ? REQUEST_PERMISSION_WINDOW_WIDTH_CN
+                           : REQUEST_PERMISSION_WINDOW_WIDTH_EN;
+  float window_height = localization_language_index_ == 0
+                            ? REQUEST_PERMISSION_WINDOW_HEIGHT_CN
+                            : REQUEST_PERMISSION_WINDOW_HEIGHT_EN;
+
+  float checkbox_padding = localization_language_index_ == 0
+                               ? REQUEST_PERMISSION_WINDOW_CHECKBOX_PADDING_CN
+                               : REQUEST_PERMISSION_WINDOW_CHECKBOX_PADDING_EN;
+
+  ImVec2 center_pos = ImVec2(
+      (viewport->WorkSize.x - window_width) * 0.5f + viewport->WorkPos.x,
+      (viewport->WorkSize.y - window_height) * 0.5f + viewport->WorkPos.y);
+  ImGui::SetNextWindowPos(center_pos, ImGuiCond_Once);
+
+  ImGui::SetNextWindowSize(ImVec2(window_width, window_height),
+                           ImGuiCond_Always);
+
+  ImGui::PushStyleColor(ImGuiCol_WindowBg, ImVec4(1.0f, 1.0f, 1.0f, 1.0f));
+  ImGui::PushStyleVar(ImGuiStyleVar_WindowBorderSize, 1.0f);
+  ImGui::PushStyleVar(ImGuiStyleVar_WindowRounding, window_rounding_);
+  ImGui::PushStyleVar(ImGuiStyleVar_FrameRounding, window_rounding_ * 0.5f);
+  ImGui::PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(0.0f, 0.0f));
+
+  ImGui::Begin(
+      localization::request_permissions[localization_language_index_].c_str(),
+      nullptr,
+      ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse |
+          ImGuiWindowFlags_NoSavedSettings);
+
+  ImGui::SetWindowFontScale(0.3f);
+
+  // use system font
+  if (main_windows_system_chinese_font_ != nullptr) {
+    ImGui::PushFont(main_windows_system_chinese_font_);
+  }
+
+  ImGui::SetCursorPosY(ImGui::GetCursorPosY() + ImGui::GetTextLineHeight() +
+                       5.0f);
+  ImGui::SetCursorPosX(10.0f);
+  ImGui::TextWrapped(
+      "%s",
+      localization::permission_required_message[localization_language_index_]
+          .c_str());
+
+  ImGui::Spacing();
+  ImGui::Spacing();
+  ImGui::Spacing();
+
+  // accessibility permission
+  ImGui::SetCursorPosX(10.0f);
+  ImGui::AlignTextToFramePadding();
+  ImGui::Text(
+      "1. %s:",
+      localization::accessibility_permission[localization_language_index_]
+          .c_str());
+  ImGui::SameLine();
+  ImGui::AlignTextToFramePadding();
+  ImGui::SetCursorPosX(checkbox_padding);
+  if (accessibility_granted) {
+    DrawToggleSwitch("accessibility_toggle_on", true, false);
+  } else {
+    if (DrawToggleSwitch("accessibility_toggle", false, true)) {
+      OpenAccessibilityPreferences();
+      mac_accessibility_permission_requested_ = true;
+      RefreshMacPermissionStatus(true);
+    }
+  }
+
+  ImGui::Spacing();
+
+  // screen recording permission
+  ImGui::SetCursorPosX(10.0f);
+  ImGui::AlignTextToFramePadding();
+  ImGui::Text(
+      "2. %s:",
+      localization::screen_recording_permission[localization_language_index_]
+          .c_str());
+  ImGui::SameLine();
+  ImGui::AlignTextToFramePadding();
+  ImGui::SetCursorPosX(checkbox_padding);
+  if (screen_recording_granted) {
+    DrawToggleSwitch("screen_recording_toggle_on", true, false);
+  } else {
+    if (DrawToggleSwitch("screen_recording_toggle", false, true)) {
+      OpenScreenRecordingPreferences();
+      mac_screen_recording_permission_requested_ = true;
+      RefreshMacPermissionStatus(true);
+    }
+  }
+
+  ImGui::SetWindowFontScale(1.0f);
+  ImGui::SetWindowFontScale(0.45f);
+
+  // pop system font
+  if (main_windows_system_chinese_font_ != nullptr) {
+    ImGui::PopFont();
+  }
+
+  ImGui::End();
+  ImGui::SetWindowFontScale(1.0f);
+  ImGui::PopStyleVar(4);
+  ImGui::PopStyleColor();
+
+  return 0;
+}
+} // namespace crossdesk

apps/desktop/src/platform/macos/gui/window_drag_mac.mm

@@ -0,0 +1,288 @@
+#include "platform/window_drag.h"
+
+#import <AppKit/AppKit.h>
+
+@interface CrossDeskStreamFullscreenTarget : NSObject
+- (void)toggleStreamFullscreen:(id)sender;
+@end
+
+@implementation CrossDeskStreamFullscreenTarget
+- (void)toggleStreamFullscreen:(id)sender {
+  (void)sender;
+  crossdesk::SetStreamWindowFullscreen(
+      !crossdesk::IsStreamWindowFullscreen());
+}
+@end
+
+namespace crossdesk {
+namespace {
+
+__weak NSWindow *stream_window = nil;
+__weak NSView *stream_slint_view = nil;
+CrossDeskStreamFullscreenTarget *stream_fullscreen_target = nil;
+bool stream_fullscreen = false;
+NSRect stream_restore_frame = NSZeroRect;
+NSWindowStyleMask stream_restore_style_mask = NSWindowStyleMaskTitled;
+NSWindowTitleVisibility stream_restore_title_visibility =
+    NSWindowTitleVisible;
+BOOL stream_restore_titlebar_transparent = NO;
+BOOL stream_restore_movable = YES;
+BOOL stream_restore_close_hidden = NO;
+BOOL stream_restore_miniaturize_hidden = NO;
+BOOL stream_restore_zoom_hidden = NO;
+NSApplicationPresentationOptions stream_restore_presentation_options =
+    NSApplicationPresentationDefault;
+
+void InstallStreamFullscreenButton(NSWindow *window) {
+  if (window == nil) {
+    return;
+  }
+  if (stream_fullscreen_target == nil) {
+    stream_fullscreen_target =
+        [[CrossDeskStreamFullscreenTarget alloc] init];
+  }
+  NSButton *zoom_button =
+      [window standardWindowButton:NSWindowZoomButton];
+  zoom_button.target = stream_fullscreen_target;
+  zoom_button.action = @selector(toggleStreamFullscreen:);
+}
+
+void SetTitlebarButtonsHidden(NSWindow *window, BOOL hidden) {
+  [window standardWindowButton:NSWindowCloseButton].hidden = hidden;
+  [window standardWindowButton:NSWindowMiniaturizeButton].hidden = hidden;
+  [window standardWindowButton:NSWindowZoomButton].hidden = hidden;
+}
+
+void CenterWindowOnScreen(NSWindow *window, NSScreen *screen) {
+  if (window == nil || screen == nil) {
+    return;
+  }
+  const NSRect available_frame = screen.visibleFrame;
+  const NSRect window_frame = window.frame;
+  const NSPoint centered_origin = NSMakePoint(
+      NSMidX(available_frame) - NSWidth(window_frame) * 0.5,
+      NSMidY(available_frame) - NSHeight(window_frame) * 0.5);
+  [window setFrameOrigin:centered_origin];
+}
+
+} // namespace
+
+bool StartNativeWindowDrag() {
+  @autoreleasepool {
+    NSEvent *event = [[NSApplication sharedApplication] currentEvent];
+    if (event == nil || event.type != NSEventTypeLeftMouseDown ||
+        event.window == nil) {
+      return false;
+    }
+
+    [event.window performWindowDragWithEvent:event];
+    return true;
+  }
+}
+
+bool HideDisabledMainWindowZoomButton() {
+  @autoreleasepool {
+    for (NSWindow *window in [NSApp windows]) {
+      if (![window.title isEqualToString:@"CrossDesk"]) {
+        continue;
+      }
+
+      NSButton *zoom_button =
+          [window standardWindowButton:NSWindowZoomButton];
+      // The main window has a fixed size, so AppKit disables its zoom button.
+      // Stream windows remain resizable and must keep their native button.
+      if (zoom_button == nil || zoom_button.enabled) {
+        continue;
+      }
+
+      zoom_button.hidden = YES;
+      return true;
+    }
+    return false;
+  }
+}
+
+bool ConfigureStreamWindowLiveResize(void *opaque_slint_view) {
+  @autoreleasepool {
+    NSView *slint_view = (__bridge NSView *)opaque_slint_view;
+    NSWindow *window = slint_view.window;
+    if (window == nil) {
+      return false;
+    }
+
+    NSButton *zoom_button =
+        [window standardWindowButton:NSWindowZoomButton];
+    NSView *content_view = window.contentView;
+    if (zoom_button == nil || !zoom_button.enabled || content_view == nil) {
+      return false;
+    }
+
+    // During an ordinary edge resize, scale one cached frame and redraw once
+    // the new window size has settled.
+    window.preservesContentDuringLiveResize = YES;
+    content_view.layerContentsRedrawPolicy =
+        NSViewLayerContentsRedrawBeforeViewResize;
+    content_view.layerContentsPlacement =
+        NSViewLayerContentsPlacementScaleProportionallyToFit;
+    stream_window = window;
+    stream_slint_view = slint_view;
+    // Native Space fullscreen cross-fades an AppKit source snapshot over a
+    // separately rendered destination window. Disable that path for the
+    // stream window and route the green button to the immediate transition.
+    window.collectionBehavior =
+        (window.collectionBehavior &
+         ~(NSWindowCollectionBehaviorFullScreenPrimary |
+           NSWindowCollectionBehaviorFullScreenAuxiliary |
+           NSWindowCollectionBehaviorFullScreenAllowsTiling)) |
+        NSWindowCollectionBehaviorFullScreenNone;
+    InstallStreamFullscreenButton(window);
+    content_view.needsDisplay = YES;
+    return true;
+  }
+}
+
+void UnregisterStreamWindow(void *opaque_slint_view) {
+  @autoreleasepool {
+    NSView *slint_view = (__bridge NSView *)opaque_slint_view;
+    if (slint_view == nil || slint_view != stream_slint_view) {
+      return;
+    }
+    stream_window = nil;
+    stream_slint_view = nil;
+    stream_fullscreen = false;
+    stream_restore_frame = NSZeroRect;
+    stream_restore_style_mask = NSWindowStyleMaskTitled;
+    stream_restore_title_visibility = NSWindowTitleVisible;
+    stream_restore_titlebar_transparent = NO;
+    stream_restore_movable = YES;
+    stream_restore_close_hidden = NO;
+    stream_restore_miniaturize_hidden = NO;
+    stream_restore_zoom_hidden = NO;
+    stream_restore_presentation_options = NSApplicationPresentationDefault;
+  }
+}
+
+bool IsStreamWindowActive() {
+  @autoreleasepool {
+    return stream_window != nil && [NSApp isActive] &&
+           [stream_window isKeyWindow];
+  }
+}
+
+bool SetStreamWindowFullscreen(bool fullscreen) {
+  @autoreleasepool {
+    if (stream_window == nil || stream_fullscreen == fullscreen) {
+      return stream_window != nil;
+    }
+
+    if (fullscreen) {
+      NSScreen *screen = stream_window.screen ?: NSScreen.mainScreen;
+      if (screen == nil) {
+        return false;
+      }
+
+      stream_restore_frame = stream_window.frame;
+      stream_restore_style_mask = stream_window.styleMask;
+      stream_restore_title_visibility = stream_window.titleVisibility;
+      stream_restore_titlebar_transparent =
+          stream_window.titlebarAppearsTransparent;
+      stream_restore_movable = stream_window.movable;
+      stream_restore_close_hidden =
+          [stream_window standardWindowButton:NSWindowCloseButton].hidden;
+      stream_restore_miniaturize_hidden =
+          [stream_window standardWindowButton:NSWindowMiniaturizeButton].hidden;
+      stream_restore_zoom_hidden =
+          [stream_window standardWindowButton:NSWindowZoomButton].hidden;
+      stream_restore_presentation_options = NSApp.presentationOptions;
+
+      stream_fullscreen = true;
+      stream_window.styleMask =
+          stream_restore_style_mask | NSWindowStyleMaskFullSizeContentView;
+      stream_window.titleVisibility = NSWindowTitleHidden;
+      stream_window.titlebarAppearsTransparent = YES;
+      stream_window.movable = NO;
+      SetTitlebarButtonsHidden(stream_window, YES);
+
+      NSApplicationPresentationOptions presentation_options =
+          stream_restore_presentation_options;
+      if ((presentation_options & (NSApplicationPresentationHideDock |
+                                   NSApplicationPresentationAutoHideDock)) ==
+          0) {
+        presentation_options |= NSApplicationPresentationAutoHideDock;
+      }
+      if ((presentation_options & (NSApplicationPresentationHideMenuBar |
+                                   NSApplicationPresentationAutoHideMenuBar)) ==
+          0) {
+        presentation_options |= NSApplicationPresentationAutoHideMenuBar;
+      }
+      NSApp.presentationOptions = presentation_options;
+      [stream_window setFrame:screen.frame display:YES animate:NO];
+      [stream_window makeKeyAndOrderFront:nil];
+    } else {
+      stream_fullscreen = false;
+      NSApp.presentationOptions = stream_restore_presentation_options;
+      stream_window.styleMask = stream_restore_style_mask;
+      stream_window.titleVisibility = stream_restore_title_visibility;
+      stream_window.titlebarAppearsTransparent =
+          stream_restore_titlebar_transparent;
+      stream_window.movable = stream_restore_movable;
+      [stream_window setFrame:stream_restore_frame display:YES animate:NO];
+      [stream_window standardWindowButton:NSWindowCloseButton].hidden =
+          stream_restore_close_hidden;
+      [stream_window standardWindowButton:NSWindowMiniaturizeButton].hidden =
+          stream_restore_miniaturize_hidden;
+      [stream_window standardWindowButton:NSWindowZoomButton].hidden =
+          stream_restore_zoom_hidden;
+      InstallStreamFullscreenButton(stream_window);
+      [stream_window makeKeyAndOrderFront:nil];
+    }
+
+    stream_window.contentView.alphaValue = 1.0;
+    stream_window.contentView.needsDisplay = YES;
+    [stream_window displayIfNeeded];
+    return true;
+  }
+}
+
+bool IsStreamWindowFullscreen() {
+  return stream_fullscreen;
+}
+
+std::string OpenNativeFileDialog(const std::string &title) {
+  @autoreleasepool {
+    NSOpenPanel *panel = [NSOpenPanel openPanel];
+    panel.canChooseFiles = YES;
+    panel.canChooseDirectories = NO;
+    panel.allowsMultipleSelection = NO;
+    panel.resolvesAliases = YES;
+
+    NSString *prompt =
+        [[NSString alloc] initWithBytes:title.data()
+                                 length:title.size()
+                               encoding:NSUTF8StringEncoding];
+    if (prompt != nil && prompt.length > 0) {
+      panel.title = prompt;
+      panel.message = prompt;
+    }
+
+    // tinyfiledialogs uses an external osascript process on macOS, so its
+    // chooser can appear without becoming the active window. Keep the picker
+    // inside CrossDesk and explicitly activate both the app and panel.
+    [NSApp activateIgnoringOtherApps:YES];
+    NSWindow *owner = stream_window ?: NSApp.keyWindow ?: NSApp.mainWindow;
+    if (owner != nil) {
+      [owner makeKeyAndOrderFront:nil];
+    }
+    NSScreen *target_screen = owner.screen ?: NSScreen.mainScreen;
+    CenterWindowOnScreen(panel, target_screen);
+    [panel makeKeyAndOrderFront:nil];
+
+    if ([panel runModal] != NSModalResponseOK || panel.URL == nil) {
+      return {};
+    }
+    const char *path = panel.URL.fileSystemRepresentation;
+    return path != nullptr ? std::string(path) : std::string{};
+  }
+}
+
+} // namespace crossdesk

apps/desktop/src/platform/macos/gui/window_util_mac.h

@@ -0,0 +1,25 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-01-20
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _WINDOW_UTIL_MAC_H_
+#define _WINDOW_UTIL_MAC_H_
+
+struct SDL_Window;
+
+namespace crossdesk {
+
+// Best-effort: keep an SDL window above normal windows on macOS.
+// No-op on non-macOS builds.
+void MacSetWindowAlwaysOnTop(::SDL_Window* window, bool always_on_top);
+
+// Best-effort: exclude an SDL window from the Window menu and window cycling.
+// Note: Cmd-Tab switches apps (not individual windows), so this primarily
+// affects the Window menu and Cmd-` window cycling.
+void MacSetWindowExcludedFromWindowMenu(::SDL_Window* window, bool excluded);
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/macos/gui/window_util_mac.mm

@@ -0,0 +1,64 @@
+#include "window_util_mac.h"
+
+#if defined(__APPLE__)
+
+#include <SDL3/SDL.h>
+
+#import <Cocoa/Cocoa.h>
+
+namespace crossdesk {
+
+static NSWindow* GetNSWindowFromSDL(::SDL_Window* window) {
+  if (!window) {
+    return nil;
+  }
+
+#if !defined(SDL_PROP_WINDOW_COCOA_WINDOW_POINTER)
+  return nil;
+#else
+  SDL_PropertiesID props = SDL_GetWindowProperties(window);
+  void* cocoa_window_ptr =
+      SDL_GetPointerProperty(props, SDL_PROP_WINDOW_COCOA_WINDOW_POINTER, NULL);
+  if (!cocoa_window_ptr) {
+    return nil;
+  }
+  return (__bridge NSWindow*)cocoa_window_ptr;
+#endif
+}
+
+void MacSetWindowAlwaysOnTop(::SDL_Window* window, bool always_on_top) {
+  NSWindow* ns_window = GetNSWindowFromSDL(window);
+  if (!ns_window) {
+    (void)always_on_top;
+    return;
+  }
+
+  // Keep above normal windows.
+  const NSInteger level = always_on_top ? NSFloatingWindowLevel : NSNormalWindowLevel;
+  [ns_window setLevel:level];
+
+  // Optional: keep visible across Spaces/fullscreen. Safe as best-effort.
+  NSWindowCollectionBehavior behavior = [ns_window collectionBehavior];
+  behavior |= NSWindowCollectionBehaviorCanJoinAllSpaces;
+  behavior |= NSWindowCollectionBehaviorFullScreenAuxiliary;
+  [ns_window setCollectionBehavior:behavior];
+}
+
+void MacSetWindowExcludedFromWindowMenu(::SDL_Window* window, bool excluded) {
+  NSWindow* ns_window = GetNSWindowFromSDL(window);
+  if (!ns_window) {
+    (void)excluded;
+    return;
+  }
+
+  [ns_window setExcludedFromWindowsMenu:excluded];
+
+  NSWindowCollectionBehavior behavior = [ns_window collectionBehavior];
+  behavior |= NSWindowCollectionBehaviorIgnoresCycle;
+  behavior |= NSWindowCollectionBehaviorTransient;
+  [ns_window setCollectionBehavior:behavior];
+}
+
+}  // namespace crossdesk
+
+#endif  // __APPLE__

apps/desktop/src/platform/macos/input/device_controller_factory.cpp

@@ -0,0 +1,19 @@
+#include "device_controller_factory.h"
+
+#include "keyboard_capturer.h"
+#include "mouse_controller.h"
+
+namespace crossdesk {
+
+DeviceController* DeviceControllerFactory::Create(Device device) {
+  switch (device) {
+    case Mouse:
+      return new PlatformMouseController();
+    case Keyboard:
+      return new PlatformKeyboardCapturer();
+    default:
+      return nullptr;
+  }
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/macos/input/keyboard/keyboard_capturer.cpp

@@ -0,0 +1,334 @@
+#include "keyboard_capturer.h"
+
+#include <cstdint>
+#include <unordered_map>
+
+#include "keyboard_converter.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+static OnKeyAction g_on_key_action = nullptr;
+static void* g_user_ptr = nullptr;
+static std::unordered_map<int, int> g_unmapped_keycode_to_vk;
+constexpr int64_t kCrossDeskInjectedKeyboardEvent = 0x43524f5353444553;
+
+static int VkCodeFromUnicode(UniChar ch) {
+  if (ch >= 'a' && ch <= 'z') {
+    return static_cast<int>(ch - 'a' + 'A');
+  }
+  if (ch >= 'A' && ch <= 'Z') {
+    return static_cast<int>(ch);
+  }
+  if (ch >= '0' && ch <= '9') {
+    return static_cast<int>(ch);
+  }
+
+  switch (ch) {
+    case ' ':
+      return 0x20;  // VK_SPACE
+    case '-':
+    case '_':
+      return 0xBD;  // VK_OEM_MINUS
+    case '=':
+    case '+':
+      return 0xBB;  // VK_OEM_PLUS
+    case '[':
+    case '{':
+      return 0xDB;  // VK_OEM_4
+    case ']':
+    case '}':
+      return 0xDD;  // VK_OEM_6
+    case '\\':
+    case '|':
+      return 0xDC;  // VK_OEM_5
+    case ';':
+    case ':':
+      return 0xBA;  // VK_OEM_1
+    case '\'':
+    case '"':
+      return 0xDE;  // VK_OEM_7
+    case ',':
+    case '<':
+      return 0xBC;  // VK_OEM_COMMA
+    case '.':
+    case '>':
+      return 0xBE;  // VK_OEM_PERIOD
+    case '/':
+    case '?':
+      return 0xBF;  // VK_OEM_2
+    case '`':
+    case '~':
+      return 0xC0;  // VK_OEM_3
+    default:
+      return -1;
+  }
+}
+
+static int ResolveVkCodeFromMacEvent(CGEventRef event, CGKeyCode key_code,
+                                     bool is_key_down) {
+  auto key_it = CGKeyCodeToVkCode.find(key_code);
+  if (key_it != CGKeyCodeToVkCode.end()) {
+    if (is_key_down) {
+      g_unmapped_keycode_to_vk.erase(static_cast<int>(key_code));
+    }
+    return key_it->second;
+  }
+
+  int vk_code = -1;
+  UniChar chars[4] = {0};
+  UniCharCount char_count = 0;
+  CGEventKeyboardGetUnicodeString(event, 4, &char_count, chars);
+  if (char_count > 0) {
+    vk_code = VkCodeFromUnicode(chars[0]);
+  }
+
+  if (vk_code < 0) {
+    auto fallback_it =
+        g_unmapped_keycode_to_vk.find(static_cast<int>(key_code));
+    if (fallback_it != g_unmapped_keycode_to_vk.end()) {
+      vk_code = fallback_it->second;
+    }
+  }
+
+  if (vk_code >= 0) {
+    if (is_key_down) {
+      g_unmapped_keycode_to_vk[static_cast<int>(key_code)] = vk_code;
+    } else {
+      g_unmapped_keycode_to_vk.erase(static_cast<int>(key_code));
+    }
+  }
+
+  return vk_code;
+}
+
+CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type,
+                         CGEventRef event, void* userInfo) {
+  (void)proxy;
+  if (CGEventGetIntegerValueField(event, kCGEventSourceUserData) ==
+      kCrossDeskInjectedKeyboardEvent) {
+    return event;
+  }
+  if (!g_on_key_action) {
+    return event;
+  }
+
+  PlatformKeyboardCapturer* keyboard_capturer = (PlatformKeyboardCapturer*)userInfo;
+  if (!keyboard_capturer) {
+    LOG_ERROR("keyboard_capturer is nullptr");
+    return event;
+  }
+
+  if (type == kCGEventKeyDown || type == kCGEventKeyUp) {
+    const bool is_key_down = (type == kCGEventKeyDown);
+    CGKeyCode key_code = static_cast<CGKeyCode>(
+        CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode));
+    int vk_code = ResolveVkCodeFromMacEvent(event, key_code, is_key_down);
+    if (vk_code >= 0) {
+      g_on_key_action(vk_code, is_key_down, 0, false, g_user_ptr);
+    }
+  } else if (type == kCGEventFlagsChanged) {
+    CGEventFlags current_flags = CGEventGetFlags(event);
+    CGKeyCode key_code = static_cast<CGKeyCode>(
+        CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode));
+    auto key_it = CGKeyCodeToVkCode.find(key_code);
+    if (key_it == CGKeyCodeToVkCode.end()) {
+      return nullptr;
+    }
+    const int vk_code = key_it->second;
+
+    // caps lock
+    bool caps_lock_state = (current_flags & kCGEventFlagMaskAlphaShift) != 0;
+    if (caps_lock_state != keyboard_capturer->caps_lock_flag_) {
+      keyboard_capturer->caps_lock_flag_ = caps_lock_state;
+      g_on_key_action(vk_code, keyboard_capturer->caps_lock_flag_, 0, false,
+                      g_user_ptr);
+    }
+
+    // shift
+    bool shift_state = (current_flags & kCGEventFlagMaskShift) != 0;
+    if (shift_state != keyboard_capturer->shift_flag_) {
+      keyboard_capturer->shift_flag_ = shift_state;
+      g_on_key_action(vk_code, keyboard_capturer->shift_flag_, 0, false,
+                      g_user_ptr);
+    }
+
+    // control
+    bool control_state = (current_flags & kCGEventFlagMaskControl) != 0;
+    if (control_state != keyboard_capturer->control_flag_) {
+      keyboard_capturer->control_flag_ = control_state;
+      g_on_key_action(vk_code, keyboard_capturer->control_flag_, 0, false,
+                      g_user_ptr);
+    }
+
+    // option
+    bool option_state = (current_flags & kCGEventFlagMaskAlternate) != 0;
+    if (option_state != keyboard_capturer->option_flag_) {
+      keyboard_capturer->option_flag_ = option_state;
+      g_on_key_action(vk_code, keyboard_capturer->option_flag_, 0, false,
+                      g_user_ptr);
+    }
+
+    // command
+    bool command_state = (current_flags & kCGEventFlagMaskCommand) != 0;
+    if (command_state != keyboard_capturer->command_flag_) {
+      keyboard_capturer->command_flag_ = command_state;
+      g_on_key_action(vk_code, keyboard_capturer->command_flag_, 0, false,
+                      g_user_ptr);
+    }
+  }
+
+  return nullptr;
+}
+
+PlatformKeyboardCapturer::PlatformKeyboardCapturer()
+    : event_tap_(nullptr), run_loop_source_(nullptr) {}
+
+PlatformKeyboardCapturer::~PlatformKeyboardCapturer() { Unhook(); }
+
+int PlatformKeyboardCapturer::Hook(OnKeyAction on_key_action, void* user_ptr) {
+  if (event_tap_) {
+    return 0;
+  }
+
+  g_unmapped_keycode_to_vk.clear();
+  g_on_key_action = on_key_action;
+  g_user_ptr = user_ptr;
+
+  CGEventMask eventMask = (1 << kCGEventKeyDown) | (1 << kCGEventKeyUp) |
+                          (1 << kCGEventFlagsChanged);
+
+  event_tap_ = CGEventTapCreate(kCGSessionEventTap, kCGHeadInsertEventTap,
+                                kCGEventTapOptionDefault, eventMask,
+                                eventCallback, this);
+
+  if (!event_tap_) {
+    LOG_ERROR("CGEventTapCreate failed");
+    return -1;
+  }
+
+  run_loop_source_ =
+      CFMachPortCreateRunLoopSource(kCFAllocatorDefault, event_tap_, 0);
+  if (!run_loop_source_) {
+    LOG_ERROR("CFMachPortCreateRunLoopSource failed");
+    CFRelease(event_tap_);
+    event_tap_ = nullptr;
+    return -1;
+  }
+
+  CFRunLoopAddSource(CFRunLoopGetCurrent(), run_loop_source_,
+                     kCFRunLoopCommonModes);
+
+  const CGEventFlags current_flags =
+      CGEventSourceFlagsState(kCGEventSourceStateCombinedSessionState);
+  caps_lock_flag_ = (current_flags & kCGEventFlagMaskAlphaShift) != 0;
+  shift_flag_ = (current_flags & kCGEventFlagMaskShift) != 0;
+  control_flag_ = (current_flags & kCGEventFlagMaskControl) != 0;
+  option_flag_ = (current_flags & kCGEventFlagMaskAlternate) != 0;
+  command_flag_ = (current_flags & kCGEventFlagMaskCommand) != 0;
+
+  CGEventTapEnable(event_tap_, true);
+  return 0;
+}
+
+int PlatformKeyboardCapturer::Unhook() {
+  g_unmapped_keycode_to_vk.clear();
+  g_on_key_action = nullptr;
+  g_user_ptr = nullptr;
+
+  if (event_tap_) {
+    CGEventTapEnable(event_tap_, false);
+  }
+
+  if (run_loop_source_) {
+    CFRunLoopRemoveSource(CFRunLoopGetCurrent(), run_loop_source_,
+                          kCFRunLoopCommonModes);
+    CFRelease(run_loop_source_);
+    run_loop_source_ = nullptr;
+  }
+
+  if (event_tap_) {
+    CFRelease(event_tap_);
+    event_tap_ = nullptr;
+  }
+
+  return 0;
+}
+
+inline bool IsFunctionKey(int key_code) {
+  switch (key_code) {
+    case 0x7A:
+    case 0x78:
+    case 0x63:
+    case 0x76:
+    case 0x60:
+    case 0x61:
+    case 0x62:
+    case 0x64:
+    case 0x65:
+    case 0x6D:
+    case 0x67:
+    case 0x6F:
+      return true;
+    default:
+      return false;
+  }
+}
+
+CGEventFlags ToCGEventFlags(uint32_t injected_flags) {
+  CGEventFlags flags = 0;
+  if ((injected_flags & kMacInjectedModifierShift) != 0) {
+    flags |= kCGEventFlagMaskShift;
+  }
+  if ((injected_flags & kMacInjectedModifierControl) != 0) {
+    flags |= kCGEventFlagMaskControl;
+  }
+  if ((injected_flags & kMacInjectedModifierOption) != 0) {
+    flags |= kCGEventFlagMaskAlternate;
+  }
+  if ((injected_flags & kMacInjectedModifierCommand) != 0) {
+    flags |= kCGEventFlagMaskCommand;
+  }
+  return flags;
+}
+
+int PlatformKeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down,
+                                          uint32_t scan_code, bool extended) {
+  (void)scan_code;
+  (void)extended;
+  const uint32_t injected_flags =
+      injected_modifier_state_.Update(key_code, is_down);
+
+  if (vkCodeToCGKeyCode.find(key_code) != vkCodeToCGKeyCode.end()) {
+    CGKeyCode cg_key_code = vkCodeToCGKeyCode[key_code];
+    CGEventRef event = CGEventCreateKeyboardEvent(NULL, cg_key_code, is_down);
+    if (!event) {
+      LOG_ERROR("CGEventCreateKeyboardEvent failed");
+      return -1;
+    }
+
+    CGEventSetFlags(event, ToCGEventFlags(injected_flags));
+    CGEventSetIntegerValueField(event, kCGEventSourceUserData,
+                               kCrossDeskInjectedKeyboardEvent);
+    CGEventPost(kCGHIDEventTap, event);
+    CFRelease(event);
+
+    // F1-F12 keys often require the FN key to be pressed on Mac keyboards, so
+    // we simulate the FN key release when an F1-F12 key is released.
+    if (IsFunctionKey(cg_key_code) && !is_down) {
+      CGEventRef fn_release_event =
+          CGEventCreateKeyboardEvent(NULL, fn_key_code_, false);
+      if (!fn_release_event) {
+        LOG_ERROR("CGEventCreateKeyboardEvent failed for fn release");
+        return -1;
+      }
+      CGEventSetIntegerValueField(fn_release_event, kCGEventSourceUserData,
+                                 kCrossDeskInjectedKeyboardEvent);
+      CGEventPost(kCGHIDEventTap, fn_release_event);
+      CFRelease(fn_release_event);
+    }
+  }
+
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/macos/input/keyboard/keyboard_capturer.h

@@ -0,0 +1,43 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2024-11-22
+ * Copyright (c) 2024 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _KEYBOARD_CAPTURER_H_
+#define _KEYBOARD_CAPTURER_H_
+
+#include <ApplicationServices/ApplicationServices.h>
+
+#include "device_controller.h"
+#include "macos_keyboard_modifier_state.h"
+
+namespace crossdesk {
+
+class PlatformKeyboardCapturer final : public KeyboardCapturer {
+ public:
+  PlatformKeyboardCapturer();
+  virtual ~PlatformKeyboardCapturer();
+
+ public:
+  virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
+  virtual int Unhook();
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false);
+
+ private:
+  CFMachPortRef event_tap_ = nullptr;
+  CFRunLoopSourceRef run_loop_source_ = nullptr;
+
+ public:
+  bool caps_lock_flag_ = false;
+  bool shift_flag_ = false;
+  bool control_flag_ = false;
+  bool option_flag_ = false;
+  bool command_flag_ = false;
+  int fn_key_code_ = 0x3F;
+  MacKeyboardModifierState injected_modifier_state_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/macos/input/macos_keyboard_modifier_state.h

@@ -0,0 +1,93 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-05-21
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _MACOS_KEYBOARD_MODIFIER_STATE_H_
+#define _MACOS_KEYBOARD_MODIFIER_STATE_H_
+
+#include <cstdint>
+
+namespace crossdesk {
+
+inline constexpr uint32_t kMacInjectedModifierShift = 1u << 0;
+inline constexpr uint32_t kMacInjectedModifierControl = 1u << 1;
+inline constexpr uint32_t kMacInjectedModifierOption = 1u << 2;
+inline constexpr uint32_t kMacInjectedModifierCommand = 1u << 3;
+
+class MacKeyboardModifierState {
+ public:
+  uint32_t Update(int key_code, bool is_down) {
+    bool* state = MutableStateForVk(key_code);
+    if (state != nullptr) {
+      *state = is_down;
+    }
+    return flags();
+  }
+
+  uint32_t flags() const {
+    uint32_t result = 0;
+    if (left_shift_down_ || right_shift_down_) {
+      result |= kMacInjectedModifierShift;
+    }
+    if (left_control_down_ || right_control_down_) {
+      result |= kMacInjectedModifierControl;
+    }
+    if (left_option_down_ || right_option_down_) {
+      result |= kMacInjectedModifierOption;
+    }
+    if (left_command_down_ || right_command_down_) {
+      result |= kMacInjectedModifierCommand;
+    }
+    return result;
+  }
+
+  void Clear() {
+    left_shift_down_ = false;
+    right_shift_down_ = false;
+    left_control_down_ = false;
+    right_control_down_ = false;
+    left_option_down_ = false;
+    right_option_down_ = false;
+    left_command_down_ = false;
+    right_command_down_ = false;
+  }
+
+ private:
+  bool* MutableStateForVk(int key_code) {
+    switch (key_code) {
+      case 0xA0:  // VK_LSHIFT
+        return &left_shift_down_;
+      case 0xA1:  // VK_RSHIFT
+        return &right_shift_down_;
+      case 0xA2:  // VK_LCONTROL
+        return &left_control_down_;
+      case 0xA3:  // VK_RCONTROL
+        return &right_control_down_;
+      case 0xA4:  // VK_LMENU / left Option
+        return &left_option_down_;
+      case 0xA5:  // VK_RMENU / right Option
+        return &right_option_down_;
+      case 0x5B:  // VK_LWIN / left Command
+        return &left_command_down_;
+      case 0x5C:  // VK_RWIN / right Command
+        return &right_command_down_;
+      default:
+        return nullptr;
+    }
+  }
+
+  bool left_shift_down_ = false;
+  bool right_shift_down_ = false;
+  bool left_control_down_ = false;
+  bool right_control_down_ = false;
+  bool left_option_down_ = false;
+  bool right_option_down_ = false;
+  bool left_command_down_ = false;
+  bool right_command_down_ = false;
+};
+
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/macos/input/macos_keycode.h

@@ -0,0 +1,861 @@
+/*
+     File:       HIToolbox/Events.h
+
+     Contains:   Event Manager Interfaces.
+
+     Copyright:  锟� 1985-2008 by Apple Computer, Inc., all rights reserved
+
+     Bugs?:      For bug reports, consult the following page on
+                 the World Wide Web:
+
+                     http://developer.apple.com/bugreporter/
+
+*/
+#ifndef __EVENTS__
+#define __EVENTS__
+
+#ifndef __APPLICATIONSERVICES__
+#include <ApplicationServices/ApplicationServices.h>
+#endif
+
+#include <AvailabilityMacros.h>
+
+#if PRAGMA_ONCE
+#pragma once
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#pragma pack(push, 2)
+
+typedef UInt16 EventKind;
+typedef UInt16 EventMask;
+enum {
+  nullEvent = 0,
+  mouseDown = 1,
+  mouseUp = 2,
+  keyDown = 3,
+  keyUp = 4,
+  autoKey = 5,
+  updateEvt = 6,
+  diskEvt = 7, /* Not sent in Carbon. See kEventClassVolume in CarbonEvents.h*/
+  activateEvt = 8,
+  osEvt = 15,
+  kHighLevelEvent = 23
+};
+
+enum {
+  mDownMask = 1 << mouseDown,   /* mouse button pressed*/
+  mUpMask = 1 << mouseUp,       /* mouse button released*/
+  keyDownMask = 1 << keyDown,   /* key pressed*/
+  keyUpMask = 1 << keyUp,       /* key released*/
+  autoKeyMask = 1 << autoKey,   /* key repeatedly held down*/
+  updateMask = 1 << updateEvt,  /* window needs updating*/
+  diskMask = 1 << diskEvt,      /* disk inserted*/
+  activMask = 1 << activateEvt, /* activate/deactivate window*/
+  highLevelEventMask = 0x0400,  /* high-level events (includes AppleEvents)*/
+  osMask = 1 << osEvt,          /* operating system events (suspend, resume)*/
+  everyEvent = 0xFFFF           /* all of the above*/
+};
+
+enum {
+  charCodeMask = 0x000000FF,
+  keyCodeMask = 0x0000FF00,
+  adbAddrMask = 0x00FF0000,
+  osEvtMessageMask = (UInt32)0xFF000000
+};
+
+enum {
+  /* OS event messages.  Event (sub)code is in the high byte of the message
+     field.*/
+  mouseMovedMessage = 0x00FA,
+  suspendResumeMessage = 0x0001
+};
+
+enum {
+  resumeFlag = 1 /* Bit 0 of message indicates resume vs suspend*/
+};
+
+#if CALL_NOT_IN_CARBON
+/*  convertClipboardFlag is not ever set under Carbon. This is because scrap
+ * conversion is  */
+/*  not tied to suspend/resume events any longer. Your application should
+ * instead use the   */
+/*  scrap promise mechanism and fulfill scrap requests only when your promise
+ * keeper proc   */
+/*  is called. If you need to know if the scrap has changed, you can cache the
+ * last         */
+/*  ScrapRef you received and compare it with the current ScrapRef */
+enum {
+  convertClipboardFlag =
+      2 /* Bit 1 in resume message indicates clipboard change*/
+};
+
+#endif /* CALL_NOT_IN_CARBON */
+
+/*
+    CARBON ALERT! BATTLESTATIONS!
+
+    The EventModifiers bits defined here are also used in the newer Carbon Event
+    key modifiers parameters. There are two main differences:
+
+    1)  The Carbon key modifiers parameter is a UInt32, not a UInt16. Never try
+   to extract the key modifiers parameter from a Carbon Event into an
+   EventModifiers type. You will probably get your stack trashed. 2)  The Carbon
+   key modifiers is just that: key modifiers. That parameter will never contain
+   the button state bit.
+*/
+typedef UInt16 EventModifiers;
+enum {
+  /* modifiers */
+  activeFlagBit = 0,      /* activate? (activateEvt and mouseDown)*/
+  btnStateBit = 7,        /* state of button?*/
+  cmdKeyBit = 8,          /* command key down?*/
+  shiftKeyBit = 9,        /* shift key down?*/
+  alphaLockBit = 10,      /* alpha lock down?*/
+  optionKeyBit = 11,      /* option key down?*/
+  controlKeyBit = 12,     /* control key down?*/
+  rightShiftKeyBit = 13,  /* right shift key down? Not supported on Mac OS X.*/
+  rightOptionKeyBit = 14, /* right Option key down? Not supported on Mac OS X.*/
+  rightControlKeyBit =
+      15 /* right Control key down? Not supported on Mac OS X.*/
+};
+
+enum {
+  activeFlag = 1 << activeFlagBit,
+  btnState = 1 << btnStateBit,
+  cmdKey = 1 << cmdKeyBit,
+  shiftKey = 1 << shiftKeyBit,
+  alphaLock = 1 << alphaLockBit,
+  optionKey = 1 << optionKeyBit,
+  controlKey = 1 << controlKeyBit,
+  rightShiftKey = 1 << rightShiftKeyBit,    /* Not supported on Mac OS X.*/
+  rightOptionKey = 1 << rightOptionKeyBit,  /* Not supported on Mac OS X.*/
+  rightControlKey = 1 << rightControlKeyBit /* Not supported on Mac OS X.*/
+};
+
+/* MacRoman character codes*/
+enum {
+  kNullCharCode = 0,
+  kHomeCharCode = 1,
+  kEnterCharCode = 3,
+  kEndCharCode = 4,
+  kHelpCharCode = 5,
+  kBellCharCode = 7,
+  kBackspaceCharCode = 8,
+  kTabCharCode = 9,
+  kLineFeedCharCode = 10,
+  kVerticalTabCharCode = 11,
+  kPageUpCharCode = 11,
+  kFormFeedCharCode = 12,
+  kPageDownCharCode = 12,
+  kReturnCharCode = 13,
+  kFunctionKeyCharCode = 16,
+  kCommandCharCode = 17,   /* glyph available only in system fonts*/
+  kCheckCharCode = 18,     /* glyph available only in system fonts*/
+  kDiamondCharCode = 19,   /* glyph available only in system fonts*/
+  kAppleLogoCharCode = 20, /* glyph available only in system fonts*/
+  kEscapeCharCode = 27,
+  kClearCharCode = 27,
+  kLeftArrowCharCode = 28,
+  kRightArrowCharCode = 29,
+  kUpArrowCharCode = 30,
+  kDownArrowCharCode = 31,
+  kSpaceCharCode = 32,
+  kDeleteCharCode = 127,
+  kBulletCharCode = 165,
+  kNonBreakingSpaceCharCode = 202
+};
+
+/* useful Unicode code points*/
+enum {
+  kShiftUnicode = 0x21E7,   /* Unicode UPWARDS WHITE ARROW*/
+  kControlUnicode = 0x2303, /* Unicode UP ARROWHEAD*/
+  kOptionUnicode = 0x2325,  /* Unicode OPTION KEY*/
+  kCommandUnicode = 0x2318, /* Unicode PLACE OF INTEREST SIGN*/
+  kPencilUnicode = 0x270E,  /* Unicode LOWER RIGHT PENCIL; actually pointed left
+                               until Mac OS X 10.3*/
+  kPencilLeftUnicode = 0xF802, /* Unicode LOWER LEFT PENCIL; available in Mac OS
+                                  X 10.3 and later*/
+  kCheckUnicode = 0x2713,      /* Unicode CHECK MARK*/
+  kDiamondUnicode = 0x25C6,    /* Unicode BLACK DIAMOND*/
+  kBulletUnicode = 0x2022,     /* Unicode BULLET*/
+  kAppleLogoUnicode = 0xF8FF   /* Unicode APPLE LOGO*/
+};
+
+/*
+ *  Summary:
+ *    Virtual keycodes
+ *
+ *  Discussion:
+ *    These constants are the virtual keycodes defined originally in
+ *    Inside Mac Volume V, pg. V-191. They identify physical keys on a
+ *    keyboard. Those constants with "ANSI" in the name are labeled
+ *    according to the key position on an ANSI-standard US keyboard.
+ *    For example, kVK_ANSI_A indicates the virtual keycode for the key
+ *    with the letter 'A' in the US keyboard layout. Other keyboard
+ *    layouts may have the 'A' key label on a different physical key;
+ *    in this case, pressing 'A' will generate a different virtual
+ *    keycode.
+ */
+enum {
+  kVK_ANSI_A = 0x00,
+  kVK_ANSI_S = 0x01,
+  kVK_ANSI_D = 0x02,
+  kVK_ANSI_F = 0x03,
+  kVK_ANSI_H = 0x04,
+  kVK_ANSI_G = 0x05,
+  kVK_ANSI_Z = 0x06,
+  kVK_ANSI_X = 0x07,
+  kVK_ANSI_C = 0x08,
+  kVK_ANSI_V = 0x09,
+  kVK_ANSI_B = 0x0B,
+  kVK_ANSI_Q = 0x0C,
+  kVK_ANSI_W = 0x0D,
+  kVK_ANSI_E = 0x0E,
+  kVK_ANSI_R = 0x0F,
+  kVK_ANSI_Y = 0x10,
+  kVK_ANSI_T = 0x11,
+  kVK_ANSI_1 = 0x12,
+  kVK_ANSI_2 = 0x13,
+  kVK_ANSI_3 = 0x14,
+  kVK_ANSI_4 = 0x15,
+  kVK_ANSI_6 = 0x16,
+  kVK_ANSI_5 = 0x17,
+  kVK_ANSI_Equal = 0x18,
+  kVK_ANSI_9 = 0x19,
+  kVK_ANSI_7 = 0x1A,
+  kVK_ANSI_Minus = 0x1B,
+  kVK_ANSI_8 = 0x1C,
+  kVK_ANSI_0 = 0x1D,
+  kVK_ANSI_RightBracket = 0x1E,
+  kVK_ANSI_O = 0x1F,
+  kVK_ANSI_U = 0x20,
+  kVK_ANSI_LeftBracket = 0x21,
+  kVK_ANSI_I = 0x22,
+  kVK_ANSI_P = 0x23,
+  kVK_ANSI_L = 0x25,
+  kVK_ANSI_J = 0x26,
+  kVK_ANSI_Quote = 0x27,
+  kVK_ANSI_K = 0x28,
+  kVK_ANSI_Semicolon = 0x29,
+  kVK_ANSI_Backslash = 0x2A,
+  kVK_ANSI_Comma = 0x2B,
+  kVK_ANSI_Slash = 0x2C,
+  kVK_ANSI_N = 0x2D,
+  kVK_ANSI_M = 0x2E,
+  kVK_ANSI_Period = 0x2F,
+  kVK_ANSI_Grave = 0x32,
+  kVK_ANSI_KeypadDecimal = 0x41,
+  kVK_ANSI_KeypadMultiply = 0x43,
+  kVK_ANSI_KeypadPlus = 0x45,
+  kVK_ANSI_KeypadClear = 0x47,
+  kVK_ANSI_KeypadDivide = 0x4B,
+  kVK_ANSI_KeypadEnter = 0x4C,
+  kVK_ANSI_KeypadMinus = 0x4E,
+  kVK_ANSI_KeypadEquals = 0x51,
+  kVK_ANSI_Keypad0 = 0x52,
+  kVK_ANSI_Keypad1 = 0x53,
+  kVK_ANSI_Keypad2 = 0x54,
+  kVK_ANSI_Keypad3 = 0x55,
+  kVK_ANSI_Keypad4 = 0x56,
+  kVK_ANSI_Keypad5 = 0x57,
+  kVK_ANSI_Keypad6 = 0x58,
+  kVK_ANSI_Keypad7 = 0x59,
+  kVK_ANSI_Keypad8 = 0x5B,
+  kVK_ANSI_Keypad9 = 0x5C
+};
+
+/* keycodes for keys that are independent of keyboard layout*/
+enum {
+  kVK_Return = 0x24,
+  kVK_Tab = 0x30,
+  kVK_Space = 0x31,
+  kVK_Delete = 0x33,
+  kVK_Escape = 0x35,
+  kVK_Command = 0x37,
+  kVK_Shift = 0x38,
+  kVK_CapsLock = 0x39,
+  kVK_Option = 0x3A,
+  kVK_Control = 0x3B,
+  kVK_RightCommand = 0x36,
+  kVK_RightShift = 0x3C,
+  kVK_RightOption = 0x3D,
+  kVK_RightControl = 0x3E,
+  kVK_Function = 0x3F,
+  kVK_F17 = 0x40,
+  kVK_VolumeUp = 0x48,
+  kVK_VolumeDown = 0x49,
+  kVK_Mute = 0x4A,
+  kVK_F18 = 0x4F,
+  kVK_F19 = 0x50,
+  kVK_F20 = 0x5A,
+  kVK_F5 = 0x60,
+  kVK_F6 = 0x61,
+  kVK_F7 = 0x62,
+  kVK_F3 = 0x63,
+  kVK_F8 = 0x64,
+  kVK_F9 = 0x65,
+  kVK_F11 = 0x67,
+  kVK_F13 = 0x69,
+  kVK_F16 = 0x6A,
+  kVK_F14 = 0x6B,
+  kVK_F10 = 0x6D,
+  kVK_ContextualMenu = 0x6E,
+  kVK_F12 = 0x6F,
+  kVK_F15 = 0x71,
+  kVK_Help = 0x72,
+  kVK_Home = 0x73,
+  kVK_PageUp = 0x74,
+  kVK_ForwardDelete = 0x75,
+  kVK_F4 = 0x76,
+  kVK_End = 0x77,
+  kVK_F2 = 0x78,
+  kVK_PageDown = 0x79,
+  kVK_F1 = 0x7A,
+  kVK_LeftArrow = 0x7B,
+  kVK_RightArrow = 0x7C,
+  kVK_DownArrow = 0x7D,
+  kVK_UpArrow = 0x7E
+};
+
+/* ISO keyboards only*/
+enum { kVK_ISO_Section = 0x0A };
+
+/* JIS keyboards only*/
+enum {
+  kVK_JIS_Yen = 0x5D,
+  kVK_JIS_Underscore = 0x5E,
+  kVK_JIS_KeypadComma = 0x5F,
+  kVK_JIS_Eisu = 0x66,
+  kVK_JIS_Kana = 0x68
+};
+
+struct EventRecord {
+  EventKind what;
+  unsigned long message;
+  UInt32 when;
+  Point where;
+  EventModifiers modifiers;
+};
+typedef struct EventRecord EventRecord;
+typedef CALLBACK_API(void, FKEYProcPtr)(void);
+typedef STACK_UPP_TYPE(FKEYProcPtr) FKEYUPP;
+/*
+ *  NewFKEYUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+/*
+ *  DisposeFKEYUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+/*
+ *  InvokeFKEYUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+#if !__LP64__
+/*
+ *  GetMouse()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use HIGetMousePosition instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.5 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern void GetMouse(Point *mouseLoc)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
+
+#endif /* !__LP64__ */
+
+/*
+ *  Button()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use GetCurrentButtonState or GetCurrentEventButtonState instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework but
+ * deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later Non-Carbon
+ * CFM:   in InterfaceLib 7.1 and later
+ */
+extern Boolean Button(void)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+#if !__LP64__
+/*
+ *  StillDown()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern Boolean StillDown(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+/*
+ *  WaitMouseUp()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern Boolean WaitMouseUp(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+/*
+ *  KeyTranslate()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use UCKeyTranslate instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern UInt32 KeyTranslate(const void *transData, UInt16 keycode, UInt32 *state)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+/*
+ *  GetCaretTime()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern UInt32 GetCaretTime(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#endif /* !__LP64__ */
+
+/*
+    QuickTime 3.0 supports GetKeys() on unix and win32
+    But, on little endian machines you will have to be
+    careful about bit numberings and/or use a KeyMapByteArray
+    instead.
+*/
+#if TARGET_API_MAC_OS8
+
+typedef UInt32 KeyMap[4];
+#else
+typedef BigEndianUInt32 KeyMap[4];
+#endif /* TARGET_API_MAC_OS8 */
+
+typedef UInt8 KeyMapByteArray[16];
+/*
+ *  GetKeys()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework
+ *    CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern void GetKeys(KeyMap theKeys) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+/* Obsolete event types & masks */
+enum {
+  networkEvt = 10,
+  driverEvt = 11,
+  app1Evt = 12,
+  app2Evt = 13,
+  app3Evt = 14,
+  app4Evt = 15,
+  networkMask = 0x0400,
+  driverMask = 0x0800,
+  app1Mask = 0x1000,
+  app2Mask = 0x2000,
+  app3Mask = 0x4000,
+  app4Mask = 0x8000
+};
+
+struct EvQEl {
+  QElemPtr qLink;
+  SInt16 qType;
+  EventKind
+      evtQWhat; /* this part is identical to the EventRecord as defined above */
+  unsigned long evtQMessage;
+  UInt32 evtQWhen;
+  Point evtQWhere;
+  EventModifiers evtQModifiers;
+};
+typedef struct EvQEl EvQEl;
+typedef EvQEl *EvQElPtr;
+typedef CALLBACK_API(void, GetNextEventFilterProcPtr)(EventRecord *theEvent,
+                                                      Boolean *result);
+typedef STACK_UPP_TYPE(GetNextEventFilterProcPtr) GetNextEventFilterUPP;
+/*
+ *  NewGetNextEventFilterUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+/*
+ *  DisposeGetNextEventFilterUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+/*
+ *  InvokeGetNextEventFilterUPP()
+ *
+ *  Availability:
+ *    Mac OS X:         not available
+ *    CarbonLib:        not available
+ *    Non-Carbon CFM:   available as macro/inline
+ */
+
+typedef GetNextEventFilterUPP GNEFilterUPP;
+#if !__LP64__
+/*
+ *  GetDblTime()
+ *
+ *  Summary:
+ *    Returns the maximum time (in units of 1/60th of a second) allowed
+ *    between two consecutive mouse-down events in order for the second
+ *    click to be considered a double-click.
+ *
+ *  Discussion:
+ *    In 64-bit applications, you may replace calls to this API with
+ *    calls to NXClickTime (declared in
+ *    <IOKit/hidsystem/event_status_driver.h>) or with +[NSEvent
+ *    doubleClickInterval] (available in Mac OS X 10.6 and later).
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Result:
+ *    The maximum time between mouse-downs allowed for a double-click.
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern UInt32 GetDblTime(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+/*
+ *  SetEventMask()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern void SetEventMask(EventMask value)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+/*
+ *  GetNextEvent()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use ReceiveNextEvent instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern Boolean GetNextEvent(EventMask eventMask, EventRecord *theEvent)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+/*
+ *  WaitNextEvent()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use ReceiveNextEvent instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern Boolean WaitNextEvent(EventMask eventMask, EventRecord *theEvent,
+                             UInt32 sleep, RgnHandle mouseRgn) /* can be NULL */
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+/*
+ *  EventAvail()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use FindSpecificEventInQueue instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern Boolean EventAvail(EventMask eventMask, EventRecord *theEvent)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+/*
+ *  PostEvent()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use PostEventToQueue or CGEventPost instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern OSErr PostEvent(EventKind eventNum, UInt32 eventMsg)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+#endif /* !__LP64__ */
+
+/*
+ *  FlushEvents()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use FlushEventsMatchingListFromQueue,
+ *    FlushSpecificEventsFromQueue, or FlushEventQueue instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework but
+ * deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later Non-Carbon
+ * CFM:   in InterfaceLib 7.1 and later
+ */
+extern void FlushEvents(EventMask whichMask, EventMask stopMask)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+#if OLDROUTINENAMES
+#define KeyTrans(transData, keycode, state) \
+  KeyTranslate(transData, keycode, state)
+#endif /* OLDROUTINENAMES */
+
+#if !__LP64__
+/*
+ *  KeyScript()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use TISSelectInputSource API for positive verbs (ScriptCode).
+ *     Use TSMDocument properties to restrict input sources:
+ *     kTSMDocumentEnabledInputSourcesPropertyTag
+ *     kTSMDocumentInputSourceOverridePropertyTag
+ *
+ *  Summary:
+ *    Switch to the specified script's default (last used) input source.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] but deprecated in 10.5 CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern void KeyScript(short code)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5;
+
+#endif /* !__LP64__ */
+
+/*
+ *  IsCmdChar()   *** DEPRECATED ***
+ *
+ *  Deprecated:
+ *    Use IsUserCancelEventRef or CheckEventQueueForUserCancel instead.
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework but
+ * deprecated in 10.6 CarbonLib:        in CarbonLib 1.0 and later Non-Carbon
+ * CFM:   in InterfaceLib 7.1 and later
+ */
+extern Boolean IsCmdChar(const EventRecord *event, short test)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_6;
+
+/*
+    LowMem accessor functions previously in LowMem.h
+*/
+/*
+ *  LMGetKeyThresh()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework
+ *    CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern SInt16 LMGetKeyThresh(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#if !__LP64__
+/*
+ *  LMSetKeyThresh()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern void LMSetKeyThresh(SInt16 value)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#endif /* !__LP64__ */
+
+/*
+ *  LMGetKeyRepThresh()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework
+ *    CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern SInt16 LMGetKeyRepThresh(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#if !__LP64__
+/*
+ *  LMSetKeyRepThresh()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern void LMSetKeyRepThresh(SInt16 value)
+    AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#endif /* !__LP64__ */
+
+/*
+ *  LMGetKbdLast()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework
+ *    CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern UInt8 LMGetKbdLast(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#if !__LP64__
+/*
+ *  LMSetKbdLast()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern void LMSetKbdLast(UInt8 value) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#endif /* !__LP64__ */
+
+/*
+ *  LMGetKbdType()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework
+ *    CarbonLib:        in CarbonLib 1.0 and later
+ *    Non-Carbon CFM:   in InterfaceLib 7.1 and later
+ */
+extern UInt8 LMGetKbdType(void) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#if !__LP64__
+/*
+ *  LMSetKbdType()
+ *
+ *  Mac OS X threading:
+ *    Not thread safe
+ *
+ *  Availability:
+ *    Mac OS X:         in version 10.0 and later in Carbon.framework [32-bit
+ * only] CarbonLib:        in CarbonLib 1.0 and later Non-Carbon CFM:   in
+ * InterfaceLib 7.1 and later
+ */
+extern void LMSetKbdType(UInt8 value) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
+
+#endif /* !__LP64__ */
+
+#pragma pack(pop)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __EVENTS__ */

apps/desktop/src/platform/macos/input/mouse/mouse_controller.cpp

@@ -0,0 +1,219 @@
+#include "mouse_controller.h"
+
+#include <remote_action.h>
+
+#include <ApplicationServices/ApplicationServices.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cmath>
+#include <cstdlib>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+namespace {
+
+constexpr auto kDoubleClickInterval = std::chrono::milliseconds(500);
+constexpr int kDoubleClickMaxDistance = 8;
+constexpr int kMaxClickState = 3;
+
+bool IsWithinClickDistance(int x1, int y1, int x2, int y2) {
+  return std::abs(x1 - x2) <= kDoubleClickMaxDistance &&
+         std::abs(y1 - y2) <= kDoubleClickMaxDistance;
+}
+
+void SetClickState(CGEventRef event, int click_state) {
+  if (!event) {
+    return;
+  }
+
+  CGEventSetIntegerValueField(
+      event, kCGMouseEventClickState,
+      std::max(1, std::min(click_state, kMaxClickState)));
+}
+
+}  // namespace
+
+PlatformMouseController::PlatformMouseController() {}
+
+PlatformMouseController::~PlatformMouseController() {}
+
+int PlatformMouseController::Init(std::vector<DisplayInfo> display_info_list) {
+  display_info_list_ = display_info_list;
+
+  return 0;
+}
+
+int PlatformMouseController::Destroy() { return 0; }
+
+void PlatformMouseController::UpdateDisplayInfoList(
+    const std::vector<DisplayInfo>& display_info_list) {
+  if (!display_info_list.empty()) {
+    display_info_list_ = display_info_list;
+  }
+}
+
+int PlatformMouseController::BeginClick(ClickTracker& tracker, int x, int y) {
+  const auto now = std::chrono::steady_clock::now();
+  const bool continues_previous_click =
+      tracker.has_last_down &&
+      now - tracker.last_down_time <= kDoubleClickInterval &&
+      IsWithinClickDistance(tracker.last_down_x, tracker.last_down_y, x, y);
+
+  tracker.click_state = continues_previous_click
+                            ? std::min(tracker.click_state + 1, kMaxClickState)
+                            : 1;
+  tracker.active_click_state = tracker.click_state;
+  tracker.has_last_down = true;
+  tracker.last_down_time = now;
+  tracker.last_down_x = x;
+  tracker.last_down_y = y;
+
+  return tracker.active_click_state;
+}
+
+int PlatformMouseController::EndClick(ClickTracker& tracker, int x, int y) {
+  const int click_state = tracker.active_click_state;
+  if (!IsWithinClickDistance(tracker.last_down_x, tracker.last_down_y, x, y)) {
+    tracker.has_last_down = false;
+    tracker.click_state = 0;
+    tracker.active_click_state = 1;
+  }
+
+  return click_state;
+}
+
+int PlatformMouseController::SendMouseCommand(RemoteAction remote_action,
+                                      int display_index) {
+  if (remote_action.type != ControlType::mouse) {
+    return 0;
+  }
+
+  if (display_index < 0 ||
+      display_index >= static_cast<int>(display_info_list_.size())) {
+    LOG_WARN("Mouse command skipped, invalid display_index={}, displays={}",
+             display_index, display_info_list_.size());
+    return -1;
+  }
+
+  const DisplayInfo& display_info = display_info_list_[display_index];
+  if (display_info.width <= 0 || display_info.height <= 0) {
+    LOG_WARN("Mouse command skipped, invalid display geometry: {}x{}",
+             display_info.width, display_info.height);
+    return -1;
+  }
+
+  const double normalized_x =
+      std::clamp(static_cast<double>(remote_action.m.x), 0.0, 1.0);
+  const double normalized_y =
+      std::clamp(static_cast<double>(remote_action.m.y), 0.0, 1.0);
+  // Keep the coordinate continuous until it reaches Core Graphics. This
+  // avoids turning a one-pixel rounding error into a visible offset when the
+  // client zooms the remote image. The upper bound remains just inside the
+  // display because CG display rectangles use an exclusive right/bottom edge.
+  const double max_x = std::nextafter(static_cast<double>(display_info.right),
+                                      static_cast<double>(display_info.left));
+  const double max_y = std::nextafter(static_cast<double>(display_info.bottom),
+                                      static_cast<double>(display_info.top));
+  const double mouse_pos_x = std::clamp(
+      display_info.left + normalized_x * display_info.width,
+      static_cast<double>(display_info.left), max_x);
+  const double mouse_pos_y = std::clamp(
+      display_info.top + normalized_y * display_info.height,
+      static_cast<double>(display_info.top), max_y);
+  const int tracked_mouse_pos_x = static_cast<int>(std::lround(mouse_pos_x));
+  const int tracked_mouse_pos_y = static_cast<int>(std::lround(mouse_pos_y));
+
+  CGEventRef mouse_event = nullptr;
+  CGEventType mouse_type;
+  CGMouseButton mouse_button;
+  CGPoint mouse_point = CGPointMake(mouse_pos_x, mouse_pos_y);
+  int click_state = 1;
+
+  switch (remote_action.m.flag) {
+    case MouseFlag::left_down:
+      mouse_type = kCGEventLeftMouseDown;
+      left_dragging_ = true;
+      click_state = BeginClick(left_click_tracker_, tracked_mouse_pos_x,
+                               tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonLeft);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::left_up:
+      mouse_type = kCGEventLeftMouseUp;
+      left_dragging_ = false;
+      click_state = EndClick(left_click_tracker_, tracked_mouse_pos_x,
+                             tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonLeft);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::right_down:
+      mouse_type = kCGEventRightMouseDown;
+      right_dragging_ = true;
+      click_state = BeginClick(right_click_tracker_, tracked_mouse_pos_x,
+                               tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonRight);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::right_up:
+      mouse_type = kCGEventRightMouseUp;
+      right_dragging_ = false;
+      click_state = EndClick(right_click_tracker_, tracked_mouse_pos_x,
+                             tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonRight);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::middle_down:
+      mouse_type = kCGEventOtherMouseDown;
+      click_state = BeginClick(middle_click_tracker_, tracked_mouse_pos_x,
+                               tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonCenter);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::middle_up:
+      mouse_type = kCGEventOtherMouseUp;
+      click_state = EndClick(middle_click_tracker_, tracked_mouse_pos_x,
+                             tracked_mouse_pos_y);
+      mouse_event = CGEventCreateMouseEvent(NULL, mouse_type, mouse_point,
+                                            kCGMouseButtonCenter);
+      SetClickState(mouse_event, click_state);
+      break;
+    case MouseFlag::wheel_vertical:
+      mouse_event = CGEventCreateScrollWheelEvent(NULL, kCGScrollEventUnitLine,
+                                                  2, remote_action.m.s, 0);
+      break;
+    case MouseFlag::wheel_horizontal:
+      mouse_event = CGEventCreateScrollWheelEvent(NULL, kCGScrollEventUnitLine,
+                                                  2, 0, remote_action.m.s);
+      break;
+    default:
+      if (left_dragging_) {
+        mouse_type = kCGEventLeftMouseDragged;
+        mouse_button = kCGMouseButtonLeft;
+      } else if (right_dragging_) {
+        mouse_type = kCGEventRightMouseDragged;
+        mouse_button = kCGMouseButtonRight;
+      } else {
+        mouse_type = kCGEventMouseMoved;
+        mouse_button = kCGMouseButtonLeft;
+      }
+
+      mouse_event =
+          CGEventCreateMouseEvent(NULL, mouse_type, mouse_point, mouse_button);
+      break;
+  }
+
+  if (mouse_event) {
+    CGEventPost(kCGHIDEventTap, mouse_event);
+    CFRelease(mouse_event);
+  }
+
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/macos/input/mouse/mouse_controller.h

@@ -0,0 +1,53 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2023-12-14
+ * Copyright (c) 2023 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _MOUSE_CONTROLLER_H_
+#define _MOUSE_CONTROLLER_H_
+
+#include <chrono>
+#include <vector>
+
+#include <remote_action.h>
+
+#include "device_controller.h"
+#include "display_info.h"
+
+namespace crossdesk {
+
+class PlatformMouseController final : public MouseController {
+ public:
+  PlatformMouseController();
+  virtual ~PlatformMouseController();
+
+ public:
+  virtual int Init(std::vector<DisplayInfo> display_info_list);
+  virtual int Destroy();
+  virtual int SendMouseCommand(RemoteAction remote_action, int display_index);
+  void UpdateDisplayInfoList(
+      const std::vector<DisplayInfo>& display_info_list);
+
+ private:
+  struct ClickTracker {
+    bool has_last_down = false;
+    std::chrono::steady_clock::time_point last_down_time{};
+    int last_down_x = 0;
+    int last_down_y = 0;
+    int click_state = 0;
+    int active_click_state = 1;
+  };
+
+  int BeginClick(ClickTracker& tracker, int x, int y);
+  int EndClick(ClickTracker& tracker, int x, int y);
+
+  std::vector<DisplayInfo> display_info_list_;
+  bool left_dragging_ = false;
+  bool right_dragging_ = false;
+  ClickTracker left_click_tracker_;
+  ClickTracker right_click_tracker_;
+  ClickTracker middle_click_tracker_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/macos/path_backend.cpp

@@ -0,0 +1,48 @@
+#include "platform/path_backend.h"
+
+#include <mach-o/dyld.h>
+
+#include <cstdlib>
+#include <vector>
+
+namespace crossdesk::platform {
+namespace {
+
+std::filesystem::path Home() {
+  const char* value = std::getenv("HOME");
+  return value ? std::filesystem::path(value) : std::filesystem::path();
+}
+
+std::filesystem::path EnvOrDefault(const char* name,
+                                   const std::filesystem::path& fallback) {
+  const char* value = std::getenv(name);
+  return value ? std::filesystem::path(value) : fallback;
+}
+
+}  // namespace
+
+std::filesystem::path GetExecutableDirectory() {
+  uint32_t size = 0;
+  _NSGetExecutablePath(nullptr, &size);
+  std::vector<char> buffer(size + 1);
+  if (_NSGetExecutablePath(buffer.data(), &size) != 0) return {};
+  std::error_code error;
+  std::filesystem::path executable =
+      std::filesystem::weakly_canonical(buffer.data(), error);
+  if (error) executable = buffer.data();
+  return executable.parent_path();
+}
+
+std::filesystem::path GetConfigPath(const std::string& app_name) {
+  return EnvOrDefault("XDG_CONFIG_HOME", Home() / ".config") / app_name;
+}
+
+std::filesystem::path GetCachePath(const std::string& app_name) {
+  return EnvOrDefault("XDG_CACHE_HOME", Home() / ".cache") / app_name;
+}
+
+std::filesystem::path GetLogPath(const std::string& app_name) {
+  return Home() / "Library" / "Logs" / app_name;
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/macos/screen_capturer/screen_capturer_factory.cpp

@@ -0,0 +1,11 @@
+#include "screen_capturer_factory.h"
+
+#include "screen_capturer_sck.h"
+
+namespace crossdesk {
+
+ScreenCapturer* ScreenCapturerFactory::Create() {
+  return new ScreenCapturerSck();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/macos/screen_capturer/screen_capturer_sck.cpp

@@ -0,0 +1,90 @@
+#include "screen_capturer_sck.h"
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+ScreenCapturerSck::ScreenCapturerSck() {}
+ScreenCapturerSck::~ScreenCapturerSck() {}
+
+int ScreenCapturerSck::Init(const int fps, cb_desktop_data cb) {
+  if (cb) {
+    on_data_ = cb;
+  } else {
+    LOG_ERROR("cb is null");
+    return -1;
+  }
+
+  screen_capturer_sck_impl_ = CreateScreenCapturerSck();
+  const int ret = screen_capturer_sck_impl_->Init(fps, on_data_);
+  if (ret != 0) {
+    screen_capturer_sck_impl_.reset();
+    return ret;
+  }
+
+  return 0;
+}
+
+int ScreenCapturerSck::Destroy() {
+  if (screen_capturer_sck_impl_) {
+    screen_capturer_sck_impl_->Destroy();
+  }
+  return 0;
+}
+
+int ScreenCapturerSck::Start(bool show_cursor) {
+  if (!screen_capturer_sck_impl_) {
+    return -1;
+  }
+
+  return screen_capturer_sck_impl_->Start(show_cursor);
+}
+
+int ScreenCapturerSck::Stop() {
+  if (screen_capturer_sck_impl_) {
+    screen_capturer_sck_impl_->Stop();
+  }
+  return 0;
+}
+
+int ScreenCapturerSck::Pause(int monitor_index) {
+  if (screen_capturer_sck_impl_) {
+    return screen_capturer_sck_impl_->Pause(monitor_index);
+  }
+  return 0;
+}
+
+int ScreenCapturerSck::Resume(int monitor_index) {
+  if (screen_capturer_sck_impl_) {
+    return screen_capturer_sck_impl_->Resume(monitor_index);
+  }
+  return 0;
+}
+
+int ScreenCapturerSck::SwitchTo(int monitor_index) {
+  if (screen_capturer_sck_impl_) {
+    return screen_capturer_sck_impl_->SwitchTo(monitor_index);
+  }
+
+  return -1;
+}
+
+int ScreenCapturerSck::ResetToInitialMonitor() {
+  if (screen_capturer_sck_impl_) {
+    return screen_capturer_sck_impl_->ResetToInitialMonitor();
+  }
+  return -1;
+}
+
+std::vector<DisplayInfo> ScreenCapturerSck::GetDisplayInfoList() {
+  if (screen_capturer_sck_impl_) {
+    return screen_capturer_sck_impl_->GetDisplayInfoList();
+  }
+
+  return std::vector<DisplayInfo>();
+}
+
+void ScreenCapturerSck::OnFrame() {}
+
+void ScreenCapturerSck::CleanUp() {}
+}  // namespace crossdesk

apps/desktop/src/platform/macos/screen_capturer/screen_capturer_sck.h

@@ -0,0 +1,62 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2024-10-17
+ * Copyright (c) 2024 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_SCK_H_
+#define _SCREEN_CAPTURER_SCK_H_
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerSck : public ScreenCapturer {
+ public:
+  ScreenCapturerSck();
+  ~ScreenCapturerSck();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override;
+
+  void OnFrame();
+
+ protected:
+  void CleanUp();
+
+ private:
+  std::unique_ptr<ScreenCapturer> CreateScreenCapturerSck();
+
+ private:
+  int _fps;
+  cb_desktop_data on_data_;
+  unsigned char* nv12_frame_ = nullptr;
+  bool inited_ = false;
+
+  // thread
+  std::thread capture_thread_;
+  std::atomic_bool running_;
+
+ private:
+  std::unique_ptr<ScreenCapturer> screen_capturer_sck_impl_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/macos/screen_capturer/screen_capturer_sck_impl.mm

@@ -0,0 +1,769 @@
+/*
+ *  Copyright (c) 2024 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+#include "screen_capturer_sck.h"
+
+#include <AppKit/AppKit.h>
+#include <ApplicationServices/ApplicationServices.h>
+#include <CoreGraphics/CoreGraphics.h>
+#include <IOKit/IOKitLib.h>
+#include <IOKit/graphics/IOGraphicsLib.h>
+#include <IOSurface/IOSurface.h>
+#include <ScreenCaptureKit/ScreenCaptureKit.h>
+#include <atomic>
+#include <cstring>
+#include <limits>
+#include <map>
+#include <mutex>
+#include <vector>
+#include "display_info.h"
+#include <display_stream_id.h>
+#include "rd_log.h"
+
+using namespace crossdesk;
+
+class ScreenCapturerSckImpl;
+
+static const int kFullDesktopScreenId = -1;
+
+static std::string NSErrorToString(NSError *error) {
+  if (!error) {
+    return "";
+  }
+
+  const char *description = [error.localizedDescription UTF8String];
+  return description ? description : "";
+}
+
+// The ScreenCaptureKit API was available in macOS 12.3, but full-screen capture
+// was reported to be broken before macOS 13 - see http://crbug.com/40234870.
+// Also, the `SCContentFilter` fields `contentRect` and `pointPixelScale` were
+// introduced in macOS 14.
+API_AVAILABLE(macos(14.0))
+@interface SckHelper : NSObject <SCStreamDelegate, SCStreamOutput>
+
+- (instancetype)initWithCapturer:(ScreenCapturerSckImpl *)capturer;
+
+- (void)onShareableContentCreated:(SCShareableContent *)content;
+
+// Called just before the capturer is destroyed. This avoids a dangling pointer,
+// and prevents any new calls into a deleted capturer. If any method-call on the
+// capturer is currently running on a different thread, this blocks until it
+// completes.
+- (void)releaseCapturer;
+@end
+
+class API_AVAILABLE(macos(14.0)) ScreenCapturerSckImpl : public ScreenCapturer {
+ public:
+  explicit ScreenCapturerSckImpl();
+
+  ScreenCapturerSckImpl(const ScreenCapturerSckImpl &) = delete;
+  ScreenCapturerSckImpl &operator=(const ScreenCapturerSckImpl &) = delete;
+  ~ScreenCapturerSckImpl();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+
+  int Start(bool show_cursor) override;
+
+  int SwitchTo(int monitor_index) override;
+
+  int Destroy() override;
+
+  int Stop() override;
+
+  int Pause(int monitor_index) override { return 0; }
+
+  int Resume(int monitor_index) override { return 0; }
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override {
+    std::lock_guard<std::mutex> lock(lock_);
+    return display_info_list_;
+  }
+  int ResetToInitialMonitor() override;
+
+ private:
+  std::vector<DisplayInfo> display_info_list_;
+  std::map<int, CGDirectDisplayID> display_id_map_;
+  unsigned char *nv12_frame_ = nullptr;
+  size_t nv12_frame_size_ = 0;
+  int width_ = 0;
+  int height_ = 0;
+  int fps_ = 60;
+  bool show_cursor_ = false;
+  bool capture_requested_ = false;
+  bool invalid_stream_id_logged_ = false;
+
+ public:
+  // Called by SckHelper when shareable content is returned by ScreenCaptureKit. `content` will be
+  // nil if an error occurred. May run on an arbitrary thread.
+  void OnShareableContentCreated(SCShareableContent *content);
+  // Called by SckHelper to notify of a newly captured frame. May run on an arbitrary thread.
+  // void OnNewIOSurface(IOSurfaceRef io_surface, CFDictionaryRef attachment);
+  void OnNewCVPixelBuffer(CVPixelBufferRef pixelBuffer, CFDictionaryRef attachment);
+
+ private:
+  // Called when starting the capturer or the configuration has changed (either from a
+  // SwitchTo() call, or the screen-resolution has changed). This tells SCK to fetch new
+  // shareable content, and the completion-handler will either start a new stream, or reconfigure
+  // the existing stream. Runs on the caller's thread.
+  void StartOrReconfigureCapturer();
+  // Helper object to receive Objective-C callbacks from ScreenCaptureKit and call into this C++
+  // object. The helper may outlive this C++ instance, if a completion-handler is passed to
+  // ScreenCaptureKit APIs and the C++ object is deleted before the handler executes.
+  SckHelper *__strong helper_ = nil;
+  // Callback for returning captured frames, or errors, to the caller. Only used on the caller's
+  // thread.
+  cb_desktop_data _on_data = nullptr;
+  // Signals that a permanent error occurred. This may be set on any thread, and is read by
+  // CaptureFrame() which runs on the caller's thread.
+  std::atomic<bool> permanent_error_ = false;
+  // Guards some variables that may be accessed on different threads.
+  std::mutex lock_;
+  // Provides captured desktop frames.
+  SCStream *__strong stream_ = nil;
+  // Currently selected display, or 0 if the full desktop is selected. This capturer does not
+  // support full-desktop capture, and will fall back to the first display.
+  CGDirectDisplayID current_display_ = 0;
+  int initial_monitor_index_ = 0;
+  int current_monitor_index_ = 0;
+  std::string current_stream_id_;
+};
+
+static std::string NSStringToUtf8(NSString *value) {
+  if (!value || value.length == 0) return "";
+  const char *utf8 = value.UTF8String;
+  return utf8 ? utf8 : "";
+}
+
+static std::string GetAppKitDisplayName(CGDirectDisplayID display_id) {
+  if (@available(macOS 10.15, *)) {
+    @autoreleasepool {
+      for (NSScreen *screen in NSScreen.screens) {
+        NSNumber *screen_number = screen.deviceDescription[@"NSScreenNumber"];
+        if (screen_number && screen_number.unsignedIntValue == display_id) {
+          return NSStringToUtf8(screen.localizedName);
+        }
+      }
+    }
+  }
+  return "";
+}
+
+std::string GetDisplayName(CGDirectDisplayID display_id) {
+  // IODisplayConnect is no longer exposed for some external displays on
+  // modern Apple Silicon Macs. NSScreen is the system-owned source for the
+  // user-visible name and maps directly to CGDirectDisplayID.
+  std::string appkit_name = GetAppKitDisplayName(display_id);
+  if (!appkit_name.empty()) return appkit_name;
+
+  // Keep the IOKit path for older macOS versions and display drivers.
+  io_iterator_t iter;
+  io_service_t serv = 0, matched_serv = 0;
+
+  CFMutableDictionaryRef matching = IOServiceMatching("IODisplayConnect");
+  if (IOServiceGetMatchingServices(kIOMainPortDefault, matching, &iter) != KERN_SUCCESS) {
+    return "";
+  }
+
+  while ((serv = IOIteratorNext(iter)) != 0) {
+    CFDictionaryRef info = IODisplayCreateInfoDictionary(serv, kIODisplayOnlyPreferredName);
+    if (info) {
+      CFNumberRef vendorID = (CFNumberRef)CFDictionaryGetValue(info, CFSTR(kDisplayVendorID));
+      CFNumberRef productID = (CFNumberRef)CFDictionaryGetValue(info, CFSTR(kDisplayProductID));
+      uint32_t vID = 0, pID = 0;
+      if (vendorID && productID && CFNumberGetValue(vendorID, kCFNumberIntType, &vID) &&
+          CFNumberGetValue(productID, kCFNumberIntType, &pID) &&
+          vID == CGDisplayVendorNumber(display_id) && pID == CGDisplayModelNumber(display_id)) {
+        matched_serv = serv;
+        CFRelease(info);
+        break;
+      }
+      CFRelease(info);
+    }
+    IOObjectRelease(serv);
+  }
+  IOObjectRelease(iter);
+
+  if (!matched_serv) return "";
+
+  CFDictionaryRef display_info =
+      IODisplayCreateInfoDictionary(matched_serv, kIODisplayOnlyPreferredName);
+  IOObjectRelease(matched_serv);
+  if (!display_info) return "";
+
+  CFDictionaryRef product_name_dict =
+      (CFDictionaryRef)CFDictionaryGetValue(display_info, CFSTR(kDisplayProductName));
+  std::string result;
+  if (product_name_dict) {
+    CFIndex count = CFDictionaryGetCount(product_name_dict);
+    if (count > 0) {
+      std::vector<const void *> keys(count);
+      std::vector<const void *> values(count);
+      CFDictionaryGetKeysAndValues(product_name_dict, keys.data(), values.data());
+      CFStringRef name_ref = (CFStringRef)values[0];
+      if (name_ref) {
+        CFIndex maxSize =
+            CFStringGetMaximumSizeForEncoding(CFStringGetLength(name_ref), kCFStringEncodingUTF8) +
+            1;
+        std::vector<char> buffer(maxSize);
+        if (CFStringGetCString(name_ref, buffer.data(), buffer.size(), kCFStringEncodingUTF8)) {
+          result = buffer.data();
+        }
+      }
+    }
+  }
+  CFRelease(display_info);
+  return result;
+}
+
+ScreenCapturerSckImpl::ScreenCapturerSckImpl() {
+  helper_ = [[SckHelper alloc] initWithCapturer:this];
+}
+
+ScreenCapturerSckImpl::~ScreenCapturerSckImpl() {
+  SckHelper *helper_to_release = nil;
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (stream_) {
+      [stream_ stopCaptureWithCompletionHandler:nil];
+      stream_ = nil;
+    }
+    _on_data = nullptr;
+    helper_to_release = helper_;
+    helper_ = nil;
+  }
+  [helper_to_release releaseCapturer];
+
+  display_info_list_.clear();
+  display_id_map_.clear();
+
+  if (nv12_frame_) {
+    delete[] nv12_frame_;
+    nv12_frame_ = nullptr;
+    nv12_frame_size_ = 0;
+  }
+}
+
+int ScreenCapturerSckImpl::Init(const int fps, cb_desktop_data cb) {
+  if (!cb) {
+    LOG_ERROR("Screen capturer callback is null");
+    return -1;
+  }
+
+  _on_data = cb;
+  fps_ = fps > 0 ? fps : 60;
+  display_info_list_.clear();
+  display_id_map_.clear();
+
+  if (@available(macOS 10.15, *)) {
+    bool has_permission = CGPreflightScreenCaptureAccess();
+    if (!has_permission) {
+      LOG_ERROR("Screen recording permission not granted");
+      return -1;
+    }
+  }
+
+  dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+  __block SCShareableContent *content = nil;
+  __block NSError *capture_error = nil;
+
+  [SCShareableContent
+      getShareableContentWithCompletionHandler:^(SCShareableContent *result, NSError *error) {
+        if (error) {
+          capture_error = error;
+          LOG_ERROR("Failed to get shareable content: {}", NSErrorToString(error));
+        } else {
+          content = result;
+        }
+        dispatch_semaphore_signal(sema);
+      }];
+  dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
+
+  if (capture_error || !content || content.displays.count == 0) {
+    LOG_ERROR("Failed to get display info, error: {}",
+              NSErrorToString(capture_error));
+    return -1;
+  }
+
+  for (SCDisplay *display in content.displays) {
+    CGDirectDisplayID display_id = display.displayID;
+    CGRect bounds = CGDisplayBounds(display_id);
+    bool is_primary = CGDisplayIsMain(display_id);
+
+    std::string name = GetDisplayName(display_id);
+    if (name.empty()) {
+      name = MakeDisplayStreamId(display_info_list_.size());
+    }
+
+    LOG_INFO("macOS display discovered: index={}, display_id={}, name='{}'",
+             display_info_list_.size(), display_id, name);
+
+    DisplayInfo info((void *)(uintptr_t)display_id, name, is_primary,
+                     static_cast<int>(bounds.origin.x), static_cast<int>(bounds.origin.y),
+                     static_cast<int>(bounds.origin.x + bounds.size.width),
+                     static_cast<int>(bounds.origin.y + bounds.size.height));
+
+    display_info_list_.push_back(info);
+    display_id_map_[display_info_list_.size() - 1] = display_id;
+  }
+
+  initial_monitor_index_ = 0;
+  current_monitor_index_ = initial_monitor_index_;
+  current_display_ = display_id_map_[current_monitor_index_];
+  current_stream_id_ = MakeDisplayStreamId(current_monitor_index_);
+  return 0;
+}
+
+int ScreenCapturerSckImpl::Start(bool show_cursor) {
+  if (permanent_error_) {
+    LOG_ERROR("Cannot start capturer: permanent error occurred");
+    return -1;
+  }
+
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (display_info_list_.empty()) {
+      LOG_ERROR("Cannot start capturer: display info not initialized");
+      return -1;
+    }
+    show_cursor_ = show_cursor;
+    capture_requested_ = true;
+    invalid_stream_id_logged_ = false;
+  }
+  StartOrReconfigureCapturer();
+  return 0;
+}
+
+int ScreenCapturerSckImpl::SwitchTo(int monitor_index) {
+  bool should_reconfigure = false;
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    auto display_it = display_id_map_.find(monitor_index);
+    if (display_it == display_id_map_.end() || monitor_index < 0 ||
+        monitor_index >= static_cast<int>(display_info_list_.size())) {
+      LOG_WARN("SwitchTo skipped, invalid monitor_index={}, displays={}",
+               monitor_index, display_id_map_.size());
+      return -1;
+    }
+    current_monitor_index_ = monitor_index;
+    current_display_ = display_it->second;
+    current_stream_id_ = MakeDisplayStreamId(monitor_index);
+    should_reconfigure = capture_requested_;
+  }
+  if (should_reconfigure) {
+    StartOrReconfigureCapturer();
+  }
+  return 0;
+}
+
+int ScreenCapturerSckImpl::ResetToInitialMonitor() {
+  const int target = initial_monitor_index_;
+  bool should_reconfigure = false;
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (display_info_list_.empty()) return -1;
+    auto display_it = display_id_map_.find(target);
+    if (display_it == display_id_map_.end()) {
+      LOG_WARN("ResetToInitialMonitor skipped, invalid monitor_index={}", target);
+      return -1;
+    }
+    const CGDirectDisplayID target_display = display_it->second;
+    if (current_display_ == target_display &&
+        current_monitor_index_ == target) {
+      return 0;
+    }
+    current_monitor_index_ = target;
+    current_display_ = target_display;
+    current_stream_id_ = MakeDisplayStreamId(target);
+    should_reconfigure = capture_requested_ && stream_ != nil;
+  }
+
+  // Resetting session state must not create a capture stream. Preserve the
+  // selected monitor for the next Start(), and only reconfigure an active one.
+  if (should_reconfigure) {
+    StartOrReconfigureCapturer();
+  }
+  return 0;
+}
+
+int ScreenCapturerSckImpl::Destroy() {
+  SckHelper *helper_to_release = nil;
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (stream_) {
+      LOG_INFO("Destroying stream");
+      [stream_ stopCaptureWithCompletionHandler:nil];
+      stream_ = nil;
+    }
+    capture_requested_ = false;
+    current_display_ = 0;
+    current_stream_id_.clear();
+    permanent_error_ = false;
+    _on_data = nullptr;
+    helper_to_release = helper_;
+    helper_ = nil;
+  }
+
+  [helper_to_release releaseCapturer];
+
+  return 0;
+}
+
+int ScreenCapturerSckImpl::Stop() {
+  std::lock_guard<std::mutex> lock(lock_);
+  capture_requested_ = false;
+  if (stream_) {
+    LOG_INFO("Stopping stream");
+    [stream_ stopCaptureWithCompletionHandler:nil];
+    stream_ = nil;
+  }
+  current_display_ = 0;
+
+  return 0;
+}
+
+void ScreenCapturerSckImpl::OnShareableContentCreated(SCShareableContent *content) {
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (!capture_requested_) {
+      LOG_INFO("Ignoring stale ScreenCaptureKit display refresh after stop");
+      return;
+    }
+  }
+
+  if (!content) {
+    LOG_ERROR("getShareableContent failed");
+    permanent_error_ = true;
+    return;
+  }
+
+  if (!content.displays || content.displays.count == 0) {
+    LOG_ERROR("getShareableContent returned no displays");
+    permanent_error_ = true;
+    return;
+  }
+
+  SCDisplay *captured_display = nil;
+  bool show_cursor = false;
+  {
+    std::lock_guard<std::mutex> lock(lock_);
+    if (!capture_requested_) return;
+
+    int logical_index = current_monitor_index_;
+    if (logical_index < 0 ||
+        logical_index >= static_cast<int>(display_info_list_.size())) {
+      logical_index = 0;
+    }
+
+    SCDisplay *logical_fallback = nil;
+    int display_index = 0;
+    for (SCDisplay *display in content.displays) {
+      if (display_index == logical_index) logical_fallback = display;
+      if (current_display_ != 0 && current_display_ == display.displayID) {
+        captured_display = display;
+        break;
+      }
+      ++display_index;
+    }
+    if (!captured_display) {
+      captured_display = logical_fallback ? logical_fallback
+                                          : content.displays.firstObject;
+      if (!logical_fallback) logical_index = 0;
+    }
+
+    if (captured_display) {
+      const CGDirectDisplayID old_display = current_display_;
+      const CGDirectDisplayID new_display = captured_display.displayID;
+      const std::string stable_stream_id = ResolveDisplayStreamId(
+          current_stream_id_.c_str(), display_info_list_.size(), logical_index);
+      if (stable_stream_id.empty()) {
+        LOG_ERROR("Cannot map macOS display {} to a registered video stream",
+                  new_display);
+        return;
+      }
+
+      current_monitor_index_ = logical_index;
+      current_display_ = new_display;
+      current_stream_id_ = stable_stream_id;
+      display_id_map_[logical_index] = new_display;
+
+      CGRect bounds = CGDisplayBounds(new_display);
+      auto& info = display_info_list_[logical_index];
+      info.handle = (void *)(uintptr_t)new_display;
+      info.is_primary = CGDisplayIsMain(new_display);
+      info.left = static_cast<int>(bounds.origin.x);
+      info.top = static_cast<int>(bounds.origin.y);
+      info.right = static_cast<int>(bounds.origin.x + bounds.size.width);
+      info.bottom = static_cast<int>(bounds.origin.y + bounds.size.height);
+      info.width = info.right - info.left;
+      info.height = info.bottom - info.top;
+      const std::string refreshed_name = GetDisplayName(new_display);
+      if (!refreshed_name.empty()) {
+        info.name = refreshed_name;
+      }
+
+      if (old_display != new_display) {
+        LOG_INFO("macOS display mapping refreshed: slot={}, old_id={}, "
+                 "new_id={}, stream='{}'",
+                 logical_index, old_display, new_display, stable_stream_id);
+      }
+    }
+    show_cursor = show_cursor_;
+  }
+
+  if (!captured_display) {
+    LOG_ERROR("Failed to find valid display");
+    permanent_error_ = true;
+    return;
+  }
+
+  SCContentFilter *filter = [[SCContentFilter alloc] initWithDisplay:captured_display
+                                                    excludingWindows:@[]];
+  if (!filter) {
+    LOG_ERROR("Failed to create SCContentFilter");
+    permanent_error_ = true;
+    return;
+  }
+
+  SCStreamConfiguration *config = [[SCStreamConfiguration alloc] init];
+  if (!config) {
+    LOG_ERROR("Failed to create SCStreamConfiguration");
+    permanent_error_ = true;
+    return;
+  }
+
+  config.pixelFormat = kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange;
+  config.showsCursor = show_cursor;
+  config.width = filter.contentRect.size.width * filter.pointPixelScale;
+  config.height = filter.contentRect.size.height * filter.pointPixelScale;
+  config.captureResolution = SCCaptureResolutionAutomatic;
+  config.minimumFrameInterval = CMTimeMake(1, fps_);
+
+  std::lock_guard<std::mutex> lock(lock_);
+  if (!capture_requested_) return;
+
+  if (stream_) {
+    LOG_INFO("Updating stream configuration");
+    [stream_ updateContentFilter:filter completionHandler:nil];
+    [stream_ updateConfiguration:config completionHandler:nil];
+  } else {
+    stream_ = [[SCStream alloc] initWithFilter:filter configuration:config delegate:helper_];
+
+    // TODO: crbug.com/327458809 - Choose an appropriate sampleHandlerQueue for
+    // best performance.
+    NSError *add_stream_output_error = nil;
+    dispatch_queue_t queue = dispatch_queue_create("ScreenCaptureKit.Queue", DISPATCH_QUEUE_SERIAL);
+    bool add_stream_output_result = [stream_ addStreamOutput:helper_
+                                                        type:SCStreamOutputTypeScreen
+                                          sampleHandlerQueue:queue
+                                                       error:&add_stream_output_error];
+
+    if (!add_stream_output_result) {
+      stream_ = nil;
+      LOG_ERROR("addStreamOutput failed: {}", NSErrorToString(add_stream_output_error));
+      permanent_error_ = true;
+      return;
+    }
+
+    auto handler = ^(NSError *error) {
+      if (error) {
+        // It should be safe to access `this` here, because the C++ destructor
+        // calls stopCaptureWithCompletionHandler on the stream, which cancels
+        // this handler.
+        permanent_error_ = true;
+        LOG_ERROR("startCaptureWithCompletionHandler failed: {}", NSErrorToString(error));
+      } else {
+        LOG_INFO("Capture started");
+      }
+    };
+
+    [stream_ startCaptureWithCompletionHandler:handler];
+  }
+}
+
+void ScreenCapturerSckImpl::OnNewCVPixelBuffer(CVPixelBufferRef pixelBuffer,
+                                               CFDictionaryRef attachment) {
+  (void)attachment;
+  if (!pixelBuffer) {
+    return;
+  }
+
+  size_t width = CVPixelBufferGetWidth(pixelBuffer);
+  size_t height = CVPixelBufferGetHeight(pixelBuffer);
+  if (width == 0 || height == 0 || CVPixelBufferGetPlaneCount(pixelBuffer) < 2) {
+    LOG_ERROR("Invalid CVPixelBuffer: width={}, height={}, planes={}", width, height,
+              CVPixelBufferGetPlaneCount(pixelBuffer));
+    return;
+  }
+
+  CVReturn status = CVPixelBufferLockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+  if (status != kCVReturnSuccess) {
+    LOG_ERROR("Failed to lock CVPixelBuffer base address: %d", status);
+    return;
+  }
+
+  size_t required_size = width * height * 3 / 2;
+  if (required_size > static_cast<size_t>((std::numeric_limits<int>::max)())) {
+    LOG_ERROR("Captured frame is too large: {} bytes", required_size);
+    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    return;
+  }
+
+  std::lock_guard<std::mutex> lock(lock_);
+  if (!_on_data || !capture_requested_) {
+    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    return;
+  }
+
+  if (!nv12_frame_ || nv12_frame_size_ < required_size) {
+    delete[] nv12_frame_;
+    nv12_frame_ = new unsigned char[required_size];
+    nv12_frame_size_ = required_size;
+  }
+  width_ = static_cast<int>(width);
+  height_ = static_cast<int>(height);
+
+  void *base_y = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0);
+  size_t stride_y = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0);
+
+  void *base_uv = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 1);
+  size_t stride_uv = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 1);
+  if (!base_y || !base_uv || stride_y < width || stride_uv < width) {
+    LOG_ERROR("Invalid CVPixelBuffer planes: base_y={}, base_uv={}, stride_y={}, stride_uv={}",
+              base_y != nullptr, base_uv != nullptr, stride_y, stride_uv);
+    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    return;
+  }
+
+  unsigned char *dst_y = nv12_frame_;
+  for (size_t row = 0; row < height; ++row) {
+    memcpy(dst_y + row * width, static_cast<unsigned char *>(base_y) + row * stride_y, width);
+  }
+
+  unsigned char *dst_uv = nv12_frame_ + width * height;
+  for (size_t row = 0; row < height / 2; ++row) {
+    memcpy(dst_uv + row * width, static_cast<unsigned char *>(base_uv) + row * stride_uv, width);
+  }
+
+  const std::string stream_id = ResolveDisplayStreamId(
+      current_stream_id_.c_str(), display_info_list_.size(),
+      current_monitor_index_);
+  if (stream_id.empty()) {
+    if (!invalid_stream_id_logged_) {
+      LOG_ERROR("Dropping macOS frames without a registered stream id, "
+                "display_id={}",
+                current_display_);
+      invalid_stream_id_logged_ = true;
+    }
+    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    return;
+  }
+  invalid_stream_id_logged_ = false;
+  _on_data(nv12_frame_, static_cast<int>(required_size), static_cast<int>(width),
+           static_cast<int>(height), stream_id.c_str());
+
+  CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+}
+
+void ScreenCapturerSckImpl::StartOrReconfigureCapturer() {
+  if (permanent_error_) {
+    LOG_ERROR("Cannot reconfigure capturer: permanent error occurred");
+    return;
+  }
+
+  if (@available(macOS 10.15, *)) {
+    bool has_permission = CGPreflightScreenCaptureAccess();
+    if (!has_permission) {
+      LOG_ERROR("Screen recording permission not granted");
+      permanent_error_ = true;
+      return;
+    }
+  }
+
+  SckHelper *local_helper = helper_;
+  if (!local_helper) {
+    LOG_ERROR("Cannot reconfigure capturer: helper is null");
+    return;
+  }
+
+  auto handler = ^(SCShareableContent *content, NSError *error) {
+    if (error) {
+      LOG_ERROR("getShareableContent failed: {}", NSErrorToString(error));
+      [local_helper onShareableContentCreated:nil];
+      return;
+    }
+    [local_helper onShareableContentCreated:content];
+  };
+  [SCShareableContent getShareableContentWithCompletionHandler:handler];
+}
+
+@implementation SckHelper {
+  // This lock is to prevent the capturer being destroyed while an instance
+  // method is still running on another thread.
+  std::mutex _capturer_lock;
+  ScreenCapturerSckImpl *_capturer;
+}
+
+- (instancetype)initWithCapturer:(ScreenCapturerSckImpl *)capturer {
+  self = [super init];
+  if (self) {
+    _capturer = capturer;
+  }
+  return self;
+}
+
+- (void)onShareableContentCreated:(SCShareableContent *)content {
+  std::lock_guard<std::mutex> lock(_capturer_lock);
+  if (_capturer) {
+    _capturer->OnShareableContentCreated(content);
+  } else {
+    LOG_ERROR("Invalid capturer");
+  }
+}
+
+- (void)stream:(SCStream *)stream
+    didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
+                   ofType:(SCStreamOutputType)type {
+  CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
+  if (!pixelBuffer) {
+    return;
+  }
+
+  CFRetain(pixelBuffer);
+
+  CFArrayRef attachmentsArray = CMSampleBufferGetSampleAttachmentsArray(sampleBuffer, false);
+  if (!attachmentsArray || CFArrayGetCount(attachmentsArray) == 0) {
+    LOG_ERROR("Discarding frame with no attachments");
+    CFRelease(pixelBuffer);
+    return;
+  }
+
+  CFDictionaryRef attachment =
+      static_cast<CFDictionaryRef>(CFArrayGetValueAtIndex(attachmentsArray, 0));
+
+  std::lock_guard<std::mutex> lock(_capturer_lock);
+  if (_capturer) {
+    _capturer->OnNewCVPixelBuffer(pixelBuffer, attachment);
+  }
+
+  CFRelease(pixelBuffer);
+}
+
+- (void)releaseCapturer {
+  std::lock_guard<std::mutex> lock(_capturer_lock);
+  _capturer = nullptr;
+}
+
+@end
+
+std::unique_ptr<ScreenCapturer> ScreenCapturerSck::CreateScreenCapturerSck() {
+  return std::make_unique<ScreenCapturerSckImpl>();
+}

apps/desktop/src/platform/macos/speaker_capturer/speaker_capturer_factory.cpp

@@ -0,0 +1,11 @@
+#include "speaker_capturer_factory.h"
+
+#include "speaker_capturer_macosx.h"
+
+namespace crossdesk {
+
+SpeakerCapturer* SpeakerCapturerFactory::Create() {
+  return new SpeakerCapturerMacosx();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/macos/speaker_capturer/speaker_capturer_macosx.h

@@ -0,0 +1,39 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2024-08-02
+ * Copyright (c) 2024 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SPEAKER_CAPTURER_MACOSX_H_
+#define _SPEAKER_CAPTURER_MACOSX_H_
+
+#include <thread>
+#include <vector>
+
+#include "speaker_capturer.h"
+
+namespace crossdesk {
+
+class SpeakerCapturerMacosx : public SpeakerCapturer {
+ public:
+  SpeakerCapturerMacosx();
+  ~SpeakerCapturerMacosx();
+
+ public:
+  virtual int Init(speaker_data_cb cb);
+  virtual int Destroy();
+  virtual int Start();
+  virtual int Stop();
+
+  int Pause();
+  int Resume();
+
+ public:
+  speaker_data_cb cb_ = nullptr;
+  bool inited_ = false;
+
+  class Impl;
+  Impl* impl_ = nullptr;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/macos/speaker_capturer/speaker_capturer_macosx.mm

@@ -0,0 +1,308 @@
+#import <AVFoundation/AVFoundation.h>
+#import <Foundation/Foundation.h>
+#import <ScreenCaptureKit/ScreenCaptureKit.h>
+
+#include "rd_log.h"
+#include "speaker_capturer_macosx.h"
+
+namespace crossdesk {
+class SpeakerCapturerMacosx;
+}
+
+namespace {
+std::string NSErrorToString(NSError* error) {
+  if (!error) {
+    return "";
+  }
+
+  const char* description = [error.localizedDescription UTF8String];
+  return description ? description : "";
+}
+}  // namespace
+
+@interface SpeakerCaptureDelegate : NSObject <SCStreamDelegate, SCStreamOutput>
+@property(nonatomic, assign) crossdesk::SpeakerCapturerMacosx* owner;
+- (instancetype)initWithOwner:(crossdesk::SpeakerCapturerMacosx*)owner;
+@end
+
+@implementation SpeakerCaptureDelegate
+- (instancetype)initWithOwner:(crossdesk::SpeakerCapturerMacosx*)owner {
+  self = [super init];
+  if (self) {
+    _owner = owner;
+  }
+  return self;
+}
+
+- (void)stream:(SCStream*)stream
+    didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
+                   ofType:(SCStreamOutputType)type {
+  if (type != SCStreamOutputTypeAudio) return;
+
+  crossdesk::SpeakerCapturerMacosx* owner = _owner;
+  if (!owner || !owner->cb_) {
+    return;
+  }
+
+  CMBlockBufferRef blockBuffer = CMSampleBufferGetDataBuffer(sampleBuffer);
+  if (!blockBuffer) {
+    return;
+  }
+
+  size_t length = CMBlockBufferGetDataLength(blockBuffer);
+  char* dataPtr = NULL;
+  OSStatus dataStatus =
+      CMBlockBufferGetDataPointer(blockBuffer, 0, NULL, NULL, &dataPtr);
+  if (dataStatus != noErr || dataPtr == nullptr || length == 0) {
+    return;
+  }
+
+  CMAudioFormatDescriptionRef formatDesc = CMSampleBufferGetFormatDescription(sampleBuffer);
+  if (!formatDesc) {
+    return;
+  }
+
+  const AudioStreamBasicDescription* asbd =
+      CMAudioFormatDescriptionGetStreamBasicDescription(formatDesc);
+  if (!asbd || asbd->mChannelsPerFrame == 0) {
+    return;
+  }
+
+  if (owner->cb_) {
+    std::vector<short> out_pcm16;
+    if (asbd->mFormatFlags & kAudioFormatFlagIsFloat) {
+      int channels = asbd->mChannelsPerFrame;
+      int samples = (int)(length / sizeof(float));
+      float* floatData = (float*)dataPtr;
+      std::vector<short> pcm16(samples);
+      for (int i = 0; i < samples; ++i) {
+        float v = floatData[i];
+        if (v > 1.0f) v = 1.0f;
+        if (v < -1.0f) v = -1.0f;
+        pcm16[i] = (short)(v * 32767.0f);
+      }
+
+      if (channels > 1) {
+        int mono_samples = samples / channels;
+        out_pcm16.resize(mono_samples);
+        for (int i = 0; i < mono_samples; ++i) {
+          int sum = 0;
+          for (int c = 0; c < channels; ++c) {
+            sum += pcm16[i * channels + c];
+          }
+          out_pcm16[i] = sum / channels;
+        }
+      } else {
+        out_pcm16 = std::move(pcm16);
+      }
+    } else if (asbd->mBitsPerChannel == 16) {
+      int channels = asbd->mChannelsPerFrame;
+      int samples = (int)(length / 2);
+      short* src = (short*)dataPtr;
+      if (channels > 1) {
+        int mono_samples = samples / channels;
+        out_pcm16.resize(mono_samples);
+        for (int i = 0; i < mono_samples; ++i) {
+          int sum = 0;
+          for (int c = 0; c < channels; ++c) {
+            sum += src[i * channels + c];
+          }
+          out_pcm16[i] = sum / channels;
+        }
+      } else {
+        out_pcm16.assign(src, src + samples);
+      }
+    }
+
+    size_t frame_bytes = 960;  // 480 * 2
+    size_t total_bytes = out_pcm16.size() * sizeof(short);
+    unsigned char* p = (unsigned char*)out_pcm16.data();
+    for (size_t offset = 0; offset + frame_bytes <= total_bytes; offset += frame_bytes) {
+      if (!owner->cb_) {
+        return;
+      }
+      owner->cb_(p + offset, frame_bytes, "audio");
+    }
+  }
+}
+
+@end
+
+namespace crossdesk {
+
+class SpeakerCapturerMacosx::Impl {
+ public:
+  SCStreamConfiguration* config = nil;
+  SCStream* stream = nil;
+  SpeakerCaptureDelegate* delegate = nil;
+  dispatch_queue_t queue = nil;
+  SCShareableContent* content = nil;
+  SCDisplay* mainDisplay = nil;
+
+  ~Impl() {
+    if (stream) {
+      [stream stopCaptureWithCompletionHandler:^(NSError* _Nullable error){
+      }];
+      stream = nil;
+    }
+    delegate = nil;
+    if (queue) {
+      queue = nil;
+    }
+    content = nil;
+    mainDisplay = nil;
+    config = nil;
+  }
+};
+
+SpeakerCapturerMacosx::SpeakerCapturerMacosx() {
+  impl_ = new Impl();
+  inited_ = false;
+  cb_ = nullptr;
+}
+
+SpeakerCapturerMacosx::~SpeakerCapturerMacosx() {
+  Destroy();
+  delete impl_;
+  impl_ = nullptr;
+}
+
+int SpeakerCapturerMacosx::Init(speaker_data_cb cb) {
+  if (inited_) {
+    return 0;
+  }
+  cb_ = cb;
+
+  impl_->config = [[SCStreamConfiguration alloc] init];
+  impl_->config.capturesAudio = YES;
+  impl_->config.sampleRate = 48000;
+  impl_->config.channelCount = 1;
+
+  dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+  __block NSError* error = nil;
+  [SCShareableContent
+      getShareableContentWithCompletionHandler:^(SCShareableContent* c, NSError* e) {
+        impl_->content = c;
+        error = e;
+        dispatch_semaphore_signal(sema);
+      }];
+  dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
+
+  if (error || !impl_->content) {
+    LOG_ERROR("Failed to get shareable content: {}",
+              NSErrorToString(error));
+    return -1;
+  }
+
+  CGDirectDisplayID mainDisplayId = CGMainDisplayID();
+  impl_->mainDisplay = nil;
+  for (SCDisplay* d in impl_->content.displays) {
+    if (d.displayID == mainDisplayId) {
+      impl_->mainDisplay = d;
+      break;
+    }
+  }
+  if (!impl_->mainDisplay) {
+    LOG_ERROR("Main display not found");
+    return -1;
+  }
+
+  if (!impl_->queue) {
+    impl_->queue = dispatch_queue_create("SpeakerAudio.Queue", DISPATCH_QUEUE_SERIAL);
+  }
+
+  inited_ = true;
+  return 0;
+}
+
+int SpeakerCapturerMacosx::Start() {
+  if (!inited_) {
+    return -1;
+  }
+
+  if (impl_->stream) {
+    dispatch_semaphore_t semaStop = dispatch_semaphore_create(0);
+    [impl_->stream stopCaptureWithCompletionHandler:^(NSError* error) {
+      dispatch_semaphore_signal(semaStop);
+    }];
+    dispatch_semaphore_wait(semaStop, DISPATCH_TIME_FOREVER);
+    impl_->stream = nil;
+    impl_->delegate = nil;
+  }
+
+  impl_->delegate = [[SpeakerCaptureDelegate alloc] initWithOwner:this];
+  SCContentFilter* filter = [[SCContentFilter alloc] initWithDisplay:impl_->mainDisplay
+                                                    excludingWindows:@[]];
+  impl_->stream = [[SCStream alloc] initWithFilter:filter
+                                     configuration:impl_->config
+                                          delegate:impl_->delegate];
+
+  NSError* addOutputError = nil;
+  BOOL ok = [impl_->stream addStreamOutput:impl_->delegate
+                                      type:SCStreamOutputTypeAudio
+                        sampleHandlerQueue:impl_->queue
+                                     error:&addOutputError];
+  if (!ok || addOutputError) {
+    LOG_ERROR("addStreamOutput error: {}",
+              NSErrorToString(addOutputError));
+    impl_->stream = nil;
+    impl_->delegate = nil;
+    return -1;
+  }
+
+  dispatch_semaphore_t semaStart = dispatch_semaphore_create(0);
+  __block int ret = 0;
+  [impl_->stream startCaptureWithCompletionHandler:^(NSError* _Nullable error) {
+    if (error) {
+      LOG_ERROR("startCaptureWithCompletionHandler error: {}",
+                NSErrorToString(error));
+      ret = -1;
+    }
+    dispatch_semaphore_signal(semaStart);
+  }];
+  dispatch_semaphore_wait(semaStart, DISPATCH_TIME_FOREVER);
+
+  return ret;
+}
+
+int SpeakerCapturerMacosx::Stop() {
+  if (!inited_) return -1;
+  if (!impl_->stream) return -1;
+
+  dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+  [impl_->stream stopCaptureWithCompletionHandler:^(NSError* error) {
+    if (error) {
+      LOG_ERROR("stopCaptureWithCompletionHandler error: {}",
+                NSErrorToString(error));
+    }
+    dispatch_semaphore_signal(sema);
+  }];
+  dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
+
+  impl_->stream = nil;
+  impl_->delegate.owner = nullptr;
+  impl_->delegate = nil;
+
+  return 0;
+}
+
+int SpeakerCapturerMacosx::Destroy() {
+  Stop();
+  cb_ = nullptr;
+
+  if (impl_) {
+    impl_->config = nil;
+    impl_->content = nil;
+    impl_->mainDisplay = nil;
+    if (impl_->queue) {
+      impl_->queue = nil;
+    }
+  }
+  inited_ = false;
+  return 0;
+}
+
+int SpeakerCapturerMacosx::Pause() { return 0; }
+
+int SpeakerCapturerMacosx::Resume() { return Start(); }
+}  // namespace crossdesk

apps/desktop/src/platform/macos/system_info.cpp

@@ -0,0 +1,55 @@
+#include "platform.h"
+
+#include <ifaddrs.h>
+#include <net/if_dl.h>
+#include <net/if_types.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <cstdio>
+#include <cstring>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+std::string GetMac() {
+  struct ifaddrs* addresses = nullptr;
+  if (getifaddrs(&addresses) != 0) return {};
+
+  std::string result;
+  for (struct ifaddrs* cursor = addresses; cursor; cursor = cursor->ifa_next) {
+    if (!cursor->ifa_addr || cursor->ifa_addr->sa_family != AF_LINK ||
+        std::strcmp(cursor->ifa_name, "en0") != 0) {
+      continue;
+    }
+    const auto* link =
+        reinterpret_cast<const struct sockaddr_dl*>(cursor->ifa_addr);
+    if (link->sdl_type != IFT_ETHER) continue;
+    const auto* bytes = reinterpret_cast<const unsigned char*>(
+        &link->sdl_data[link->sdl_nlen]);
+    char address[16] = {};
+    int length = 0;
+    for (int index = 0; index < link->sdl_alen; ++index) {
+      length += std::snprintf(address + length, sizeof(address) - length,
+                              "%.2X", bytes[index]);
+    }
+    result = address;
+    break;
+  }
+  freeifaddrs(addresses);
+  return result;
+}
+
+std::string GetHostName() {
+  char hostname[256] = {};
+  if (gethostname(hostname, sizeof(hostname)) == -1) {
+    LOG_ERROR("gethostname failed");
+    return {};
+  }
+  return hostname;
+}
+
+bool IsWaylandSession() { return false; }
+
+}  // namespace crossdesk

apps/desktop/src/platform/path_backend.h

@@ -0,0 +1,16 @@
+#ifndef CROSSDESK_PLATFORM_PATH_BACKEND_H_
+#define CROSSDESK_PLATFORM_PATH_BACKEND_H_
+
+#include <filesystem>
+#include <string>
+
+namespace crossdesk::platform {
+
+std::filesystem::path GetExecutableDirectory();
+std::filesystem::path GetConfigPath(const std::string& app_name);
+std::filesystem::path GetCachePath(const std::string& app_name);
+std::filesystem::path GetLogPath(const std::string& app_name);
+
+}  // namespace crossdesk::platform
+
+#endif  // CROSSDESK_PLATFORM_PATH_BACKEND_H_

apps/desktop/src/platform/video_renderer.h

@@ -0,0 +1,70 @@
+#ifndef CROSSDESK_GUI_PLATFORM_VIDEO_RENDERER_H_
+#define CROSSDESK_GUI_PLATFORM_VIDEO_RENDERER_H_
+
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace crossdesk {
+
+// Platform-independent contract for the native stream video renderer.
+//
+// Frame submission and snapshot methods may be called from MiniRTC callback
+// threads. Surface setup, rendering and teardown remain backend-specific and
+// are driven by the Slint presentation module on the UI thread.
+class VideoRenderer {
+public:
+  enum class SubmitResult {
+    submitted,
+    not_selected,
+    dropped,
+    failed,
+  };
+
+  enum class RenderResult {
+    rendered,
+    idle,
+    empty,
+    failed,
+  };
+
+  struct RenderOutcome {
+    RenderResult result = RenderResult::failed;
+    int width = 0;
+    int height = 0;
+    uint64_t sequence = 0;
+  };
+
+  virtual ~VideoRenderer() = default;
+
+  virtual bool IsReady() const = 0;
+
+  // True only while the renderer can accept and present native frames. Metal
+  // additionally requires attachment to an AppKit view; OpenGL requires an
+  // active Slint rendering context.
+  virtual bool IsActive() const = 0;
+
+  virtual bool SetSelectedStream(std::string remote_id) = 0;
+  virtual void DiscardStream(std::string_view remote_id) = 0;
+
+  virtual SubmitResult SubmitNv12(std::string_view remote_id,
+                                  const uint8_t* data, size_t size, int width,
+                                  int height) = 0;
+  virtual SubmitResult SubmitCachedNv12(std::string_view remote_id,
+                                        const uint8_t* data, size_t size,
+                                        int width, int height) = 0;
+
+  virtual bool CopyLatestNv12(std::string_view remote_id,
+                              std::vector<unsigned char>* output, int* width,
+                              int* height) const = 0;
+};
+
+// Exactly one factory implementation is linked for the target platform.
+std::unique_ptr<VideoRenderer> CreateVideoRenderer();
+
+}  // namespace crossdesk
+
+#endif  // CROSSDESK_GUI_PLATFORM_VIDEO_RENDERER_H_

apps/desktop/src/platform/window_drag.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <string>
+
+namespace crossdesk {
+
+// Starts the platform's native move loop for the window receiving the current
+// left-mouse-down event. Returns false when no suitable native event exists.
+bool StartNativeWindowDrag();
+
+// Hides the disabled native zoom button on CrossDesk's fixed-size main
+// window. Returns true once the matching AppKit window has been configured.
+bool HideDisabledMainWindowZoomButton();
+
+// Configures live resize and replaces the stream window's native Space
+// fullscreen action with an immediate, single-window fullscreen transition.
+// |slint_view| is the current stream window's AppKit NSView*. Passing the
+// identity explicitly prevents a closing window with the same title from
+// being selected during a later connection.
+bool ConfigureStreamWindowLiveResize(void* slint_view);
+
+// Drops the native stream-window reference if it belongs to |slint_view|.
+// This must run before the corresponding Slint component is destroyed.
+void UnregisterStreamWindow(void* slint_view);
+
+// Returns whether the configured stream window is currently the active AppKit
+// key window.
+bool IsStreamWindowActive();
+
+// Enters or leaves the stream window's animation-free fullscreen mode.
+bool SetStreamWindowFullscreen(bool fullscreen);
+bool IsStreamWindowFullscreen();
+
+// Opens an application-modal macOS file picker. The panel is made key before
+// entering its modal loop so it receives keyboard input immediately.
+std::string OpenNativeFileDialog(const std::string &title);
+
+} // namespace crossdesk

apps/desktop/src/platform/windows/autostart.cpp

@@ -0,0 +1,69 @@
+#include "platform/autostart_backend.h"
+
+#include <windows.h>
+
+#include <filesystem>
+#include <string>
+
+namespace crossdesk::platform {
+namespace {
+
+constexpr const char* kRunKey =
+    "Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+
+}  // namespace
+
+std::string GetAutostartExecutablePath() {
+  char path[32768] = {};
+  const DWORD length = GetModuleFileNameA(nullptr, path, sizeof(path));
+  return length > 0 && length < sizeof(path) ? std::string(path, length)
+                                             : std::string();
+}
+
+bool EnableAutostart(const std::string& app_name,
+                     const std::string& executable_path) {
+  if (!std::filesystem::exists(executable_path)) return false;
+
+  HKEY key = nullptr;
+  if (RegOpenKeyExA(HKEY_CURRENT_USER, kRunKey, 0, KEY_WRITE, &key) !=
+      ERROR_SUCCESS) {
+    return false;
+  }
+
+  std::string value = executable_path;
+  if (value.find(' ') != std::string::npos &&
+      (value.front() != '"' || value.back() != '"')) {
+    value = "\"" + value + "\"";
+  }
+  const LONG result = RegSetValueExA(
+      key, app_name.c_str(), 0, REG_SZ,
+      reinterpret_cast<const BYTE*>(value.c_str()),
+      static_cast<DWORD>(value.size() + 1));
+  RegCloseKey(key);
+  return result == ERROR_SUCCESS;
+}
+
+bool DisableAutostart(const std::string& app_name) {
+  HKEY key = nullptr;
+  if (RegOpenKeyExA(HKEY_CURRENT_USER, kRunKey, 0, KEY_WRITE, &key) !=
+      ERROR_SUCCESS) {
+    return false;
+  }
+  const LONG result = RegDeleteValueA(key, app_name.c_str());
+  RegCloseKey(key);
+  return result == ERROR_SUCCESS || result == ERROR_FILE_NOT_FOUND;
+}
+
+bool IsAutostartEnabled(const std::string& app_name) {
+  HKEY key = nullptr;
+  if (RegOpenKeyExA(HKEY_CURRENT_USER, kRunKey, 0, KEY_READ, &key) !=
+      ERROR_SUCCESS) {
+    return false;
+  }
+  const LONG result =
+      RegQueryValueExA(key, app_name.c_str(), nullptr, nullptr, nullptr, nullptr);
+  RegCloseKey(key);
+  return result == ERROR_SUCCESS;
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/windows/clipboard.cpp

@@ -0,0 +1,139 @@
+#include "clipboard.h"
+
+#include <windows.h>
+
+#include <string>
+
+#include "platform/clipboard_backend.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+namespace {
+
+HWND g_clipboard_window = nullptr;
+constexpr const char* kClipboardWindowClass = "CrossDeskClipboardMonitor";
+
+LRESULT CALLBACK ClipboardWindowProc(HWND window, UINT message, WPARAM wparam,
+                                     LPARAM lparam) {
+  if (message == WM_CLIPBOARDUPDATE) {
+    platform::HandleClipboardChange();
+    return 0;
+  }
+  return DefWindowProc(window, message, wparam, lparam);
+}
+
+}  // namespace
+
+std::string Clipboard::GetText() {
+  if (!OpenClipboard(nullptr)) {
+    LOG_ERROR("Clipboard::GetText: failed to open clipboard");
+    return {};
+  }
+
+  std::string result;
+  HANDLE data = GetClipboardData(CF_UNICODETEXT);
+  if (data) {
+    const wchar_t* text = static_cast<const wchar_t*>(GlobalLock(data));
+    if (text) {
+      const int size =
+          WideCharToMultiByte(CP_UTF8, 0, text, -1, nullptr, 0, nullptr, nullptr);
+      if (size > 1) {
+        result.resize(static_cast<size_t>(size));
+        WideCharToMultiByte(CP_UTF8, 0, text, -1, result.data(), size,
+                            nullptr, nullptr);
+        result.resize(static_cast<size_t>(size - 1));
+      }
+      GlobalUnlock(data);
+    }
+  }
+  CloseClipboard();
+  return result;
+}
+
+bool Clipboard::SetText(const std::string& text) {
+  if (!OpenClipboard(nullptr)) {
+    LOG_ERROR("Clipboard::SetText: failed to open clipboard");
+    return false;
+  }
+  if (!EmptyClipboard()) {
+    LOG_ERROR("Clipboard::SetText: failed to empty clipboard");
+    CloseClipboard();
+    return false;
+  }
+
+  const int size =
+      MultiByteToWideChar(CP_UTF8, 0, text.c_str(), -1, nullptr, 0);
+  HGLOBAL memory =
+      size > 0 ? GlobalAlloc(GMEM_MOVEABLE, size * sizeof(wchar_t)) : nullptr;
+  if (!memory) {
+    LOG_ERROR("Clipboard::SetText: failed to allocate memory");
+    CloseClipboard();
+    return false;
+  }
+
+  wchar_t* output = static_cast<wchar_t*>(GlobalLock(memory));
+  if (!output) {
+    GlobalFree(memory);
+    CloseClipboard();
+    return false;
+  }
+  MultiByteToWideChar(CP_UTF8, 0, text.c_str(), -1, output, size);
+  GlobalUnlock(memory);
+  if (!SetClipboardData(CF_UNICODETEXT, memory)) {
+    GlobalFree(memory);
+    CloseClipboard();
+    return false;
+  }
+  CloseClipboard();
+  return true;
+}
+
+bool Clipboard::HasText() {
+  if (!OpenClipboard(nullptr)) return false;
+  const bool result = IsClipboardFormatAvailable(CF_UNICODETEXT) ||
+                      IsClipboardFormatAvailable(CF_TEXT);
+  CloseClipboard();
+  return result;
+}
+
+namespace platform {
+
+void RunClipboardMonitor(int) {
+  WNDCLASSA window_class = {};
+  window_class.lpfnWndProc = ClipboardWindowProc;
+  window_class.hInstance = GetModuleHandle(nullptr);
+  window_class.lpszClassName = kClipboardWindowClass;
+  RegisterClassA(&window_class);
+
+  g_clipboard_window = CreateWindowA(
+      kClipboardWindowClass, nullptr, 0, 0, 0, 0, 0, HWND_MESSAGE, nullptr,
+      nullptr, nullptr);
+  if (!g_clipboard_window ||
+      !AddClipboardFormatListener(g_clipboard_window)) {
+    LOG_ERROR("Failed to initialize clipboard monitor window");
+    if (g_clipboard_window) DestroyWindow(g_clipboard_window);
+    g_clipboard_window = nullptr;
+    return;
+  }
+
+  LOG_INFO("Clipboard event monitoring started (Windows)");
+  MSG message = {};
+  while (ClipboardMonitoring()) {
+    const BOOL result = GetMessage(&message, nullptr, 0, 0);
+    if (result == 0 || result == -1) break;
+    TranslateMessage(&message);
+    DispatchMessage(&message);
+  }
+
+  RemoveClipboardFormatListener(g_clipboard_window);
+  DestroyWindow(g_clipboard_window);
+  g_clipboard_window = nullptr;
+  UnregisterClassA(kClipboardWindowClass, GetModuleHandle(nullptr));
+}
+
+void WakeClipboardMonitor() {
+  if (g_clipboard_window) PostMessage(g_clipboard_window, WM_QUIT, 0, 0);
+}
+
+}  // namespace platform
+}  // namespace crossdesk

apps/desktop/src/platform/windows/daemon_backend.cpp

@@ -0,0 +1,64 @@
+#include "platform/daemon_backend.h"
+
+#include <windows.h>
+
+#include <atomic>
+#include <chrono>
+#include <thread>
+#include <vector>
+
+namespace crossdesk::platform {
+namespace {
+
+std::atomic<bool> g_stop_requested{false};
+
+}  // namespace
+
+void ResetDaemonStop() { g_stop_requested.store(false); }
+
+void RequestDaemonStop() { g_stop_requested.store(true); }
+
+bool DaemonStopRequested() { return g_stop_requested.load(); }
+
+bool PrepareDaemon() { return true; }
+
+std::string GetDaemonExecutablePath() {
+  char path[32768] = {};
+  const DWORD length = GetModuleFileNameA(nullptr, path, sizeof(path));
+  return length > 0 && length < sizeof(path) ? std::string(path, length)
+                                             : std::string();
+}
+
+DaemonChildResult RunDaemonChild(const std::string& executable_path,
+                                 const std::function<bool()>& keep_running) {
+  DaemonChildResult result;
+  STARTUPINFOA startup = {sizeof(startup)};
+  PROCESS_INFORMATION process = {};
+  std::string command = "\"" + executable_path + "\" --child";
+  std::vector<char> command_buffer(command.begin(), command.end());
+  command_buffer.push_back('\0');
+  if (!CreateProcessA(nullptr, command_buffer.data(), nullptr, nullptr, FALSE,
+                      0, nullptr, nullptr, &startup, &process)) {
+    return result;
+  }
+
+  result.started = true;
+  while (keep_running()) {
+    const DWORD wait_result = WaitForSingleObject(process.hProcess, 200);
+    if (wait_result == WAIT_OBJECT_0 || wait_result == WAIT_FAILED) break;
+  }
+  if (!keep_running()) {
+    TerminateProcess(process.hProcess, 1);
+    WaitForSingleObject(process.hProcess, 3000);
+  }
+
+  DWORD exit_code = 0;
+  GetExitCodeProcess(process.hProcess, &exit_code);
+  result.exit_code = static_cast<int>(exit_code);
+  result.normal_exit = exit_code == 0;
+  CloseHandle(process.hProcess);
+  CloseHandle(process.hThread);
+  return result;
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/windows/gui/application/portable_service_integration.cpp

@@ -0,0 +1,144 @@
+#include "application/gui_application.h"
+
+#if _WIN32 && CROSSDESK_PORTABLE
+
+#include <Windows.h>
+#include <shellapi.h>
+
+#include <filesystem>
+#include <vector>
+
+#include "rd_log.h"
+#include "service_host.h"
+
+namespace crossdesk {
+namespace {
+
+std::filesystem::path GetCurrentExecutablePath() {
+  std::vector<wchar_t> buffer(MAX_PATH);
+  while (true) {
+    const DWORD length = GetModuleFileNameW(
+        nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
+    if (length == 0) {
+      return {};
+    }
+    if (length < buffer.size()) {
+      return std::filesystem::path(buffer.data(), buffer.data() + length);
+    }
+    if (buffer.size() >= 32768) {
+      return {};
+    }
+    buffer.resize(buffer.size() * 2);
+  }
+}
+
+bool InstallServiceWithElevation() {
+  const std::filesystem::path executable_path = GetCurrentExecutablePath();
+  if (executable_path.empty()) {
+    LOG_ERROR("Portable service install failed: current executable not found");
+    return false;
+  }
+
+  const std::filesystem::path service_path =
+      executable_path.parent_path() / L"crossdesk_service.exe";
+  const std::filesystem::path helper_path =
+      executable_path.parent_path() / L"crossdesk_session_helper.exe";
+  if (!std::filesystem::exists(service_path) ||
+      !std::filesystem::exists(helper_path)) {
+    LOG_ERROR("Portable service install failed: service binaries missing, "
+              "service={}, helper={}",
+              service_path.string(), helper_path.string());
+    return false;
+  }
+
+  const std::wstring executable = executable_path.wstring();
+  const std::wstring working_dir = executable_path.parent_path().wstring();
+  constexpr wchar_t parameters[] = L"--service-install";
+
+  SHELLEXECUTEINFOW execute_info{};
+  execute_info.cbSize = sizeof(execute_info);
+  execute_info.fMask = SEE_MASK_NOCLOSEPROCESS;
+  execute_info.lpVerb = L"runas";
+  execute_info.lpFile = executable.c_str();
+  execute_info.lpParameters = parameters;
+  execute_info.lpDirectory = working_dir.c_str();
+  execute_info.nShow = SW_HIDE;
+
+  if (!ShellExecuteExW(&execute_info)) {
+    LOG_ERROR("Portable service install failed: ShellExecuteExW error={}",
+              GetLastError());
+    return false;
+  }
+
+  const DWORD wait_result =
+      WaitForSingleObject(execute_info.hProcess, INFINITE);
+  DWORD exit_code = 1;
+  if (wait_result == WAIT_OBJECT_0) {
+    GetExitCodeProcess(execute_info.hProcess, &exit_code);
+  } else {
+    LOG_ERROR("Portable service install wait failed, result={}", wait_result);
+  }
+  CloseHandle(execute_info.hProcess);
+
+  if (exit_code != 0) {
+    LOG_ERROR("Portable service install command failed, exit_code={}",
+              exit_code);
+    return false;
+  }
+
+  const bool started = StartCrossDeskService();
+  if (!started) {
+    LOG_WARN("Portable service installed but start failed");
+  }
+  return IsCrossDeskServiceInstalled() && started;
+}
+
+} // namespace
+
+void GuiApplication::CheckPortableWindowsService() {
+  if (portable_service_prompt_checked_) {
+    return;
+  }
+  portable_service_prompt_checked_ = true;
+  portable_service_installed_ = IsCrossDeskServiceInstalled();
+  if (portable_service_installed_ || portable_service_prompt_suppressed_) {
+    return;
+  }
+
+  portable_service_install_state_.store(PortableServiceInstallState::idle,
+                                        std::memory_order_relaxed);
+  show_portable_service_install_window_ = true;
+}
+
+void GuiApplication::StartPortableWindowsServiceInstall() {
+  portable_service_do_not_remind_ = false;
+  PortableServiceInstallState expected = PortableServiceInstallState::idle;
+  if (!portable_service_install_state_.compare_exchange_strong(
+          expected, PortableServiceInstallState::installing,
+          std::memory_order_acq_rel)) {
+    if (expected != PortableServiceInstallState::failed) {
+      return;
+    }
+    portable_service_install_state_.store(
+        PortableServiceInstallState::installing, std::memory_order_release);
+  }
+
+  JoinPortableWindowsServiceInstallThread();
+  portable_service_install_thread_ = std::thread([this]() {
+    const bool installed = InstallServiceWithElevation();
+    portable_service_install_state_.store(
+        installed ? PortableServiceInstallState::succeeded
+                  : PortableServiceInstallState::failed,
+        std::memory_order_release);
+  });
+}
+
+void GuiApplication::JoinPortableWindowsServiceInstallThread() {
+  if (portable_service_install_thread_.joinable()) {
+    portable_service_install_thread_.join();
+  }
+}
+
+} // namespace crossdesk
+
+#endif

apps/desktop/src/platform/windows/gui/runtime/windows_service_runtime.cpp

@@ -0,0 +1,231 @@
+#include "runtime/gui_runtime.h"
+
+#include <remote_action.h>
+
+#include <algorithm>
+#include <cstring>
+#include <shared_mutex>
+#include <string>
+
+#include "rd_log.h"
+
+#if _WIN32
+#include "interactive_state.h"
+#include "service_host.h"
+#endif
+
+namespace crossdesk {
+namespace {
+#if _WIN32
+struct WindowsServiceInteractiveStatus {
+  bool available = false;
+  bool sas_secure_desktop_grace_active = false;
+  unsigned int error_code = 0;
+  std::string interactive_stage;
+  std::string error;
+};
+
+constexpr uint32_t kWindowsServiceStatusIntervalMs = 1000;
+constexpr uint32_t kWindowsServiceSasSecureDesktopGraceMs = 2000;
+constexpr DWORD kWindowsServiceQueryTimeoutMs = 500;
+constexpr DWORD kWindowsServiceSasTimeoutMs = 500;
+
+bool IsTransientWindowsServiceStatusError(const std::string &error) {
+  return error == "pipe_unavailable" || error == "pipe_connect_failed" ||
+         error == "pipe_read_failed";
+}
+
+RemoteAction
+BuildWindowsServiceStatusAction(const WindowsServiceInteractiveStatus &status) {
+  RemoteAction action{};
+  action.type = ControlType::service_status;
+  action.ss.available = status.available;
+  std::strncpy(action.ss.interactive_stage, status.interactive_stage.c_str(),
+               sizeof(action.ss.interactive_stage) - 1);
+  action.ss.interactive_stage[sizeof(action.ss.interactive_stage) - 1] = '\0';
+  return action;
+}
+
+bool QueryWindowsServiceInteractiveStatus(
+    WindowsServiceInteractiveStatus *status) {
+  if (status == nullptr) {
+    return false;
+  }
+
+  *status = WindowsServiceInteractiveStatus{};
+  const std::string response =
+      QueryCrossDeskService("status", kWindowsServiceQueryTimeoutMs);
+  auto json = nlohmann::json::parse(response, nullptr, false);
+  if (json.is_discarded() || !json.is_object()) {
+    status->error = "invalid_service_status_json";
+    return false;
+  }
+
+  status->available = json.value("ok", false);
+  if (!status->available) {
+    status->error = json.value("error", std::string("service_unavailable"));
+    status->error_code = json.value("code", 0u);
+    return true;
+  }
+
+  status->interactive_stage = json.value("interactive_stage", std::string());
+  status->sas_secure_desktop_grace_active =
+      json.value("sas_secure_desktop_grace_active", false);
+
+  if (ShouldNormalizeUnlockToUserDesktop(
+          json.value("interactive_lock_screen_visible", false),
+          status->interactive_stage, json.value("session_locked", false),
+          json.value("interactive_logon_ui_visible", false),
+          json.value("interactive_secure_desktop_active",
+                     json.value("secure_desktop_active", false)),
+          json.value("credential_ui_visible", false),
+          json.value("password_box_visible", false),
+          json.value("unlock_ui_visible", false),
+          json.value("last_session_event", std::string()))) {
+    status->interactive_stage = "user-desktop";
+  }
+  return true;
+}
+#endif
+} // namespace
+
+void GuiRuntime::HandleWindowsServiceIntegration() {
+#if _WIN32
+  static bool last_logged_service_available = true;
+  static unsigned int last_logged_service_error_code = 0;
+  static std::string last_logged_service_error;
+
+  if (!is_server_mode_ || peer_ == nullptr) {
+    ResetLocalWindowsServiceState(true);
+    return;
+  }
+
+  const bool has_connected_remote = [&] {
+    std::shared_lock lock(connection_status_mutex_);
+    return std::any_of(connection_status_.begin(), connection_status_.end(),
+                       [](const auto &entry) {
+                         return entry.second == ConnectionStatus::Connected;
+                       });
+  }();
+  if (!has_connected_remote) {
+    ResetLocalWindowsServiceState(false);
+    return;
+  }
+
+  bool force_broadcast = false;
+  if (pending_windows_service_sas_.exchange(false, std::memory_order_relaxed)) {
+    const std::string response =
+        QueryCrossDeskService("sas", kWindowsServiceSasTimeoutMs);
+    auto json = nlohmann::json::parse(response, nullptr, false);
+    if (json.is_discarded() || !json.value("ok", false)) {
+      LOG_WARN("Remote SAS request failed: {}", response);
+    } else {
+      LOG_INFO("Remote SAS request forwarded to local Windows service");
+      optimistic_windows_secure_desktop_until_tick_ =
+          static_cast<uint32_t>(SDL_GetTicks()) +
+          kWindowsServiceSasSecureDesktopGraceMs;
+      local_service_status_received_ = true;
+      local_service_available_ = true;
+      local_interactive_stage_ = "secure-desktop";
+    }
+    last_windows_service_status_tick_ = 0;
+    force_broadcast = true;
+  }
+
+  const uint32_t now = static_cast<uint32_t>(SDL_GetTicks());
+  if (!force_broadcast && last_windows_service_status_tick_ != 0 &&
+      now - last_windows_service_status_tick_ <
+          kWindowsServiceStatusIntervalMs) {
+    return;
+  }
+  last_windows_service_status_tick_ = now;
+
+  WindowsServiceInteractiveStatus status;
+  const bool status_ok = QueryWindowsServiceInteractiveStatus(&status);
+  WindowsServiceInteractiveStatus broadcast_status = status;
+  const bool previous_secure_desktop_interaction =
+      IsSecureDesktopInteractionRequired(local_interactive_stage_);
+  const bool optimistic_secure_desktop_active =
+      optimistic_windows_secure_desktop_until_tick_ != 0 &&
+      static_cast<int32_t>(optimistic_windows_secure_desktop_until_tick_ -
+                           now) > 0;
+  const bool keep_optimistic_secure_desktop =
+      status_ok && status.available && optimistic_secure_desktop_active &&
+      status.sas_secure_desktop_grace_active &&
+      status.interactive_stage == "user-desktop";
+  local_service_status_received_ =
+      status_ok || previous_secure_desktop_interaction;
+  local_service_available_ = status.available;
+  if (status.available) {
+    if (keep_optimistic_secure_desktop) {
+      local_interactive_stage_ = "secure-desktop";
+      broadcast_status.interactive_stage = local_interactive_stage_;
+    } else {
+      local_interactive_stage_ = status.interactive_stage;
+      optimistic_windows_secure_desktop_until_tick_ = 0;
+    }
+  } else if (!previous_secure_desktop_interaction) {
+    local_interactive_stage_.clear();
+    optimistic_windows_secure_desktop_until_tick_ = 0;
+  }
+
+  if (status_ok) {
+    const bool availability_changed =
+        status.available != last_logged_service_available;
+    const bool error_changed =
+        !status.available &&
+        (status.error != last_logged_service_error ||
+         status.error_code != last_logged_service_error_code);
+    if (availability_changed || error_changed) {
+      if (status.available) {
+        LOG_INFO(
+            "Local Windows service available for secure desktop integration");
+      } else if (IsTransientWindowsServiceStatusError(status.error)) {
+        LOG_INFO("Local Windows service temporarily unavailable, keeping last "
+                 "secure desktop state: error={}, code={}",
+                 status.error, status.error_code);
+      } else {
+        LOG_WARN(
+            "Local Windows service unavailable, secure desktop integration "
+            "disabled: error={}, code={}",
+            status.error, status.error_code);
+      }
+      last_logged_service_available = status.available;
+      last_logged_service_error = status.error;
+      last_logged_service_error_code = status.error_code;
+    }
+  } else if (last_logged_service_available ||
+             last_logged_service_error != "invalid_service_status_json") {
+    LOG_WARN(
+        "Local Windows service status query failed, secure desktop integration "
+        "disabled");
+    last_logged_service_available = false;
+    last_logged_service_error = "invalid_service_status_json";
+    last_logged_service_error_code = 0;
+  }
+
+  RemoteAction remote_action =
+      BuildWindowsServiceStatusAction(broadcast_status);
+  std::string msg = remote_action.to_json();
+  int ret = SendReliableDataFrame(peer_, msg.data(), msg.size(),
+                                  control_data_label_.c_str());
+  if (ret != 0) {
+    LOG_WARN("Broadcast Windows service status failed, ret={}", ret);
+  }
+#endif
+}
+
+#if _WIN32
+void GuiRuntime::ResetLocalWindowsServiceState(bool clear_pending_sas) {
+  last_windows_service_status_tick_ = 0;
+  if (clear_pending_sas) {
+    pending_windows_service_sas_.store(false, std::memory_order_relaxed);
+  }
+  local_service_status_received_ = false;
+  local_service_available_ = false;
+  local_interactive_stage_.clear();
+  optimistic_windows_secure_desktop_until_tick_ = 0;
+}
+#endif
+
+} // namespace crossdesk

apps/desktop/src/platform/windows/gui/tray/win_tray.cpp

@@ -0,0 +1,169 @@
+#include "win_tray.h"
+
+#include <SDL3/SDL.h>
+
+#include "localization.h"
+
+#include <utility>
+
+namespace crossdesk {
+
+// callback for the message-only window that handles tray icon messages
+static LRESULT CALLBACK MsgWndProc(HWND hwnd, UINT msg, WPARAM wParam,
+                                   LPARAM lParam) {
+  WinTray* tray =
+      reinterpret_cast<WinTray*>(GetWindowLongPtr(hwnd, GWLP_USERDATA));
+  if (!tray) {
+    return DefWindowProc(hwnd, msg, wParam, lParam);
+  }
+
+  if (msg == WM_TRAY_CALLBACK) {
+    MSG tmpMsg = {};
+    tmpMsg.message = msg;
+    tmpMsg.wParam = wParam;
+    tmpMsg.lParam = lParam;
+    tray->HandleTrayMessage(&tmpMsg);
+    return 0;
+  }
+
+  return DefWindowProc(hwnd, msg, wParam, lParam);
+}
+
+WinTray::WinTray(HWND app_hwnd, HICON icon, const std::wstring& tooltip,
+                 int language_index)
+    : app_hwnd_(app_hwnd),
+      icon_(icon),
+      tip_(tooltip),
+      hwnd_message_only_(nullptr),
+      language_index_(language_index) {
+  WNDCLASS wc = {};
+  wc.lpfnWndProc = MsgWndProc;
+  wc.hInstance = GetModuleHandle(nullptr);
+  wc.lpszClassName = L"TrayMessageWindow";
+  RegisterClass(&wc);
+
+  // create a message-only window to receive tray messages
+  hwnd_message_only_ =
+      CreateWindowEx(0, wc.lpszClassName, L"TrayMsg", 0, 0, 0, 0, 0,
+                     HWND_MESSAGE, nullptr, wc.hInstance, nullptr);
+
+  // store pointer to this WinTray instance in window data
+  SetWindowLongPtr(hwnd_message_only_, GWLP_USERDATA,
+                   reinterpret_cast<LONG_PTR>(this));
+
+  // initialize NOTIFYICONDATA structure
+  ZeroMemory(&nid_, sizeof(nid_));
+  nid_.cbSize = sizeof(nid_);
+  nid_.hWnd = hwnd_message_only_;
+  nid_.uID = 1;
+  nid_.uFlags = NIF_ICON | NIF_MESSAGE | NIF_TIP;
+  nid_.uCallbackMessage = WM_TRAY_CALLBACK;
+  nid_.hIcon = icon_;
+  wcsncpy_s(nid_.szTip, tip_.c_str(), _TRUNCATE);
+}
+
+WinTray::WinTray(std::function<void()> show_window,
+                 std::function<void()> hide_window,
+                 std::function<void()> open_settings,
+                 std::function<void()> exit_app, HICON icon,
+                 const std::wstring& tooltip, int language_index)
+    : WinTray(nullptr, icon, tooltip, language_index) {
+  show_window_ = std::move(show_window);
+  hide_window_ = std::move(hide_window);
+  open_settings_ = std::move(open_settings);
+  exit_app_ = std::move(exit_app);
+}
+
+WinTray::~WinTray() {
+  RemoveTrayIcon();
+  if (hwnd_message_only_) DestroyWindow(hwnd_message_only_);
+}
+
+void WinTray::MinimizeToTray() {
+  Shell_NotifyIcon(NIM_ADD, &nid_);
+  if (hide_window_) {
+    hide_window_();
+  } else if (app_hwnd_) {
+    ShowWindow(app_hwnd_, SW_HIDE);
+  }
+}
+
+void WinTray::RemoveTrayIcon() { Shell_NotifyIcon(NIM_DELETE, &nid_); }
+
+void WinTray::ShowApplicationWindow() {
+  if (show_window_) {
+    show_window_();
+  } else if (app_hwnd_) {
+    ShowWindow(app_hwnd_, SW_SHOW);
+    SetForegroundWindow(app_hwnd_);
+  }
+}
+
+void WinTray::OpenSettings() {
+  if (open_settings_) {
+    open_settings_();
+  } else {
+    ShowApplicationWindow();
+  }
+}
+
+bool WinTray::HandleTrayMessage(MSG* msg) {
+  if (!msg || msg->message != WM_TRAY_CALLBACK) return false;
+
+  switch (LOWORD(msg->lParam)) {
+    case WM_LBUTTONDBLCLK:
+    case WM_LBUTTONUP: {
+      ShowApplicationWindow();
+      break;
+    }
+
+    case WM_RBUTTONUP: {
+      POINT pt;
+      GetCursorPos(&pt);
+      HMENU menu = CreatePopupMenu();
+      HBRUSH menu_background = CreateSolidBrush(RGB(255, 255, 255));
+      if (menu_background) {
+        MENUINFO menu_info{};
+        menu_info.cbSize = sizeof(menu_info);
+        menu_info.fMask = MIM_BACKGROUND | MIM_APPLYTOSUBMENUS;
+        menu_info.hbrBack = menu_background;
+        SetMenuInfo(menu, &menu_info);
+      }
+
+      AppendMenuW(menu, MF_STRING, 1002,
+                  localization::GetShowMainWindowLabel(language_index_));
+      AppendMenuW(menu, MF_STRING, 1003,
+                  localization::GetSettingsLabel(language_index_));
+      AppendMenuW(menu, MF_SEPARATOR, 0, nullptr);
+      AppendMenuW(menu, MF_STRING, 1001,
+                  localization::GetExitProgramLabel(language_index_));
+
+      SetForegroundWindow(hwnd_message_only_);
+      int cmd =
+          TrackPopupMenu(menu, TPM_RETURNCMD | TPM_NONOTIFY | TPM_LEFTALIGN,
+                         pt.x, pt.y, 0, hwnd_message_only_, nullptr);
+      DestroyMenu(menu);
+      if (menu_background) {
+        DeleteObject(menu_background);
+      }
+
+      // handle menu command
+      if (cmd == 1001) {
+        if (exit_app_) {
+          exit_app_();
+        } else {
+          SDL_Event event;
+          event.type = SDL_EVENT_QUIT;
+          SDL_PushEvent(&event);
+        }
+      } else if (cmd == 1002) {
+        ShowApplicationWindow();
+      } else if (cmd == 1003) {
+        OpenSettings();
+      }
+      break;
+    }
+  }
+  return true;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/windows/gui/tray/win_tray.h

@@ -0,0 +1,51 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2025-10-22
+ * Copyright (c) 2025 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _WIN_TRAY_H_
+#define _WIN_TRAY_H_
+
+#include <Windows.h>
+#include <shellapi.h>
+
+#include <functional>
+#include <string>
+
+#define WM_TRAY_CALLBACK (WM_USER + 1)
+
+namespace crossdesk {
+
+class WinTray {
+ public:
+  WinTray(HWND app_hwnd, HICON icon, const std::wstring& tooltip,
+          int language_index);
+  WinTray(std::function<void()> show_window,
+          std::function<void()> hide_window,
+          std::function<void()> open_settings,
+          std::function<void()> exit_app,
+          HICON icon, const std::wstring& tooltip, int language_index);
+  ~WinTray();
+
+  void MinimizeToTray();
+  void RemoveTrayIcon();
+  bool HandleTrayMessage(MSG* msg);
+
+ private:
+  void ShowApplicationWindow();
+  void OpenSettings();
+
+  HWND app_hwnd_;
+  HWND hwnd_message_only_;
+  HICON icon_;
+  std::wstring tip_;
+  int language_index_;
+  NOTIFYICONDATA nid_;
+  std::function<void()> show_window_;
+  std::function<void()> hide_window_;
+  std::function<void()> open_settings_;
+  std::function<void()> exit_app_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/windows/input/device_controller_factory.cpp

@@ -0,0 +1,19 @@
+#include "device_controller_factory.h"
+
+#include "keyboard_capturer.h"
+#include "mouse_controller.h"
+
+namespace crossdesk {
+
+DeviceController* DeviceControllerFactory::Create(Device device) {
+  switch (device) {
+    case Mouse:
+      return new PlatformMouseController();
+    case Keyboard:
+      return new PlatformKeyboardCapturer();
+    default:
+      return nullptr;
+  }
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/windows/input/keyboard/keyboard_capturer.cpp

@@ -0,0 +1,316 @@
+#include "keyboard_capturer.h"
+
+#include <hidusage.h>
+
+#include "rd_log.h"
+#include "windows_input_marker.h"
+
+namespace crossdesk {
+namespace {
+
+constexpr wchar_t kRawInputWindowClassName[] =
+    L"CrossDeskKeyboardRawInputWindow";
+
+bool PreferSideSpecificVkInjection(int key_code) {
+  switch (key_code) {
+    case VK_LSHIFT:
+    case VK_RSHIFT:
+    case VK_LCONTROL:
+    case VK_RCONTROL:
+    case VK_LMENU:
+    case VK_RMENU:
+    case VK_LWIN:
+    case VK_RWIN:
+      return true;
+    default:
+      return false;
+  }
+}
+
+}  // namespace
+
+PlatformKeyboardCapturer::PlatformKeyboardCapturer() {}
+
+PlatformKeyboardCapturer::~PlatformKeyboardCapturer() { Unhook(); }
+
+int PlatformKeyboardCapturer::Hook(OnKeyAction on_key_action, void* user_ptr) {
+  if (capture_thread_.joinable()) {
+    return 0;
+  }
+
+  on_key_action_ = on_key_action;
+  user_ptr_ = user_ptr;
+  {
+    std::lock_guard<std::mutex> lock(capture_state_mutex_);
+    capture_thread_id_ = 0;
+    capture_start_complete_ = false;
+    capture_start_succeeded_ = false;
+  }
+
+  capture_thread_ = std::thread(&PlatformKeyboardCapturer::RawInputThreadMain, this);
+
+  std::unique_lock<std::mutex> lock(capture_state_mutex_);
+  capture_start_condition_.wait(
+      lock, [this] { return capture_start_complete_; });
+  const bool capture_started = capture_start_succeeded_;
+  lock.unlock();
+
+  if (!capture_started) {
+    if (capture_thread_.joinable()) {
+      capture_thread_.join();
+    }
+    on_key_action_ = nullptr;
+    user_ptr_ = nullptr;
+    return -1;
+  }
+  return 0;
+}
+
+int PlatformKeyboardCapturer::Unhook() {
+  DWORD capture_thread_id = 0;
+  {
+    std::lock_guard<std::mutex> lock(capture_state_mutex_);
+    capture_thread_id = capture_thread_id_;
+  }
+  if (capture_thread_id != 0 &&
+      !PostThreadMessageW(capture_thread_id, WM_QUIT, 0, 0)) {
+    LOG_WARN("Failed to stop keyboard raw input thread, thread_id={}, error={}",
+             capture_thread_id, GetLastError());
+  }
+  if (capture_thread_.joinable()) {
+    capture_thread_.join();
+  }
+
+  on_key_action_ = nullptr;
+  user_ptr_ = nullptr;
+  return 0;
+}
+
+void PlatformKeyboardCapturer::RawInputThreadMain() {
+  const DWORD thread_id = GetCurrentThreadId();
+
+  MSG message{};
+  PeekMessageW(&message, nullptr, WM_USER, WM_USER, PM_NOREMOVE);
+  const bool capture_started = CreateRawInputWindow();
+  {
+    std::lock_guard<std::mutex> lock(capture_state_mutex_);
+    capture_thread_id_ = thread_id;
+    capture_start_succeeded_ = capture_started;
+    capture_start_complete_ = true;
+  }
+  capture_start_condition_.notify_one();
+
+  if (!capture_started) {
+    std::lock_guard<std::mutex> lock(capture_state_mutex_);
+    capture_thread_id_ = 0;
+    return;
+  }
+
+  LOG_INFO("Keyboard raw input capture started, thread_id={}", thread_id);
+  while (true) {
+    const BOOL get_message_result = GetMessageW(&message, nullptr, 0, 0);
+    if (get_message_result <= 0) {
+      if (get_message_result < 0) {
+        LOG_WARN("Keyboard raw input message loop failed, thread_id={}, "
+                 "error={}",
+                 thread_id, GetLastError());
+      }
+      break;
+    }
+    TranslateMessage(&message);
+    DispatchMessageW(&message);
+  }
+
+  DestroyRawInputWindow();
+  {
+    std::lock_guard<std::mutex> lock(capture_state_mutex_);
+    capture_thread_id_ = 0;
+  }
+  LOG_INFO("Keyboard raw input capture stopped, thread_id={}", thread_id);
+}
+
+bool PlatformKeyboardCapturer::CreateRawInputWindow() {
+  const HINSTANCE instance = GetModuleHandleW(nullptr);
+  WNDCLASSEXW window_class{};
+  window_class.cbSize = sizeof(window_class);
+  window_class.lpfnWndProc = &PlatformKeyboardCapturer::RawInputWindowProc;
+  window_class.hInstance = instance;
+  window_class.lpszClassName = kRawInputWindowClassName;
+
+  if (RegisterClassExW(&window_class) == 0) {
+    const DWORD error = GetLastError();
+    if (error != ERROR_CLASS_ALREADY_EXISTS) {
+      LOG_WARN("Failed to register keyboard raw input window class, error={}",
+               error);
+      return false;
+    }
+  }
+
+  raw_input_window_ = CreateWindowExW(
+      0, kRawInputWindowClassName, L"", 0, 0, 0, 0, 0, HWND_MESSAGE, nullptr,
+      instance, this);
+  if (!raw_input_window_) {
+    LOG_WARN("Failed to create keyboard raw input window, error={}",
+             GetLastError());
+    return false;
+  }
+
+  RAWINPUTDEVICE keyboard_device{};
+  keyboard_device.usUsagePage = HID_USAGE_PAGE_GENERIC;
+  keyboard_device.usUsage = HID_USAGE_GENERIC_KEYBOARD;
+  keyboard_device.dwFlags = RIDEV_DEVNOTIFY | RIDEV_INPUTSINK;
+  keyboard_device.hwndTarget = raw_input_window_;
+  if (!RegisterRawInputDevices(&keyboard_device, 1,
+                               sizeof(keyboard_device))) {
+    LOG_WARN("Failed to register keyboard raw input, error={}", GetLastError());
+    DestroyWindow(raw_input_window_);
+    raw_input_window_ = nullptr;
+    return false;
+  }
+
+  raw_input_registered_ = true;
+  return true;
+}
+
+void PlatformKeyboardCapturer::DestroyRawInputWindow() {
+  if (raw_input_registered_) {
+    RAWINPUTDEVICE keyboard_device{};
+    keyboard_device.usUsagePage = HID_USAGE_PAGE_GENERIC;
+    keyboard_device.usUsage = HID_USAGE_GENERIC_KEYBOARD;
+    keyboard_device.dwFlags = RIDEV_REMOVE;
+    keyboard_device.hwndTarget = nullptr;
+    if (!RegisterRawInputDevices(&keyboard_device, 1,
+                                 sizeof(keyboard_device))) {
+      LOG_WARN("Failed to unregister keyboard raw input, error={}",
+               GetLastError());
+    }
+    raw_input_registered_ = false;
+  }
+  if (raw_input_window_) {
+    DestroyWindow(raw_input_window_);
+    raw_input_window_ = nullptr;
+  }
+}
+
+LRESULT CALLBACK PlatformKeyboardCapturer::RawInputWindowProc(
+    HWND window, UINT message, WPARAM w_param, LPARAM l_param) {
+  PlatformKeyboardCapturer* capturer = reinterpret_cast<PlatformKeyboardCapturer*>(
+      GetWindowLongPtrW(window, GWLP_USERDATA));
+  if (message == WM_NCCREATE) {
+    auto* create = reinterpret_cast<CREATESTRUCTW*>(l_param);
+    capturer = static_cast<PlatformKeyboardCapturer*>(create->lpCreateParams);
+    SetWindowLongPtrW(window, GWLP_USERDATA,
+                      reinterpret_cast<LONG_PTR>(capturer));
+  } else if (message == WM_INPUT && capturer) {
+    capturer->HandleRawInput(reinterpret_cast<HRAWINPUT>(l_param));
+  } else if (message == WM_NCDESTROY) {
+    SetWindowLongPtrW(window, GWLP_USERDATA, 0);
+  }
+  return DefWindowProcW(window, message, w_param, l_param);
+}
+
+void PlatformKeyboardCapturer::HandleRawInput(HRAWINPUT raw_input_handle) {
+  RAWINPUT input{};
+  UINT input_size = sizeof(input);
+  const UINT bytes_read =
+      GetRawInputData(raw_input_handle, RID_INPUT, &input, &input_size,
+                      sizeof(RAWINPUTHEADER));
+  if (bytes_read == static_cast<UINT>(-1) ||
+      bytes_read < sizeof(RAWINPUTHEADER) ||
+      input.header.dwType != RIM_TYPEKEYBOARD) {
+    return;
+  }
+
+  const RAWKEYBOARD& keyboard = input.data.keyboard;
+  if (keyboard.VKey == 0xFF ||
+      keyboard.ExtraInformation ==
+          static_cast<ULONG>(kInjectedKeyboardInputMarker)) {
+    return;
+  }
+
+  bool is_down = false;
+  if (keyboard.Message == WM_KEYDOWN || keyboard.Message == WM_SYSKEYDOWN) {
+    is_down = true;
+  } else if (keyboard.Message != WM_KEYUP &&
+             keyboard.Message != WM_SYSKEYUP) {
+    return;
+  }
+
+  const bool extended = (keyboard.Flags & (RI_KEY_E0 | RI_KEY_E1)) != 0;
+  UINT mapped_scan_code = keyboard.MakeCode;
+  if ((keyboard.Flags & RI_KEY_E0) != 0) {
+    mapped_scan_code |= 0xE000;
+  } else if ((keyboard.Flags & RI_KEY_E1) != 0) {
+    mapped_scan_code |= 0xE100;
+  }
+  if (mapped_scan_code == 0xE11D || mapped_scan_code == 0xE02A) {
+    return;
+  }
+
+  int key_code = static_cast<int>(keyboard.VKey);
+  if (key_code == VK_SHIFT || key_code == VK_CONTROL || key_code == VK_MENU) {
+    const UINT normalized =
+        MapVirtualKeyW(mapped_scan_code, MAPVK_VSC_TO_VK_EX);
+    if (normalized != 0) {
+      key_code = static_cast<int>(normalized);
+    }
+  }
+
+  if (on_key_action_) {
+    on_key_action_(key_code, is_down, keyboard.MakeCode, extended, user_ptr_);
+  }
+}
+
+// Apply remote keyboard commands to the local machine.
+int PlatformKeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down,
+                                          uint32_t scan_code, bool extended) {
+  INPUT input = {0};
+  input.type = INPUT_KEYBOARD;
+  input.ki.dwExtraInfo =
+      static_cast<ULONG_PTR>(kInjectedKeyboardInputMarker);
+
+  const bool prefer_vk = PreferSideSpecificVkInjection(key_code);
+  const UINT resolved_scan_code =
+      scan_code != 0
+          ? static_cast<UINT>(scan_code & 0xFF) | (extended ? 0xE000u : 0u)
+          : MapVirtualKeyW(static_cast<UINT>(key_code), MAPVK_VK_TO_VSC_EX);
+
+  if (scan_code != 0 && !prefer_vk) {
+    input.ki.wVk = 0;
+    input.ki.wScan = static_cast<WORD>(scan_code & 0xFF);
+    input.ki.dwFlags |= KEYEVENTF_SCANCODE;
+    if (extended) {
+      input.ki.dwFlags |= KEYEVENTF_EXTENDEDKEY;
+    }
+  } else {
+    input.ki.wVk = static_cast<WORD>(key_code);
+
+    if (prefer_vk && resolved_scan_code != 0) {
+      input.ki.wScan = static_cast<WORD>(resolved_scan_code & 0xFF);
+      if ((resolved_scan_code & 0xFF00) != 0) {
+        input.ki.dwFlags |= KEYEVENTF_EXTENDEDKEY;
+      }
+    } else if (resolved_scan_code != 0) {
+      input.ki.wVk = 0;
+      input.ki.wScan = static_cast<WORD>(resolved_scan_code & 0xFF);
+      input.ki.dwFlags |= KEYEVENTF_SCANCODE;
+      if ((resolved_scan_code & 0xFF00) != 0) {
+        input.ki.dwFlags |= KEYEVENTF_EXTENDEDKEY;
+      }
+    }
+  }
+
+  if (!is_down) {
+    input.ki.dwFlags |= KEYEVENTF_KEYUP;
+  }
+
+  const UINT sent = SendInput(1, &input, sizeof(INPUT));
+  if (sent != 1) {
+    LOG_WARN("SendInput failed for key_code={}, is_down={}, err={}", key_code,
+             is_down, GetLastError());
+    return -1;
+  }
+
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/windows/input/keyboard/keyboard_capturer.h

@@ -0,0 +1,54 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2024-11-22
+ * Copyright (c) 2024 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _KEYBOARD_CAPTURER_H_
+#define _KEYBOARD_CAPTURER_H_
+
+#include <Windows.h>
+
+#include <condition_variable>
+#include <mutex>
+#include <thread>
+
+#include "device_controller.h"
+
+namespace crossdesk {
+
+class PlatformKeyboardCapturer final : public KeyboardCapturer {
+ public:
+  PlatformKeyboardCapturer();
+  virtual ~PlatformKeyboardCapturer();
+
+ public:
+  virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
+  virtual int Unhook();
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false);
+
+ private:
+  static LRESULT CALLBACK RawInputWindowProc(HWND window, UINT message,
+                                             WPARAM w_param, LPARAM l_param);
+
+  void RawInputThreadMain();
+  bool CreateRawInputWindow();
+  void DestroyRawInputWindow();
+  void HandleRawInput(HRAWINPUT raw_input_handle);
+
+  OnKeyAction on_key_action_ = nullptr;
+  void* user_ptr_ = nullptr;
+  HWND raw_input_window_ = nullptr;
+  bool raw_input_registered_ = false;
+  std::thread capture_thread_;
+  DWORD capture_thread_id_ = 0;
+  bool capture_start_complete_ = false;
+  bool capture_start_succeeded_ = false;
+  std::mutex capture_state_mutex_;
+  std::condition_variable capture_start_condition_;
+};
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/windows/input/mouse/mouse_controller.cpp

@@ -0,0 +1,98 @@
+#include "mouse_controller.h"
+
+#include <remote_action.h>
+
+#include <Windows.h>
+
+#include "rd_log.h"
+
+namespace crossdesk {
+
+PlatformMouseController::PlatformMouseController() {}
+
+PlatformMouseController::~PlatformMouseController() {}
+
+int PlatformMouseController::Init(std::vector<DisplayInfo> display_info_list) {
+  display_info_list_ = display_info_list;
+
+  return 0;
+}
+
+int PlatformMouseController::Destroy() { return 0; }
+
+int PlatformMouseController::SendMouseCommand(RemoteAction remote_action,
+                                      int display_index) {
+  if (display_index < 0 ||
+      display_index >= static_cast<int>(display_info_list_.size())) {
+    LOG_WARN("Mouse command skipped, invalid display_index={}, displays={}",
+             display_index, display_info_list_.size());
+    return -1;
+  }
+
+  INPUT ip = {0};
+
+  if (remote_action.type == ControlType::mouse) {
+    ip.type = INPUT_MOUSE;
+    ip.mi.dx =
+        (LONG)(remote_action.m.x * display_info_list_[display_index].width) +
+        display_info_list_[display_index].left;
+    ip.mi.dy =
+        (LONG)(remote_action.m.y * display_info_list_[display_index].height) +
+        display_info_list_[display_index].top;
+
+    switch (remote_action.m.flag) {
+      case MouseFlag::left_down:
+        ip.mi.dwFlags = MOUSEEVENTF_LEFTDOWN | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::left_up:
+        ip.mi.dwFlags = MOUSEEVENTF_LEFTUP | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::right_down:
+        ip.mi.dwFlags = MOUSEEVENTF_RIGHTDOWN | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::right_up:
+        ip.mi.dwFlags = MOUSEEVENTF_RIGHTUP | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::middle_down:
+        ip.mi.dwFlags = MOUSEEVENTF_MIDDLEDOWN | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::middle_up:
+        ip.mi.dwFlags = MOUSEEVENTF_MIDDLEUP | MOUSEEVENTF_ABSOLUTE;
+        break;
+      case MouseFlag::wheel_vertical:
+        ip.mi.dwFlags = MOUSEEVENTF_WHEEL;
+        ip.mi.mouseData = remote_action.m.s * 120;
+        break;
+      case MouseFlag::wheel_horizontal:
+        ip.mi.dwFlags = MOUSEEVENTF_HWHEEL;
+        ip.mi.mouseData = remote_action.m.s * 120;
+        break;
+      default:
+        ip.mi.dwFlags = MOUSEEVENTF_MOVE;
+        break;
+    }
+
+    ip.mi.time = 0;
+
+    if (!SetCursorPos(ip.mi.dx, ip.mi.dy)) {
+      LOG_WARN("SetCursorPos failed for mouse x={}, y={}, flag={}, err={}",
+               ip.mi.dx, ip.mi.dy, static_cast<int>(remote_action.m.flag),
+               GetLastError());
+      return -1;
+    }
+
+    if (ip.mi.dwFlags != MOUSEEVENTF_MOVE) {
+      UINT sent = SendInput(1, &ip, sizeof(INPUT));
+      if (sent != 1) {
+        LOG_WARN(
+            "SendInput failed for mouse x={}, y={}, wheel={}, flag={}, err={}",
+            ip.mi.dx, ip.mi.dy, remote_action.m.s,
+            static_cast<int>(remote_action.m.flag), GetLastError());
+        return -1;
+      }
+    }
+  }
+
+  return 0;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/windows/input/mouse/mouse_controller.h

@@ -0,0 +1,33 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2023-12-14
+ * Copyright (c) 2023 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _MOUSE_CONTROLLER_H_
+#define _MOUSE_CONTROLLER_H_
+
+#include <vector>
+
+#include <remote_action.h>
+
+#include "device_controller.h"
+#include "display_info.h"
+
+namespace crossdesk {
+
+class PlatformMouseController final : public MouseController {
+ public:
+  PlatformMouseController();
+  virtual ~PlatformMouseController();
+
+ public:
+  virtual int Init(std::vector<DisplayInfo> display_info_list);
+  virtual int Destroy();
+  virtual int SendMouseCommand(RemoteAction remote_action, int display_index);
+
+ private:
+  std::vector<DisplayInfo> display_info_list_;
+};
+}  // namespace crossdesk
+#endif

apps/desktop/src/platform/windows/input/windows_input_marker.h

@@ -0,0 +1,15 @@
+#ifndef CROSSDESK_COMMON_WINDOWS_INPUT_MARKER_H_
+#define CROSSDESK_COMMON_WINDOWS_INPUT_MARKER_H_
+
+#include <cstdint>
+
+namespace crossdesk {
+
+// SendInput copies dwExtraInfo into KBDLLHOOKSTRUCT. Tag CrossDesk-generated
+// keyboard input so the controller hook can ignore only its own injections
+// while still accepting input from accessibility tools or remote sessions.
+inline constexpr std::uintptr_t kInjectedKeyboardInputMarker = 0x4353444B;
+
+}  // namespace crossdesk
+
+#endif  // CROSSDESK_COMMON_WINDOWS_INPUT_MARKER_H_

apps/desktop/src/platform/windows/input/windows_keycode.h

@@ -0,0 +1,206 @@
+// virtual_key_codes.h
+#ifndef VIRTUAL_KEY_CODES_H
+#define VIRTUAL_KEY_CODES_H
+
+#define VK_LBUTTON 0x01   // Left mouse button
+#define VK_RBUTTON 0x02   // Right mouse button
+#define VK_CANCEL 0x03    // Control-break processing
+#define VK_MBUTTON 0x04   // Middle mouse button
+#define VK_XBUTTON1 0x05  // X1 mouse button
+#define VK_XBUTTON2 0x06  // X2 mouse button
+// 0x07 Reserved
+#define VK_BACK 0x08  // Backspace key
+#define VK_TAB 0x09   // Tab key
+// 0x0A-0B Reserved
+#define VK_CLEAR 0x0C   // Clear key
+#define VK_RETURN 0x0D  // Enter key
+// 0x0E-0F Unassigned
+#define VK_SHIFT 0x10       // Shift key
+#define VK_CONTROL 0x11     // Ctrl key
+#define VK_MENU 0x12        // Alt key
+#define VK_PAUSE 0x13       // Pause key
+#define VK_CAPITAL 0x14     // Caps lock key
+#define VK_KANA 0x15        // IME Kana mode
+#define VK_HANGUL 0x15      // IME Hangul mode
+#define VK_IME_ON 0x16      // IME On
+#define VK_JUNJA 0x17       // IME Junja mode
+#define VK_FINAL 0x18       // IME final mode
+#define VK_HANJA 0x19       // IME Hanja mode
+#define VK_KANJI 0x19       // IME Kanji mode
+#define VK_IME_OFF 0x1A     // IME Off
+#define VK_ESCAPE 0x1B      // Esc key
+#define VK_CONVERT 0x1C     // IME convert
+#define VK_NONCONVERT 0x1D  // IME nonconvert
+#define VK_ACCEPT 0x1E      // IME accept
+#define VK_MODECHANGE 0x1F  // IME mode change request
+#define VK_SPACE 0x20       // Spacebar key
+#define VK_PRIOR 0x21       // Page up key
+#define VK_NEXT 0x22        // Page down key
+#define VK_END 0x23         // End key
+#define VK_HOME 0x24        // Home key
+#define VK_LEFT 0x25        // Left arrow key
+#define VK_UP 0x26          // Up arrow key
+#define VK_RIGHT 0x27       // Right arrow key
+#define VK_DOWN 0x28        // Down arrow key
+#define VK_SELECT 0x29      // Select key
+#define VK_PRINT 0x2A       // Print key
+#define VK_EXECUTE 0x2B     // Execute key
+#define VK_SNAPSHOT 0x2C    // Print screen key
+#define VK_INSERT 0x2D      // Insert key
+#define VK_DELETE 0x2E      // Delete key
+#define VK_HELP 0x2F        // Help key
+
+#define VK_0 0x30  // 0 key
+#define VK_1 0x31  // 1 key
+#define VK_2 0x32  // 2 key
+#define VK_3 0x33  // 3 key
+#define VK_4 0x34  // 4 key
+#define VK_5 0x35  // 5 key
+#define VK_6 0x36  // 6 key
+#define VK_7 0x37  // 7 key
+#define VK_8 0x38  // 8 key
+#define VK_9 0x39  // 9 key
+// 0x3A-40 Undefined
+
+#define VK_A 0x41  // A key
+#define VK_B 0x42  // B key
+#define VK_C 0x43  // C key
+#define VK_D 0x44  // D key
+#define VK_E 0x45  // E key
+#define VK_F 0x46  // F key
+#define VK_G 0x47  // G key
+#define VK_H 0x48  // H key
+#define VK_I 0x49  // I key
+#define VK_J 0x4A  // J key
+#define VK_K 0x4B  // K key
+#define VK_L 0x4C  // L key
+#define VK_M 0x4D  // M key
+#define VK_N 0x4E  // N key
+#define VK_O 0x4F  // O key
+#define VK_P 0x50  // P key
+#define VK_Q 0x51  // Q key
+#define VK_R 0x52  // R key
+#define VK_S 0x53  // S key
+#define VK_T 0x54  // T key
+#define VK_U 0x55  // U key
+#define VK_V 0x56  // V key
+#define VK_W 0x57  // W key
+#define VK_X 0x58  // X key
+#define VK_Y 0x59  // Y key
+#define VK_Z 0x5A  // Z key
+
+#define VK_LWIN 0x5B  // Left Windows logo key
+#define VK_RWIN 0x5C  // Right Windows logo key
+#define VK_APPS 0x5D  // Application key
+// 0x5E Reserved
+#define VK_SLEEP 0x5F  // Computer Sleep key
+
+#define VK_NUMPAD0 0x60    // Numeric keypad 0 key
+#define VK_NUMPAD1 0x61    // Numeric keypad 1 key
+#define VK_NUMPAD2 0x62    // Numeric keypad 2 key
+#define VK_NUMPAD3 0x63    // Numeric keypad 3 key
+#define VK_NUMPAD4 0x64    // Numeric keypad 4 key
+#define VK_NUMPAD5 0x65    // Numeric keypad 5 key
+#define VK_NUMPAD6 0x66    // Numeric keypad 6 key
+#define VK_NUMPAD7 0x67    // Numeric keypad 7 key
+#define VK_NUMPAD8 0x68    // Numeric keypad 8 key
+#define VK_NUMPAD9 0x69    // Numeric keypad 9 key
+#define VK_MULTIPLY 0x6A   // Multiply key
+#define VK_ADD 0x6B        // Add key
+#define VK_SEPARATOR 0x6C  // Separator key
+#define VK_SUBTRACT 0x6D   // Subtract key
+#define VK_DECIMAL 0x6E    // Decimal key
+#define VK_DIVIDE 0x6F     // Divide key
+
+#define VK_F1 0x70   // F1 key
+#define VK_F2 0x71   // F2 key
+#define VK_F3 0x72   // F3 key
+#define VK_F4 0x73   // F4 key
+#define VK_F5 0x74   // F5 key
+#define VK_F6 0x75   // F6 key
+#define VK_F7 0x76   // F7 key
+#define VK_F8 0x77   // F8 key
+#define VK_F9 0x78   // F9 key
+#define VK_F10 0x79  // F10 key
+#define VK_F11 0x7A  // F11 key
+#define VK_F12 0x7B  // F12 key
+#define VK_F13 0x7C  // F13 key
+#define VK_F14 0x7D  // F14 key
+#define VK_F15 0x7E  // F15 key
+#define VK_F16 0x7F  // F16 key
+#define VK_F17 0x80  // F17 key
+#define VK_F18 0x81  // F18 key
+#define VK_F19 0x82  // F19 key
+#define VK_F20 0x83  // F20 key
+#define VK_F21 0x84  // F21 key
+#define VK_F22 0x85  // F22 key
+#define VK_F23 0x86  // F23 key
+#define VK_F24 0x87  // F24 key
+// 0x88–0x8F Reserved
+
+#define VK_NUMLOCK 0x90  // Num lock key
+#define VK_SCROLL 0x91   // Scroll lock key
+// 0x92–0x96 OEM specific
+// 0x97–0x9F Unassigned
+
+#define VK_LSHIFT 0xA0    // Left Shift key
+#define VK_RSHIFT 0xA1    // Right Shift key
+#define VK_LCONTROL 0xA2  // Left Ctrl key
+#define VK_RCONTROL 0xA3  // Right Ctrl key
+#define VK_LMENU 0xA4     // Left Alt key
+#define VK_RMENU 0xA5     // Right Alt key
+
+#define VK_BROWSER_BACK 0xA6       // Browser Back key
+#define VK_BROWSER_FORWARD 0xA7    // Browser Forward key
+#define VK_BROWSER_REFRESH 0xA8    // Browser Refresh key
+#define VK_BROWSER_STOP 0xA9       // Browser Stop key
+#define VK_BROWSER_SEARCH 0xAA     // Browser Search key
+#define VK_BROWSER_FAVORITES 0xAB  // Browser Favorites key
+#define VK_BROWSER_HOME 0xAC       // Browser Start and Home key
+#define VK_VOLUME_MUTE 0xAD        // Volume Mute key
+#define VK_VOLUME_DOWN 0xAE        // Volume Down key
+#define VK_VOLUME_UP 0xAF          // Volume Up key
+
+#define VK_MEDIA_NEXT_TRACK 0xB0     // Next Track key
+#define VK_MEDIA_PREV_TRACK 0xB1     // Previous Track key
+#define VK_MEDIA_STOP 0xB2           // Stop Media key
+#define VK_MEDIA_PLAY_PAUSE 0xB3     // Play/Pause Media key
+#define VK_LAUNCH_MAIL 0xB4          // Start Mail key
+#define VK_LAUNCH_MEDIA_SELECT 0xB5  // Select Media key
+#define VK_LAUNCH_APP1 0xB6          // Start Application 1 key
+#define VK_LAUNCH_APP2 0xB7          // Start Application 2 key
+// 0xB8–0xB9 Reserved
+
+#define VK_OEM_1 0xBA       // For US: Semicolon/Colon key
+#define VK_OEM_PLUS 0xBB    // Equals/Plus key
+#define VK_OEM_COMMA 0xBC   // Comma/Less Than key
+#define VK_OEM_MINUS 0xBD   // Dash/Underscore key
+#define VK_OEM_PERIOD 0xBE  // Period/Greater Than key
+#define VK_OEM_2 0xBF       // Slash/Question Mark key
+#define VK_OEM_3 0xC0       // Grave Accent/Tilde key
+// 0xC1–0xDA Reserved
+
+#define VK_OEM_4 0xDB  // Left Brace key
+#define VK_OEM_5 0xDC  // Backslash/Pipe key
+#define VK_OEM_6 0xDD  // Right Brace key
+#define VK_OEM_7 0xDE  // Apostrophe/Quote key
+#define VK_OEM_8 0xDF  // (Canadian CSA: Right Ctrl key)
+// 0xE0 Reserved
+#define VK_OEM_102 0xE2  // (European ISO: Backslash/Pipe key)
+// 0xE3–E4 OEM specific
+#define VK_PROCESSKEY 0xE5  // IME PROCESS key
+// 0xE6 OEM specific
+#define VK_PACKET 0xE7  // Unicode characters as keystrokes
+// 0xE8 Unassigned
+// 0xE9–F5 OEM specific
+#define VK_ATTN 0xF6       // Attn key
+#define VK_CRSEL 0xF7      // CrSel key
+#define VK_EXSEL 0xF8      // ExSel key
+#define VK_EREOF 0xF9      // Erase EOF key
+#define VK_PLAY 0xFA       // Play key
+#define VK_ZOOM 0xFB       // Zoom key
+#define VK_NONAME 0xFC     // Reserved
+#define VK_PA1 0xFD        // PA1 key
+#define VK_OEM_CLEAR 0xFE  // Clear key
+
+#endif  // VIRTUAL_KEY_CODES_H

apps/desktop/src/platform/windows/path_backend.cpp

@@ -0,0 +1,51 @@
+#include "platform/path_backend.h"
+
+#include <shlobj.h>
+#include <windows.h>
+
+#include <vector>
+
+namespace crossdesk::platform {
+namespace {
+
+std::filesystem::path GetKnownFolder(REFKNOWNFOLDERID id) {
+  PWSTR value = nullptr;
+  if (FAILED(SHGetKnownFolderPath(id, 0, nullptr, &value))) return {};
+  const std::filesystem::path result(value);
+  CoTaskMemFree(value);
+  return result;
+}
+
+}  // namespace
+
+std::filesystem::path GetExecutableDirectory() {
+  std::vector<wchar_t> buffer(MAX_PATH);
+  while (true) {
+    const DWORD length = GetModuleFileNameW(
+        nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
+    if (length == 0 || buffer.size() >= 32768) return {};
+    if (length < buffer.size()) {
+      return std::filesystem::path(buffer.data(), buffer.data() + length)
+          .parent_path();
+    }
+    buffer.resize(buffer.size() * 2);
+  }
+}
+
+std::filesystem::path GetConfigPath(const std::string& app_name) {
+  return GetKnownFolder(FOLDERID_RoamingAppData) / app_name;
+}
+
+std::filesystem::path GetCachePath(const std::string& app_name) {
+#ifdef CROSSDESK_DEBUG
+  return "cache";
+#else
+  return GetKnownFolder(FOLDERID_LocalAppData) / app_name / "cache";
+#endif
+}
+
+std::filesystem::path GetLogPath(const std::string& app_name) {
+  return GetKnownFolder(FOLDERID_LocalAppData) / app_name / "logs";
+}
+
+}  // namespace crossdesk::platform

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_dxgi.cpp

@@ -0,0 +1,399 @@
+#include "screen_capturer_dxgi.h"
+
+#include <algorithm>
+#include <chrono>
+#include <string>
+#include <vector>
+
+#include <display_stream_id.h>
+#include "libyuv.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+namespace {
+std::string WideToUtf8(const std::wstring& wstr) {
+  if (wstr.empty()) return {};
+  int size_needed = WideCharToMultiByte(
+      CP_UTF8, 0, wstr.data(), (int)wstr.size(), nullptr, 0, nullptr, nullptr);
+  std::string result(size_needed, 0);
+  WideCharToMultiByte(CP_UTF8, 0, wstr.data(), (int)wstr.size(), result.data(),
+                      size_needed, nullptr, nullptr);
+  return result;
+}
+
+std::string GetDisplayLabel(const std::wstring& wide_name) {
+  std::string name = WideToUtf8(wide_name);
+  constexpr char kDevicePrefix[] = "\\\\.\\";
+  if (name.rfind(kDevicePrefix, 0) == 0) {
+    name.erase(0, sizeof(kDevicePrefix) - 1);
+  }
+  return name;
+}
+}  // namespace
+
+ScreenCapturerDxgi::ScreenCapturerDxgi() {}
+ScreenCapturerDxgi::~ScreenCapturerDxgi() {
+  Stop();
+  Destroy();
+}
+
+int ScreenCapturerDxgi::Init(const int fps, cb_desktop_data cb) {
+  fps_ = fps;
+  callback_ = cb;
+  if (!callback_) {
+    LOG_ERROR("DXGI: callback is null");
+    return -1;
+  }
+
+  if (!InitializeDxgi()) {
+    LOG_ERROR("DXGI: initialize DXGI failed");
+    return -2;
+  }
+
+  EnumerateDisplays();
+  if (display_info_list_.empty()) {
+    LOG_ERROR("DXGI: no displays found");
+    return -3;
+  }
+
+  monitor_index_ = 0;
+  initial_monitor_index_ = monitor_index_;
+  return 0;
+}
+
+int ScreenCapturerDxgi::Destroy() {
+  Stop();
+  ReleaseDuplication();
+  outputs_.clear();
+  d3d_context_.Reset();
+  d3d_device_.Reset();
+  dxgi_factory_.Reset();
+  if (nv12_frame_) {
+    delete[] nv12_frame_;
+    nv12_frame_ = nullptr;
+    nv12_width_ = 0;
+    nv12_height_ = 0;
+  }
+  return 0;
+}
+
+int ScreenCapturerDxgi::Start(bool show_cursor) {
+  if (running_) return 0;
+  show_cursor_ = show_cursor;
+
+  if (!CreateDuplicationForMonitor(monitor_index_)) {
+    LOG_ERROR("DXGI: create duplication failed for monitor {}",
+              monitor_index_.load());
+    return -1;
+  }
+
+  paused_ = false;
+  running_ = true;
+  thread_ = std::thread([this]() { CaptureLoop(); });
+  return 0;
+}
+
+int ScreenCapturerDxgi::Stop() {
+  if (!running_) return 0;
+  running_ = false;
+  if (thread_.joinable()) thread_.join();
+  ReleaseDuplication();
+  return 0;
+}
+
+int ScreenCapturerDxgi::Pause(int monitor_index) {
+  paused_ = true;
+  return 0;
+}
+
+int ScreenCapturerDxgi::Resume(int monitor_index) {
+  paused_ = false;
+  return 0;
+}
+
+int ScreenCapturerDxgi::SwitchTo(int monitor_index) {
+  std::lock_guard<std::mutex> lock(switch_mutex_);
+  if (monitor_index < 0 || monitor_index >= (int)display_info_list_.size()) {
+    LOG_ERROR("DXGI: invalid monitor index {}", monitor_index);
+    return -1;
+  }
+  paused_ = true;
+  monitor_index_ = monitor_index;
+  ReleaseDuplication();
+  if (!CreateDuplicationForMonitor(monitor_index_)) {
+    LOG_ERROR("DXGI: create duplication failed for monitor {}",
+              monitor_index_.load());
+    paused_ = false;  // Reset paused_ on failure
+    return -2;
+  }
+  paused_ = false;
+  LOG_INFO("DXGI: switched to monitor {}:{}", monitor_index_.load(),
+           display_info_list_[monitor_index_].name);
+  return 0;
+}
+
+int ScreenCapturerDxgi::ResetToInitialMonitor() {
+  std::lock_guard<std::mutex> lock(switch_mutex_);
+  if (display_info_list_.empty()) return -1;
+  int target = initial_monitor_index_;
+  if (target < 0 || target >= (int)display_info_list_.size()) return -1;
+  if (monitor_index_ == target) return 0;
+  if (running_) {
+    paused_ = true;
+    monitor_index_ = target;
+    ReleaseDuplication();
+    if (!CreateDuplicationForMonitor(monitor_index_)) {
+      paused_ = false;
+      return -2;
+    }
+    paused_ = false;
+    LOG_INFO("DXGI: reset to initial monitor {}:{}", monitor_index_.load(),
+             display_info_list_[monitor_index_].name);
+  } else {
+    monitor_index_ = target;
+  }
+  return 0;
+}
+
+bool ScreenCapturerDxgi::InitializeDxgi() {
+  UINT flags = D3D11_CREATE_DEVICE_BGRA_SUPPORT;
+#ifdef _DEBUG
+  flags |= D3D11_CREATE_DEVICE_DEBUG;
+#endif
+
+  D3D_FEATURE_LEVEL feature_levels[] = {
+      D3D_FEATURE_LEVEL_11_1, D3D_FEATURE_LEVEL_11_0, D3D_FEATURE_LEVEL_10_1,
+      D3D_FEATURE_LEVEL_10_0};
+
+  D3D_FEATURE_LEVEL out_level{};
+  HRESULT hr = D3D11CreateDevice(
+      nullptr, D3D_DRIVER_TYPE_HARDWARE, nullptr, flags, feature_levels,
+      ARRAYSIZE(feature_levels), D3D11_SDK_VERSION, d3d_device_.GetAddressOf(),
+      &out_level, d3d_context_.GetAddressOf());
+  if (FAILED(hr)) {
+    hr = D3D11CreateDevice(nullptr, D3D_DRIVER_TYPE_WARP, nullptr, flags,
+                           feature_levels, ARRAYSIZE(feature_levels),
+                           D3D11_SDK_VERSION, d3d_device_.GetAddressOf(),
+                           &out_level, d3d_context_.GetAddressOf());
+    if (FAILED(hr)) {
+      LOG_ERROR("DXGI: D3D11CreateDevice failed, hr={}", (int)hr);
+      return false;
+    }
+  }
+
+  hr = CreateDXGIFactory1(
+      __uuidof(IDXGIFactory1),
+      reinterpret_cast<void**>(dxgi_factory_.GetAddressOf()));
+  if (FAILED(hr)) {
+    LOG_ERROR("DXGI: CreateDXGIFactory1 failed, hr={}", (int)hr);
+    return false;
+  }
+  return true;
+}
+
+void ScreenCapturerDxgi::EnumerateDisplays() {
+  display_info_list_.clear();
+  outputs_.clear();
+
+  Microsoft::WRL::ComPtr<IDXGIAdapter> adapter;
+  for (UINT a = 0;
+       dxgi_factory_->EnumAdapters(a, adapter.ReleaseAndGetAddressOf()) !=
+       DXGI_ERROR_NOT_FOUND;
+       ++a) {
+    Microsoft::WRL::ComPtr<IDXGIOutput> output;
+    for (UINT o = 0; adapter->EnumOutputs(o, output.ReleaseAndGetAddressOf()) !=
+                     DXGI_ERROR_NOT_FOUND;
+         ++o) {
+      DXGI_OUTPUT_DESC desc{};
+      if (FAILED(output->GetDesc(&desc))) {
+        continue;
+      }
+      std::string name = GetDisplayLabel(desc.DeviceName);
+      MONITORINFOEX mi{};
+      mi.cbSize = sizeof(MONITORINFOEX);
+      if (GetMonitorInfo(desc.Monitor, &mi)) {
+        bool is_primary = (mi.dwFlags & MONITORINFOF_PRIMARY) ? true : false;
+        DisplayInfo info((void*)desc.Monitor, name, is_primary,
+                         mi.rcMonitor.left, mi.rcMonitor.top,
+                         mi.rcMonitor.right, mi.rcMonitor.bottom);
+        // primary first
+        if (is_primary)
+          display_info_list_.insert(display_info_list_.begin(), info);
+        else
+          display_info_list_.push_back(info);
+        outputs_.push_back(output);
+      }
+    }
+  }
+}
+
+bool ScreenCapturerDxgi::CreateDuplicationForMonitor(int monitor_index) {
+  if (monitor_index < 0 || monitor_index >= (int)outputs_.size()) return false;
+  Microsoft::WRL::ComPtr<IDXGIOutput1> output1;
+  HRESULT hr = outputs_[monitor_index]->QueryInterface(
+      IID_PPV_ARGS(output1.GetAddressOf()));
+  if (FAILED(hr)) {
+    LOG_ERROR("DXGI: Query IDXGIOutput1 failed, hr={}", (int)hr);
+    return false;
+  }
+
+  duplication_.Reset();
+  hr = output1->DuplicateOutput(d3d_device_.Get(), duplication_.GetAddressOf());
+  if (FAILED(hr)) {
+    LOG_ERROR("DXGI: DuplicateOutput failed, hr={}", (int)hr);
+    return false;
+  }
+
+  staging_.Reset();
+  return true;
+}
+
+bool ScreenCapturerDxgi::RecreateDuplicationForCurrentMonitor() {
+  std::lock_guard<std::mutex> lock(switch_mutex_);
+  ReleaseDuplication();
+  int current_monitor = monitor_index_.load();
+  if (CreateDuplicationForMonitor(current_monitor)) {
+    return true;
+  }
+
+  EnumerateDisplays();
+  if (display_info_list_.empty()) {
+    LOG_ERROR("DXGI: no displays found while recreating duplication");
+    return false;
+  }
+  if (current_monitor < 0 ||
+      current_monitor >= static_cast<int>(display_info_list_.size())) {
+    current_monitor = 0;
+    monitor_index_ = 0;
+  }
+  if (CreateDuplicationForMonitor(current_monitor)) {
+    LOG_INFO("DXGI: recreated duplication for monitor {}",
+             monitor_index_.load());
+    return true;
+  }
+  return false;
+}
+
+void ScreenCapturerDxgi::ReleaseDuplication() {
+  staging_.Reset();
+  if (duplication_) {
+    duplication_->ReleaseFrame();
+  }
+  duplication_.Reset();
+}
+
+void ScreenCapturerDxgi::CaptureLoop() {
+  const int timeout_ms = 33;
+  auto last_duplication_retry =
+      std::chrono::steady_clock::now() - std::chrono::milliseconds(1000);
+  while (running_) {
+    if (paused_) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(10));
+      continue;
+    }
+
+    if (!duplication_) {
+      const auto now = std::chrono::steady_clock::now();
+      if (now - last_duplication_retry >= std::chrono::milliseconds(500)) {
+        last_duplication_retry = now;
+        RecreateDuplicationForCurrentMonitor();
+      }
+      std::this_thread::sleep_for(std::chrono::milliseconds(10));
+      continue;
+    }
+
+    DXGI_OUTDUPL_FRAME_INFO frame_info{};
+    Microsoft::WRL::ComPtr<IDXGIResource> desktop_resource;
+    HRESULT hr = duplication_->AcquireNextFrame(
+        timeout_ms, &frame_info, desktop_resource.GetAddressOf());
+    if (hr == DXGI_ERROR_WAIT_TIMEOUT) {
+      continue;
+    }
+    if (FAILED(hr)) {
+      LOG_ERROR("DXGI: AcquireNextFrame failed, hr={}", (int)hr);
+      RecreateDuplicationForCurrentMonitor();
+      continue;
+    }
+
+    Microsoft::WRL::ComPtr<ID3D11Texture2D> acquired_tex;
+    if (desktop_resource) {
+      hr = desktop_resource->QueryInterface(
+          IID_PPV_ARGS(acquired_tex.GetAddressOf()));
+      if (FAILED(hr)) {
+        duplication_->ReleaseFrame();
+        continue;
+      }
+    } else {
+      duplication_->ReleaseFrame();
+      continue;
+    }
+
+    D3D11_TEXTURE2D_DESC src_desc{};
+    acquired_tex->GetDesc(&src_desc);
+
+    if (!staging_) {
+      D3D11_TEXTURE2D_DESC staging_desc = src_desc;
+      staging_desc.Usage = D3D11_USAGE_STAGING;
+      staging_desc.BindFlags = 0;
+      staging_desc.CPUAccessFlags = D3D11_CPU_ACCESS_READ;
+      staging_desc.MiscFlags = 0;
+      hr = d3d_device_->CreateTexture2D(&staging_desc, nullptr,
+                                        staging_.GetAddressOf());
+      if (FAILED(hr)) {
+        LOG_ERROR("DXGI: CreateTexture2D staging failed, hr={}", (int)hr);
+        duplication_->ReleaseFrame();
+        continue;
+      }
+    }
+
+    d3d_context_->CopyResource(staging_.Get(), acquired_tex.Get());
+
+    D3D11_MAPPED_SUBRESOURCE mapped{};
+    hr = d3d_context_->Map(staging_.Get(), 0, D3D11_MAP_READ, 0, &mapped);
+    if (FAILED(hr)) {
+      duplication_->ReleaseFrame();
+      continue;
+    }
+
+    int logical_width = static_cast<int>(src_desc.Width);
+    int even_width = logical_width & ~1;
+    int even_height = static_cast<int>(src_desc.Height) & ~1;
+    if (even_width <= 0 || even_height <= 0) {
+      d3d_context_->Unmap(staging_.Get(), 0);
+      duplication_->ReleaseFrame();
+      continue;
+    }
+
+    int nv12_size = even_width * even_height * 3 / 2;
+    if (!nv12_frame_ || nv12_width_ != even_width ||
+        nv12_height_ != even_height) {
+      delete[] nv12_frame_;
+      nv12_frame_ = new unsigned char[nv12_size];
+      nv12_width_ = even_width;
+      nv12_height_ = even_height;
+    }
+
+    libyuv::ARGBToNV12(static_cast<const uint8_t*>(mapped.pData),
+                       static_cast<int>(mapped.RowPitch), nv12_frame_,
+                       even_width, nv12_frame_ + even_width * even_height,
+                       even_width, even_width, even_height);
+
+    if (callback_) {
+      int idx = monitor_index_.load();
+      if (idx >= 0 && idx < static_cast<int>(display_info_list_.size())) {
+        const std::string stream_id = MakeDisplayStreamId(idx);
+        callback_(nv12_frame_, nv12_size, even_width, even_height,
+                  stream_id.c_str());
+      } else {
+        LOG_ERROR("DXGI: CaptureLoop invalid monitor_index {} (list size {})",
+                  idx, display_info_list_.size());
+      }
+    }
+
+    d3d_context_->Unmap(staging_.Get(), 0);
+    duplication_->ReleaseFrame();
+  }
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_dxgi.h

@@ -0,0 +1,83 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-02-27
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_DXGI_H_
+#define _SCREEN_CAPTURER_DXGI_H_
+
+#include <Windows.h>
+#include <d3d11.h>
+#include <dxgi1_2.h>
+#include <wrl/client.h>
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "rd_log.h"
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerDxgi : public ScreenCapturer {
+ public:
+  ScreenCapturerDxgi();
+  ~ScreenCapturerDxgi();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override {
+    return display_info_list_;
+  }
+
+ private:
+  bool InitializeDxgi();
+  void EnumerateDisplays();
+  bool CreateDuplicationForMonitor(int monitor_index);
+  bool RecreateDuplicationForCurrentMonitor();
+  void CaptureLoop();
+  void ReleaseDuplication();
+
+ private:
+  std::vector<DisplayInfo> display_info_list_;
+  std::vector<Microsoft::WRL::ComPtr<IDXGIOutput>> outputs_;
+
+  Microsoft::WRL::ComPtr<IDXGIFactory1> dxgi_factory_;
+  Microsoft::WRL::ComPtr<ID3D11Device> d3d_device_;
+  Microsoft::WRL::ComPtr<ID3D11DeviceContext> d3d_context_;
+  Microsoft::WRL::ComPtr<IDXGIOutputDuplication> duplication_;
+  Microsoft::WRL::ComPtr<ID3D11Texture2D> staging_;
+
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  std::atomic<int> monitor_index_{0};
+  int initial_monitor_index_ = 0;
+  std::atomic<bool> show_cursor_{true};
+  std::thread thread_;
+  int fps_ = 60;
+  cb_desktop_data callback_ = nullptr;
+  std::mutex switch_mutex_;
+
+  unsigned char* nv12_frame_ = nullptr;
+  int nv12_width_ = 0;
+  int nv12_height_ = 0;
+};
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_factory.cpp

@@ -0,0 +1,11 @@
+#include "screen_capturer_factory.h"
+
+#include "screen_capturer_win.h"
+
+namespace crossdesk {
+
+ScreenCapturer* ScreenCapturerFactory::Create() {
+  return new ScreenCapturerWin();
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_gdi.cpp

@@ -0,0 +1,227 @@
+#include "screen_capturer_gdi.h"
+
+#include <algorithm>
+#include <chrono>
+#include <string>
+#include <vector>
+
+#include <display_stream_id.h>
+#include "libyuv.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+namespace {
+std::string WideToUtf8(const std::wstring& wstr) {
+  if (wstr.empty()) return {};
+  int size_needed = WideCharToMultiByte(
+      CP_UTF8, 0, wstr.data(), (int)wstr.size(), nullptr, 0, nullptr, nullptr);
+  std::string result(size_needed, 0);
+  WideCharToMultiByte(CP_UTF8, 0, wstr.data(), (int)wstr.size(), result.data(),
+                      size_needed, nullptr, nullptr);
+  return result;
+}
+
+std::string GetDisplayLabel(const std::wstring& wide_name) {
+  std::string name = WideToUtf8(wide_name);
+  constexpr char kDevicePrefix[] = "\\\\.\\";
+  if (name.rfind(kDevicePrefix, 0) == 0) {
+    name.erase(0, sizeof(kDevicePrefix) - 1);
+  }
+  return name;
+}
+}  // namespace
+
+ScreenCapturerGdi::ScreenCapturerGdi() {}
+ScreenCapturerGdi::~ScreenCapturerGdi() {
+  Stop();
+  Destroy();
+}
+
+BOOL CALLBACK ScreenCapturerGdi::EnumMonitorProc(HMONITOR hMonitor, HDC, LPRECT,
+                                                 LPARAM data) {
+  auto displays = reinterpret_cast<std::vector<DisplayInfo>*>(data);
+  MONITORINFOEX mi{};
+  mi.cbSize = sizeof(MONITORINFOEX);
+  if (GetMonitorInfo(hMonitor, &mi)) {
+    std::string name = GetDisplayLabel(mi.szDevice);
+    bool is_primary = (mi.dwFlags & MONITORINFOF_PRIMARY) ? true : false;
+    DisplayInfo info((void*)hMonitor, name, is_primary, mi.rcMonitor.left,
+                     mi.rcMonitor.top, mi.rcMonitor.right, mi.rcMonitor.bottom);
+    if (is_primary)
+      displays->insert(displays->begin(), info);
+    else
+      displays->push_back(info);
+  }
+  return TRUE;
+}
+
+void ScreenCapturerGdi::EnumerateDisplays() {
+  display_info_list_.clear();
+  EnumDisplayMonitors(nullptr, nullptr, EnumMonitorProc,
+                      (LPARAM)&display_info_list_);
+}
+
+int ScreenCapturerGdi::Init(const int fps, cb_desktop_data cb) {
+  fps_ = fps;
+  callback_ = cb;
+  if (!callback_) {
+    LOG_ERROR("GDI: callback is null");
+    return -1;
+  }
+  EnumerateDisplays();
+  if (display_info_list_.empty()) {
+    LOG_ERROR("GDI: no displays found");
+    return -2;
+  }
+  monitor_index_ = 0;
+  initial_monitor_index_ = monitor_index_;
+  return 0;
+}
+
+int ScreenCapturerGdi::Destroy() {
+  Stop();
+  if (nv12_frame_) {
+    delete[] nv12_frame_;
+    nv12_frame_ = nullptr;
+    nv12_width_ = 0;
+    nv12_height_ = 0;
+  }
+  return 0;
+}
+
+int ScreenCapturerGdi::Start(bool show_cursor) {
+  if (running_) return 0;
+  show_cursor_ = show_cursor;
+  paused_ = false;
+  running_ = true;
+  thread_ = std::thread([this]() { CaptureLoop(); });
+  return 0;
+}
+
+int ScreenCapturerGdi::Stop() {
+  if (!running_) return 0;
+  running_ = false;
+  if (thread_.joinable()) thread_.join();
+  return 0;
+}
+
+int ScreenCapturerGdi::Pause(int monitor_index) {
+  paused_ = true;
+  return 0;
+}
+
+int ScreenCapturerGdi::Resume(int monitor_index) {
+  paused_ = false;
+  return 0;
+}
+
+int ScreenCapturerGdi::SwitchTo(int monitor_index) {
+  if (monitor_index < 0 || monitor_index >= (int)display_info_list_.size()) {
+    LOG_ERROR("GDI: invalid monitor index {}", monitor_index);
+    return -1;
+  }
+  monitor_index_ = monitor_index;
+  LOG_INFO("GDI: switched to monitor {}:{}", monitor_index_.load(),
+           display_info_list_[monitor_index_].name);
+  return 0;
+}
+
+int ScreenCapturerGdi::ResetToInitialMonitor() {
+  if (display_info_list_.empty()) return -1;
+  int target = initial_monitor_index_;
+  if (target < 0 || target >= (int)display_info_list_.size()) return -1;
+  monitor_index_ = target;
+  LOG_INFO("GDI: reset to initial monitor {}:{}", monitor_index_.load(),
+           display_info_list_[monitor_index_].name);
+  return 0;
+}
+
+void ScreenCapturerGdi::CaptureLoop() {
+  int interval_ms = fps_ > 0 ? (1000 / fps_) : 16;
+  HDC screen_dc = GetDC(nullptr);
+  while (running_) {
+    if (paused_) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(10));
+      continue;
+    }
+    if (!screen_dc) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(10));
+      continue;
+    }
+
+    int idx = monitor_index_.load();
+    if (idx < 0 || idx >= static_cast<int>(display_info_list_.size())) {
+      LOG_ERROR("GDI: CaptureLoop invalid monitor_index {} (list size {})",
+                idx, display_info_list_.size());
+      std::this_thread::sleep_for(std::chrono::milliseconds(interval_ms));
+      continue;
+    }
+    const auto& di = display_info_list_[idx];
+    int left = di.left;
+    int top = di.top;
+    int width = di.width & ~1;
+    int height = di.height & ~1;
+    if (width <= 0 || height <= 0) {
+      std::this_thread::sleep_for(std::chrono::milliseconds(interval_ms));
+      continue;
+    }
+
+    BITMAPINFO bmi{};
+    bmi.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
+    bmi.bmiHeader.biWidth = width;
+    bmi.bmiHeader.biHeight = -height;
+    bmi.bmiHeader.biPlanes = 1;
+    bmi.bmiHeader.biBitCount = 32;
+    bmi.bmiHeader.biCompression = BI_RGB;
+
+    void* bits = nullptr;
+    HDC mem_dc = CreateCompatibleDC(screen_dc);
+    HBITMAP dib =
+        CreateDIBSection(mem_dc, &bmi, DIB_RGB_COLORS, &bits, nullptr, 0);
+    HGDIOBJ old = SelectObject(mem_dc, dib);
+
+    BitBlt(mem_dc, 0, 0, width, height, screen_dc, left, top,
+           SRCCOPY | CAPTUREBLT);
+
+    if (show_cursor_) {
+      CURSORINFO ci{};
+      ci.cbSize = sizeof(CURSORINFO);
+      if (GetCursorInfo(&ci) && ci.flags == CURSOR_SHOWING && ci.hCursor) {
+        POINT pt = ci.ptScreenPos;
+        int cx = pt.x - left;
+        int cy = pt.y - top;
+        if (cx >= -64 && cy >= -64 && cx < width + 64 && cy < height + 64) {
+          DrawIconEx(mem_dc, cx, cy, ci.hCursor, 0, 0, 0, nullptr, DI_NORMAL);
+        }
+      }
+    }
+
+    int stride_argb = width * 4;
+    int nv12_size = width * height * 3 / 2;
+    if (!nv12_frame_ || nv12_width_ != width || nv12_height_ != height) {
+      delete[] nv12_frame_;
+      nv12_frame_ = new unsigned char[nv12_size];
+      nv12_width_ = width;
+      nv12_height_ = height;
+    }
+
+    libyuv::ARGBToNV12(static_cast<const uint8_t*>(bits), stride_argb,
+                       nv12_frame_, width, nv12_frame_ + width * height, width,
+                       width, height);
+
+    if (callback_) {
+      const std::string stream_id = MakeDisplayStreamId(idx);
+      callback_(nv12_frame_, nv12_size, width, height, stream_id.c_str());
+    }
+
+    SelectObject(mem_dc, old);
+    DeleteObject(dib);
+    DeleteDC(mem_dc);
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(interval_ms));
+  }
+  ReleaseDC(nullptr, screen_dc);
+}
+
+}  // namespace crossdesk

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_gdi.h

@@ -0,0 +1,68 @@
+/*
+ * @Author: DI JUNKUN
+ * @Date: 2026-02-27
+ * Copyright (c) 2026 by DI JUNKUN, All Rights Reserved.
+ */
+
+#ifndef _SCREEN_CAPTURER_GDI_H_
+#define _SCREEN_CAPTURER_GDI_H_
+
+#include <Windows.h>
+
+#include <atomic>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "rd_log.h"
+#include "screen_capturer.h"
+
+namespace crossdesk {
+
+class ScreenCapturerGdi : public ScreenCapturer {
+ public:
+  ScreenCapturerGdi();
+  ~ScreenCapturerGdi();
+
+ public:
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  int SwitchTo(int monitor_index) override;
+  int ResetToInitialMonitor() override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() override {
+    return display_info_list_;
+  }
+
+ private:
+  static BOOL CALLBACK EnumMonitorProc(HMONITOR hMonitor, HDC, LPRECT,
+                                       LPARAM data);
+  void EnumerateDisplays();
+  void CaptureLoop();
+
+ private:
+  std::vector<DisplayInfo> display_info_list_;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  std::atomic<int> monitor_index_{0};
+  int initial_monitor_index_ = 0;
+  std::atomic<bool> show_cursor_{true};
+  std::thread thread_;
+  int fps_ = 60;
+  cb_desktop_data callback_ = nullptr;
+
+  unsigned char* nv12_frame_ = nullptr;
+  int nv12_width_ = 0;
+  int nv12_height_ = 0;
+};
+}  // namespace crossdesk
+
+#endif

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_wgc.cpp

@@ -0,0 +1,426 @@
+#include "screen_capturer_wgc.h"
+
+#include <Windows.h>
+#include <d3d11_4.h>
+#include <winrt/Windows.Foundation.Metadata.h>
+#include <winrt/Windows.Graphics.Capture.h>
+
+#include <iostream>
+
+#include <display_stream_id.h>
+#include "libyuv.h"
+#include "rd_log.h"
+
+namespace crossdesk {
+
+static std::vector<DisplayInfo> gs_display_list;
+
+std::string WideToUtf8(const std::wstring& wstr) {
+  if (wstr.empty()) return {};
+  int size_needed = WideCharToMultiByte(
+      CP_UTF8, 0, wstr.data(), (int)wstr.size(), nullptr, 0, nullptr, nullptr);
+  std::string result(size_needed, 0);
+  WideCharToMultiByte(CP_UTF8, 0, wstr.data(), (int)wstr.size(), result.data(),
+                      size_needed, nullptr, nullptr);
+  return result;
+}
+
+std::string GetDisplayLabel(const std::wstring& wide_name) {
+  std::string name = WideToUtf8(wide_name);
+  constexpr char kDevicePrefix[] = "\\\\.\\";
+  if (name.rfind(kDevicePrefix, 0) == 0) {
+    name.erase(0, sizeof(kDevicePrefix) - 1);
+  }
+  return name;
+}
+
+BOOL WINAPI EnumMonitorProc(HMONITOR hmonitor, [[maybe_unused]] HDC hdc,
+                            [[maybe_unused]] LPRECT lprc, LPARAM data) {
+  MONITORINFOEX monitor_info_;
+  monitor_info_.cbSize = sizeof(MONITORINFOEX);
+
+  if (GetMonitorInfo(hmonitor, &monitor_info_)) {
+    std::string display_name = GetDisplayLabel(monitor_info_.szDevice);
+    if (monitor_info_.dwFlags & MONITORINFOF_PRIMARY) {
+      gs_display_list.insert(
+          gs_display_list.begin(),
+          {(void*)hmonitor, display_name,
+           (monitor_info_.dwFlags & MONITORINFOF_PRIMARY) ? true : false,
+           monitor_info_.rcMonitor.left, monitor_info_.rcMonitor.top,
+           monitor_info_.rcMonitor.right, monitor_info_.rcMonitor.bottom});
+      *(HMONITOR*)data = hmonitor;
+    } else {
+      gs_display_list.push_back(DisplayInfo(
+          (void*)hmonitor, display_name,
+          (monitor_info_.dwFlags & MONITORINFOF_PRIMARY) ? true : false,
+          monitor_info_.rcMonitor.left, monitor_info_.rcMonitor.top,
+          monitor_info_.rcMonitor.right, monitor_info_.rcMonitor.bottom));
+    }
+  }
+
+  return true;
+}
+
+HMONITOR GetPrimaryMonitor() {
+  HMONITOR hmonitor = nullptr;
+
+  gs_display_list.clear();
+  ::EnumDisplayMonitors(NULL, NULL, EnumMonitorProc, (LPARAM)&hmonitor);
+
+  return hmonitor;
+}
+
+ScreenCapturerWgc::ScreenCapturerWgc() : monitor_(nullptr) {}
+
+ScreenCapturerWgc::~ScreenCapturerWgc() {
+  Stop();
+  CleanUp();
+
+  if (nv12_frame_) {
+    delete[] nv12_frame_;
+    nv12_frame_ = nullptr;
+    nv12_width_ = 0;
+    nv12_height_ = 0;
+  }
+
+  if (nv12_frame_scaled_) {
+    delete[] nv12_frame_scaled_;
+    nv12_frame_scaled_ = nullptr;
+  }
+}
+
+bool ScreenCapturerWgc::IsWgcSupported() {
+  try {
+    /* no contract for IGraphicsCaptureItemInterop, verify 10.0.18362.0 */
+    return winrt::Windows::Foundation::Metadata::ApiInformation::
+        IsApiContractPresent(L"Windows.Foundation.UniversalApiContract", 8);
+  } catch (const winrt::hresult_error&) {
+    return false;
+  } catch (...) {
+    return false;
+  }
+}
+
+int ScreenCapturerWgc::Init(const int fps, cb_desktop_data cb) {
+  if (inited_ == true) return 0;
+
+  // nv12_frame_ = new unsigned char[rect.right * rect.bottom * 3 / 2];
+  // nv12_frame_scaled_ = new unsigned char[1280 * 720 * 3 / 2];
+
+  fps_ = fps;
+
+  on_data_ = cb;
+
+  if (!IsWgcSupported()) {
+    LOG_ERROR("WGC not supported");
+    return 2;
+  }
+
+  return RebuildSessions(monitor_index_);
+}
+
+int ScreenCapturerWgc::RebuildSessions(int preferred_monitor_index) {
+  CleanUp();
+
+  if (!IsWgcSupported()) {
+    LOG_ERROR("WGC not supported");
+    return 2;
+  }
+
+  monitor_ = GetPrimaryMonitor();
+
+  display_info_list_ = gs_display_list;
+
+  if (display_info_list_.empty()) {
+    LOG_ERROR("No display found");
+    return -1;
+  }
+
+  if (preferred_monitor_index < 0 ||
+      preferred_monitor_index >= static_cast<int>(display_info_list_.size())) {
+    preferred_monitor_index = 0;
+  }
+  monitor_index_ = preferred_monitor_index;
+
+  int error = 0;
+  for (int i = 0; i < display_info_list_.size(); i++) {
+    const auto& display = display_info_list_[i];
+    LOG_INFO(
+        "index: {}, display name: {}, is primary: {}, bounds: ({}, {}) - "
+        "({}, {})",
+        i, display.name, (display.is_primary ? "yes" : "no"), display.left,
+        display.top, display.right, display.bottom);
+
+    sessions_.push_back(
+        {std::make_unique<WgcSessionImpl>(i), false, false, false});
+    sessions_.back().session_->RegisterObserver(this);
+    error = sessions_.back().session_->Initialize((HMONITOR)display.handle);
+    if (error != 0) {
+      LOG_ERROR("WGC: initialize session {} failed, ret={}", i, error);
+      CleanUp();
+      return error;
+    }
+    sessions_[i].inited_ = true;
+  }
+
+  LOG_INFO("Default on monitor {}:{}", monitor_index_,
+           display_info_list_[monitor_index_].name);
+
+  if (initial_monitor_index_ < 0 ||
+      initial_monitor_index_ >= static_cast<int>(display_info_list_.size())) {
+    initial_monitor_index_ = monitor_index_;
+  }
+  inited_ = true;
+  return 0;
+}
+
+int ScreenCapturerWgc::Destroy() {
+  CleanUp();
+  return 0;
+}
+
+int ScreenCapturerWgc::Start(bool show_cursor) {
+  if (running_ == true) {
+    LOG_ERROR("Screen capturer already running");
+    return 0;
+  }
+
+  if (inited_ == false) {
+    const int ret = RebuildSessions(monitor_index_);
+    if (ret != 0) {
+      LOG_ERROR("Screen capturer not inited");
+      return ret;
+    }
+  }
+
+  int ret = StartSessions(show_cursor);
+  if (ret == 0) {
+    return 0;
+  }
+
+  LOG_WARN("WGC: start failed, rebuilding sessions");
+  ret = RebuildSessions(monitor_index_);
+  if (ret != 0) {
+    return ret;
+  }
+  return StartSessions(show_cursor);
+}
+
+int ScreenCapturerWgc::StartSessions(bool show_cursor) {
+  bool any_started = false;
+  bool active_started = false;
+  int last_error = 0;
+  int active_monitor = monitor_index_;
+  if (active_monitor < 0 ||
+      active_monitor >= static_cast<int>(sessions_.size())) {
+    active_monitor = 0;
+    monitor_index_ = 0;
+  }
+  for (int i = 0; i < static_cast<int>(sessions_.size()); i++) {
+    if (sessions_[i].inited_ == false) {
+      LOG_ERROR("Session {} not inited", i);
+      continue;
+    }
+
+    if (sessions_[i].running_) {
+      LOG_ERROR("Session {} is already running", i);
+    } else {
+      int ret = sessions_[i].session_->Start(show_cursor);
+      if (ret != 0) {
+        LOG_ERROR("Session {} start failed, ret={}", i, ret);
+        last_error = ret;
+        continue;
+      }
+
+      if (i != active_monitor) {
+        sessions_[i].session_->Pause();
+        sessions_[i].paused_ = true;
+      } else {
+        sessions_[i].session_->Resume();
+        sessions_[i].paused_ = false;
+      }
+      sessions_[i].running_ = true;
+      any_started = true;
+      if (i == active_monitor) {
+        active_started = true;
+      }
+    }
+  }
+
+  running_ = active_started;
+  if (!active_started) {
+    LOG_ERROR("WGC: active session did not start successfully");
+    Stop();
+    return last_error != 0 ? last_error : -1;
+  }
+  if (!any_started) {
+    LOG_ERROR("WGC: no session started successfully");
+    return last_error != 0 ? last_error : -1;
+  }
+  return 0;
+}
+
+int ScreenCapturerWgc::Pause(int monitor_index) {
+  if (monitor_index >= sessions_.size() || monitor_index < 0) {
+    LOG_ERROR("Invalid session index: {}", monitor_index);
+    return -1;
+  }
+
+  if (!sessions_[monitor_index].paused_) {
+    sessions_[monitor_index].session_->Pause();
+    sessions_[monitor_index].paused_ = true;
+    LOG_INFO("Pausing session {}", monitor_index);
+  }
+  return 0;
+}
+
+int ScreenCapturerWgc::Resume(int monitor_index) {
+  if (monitor_index >= sessions_.size() || monitor_index < 0) {
+    LOG_ERROR("Invalid session index: {}", monitor_index);
+    return -1;
+  }
+
+  if (sessions_[monitor_index].paused_) {
+    sessions_[monitor_index].session_->Resume();
+    sessions_[monitor_index].paused_ = false;
+    LOG_INFO("Resuming session {}", monitor_index);
+  }
+  return 0;
+}
+
+int ScreenCapturerWgc::Stop() {
+  running_ = false;
+
+  for (int i = 0; i < sessions_.size(); i++) {
+    if (sessions_[i].running_) {
+      sessions_[i].session_->Stop();
+      sessions_[i].running_ = false;
+    }
+  }
+
+  return 0;
+}
+
+int ScreenCapturerWgc::SwitchTo(int monitor_index) {
+  if (monitor_index_ == monitor_index) {
+    LOG_INFO("Already on monitor {}:{}", monitor_index_ + 1,
+             display_info_list_[monitor_index_].name);
+    return 0;
+  }
+
+  if (monitor_index < 0 || monitor_index >= static_cast<int>(display_info_list_.size())) {
+    LOG_ERROR("Invalid monitor index: {}", monitor_index);
+    return -1;
+  }
+
+  if (!sessions_[monitor_index].inited_) {
+    LOG_ERROR("Monitor {} not inited", monitor_index);
+    return -1;
+  }
+
+  Pause(monitor_index_);
+
+  monitor_index_ = monitor_index;
+  LOG_INFO("Switching to monitor {}:{}", monitor_index_,
+           display_info_list_[monitor_index_].name);
+
+  Resume(monitor_index);
+
+  return 0;
+}
+
+int ScreenCapturerWgc::ResetToInitialMonitor() {
+  if (display_info_list_.empty()) return -1;
+  if (initial_monitor_index_ < 0 ||
+      initial_monitor_index_ >= static_cast<int>(display_info_list_.size())) {
+    return -1;
+  }
+  if (monitor_index_ == initial_monitor_index_) {
+    return 0;
+  }
+  if (running_) {
+    Pause(monitor_index_);
+  }
+  monitor_index_ = initial_monitor_index_;
+  LOG_INFO("Reset to initial monitor {}:{}", monitor_index_,
+           display_info_list_[monitor_index_].name);
+  if (running_) {
+    Resume(monitor_index_);
+  }
+  return 0;
+}
+void ScreenCapturerWgc::OnFrame(const WgcSession::wgc_session_frame& frame,
+                                int id) {
+  if (!running_ || !on_data_) {
+    return;
+  }
+
+  std::lock_guard<std::mutex> lock(frame_mutex_);
+
+  if (on_data_) {
+    if (id < 0 || id >= static_cast<int>(display_info_list_.size())) {
+      LOG_ERROR("WGC OnFrame invalid display index: {}", id);
+      return;
+    }
+
+    if (!frame.data || frame.row_pitch == 0) {
+      LOG_ERROR("WGC OnFrame received invalid frame: data={}, row_pitch={}",
+                (void*)frame.data, frame.row_pitch);
+      return;
+    }
+
+    // calculate the maximum width that can be contained in one row according to
+    // row_pitch (BGRA: 4 bytes per pixel), and take the minimum with logical
+    // width to avoid out-of-bounds access.
+    unsigned int max_width_by_pitch = frame.row_pitch / 4u;
+    int logical_width = static_cast<int>(
+        frame.width < max_width_by_pitch ? frame.width : max_width_by_pitch);
+
+    // libyuv::ARGBToNV12 requires even width/height
+    int even_width = logical_width & ~1;
+    int even_height = static_cast<int>(frame.height) & ~1;
+
+    if (even_width <= 0 || even_height <= 0) {
+      LOG_ERROR(
+          "WGC OnFrame invalid frame size after adjust: width={} "
+          "(frame.width={}, max_by_pitch={}), height={}",
+          logical_width, frame.width, max_width_by_pitch, frame.height);
+      return;
+    }
+
+    int nv12_size = even_width * even_height * 3 / 2;
+
+    if (!nv12_frame_ || nv12_width_ != even_width ||
+        nv12_height_ != even_height) {
+      delete[] nv12_frame_;
+      nv12_frame_ = new unsigned char[nv12_size];
+      nv12_width_ = even_width;
+      nv12_height_ = even_height;
+    }
+
+    libyuv::ARGBToNV12((const uint8_t*)frame.data,
+                       static_cast<int>(frame.row_pitch), (uint8_t*)nv12_frame_,
+                       even_width,
+                       (uint8_t*)(nv12_frame_ + even_width * even_height),
+                       even_width, even_width, even_height);
+
+    const std::string stream_id = MakeDisplayStreamId(id);
+    on_data_(nv12_frame_, nv12_size, even_width, even_height,
+             stream_id.c_str());
+  }
+}
+
+void ScreenCapturerWgc::CleanUp() {
+  running_ = false;
+  for (auto& session : sessions_) {
+    if (session.session_) {
+      session.session_->Stop();
+    }
+  }
+  sessions_.clear();
+  display_info_list_.clear();
+  gs_display_list.clear();
+  monitor_ = nullptr;
+  inited_ = false;
+}
+}  // namespace crossdesk

apps/desktop/src/platform/windows/screen_capturer/screen_capturer_wgc.h

@@ -0,0 +1,79 @@
+#ifndef _SCREEN_CAPTURER_WGC_H_
+#define _SCREEN_CAPTURER_WGC_H_
+
+#include <atomic>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "screen_capturer.h"
+#include "wgc_session.h"
+#include "wgc_session_impl.h"
+
+namespace crossdesk {
+
+class ScreenCapturerWgc : public ScreenCapturer,
+                          public WgcSession::wgc_session_observer {
+ public:
+  ScreenCapturerWgc();
+  ~ScreenCapturerWgc();
+
+ public:
+  bool IsWgcSupported();
+
+  int Init(const int fps, cb_desktop_data cb) override;
+  int Destroy() override;
+  int Start(bool show_cursor) override;
+  int Stop() override;
+
+  int Pause(int monitor_index) override;
+  int Resume(int monitor_index) override;
+
+  std::vector<DisplayInfo> GetDisplayInfoList() { return display_info_list_; }
+
+  int SwitchTo(int monitor_index);
+  int ResetToInitialMonitor() override;
+
+  void OnFrame(const WgcSession::wgc_session_frame& frame, int id);
+
+ protected:
+  void CleanUp();
+  int RebuildSessions(int preferred_monitor_index);
+  int StartSessions(bool show_cursor);
+
+ private:
+  HMONITOR monitor_;
+  MONITORINFOEX monitor_info_;
+  std::vector<DisplayInfo> display_info_list_;
+  int monitor_index_ = 0;
+  int initial_monitor_index_ = 0;
+
+ private:
+  class WgcSessionInfo {
+   public:
+    std::unique_ptr<WgcSession> session_;
+    bool inited_ = false;
+    bool running_ = false;
+    bool paused_ = false;
+  };
+
+  std::vector<WgcSessionInfo> sessions_;
+
+  std::atomic_bool running_{false};
+  std::atomic_bool inited_{false};
+
+  int fps_ = 60;
+
+  cb_desktop_data on_data_ = nullptr;
+
+  unsigned char* nv12_frame_ = nullptr;
+  unsigned char* nv12_frame_scaled_ = nullptr;
+  int nv12_width_ = 0;
+  int nv12_height_ = 0;
+
+  std::mutex frame_mutex_;
+};
+}  // namespace crossdesk
+#endif