[fix] fix macOS remote keyboard modifier injection, fixes #81

.github/workflows/build.yml

@@ -242,6 +242,11 @@ jobs:
           cd "${{ github.workspace }}\scripts\windows"
           makensis /DVERSION=$env:VERSION_NUM nsis_script.nsi
 
+      - name: Build Portable CrossDesk
+        run: |
+          xmake f --CROSSDESK_VERSION=${{ env.VERSION_NUM }} --USE_CUDA=true --CROSSDESK_PORTABLE=true -y
+          xmake b -vy crossdesk
+
       - name: Package Portable
         shell: pwsh
         run: |

src/device_controller/device_controller.h

@@ -7,9 +7,10 @@
 #ifndef _DEVICE_CONTROLLER_H_
 #define _DEVICE_CONTROLLER_H_
 
-#include <cstring>
 #include <stdio.h>
 
+#include <cstdint>
+#include <cstring>
 #include <nlohmann/json.hpp>
 #include <string>
 
@@ -49,6 +50,8 @@ typedef struct {
 
 typedef struct {
   size_t key_value;
+  uint32_t scan_code;
+  bool extended;
   KeyFlag flag;
 } Key;
 
@@ -103,7 +106,10 @@ struct RemoteAction {
             {"x", a.m.x}, {"y", a.m.y}, {"s", a.m.s}, {"flag", a.m.flag}};
         break;
       case ControlType::keyboard:
-        j["keyboard"] = {{"key_value", a.k.key_value}, {"flag", a.k.flag}};
+        j["keyboard"] = {{"key_value", a.k.key_value},
+                         {"scan_code", a.k.scan_code},
+                         {"extended", a.k.extended},
+                         {"flag", a.k.flag}};
         break;
       case ControlType::audio_capture:
         j["audio_capture"] = a.a;
@@ -113,8 +119,7 @@ struct RemoteAction {
         break;
       case ControlType::service_status:
         j["service_status"] = {{"available", a.ss.available},
-                               {"interactive_stage",
-                                a.ss.interactive_stage}};
+                               {"interactive_stage", a.ss.interactive_stage}};
         break;
       case ControlType::service_command:
         j["service_command"] = {{"flag", a.c.flag}};
@@ -152,6 +157,9 @@ struct RemoteAction {
           break;
         case ControlType::keyboard:
           out.k.key_value = j.at("keyboard").at("key_value").get<size_t>();
+          out.k.scan_code =
+              j.at("keyboard").value("scan_code", static_cast<uint32_t>(0));
+          out.k.extended = j.at("keyboard").value("extended", false);
           out.k.flag = (KeyFlag)j.at("keyboard").at("flag").get<int>();
           break;
         case ControlType::audio_capture:
@@ -164,16 +172,15 @@ struct RemoteAction {
           const auto& service_status_json = j.at("service_status");
           out.ss.available = service_status_json.value("available", false);
           std::string interactive_stage =
-            service_status_json.value("interactive_stage", std::string());
+              service_status_json.value("interactive_stage", std::string());
           std::strncpy(out.ss.interactive_stage, interactive_stage.c_str(),
-                 sizeof(out.ss.interactive_stage) - 1);
-          out.ss.interactive_stage[sizeof(out.ss.interactive_stage) - 1] =
-            '\0';
+                       sizeof(out.ss.interactive_stage) - 1);
+          out.ss.interactive_stage[sizeof(out.ss.interactive_stage) - 1] = '\0';
           break;
         }
         case ControlType::service_command:
           out.c.flag = static_cast<ServiceCommandFlag>(
-            j.at("service_command").at("flag").get<int>());
+              j.at("service_command").at("flag").get<int>());
           break;
         case ControlType::host_infomation: {
           std::string host_name =
@@ -212,8 +219,8 @@ struct RemoteAction {
   }
 };
 
-// int key_code, bool is_down
-typedef void (*OnKeyAction)(int, bool, void*);
+// int key_code, bool is_down, uint32_t scan_code, bool extended
+typedef void (*OnKeyAction)(int, bool, uint32_t, bool, void*);
 
 class DeviceController {
  public:

src/device_controller/keyboard/linux/keyboard_capturer.cpp

@@ -6,6 +6,7 @@
 #include "keyboard_converter.h"
 #include "platform.h"
 #include "rd_log.h"
+#include "windows_key_metadata.h"
 
 namespace crossdesk {
 
@@ -35,9 +36,12 @@ static int KeyboardEventHandler(Display* display, XEvent* event) {
 
     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, g_user_ptr);
+      g_on_key_action(key_code, is_key_down, scan_code, extended, g_user_ptr);
     }
   }
   return 0;
@@ -146,7 +150,10 @@ int KeyboardCapturer::Unhook() {
   return 0;
 }
 
-int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down) {
+int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down,
+                                          uint32_t scan_code, bool extended) {
+  (void)scan_code;
+  (void)extended;
   if (IsWaylandSession()) {
     if (!use_wayland_portal_ && !wayland_init_attempted_) {
       wayland_init_attempted_ = true;
@@ -154,12 +161,14 @@ int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down) {
         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");
+        LOG_WARN(
+            "Wayland keyboard control init failed, falling back to X11/XTest "
+            "backend");
       }
     }
 
     if (use_wayland_portal_) {
-      return SendWaylandKeyboardCommand(key_code, is_down);
+      return SendWaylandKeyboardCommand(key_code, is_down, scan_code, extended);
     }
   }
 

src/device_controller/keyboard/linux/keyboard_capturer.h

@@ -32,12 +32,15 @@ class KeyboardCapturer : public DeviceController {
  public:
   virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
   virtual int Unhook();
-  virtual int SendKeyboardCommand(int key_code, bool is_down);
+  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);
+  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,

src/device_controller/keyboard/linux/keyboard_capturer_wayland.cpp

@@ -575,8 +575,12 @@ void KeyboardCapturer::CleanupWaylandPortal() {
   wayland_session_handle_.clear();
 }
 
-int KeyboardCapturer::SendWaylandKeyboardCommand(int key_code, bool is_down) {
+int KeyboardCapturer::SendWaylandKeyboardCommand(int key_code, bool is_down,
+                                                 uint32_t scan_code,
+                                                 bool extended) {
 #if defined(CROSSDESK_HAS_WAYLAND_CAPTURER) && CROSSDESK_HAS_WAYLAND_CAPTURER
+  (void)scan_code;
+  (void)extended;
   if (!dbus_connection_ || wayland_session_handle_.empty()) {
     return -1;
   }
@@ -613,6 +617,8 @@ int KeyboardCapturer::SendWaylandKeyboardCommand(int key_code, bool is_down) {
 #else
   (void)key_code;
   (void)is_down;
+  (void)scan_code;
+  (void)extended;
   return -1;
 #endif
 }

src/device_controller/keyboard/mac/keyboard_capturer.cpp

@@ -119,7 +119,7 @@ CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type,
         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, g_user_ptr);
+      g_on_key_action(vk_code, is_key_down, 0, false, g_user_ptr);
     }
   } else if (type == kCGEventFlagsChanged) {
     CGEventFlags current_flags = CGEventGetFlags(event);
@@ -135,35 +135,40 @@ CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type,
     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_, g_user_ptr);
+      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_, g_user_ptr);
+      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_, g_user_ptr);
+      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_, g_user_ptr);
+      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_, g_user_ptr);
+      g_on_key_action(vk_code, keyboard_capturer->command_flag_, 0, false,
+                      g_user_ptr);
     }
   }
 
@@ -264,7 +269,30 @@ inline bool IsFunctionKey(int key_code) {
   }
 }
 
-int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down) {
+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 KeyboardCapturer::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);
@@ -273,7 +301,7 @@ int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down) {
       return -1;
     }
 
-    CGEventSetFlags(event, 0);
+    CGEventSetFlags(event, ToCGEventFlags(injected_flags));
     CGEventPost(kCGHIDEventTap, event);
     CFRelease(event);
 

src/device_controller/keyboard/mac/keyboard_capturer.h

@@ -10,6 +10,7 @@
 #include <ApplicationServices/ApplicationServices.h>
 
 #include "device_controller.h"
+#include "macos_keyboard_modifier_state.h"
 
 namespace crossdesk {
 
@@ -21,7 +22,9 @@ class KeyboardCapturer : public DeviceController {
  public:
   virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
   virtual int Unhook();
-  virtual int SendKeyboardCommand(int key_code, bool is_down);
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false);
 
  private:
   CFMachPortRef event_tap_ = nullptr;
@@ -34,6 +37,7 @@ class KeyboardCapturer : public DeviceController {
   bool option_flag_ = false;
   bool command_flag_ = false;
   int fn_key_code_ = 0x3F;
+  MacKeyboardModifierState injected_modifier_state_;
 };
 }  // namespace crossdesk
 #endif

src/device_controller/keyboard/windows/keyboard_capturer.cpp

@@ -7,14 +7,56 @@ namespace crossdesk {
 static OnKeyAction g_on_key_action = nullptr;
 static void* g_user_ptr = nullptr;
 
+static int NormalizeModifierVkCode(const KBDLLHOOKSTRUCT* kb_data) {
+  if (kb_data == nullptr) {
+    return -1;
+  }
+
+  if (kb_data->vkCode != VK_SHIFT && kb_data->vkCode != VK_CONTROL &&
+      kb_data->vkCode != VK_MENU) {
+    return static_cast<int>(kb_data->vkCode);
+  }
+
+  UINT scan_code = static_cast<UINT>(kb_data->scanCode & 0xFF);
+  if ((kb_data->flags & LLKHF_EXTENDED) != 0) {
+    scan_code |= 0xE000;
+  }
+
+  const UINT normalized_vk = MapVirtualKeyW(scan_code, MAPVK_VSC_TO_VK_EX);
+  if (normalized_vk != 0) {
+    return static_cast<int>(normalized_vk);
+  }
+
+  return static_cast<int>(kb_data->vkCode);
+}
+
+static 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;
+  }
+}
+
 LRESULT CALLBACK KeyboardProc(int nCode, WPARAM wParam, LPARAM lParam) {
   if (nCode == HC_ACTION && g_on_key_action) {
     KBDLLHOOKSTRUCT* kbData = reinterpret_cast<KBDLLHOOKSTRUCT*>(lParam);
+    const int key_code = NormalizeModifierVkCode(kbData);
 
     if (wParam == WM_KEYDOWN || wParam == WM_SYSKEYDOWN) {
-      g_on_key_action(kbData->vkCode, true, g_user_ptr);
+      g_on_key_action(key_code, true, kbData->scanCode,
+                      (kbData->flags & LLKHF_EXTENDED) != 0, g_user_ptr);
     } else if (wParam == WM_KEYUP || wParam == WM_SYSKEYUP) {
-      g_on_key_action(kbData->vkCode, false, g_user_ptr);
+      g_on_key_action(key_code, false, kbData->scanCode,
+                      (kbData->flags & LLKHF_EXTENDED) != 0, g_user_ptr);
     }
     return 1;
   }
@@ -49,20 +91,40 @@ int KeyboardCapturer::Unhook() {
 }
 
 // apply remote keyboard commands to the local machine
-int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down) {
+int KeyboardCapturer::SendKeyboardCommand(int key_code, bool is_down,
+                                          uint32_t scan_code, bool extended) {
   INPUT input = {0};
   input.type = INPUT_KEYBOARD;
-  input.ki.wVk = (WORD)key_code;
 
-  const UINT scan_code =
-      MapVirtualKeyW(static_cast<UINT>(key_code), MAPVK_VK_TO_VSC_EX);
-  if (scan_code != 0) {
+  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 ((scan_code & 0xFF00) != 0) {
+    if (extended) {
       input.ki.dwFlags |= KEYEVENTF_EXTENDEDKEY;
     }
+  } else {
+    input.ki.wVk = (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) {

src/device_controller/keyboard/windows/keyboard_capturer.h

@@ -21,7 +21,9 @@ class KeyboardCapturer : public DeviceController {
  public:
   virtual int Hook(OnKeyAction on_key_action, void* user_ptr);
   virtual int Unhook();
-  virtual int SendKeyboardCommand(int key_code, bool is_down);
+  virtual int SendKeyboardCommand(int key_code, bool is_down,
+                                  uint32_t scan_code = 0,
+                                  bool extended = false);
 
  private:
   HHOOK keyboard_hook_ = nullptr;

src/device_controller/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

src/device_controller/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

src/gui/render.cpp

@@ -812,10 +812,11 @@ int Render::StartKeyboardCapturer() {
   }
 
   int keyboard_capturer_init_ret = keyboard_capturer_->Hook(
-      [](int key_code, bool is_down, void* user_ptr) {
+      [](int key_code, bool is_down, uint32_t scan_code, bool extended,
+         void* user_ptr) {
         if (user_ptr) {
           Render* render = (Render*)user_ptr;
-          render->SendKeyCommand(key_code, is_down);
+          render->SendKeyCommand(key_code, is_down, scan_code, extended);
         }
       },
       this);

src/gui/render.h

@@ -339,7 +339,8 @@ class Render {
   static void FreeRemoteAction(RemoteAction& action);
 
  private:
-  int SendKeyCommand(int key_code, bool is_down);
+  int SendKeyCommand(int key_code, bool is_down, uint32_t scan_code = 0,
+                     bool extended = false);
   static bool IsModifierVkKey(int key_code);
   void TrackPressedKeyState(int key_code, bool is_down);
   void ForceReleasePressedKeys();

src/gui/render_callback.cpp

@@ -17,6 +17,7 @@
 #include "platform.h"
 #include "rd_log.h"
 #include "render.h"
+#include "windows_key_metadata.h"
 #if _WIN32
 #include "interactive_state.h"
 #include "service_host.h"
@@ -28,34 +29,66 @@ namespace crossdesk {
 
 namespace {
 
-int TranslateSdlKeypadScancodeToVk(SDL_Scancode scancode) {
-  switch (scancode) {
+int TranslateSdlKeypadScancodeToVk(const SDL_KeyboardEvent& event) {
+  const bool numlock_enabled = (event.mod & SDL_KMOD_NUM) != 0;
+
+  switch (event.scancode) {
     case SDL_SCANCODE_NUMLOCKCLEAR:
       return 0x90;
     case SDL_SCANCODE_KP_ENTER:
       return 0x0D;
     case SDL_SCANCODE_KP_0:
+      if (!numlock_enabled) {
+        return 0x2D;
+      }
       return 0x60;
     case SDL_SCANCODE_KP_1:
+      if (!numlock_enabled) {
+        return 0x23;
+      }
       return 0x61;
     case SDL_SCANCODE_KP_2:
+      if (!numlock_enabled) {
+        return 0x28;
+      }
       return 0x62;
     case SDL_SCANCODE_KP_3:
+      if (!numlock_enabled) {
+        return 0x22;
+      }
       return 0x63;
     case SDL_SCANCODE_KP_4:
+      if (!numlock_enabled) {
+        return 0x25;
+      }
       return 0x64;
     case SDL_SCANCODE_KP_5:
       return 0x65;
     case SDL_SCANCODE_KP_6:
+      if (!numlock_enabled) {
+        return 0x27;
+      }
       return 0x66;
     case SDL_SCANCODE_KP_7:
+      if (!numlock_enabled) {
+        return 0x24;
+      }
       return 0x67;
     case SDL_SCANCODE_KP_8:
+      if (!numlock_enabled) {
+        return 0x26;
+      }
       return 0x68;
     case SDL_SCANCODE_KP_9:
+      if (!numlock_enabled) {
+        return 0x21;
+      }
       return 0x69;
     case SDL_SCANCODE_KP_PERIOD:
     case SDL_SCANCODE_KP_COMMA:
+      if (!numlock_enabled) {
+        return 0x2E;
+      }
       return 0x6E;
     case SDL_SCANCODE_KP_DIVIDE:
       return 0x6F;
@@ -73,7 +106,7 @@ int TranslateSdlKeypadScancodeToVk(SDL_Scancode scancode) {
 }
 
 int TranslateSdlKeyboardEventToVk(const SDL_KeyboardEvent& event) {
-  const int keypad_key_code = TranslateSdlKeypadScancodeToVk(event.scancode);
+  const int keypad_key_code = TranslateSdlKeypadScancodeToVk(event);
   if (keypad_key_code >= 0) {
     return keypad_key_code;
   }
@@ -200,6 +233,49 @@ int TranslateSdlKeyboardEventToVk(const SDL_KeyboardEvent& event) {
   }
 }
 
+int NormalizeWindowsModifierVk(int key_code, uint32_t scan_code,
+                               bool extended) {
+#if _WIN32
+  if (key_code != 0x10 && key_code != 0x11 && key_code != 0x12) {
+    return key_code;
+  }
+
+  UINT scan_code_with_prefix = static_cast<UINT>(scan_code & 0xFF);
+  if (extended) {
+    scan_code_with_prefix |= 0xE000;
+  }
+
+  const UINT normalized_vk =
+      MapVirtualKeyW(scan_code_with_prefix, MAPVK_VSC_TO_VK_EX);
+  return normalized_vk != 0 ? static_cast<int>(normalized_vk) : key_code;
+#else
+  (void)scan_code;
+  (void)extended;
+  return key_code;
+#endif
+}
+
+void PopulateWindowsKeyMetadataFromVk(int key_code, uint32_t* scan_code_out,
+                                      bool* extended_out) {
+  if (scan_code_out == nullptr || extended_out == nullptr) {
+    return;
+  }
+
+#if _WIN32
+  const UINT scan_code =
+      MapVirtualKeyW(static_cast<UINT>(key_code), MAPVK_VK_TO_VSC_EX);
+  if (scan_code == 0) {
+    LookupWindowsKeyMetadataFromVk(key_code, scan_code_out, extended_out);
+    return;
+  }
+
+  *scan_code_out = static_cast<uint32_t>(scan_code & 0xFF);
+  *extended_out = (scan_code & 0xFF00) != 0;
+#else
+  LookupWindowsKeyMetadataFromVk(key_code, scan_code_out, extended_out);
+#endif
+}
+
 #if _WIN32
 constexpr uint32_t kSecureDesktopInputLogIntervalMs = 2000;
 
@@ -353,15 +429,26 @@ void Render::ForceReleasePressedKeys() {
   }
 }
 
-int Render::SendKeyCommand(int key_code, bool is_down) {
-  RemoteAction remote_action;
+int Render::SendKeyCommand(int key_code, bool is_down, uint32_t scan_code,
+                           bool extended) {
+  RemoteAction remote_action{};
   remote_action.type = ControlType::keyboard;
   if (is_down) {
     remote_action.k.flag = KeyFlag::key_down;
   } else {
     remote_action.k.flag = KeyFlag::key_up;
   }
+
+  if (scan_code == 0) {
+    PopulateWindowsKeyMetadataFromVk(key_code, &scan_code, &extended);
+  }
+#if _WIN32
+  key_code = NormalizeWindowsModifierVk(key_code, scan_code, extended);
+#endif
+
   remote_action.k.key_value = key_code;
+  remote_action.k.scan_code = scan_code;
+  remote_action.k.extended = extended;
 
   std::string target_id = controlled_remote_id_.empty() ? focused_remote_id_
                                                         : controlled_remote_id_;
@@ -1048,8 +1135,9 @@ void Render::OnReceiveDataBufferCb(const char* data, size_t size,
       if (remote_action.type == ControlType::keyboard) {
         const int key_code = static_cast<int>(remote_action.k.key_value);
         const bool is_down = remote_action.k.flag == KeyFlag::key_down;
-        const std::string response =
-            SendCrossDeskSecureDesktopKeyInput(key_code, is_down, 1000);
+        const std::string response = SendCrossDeskSecureDesktopKeyInput(
+            key_code, is_down, remote_action.k.scan_code,
+            remote_action.k.extended, 1000);
         auto json = nlohmann::json::parse(response, nullptr, false);
         if (json.is_discarded() || !json.value("ok", false)) {
           LogSecureDesktopInputBlocked(
@@ -1076,7 +1164,8 @@ void Render::OnReceiveDataBufferCb(const char* data, size_t size,
                render->keyboard_capturer_) {
       render->keyboard_capturer_->SendKeyboardCommand(
           (int)remote_action.k.key_value,
-          remote_action.k.flag == KeyFlag::key_down);
+          remote_action.k.flag == KeyFlag::key_down, remote_action.k.scan_code,
+          remote_action.k.extended);
     } else if (remote_action.type == ControlType::display_id &&
                render->screen_capturer_) {
       render->selected_display_ = remote_action.d;

src/gui/windows/about_window.cpp

@@ -104,7 +104,7 @@ int Render::AboutWindow() {
     ImGui::SetCursorPosX(about_window_width * 0.1f);
     ImGui::Text("%s", text.c_str());
 
-    if (0) {
+    if (update_available_ && show_new_version_icon_in_menu_) {
       std::string new_version_available =
           localization::new_version_available[localization_language_index_] +
           ": ";

src/gui/windows/update_notification_window.cpp

@@ -92,7 +92,7 @@ int Render::UpdateNotificationWindow() {
     ImGui::SetWindowFontScale(0.55f);
     std::string title =
         localization::new_version_available[localization_language_index_] +
-        ": v" + latest_version_;
+        ": " + latest_version_;
     ImGui::Text("%s", title.c_str());
     ImGui::SetWindowFontScale(0.1f);
 

src/path_manager/path_manager.cpp

@@ -1,12 +1,98 @@
 #include "path_manager.h"
 
+#include <cstdint>
 #include <cstdlib>
+#include <vector>
+
+#ifndef CROSSDESK_PORTABLE
+#define CROSSDESK_PORTABLE 0
+#endif
+
+#if CROSSDESK_PORTABLE
+#if defined(__APPLE__)
+#include <mach-o/dyld.h>
+#elif !defined(_WIN32)
+#include <limits.h>
+#include <unistd.h>
+#endif
+#endif
+
+namespace {
+
+#if CROSSDESK_PORTABLE
+std::filesystem::path GetExecutableDirectory() {
+#ifdef _WIN32
+  std::vector<wchar_t> buffer(MAX_PATH);
+  while (true) {
+    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)
+          .parent_path();
+    }
+    if (buffer.size() >= 32768) {
+      return {};
+    }
+    buffer.resize(buffer.size() * 2);
+  }
+#elif defined(__APPLE__)
+  uint32_t size = 0;
+  _NSGetExecutablePath(nullptr, &size);
+  std::vector<char> buffer(size + 1);
+  if (_NSGetExecutablePath(buffer.data(), &size) != 0) {
+    return {};
+  }
+
+  std::error_code ec;
+  std::filesystem::path executable =
+      std::filesystem::weakly_canonical(buffer.data(), ec);
+  if (ec) {
+    executable = buffer.data();
+  }
+  return executable.parent_path();
+#else
+  std::vector<char> buffer(PATH_MAX);
+  while (true) {
+    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);
+  }
+#endif
+}
+
+std::filesystem::path GetPortableRootPath() {
+  std::filesystem::path executable_dir = GetExecutableDirectory();
+  if (!executable_dir.empty()) {
+    return executable_dir;
+  }
+
+  std::error_code ec;
+  std::filesystem::path current = std::filesystem::current_path(ec);
+  return ec ? std::filesystem::path(".") : current;
+}
+#endif
+
+}  // namespace
 
 namespace crossdesk {
 
 PathManager::PathManager(const std::string& app_name) : app_name_(app_name) {}
 
 std::filesystem::path PathManager::GetConfigPath() {
+#if CROSSDESK_PORTABLE
+  return GetPortableRootPath() / "data";
+#else
 #ifdef _WIN32
   return GetKnownFolder(FOLDERID_RoamingAppData) / app_name_;
 #elif __APPLE__
@@ -14,9 +100,13 @@ std::filesystem::path PathManager::GetConfigPath() {
 #else
   return GetEnvOrDefault("XDG_CONFIG_HOME", GetHome() + "/.config") / app_name_;
 #endif
+#endif
 }
 
 std::filesystem::path PathManager::GetCachePath() {
+#if CROSSDESK_PORTABLE
+  return GetPortableRootPath() / "data";
+#else
 #ifdef _WIN32
 #ifdef CROSSDESK_DEBUG
   return "cache";
@@ -28,9 +118,13 @@ std::filesystem::path PathManager::GetCachePath() {
 #else
   return GetEnvOrDefault("XDG_CACHE_HOME", GetHome() + "/.cache") / app_name_;
 #endif
+#endif
 }
 
 std::filesystem::path PathManager::GetLogPath() {
+#if CROSSDESK_PORTABLE
+  return GetPortableRootPath() / "logs";
+#else
 #ifdef _WIN32
   return GetKnownFolder(FOLDERID_LocalAppData) / app_name_ / "logs";
 #elif __APPLE__
@@ -38,6 +132,7 @@ std::filesystem::path PathManager::GetLogPath() {
 #else
   return GetCachePath() / "logs";
 #endif
+#endif
 }
 
 bool PathManager::CreateDirectories(const std::filesystem::path& p) {
@@ -93,4 +188,4 @@ std::filesystem::path PathManager::GetEnvOrDefault(const char* env_var,
 
   return std::filesystem::path(def);
 }
-}  // namespace crossdesk
+}  // namespace crossdesk

src/service/windows/service_host.cpp

@@ -313,10 +313,12 @@ std::string QueryNamedPipeMessage(const std::wstring& pipe_name,
   return std::string(buffer, buffer + bytes_read);
 }
 
-std::string BuildSecureDesktopKeyboardIpcCommand(int key_code, bool is_down) {
+std::string BuildSecureDesktopKeyboardIpcCommand(int key_code, bool is_down,
+                                                 uint32_t scan_code,
+                                                 bool extended) {
   std::ostringstream stream;
   stream << kSecureDesktopKeyboardIpcCommandPrefix << key_code << ":"
-         << (is_down ? 1 : 0);
+         << (is_down ? 1 : 0) << ":" << scan_code << ":" << (extended ? 1 : 0);
   return stream.str();
 }
 
@@ -328,20 +330,27 @@ std::string BuildSecureDesktopMouseIpcCommand(int x, int y, int wheel,
   return stream.str();
 }
 
-std::string BuildSecureInputHelperKeyboardCommand(int key_code, bool is_down) {
+std::string BuildSecureInputHelperKeyboardCommand(int key_code, bool is_down,
+                                                  uint32_t scan_code,
+                                                  bool extended) {
   std::ostringstream stream;
   stream << kCrossDeskSecureInputKeyboardCommandPrefix << key_code << ":"
-         << (is_down ? 1 : 0);
+         << (is_down ? 1 : 0) << ":" << scan_code << ":" << (extended ? 1 : 0);
   return stream.str();
 }
 
 bool ParseSecureDesktopKeyboardIpcCommand(const std::string& command,
-                                          int* key_code_out,
-                                          bool* is_down_out) {
-  if (key_code_out == nullptr || is_down_out == nullptr) {
+                                          int* key_code_out, bool* is_down_out,
+                                          uint32_t* scan_code_out,
+                                          bool* extended_out) {
+  if (key_code_out == nullptr || is_down_out == nullptr ||
+      scan_code_out == nullptr || extended_out == nullptr) {
     return false;
   }
 
+  *scan_code_out = 0;
+  *extended_out = false;
+
   if (command.rfind(kSecureDesktopKeyboardIpcCommandPrefix, 0) != 0) {
     return false;
   }
@@ -358,13 +367,46 @@ bool ParseSecureDesktopKeyboardIpcCommand(const std::string& command,
     return false;
   }
 
-  const std::string state = command.substr(separator + 1);
+  const size_t scan_separator = command.find(':', separator + 1);
+  const std::string state =
+      scan_separator == std::string::npos
+          ? command.substr(separator + 1)
+          : command.substr(separator + 1, scan_separator - separator - 1);
   if (state == "1" || state == "down") {
     *is_down_out = true;
+  } else if (state == "0" || state == "up") {
+    *is_down_out = false;
+  } else {
+    return false;
+  }
+
+  if (scan_separator == std::string::npos) {
     return true;
   }
-  if (state == "0" || state == "up") {
-    *is_down_out = false;
+
+  const size_t extended_separator = command.find(':', scan_separator + 1);
+  const std::string scan_code_str =
+      extended_separator == std::string::npos
+          ? command.substr(scan_separator + 1)
+          : command.substr(scan_separator + 1,
+                           extended_separator - scan_separator - 1);
+  try {
+    *scan_code_out = static_cast<uint32_t>(std::stoul(scan_code_str));
+  } catch (...) {
+    return false;
+  }
+
+  if (extended_separator == std::string::npos) {
+    return true;
+  }
+
+  const std::string extended_str = command.substr(extended_separator + 1);
+  if (extended_str == "1" || extended_str == "true") {
+    *extended_out = true;
+    return true;
+  }
+  if (extended_str == "0" || extended_str == "false") {
+    *extended_out = false;
     return true;
   }
   return false;
@@ -1712,8 +1754,12 @@ std::string CrossDeskServiceHost::HandleIpcCommand(const std::string& command) {
   }
   int key_code = 0;
   bool is_down = false;
-  if (ParseSecureDesktopKeyboardIpcCommand(normalized, &key_code, &is_down)) {
-    return SendSecureDesktopKeyboardInput(key_code, is_down);
+  uint32_t scan_code = 0;
+  bool extended = false;
+  if (ParseSecureDesktopKeyboardIpcCommand(normalized, &key_code, &is_down,
+                                           &scan_code, &extended)) {
+    return SendSecureDesktopKeyboardInput(key_code, is_down, scan_code,
+                                          extended);
   }
   return BuildErrorJson("unknown_command");
 }
@@ -1928,8 +1974,8 @@ std::string CrossDeskServiceHost::SendSecureAttentionSequence() {
   return "{\"ok\":true,\"sent\":\"sas\"}";
 }
 
-std::string CrossDeskServiceHost::SendSecureDesktopKeyboardInput(int key_code,
-                                                                 bool is_down) {
+std::string CrossDeskServiceHost::SendSecureDesktopKeyboardInput(
+    int key_code, bool is_down, uint32_t scan_code, bool extended) {
   RefreshSessionState();
   ReapSecureInputHelper();
   EnsureSessionHelper();
@@ -1963,7 +2009,9 @@ std::string CrossDeskServiceHost::SendSecureDesktopKeyboardInput(int key_code,
 
   return QueryNamedPipeMessage(
       GetCrossDeskSecureInputHelperPipeName(target_session_id),
-      BuildSecureInputHelperKeyboardCommand(key_code, is_down), 1000);
+      BuildSecureInputHelperKeyboardCommand(key_code, is_down, scan_code,
+                                            extended),
+      1000);
 }
 
 bool InstallCrossDeskService(const std::wstring& binary_path) {
@@ -2176,9 +2224,12 @@ std::string QueryCrossDeskService(const std::string& command,
 }
 
 std::string SendCrossDeskSecureDesktopKeyInput(int key_code, bool is_down,
+                                               uint32_t scan_code,
+                                               bool extended,
                                                DWORD timeout_ms) {
-  return QueryCrossDeskService(
-      BuildSecureDesktopKeyboardIpcCommand(key_code, is_down), timeout_ms);
+  return QueryCrossDeskService(BuildSecureDesktopKeyboardIpcCommand(
+                                   key_code, is_down, scan_code, extended),
+                               timeout_ms);
 }
 
 std::string SendCrossDeskSecureDesktopMouseInput(int x, int y, int wheel,

src/service/windows/service_host.h

@@ -9,6 +9,7 @@
 
 #include <Windows.h>
 
+#include <cstdint>
 #include <mutex>
 #include <string>
 #include <thread>
@@ -60,7 +61,9 @@ class CrossDeskServiceHost {
   std::string HandleIpcCommand(const std::string& command);
   std::string BuildStatusResponse();
   std::string SendSecureAttentionSequence();
-  std::string SendSecureDesktopKeyboardInput(int key_code, bool is_down);
+  std::string SendSecureDesktopKeyboardInput(int key_code, bool is_down,
+                                             uint32_t scan_code = 0,
+                                             bool extended = false);
 
   static void WINAPI ServiceMain(DWORD argc, LPWSTR* argv);
   static BOOL WINAPI ConsoleControlHandler(DWORD control_type);
@@ -138,6 +141,8 @@ bool StopCrossDeskService(DWORD timeout_ms = 5000);
 std::string QueryCrossDeskService(const std::string& command,
                                   DWORD timeout_ms = 1000);
 std::string SendCrossDeskSecureDesktopKeyInput(int key_code, bool is_down,
+                                               uint32_t scan_code = 0,
+                                               bool extended = false,
                                                DWORD timeout_ms = 1000);
 std::string SendCrossDeskSecureDesktopMouseInput(int x, int y, int wheel,
                                                  int flag,

src/service/windows/session_helper_main.cpp

@@ -485,20 +485,56 @@ bool EnsureThreadDesktop(const wchar_t* desktop_name,
   return true;
 }
 
-int InjectKeyboardInput(int key_code, bool is_down) {
+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;
+  }
+}
+
+int InjectKeyboardInput(int key_code, bool is_down, uint32_t scan_code,
+                        bool extended) {
   INPUT input = {0};
   input.type = INPUT_KEYBOARD;
-  input.ki.wVk = static_cast<WORD>(key_code);
 
-  const UINT scan_code =
-      MapVirtualKeyW(static_cast<UINT>(key_code), MAPVK_VK_TO_VSC_EX);
-  if (scan_code != 0) {
+  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 ((scan_code & 0xFF00) != 0) {
+    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) {
@@ -514,11 +550,17 @@ int InjectKeyboardInput(int key_code, bool is_down) {
 }
 
 bool ParseSecureInputKeyboardCommand(const std::string& command,
-                                     int* key_code_out, bool* is_down_out) {
-  if (key_code_out == nullptr || is_down_out == nullptr) {
+                                     int* key_code_out, bool* is_down_out,
+                                     uint32_t* scan_code_out,
+                                     bool* extended_out) {
+  if (key_code_out == nullptr || is_down_out == nullptr ||
+      scan_code_out == nullptr || extended_out == nullptr) {
     return false;
   }
 
+  *scan_code_out = 0;
+  *extended_out = false;
+
   if (command.rfind(crossdesk::kCrossDeskSecureInputKeyboardCommandPrefix, 0) !=
       0) {
     return false;
@@ -537,13 +579,46 @@ bool ParseSecureInputKeyboardCommand(const std::string& command,
     return false;
   }
 
-  const std::string state = command.substr(separator + 1);
+  const size_t scan_separator = command.find(':', separator + 1);
+  const std::string state =
+      scan_separator == std::string::npos
+          ? command.substr(separator + 1)
+          : command.substr(separator + 1, scan_separator - separator - 1);
   if (state == "1" || state == "down") {
     *is_down_out = true;
+  } else if (state == "0" || state == "up") {
+    *is_down_out = false;
+  } else {
+    return false;
+  }
+
+  if (scan_separator == std::string::npos) {
     return true;
   }
-  if (state == "0" || state == "up") {
-    *is_down_out = false;
+
+  const size_t extended_separator = command.find(':', scan_separator + 1);
+  const std::string scan_code_str =
+      extended_separator == std::string::npos
+          ? command.substr(scan_separator + 1)
+          : command.substr(scan_separator + 1,
+                           extended_separator - scan_separator - 1);
+  try {
+    *scan_code_out = static_cast<uint32_t>(std::stoul(scan_code_str));
+  } catch (...) {
+    return false;
+  }
+
+  if (extended_separator == std::string::npos) {
+    return true;
+  }
+
+  const std::string extended_str = command.substr(extended_separator + 1);
+  if (extended_str == "1" || extended_str == "true") {
+    *extended_out = true;
+    return true;
+  }
+  if (extended_str == "0" || extended_str == "false") {
+    *extended_out = false;
     return true;
   }
   return false;
@@ -807,13 +882,17 @@ std::vector<uint8_t> HandleSecureInputHelperCommand(
 
   int key_code = 0;
   bool is_down = false;
-  if (ParseSecureInputKeyboardCommand(command, &key_code, &is_down)) {
-    const int inject_result = InjectKeyboardInput(key_code, is_down);
+  uint32_t scan_code = 0;
+  bool extended = false;
+  if (ParseSecureInputKeyboardCommand(command, &key_code, &is_down, &scan_code,
+                                      &extended)) {
+    const int inject_result =
+        InjectKeyboardInput(key_code, is_down, scan_code, extended);
     if (inject_result != 0) {
       LOG_WARN(
           "Secure input helper SendInput failed for key_code={}, is_down={}, "
-          "err={}",
-          key_code, is_down, inject_result);
+          "scan_code={}, extended={}, err={}",
+          key_code, is_down, scan_code, extended, inject_result);
       return BuildTextResponseBytes(BuildErrorJson(
           "send_input_failed", static_cast<DWORD>(inject_result)));
     }
@@ -823,6 +902,8 @@ std::vector<uint8_t> HandleSecureInputHelperCommand(
     json["injected"] = "keyboard";
     json["key_code"] = key_code;
     json["is_down"] = is_down;
+    json["scan_code"] = scan_code;
+    json["extended"] = extended;
     json["desktop"] = WideToUtf8(GetCurrentThreadDesktopNameW());
     return BuildTextResponseBytes(json.dump());
   }

tests/macos_keyboard_modifier_state_test.cpp

@@ -0,0 +1,60 @@
+#include "macos_keyboard_modifier_state.h"
+
+#include <cstdint>
+#include <iostream>
+
+namespace {
+
+bool ExpectEqual(const char* name, uint32_t actual, uint32_t expected) {
+  if (actual == expected) {
+    return true;
+  }
+
+  std::cerr << name << " mismatch\n"
+            << "  expected: " << expected << "\n"
+            << "  actual:   " << actual << "\n";
+  return false;
+}
+
+}  // namespace
+
+int main() {
+  crossdesk::MacKeyboardModifierState state;
+
+  bool ok = true;
+  ok &= ExpectEqual("initial flags", state.flags(), 0);
+  ok &= ExpectEqual("left shift down", state.Update(0xA0, true),
+                    crossdesk::kMacInjectedModifierShift);
+  ok &= ExpectEqual("shifted semicolon keeps shift",
+                    state.Update(0xBA, true),
+                    crossdesk::kMacInjectedModifierShift);
+  ok &= ExpectEqual("semicolon up keeps shift", state.Update(0xBA, false),
+                    crossdesk::kMacInjectedModifierShift);
+  ok &= ExpectEqual("right shift down while left held",
+                    state.Update(0xA1, true),
+                    crossdesk::kMacInjectedModifierShift);
+  ok &= ExpectEqual("left shift up while right held", state.Update(0xA0, false),
+                    crossdesk::kMacInjectedModifierShift);
+  ok &= ExpectEqual("right shift up clears shift", state.Update(0xA1, false),
+                    0);
+
+  ok &= ExpectEqual("left control down", state.Update(0xA2, true),
+                    crossdesk::kMacInjectedModifierControl);
+  ok &= ExpectEqual("right alt adds option", state.Update(0xA5, true),
+                    crossdesk::kMacInjectedModifierControl |
+                        crossdesk::kMacInjectedModifierOption);
+  ok &= ExpectEqual("left command adds command", state.Update(0x5B, true),
+                    crossdesk::kMacInjectedModifierControl |
+                        crossdesk::kMacInjectedModifierOption |
+                        crossdesk::kMacInjectedModifierCommand);
+  ok &= ExpectEqual("left control up leaves option command",
+                    state.Update(0xA2, false),
+                    crossdesk::kMacInjectedModifierOption |
+                        crossdesk::kMacInjectedModifierCommand);
+  ok &= ExpectEqual("right alt up leaves command", state.Update(0xA5, false),
+                    crossdesk::kMacInjectedModifierCommand);
+  ok &= ExpectEqual("left command up clears all", state.Update(0x5B, false),
+                    0);
+
+  return ok ? 0 : 1;
+}

tests/path_manager_portable_test.cpp

@@ -0,0 +1,78 @@
+#include "path_manager.h"
+
+#include <cstdint>
+#include <filesystem>
+#include <iostream>
+#include <string>
+
+#ifdef _WIN32
+#include <windows.h>
+#elif defined(__APPLE__)
+#include <mach-o/dyld.h>
+#include <limits.h>
+#else
+#include <limits.h>
+#include <unistd.h>
+#endif
+
+namespace {
+
+std::filesystem::path GetExecutableDirectory() {
+#ifdef _WIN32
+  wchar_t buffer[MAX_PATH] = {};
+  DWORD length = GetModuleFileNameW(nullptr, buffer, MAX_PATH);
+  if (length == 0 || length == MAX_PATH) {
+    return {};
+  }
+  return std::filesystem::path(buffer).parent_path();
+#elif defined(__APPLE__)
+  char buffer[PATH_MAX] = {};
+  uint32_t size = sizeof(buffer);
+  if (_NSGetExecutablePath(buffer, &size) != 0) {
+    return {};
+  }
+  return std::filesystem::weakly_canonical(buffer).parent_path();
+#else
+  char buffer[PATH_MAX] = {};
+  ssize_t length = readlink("/proc/self/exe", buffer, sizeof(buffer) - 1);
+  if (length <= 0) {
+    return {};
+  }
+  buffer[length] = '\0';
+  return std::filesystem::path(buffer).parent_path();
+#endif
+}
+
+bool ExpectEqual(const char* name,
+                 const std::filesystem::path& actual,
+                 const std::filesystem::path& expected) {
+  if (actual.lexically_normal() == expected.lexically_normal()) {
+    return true;
+  }
+
+  std::cerr << name << " mismatch\n"
+            << "  expected: " << expected.string() << "\n"
+            << "  actual:   " << actual.string() << "\n";
+  return false;
+}
+
+}  // namespace
+
+int main() {
+  const std::filesystem::path exe_dir = GetExecutableDirectory();
+  if (exe_dir.empty()) {
+    std::cerr << "failed to resolve executable directory\n";
+    return 1;
+  }
+
+  crossdesk::PathManager path_manager("CrossDesk");
+  const std::filesystem::path expected_data = exe_dir / "data";
+  const std::filesystem::path expected_logs = exe_dir / "logs";
+
+  bool ok = true;
+  ok &= ExpectEqual("config path", path_manager.GetConfigPath(), expected_data);
+  ok &= ExpectEqual("cache path", path_manager.GetCachePath(), expected_data);
+  ok &= ExpectEqual("log path", path_manager.GetLogPath(), expected_logs);
+
+  return ok ? 0 : 1;
+}

xmake/options.lua

@@ -23,6 +23,12 @@ function setup_options_and_dependencies()
         set_description("Enable DRM capture on Linux (assumes dependencies are installed)")
     option_end()
 
+    option("CROSSDESK_PORTABLE")
+        set_default(false)
+        set_showmenu(true)
+        set_description("Build CrossDesk as a portable package that stores data beside the executable")
+    option_end()
+
     add_rules("mode.release", "mode.debug")
     set_languages("c++17")
     set_encodings("utf-8")
@@ -35,6 +41,7 @@ function setup_options_and_dependencies()
     add_defines("USE_CUDA=" .. (is_config("USE_CUDA", true) and "1" or "0"))
     add_defines("USE_WAYLAND=" .. (is_config("USE_WAYLAND", true) and "1" or "0"))
     add_defines("USE_DRM=" .. (is_config("USE_DRM", true) and "1" or "0"))
+    add_defines("CROSSDESK_PORTABLE=" .. (is_config("CROSSDESK_PORTABLE", true) and "1" or "0"))
 
     if is_mode("debug") then
         add_defines("CROSSDESK_DEBUG")
@@ -47,4 +54,4 @@ function setup_options_and_dependencies()
     add_requires("nlohmann_json 3.11.3")
     add_requires("cpp-httplib v0.26.0", {configs = {ssl = true}})
     add_requires("tinyfiledialogs 3.15.1")
-end
+end

xmake/targets.lua

@@ -25,6 +25,20 @@ function setup_targets()
         add_files("src/path_manager/*.cpp")
         add_includedirs("src/path_manager", {public = true})
 
+    target("path_manager_portable_test")
+        set_kind("binary")
+        set_default(false)
+        add_defines("CROSSDESK_PORTABLE=1")
+        add_includedirs("src/path_manager")
+        add_files("tests/path_manager_portable_test.cpp",
+            "src/path_manager/path_manager.cpp")
+
+    target("macos_keyboard_modifier_state_test")
+        set_kind("binary")
+        set_default(false)
+        add_includedirs("src/device_controller")
+        add_files("tests/macos_keyboard_modifier_state_test.cpp")
+
     target("screen_capturer")
         set_kind("object")
         add_deps("rd_log", "common")
@@ -195,4 +209,4 @@ function setup_targets()
             add_deps("wgc_plugin", "crossdesk_service", "crossdesk_session_helper")
             add_files("scripts/windows/crossdesk.rc")
         end
-end
+end