feat: 마우스 휠 키 매핑과 노브 휠 연동 - #204

개요

마우스 휠 위·아래와 틸트 좌·우를 일반 키처럼 매핑할 수 있게 하고, 노브 요소를 휠에 연결해 휠 방향대로 돌아가게 함. 휠은 떼는 입력이 없어서 한 칸을 짧은 키 입력 한 번으로 처리하고, 카운터와 KPS는 굴린 칸 수와 같게 맞춤

관련 이슈: #197

변경 내용

휠 입력

• 휠 처리를 daemon/wheel.rs 한 곳으로 모음. 플랫폼 코드는 휠 원본 값만 넘기고 칸 계산, 키 입력 생성, 노브용 축 값은 공용 엔진에서 처리. 기존 HookMessage, HidAxisMessage를 그대로 써서 IPC 계약 변경 없음
• 한 칸마다 Down, 50ms 뒤 Up. 50ms 안에 다음 칸이 오면 바로 Up 후 Down을 보내서 빠르게 굴려도 칸이 빠지지 않음
• 고해상도 휠의 한 칸 미만 값은 누적해서 한 칸이 찼을 때 처리
• Windows는 기존 Raw Input 마우스 이벤트에서 휠 값을 읽음. 쓰지 않던 휠 상수는 엔진으로 옮김
• macOS는 IOHIDManager로 마우스 HID 휠 값을 직접 읽음. 스크롤 이벤트는 가속과 자연스러운 스크롤 반전이 적용된 값이라 칸 수로 쓸 수 없고, 트랙패드는 HID 휠 요소가 없어 휠로 잡히지 않음
• 고해상도 배율은 장치 연결 시 Resolution Multiplier 값을 읽어 반영. 입력 모니터링 권한을 나중에 허용해도 재시작 없이 다시 연결

노브

• 휠을 가상 축 WHEEL:VERTICAL, WHEEL:HORIZONTAL로 보냄. 24칸이 한 바퀴라 sensitivity 1이면 24칸에 360°
• 한 번에 크게 굴리면 값을 나눠 보내서 회전 방향이 뒤집히지 않게 함. 매번 이동 전 값을 먼저 보내서 휠을 굴리던 중에 열린 오버레이도 첫 칸부터 반영
• 데몬이 다시 뜨면 축 값이 0부터 시작하는데 이전 값과 이어 계산해 노브가 거꾸로 튀던 문제. 키보드 훅 재시작과 OBS 재동기화 때 축 기준값 초기화
• 노브 패널에서 휠 축을 마우스 휠, 마우스 가로 휠로 표시

설정 화면·오버레이

• 키 표시 이름 Wheel Up, Wheel Down, Wheel Left, Wheel Right 추가
• 휠로 키를 할당할 때 속성 패널이 같이 스크롤되던 문제. 할당 대기 중에는 휠 스크롤 차단
• 이벤트 하나에 여러 칸이 담기면 같은 키 노트가 같은 시각에 생겨 id가 겹치던 문제. id에 순번을 붙여 구분

플러그인 API

• onRawInput 문서에 휠 라벨과 Down/Up 규칙, 노브 문서에 휠 축 식별자 추가
• 영어와 한국어 문서 양쪽 반영

알려진 동작

• 휠 Up은 실제로 뗀 시각이 아니라 계산된 시각. hold는 50ms 또는 다음 칸까지의 간격
• 이벤트 하나에 여러 칸이 담기면 중간 노트는 길이 0. 앞뒤 노트가 붙어 보이고 카운터는 정상
• 트랙패드와 Magic Mouse 스크롤은 휠로 인식하지 않음. 관성 스크롤까지 칸으로 세면 한 번 쓸어내릴 때 수백 칸이 됨
• macOS에서 휠을 가로채는 마우스 유틸리티를 쓰면 인식되지 않을 수 있음
• 휠은 마우스 버튼처럼 키음 없음
• 휠을 매핑하지 않았으면 다른 앱에서 스크롤해도 카운터와 KPS 변화 없음

검증

• Vitest 4,665 통과, 18 스킵, 실패 0
• Rust 1,198 통과, 6 스킵, 실패 0
• TypeScript, ESLint, Prettier, Clippy -D warnings, rustfmt 통과
• 회귀 테스트는 수정을 되돌리면 실패하는 것 확인
• macOS에서 트랙패드 제외와 데몬 실행 확인. 휠 마우스가 없어 실제 휠 입력은 미확인

리뷰 포인트

Windows 쪽 Rust 코드는 이 PR CI에서 처음 컴파일됨. CI 통과 후 Windows 실기 확인 부탁

• 키 할당 대기 중 휠 위·아래, 틸트 좌·우가 Wheel Up, Wheel Down, Wheel Left, Wheel Right로 잡힘
• 한 칸씩 10칸 굴리면 카운터 +10, 노트 10개
• 빠르게 굴리면 키가 눌린 상태로 유지되고 노트가 이어지며 카운터는 굴린 칸 수와 같음
• 위로 굴리다 바로 아래로 굴리면 Wheel Up이 바로 떨어지고 Wheel Down이 눌림
• 고해상도 휠도 칸 수 일치
• 노브 감지 후 휠을 굴리면 마우스 휠로 연결되고 24칸에 한 바퀴
• OBS 모드에서 휠 키와 노브가 오버레이와 같게 동작
• 정밀 터치패드 두 손가락 스크롤이 휠로 잡히는지
• 마우스 전용 소프트웨어의 스무스 스크롤 등을 켰을 때 인식 여부와 중복 집계 여부