feat(windows): back the virtual mouse with a real HID device

README.md

@@ -19,7 +19,7 @@
 <div align="center">
   <h2>🎮 Windows Virtual HID Driver License</h2>
   <p>
-    <strong>A license is required to create virtual gamepads with the Windows driver.</strong><br>
+    <strong>A license is required to create virtual gamepads or Raw Input-visible mice with the Windows driver.</strong><br>
     This requirement is Windows-only; non-Windows backends do not currently require a license.<br>
     Yearly and lifetime options are available.
   </p>
@@ -48,12 +48,13 @@ behind backend implementations.
 - Descriptor-driven PlayStation gamepads through Linux `uhid`; Generic, Xbox,
   and Switch Pro gamepads plus keyboard, mouse, touchscreen, trackpad, and pen
   tablet devices through `uinput`.
-- Windows gamepads through a user-mode UMDF2 control driver backed by Virtual
-  HID Framework, with keyboard and mouse support through normal Win32 APIs.
+- Windows gamepads and Raw Input-visible mice through a user-mode UMDF2 control
+  driver backed by Virtual HID Framework, with keyboard and fallback mouse
+  support through normal Win32 APIs.
 - Output callbacks for profile-specific feedback such as rumble, LEDs,
   adaptive triggers, and raw HID output reports when available.
 - An optional `virtualhid_control` native UI tool for creating, removing,
-  controlling, and inspecting test gamepads through the public C++ API.
+  controlling, and inspecting test gamepads and mice through the public C++ API.
 - CMake consumption through installed packages, vendored source,
   `add_subdirectory`, or `FetchContent`.
 

docs/maintainer/store-review-validation.md

@@ -15,7 +15,7 @@ Paste this into the Partner Center certification notes field:
 ```text
 This package installs the libvirtualhid Windows user-mode UMDF/VHF virtual HID driver and local broker service. Applications consume it through the libvirtualhid client API, and the MSI includes a native diagnostic UI for local validation.
 
-Every virtual gamepad creation requires an active license. A currently granted review license key with an available device activation is supplied separately in the Partner Center certification credentials or notes. The key is not embedded in the package or this document.
+Every virtual gamepad or driver-backed Raw Input mouse creation requires an active license. A currently granted review license key with an available device activation is supplied separately in the Partner Center certification credentials or notes. The key is not embedded in the package or this document.
 
 Launch the validation tool below.
 
@@ -31,17 +31,20 @@ Required validation:
 $installRoot = Join-Path $env:ProgramFiles "libvirtualhid"
 Start-Process "$installRoot\tools\windows\virtualhid_control.exe"
 
-In the libvirtualhid control window, paste the supplied review key into the License key field and click Activate license. Confirm the status changes to Licensed. Then leave the default Xbox Series profile selected and click Create. Use the button and axis controls in the UI to submit input to the virtual controller.
+In the libvirtualhid control window, paste the supplied review key into the License key field and click Activate license. Confirm the status changes to Licensed. Then leave the default Xbox Series profile selected and click Create. Use the button and axis controls in the UI to submit input to the virtual controller. Next, change Device type to Mouse and click Create. Use Tab or the arrow keys to highlight the mouse controls and Space or Enter to activate relative movement, momentary button, and wheel input without using the physical mouse.
 
 Expected result:
-- The backend status reports windows-umdf with gamepad support available
+- The backend status reports windows-umdf with gamepad and mouse support available
 - The libvirtualhid_broker service is running
 - License validation succeeds and the license status reports Licensed
 - A virtual HID gamepad is created and appears in the device list
 - A virtual HID gamepad child device starts with the Xbox Series HID ID
   HID\VID_045E&PID_0B12&IG_00
 - Button, axis, and Share values in the UI can be pressed or moved without
   errors
+- A driver-backed virtual HID mouse is created and appears in the device list
+- Keyboard activation of the mouse controls moves the pointer, changes button
+  state, and scrolls without errors
 
 Optional browser validation:
 $installRoot = Join-Path $env:ProgramFiles "libvirtualhid"
@@ -55,6 +58,12 @@ Use the libvirtualhid control window to press buttons or move axes while the bro
 Expected result:
 - The browser Gamepad API sees an Xbox-compatible controller
 - Button and axis values change while controls are used in the validation UI
+
+For a browser mouse-event tester, create a mouse in the validation UI and enable Delayed browser test. Leave the pointer over the browser test target, activate a movement, button, or wheel action with the keyboard, then switch to the browser before the displayed countdown expires.
+
+Expected result:
+- The browser receives the queued mouse action while it owns focus
+- A queued button action produces one press followed by one release
 ```
 
 ## Manual Review Steps
@@ -66,7 +75,8 @@ Expected result:
 4. Run the required validation tool from the submission notes.
 5. Activate the review key supplied through Partner Center.
 6. Create the default gamepad and exercise its controls.
-7. Optionally, run the browser validation steps.
+7. Create a mouse and exercise its controls with keyboard navigation.
+8. Optionally, run the browser validation steps.
 
 If the default install location was changed during MSI installation, replace
 `$env:ProgramFiles\libvirtualhid` with the selected install directory.
@@ -84,5 +94,5 @@ HID-only and intentionally does not emulate the Xbox 360 XUSB stack.
 
 The reviewer-visible success signal is the installed `ROOT\LIBVIRTUALHID`
 control device, the `\\.\LibVirtualHid` control path, the running
-`libvirtualhid_broker` service, and a started HID gamepad child device while
-`virtualhid_control.exe` has a gamepad created.
+`libvirtualhid_broker` service, and started HID child devices while
+`virtualhid_control.exe` has a gamepad and mouse created.

docs/platform-support.md

@@ -25,8 +25,9 @@ Use capability queries for behavior such as:
 ## Windows
 
 The Windows backend keeps the normal C++ library buildable with MSVC and
-MinGW/UCRT64. Keyboard and mouse input use Win32 APIs. Gamepad creation uses a
-user-mode UMDF2 control driver and Windows Virtual HID Framework.
+MinGW/UCRT64. Gamepad creation and Raw Input-visible relative mouse input use a
+user-mode UMDF2 control driver and Windows Virtual HID Framework. Keyboard,
+absolute mouse input, and the mouse fallback use Win32 APIs.
 
 The C++ library communicates with the driver through fixed-size protocol
 structures and `DeviceIoControl`, not C++ STL types. This keeps the public API
@@ -199,6 +200,13 @@ libraries. Many distro toolchains intentionally omit some static archives, so
 release packaging should keep full static linking as a packaging-mode choice
 rather than an unconditional default.
 
+The UI can create and exercise both gamepads and mice. Its mouse movement,
+button, and wheel controls participate in Dear ImGui keyboard navigation; use
+Tab or the arrow keys to highlight them and Space or Enter to activate them.
+Mouse buttons are momentary. A delayed browser-test mode queues an action long
+enough to switch focus to an external event tester, sending button actions as a
+single press-and-release click.
+
 ### Permissions
 
 Linux deployment requires both device-node permissions and the kernel modules