feat(native): capture light feedback reports

Author: SYMBaiEX

README.md

@@ -295,7 +295,7 @@ The Linux native package adds:
 The Windows native package adds:
 
 - VHF-ready HID descriptor, input report helpers, Switch/PlayStation report
-  profiles, and rumble feedback contract
+  profiles, and rumble/light feedback contract
 - INF, WDK C source, host bridge C source, C-array asset generators, and a host bridge adapter factory for a maintained Windows VHF driver path
 - generated VHF source templates that capture HID output reports and emit native bridge feedback JSONL
 - setup helper for staging reviewed VHF driver/host source files and install/test commands without privileged changes
@@ -306,10 +306,11 @@ The Windows native package adds:
 The macOS native package adds:
 
 - DriverKit-ready HID descriptor, input report helpers, Switch/PlayStation
-  report profiles, and rumble output report codecs
+  report profiles, and rumble/light output report codecs
 - Info.plist and entitlement templates for a virtual HID gamepad dext
 - C++ DriverKit source and byte-array asset generation, including `setReport`
-  rumble capture and a `copyRumbleReport` hook for signed host bridges
+  rumble/light capture plus `copyRumbleReport` and `copyLightReport` hooks for
+  signed host bridges
 - host bridge adapter factory for a signed DriverKit host process
 - setup helper for staging reviewed DriverKit/host source files and activation/test commands without privileged changes
 - `opencontroller-macos-driverkit-doctor`
@@ -560,8 +561,8 @@ const controller = await createController({
 
 The default macOS bridge path is
 `~/Library/Application Support/OpenController/bin/OpenControllerDriverKitHostBridge`.
-The generated DriverKit source stores HID rumble output reports so a signed host
-bridge can publish `opencontroller.bridge.feedback` JSONL back to
+The generated DriverKit source stores HID rumble and light output reports so a
+signed host bridge can publish `opencontroller.bridge.feedback` JSONL back to
 `controller.onFeedback(...)`.
 
 For application code that should run on whichever native backend is installed

bun.lock

@@ -123,10 +123,10 @@ descriptor/report for Switch motion vectors.
 
 The generated C++ source is a DriverKit starting point for an `IOUserHIDDevice`
 subclass. It returns the selected OpenController report descriptor with rumble
-output support, publishes the virtual gamepad description, keeps a neutral input
-report sized to the chosen profile, accepts host output reports through `setReport`, and
-exposes `updateInputReport` plus `copyRumbleReport` entry points for a signed
-host app/user-client bridge.
+and light output support, publishes the virtual gamepad description, keeps a
+neutral input report sized to the chosen profile, accepts host output reports
+through `setReport`, and exposes `updateInputReport`, `copyRumbleReport`, and
+`copyLightReport` entry points for a signed host app/user-client bridge.
 
 ## Host Bridge Adapter
 
@@ -164,11 +164,12 @@ to the intended DriverKit service. It also passes
 `OPENCONTROLLER_CONTROLLER_ID` when `controllerId` is provided so the host bridge
 can ignore other controllers in a shared multi-agent stream.
 
-For haptics, the generated DriverKit source stores the latest 5-byte HID rumble
-output report. A signed host bridge can poll `copyRumbleReport`, encode the
-bytes as the shared `"hid-gamepad-rumble"` feedback payload, and write
-`opencontroller.bridge.feedback` JSONL to stdout so `controller.onFeedback(...)`
-receives the event.
+For feedback, the generated DriverKit source stores the latest 5-byte HID rumble
+output report and 7-byte light/player-indicator output report. A signed host
+bridge can poll `copyRumbleReport` and `copyLightReport`, encode the bytes as
+the shared `"hid-gamepad-rumble"` and `"hid-gamepad-lights"` feedback payloads,
+and write `opencontroller.bridge.feedback` JSONL to stdout so
+`controller.onFeedback(...)` receives the events.
 
 ## Current Limitations
 

docs/macos-driverkit.md

@@ -5,6 +5,9 @@
 - Added HID light/player-indicator output reports and native bridge light
   feedback messages so hosts can surface lightbar and player LED state through
   `controller.onFeedback(...)`.
+- Windows VHF and macOS DriverKit generated templates now capture HID light
+  output reports alongside rumble reports and expose `"hid-gamepad-lights"`
+  feedback paths for native host bridges.
 - Added `bun run npm:status` to compare local OpenController package versions
   against the live npm registry before and after publish.
 - README, docs, and demo-facing labels now consistently present the project as
@@ -37,7 +40,7 @@
   encoded as combined cardinal D-pad state and report bits.
 - D-pad helper commands now honor disabled-button, disabled-combo, and
   max-button-hold safety policies through their underlying `DPAD_*` buttons.
-- Prepared workspace package manifests for the next `0.1.8` npm patch release.
+- Prepared workspace package manifests for the next `0.1.9` npm patch release.
 - Added a guarded `publish:npm` helper that publishes packages in dependency
   order and supports npm two-factor `--otp` codes.
 - `CODE_OF_CONDUCT.md` added for open-source community participation.

docs/release-notes.md

@@ -151,21 +151,22 @@ opencontroller-windows-vhf-setup --report-profile switch
 ```
 
 The generated driver source is a WDK/KMDF starting point that wires the shared
-descriptor with rumble output into `VHF_CONFIG_INIT`, creates and starts a VHF
-device, accepts an OpenController HID input report through a buffered
-IOCTL, and submits it with `VhfReadReportSubmit`. It also registers
+descriptor with rumble and light output into `VHF_CONFIG_INIT`, creates and
+starts a VHF device, accepts an OpenController HID input report through a
+buffered IOCTL, and submits it with `VhfReadReportSubmit`. It also registers
 `EvtVhfAsyncOperationWriteReport` so host HID output reports can be captured as
-5-byte rumble packets and exposed to the user-mode host bridge through a read
-IOCTL. It still needs a signed driver package and a reviewed user-mode host path
-before installation.
+5-byte rumble packets and 7-byte light/player-indicator packets, then exposed to
+the user-mode host bridge through read IOCTLs. It still needs a signed driver
+package and a reviewed user-mode host path before installation.
 
 The generated host bridge C source reads OpenController native bridge JSONL from
 stdin, prefers direct `hidReportBase64` payloads, falls back to converting
 legacy `reportBase64` XInput packets, opens the VHF driver with `CreateFileA`,
 and writes HID reports through `DeviceIoControl`. A background feedback
-thread polls the driver's rumble IOCTL and emits `opencontroller.bridge.feedback`
-JSONL on stdout so `NativeProcessBridgeAdapter` can surface host haptics through
-`controller.onFeedback(...)`. Set `OPENCONTROLLER_CONTROLLER_ID` or pass
+thread polls the driver's rumble and light IOCTLs and emits
+`opencontroller.bridge.feedback` JSONL on stdout so
+`NativeProcessBridgeAdapter` can surface host haptics and light/player-indicator
+changes through `controller.onFeedback(...)`. Set `OPENCONTROLLER_CONTROLLER_ID` or pass
 `--controller-id` when the host bridge is reading a shared stream so each virtual
 device only reacts to its assigned controller.
 
@@ -184,6 +185,7 @@ const controller = await createController({
   adapter: createWindowsVhfHostBridgeAdapter({
     controllerId: "player-1",
     supportsRumble: true,
+    supportsLights: true,
     hostBridgePath: "C:\\OpenController\\OpenControllerVhfHostBridge.exe",
     devicePath: "\\\\.\\OpenControllerVhfGamepad"
   }),
@@ -194,6 +196,9 @@ controller.onFeedback((event) => {
   if (event.type === "rumble") {
     console.log(event.weakMotor, event.strongMotor);
   }
+  if (event.type === "lights") {
+    console.log(event.red, event.green, event.blue, event.playerLightMask);
+  }
 });
 ```
 
@@ -217,6 +222,6 @@ emits for native bridge processes.
   commands only
 - generated host bridge source still needs a Windows build project and signed
   device install verification
-- rumble feedback requires the generated VHF driver and host bridge to be built
+- feedback requires the generated VHF driver and host bridge to be built
   together so their submit/pop IOCTL function codes match
 - legacy ViGEmBus diagnostics are compatibility-only

docs/windows-virtual-gamepad.md

@@ -1,6 +1,6 @@
 {
   "name": "opencontroller",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": true,
   "description": "OpenController packages for AI-agent virtual controller control, overlays, safety, and replay logs.",
   "type": "module",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencontroller/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Command line tools for OpenController.",
   "type": "module",
   "license": "MIT",
@@ -34,12 +34,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencontroller/core": "^0.1.8",
-    "@opencontroller/native": "^0.1.8",
-    "@opencontroller/native-linux-uinput": "^0.1.8",
-    "@opencontroller/native-macos-driverkit": "^0.1.8",
-    "@opencontroller/native-windows-virtual-gamepad": "^0.1.8",
-    "@opencontroller/overlay": "^0.1.8"
+    "@opencontroller/core": "^0.1.9",
+    "@opencontroller/native": "^0.1.9",
+    "@opencontroller/native-linux-uinput": "^0.1.9",
+    "@opencontroller/native-macos-driverkit": "^0.1.9",
+    "@opencontroller/native-windows-virtual-gamepad": "^0.1.9",
+    "@opencontroller/overlay": "^0.1.9"
   },
   "devDependencies": {
     "@types/bun": "^1.2.15",

packages/cli/package.json

@@ -186,7 +186,7 @@ const hid = new HidGamepadReportAdapter({
     console.log("hid", bytes);
   },
   onFeedback(event) {
-    console.log("hid rumble", event.weakMotor, event.strongMotor);
+    console.log("hid feedback", event.type);
   },
 });
 
@@ -209,8 +209,8 @@ payload, and `hid-playstation-extended-report` for the 47-byte PlayStation
 profile payload that carries touchpad contacts and motion vectors.
 `hid-switch-extended-report` carries the common gamepad payload plus Switch
 motion vectors in a 31-byte profile report. The HID report adapters also accept
-the shared 5-byte rumble output report through
-`adapter.receiveOutputReport(bytes)` and surface it through
+the shared 5-byte rumble and 7-byte light/player-indicator output reports
+through `adapter.receiveOutputReport(bytes)` and surface it through
 `controller.onFeedback(...)`.
 
 ## Capability Metadata
@@ -222,9 +222,12 @@ console.log(capabilities.supportedProfiles);
 console.log(capabilities.outputFormats);
 console.log(capabilities.reportFormats);
 
-if (capabilities.feedbackTypes.includes("rumble")) {
+if (
+  capabilities.feedbackTypes.includes("rumble") ||
+  capabilities.feedbackTypes.includes("lights")
+) {
   controller.onFeedback((event) => {
-    console.log(event.weakMotor, event.strongMotor);
+    console.log(event.type, event.reportFormat);
   });
 }
 ```

packages/core/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@opencontroller/core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Core OpenController controller runtime for AI-agent virtual controller control.",
   "type": "module",
   "license": "MIT",

packages/core/package.json

@@ -1,6 +1,7 @@
 import type { ControllerState, ControllerTouchpadContact } from "../types";
 import {
   createHidGamepadReport,
+  hidGamepadLightOutputReportDescriptor,
   hidGamepadRumbleOutputReportDescriptor,
 } from "./hid-gamepad";
 
@@ -133,6 +134,14 @@ export const hidPlayStationExtendedReportDescriptorWithRumble = Uint8Array.from(
   ],
 );
 
+export const hidPlayStationExtendedReportDescriptorWithFeedback =
+  Uint8Array.from([
+    ...hidPlayStationExtendedReportDescriptor.slice(0, -1),
+    ...hidGamepadRumbleOutputReportDescriptor,
+    ...hidGamepadLightOutputReportDescriptor,
+    0xc0, // End Collection
+  ]);
+
 export function createHidPlayStationExtendedReport(
   state: ControllerState,
 ): HidPlayStationExtendedReport {