import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { globalShortcut, ipcMain, powerMonitor } from 'electron' import { uIOhook, UiohookKey } from 'uiohook-napi' import type { UiohookKeyboardEvent, UiohookMouseEvent } from 'uiohook-napi' import { IPC_CHANNELS } from '@d3ro/core/ipc-channels' import { MouseButton, VK, createDefaultBindingMap, kb, validateBinding, } from '@d3ro/core/keybinding' import type { KeyBinding, MouseButtonCode } from '@d3ro/core/types' import { configSet, initInMemoryConfig, resetInMemoryConfig, saveKeyBindings, } from '../../../src/main/services/ConfigService' import { getKeyBindingService, uiohookCodeToVk, type KeyBindingTriggerPayload, } from '../../../src/main/services/KeyBindingService' import { registerKeyBindingHandlers } from '../../../src/main/ipc/keybinding-handlers' import { resetGlobalInputHookForTests } from '../../../src/main/services/global-input-hook' type HookHandler = (event: T) => void function createHookHarness(): { keydown: (event: Partial & { keycode: number }) => void keyup: (event: Partial & { keycode: number }) => void mousedown: (event: Partial & { button: unknown }) => void mouseup: (event: Partial & { button: unknown }) => void } { const findListener = (eventName: string): HookHandler => { const calls = vi.mocked(uIOhook.on).mock.calls for (let i = calls.length - 1; i >= 0; i -= 1) { const [registeredEvent, listener] = calls[i] if (registeredEvent === eventName && typeof listener === 'function') { return listener as unknown as HookHandler } } throw new Error(`No uIOhook listener registered for "${eventName}"`) } return { keydown: (event) => { findListener('keydown')({ type: 4, time: Date.now(), altKey: false, ctrlKey: false, metaKey: false, shiftKey: false, ...event, } as UiohookKeyboardEvent) }, keyup: (event) => { findListener('keyup')({ type: 5, time: Date.now(), altKey: false, ctrlKey: false, metaKey: false, shiftKey: false, ...event, } as UiohookKeyboardEvent) }, mousedown: (event) => { findListener('mousedown')({ type: 7, time: Date.now(), altKey: false, ctrlKey: false, metaKey: false, shiftKey: false, x: 0, y: 0, clicks: 1, ...event, } as UiohookMouseEvent) }, mouseup: (event) => { findListener('mouseup')({ type: 8, time: Date.now(), altKey: false, ctrlKey: false, metaKey: false, shiftKey: false, x: 0, y: 0, clicks: 1, ...event, } as UiohookMouseEvent) }, } } function mb( code: MouseButtonCode, mods: Partial> = {}, ): KeyBinding { return { device: 'mouse', code, ctrl: mods.ctrl ?? false, alt: mods.alt ?? false, shift: mods.shift ?? false, meta: mods.meta ?? false, } } const VK_F8 = VK.F1 + 7 const VK_F9 = VK.F1 + 8 describe('KeyBindingService', () => { const hook = createHookHarness() beforeEach(() => { vi.clearAllMocks() resetGlobalInputHookForTests() initInMemoryConfig({ hotkeyEnabled: true, suggestionEnabled: true, }) const service = getKeyBindingService() service.dispose() }) afterEach(() => { getKeyBindingService().dispose() resetGlobalInputHookForTests() resetInMemoryConfig() }) describe('keyboard & mouse event handling and lifecycle', () => { it('maps uiohook keycodes to canonical Windows VK codes and returns null for unknown codes', () => { expect(uiohookCodeToVk(UiohookKey.F8)).toBe(VK_F8) expect(uiohookCodeToVk(UiohookKey.AltRight)).toBe(VK.AltRight) expect(uiohookCodeToVk(UiohookKey.A)).toBe(VK.A) expect(uiohookCodeToVk(UiohookKey.Enter)).toBe(VK.Enter) expect(uiohookCodeToVk(999_999)).toBeNull() }) it('attaches uIOhook listeners on start, triggers keyboard actions, and cleans up on stop', () => { const map = createDefaultBindingMap() map.command = [kb(VK_F9, { ctrl: true })] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() expect(service.isRunning).toBe(true) expect(service.registeredBindingCount).toBeGreaterThan(0) hook.keydown({ keycode: UiohookKey.F9, ctrlKey: true }) hook.keyup({ keycode: UiohookKey.F9, ctrlKey: true }) expect(triggered).toEqual([ expect.objectContaining({ actionId: 'command', type: 'pressed', isDoublePress: false, }), expect.objectContaining({ actionId: 'command', type: 'released', isDoublePress: false, }), ]) service.stop() expect(service.isRunning).toBe(false) expect(uIOhook.removeListener).toHaveBeenCalledWith('keydown', expect.any(Function)) expect(uIOhook.removeListener).toHaveBeenCalledWith('keyup', expect.any(Function)) expect(uIOhook.removeListener).toHaveBeenCalledWith('mousedown', expect.any(Function)) expect(uIOhook.removeListener).toHaveBeenCalledWith('mouseup', expect.any(Function)) }) it('skips keyboard bindings whose VK has no uiohook mapping (e.g., VK.Pause)', () => { const map = createDefaultBindingMap() for (const key of Object.keys(map) as Array) { map[key] = [] } map.command = [kb(VK.Pause)] saveKeyBindings(map) const service = getKeyBindingService() service.loadFromConfig() expect(service.registeredBindingCount).toBe(0) }) it('releases held bindings when powerMonitor emits lock-screen or suspend', () => { const map = createDefaultBindingMap() map.dictation = [kb(VK_F8)] map['hands-free'] = [] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() hook.keydown({ keycode: UiohookKey.F8 }) expect(triggered).toHaveLength(1) expect(triggered[0]).toMatchObject({ actionId: 'dictation', type: 'pressed' }) const lockCall = vi .mocked(powerMonitor.on) .mock.calls.find(([event]) => (event as string) === 'lock-screen') expect(lockCall).toBeDefined() const lockHandler = lockCall?.[1] as (() => void) | undefined lockHandler?.() expect(triggered).toHaveLength(2) expect(triggered[1]).toMatchObject({ actionId: 'dictation', type: 'released' }) }) }) describe('mouse button binding rules (MB1 rejection, MB2/MB3 modifier requirement, MB4/MB5 free binding)', () => { it('rejects MB1 (Left click) both with and without modifiers in validation and IPC setBindings', async () => { expect(validateBinding(mb(MouseButton.Left))).toEqual({ valid: false, reason: 'device-disabled', reasonKey: 'keybinding.disabled.mouseLeft', warningKey: null, }) expect(validateBinding(mb(MouseButton.Left, { ctrl: true, alt: true }))).toEqual({ valid: false, reason: 'device-disabled', reasonKey: 'keybinding.disabled.mouseLeft', warningKey: null, }) const handlers = new Map unknown>() vi.mocked(ipcMain.handle).mockImplementation((channel, listener) => { handlers.set(channel, listener as (...args: unknown[]) => unknown) }) registerKeyBindingHandlers() const setBindings = handlers.get(IPC_CHANNELS.KEYBINDING.SET_BINDINGS)! const res = (await setBindings({}, { actionId: 'dictation', bindings: [mb(MouseButton.Left, { ctrl: true })], })) as { success: boolean; error?: { details?: { reason?: string } } } expect(res.success).toBe(false) expect(res.error?.details?.reason).toBe('device-disabled') }) it('requires a modifier for MB2 (Right) and MB3 (Middle), and triggers only when modifier is held', () => { expect(validateBinding(mb(MouseButton.Right))).toMatchObject({ valid: false, reason: 'modifier-required', reasonKey: 'keybinding.reject.modifierRequired', }) expect(validateBinding(mb(MouseButton.Middle))).toMatchObject({ valid: false, reason: 'modifier-required', reasonKey: 'keybinding.reject.modifierRequired', }) expect(validateBinding(mb(MouseButton.Right, { ctrl: true }))).toMatchObject({ valid: true, reason: null, warningKey: 'keybinding.warning.mousePassthrough', }) expect(validateBinding(mb(MouseButton.Middle, { alt: true }))).toMatchObject({ valid: true, reason: null, warningKey: 'keybinding.warning.mousePassthrough', }) const map = createDefaultBindingMap() map.command = [mb(MouseButton.Right, { ctrl: true })] map.caption = [mb(MouseButton.Middle, { alt: true })] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() // Unmodified MB2 / MB3 must not trigger hook.mousedown({ button: MouseButton.Right }) hook.mouseup({ button: MouseButton.Right }) hook.mousedown({ button: MouseButton.Middle }) hook.mouseup({ button: MouseButton.Middle }) expect(triggered).toHaveLength(0) // Ctrl+MB2 and Alt+MB3 trigger their respective actions hook.mousedown({ button: MouseButton.Right, ctrlKey: true }) hook.mouseup({ button: MouseButton.Right, ctrlKey: true }) hook.mousedown({ button: MouseButton.Middle, altKey: true }) hook.mouseup({ button: MouseButton.Middle, altKey: true }) expect( triggered.filter((t) => t.type === 'pressed').map((t) => t.actionId), ).toEqual(['command', 'caption']) }) it('allows free (unmodified) binding for MB4 (Back) and MB5 (Forward) and handles constituent mouseup release', () => { expect(validateBinding(mb(MouseButton.Back))).toMatchObject({ valid: true, reason: null, warningKey: 'keybinding.warning.mousePassthrough', }) expect(validateBinding(mb(MouseButton.Forward))).toMatchObject({ valid: true, reason: null, warningKey: 'keybinding.warning.mousePassthrough', }) const map = createDefaultBindingMap() map.dictation = [mb(MouseButton.Back)] map['hands-free'] = [] map.command = [mb(MouseButton.Forward)] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() // Press MB4 unmodified -> hold starts; release MB4 while Alt is held -> constituent button still releases hold! hook.mousedown({ button: MouseButton.Back }) hook.mouseup({ button: MouseButton.Back, altKey: true }) // Press MB5 unmodified -> triggers command hook.mousedown({ button: MouseButton.Forward }) hook.mouseup({ button: MouseButton.Forward }) expect(triggered).toEqual([ expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }), expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }), expect.objectContaining({ actionId: 'command', type: 'pressed', isDoublePress: false }), expect.objectContaining({ actionId: 'command', type: 'released', isDoublePress: false }), ]) }) }) describe('hold-to-talk vs double-press hands-free on shared binding', () => { it('distinguishes single hold (dictation) from rapid double-press (hands-free) on the same key', () => { const sharedBinding = kb(VK_F8) const map = createDefaultBindingMap() map.dictation = [sharedBinding] map['hands-free'] = [sharedBinding] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() let now = 1_000 const nowSpy = vi.spyOn(Date, 'now').mockImplementation(() => now) try { // 1. Single press & hold (>400ms gap afterwards) hook.keydown({ keycode: UiohookKey.F8, time: now }) now += 600 hook.keyup({ keycode: UiohookKey.F8, time: now }) expect(triggered).toEqual([ expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }), expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }), ]) triggered.length = 0 // 2. Wait past double-press window, then double-press within 150ms now += 1_000 hook.keydown({ keycode: UiohookKey.F8, time: now }) now += 80 hook.keyup({ keycode: UiohookKey.F8, time: now }) now += 100 hook.keydown({ keycode: UiohookKey.F8, time: now }) now += 80 hook.keyup({ keycode: UiohookKey.F8, time: now }) expect(triggered).toEqual([ expect.objectContaining({ actionId: 'dictation', type: 'pressed', isDoublePress: false }), expect.objectContaining({ actionId: 'dictation', type: 'released', isDoublePress: false }), expect.objectContaining({ actionId: 'hands-free', type: 'pressed', isDoublePress: true }), expect.objectContaining({ actionId: 'hands-free', type: 'released', isDoublePress: true }), ]) } finally { nowSpy.mockRestore() } }) }) describe('multiple bindings per action', () => { it('triggers the same action from multiple distinct keyboard and mouse bindings independently', () => { const map = createDefaultBindingMap() map.dictation = [kb(VK_F8), mb(MouseButton.Back)] map['hands-free'] = [] saveKeyBindings(map) const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() hook.keydown({ keycode: UiohookKey.F8 }) hook.keyup({ keycode: UiohookKey.F8 }) hook.mousedown({ button: MouseButton.Back }) hook.mouseup({ button: MouseButton.Back }) expect(triggered).toEqual([ expect.objectContaining({ actionId: 'dictation', type: 'pressed', binding: expect.objectContaining({ device: 'keyboard', code: VK_F8 }), }), expect.objectContaining({ actionId: 'dictation', type: 'released', binding: expect.objectContaining({ device: 'keyboard', code: VK_F8 }), }), expect.objectContaining({ actionId: 'dictation', type: 'pressed', binding: expect.objectContaining({ device: 'mouse', code: MouseButton.Back }), }), expect.objectContaining({ actionId: 'dictation', type: 'released', binding: expect.objectContaining({ device: 'mouse', code: MouseButton.Back }), }), ]) }) }) describe('suggestion capture accelerator registration & unregistration', () => { it('registers suggestion accelerators only while suggestion capture is active and suggestionEnabled is true', () => { const service = getKeyBindingService() service.loadFromConfig() service.start() // On Windows/Linux, no globalShortcut is registered when suggestion overlay is inactive vi.mocked(globalShortcut.register).mockClear() vi.mocked(globalShortcut.unregister).mockClear() service.setSuggestionCaptureActive(true) const registeredWhenActive = vi .mocked(globalShortcut.register) .mock.calls.map(([accelerator]) => accelerator) expect(registeredWhenActive).toEqual( expect.arrayContaining([ 'Control+Alt+Return', 'Control+Alt+Space', 'Control+Alt+Down', 'Control+Alt+Up', 'Control+Alt+Backspace', ]), ) // Deactivating suggestion capture unregisters all captured accelerators service.setSuggestionCaptureActive(false) const unregisteredWhenInactive = vi .mocked(globalShortcut.unregister) .mock.calls.map(([accelerator]) => accelerator) expect(unregisteredWhenInactive).toEqual( expect.arrayContaining([ 'Control+Alt+Return', 'Control+Alt+Space', 'Control+Alt+Down', 'Control+Alt+Up', 'Control+Alt+Backspace', ]), ) }) it('releases captured accelerators when suggestionEnabled is turned off and re-registers when turned back on', () => { const service = getKeyBindingService() service.loadFromConfig() service.start() service.setSuggestionCaptureActive(true) vi.mocked(globalShortcut.register).mockClear() vi.mocked(globalShortcut.unregister).mockClear() // Turning off suggestionEnabled releases captured shortcuts immediately configSet('suggestionEnabled', false) expect(vi.mocked(globalShortcut.unregister)).toHaveBeenCalledWith('Control+Alt+Return') vi.mocked(globalShortcut.register).mockClear() // Turning suggestionEnabled back on while capture is still wanted re-registers them configSet('suggestionEnabled', true) expect(vi.mocked(globalShortcut.register)).toHaveBeenCalledWith( 'Control+Alt+Return', expect.any(Function), ) }) it('triggers suggestion-accept for NumpadEnter and via OS capture fallback when uiohook misses the key', () => { vi.useFakeTimers() try { const service = getKeyBindingService() const triggered: KeyBindingTriggerPayload[] = [] service.on('triggered', (payload) => triggered.push(payload)) service.loadFromConfig() service.start() service.setSuggestionCaptureActive(true) // 1) NumpadEnter via uiohook hook.keydown({ keycode: UiohookKey.NumpadEnter, ctrlKey: true, altKey: true }) hook.keyup({ keycode: UiohookKey.NumpadEnter, ctrlKey: true, altKey: true }) expect(triggered.filter((t) => t.actionId === 'suggestion-accept' && t.type === 'pressed')).toHaveLength(1) // 2) OS globalShortcut callback fires without a recent uiohook press (e.g. elevated window / UIPI) vi.advanceTimersByTime(300) const returnCall = vi .mocked(globalShortcut.register) .mock.calls.find(([accelerator]) => accelerator === 'Control+Alt+Return') const callback = returnCall?.[1] as (() => void) | undefined expect(callback).toBeDefined() callback?.() vi.advanceTimersByTime(30) expect(triggered.filter((t) => t.actionId === 'suggestion-accept' && t.type === 'pressed')).toHaveLength(2) } finally { vi.useRealTimers() } }) }) })