개요

@wtre 님이 제보해주신 노트 관련 버그 3개 수정 (#81)

1. 노트 테두리 색 투명도가 동작 안 함

테두리 색 피커에 알파 슬라이더가 보이는데 아무리 내려도 100으로 고정되고, 게다가 테두리 투명도가 노트 배경 투명도에 딸려가서 "배경 투명 + 테두리만 보이는 직사각형"을 못 만드는 상태

noteBorderColor가 #RRGGBB hex 계약이라 피커가 준 rgba(...)의 알파를 저장 단계에서 버리고 있었고, 셰이더도 테두리 알파를 baseColor.a * borderMask로 계산하고 있어서 배경(노트) 투명도에 그대로 종속됐습니다. 그래서 테두리 알파를 독립적으로 줄 방법이 아예 없었던 것 같네요.

2. 다중 선택으로 테두리 색 바꿀 때 선택 색이 안 보임

여러 키 선택 후 테두리 색을 바꾸면 고른 색이 스와치/미리보기에 제대로 안 뜨는 문제. 저장 자체는 됐는데, 배치 스와치가 피커 닫혀 있을 때도 실제 공통값이 아니라 직전 로컬 상태를 표시하고 있었고, 색 바꾸는 도중 라이브 preview dispatch가 빠져 있어서 노트색/글로우색과 달리 테두리만 즉시 반영이 안 됐어요.

3. 노트 표시 위치 시간 해상도가 주사율/OBS fps에 종속

프레임 제한을 0으로 둬도 노트 시작 위치의 시간 해상도가 모니터 주사율(OBS는 OBS fps)에 묶이던 문제

키 입력은 폴링레이트로 정확하게 받는데, 정작 노트 생성을 requestAnimationFrame 안에서 처리하면서 startTime이 그 프레임의 performance.now()로 찍힌 것 같습니다. 그래서 프레임 사이 어디서 눌렀든 노트 시작이 프레임 경계로 스냅됨, OBS browser source는 CEF 오프스크린 렌더라 rAF 자체가 OBS fps(windowless_frame_rate)에 묶여서 더 눈에 띈 상태였습니다.

변경 내용

백엔드

• KeyPosition에 note_border_opacity(0~100, 기본 100) 추가 — 기존 note_opacity/note_glow_opacity와 동일하게 plain u32라 기존 저장값은 default로 그대로 호환
• keys:state payload에 eventAgeMs(입력 수신~emit 경과 ms) 추가 — Instant로 측정

프론트엔드

1. 테두리 투명도 분리

• noteBorderOpacity zod 스키마 + 노트 버퍼에 별도 noteBorderOpacity 속성, WebGL 셰이더에 독립 알파 채널(borderAlpha = vBorderOpacity * borderMask)로 노트 배경 알파에서 분리
• 테두리 색 피커가 버리던 알파를 noteBorderOpacity로 캡처하도록 변경(단일/배치 동일) 색은 hex 계약 유지
• colorUtils에 parseAlphaPercent/hexWithAlphaPercent 유틸 추가

2. 배치 테두리 색 표시/미리보기

• 노트색/글로우색과 같은 getBatchBorderColorDisplay() 헬퍼로 공통값/Mixed 표시 통일
• 색 변경 중 라이브 preview dispatch 추가

3. 입력 시각 기반 노트 시작

• 오버레이에서 rAF 래핑 제거하고 performance.now() - eventAgeMs로 실제 입력 시각을 복원해 노트 startTime에 반영 → 시작 위치가 프레임 경계에 양자화되지 않음
• delayed 노트 타이머는 max(0, ...)로 clamp, eventAgeMs도 0~250ms로 clamp(백엔드 stall/클럭 이상 방어)
• 플러그인 API 문서(onKeyState) en/ko 동기화

테스트

• 테두리 투명도 50%로 내렸을 때 테두리만 반투명, 노트 배경 투명도 0 + 테두리 100으로 "테두리만 보이는 직사각형" 정상 렌더 확인
• 다중 선택 테두리 색 변경 시 스와치/미리보기 즉시 반영, 공통값/Mixed 표시 확인
• 연타 시 노트 시작 위치가 입력 간격대로 분포(프레임 경계 스냅 없음), 키 딜레이 옵션 켠 상태 회귀 없음
• 기존 저장값 로드 시 테두리 투명도 100으로 호환 확인
• tsc --noEmit / eslint / prettier / cargo check / cargo clippy / 프로덕션 빌드 통과

시작 위치 양자화는 없앴지만, OBS browser source는 구조상 매 프레임 위치 갱신의 해상도가 OBS fps를 넘진 못해요(CEF OSR이라 브라우저가 더 자주 그려도 OBS가 안 받음) OBS 모드에선 browser source FPS를 60으로 맞추는 걸 권장