This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
npm run dev # Start Electron app in development mode
npm run build # Build Electron app for production
npm run lint # ESLint (src*/**/*.{ts,js,cjs,mjs,vue})
npm run format # Prettier (write)
npm run format:check # Prettier (check only)
npm run test:unit # Run vitest in watch mode
npm run test:unit:ci # Run vitest once (CI)
npm run test:unit:ui # Run vitest with UITo run a single test file:
npx vitest run test/vitest/__tests__/BuzzerPage.test.tsBuzzMaster is an Electron + Quasar + Vue 3 desktop app for hosting quiz shows with PlayStation buzz controllers (HID devices).
The app spawns two Electron BrowserWindow instances:
- Main window (
/) — the host's control interface - Cast window (
/cast) — the audience-facing display (non-interactive, always-on-top, transparent frame)
Windows communicate via Electron IPC channels defined in src-electron/castAPI/. The main window sends game state updates; the cast window mirrors them and routes to the appropriate cast page. The cast window stores a snapshot of the last received data so it can replay it when a new cast window is opened (cast:ready event).
The three IPC namespaces are:
appAPI— OS-level functions (locale, window management)windowAPI— Window controls (minimize, maximize, close)castAPI— Game state synchronization to the cast window
Preload scripts in src-electron/*/preload.ts expose safe IPC bridges to the renderer via window.appAPI, window.windowAPI, and window.castAPI. Types for these APIs are declared in common/.
Each game mode implements a state machine using the useGameState composable (src/composables/gameState.ts):
- State types are discriminated unions defined in
common/gameState/(e.g.,BuzzerState,QuizState,SimonState). Each state has agamefield (game mode name) and anamefield (phase within that game). useGameStore(Pinia,src/stores/game-store.ts) holds the currentGameState. Transitions between differentgamevalues are illegal and throw; you must reset first.useGameState<S>(initialState)wrapsuseGameStoreand provides:gameState— reactive read of current statetransition(from, to)— type-safe state transition builderonStateEntry,onStateExit,onStateDo— lifecycle hooks per state namecreateEvent— chains multiple transition rules
Game page components (e.g., src/pages/gameModes/BuzzerGamePage.vue) call useGameState with the initial state and wire up buzzer events to transition calls.
The cast store (src/stores/cast-store.ts) independently mirrors the game state for the cast window and handles routing to the correct cast page.
src/plugins/buzzer/ wraps the WebHID API:
BuzzerApi— top-level API; holds reactive arrays ofdonglesanddisconnectedDongles, emitspress/release/changeeventsDongle— one USB dongle (up to 4 controllers per dongle)Controller— one physical controller withsetLight(),buttons, andfind()(flash to locate)- HID device implementations live in
src/plugins/buzzer/hid/(PS2, PS3) useBuzzer()composable injects the API and exposescontrollers(flat list, disabled ones filtered out),dongles, andbuzzer(the API itself)- New HID device vendor/product IDs must be registered in both
src/plugins/buzzer/hid/index.tsandsrc-electron/electron-main.ts(setDevicePermissionHandler)
common/ is shared between the renderer and main process. It contains:
gameState/— all game state type definitionsgameSettings/— settings types per game modeAppAPI,WindowAPI,CastAPI— TypeScript interfaces for the IPC bridges
| Store | Purpose |
|---|---|
game-store |
Current game state (main window) |
cast-store |
Mirrored game state (cast window), handles cast routing |
game-settings-store |
Per-game settings (answer time, modes, etc.) |
leaderboard-store |
Points tracking across rounds |
battery-saving-store |
Battery saving warning state |
updater-store |
Auto-update state |
Locales: en-US (master schema), de-DE, es-ES. Located in src/i18n/. The en-US locale is the TypeScript source of truth — all keys must exist there first. The locale is persisted via appAPI.setLocale / appAPI.getLocale.
When adding a new game mode, add translation files under src/i18n/{locale}/gameMode/ and src/i18n/{locale}/cast/, then re-export from the index files.
Tests use vitest + @vue/test-utils + @pinia/testing. Test files live in test/vitest/__tests__/. Test utilities:
test/vitest/utils/mount.ts—mountPage()helper that sets up Quasar, Pinia, router, and the buzzer plugintest/vitest/utils/buzzer.ts—createDevice()for simulating HID input in teststest/vitest/utils/element-selector.ts—selector()fordata-testidattribute queriestest/vitest/install-timer.ts—installFakeTimer()for time-based state transitions
Game page tests drive the state machine by directly calling gameStore.transition() and simulating button presses via pressAndRelease().