fantasia-keybinds

name: fantasia-keybinds description: >- Global keyboard shortcuts (faKeybinds): renderer matching, Pinia store, main-process persistence over IPC, and Keybind settings UI. Use when adding or changing app-wide shortcuts, capture validation, or bridge APIs for keybind storage.

Fantasia Archive — global keyboard shortcuts (faKeybinds)

What exists today

Renderer keydown listener (capture) — calls dialog/app helpers without widening preload beyond getKeybinds / setKeybinds
Definitions: faKeybindCommandDefinitions.ts (FA_KEYBIND_COMMAND_DEFINITIONS)
Chord logic: faKeybindsChordFromEvent.ts, faKeybindsChordEqualityAndResolve.ts, faKeybindsChordDisplayAndConflict.ts
UI formatting: faKeybindsChordUiFormatting.ts — settings, menus, shortcut copy
Dispatch: faKeybindsGlobalDispatch.ts → faKeybindRunCommand.ts → runFaAction via FA_KEYBIND_COMMAND_TO_ACTION_ID (fantasia-action-manager)
Layout: MainLayout.vue registers after refreshKeybinds(); skipped in Storybook canvas + non-Electron
Chromium Ctrl+Shift suppress: main registerFaChromiumCtrlShiftShortcutSuppress (takes BrowserWindow) → createFaChromiumCtrlShiftGlobalShortcutForwardController (activate/deactivate); globalShortcut accelerators register only while main window focused (activate on focus, release on blur + teardown on close) so backgrounded app never intercepts chords in other apps. before-input-event already focus-scoped. Boot faChromiumForwardedKeyChord
Pinia: S_FaKeybinds.ts
Persistence: src-electron/mainScripts/keybinds/; registerFaKeybindsIpc.ts; FA_KEYBINDS_IPC
Preload: faKeybindsAPI.ts; types types/I_faKeybindsDomain.ts
Settings UI: DialogKeybindSettings/ — table from definitions; capture in dialogKeybindSettingsCapture*.ts
Shipped: openProjectSettings → openProjectSettingsDialog when active project

`src/scripts/keybinds/` — avoid fragmentation

Few domain modules: chord parse, equality/resolve, display/conflict, dispatch wiring. faKeybindRunCommand.ts stays thin for vi.mock seam — typescript-scripts.mdc.

Adding a new global command (checklist)

types/I_faKeybindsDomain.ts — append FA_KEYBIND_COMMAND_IDS
faKeybindCommandDefinitions.ts — one definition row
i18n/*/dialogs/L_dialogKeybindSettings.ts — commands.<camelCaseId>
faKeybindRunCommand.ts — FA_KEYBIND_COMMAND_TO_ACTION_ID row; register action in faActionDefinitions.ts
Tests — run command, dispatch integration, definitions, store, dialog, Electron IPC/preload

Persisted schema changes → Zod in src-electron/shared/ + keybinds_manager + bridge sync.

Playwright (`keyboard.press`)

Use faPlaywrightKeyboardChords.ts — primary vs literal Control per faKeybindExpandDefaultChord. Docs: playwright-tests.mdc, fantasia-testing.

fantasia-action-manager, fantasia-electron-preload, fantasia-electron-main, fantasia-quasar-vue, fantasia-i18n

Types

Shared types → types/. See types-folder.mdc.