정확성(Accuracy) 우선 설계/제약

ByteFlusher는 타이핑 속도보다 정확성(누락/중복/깨짐 방지)을 우선합니다. 이 문서는 “왜 이렇게 설계했는지”, “어떤 제약이 있는지”, “정확도를 위해 무엇을 조절해야 하는지”를 Q&A 형태로 정리합니다.

Q. 왜 USB HID(키보드) 방식이면서도 정확성이 어렵나요?

USB HID 키보드 입력은 OS/앱 관점에서 “사람이 누르는 키”와 동일하게 처리됩니다. 따라서 아래 요소가 정확성을 깨뜨릴 수 있습니다.

• 포커스 이동(알림/팝업/UAC/자동완성/다른 창 클릭)
• IME(한/영 전환, 조합 중 상태)와 앱 내부 입력기 동작 차이
• 앱의 자동 기능(자동 들여쓰기/자동 괄호/자동 완성/자동 포맷)
• 키 입력이 너무 빠를 때 발생하는 누락(특히 콘솔/원격환경/가상화)

정확성은 “전송이 정확함” + “타깃 입력기가 정확히 받음” 두 축이 모두 만족되어야 합니다.

Q. ByteFlusher는 정확성을 위해 무엇을 하나요?

크게 3개입니다.

1) 중복 방지(프로토콜)

• BLE 청크에 sessionId/seq를 포함하고, 이미 처리한 청크는 무시해 중복 타이핑을 막습니다.

2) Flow Control(버퍼 기반)

• 장치 RX 버퍼 여유를 상태로 알려주고, 웹이 여유가 있을 때만 전송합니다.
• 목적: 버퍼를 과도하게 밀어넣지 않아 Pause/Stop이 진짜 즉시 멈추도록 합니다.

3) 타이핑 타이밍(안정화)

• 문자 입력 후 대기(typingDelay), 키 눌림 유지(keyPressDelay), 한/영 전환 후 대기(modeSwitchDelay)를 둡니다.
• 기본값은 빠르기보다 안정성에 맞춘 값입니다.

Q. 정확성 관점에서 중요한 제약은?

• 포커스는 자동으로 보장 불가: 시작 전 커서 위치 확인, 실행 중 포커스 유지가 필수입니다.
• IME 동기화 100% 보장 불가: 토글 결과는 환경/상태에 따라 달라질 수 있습니다.
• 앱 자동기능이 오입력/변형을 만들 수 있습니다(IDE 먼저 끄고 테스트).
• 길이가 길수록 실패 확률 누적: 긴 작업은 분할 전략이 유리합니다.

Q. 정확성 우선 권장 세팅은?

권장(시작점):

• typingDelayMs: 30~80ms (환경이 느리면 120ms까지)
• keyPressDelayMs: 10~30ms
• modeSwitchDelayMs: 100~400ms (IME가 불안정하면 800ms까지)

먼저 단순 에디터(메모장)에서 성공률을 확보한 뒤, IDE/터미널로 옮기는 것을 권장합니다.

원본(Markdown): docs/accuracy-design.md