Publish Windows physical-click validation handoff

handoff/README.md

@@ -0,0 +1,46 @@
+# Agent integration handoff
+
+Runtime coordination between the Windows and macOS agents is exchanged through
+versioned files in this directory instead of manual copy/paste.
+
+## Windows to macOS
+
+The Windows agent owns `windows-runtime.json`. The macOS agent should pull the
+latest integration branch, read that file, and use its exact address, port,
+minimum commit, and startup marker. Values such as `WINDOWS_IP` in general
+documentation are placeholders and must never be passed literally.
+
+## macOS to Windows
+
+After a real-device run, the macOS agent should create or update
+`mac-validation.json` with this shape:
+
+```json
+{
+  "schema_version": 1,
+  "tested_windows_runtime_updated_at": "copy from windows-runtime.json",
+  "mac_source_commit": "full Git commit",
+  "connected": true,
+  "physical_button_enabled": true,
+  "button_events": 2,
+  "physical_drag": "failed",
+  "raw_button_callbacks": [
+    {"pressed": 1, "released": 0},
+    {"pressed": 0, "released": 1}
+  ],
+  "emitted_button_transitions": [
+    {"sequence": 100, "button": true, "contact_count": 1},
+    {"sequence": 350, "button": false, "contact_count": 1}
+  ],
+  "notes": ["Add exact symptoms here."]
+}
+```
+
+`button_events` must increase for physical press and release. Use
+`"physical_drag": "failed"` and place exact symptoms in `notes` if Windows
+does not drag despite nonzero button events. For a two-second hold, the
+frame-level button value must remain true for every intervening contact frame;
+a short true/false pulse is only a click and cannot drag.
+
+Do not put credentials, certificate private keys, tokens, or public-network
+addresses in handoff files.

handoff/windows-runtime.json

@@ -0,0 +1,43 @@
+{
+  "schema_version": 1,
+  "updated_at": "2026-07-30T14:20:00+08:00",
+  "source_commit": "5334a7363c9a6db5693b3e498e14e8da2a6173b8",
+  "windows": {
+    "ipv4": "192.168.31.115",
+    "tcp_port": 39871,
+    "receiver_executable": "out/windows/Release/mtp-receiver.exe",
+    "receiver_listening": true,
+    "driver_version": "0.1.0.8",
+    "ioctl_abi_version": 2,
+    "driver_installed": true
+  },
+  "mac": {
+    "minimum_source_commit": "5334a7363c9a6db5693b3e498e14e8da2a6173b8",
+    "connectivity_command": "nc -vz 192.168.31.115 39871",
+    "agent_command": "./build/mac-touch-agent 192.168.31.115 39871",
+    "required_startup_marker": "physical button=enabled"
+  },
+  "validation": {
+    "windows_receiver_tests": "passed",
+    "synthetic_button_frame": "passed",
+    "real_mac_click": "passed",
+    "real_mac_physical_drag": "failed",
+    "observed_symptom": "A physical press activates the target window, but holding the press while moving does not select text."
+  },
+  "requested_mac_diagnostics": {
+    "scenario": "Place one finger on the trackpad, press and hold for two seconds while moving, then release.",
+    "required_trace": [
+      "Every raw MTRegisterButtonStateCallback invocation with pressed and released integer arguments.",
+      "Every emitted button transition with sequence, frame flags, and contact_count.",
+      "Final button_events count."
+    ],
+    "acceptance_condition": "TP_FRAME_BUTTON remains set on every contact frame from physical down until physical release.",
+    "response_file": "handoff/mac-validation.json"
+  },
+  "notes": [
+    "Do not pass the literal placeholder WINDOWS_IP to mac-touch-agent.",
+    "Physical press validation requires button_events to increase on both press and release.",
+    "The current symptom is consistent with a short button pulse rather than a held level.",
+    "Write the Mac trace and result to handoff/mac-validation.json and commit it for the Windows agent."
+  ]
+}

windows/driver/MtpVhfTouchpad.inf

@@ -3,7 +3,7 @@ Signature="$WINDOWS NT$"
 Class=HIDClass
 ClassGuid={745A17A0-74D3-11D0-B6FE-00A0C90F57DA}
 Provider=%ManufacturerName%
-DriverVer=07/23/2026,0.1.0.7
+DriverVer=07/30/2026,0.1.0.8
 CatalogFile=MtpVhfTouchpad.cat
 PnpLockdown=1
 

windows/driver/MtpVhfTouchpad.vcxproj

@@ -27,7 +27,7 @@
   <ItemDefinitionGroup>
     <ClCompile><WarningLevel>Level4</WarningLevel><TreatWarningAsError>true</TreatWarningAsError><DisableSpecificWarnings>4005;4083;%(DisableSpecificWarnings)</DisableSpecificWarnings><AdditionalIncludeDirectories>$(ProjectDir)..\shared;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories></ClCompile>
     <Link><AdditionalDependencies>VhfKm.lib;%(AdditionalDependencies)</AdditionalDependencies></Link>
-    <Inf><TimeStamp>0.1.0.7</TimeStamp></Inf>
+    <Inf><TimeStamp>0.1.0.8</TimeStamp></Inf>
   </ItemDefinitionGroup>
   <ItemGroup><ClCompile Include="Driver.c" /><ClCompile Include="Descriptor.c" /></ItemGroup>
   <ItemGroup><ClInclude Include="Driver.h" /><ClInclude Include="..\shared\TouchpadIoctl.h" /></ItemGroup>

windows/shared/TouchpadIoctl.h

@@ -13,7 +13,7 @@
 #define MTP_INT32 int32_t
 #endif
 
-#define MTP_IOCTL_ABI_VERSION 1u
+#define MTP_IOCTL_ABI_VERSION 2u
 #define MTP_HID_MAX_CONTACTS 5u
 #define MTP_COORDINATE_LOGICAL_MAX 32767u