# Windows native hotkey helper plan

## Goal

Enable hold-to-talk using modifier-only keys on Windows without relying on global shortcut registration.

## Current code skeleton

A helper crate now exists at:

- `src-tauri/native-helper/windows/helper`

It is designed to be built on Windows and emit newline-delimited JSON events for:

- `left_control`
- `left_alt`
- `left_shift`
- `left_command`
- `right_alt`
- `right_shift`
- `right_command`

## Recommended backend

- `SetWindowsHookExW(WH_KEYBOARD_LL, ...)`
- Read `WM_KEYDOWN`, `WM_KEYUP`, `WM_SYSKEYDOWN`, `WM_SYSKEYUP`
- Inspect virtual keys:
  - `VK_CONTROL`
  - `VK_LCONTROL`
  - `VK_MENU` / `VK_LMENU` (Alt)
  - `VK_SHIFT` / `VK_LSHIFT`
  - `VK_LWIN`
  - `VK_RMENU`
  - `VK_RSHIFT`
  - `VK_RWIN`

## Why not Fn

`Fn` is usually handled by keyboard firmware / OEM drivers and often never surfaces as a stable Win32 virtual key. That means:

- `Control / Alt / Shift` are realistic
- `Fn` should not be treated as a portable Windows key

## Suggested protocol to Tauri

Emit newline-delimited JSON to the Tauri host process:

```json
{"event":"modifier","key":"left_control","state":"down"}
{"event":"modifier","key":"left_control","state":"up"}
```

Additional keys can follow the same shape, but Windows should only promise:

- `left_control`
- `left_alt`
- `left_shift`
- `left_command`
- `right_alt`
- `right_shift`
- `right_command`

`fn` should be treated as unsupported / best effort only.

## Integration direction

1. Spawn helper at app startup
2. Read helper stdout asynchronously
3. Map helper events to renderer events:
   - `voice-hotkey-toggle`
4. Keep the current Tauri global shortcut path as the fallback backend

## Build command

Build on Windows:

```bash
cargo build --manifest-path src-tauri/native-helper/windows/helper/Cargo.toml --release
```

## Minimal implementation sketch

- helper thread installs `WH_KEYBOARD_LL`
- callback filters:
  - `WM_KEYDOWN`
  - `WM_KEYUP`
  - `WM_SYSKEYDOWN`
  - `WM_SYSKEYUP`
- convert to JSON lines on stdout:

```json
{"event":"modifier","key":"left_alt","state":"down"}
{"event":"modifier","key":"left_alt","state":"up"}
```
