/** * Key events as the rest of Faceclaw sees them, and the translation from the * keyboard bridge's raw HID transitions: layout (US only for now), modifier * and Caps Lock state, and typematic repeat, which a BLE keyboard never sends * (its report just stays asserted). The translation tables follow the Glassly * app's (GlassesKeyboardInput.ts, MIT). * No platform imports: this runs under node in the tests, and in app workers. */ import type { HidKeyEvent } from "./hid"; export type KeyModifiers = { shift: boolean; ctrl: boolean; alt: boolean; meta: boolean }; /** * One key transition, shaped like a DOM KeyboardEvent: `key` is the logical * key with the layout applied ("a", "A", "Enter", "ArrowUp"), `code` the * physical key ("KeyA"), `text` what a press types (absent for releases, for * keys that type nothing, and for Ctrl/Alt/Meta chords, which are commands). */ export type KeyEvent = { phase: "down" | "up"; key: string; code: string; text?: string; modifiers: KeyModifiers; /** A synthesized auto-repeat of a held key. */ repeat: boolean; /** * One of a stream that can arrive faster than it can be acted on (a wheel * turning): whoever acts on it may drop some rather than fall behind. */ burst?: boolean; /** Date.now() when the phone saw the transition. */ timestampMs: number; }; const HID_PAGE_KEYBOARD = 7; const HID_PAGE_CONSUMER = 12; /** A mouse's buttons, which arrive here as keys: usage 1 is the left button, 2 the right, 3 the middle. */ export const HID_PAGE_BUTTON = 9; const USAGE_CAPS_LOCK = 57; /** [unshifted, shifted, code] for US-layout punctuation on the keyboard page. */ const PUNCTUATION: Record = { 45: ["-", "_", "Minus"], 46: ["=", "+", "Equal"], 47: ["[", "{", "BracketLeft"], 48: ["]", "}", "BracketRight"], 49: ["\\", "|", "Backslash"], 50: ["#", "~", "IntlHash"], 51: [";", ":", "Semicolon"], 52: ["'", '"', "Quote"], 53: ["`", "~", "Backquote"], 54: [",", "<", "Comma"], 55: [".", ">", "Period"], 56: ["/", "?", "Slash"], 100: ["\\", "|", "IntlBackslash"], }; const DIGITS = "1234567890"; const SHIFTED_DIGITS = "!@#$%^&*()"; /** [key, code] for keys that type nothing. */ const NAMED: Record = { 40: ["Enter", "Enter"], 41: ["Escape", "Escape"], 42: ["Backspace", "Backspace"], 43: ["Tab", "Tab"], 57: ["CapsLock", "CapsLock"], 70: ["PrintScreen", "PrintScreen"], 71: ["ScrollLock", "ScrollLock"], 72: ["Pause", "Pause"], 73: ["Insert", "Insert"], 74: ["Home", "Home"], 75: ["PageUp", "PageUp"], 76: ["Delete", "Delete"], 77: ["End", "End"], 78: ["PageDown", "PageDown"], 79: ["ArrowRight", "ArrowRight"], 80: ["ArrowLeft", "ArrowLeft"], 81: ["ArrowDown", "ArrowDown"], 82: ["ArrowUp", "ArrowUp"], 83: ["NumLock", "NumLock"], 88: ["Enter", "NumpadEnter"], 101: ["ContextMenu", "ContextMenu"], 102: ["Power", "Power"], 224: ["Control", "ControlLeft"], 225: ["Shift", "ShiftLeft"], 226: ["Alt", "AltLeft"], 227: ["Meta", "MetaLeft"], 228: ["Control", "ControlRight"], 229: ["Shift", "ShiftRight"], 230: ["Alt", "AltRight"], 231: ["Meta", "MetaRight"], }; /** [key and text, code] for the numeric keypad's operators. */ const NUMPAD: Record = { 84: ["/", "NumpadDivide"], 85: ["*", "NumpadMultiply"], 86: ["-", "NumpadSubtract"], 87: ["+", "NumpadAdd"], 99: [".", "NumpadDecimal"], 103: ["=", "NumpadEqual"], }; const CONSUMER: Record = { 0xe9: "AudioVolumeUp", 0xea: "AudioVolumeDown", 0xe2: "AudioVolumeMute", 0xcd: "MediaPlayPause", 0xb0: "MediaPlay", 0xb1: "MediaPause", 0xb5: "MediaTrackNext", 0xb6: "MediaTrackPrevious", 0xb7: "MediaStop", 0x6f: "BrightnessUp", 0x70: "BrightnessDown", 0x221: "BrowserSearch", 0x223: "BrowserHome", 0x224: "BrowserBack", 0x225: "BrowserForward", 0x18a: "LaunchMail", 0x192: "LaunchApplication2", 0x194: "LaunchApplication1", }; const MODIFIER_USAGES: Record = { 224: "ctrl", 228: "ctrl", 225: "shift", 229: "shift", 226: "alt", 230: "alt", 227: "meta", 231: "meta", }; type Translated = { key: string; code: string; text?: string }; /** One HID usage under the US layout. Caps Lock only affects letters. */ export function translateUsage(page: number, usage: number, shift: boolean, capsLock: boolean): Translated { if (page === HID_PAGE_KEYBOARD) { if (usage >= 4 && usage <= 29) { const lower = String.fromCharCode(97 + usage - 4); const key = shift !== capsLock ? lower.toUpperCase() : lower; return { key, code: `Key${lower.toUpperCase()}`, text: key }; } if (usage >= 30 && usage <= 39) { const index = usage - 30; const key = shift ? SHIFTED_DIGITS[index]! : DIGITS[index]!; return { key, code: `Digit${DIGITS[index]}`, text: key }; } if (usage === 44) return { key: " ", code: "Space", text: " " }; const punctuation = PUNCTUATION[usage]; if (punctuation) { const key = shift ? punctuation[1] : punctuation[0]; return { key, code: punctuation[2], text: key }; } if (usage >= 58 && usage <= 69) return { key: `F${usage - 57}`, code: `F${usage - 57}` }; if (usage >= 104 && usage <= 115) return { key: `F${usage - 91}`, code: `F${usage - 91}` }; if (usage >= 89 && usage <= 97) { const digit = String(usage - 88); return { key: digit, code: `Numpad${digit}`, text: digit }; } if (usage === 98) return { key: "0", code: "Numpad0", text: "0" }; const numpad = NUMPAD[usage]; if (numpad) return { key: numpad[0], code: numpad[1], text: numpad[0] }; const named = NAMED[usage]; if (named) return { key: named[0], code: named[1] }; return { key: "Unidentified", code: `Usage${usage.toString(16).padStart(2, "0")}` }; } if (page === HID_PAGE_CONSUMER) { const name = CONSUMER[usage]; return name ? { key: name, code: name } : { key: "Unidentified", code: `Consumer${usage.toString(16)}` }; } if (page === HID_PAGE_BUTTON) return { key: `MouseButton${usage}`, code: `MouseButton${usage}` }; return { key: "Unidentified", code: `Page${page.toString(16)}Usage${usage.toString(16)}` }; } export type KeyTranslatorOptions = { emit: (event: KeyEvent) => void; now?: () => number; setTimer?: (callback: () => void, delayMs: number) => unknown; clearTimer?: (handle: unknown) => void; /** Hold time before the first repeat, and the gap between repeats. */ repeatDelayMs?: number; repeatIntervalMs?: number; }; const REPEAT_DELAY_MS = 400; const REPEAT_INTERVAL_MS = 50; /** * Raw HID transitions in, KeyEvents out. Modifier state comes from the same * stream, and the bridge reports a release for every key when the stream may * have lost something, so a missed key-up cannot leave a modifier stuck or a * key repeating forever. */ export class KeyTranslator { private readonly emitEvent: (event: KeyEvent) => void; private readonly now: () => number; private readonly setTimer: (callback: () => void, delayMs: number) => unknown; private readonly clearTimer: (handle: unknown) => void; private readonly repeatDelayMs: number; private readonly repeatIntervalMs: number; private readonly held = new Set(); private modifiers: KeyModifiers = { shift: false, ctrl: false, alt: false, meta: false }; private capsLock = false; private repeatTimer: unknown = null; private repeating: { page: number; usage: number } | null = null; constructor(options: KeyTranslatorOptions) { this.emitEvent = options.emit; this.now = options.now ?? (() => Date.now()); this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs)); this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType)); this.repeatDelayMs = options.repeatDelayMs ?? REPEAT_DELAY_MS; this.repeatIntervalMs = options.repeatIntervalMs ?? REPEAT_INTERVAL_MS; } /** Apply the transitions one input report produced, in order. */ handle(events: readonly HidKeyEvent[]): void { for (const event of events) this.handleOne(event); } private handleOne(event: HidKeyEvent): void { const id = `${event.page}:${event.usage}`; const modifier = event.page === HID_PAGE_KEYBOARD ? MODIFIER_USAGES[event.usage] : undefined; if (event.down) { if (this.held.has(id)) return; this.held.add(id); if (modifier) this.modifiers[modifier] = true; if (event.page === HID_PAGE_KEYBOARD && event.usage === USAGE_CAPS_LOCK) this.capsLock = !this.capsLock; this.emit("down", event.page, event.usage, false); // The newest non-modifier key is the one that repeats, as on a PC. A // mouse button neither repeats nor takes the repeat from a held key. if (!modifier && event.page !== HID_PAGE_BUTTON) this.startRepeat(event.page, event.usage); } else { if (!this.held.delete(id)) return; if (modifier) this.modifiers[modifier] = this.otherHeld(event.usage, modifier); if (this.repeating?.page === event.page && this.repeating.usage === event.usage) this.stopRepeat(); this.emit("up", event.page, event.usage, false); } } /** * A press and release in one, for input that has no "held" (a wheel's * detent): `name` is both the key and the code, e.g. "WheelUp". Carries * the modifiers held on the keyboard, like any key. */ pulse(name: string): void { const timestampMs = this.now(); for (const phase of ["down", "up"] as const) { this.emitEvent({ phase, key: name, code: name, modifiers: { ...this.modifiers }, repeat: false, burst: true, timestampMs }); } } /** The keyboard went away: forget everything without emitting releases. */ reset(): void { this.stopRepeat(); this.held.clear(); this.modifiers = { shift: false, ctrl: false, alt: false, meta: false }; this.capsLock = false; } /** Whether the same modifier's key on the other side is still down. */ private otherHeld(released: number, modifier: keyof KeyModifiers): boolean { for (const [usage, name] of Object.entries(MODIFIER_USAGES)) { if (name === modifier && Number(usage) !== released && this.held.has(`${HID_PAGE_KEYBOARD}:${usage}`)) return true; } return false; } private emit(phase: "down" | "up", page: number, usage: number, repeat: boolean): void { const translated = translateUsage(page, usage, this.modifiers.shift, this.capsLock); const event: KeyEvent = { phase, key: translated.key, code: translated.code, modifiers: { ...this.modifiers }, repeat, timestampMs: this.now(), }; if (phase === "down" && translated.text !== undefined && !this.modifiers.ctrl && !this.modifiers.alt && !this.modifiers.meta) { event.text = translated.text; } this.emitEvent(event); } private startRepeat(page: number, usage: number): void { this.stopRepeat(); this.repeating = { page, usage }; this.repeatTimer = this.setTimer(() => this.repeatTick(), this.repeatDelayMs); } private repeatTick(): void { const key = this.repeating; this.repeatTimer = null; if (!key || !this.held.has(`${key.page}:${key.usage}`)) { this.repeating = null; return; } this.emit("down", key.page, key.usage, true); this.repeatTimer = this.setTimer(() => this.repeatTick(), this.repeatIntervalMs); } private stopRepeat(): void { if (this.repeatTimer !== null) this.clearTimer(this.repeatTimer); this.repeatTimer = null; this.repeating = null; } }