feat:(Windows): add HID keyboard support

Add a licensed driver-backed keyboard path on Windows, including protocol/version updates, HID report framing, broker validation, and Win32 fallback behavior when the licensed path is unavailable. Update tests and documentation to cover the new keyboard device type and control-protocol semantics.

Author: ReenigneArcher

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 or Raw Input-visible mice with the Windows driver.</strong><br>
+    <strong>A license is required to create virtual gamepads, keyboards, 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,9 +48,9 @@ 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 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.
+- Windows gamepads, keyboards, and Raw Input-visible mice through a user-mode
+  UMDF2 control driver backed by Virtual HID Framework, with Win32 keyboard and
+  mouse fallbacks when the licensed driver path is unavailable.
 - 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,
@@ -107,7 +107,8 @@ devices from the OS, or ship a Windows kernel-mode driver.
 
 Linux and Windows provide virtual-device backends. Linux uses standard
 user-space kernel interfaces. Windows remains user-mode: the C++ library talks
-to a UMDF2 control driver, and the driver publishes HID gamepads through VHF.
+to a UMDF2 control driver, and the driver publishes HID gamepads, keyboards,
+and mice through VHF.
 macOS currently provides a limited CoreGraphics synthetic-input backend for
 keyboard and mouse only. It is not a virtual-HID backend and does not yet
 support gamepads; native macOS virtual-HID gamepad support is planned.

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 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.
+Every virtual gamepad, driver-backed keyboard, 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.
 
@@ -34,7 +34,7 @@ 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. 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 and mouse support available
+- The backend status reports windows-umdf with gamepad, keyboard, 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

docs/platform-support.md

@@ -25,19 +25,29 @@ Use capability queries for behavior such as:
 ## Windows
 
 The Windows backend keeps the normal C++ library buildable with MSVC and
-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.
+MinGW/UCRT64. Gamepad creation, Raw Input-visible keyboard input, and Raw
+Input-visible relative mouse input use a user-mode UMDF2 control driver and
+Windows Virtual HID Framework. Keyboard text input, absolute mouse input, and
+the keyboard and mouse fallbacks 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
 compiler-neutral and preserves the boundary between the MinGW/MSVC client
 library and the WDK/MSVC driver package.
 
-When the driver is installed, the backend publishes HID gamepads that standard
-HID consumers can enumerate, including SDL/HIDAPI, DirectInput,
-Windows.Gaming.Input/GameInput, and browser Gamepad API clients. XInput is not a
-direct target of the HID backend.
+When the driver is installed and licensed, the backend publishes HID gamepads,
+keyboards, and mice that standard HID and Raw Input consumers can enumerate.
+Gamepad consumers include SDL/HIDAPI, DirectInput,
+Windows.Gaming.Input/GameInput, and browser Gamepad API clients. XInput is not
+a direct target of the HID backend.
+
+Driver-backed keyboard key transitions use a standard keyboard-page HID report
+with modifier state and sixteen simultaneous non-modifier usages. Unicode text
+requests and keyboard-page keys that the descriptor cannot represent retain
+the Win32 injection path. If driver or license creation is unavailable,
+keyboard creation falls back to the existing Win32 implementation. Unexpected
+protocol and driver failures remain visible to the caller instead of silently
+changing the input path.
 
 The library and driver must use the same Windows control-protocol version. A
 descriptor-capacity change therefore increments the protocol version so a

docs/usage.md

@@ -77,8 +77,8 @@ unless they explicitly enable additional options.
 - `LIBVIRTUALHID_BUILD_WINDOWS_DRIVER`: build the Windows UMDF2 driver package
   with the Microsoft WDK/MSVC toolchain.
 - `LIBVIRTUALHID_BUILD_WINDOWS_BROKER`: build the Windows broker service used by
-  the driver package for gamepad creation, active-device limits, and license
-  state.
+  the driver package for licensed virtual HID device creation, active-device
+  limits, and license state.
 - `LIBVIRTUALHID_ENABLE_PACKAGING`: enable CPack package metadata.
 - `LIBVIRTUALHID_WARNINGS_AS_ERRORS`: treat project warnings as errors.
 
@@ -107,16 +107,16 @@ rumble, and raw report events delivered through the normal callback path. Button
 controls are momentary by default, so they behave like physical gamepad buttons;
 on Windows, the UI also displays broker license status and can activate,
 refresh, or deactivate a machine license without elevation. Windows UMDF
-gamepad creation requires a current machine authorization, but does not perform
-an online request per controller. The broker validates in the background at
-startup and once per day. If Polar cannot be reached, it retries every 60
-seconds. Existing gamepads are retained for one hour, but a new gamepad can be
-created only when no licensed gamepad is active. When the outage reaches one
-hour, the broker removes excess licensed gamepads and retains at most one. A
+virtual HID device creation requires a current machine authorization, but does
+not perform an online request per device. The broker validates in the
+background at startup and once per day. If Polar cannot be reached, it retries
+every 60 seconds. Existing devices are retained for one hour, but a new device
+can be created only when no licensed device is active. When the outage reaches one
+hour, the broker removes excess licensed devices and retains at most one. A
 yearly subscription must validate successfully within 25 hours of its previous
-validation, so the remaining gamepad is removed when that deadline passes. A
-lifetime license can retain the one-gamepad fallback until validation succeeds.
-If the broker service restarts, it removes gamepads left by the previous broker
+validation, so the remaining device is removed when that deadline passes. A
+lifetime license can retain the one-device fallback until validation succeeds.
+If the broker service restarts, it removes devices left by the previous broker
 instance before accepting new creation requests. Failed removals are retried.
 Both supported plans rely on Polar's entitlement status rather than a locally
 enforced calendar expiration. A granted yearly license follows its subscription
@@ -125,10 +125,10 @@ response does not include the subscription renewal date; the linked Polar accoun
 portal remains authoritative instead of the broker estimating a date. Polar
 server time, Windows uptime, and a per-boot marker track subscription validation
 age without relying on the user-adjustable Windows date. After Windows restarts,
-a yearly subscription must reconnect to Polar before gamepad creation; a lifetime
-license can use the one-gamepad outage fallback. A confirmed missing, revoked,
+a yearly subscription must reconnect to Polar before device creation; a lifetime
+license can use the one-device outage fallback. A confirmed missing, revoked,
 disabled, or mismatched entitlement invalidates the license and removes all
-licensed gamepads.
+licensed virtual HID devices.
 Purchase and account-management buttons use the compiled URLs in
 `src/platform/windows/shared/lvh_windows_broker_config.hpp`.
 Enable `Lock buttons` to click-to-toggle behavior for held inputs.

docs/windows-driver.md

@@ -1,10 +1,10 @@
 # Windows Driver Package
 
-Windows virtual HID gamepad and Raw Input mouse support uses a user-mode UMDF2
-control driver backed by Virtual HID Framework. The driver package is separate
-from the normal C++ library build: the library remains consumable from MSVC and
-MinGW/UCRT64, while the driver package is built with the Microsoft SDK/WDK
-toolchain.
+Windows virtual HID gamepad, keyboard, and Raw Input mouse support uses a
+user-mode UMDF2 control driver backed by Virtual HID Framework. The driver
+package is separate from the normal C++ library build: the library remains
+consumable from MSVC and MinGW/UCRT64, while the driver package is built with
+the Microsoft SDK/WDK toolchain.
 
 Windows 11 version 21H2 and later is the supported driver target. The INF also
 provides a best-effort compatibility path for Windows 10 version 2004 and later
@@ -19,19 +19,19 @@ so Store listing copy should describe the installed driver component.
 ### Short Description
 
 ```text
-User-mode virtual HID driver package that enables compatible apps to create virtual gamepads and Raw Input mice on Windows.
+User-mode virtual HID driver package that enables compatible apps to create virtual gamepads, keyboards, and Raw Input mice on Windows.
 ```
 
 ### Description
 
 ```text
 Virtual HID Driver installs the user-mode driver component used by compatible
-applications to create virtual HID gamepads and mice on Windows.
+applications to create virtual HID gamepads, keyboards, and mice on Windows.
 
 The package includes a local diagnostic UI for creating and testing virtual
 gamepads and mice. Compatible applications can also request virtual HID gamepads
-or mice, and Windows applications that understand standard HID devices can
-discover them.
+keyboards, or mice, and Windows applications that understand standard HID
+devices can discover them.
 ```
 
 ## Architecture
@@ -86,8 +86,9 @@ axis, trigger, motion, battery, and touch-position states with the newest report
 Button, D-pad, trigger-threshold, report-ID, and touch-contact lifecycle changes
 remain ordered in a bounded transition queue. This keeps continuously moving
 controls close to the latest submitted state while preserving ordinary button
-press and release transitions. Relative mouse motion and wheel values are
-accumulated by button state and emitted in descriptor-sized chunks, so VHF
+press and release transitions. Keyboard reports also remain ordered so short
+key transitions are not coalesced away. Relative mouse motion and wheel values
+are accumulated by button state and emitted in descriptor-sized chunks, so VHF
 backpressure does not turn relative movement into a replaceable absolute state.
 Profile initialization replies are prioritized over pending controller states
 so the Switch Pro handshake remains responsive.
@@ -103,10 +104,10 @@ they are not a separate runtime bypass for creating or destroying virtual
 devices.
 
 The library and installed driver must use the same control-protocol version.
-Control protocol version 3 adds an explicit device type to the common create
-request while retaining the 2048-byte report-descriptor capacity needed by the
-complete DirectInput PID descriptor. A version mismatch is rejected rather than
-interpreting a differently sized request.
+Control protocol version 4 adds the canonical keyboard device type and report
+contract to the common create request. It retains the explicit device type and
+2048-byte report-descriptor capacity introduced by version 3. A version mismatch
+is rejected rather than interpreting a request with different semantics.
 
 Each backend runtime uses one control-file handle for commands and its pending
 output read. Broker protocol version 4 carries the generalized device create
@@ -131,8 +132,8 @@ recreate their devices after the broker service restarts.
 
 The backend reports `requires_installed_driver = true` and only advertises
 gamepad/output-report support when the broker is reachable and the control
-device can be opened. Keyboard injection and the mouse `SendInput` fallback do
-not require the driver package; a Raw Input-visible mouse does require the
+device can be opened. The keyboard and mouse `SendInput` fallbacks do not
+require the driver package; a Raw Input-visible keyboard or mouse requires the
 driver and the same broker license as a gamepad.
 
 ## Build
@@ -331,9 +332,9 @@ opens the shared persistent Polar Checkout Link. Account management opens the
 where customers can manage their five allowed machine activations.
 
 Normal Windows UMDF virtual HID device creation requires a current machine
-authorization, but device creation itself does not contact Polar. A mouse does
-not consume another Polar machine activation; it is another active device under
-the existing machine license. The broker validates the
+authorization, but device creation itself does not contact Polar. A keyboard or
+mouse does not consume another Polar machine activation; each is another active
+device under the existing machine license. The broker validates the
 saved activation immediately after service startup and then once per day in the
 background. If validation cannot complete because of a temporary network or
 provider failure, the broker retries every 60 seconds. Devices that already
@@ -388,6 +389,18 @@ WinHTTP resolve, connect, send, and receive operations have explicit timeouts of
 
 ## Profile Compatibility
 
+For a keyboard, the Windows backend preserves the requested bus type, VID, PID,
+version, name, manufacturer, and stable ID. The Windows transport owns the HID
+framing: it uses a report-ID-free standard keyboard descriptor with eight
+modifier bits, sixteen simultaneous keyboard-page usages, and a one-byte LED
+output report. Normal key transitions use the licensed VHF device so Raw Input
+clients enumerate a physical-style HID keyboard instead of receiving only
+`SendInput` injection. Unicode text input and keys outside the descriptor's
+keyboard-page range continue through `SendInput`. If the driver, broker, or
+license is unavailable, keyboard creation retains the existing `SendInput`
+fallback; malformed requests and unexpected driver failures are returned to the
+caller.
+
 For a mouse, the Windows backend preserves the requested bus type, VID, PID,
 version, name, manufacturer, and stable ID. The Windows transport owns the HID
 framing: it uses a report-ID-free seven-byte descriptor with five buttons,

src/platform/windows/broker/broker_request_validation.hpp

@@ -17,6 +17,7 @@
 #include <utility>
 
 // local includes
+#include "keyboard_protocol.hpp"
 #include "lvh_windows_broker_protocol.h"
 #include "mouse_protocol.hpp"
 
@@ -79,14 +80,23 @@ namespace lvh::windows::broker_validation {
   inline bool valid_device_request(const LvhWindowsCreateDeviceRequest &request) {
     const auto &sizes = request.report_sizes;
     const auto known_device = request.device_type == LVH_WINDOWS_DEVICE_GAMEPAD ||
+                              request.device_type == LVH_WINDOWS_DEVICE_KEYBOARD ||
                               request.device_type == LVH_WINDOWS_DEVICE_MOUSE;
     const auto known_bus = request.bus_type == LVH_WINDOWS_BUS_UNKNOWN ||
                            request.bus_type == LVH_WINDOWS_BUS_USB ||
                            request.bus_type == LVH_WINDOWS_BUS_BLUETOOTH;
     const auto known_profile = request.gamepad_kind <= LVH_WINDOWS_GAMEPAD_DUALSHOCK4;
-    const auto valid_mouse_descriptor =
+    const auto valid_driver_descriptor =
       request.device_type == LVH_WINDOWS_DEVICE_GAMEPAD ||
-      (sizes.report_descriptor_size == lvh::detail::windows::mouse_report_descriptor.size() &&
+      (request.device_type == LVH_WINDOWS_DEVICE_KEYBOARD &&
+       sizes.report_descriptor_size == lvh::detail::windows::keyboard_report_descriptor.size() &&
+       std::equal(
+         lvh::detail::windows::keyboard_report_descriptor.begin(),
+         lvh::detail::windows::keyboard_report_descriptor.end(),
+         request.report_descriptor.begin()
+       )) ||
+      (request.device_type == LVH_WINDOWS_DEVICE_MOUSE &&
+       sizes.report_descriptor_size == lvh::detail::windows::mouse_report_descriptor.size() &&
        std::equal(
          lvh::detail::windows::mouse_report_descriptor.begin(),
          lvh::detail::windows::mouse_report_descriptor.end(),
@@ -96,8 +106,12 @@ namespace lvh::windows::broker_validation {
                                      (request.gamepad_kind == LVH_WINDOWS_GAMEPAD_GENERIC &&
                                       request.flags == 0U &&
                                       request.hardware_ids.report_id == 0U &&
-                                      sizes.input_report_size == LVH_WINDOWS_MOUSE_INPUT_REPORT_SIZE &&
-                                      sizes.output_report_size == 0U);
+                                      ((request.device_type == LVH_WINDOWS_DEVICE_KEYBOARD &&
+                                        sizes.input_report_size == LVH_WINDOWS_KEYBOARD_INPUT_REPORT_SIZE &&
+                                        sizes.output_report_size == LVH_WINDOWS_KEYBOARD_OUTPUT_REPORT_SIZE) ||
+                                       (request.device_type == LVH_WINDOWS_DEVICE_MOUSE &&
+                                        sizes.input_report_size == LVH_WINDOWS_MOUSE_INPUT_REPORT_SIZE &&
+                                        sizes.output_report_size == 0U)));
 
     return request.version == LVH_WINDOWS_CONTROL_PROTOCOL_VERSION &&
            request.size == sizeof(request) &&
@@ -106,7 +120,7 @@ namespace lvh::windows::broker_validation {
            known_bus &&
            known_profile &&
            valid_device_fields &&
-           valid_mouse_descriptor &&
+           valid_driver_descriptor &&
            (request.flags & ~known_gamepad_flags) == 0U &&
            all_zero(request.hardware_ids.reserved0) &&
            sizes.input_report_size > 0U &&