# 02. IPC 채널 & 타입 명세서

> D3RO-VOICE의 모든 IPC 채널, TypeScript 타입, 에러 코드, preload API를 정의한다.
> Speakly의 ~200개 IPC 채널을 참고하되, 클라우드/인증/텔레메트리를 제거하고 로컬 서비스(STT, TTS, LLM)를 추가한다.

---

## 1. IPC 채널 전체 목록

### 방향 범례

| 기호 | Electron API | 설명 |
|------|-------------|------|
| `handle` | `ipcMain.handle` / `ipcRenderer.invoke` | 양방향 (요청→응답) |
| `on` | `ipcMain.on` | 단방향 Renderer → Main (fire-and-forget) |
| `send` | `webContents.send` | 단방향 Main → Renderer (푸시 이벤트) |

---

### 1.1 `voice:*` -- 음성 녹음/인식 오케스트레이션

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `voice:startRecording` | handle | `StartRecordingParams` | `StartRecordingResult` | VoiceModeService | 녹음 세션 시작 (마이크 캡처 + STT 준비) |
| `voice:stopRecording` | handle | `StopRecordingParams` | `StopRecordingResult` | VoiceModeService | 녹음 중단 및 최종 전사 요청 |
| `voice:cancelRecording` | handle | `CancelRecordingParams` | `void` | VoiceModeService | 녹음 취소 (결과 버림) |
| `voice:getState` | handle | `void` | `VoiceState` | VoiceModeService | 현재 RecognitionState + AudioState 조회 |
| `voice:setMode` | handle | `SetVoiceModeParams` | `void` | VoiceModeService | 녹음 모드 변경 (dictation/hands-free) |
| `voice:getMode` | handle | `void` | `VoiceMode` | VoiceModeService | 현재 녹음 모드 조회 |
| `voice:stateChanged` | send | -- | `VoiceStateChangedEvent` | VoiceModeService | 상태 전이 알림 |
| `voice:transcriptionDelta` | send | -- | `TranscriptionDeltaEvent` | VoiceModeService | 중간 전사 결과 스트리밍 |
| `voice:transcriptionComplete` | send | -- | `TranscriptionCompleteEvent` | VoiceModeService | 최종 전사 결과 |
| `voice:error` | send | -- | `VoiceErrorEvent` | VoiceModeService | 음성 처리 에러 알림 |
| `voice:audioLevel` | send | -- | `AudioLevelEvent` | VoiceModeService | 오디오 레벨 (웨이브 바 애니메이션용, ~100ms 간격) |

### 1.2 `audio:*` -- 오디오 디바이스 & 캡처

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `audio:getDevices` | handle | `void` | `AudioDevice[]` | AudioCaptureService | 사용 가능한 마이크 디바이스 목록 |
| `audio:getSelectedDevice` | handle | `void` | `string \| null` | AudioCaptureService | 현재 선택된 디바이스 ID |
| `audio:setSelectedDevice` | handle | `SetDeviceParams` | `void` | AudioCaptureService | 마이크 디바이스 변경 |
| `audio:testDevice` | handle | `TestDeviceParams` | `TestDeviceResult` | AudioCaptureService | 마이크 테스트 (짧은 캡처 후 레벨 반환) |
| `audio:deviceChanged` | send | -- | `AudioDeviceChangedEvent` | AudioCaptureService | 디바이스 연결/해제 알림 |

### 1.3 `stt:*` -- 로컬 STT (Whisper)

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `stt:getStatus` | handle | `void` | `STTStatus` | LocalSTTService | STT 엔진 상태 (모델 로딩 여부, 버전 등) |
| `stt:getModels` | handle | `void` | `STTModel[]` | LocalSTTService | 사용 가능한 Whisper 모델 목록 |
| `stt:getActiveModel` | handle | `void` | `string \| null` | LocalSTTService | 현재 활성 모델 ID |
| `stt:setModel` | handle | `SetSTTModelParams` | `void` | LocalSTTService | 사용할 Whisper 모델 변경 |
| `stt:downloadModel` | handle | `DownloadModelParams` | `void` | LocalSTTService | 모델 다운로드 시작 |
| `stt:cancelDownload` | handle | `void` | `void` | LocalSTTService | 진행 중인 모델 다운로드 취소 |
| `stt:getLanguage` | handle | `void` | `string` | LocalSTTService | STT 인식 언어 조회 |
| `stt:setLanguage` | handle | `SetSTTLanguageParams` | `void` | LocalSTTService | STT 인식 언어 변경 |
| `stt:statusChanged` | send | -- | `STTStatusChangedEvent` | LocalSTTService | STT 엔진 상태 변경 알림 |
| `stt:downloadProgress` | send | -- | `DownloadProgressEvent` | LocalSTTService | 모델 다운로드 진행률 |

### 1.4 `tts:*` -- 로컬 TTS

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `tts:speak` | handle | `TTSSpeakParams` | `TTSSpeakResult` | LocalTTSService | 텍스트를 음성으로 변환 및 재생 |
| `tts:stop` | handle | `void` | `void` | LocalTTSService | 현재 재생 중단 |
| `tts:getVoices` | handle | `void` | `TTSVoice[]` | LocalTTSService | 사용 가능한 음성 목록 |
| `tts:getActiveVoice` | handle | `void` | `string \| null` | LocalTTSService | 현재 활성 음성 ID |
| `tts:setVoice` | handle | `SetTTSVoiceParams` | `void` | LocalTTSService | 사용할 음성 변경 |
| `tts:getStatus` | handle | `void` | `TTSStatus` | LocalTTSService | TTS 엔진 상태 |
| `tts:downloadVoice` | handle | `DownloadVoiceParams` | `void` | LocalTTSService | 음성 모델 다운로드 |
| `tts:statusChanged` | send | -- | `TTSStatusChangedEvent` | LocalTTSService | TTS 엔진 상태 변경 알림 |
| `tts:speakingStateChanged` | send | -- | `SpeakingStateChangedEvent` | LocalTTSService | 재생 시작/완료 알림 |

### 1.5 `llm:*` -- 로컬 LLM (Ollama)

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `llm:getStatus` | handle | `void` | `LLMStatus` | LocalLLMService | Ollama 서버 연결 상태 |
| `llm:getModels` | handle | `void` | `LLMModel[]` | LocalLLMService | 사용 가능한 모델 목록 |
| `llm:getActiveModel` | handle | `void` | `string \| null` | LocalLLMService | 현재 활성 모델 ID |
| `llm:setModel` | handle | `SetLLMModelParams` | `void` | LocalLLMService | 사용할 모델 변경 |
| `llm:process` | handle | `LLMProcessParams` | `LLMProcessResult` | LocalLLMService | 텍스트 처리 (다듬기, 번역, 요약 등) |
| `llm:cancelProcess` | handle | `void` | `void` | LocalLLMService | 진행 중인 LLM 처리 취소 |
| `llm:getServerUrl` | handle | `void` | `string` | LocalLLMService | Ollama 서버 URL 조회 |
| `llm:setServerUrl` | handle | `SetServerUrlParams` | `void` | LocalLLMService | Ollama 서버 URL 변경 |
| `llm:pullModel` | handle | `PullModelParams` | `void` | LocalLLMService | Ollama 모델 pull 시작 |
| `llm:statusChanged` | send | -- | `LLMStatusChangedEvent` | LocalLLMService | Ollama 연결 상태 변경 알림 |
| `llm:processProgress` | send | -- | `LLMProcessProgressEvent` | LocalLLMService | LLM 처리 스트리밍 (토큰 단위) |
| `llm:pullProgress` | send | -- | `LLMPullProgressEvent` | LocalLLMService | 모델 pull 진행률 |

### 1.6 `hotkey:*` -- 핫키 설정

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `hotkey:getDictationShortcut` | handle | `void` | `HotkeyBinding` | HotkeyService | 받아쓰기 핫키 조회 |
| `hotkey:setDictationShortcut` | handle | `SetHotkeyParams` | `void` | HotkeyService | 받아쓰기 핫키 변경 |
| `hotkey:getHandsFreeShortcut` | handle | `void` | `HotkeyBinding` | HotkeyService | 핸즈프리 모드 핫키 조회 |
| `hotkey:setHandsFreeShortcut` | handle | `SetHotkeyParams` | `void` | HotkeyService | 핸즈프리 모드 핫키 변경 |
| `hotkey:getCommandShortcut` | handle | `void` | `HotkeyBinding` | HotkeyService | 명령 모드 핫키 조회 |
| `hotkey:setCommandShortcut` | handle | `SetHotkeyParams` | `void` | HotkeyService | 명령 모드 핫키 변경 |
| `hotkey:isEnabled` | handle | `void` | `boolean` | HotkeyService | 핫키 활성화 상태 조회 |
| `hotkey:setEnabled` | handle | `SetEnabledParams` | `void` | HotkeyService | 핫키 전역 활성화/비활성화 |
| `hotkey:startRecording` | handle | `void` | `void` | HotkeyService | 핫키 녹화 모드 시작 (설정 UI용) |
| `hotkey:stopRecording` | handle | `void` | `HotkeyBinding \| null` | HotkeyService | 핫키 녹화 모드 종료 및 결과 반환 |
| `hotkey:triggered` | send | -- | `HotkeyTriggeredEvent` | HotkeyService | 핫키 입력 감지 알림 |
| `hotkey:recordingResult` | send | -- | `HotkeyRecordingResultEvent` | HotkeyService | 핫키 녹화 결과 알림 |

### 1.7 `config:*` -- 설정 관리

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `config:get` | handle | `ConfigGetParams` | `unknown` | ConfigService | 설정값 조회 (키 기반) |
| `config:set` | handle | `ConfigSetParams` | `void` | ConfigService | 설정값 변경 |
| `config:getAll` | handle | `void` | `AppConfig` | ConfigService | 전체 설정 조회 |
| `config:reset` | handle | `ConfigResetParams` | `void` | ConfigService | 설정값 초기화 (키 지정 또는 전체) |
| `config:getTheme` | handle | `void` | `ThemeMode` | ConfigService | 테마 조회 (light/dark/auto) |
| `config:setTheme` | handle | `SetThemeParams` | `void` | ConfigService | 테마 변경 |
| `config:getLanguage` | handle | `void` | `string` | ConfigService | UI 언어 조회 |
| `config:setLanguage` | handle | `SetLanguageParams` | `void` | ConfigService | UI 언어 변경 |
| `config:getAutoLaunch` | handle | `void` | `boolean` | ConfigService | 시작 시 자동 실행 여부 |
| `config:setAutoLaunch` | handle | `SetAutoLaunchParams` | `void` | ConfigService | 시작 시 자동 실행 설정 |
| `config:getCloseToTray` | handle | `void` | `boolean` | ConfigService | 닫기 버튼 시 트레이로 최소화 여부 |
| `config:setCloseToTray` | handle | `SetCloseToTrayParams` | `void` | ConfigService | 트레이로 최소화 설정 |
| `config:changed` | send | -- | `ConfigChangedEvent` | ConfigService | 설정 변경 알림 |

### 1.8 `history:*` -- 히스토리

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `history:getAll` | handle | `HistoryQueryParams` | `HistoryPage` | HistoryService | 히스토리 목록 조회 (페이지네이션) |
| `history:getById` | handle | `HistoryGetByIdParams` | `HistoryEntry \| null` | HistoryService | 단건 히스토리 조회 |
| `history:delete` | handle | `HistoryDeleteParams` | `void` | HistoryService | 히스토리 삭제 |
| `history:deleteAll` | handle | `void` | `void` | HistoryService | 전체 히스토리 삭제 |
| `history:search` | handle | `HistorySearchParams` | `HistoryPage` | HistoryService | 히스토리 전문 검색 |
| `history:export` | handle | `HistoryExportParams` | `string` | HistoryService | 히스토리 내보내기 (파일 경로 반환) |
| `history:added` | send | -- | `HistoryEntry` | HistoryService | 새 히스토리 추가 알림 |

### 1.9 `dictionary:*` -- 사전

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `dictionary:getAll` | handle | `DictionaryQueryParams` | `DictionaryPage` | DictionaryService | 사전 항목 목록 조회 |
| `dictionary:add` | handle | `DictionaryAddParams` | `DictionaryEntry` | DictionaryService | 사전 항목 추가 |
| `dictionary:update` | handle | `DictionaryUpdateParams` | `DictionaryEntry` | DictionaryService | 사전 항목 수정 |
| `dictionary:delete` | handle | `DictionaryDeleteParams` | `void` | DictionaryService | 사전 항목 삭제 |
| `dictionary:import` | handle | `DictionaryImportParams` | `DictionaryImportResult` | DictionaryService | 사전 가져오기 (CSV/JSON) |
| `dictionary:export` | handle | `DictionaryExportParams` | `string` | DictionaryService | 사전 내보내기 (파일 경로 반환) |
| `dictionary:search` | handle | `DictionarySearchParams` | `DictionaryPage` | DictionaryService | 사전 검색 |

### 1.10 `window:*` -- 윈도우 제어

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `window:minimize` | on | `void` | -- | WindowManager | 메인 윈도우 최소화 |
| `window:maximize` | on | `void` | -- | WindowManager | 메인 윈도우 최대화/복원 토글 |
| `window:close` | on | `void` | -- | WindowManager | 메인 윈도우 닫기 |
| `window:isMaximized` | handle | `void` | `boolean` | WindowManager | 최대화 상태 조회 |
| `window:showRecordingTip` | on | `ShowRecordingTipParams` | -- | WindowManager | RecordingTip 팝업 표시 |
| `window:hideRecordingTip` | on | `void` | -- | WindowManager | RecordingTip 팝업 숨김 |
| `window:showResultPopup` | on | `ShowResultPopupParams` | -- | WindowManager | ResultPopup 팝업 표시 |
| `window:hideResultPopup` | on | `void` | -- | WindowManager | ResultPopup 팝업 숨김 |
| `window:tipMeasured` | on | `TipMeasuredParams` | -- | WindowManager | RecordingTip 측정 완료 (2-phase 리사이즈) |
| `window:tipStateChanged` | send | -- | `TipStateChangedEvent` | WindowManager | RecordingTip 상태 변경 전달 |
| `window:tipPrepare` | send | -- | `TipPrepareEvent` | WindowManager | RecordingTip 측정 요청 (2-phase step 1) |
| `window:tipShow` | send | -- | `TipShowEvent` | WindowManager | RecordingTip 표시 요청 (2-phase step 2) |

### 1.11 `system:*` -- 시스템 (권한, 알림, 외부 앱)

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `system:getPlatform` | handle | `void` | `NodeJS.Platform` | SystemService | OS 플랫폼 조회 |
| `system:getVersion` | handle | `void` | `string` | SystemService | 앱 버전 조회 |
| `system:checkMicPermission` | handle | `void` | `PermissionStatus` | PermissionService | 마이크 권한 상태 확인 |
| `system:requestMicPermission` | handle | `void` | `PermissionStatus` | PermissionService | 마이크 권한 요청 |
| `system:showNotification` | handle | `ShowNotificationParams` | `void` | SystemService | 시스템 알림 표시 |
| `system:openExternal` | handle | `OpenExternalParams` | `void` | SystemService | 외부 URL/파일 열기 |
| `system:getActiveApp` | handle | `void` | `ActiveAppInfo \| null` | SystemService | 현재 활성 앱 정보 조회 |
| `system:insertText` | handle | `InsertTextParams` | `InsertTextResult` | TextInsertService | 활성 앱에 텍스트 삽입 (클립보드 방식) |
| `system:playSound` | handle | `PlaySoundParams` | `void` | SoundEffectService | 효과음 재생 |
| `system:setSoundEnabled` | handle | `SetSoundEnabledParams` | `void` | SoundEffectService | 효과음 on/off |
| `system:isSoundEnabled` | handle | `void` | `boolean` | SoundEffectService | 효과음 활성화 상태 |

### 1.12 `stats:*` -- 통계

| 채널명 | 방향 | 파라미터 타입 | 반환 타입 | 담당 서비스 | 설명 |
|--------|------|--------------|----------|------------|------|
| `stats:getSummary` | handle | `void` | `StatsSummary` | StatsService | 전체 통계 요약 (총 시간, 단어 수 등) |
| `stats:getDaily` | handle | `StatsQueryParams` | `DailyStats[]` | StatsService | 일별 통계 |
| `stats:getWeekly` | handle | `StatsQueryParams` | `WeeklyStats[]` | StatsService | 주별 통계 |
| `stats:updated` | send | -- | `StatsSummary` | StatsService | 통계 갱신 알림 |

---

## 2. `shared/ipc-channels.ts` 전체 코드

```typescript
// src/shared/ipc-channels.ts
// IPC 채널명 중앙 정의 — 모든 채널명은 이 파일에서만 정의한다.

export const IPC_CHANNELS = {
  VOICE: {
    START_RECORDING: 'voice:startRecording',
    STOP_RECORDING: 'voice:stopRecording',
    CANCEL_RECORDING: 'voice:cancelRecording',
    GET_STATE: 'voice:getState',
    SET_MODE: 'voice:setMode',
    GET_MODE: 'voice:getMode',
    // Main → Renderer events
    STATE_CHANGED: 'voice:stateChanged',
    TRANSCRIPTION_DELTA: 'voice:transcriptionDelta',
    TRANSCRIPTION_COMPLETE: 'voice:transcriptionComplete',
    ERROR: 'voice:error',
    AUDIO_LEVEL: 'voice:audioLevel',
  },

  AUDIO: {
    GET_DEVICES: 'audio:getDevices',
    GET_SELECTED_DEVICE: 'audio:getSelectedDevice',
    SET_SELECTED_DEVICE: 'audio:setSelectedDevice',
    TEST_DEVICE: 'audio:testDevice',
    // Main → Renderer events
    DEVICE_CHANGED: 'audio:deviceChanged',
  },

  STT: {
    GET_STATUS: 'stt:getStatus',
    GET_MODELS: 'stt:getModels',
    GET_ACTIVE_MODEL: 'stt:getActiveModel',
    SET_MODEL: 'stt:setModel',
    DOWNLOAD_MODEL: 'stt:downloadModel',
    CANCEL_DOWNLOAD: 'stt:cancelDownload',
    GET_LANGUAGE: 'stt:getLanguage',
    SET_LANGUAGE: 'stt:setLanguage',
    // Main → Renderer events
    STATUS_CHANGED: 'stt:statusChanged',
    DOWNLOAD_PROGRESS: 'stt:downloadProgress',
  },

  TTS: {
    SPEAK: 'tts:speak',
    STOP: 'tts:stop',
    GET_VOICES: 'tts:getVoices',
    GET_ACTIVE_VOICE: 'tts:getActiveVoice',
    SET_VOICE: 'tts:setVoice',
    GET_STATUS: 'tts:getStatus',
    DOWNLOAD_VOICE: 'tts:downloadVoice',
    // Main → Renderer events
    STATUS_CHANGED: 'tts:statusChanged',
    SPEAKING_STATE_CHANGED: 'tts:speakingStateChanged',
  },

  LLM: {
    GET_STATUS: 'llm:getStatus',
    GET_MODELS: 'llm:getModels',
    GET_ACTIVE_MODEL: 'llm:getActiveModel',
    SET_MODEL: 'llm:setModel',
    PROCESS: 'llm:process',
    CANCEL_PROCESS: 'llm:cancelProcess',
    GET_SERVER_URL: 'llm:getServerUrl',
    SET_SERVER_URL: 'llm:setServerUrl',
    PULL_MODEL: 'llm:pullModel',
    // Main → Renderer events
    STATUS_CHANGED: 'llm:statusChanged',
    PROCESS_PROGRESS: 'llm:processProgress',
    PULL_PROGRESS: 'llm:pullProgress',
  },

  HOTKEY: {
    GET_DICTATION_SHORTCUT: 'hotkey:getDictationShortcut',
    SET_DICTATION_SHORTCUT: 'hotkey:setDictationShortcut',
    GET_HANDS_FREE_SHORTCUT: 'hotkey:getHandsFreeShortcut',
    SET_HANDS_FREE_SHORTCUT: 'hotkey:setHandsFreeShortcut',
    GET_COMMAND_SHORTCUT: 'hotkey:getCommandShortcut',
    SET_COMMAND_SHORTCUT: 'hotkey:setCommandShortcut',
    IS_ENABLED: 'hotkey:isEnabled',
    SET_ENABLED: 'hotkey:setEnabled',
    START_RECORDING: 'hotkey:startRecording',
    STOP_RECORDING: 'hotkey:stopRecording',
    // Main → Renderer events
    TRIGGERED: 'hotkey:triggered',
    RECORDING_RESULT: 'hotkey:recordingResult',
  },

  CONFIG: {
    GET: 'config:get',
    SET: 'config:set',
    GET_ALL: 'config:getAll',
    RESET: 'config:reset',
    GET_THEME: 'config:getTheme',
    SET_THEME: 'config:setTheme',
    GET_LANGUAGE: 'config:getLanguage',
    SET_LANGUAGE: 'config:setLanguage',
    GET_AUTO_LAUNCH: 'config:getAutoLaunch',
    SET_AUTO_LAUNCH: 'config:setAutoLaunch',
    GET_CLOSE_TO_TRAY: 'config:getCloseToTray',
    SET_CLOSE_TO_TRAY: 'config:setCloseToTray',
    // Main → Renderer events
    CHANGED: 'config:changed',
  },

  HISTORY: {
    GET_ALL: 'history:getAll',
    GET_BY_ID: 'history:getById',
    DELETE: 'history:delete',
    DELETE_ALL: 'history:deleteAll',
    SEARCH: 'history:search',
    EXPORT: 'history:export',
    // Main → Renderer events
    ADDED: 'history:added',
  },

  DICTIONARY: {
    GET_ALL: 'dictionary:getAll',
    ADD: 'dictionary:add',
    UPDATE: 'dictionary:update',
    DELETE: 'dictionary:delete',
    IMPORT: 'dictionary:import',
    EXPORT: 'dictionary:export',
    SEARCH: 'dictionary:search',
  },

  WINDOW: {
    MINIMIZE: 'window:minimize',
    MAXIMIZE: 'window:maximize',
    CLOSE: 'window:close',
    IS_MAXIMIZED: 'window:isMaximized',
    SHOW_RECORDING_TIP: 'window:showRecordingTip',
    HIDE_RECORDING_TIP: 'window:hideRecordingTip',
    SHOW_RESULT_POPUP: 'window:showResultPopup',
    HIDE_RESULT_POPUP: 'window:hideResultPopup',
    TIP_MEASURED: 'window:tipMeasured',
    // Main → Renderer events
    TIP_STATE_CHANGED: 'window:tipStateChanged',
    TIP_PREPARE: 'window:tipPrepare',
    TIP_SHOW: 'window:tipShow',
  },

  SYSTEM: {
    GET_PLATFORM: 'system:getPlatform',
    GET_VERSION: 'system:getVersion',
    CHECK_MIC_PERMISSION: 'system:checkMicPermission',
    REQUEST_MIC_PERMISSION: 'system:requestMicPermission',
    SHOW_NOTIFICATION: 'system:showNotification',
    OPEN_EXTERNAL: 'system:openExternal',
    GET_ACTIVE_APP: 'system:getActiveApp',
    INSERT_TEXT: 'system:insertText',
    PLAY_SOUND: 'system:playSound',
    SET_SOUND_ENABLED: 'system:setSoundEnabled',
    IS_SOUND_ENABLED: 'system:isSoundEnabled',
  },

  STATS: {
    GET_SUMMARY: 'stats:getSummary',
    GET_DAILY: 'stats:getDaily',
    GET_WEEKLY: 'stats:getWeekly',
    // Main → Renderer events
    UPDATED: 'stats:updated',
  },
} as const;

// 타입 유틸리티: 채널명 유니온 추출
type NestedValues<T> = T extends Record<string, infer V>
  ? V extends string
    ? V
    : NestedValues<V>
  : never;

export type IPCChannel = NestedValues<typeof IPC_CHANNELS>;
```

---

## 3. `shared/types.ts` 전체 코드

```typescript
// src/shared/types.ts
// 모든 IPC 파라미터/반환 타입 정의

// ============================================================
// Common
// ============================================================

export type ThemeMode = 'light' | 'dark' | 'auto';

export type VoiceMode = 'dictation' | 'hands-free';

export type PermissionStatus = 'granted' | 'denied' | 'unknown';

// ============================================================
// Voice (음성 오케스트레이션)
// ============================================================

export enum RecognitionState {
  IDLE = 'idle',
  PREPARING = 'preparing',
  CONNECTING = 'connecting',
  READY = 'ready',
  RECOGNIZING = 'recognizing',
  COMPLETED = 'completed',
  CANCELLED = 'cancelled',
  ERROR = 'error',
  DESTROYED = 'destroyed',
}

export enum AudioState {
  IDLE = 'idle',
  INITIALIZING = 'initializing',
  STREAMING = 'streaming',
  STOPPED = 'stopped',
}

export interface VoiceState {
  recognitionState: RecognitionState;
  audioState: AudioState;
  mode: VoiceMode;
  sessionId: string | null;
  /** 현재 세션 녹음 시작 시각 (ms epoch), null이면 비활성 */
  recordingStartedAt: number | null;
}

export interface StartRecordingParams {
  /** 세션 ID (자동 생성 시 생략 가능) */
  sessionId?: string;
  /** 마이크 디바이스 ID (생략 시 기본 디바이스) */
  deviceId?: string;
}

export interface StartRecordingResult {
  sessionId: string;
}

export interface StopRecordingParams {
  sessionId: string;
}

export interface StopRecordingResult {
  sessionId: string;
  /** 최종 전사 텍스트 (완료 전이면 빈 문자열) */
  text: string;
  /** 녹음 지속 시간 (ms) */
  durationMs: number;
}

export interface CancelRecordingParams {
  sessionId: string;
}

export interface SetVoiceModeParams {
  mode: VoiceMode;
}

// Voice events (Main → Renderer)

export interface VoiceStateChangedEvent {
  previousState: RecognitionState;
  currentState: RecognitionState;
  audioState: AudioState;
  sessionId: string | null;
}

export interface TranscriptionDeltaEvent {
  sessionId: string;
  /** 중간 전사 텍스트 (누적) */
  text: string;
  /** 마지막 델타 부분 */
  delta: string;
  isFinal: boolean;
}

export interface TranscriptionCompleteEvent {
  sessionId: string;
  text: string;
  durationMs: number;
  language: string;
}

export interface VoiceErrorEvent {
  sessionId: string | null;
  errorCode: number;
  message: string;
}

export interface AudioLevelEvent {
  /** 0.0 ~ 1.0 정규화된 오디오 레벨 */
  level: number;
}

// ============================================================
// Audio (디바이스 & 캡처)
// ============================================================

export interface AudioDevice {
  deviceId: string;
  label: string;
  isDefault: boolean;
}

export interface SetDeviceParams {
  deviceId: string;
}

export interface TestDeviceParams {
  deviceId: string;
  /** 테스트 지속 시간 (ms), 기본 2000 */
  durationMs?: number;
}

export interface TestDeviceResult {
  /** 평균 오디오 레벨 (0.0 ~ 1.0) */
  averageLevel: number;
  /** 피크 오디오 레벨 */
  peakLevel: number;
  /** 오디오 데이터를 받았는지 여부 */
  hasAudio: boolean;
}

export interface AudioDeviceChangedEvent {
  devices: AudioDevice[];
  /** 변경 유형 */
  type: 'added' | 'removed' | 'default-changed';
}

// ============================================================
// STT (로컬 Whisper)
// ============================================================

export enum STTEngineState {
  NOT_INSTALLED = 'not-installed',
  DOWNLOADING = 'downloading',
  LOADING = 'loading',
  READY = 'ready',
  PROCESSING = 'processing',
  ERROR = 'error',
}

export interface STTStatus {
  engineState: STTEngineState;
  activeModel: string | null;
  /** faster-whisper 또는 whisper.cpp 버전 */
  engineVersion: string | null;
  /** GPU 가속 사용 여부 */
  gpuAccelerated: boolean;
}

export interface STTModel {
  id: string;
  name: string;
  /** 모델 크기 (bytes) */
  sizeBytes: number;
  /** 다운로드 완료 여부 */
  downloaded: boolean;
  /** 지원 언어 목록 (ISO 639-1) */
  languages: string[];
  /** 상대적 정확도 (1-5, 5가 가장 높음) */
  accuracy: number;
  /** 상대적 속도 (1-5, 5가 가장 빠름) */
  speed: number;
}

export interface SetSTTModelParams {
  modelId: string;
}

export interface DownloadModelParams {
  modelId: string;
}

export interface SetSTTLanguageParams {
  /** ISO 639-1 언어 코드 (예: 'ko', 'en', 'auto') */
  language: string;
}

export interface STTStatusChangedEvent {
  status: STTStatus;
}

export interface DownloadProgressEvent {
  modelId: string;
  /** 0 ~ 100 */
  percent: number;
  /** 다운로드된 바이트 */
  downloadedBytes: number;
  /** 전체 바이트 */
  totalBytes: number;
  /** 초당 바이트 */
  bytesPerSecond: number;
}

// ============================================================
// TTS (로컬 TTS)
// ============================================================

export enum TTSEngineState {
  NOT_INSTALLED = 'not-installed',
  LOADING = 'loading',
  READY = 'ready',
  SPEAKING = 'speaking',
  ERROR = 'error',
}

export interface TTSStatus {
  engineState: TTSEngineState;
  activeVoice: string | null;
  engineVersion: string | null;
}

export interface TTSVoice {
  id: string;
  name: string;
  language: string;
  /** 음성 성별 */
  gender: 'male' | 'female' | 'neutral';
  /** 다운로드 완료 여부 */
  downloaded: boolean;
  sizeBytes: number;
}

export interface TTSSpeakParams {
  text: string;
  /** 음성 ID (생략 시 활성 음성) */
  voiceId?: string;
  /** 재생 속도 (0.5 ~ 2.0, 기본 1.0) */
  speed?: number;
}

export interface TTSSpeakResult {
  /** 생성된 오디오 지속 시간 (ms) */
  durationMs: number;
}

export interface SetTTSVoiceParams {
  voiceId: string;
}

export interface DownloadVoiceParams {
  voiceId: string;
}

export interface TTSStatusChangedEvent {
  status: TTSStatus;
}

export interface SpeakingStateChangedEvent {
  isSpeaking: boolean;
  /** 현재/마지막 재생 텍스트 */
  text: string;
}

// ============================================================
// LLM (Ollama)
// ============================================================

export enum LLMConnectionState {
  DISCONNECTED = 'disconnected',
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  ERROR = 'error',
}

export interface LLMStatus {
  connectionState: LLMConnectionState;
  serverUrl: string;
  activeModel: string | null;
  /** Ollama 서버 버전 */
  serverVersion: string | null;
}

export interface LLMModel {
  id: string;
  name: string;
  /** 모델 크기 (bytes) */
  sizeBytes: number;
  /** 파라미터 수 문자열 (예: '7B', '13B') */
  parameterSize: string;
  /** 양자화 레벨 (예: 'Q4_K_M') */
  quantization: string;
  /** 수정 시각 (ISO 8601) */
  modifiedAt: string;
}

export type LLMAction =
  | 'refine'       // 텍스트 다듬기
  | 'translate'    // 번역
  | 'summarize'    // 요약
  | 'expand'       // 확장
  | 'grammar'      // 문법 교정
  | 'custom';      // 커스텀 프롬프트

export interface LLMProcessParams {
  text: string;
  action: LLMAction;
  /** translate 시 대상 언어 */
  targetLanguage?: string;
  /** custom 시 프롬프트 */
  customPrompt?: string;
  /** 사용할 모델 ID (생략 시 활성 모델) */
  modelId?: string;
}

export interface LLMProcessResult {
  originalText: string;
  processedText: string;
  action: LLMAction;
  /** 처리 시간 (ms) */
  processingTimeMs: number;
  /** 사용된 토큰 수 */
  tokenCount: number;
}

export interface SetLLMModelParams {
  modelId: string;
}

export interface SetServerUrlParams {
  url: string;
}

export interface PullModelParams {
  modelName: string;
}

export interface LLMStatusChangedEvent {
  status: LLMStatus;
}

export interface LLMProcessProgressEvent {
  /** 누적 생성 텍스트 */
  text: string;
  /** 마지막 토큰 */
  token: string;
  /** 완료 여부 */
  done: boolean;
}

export interface LLMPullProgressEvent {
  modelName: string;
  status: string;
  /** 0 ~ 100 */
  percent: number;
  /** 다운로드된 바이트 */
  downloadedBytes: number;
  totalBytes: number;
}

// ============================================================
// Hotkey (핫키)
// ============================================================

export interface HotkeyBinding {
  /** uiohook 키코드 */
  keyCode: number;
  /** Ctrl 수식자 */
  ctrl: boolean;
  /** Alt 수식자 */
  alt: boolean;
  /** Shift 수식자 */
  shift: boolean;
  /** Meta(Win) 수식자 */
  meta: boolean;
  /** 표시용 문자열 (예: 'Right Alt') */
  displayLabel: string;
}

export interface SetHotkeyParams {
  binding: HotkeyBinding;
}

export interface SetEnabledParams {
  enabled: boolean;
}

export type HotkeyAction = 'dictation' | 'hands-free' | 'command';

export interface HotkeyTriggeredEvent {
  action: HotkeyAction;
  /** 'pressed' | 'released' — hold-to-talk용 */
  type: 'pressed' | 'released';
  /** 더블프레스 여부 (300ms 이내) */
  isDoublePress: boolean;
}

export interface HotkeyRecordingResultEvent {
  binding: HotkeyBinding | null;
  /** 시스템 예약 키 충돌 시 사유 */
  conflictReason: string | null;
}

// ============================================================
// Config (설정)
// ============================================================

export interface AppConfig {
  // UI
  theme: ThemeMode;
  language: string;
  closeToTray: boolean;
  autoLaunch: boolean;
  soundEnabled: boolean;

  // Audio
  selectedDeviceId: string | null;

  // STT
  sttModelId: string;
  sttLanguage: string;

  // TTS
  ttsVoiceId: string | null;
  ttsSpeed: number;

  // LLM
  ollamaServerUrl: string;
  llmModelId: string | null;
  defaultLLMAction: LLMAction;

  // Hotkey
  dictationShortcut: HotkeyBinding;
  handsFreeShortcut: HotkeyBinding;
  commandShortcut: HotkeyBinding;
  hotkeyEnabled: boolean;

  // Text Insert
  insertMethod: 'clipboard' | 'keyboard';
  autoInsert: boolean;

  // History
  maxHistoryEntries: number;
}

export interface ConfigGetParams {
  key: keyof AppConfig;
}

export interface ConfigSetParams {
  key: keyof AppConfig;
  value: AppConfig[keyof AppConfig];
}

export interface ConfigResetParams {
  /** 초기화할 키 (생략 시 전체 초기화) */
  key?: keyof AppConfig;
}

export interface SetThemeParams {
  theme: ThemeMode;
}

export interface SetLanguageParams {
  language: string;
}

export interface SetAutoLaunchParams {
  enabled: boolean;
}

export interface SetCloseToTrayParams {
  enabled: boolean;
}

export interface ConfigChangedEvent {
  key: keyof AppConfig;
  value: AppConfig[keyof AppConfig];
  previousValue: AppConfig[keyof AppConfig];
}

// ============================================================
// History (히스토리)
// ============================================================

export interface HistoryEntry {
  id: string;
  /** 원본 전사 텍스트 */
  originalText: string;
  /** LLM 다듬기/번역 결과 (미처리 시 null) */
  polishedText: string | null;
  /** 포커스 앱 실행 경로 */
  focusedApp: string | null;
  /** 포커스 앱 이름 */
  focusedAppName: string | null;
  /** 포커스 윈도우 타이틀 */
  focusedAppWindowTitle: string | null;
  /** 녹음 모드 */
  mode: 'dictation' | 'translate' | 'command';
  /** 세션 상태 */
  status: 'completed' | 'cancelled' | 'error';
  /** 에러 코드 (실패 시) */
  errorCode: string | null;
  /** 녹음 파일 경로 */
  audioLocalPath: string | null;
  /** 녹음 시간 (초) */
  duration: number;
  /** Whisper 감지 언어 */
  detectedLanguage: string | null;
  /** 마이크 디바이스 ID */
  micDevice: string | null;
  /** 단어 수 */
  wordCount: number;
  /** 사용된 Whisper 모델명 */
  sttModel: string | null;
  /** 사용된 Ollama 모델명 */
  llmModel: string | null;
  /** STT 처리 시간 (ms) */
  sttLatencyMs: number | null;
  /** LLM 처리 시간 (ms) */
  llmLatencyMs: number | null;
  createdAt: number;
  updatedAt: number;
  appVersion: string;
}

export interface HistoryQueryParams {
  /** 페이지 번호 (0부터) */
  page: number;
  /** 페이지 크기 */
  pageSize: number;
  /** 정렬 기준 */
  sortBy?: 'createdAt' | 'durationMs' | 'wordCount';
  /** 정렬 방향 */
  sortOrder?: 'asc' | 'desc';
}

export interface HistoryPage {
  entries: HistoryEntry[];
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

export interface HistoryGetByIdParams {
  id: string;
}

export interface HistoryDeleteParams {
  id: string;
}

export interface HistorySearchParams {
  query: string;
  page: number;
  pageSize: number;
}

export interface HistoryExportParams {
  format: 'json' | 'csv';
  /** 내보내기 시작 날짜 (ISO 8601, 생략 시 전체) */
  from?: string;
  /** 내보내기 종료 날짜 */
  to?: string;
}

// ============================================================
// Dictionary (사전)
// ============================================================

export interface DictionaryEntry {
  id: string;
  /** 단어/구문 */
  word: string;
  /** 발음 힌트 (선택) */
  pronunciation: string | null;
  /** 카테고리 */
  category: 'user' | 'auto' | 'technical';
  /** 사용 횟수 */
  usageCount: number;
  /** 마지막 사용 시각 */
  lastUsedAt: number | null;
  createdAt: number;
  updatedAt: number;
}

export interface DictionaryQueryParams {
  page: number;
  pageSize: number;
  sortBy?: 'word' | 'category' | 'usageCount' | 'createdAt';
  sortOrder?: 'asc' | 'desc';
}

export interface DictionaryPage {
  entries: DictionaryEntry[];
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

export interface DictionaryAddParams {
  word: string;
  pronunciation?: string;
  category?: 'user' | 'auto' | 'technical';
}

export interface DictionaryUpdateParams {
  id: string;
  word?: string;
  pronunciation?: string;
  category?: 'user' | 'auto' | 'technical';
}

export interface DictionaryDeleteParams {
  id: string;
}

export interface DictionaryImportParams {
  /** 파일 경로 */
  filePath: string;
  format: 'json' | 'csv';
}

export interface DictionaryImportResult {
  imported: number;
  skipped: number;
  errors: number;
}

export interface DictionaryExportParams {
  format: 'json' | 'csv';
}

export interface DictionarySearchParams {
  query: string;
  page: number;
  pageSize: number;
}

// ============================================================
// Window (윈도우 제어)
// ============================================================

export type RecordingTipState =
  | 'opening'
  | 'recording'
  | 'thinking'
  | 'result'
  | 'error';

export interface ShowRecordingTipParams {
  state: RecordingTipState;
  /** 결과 텍스트 (state='result' 시) */
  text?: string;
  /** 에러 메시지 (state='error' 시) */
  errorMessage?: string;
}

export interface ShowResultPopupParams {
  text: string;
  /** 자동 숨김 시간 (ms), 0이면 수동 닫기만 */
  autoHideMs?: number;
}

export interface TipMeasuredParams {
  /** 측정된 너비 (px) */
  width: number;
  /** 측정된 높이 (px) */
  height: number;
}

export interface TipStateChangedEvent {
  state: RecordingTipState;
  text?: string;
  errorMessage?: string;
}

export interface TipPrepareEvent {
  state: RecordingTipState;
  text?: string;
}

export interface TipShowEvent {
  state: RecordingTipState;
}

// ============================================================
// System (시스템)
// ============================================================

export interface ActiveAppInfo {
  /** 앱 실행 파일명 */
  name: string;
  /** 윈도우 제목 */
  title: string;
  /** 프로세스 ID */
  pid: number;
}

export interface ShowNotificationParams {
  title: string;
  body: string;
  /** 'info' | 'warning' | 'error' */
  type?: 'info' | 'warning' | 'error';
}

export interface OpenExternalParams {
  url: string;
}

export interface InsertTextParams {
  text: string;
  /** 삽입 방법 (생략 시 설정 기본값) */
  method?: 'clipboard' | 'keyboard';
}

export interface InsertTextResult {
  success: boolean;
  /** 삽입된 문자 수 */
  insertedLength: number;
}

export type SoundEffect =
  | 'recording-start'
  | 'recording-stop'
  | 'transcription-complete'
  | 'error'
  | 'notification';

export interface PlaySoundParams {
  sound: SoundEffect;
}

export interface SetSoundEnabledParams {
  enabled: boolean;
}

// ============================================================
// Stats (통계)
// ============================================================

export interface StatsSummary {
  /** 총 녹음 시간 (ms) */
  totalRecordingTimeMs: number;
  /** 총 단어 수 */
  totalWordCount: number;
  /** 총 세션 수 */
  totalSessionCount: number;
  /** 오늘 녹음 시간 (ms) */
  todayRecordingTimeMs: number;
  /** 오늘 단어 수 */
  todayWordCount: number;
  /** 오늘 세션 수 */
  todaySessionCount: number;
  /** 연속 사용 일수 */
  streakDays: number;
}

export interface StatsQueryParams {
  /** 조회 시작일 (ISO 8601) */
  from: string;
  /** 조회 종료일 */
  to: string;
}

export interface DailyStats {
  date: string;
  recordingTimeMs: number;
  wordCount: number;
  sessionCount: number;
}

export interface WeeklyStats {
  /** 주 시작일 (월요일) */
  weekStart: string;
  recordingTimeMs: number;
  wordCount: number;
  sessionCount: number;
}
```

---

## 4. `shared/errors.ts` 에러 코드 전체 설계

Speakly의 900+ 에러 코드 체계를 참고하되, 클라우드/인증 관련을 제거하고 로컬 서비스에 맞게 재설계한다.

### 에러 코드 범위 규칙

| 범위 | 카테고리 |
|------|---------|
| 0 | 성공 |
| 100-199 | STT (Whisper) |
| 200-299 | TTS |
| 300-399 | LLM (Ollama) |
| 400-499 | Audio (마이크/캡처) |
| 500-599 | Hotkey |
| 600-699 | TextInsert (텍스트 삽입) |
| 700-799 | History / Dictionary (DB) |
| 800-899 | Config (설정) |
| 900-999 | System / Window |

```typescript
// src/shared/errors.ts

export enum ErrorCode {
  // === Success ===
  Success = 0,

  // === STT (100-199) ===
  STTEngineNotInstalled = 100,
  STTModelNotFound = 101,
  STTModelNotLoaded = 102,
  STTModelLoadFailed = 103,
  STTModelDownloadFailed = 104,
  STTModelDownloadCancelled = 105,
  STTTranscriptionFailed = 110,
  STTTranscriptionTimeout = 111,
  STTTranscriptionCancelled = 112,
  STTNoAudioData = 113,
  STTAudioTooShort = 114,
  STTLanguageNotSupported = 120,
  STTSidecarSpawnFailed = 130,
  STTSidecarCrashed = 131,
  STTSidecarCommunicationFailed = 132,
  STTGPUNotAvailable = 140,

  // === TTS (200-299) ===
  TTSEngineNotInstalled = 200,
  TTSVoiceNotFound = 201,
  TTSVoiceNotLoaded = 202,
  TTSVoiceLoadFailed = 203,
  TTSVoiceDownloadFailed = 204,
  TTSSynthesisFailed = 210,
  TTSPlaybackFailed = 211,
  TTSPlaybackInterrupted = 212,
  TTSTextTooLong = 220,
  TTSTextEmpty = 221,

  // === LLM / Ollama (300-399) ===
  LLMServerUnreachable = 300,
  LLMServerConnectionFailed = 301,
  LLMServerTimeout = 302,
  LLMModelNotFound = 310,
  LLMModelNotLoaded = 311,
  LLMModelLoadFailed = 312,
  LLMModelPullFailed = 313,
  LLMModelPullCancelled = 314,
  LLMProcessingFailed = 320,
  LLMProcessingTimeout = 321,
  LLMProcessingCancelled = 322,
  LLMResponseParseFailed = 323,
  LLMInvalidAction = 330,
  LLMPromptTooLong = 331,

  // === Audio (400-499) ===
  AudioDeviceNotFound = 400,
  AudioDeviceAccessDenied = 401,
  AudioDeviceBusy = 402,
  AudioCaptureStartFailed = 410,
  AudioCaptureStopFailed = 411,
  AudioCaptureFailed = 412,
  AudioNoPermission = 420,
  AudioStreamError = 430,
  AudioBufferOverflow = 431,

  // === Hotkey (500-599) ===
  HotkeyRegistrationFailed = 500,
  HotkeyConflict = 501,
  HotkeySystemReserved = 502,
  HotkeyHookInitFailed = 510,
  HotkeyHookCrashed = 511,

  // === TextInsert (600-699) ===
  TextInsertFailed = 600,
  TextInsertClipboardSaveFailed = 601,
  TextInsertClipboardRestoreFailed = 602,
  TextInsertKeySimulationFailed = 603,
  TextInsertNoActiveWindow = 610,
  TextInsertTargetAppNotResponding = 611,

  // === History / Dictionary / DB (700-799) ===
  DBOpenFailed = 700,
  DBMigrationFailed = 701,
  DBQueryFailed = 702,
  DBWriteFailed = 703,
  HistoryNotFound = 710,
  HistoryExportFailed = 711,
  DictionaryNotFound = 720,
  DictionaryDuplicate = 721,
  DictionaryImportFailed = 722,
  DictionaryExportFailed = 723,
  DictionaryImportInvalidFormat = 724,

  // === Config (800-899) ===
  ConfigReadFailed = 800,
  ConfigWriteFailed = 801,
  ConfigInvalidValue = 802,
  ConfigKeyNotFound = 803,
  ConfigResetFailed = 804,
  ConfigMigrationFailed = 810,

  // === System / Window (900-999) ===
  WindowCreationFailed = 900,
  WindowNotFound = 901,
  TrayCreationFailed = 910,
  NotificationFailed = 920,
  PermissionDenied = 930,
  ExternalOpenFailed = 940,
  SoundPlayFailed = 950,
  AppAlreadyRunning = 960,
  UnknownError = 999,
}

/**
 * D3RO-VOICE 표준 에러 객체 (Speakly NXError 패턴)
 * 모든 IPC 에러 응답은 이 형태로 전달된다.
 */
export class D3ROError extends Error {
  readonly code: ErrorCode;
  readonly details?: Record<string, unknown>;

  constructor(code: ErrorCode, message: string, details?: Record<string, unknown>) {
    super(message);
    this.name = 'D3ROError';
    this.code = code;
    this.details = details;
  }

  toJSON(): D3ROErrorJSON {
    return {
      code: this.code,
      message: this.message,
      details: this.details,
    };
  }

  static fromJSON(json: D3ROErrorJSON): D3ROError {
    return new D3ROError(json.code, json.message, json.details);
  }
}

export interface D3ROErrorJSON {
  code: ErrorCode;
  message: string;
  details?: Record<string, unknown>;
}

/**
 * IPC 핸들러에서 사용하는 표준 응답 래퍼.
 * 성공 시 { success: true, data }, 실패 시 { success: false, error }
 */
export type IPCResult<T> =
  | { success: true; data: T }
  | { success: false; error: D3ROErrorJSON };

/**
 * IPCResult 헬퍼 함수
 */
export function ipcSuccess<T>(data: T): IPCResult<T> {
  return { success: true, data };
}

export function ipcError<T>(code: ErrorCode, message: string, details?: Record<string, unknown>): IPCResult<T> {
  return { success: false, error: { code, message, details } };
}
```

---

## 5. `preload/index.ts` 전체 API 설계

contextBridge로 노출할 `window.electronAPI` 구조. 렌더러는 이 객체를 통해서만 메인 프로세스와 통신한다.

```typescript
// src/preload/index.ts
import { contextBridge, ipcRenderer } from 'electron';
import { IPC_CHANNELS } from '../shared/ipc-channels';
import type {
  // Voice
  StartRecordingParams, StartRecordingResult,
  StopRecordingParams, StopRecordingResult,
  CancelRecordingParams, VoiceState, SetVoiceModeParams, VoiceMode,
  VoiceStateChangedEvent, TranscriptionDeltaEvent, TranscriptionCompleteEvent,
  VoiceErrorEvent, AudioLevelEvent,
  // Audio
  AudioDevice, SetDeviceParams, TestDeviceParams, TestDeviceResult,
  AudioDeviceChangedEvent,
  // STT
  STTStatus, STTModel, SetSTTModelParams, DownloadModelParams,
  SetSTTLanguageParams, STTStatusChangedEvent, DownloadProgressEvent,
  // TTS
  TTSStatus, TTSVoice, TTSSpeakParams, TTSSpeakResult,
  SetTTSVoiceParams, DownloadVoiceParams,
  TTSStatusChangedEvent, SpeakingStateChangedEvent,
  // LLM
  LLMStatus, LLMModel, SetLLMModelParams, LLMProcessParams, LLMProcessResult,
  SetServerUrlParams, PullModelParams,
  LLMStatusChangedEvent, LLMProcessProgressEvent, LLMPullProgressEvent,
  // Hotkey
  HotkeyBinding, SetHotkeyParams, SetEnabledParams,
  HotkeyTriggeredEvent, HotkeyRecordingResultEvent,
  // Config
  AppConfig, ConfigGetParams, ConfigSetParams, ConfigResetParams,
  SetThemeParams, SetLanguageParams, SetAutoLaunchParams, SetCloseToTrayParams,
  ThemeMode, ConfigChangedEvent,
  // History
  HistoryEntry, HistoryQueryParams, HistoryPage, HistoryGetByIdParams,
  HistoryDeleteParams, HistorySearchParams, HistoryExportParams,
  // Dictionary
  DictionaryEntry, DictionaryQueryParams, DictionaryPage,
  DictionaryAddParams, DictionaryUpdateParams, DictionaryDeleteParams,
  DictionaryImportParams, DictionaryImportResult, DictionaryExportParams,
  DictionarySearchParams,
  // Window
  ShowRecordingTipParams, ShowResultPopupParams, TipMeasuredParams,
  TipStateChangedEvent, TipPrepareEvent, TipShowEvent,
  // System
  ActiveAppInfo, ShowNotificationParams, OpenExternalParams,
  InsertTextParams, InsertTextResult, PlaySoundParams, SetSoundEnabledParams,
  PermissionStatus,
  // Stats
  StatsSummary, StatsQueryParams, DailyStats, WeeklyStats,
} from '../shared/types';
import type { IPCResult } from '../shared/errors';

// 타입 안전한 invoke 헬퍼
function invoke<TResult>(channel: string, ...args: unknown[]): Promise<IPCResult<TResult>> {
  return ipcRenderer.invoke(channel, ...args);
}

// 타입 안전한 send 헬퍼 (fire-and-forget)
function send(channel: string, ...args: unknown[]): void {
  ipcRenderer.send(channel, ...args);
}

// 타입 안전한 이벤트 리스너 헬퍼
type Unsubscribe = () => void;
function on<T>(channel: string, callback: (data: T) => void): Unsubscribe {
  const listener = (_event: Electron.IpcRendererEvent, data: T) => callback(data);
  ipcRenderer.on(channel, listener);
  return () => ipcRenderer.removeListener(channel, listener);
}

const electronAPI = {
  // ── Voice ──────────────────────────────────────────────
  voice: {
    startRecording: (params: StartRecordingParams) =>
      invoke<StartRecordingResult>(IPC_CHANNELS.VOICE.START_RECORDING, params),
    stopRecording: (params: StopRecordingParams) =>
      invoke<StopRecordingResult>(IPC_CHANNELS.VOICE.STOP_RECORDING, params),
    cancelRecording: (params: CancelRecordingParams) =>
      invoke<void>(IPC_CHANNELS.VOICE.CANCEL_RECORDING, params),
    getState: () =>
      invoke<VoiceState>(IPC_CHANNELS.VOICE.GET_STATE),
    setMode: (params: SetVoiceModeParams) =>
      invoke<void>(IPC_CHANNELS.VOICE.SET_MODE, params),
    getMode: () =>
      invoke<VoiceMode>(IPC_CHANNELS.VOICE.GET_MODE),

    onStateChanged: (cb: (e: VoiceStateChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.VOICE.STATE_CHANGED, cb),
    onTranscriptionDelta: (cb: (e: TranscriptionDeltaEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.VOICE.TRANSCRIPTION_DELTA, cb),
    onTranscriptionComplete: (cb: (e: TranscriptionCompleteEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.VOICE.TRANSCRIPTION_COMPLETE, cb),
    onError: (cb: (e: VoiceErrorEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.VOICE.ERROR, cb),
    onAudioLevel: (cb: (e: AudioLevelEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.VOICE.AUDIO_LEVEL, cb),
  },

  // ── Audio ──────────────────────────────────────────────
  audio: {
    getDevices: () =>
      invoke<AudioDevice[]>(IPC_CHANNELS.AUDIO.GET_DEVICES),
    getSelectedDevice: () =>
      invoke<string | null>(IPC_CHANNELS.AUDIO.GET_SELECTED_DEVICE),
    setSelectedDevice: (params: SetDeviceParams) =>
      invoke<void>(IPC_CHANNELS.AUDIO.SET_SELECTED_DEVICE, params),
    testDevice: (params: TestDeviceParams) =>
      invoke<TestDeviceResult>(IPC_CHANNELS.AUDIO.TEST_DEVICE, params),

    onDeviceChanged: (cb: (e: AudioDeviceChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.AUDIO.DEVICE_CHANGED, cb),
  },

  // ── STT ────────────────────────────────────────────────
  stt: {
    getStatus: () =>
      invoke<STTStatus>(IPC_CHANNELS.STT.GET_STATUS),
    getModels: () =>
      invoke<STTModel[]>(IPC_CHANNELS.STT.GET_MODELS),
    getActiveModel: () =>
      invoke<string | null>(IPC_CHANNELS.STT.GET_ACTIVE_MODEL),
    setModel: (params: SetSTTModelParams) =>
      invoke<void>(IPC_CHANNELS.STT.SET_MODEL, params),
    downloadModel: (params: DownloadModelParams) =>
      invoke<void>(IPC_CHANNELS.STT.DOWNLOAD_MODEL, params),
    cancelDownload: () =>
      invoke<void>(IPC_CHANNELS.STT.CANCEL_DOWNLOAD),
    getLanguage: () =>
      invoke<string>(IPC_CHANNELS.STT.GET_LANGUAGE),
    setLanguage: (params: SetSTTLanguageParams) =>
      invoke<void>(IPC_CHANNELS.STT.SET_LANGUAGE, params),

    onStatusChanged: (cb: (e: STTStatusChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.STT.STATUS_CHANGED, cb),
    onDownloadProgress: (cb: (e: DownloadProgressEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.STT.DOWNLOAD_PROGRESS, cb),
  },

  // ── TTS ────────────────────────────────────────────────
  tts: {
    speak: (params: TTSSpeakParams) =>
      invoke<TTSSpeakResult>(IPC_CHANNELS.TTS.SPEAK, params),
    stop: () =>
      invoke<void>(IPC_CHANNELS.TTS.STOP),
    getVoices: () =>
      invoke<TTSVoice[]>(IPC_CHANNELS.TTS.GET_VOICES),
    getActiveVoice: () =>
      invoke<string | null>(IPC_CHANNELS.TTS.GET_ACTIVE_VOICE),
    setVoice: (params: SetTTSVoiceParams) =>
      invoke<void>(IPC_CHANNELS.TTS.SET_VOICE, params),
    getStatus: () =>
      invoke<TTSStatus>(IPC_CHANNELS.TTS.GET_STATUS),
    downloadVoice: (params: DownloadVoiceParams) =>
      invoke<void>(IPC_CHANNELS.TTS.DOWNLOAD_VOICE, params),

    onStatusChanged: (cb: (e: TTSStatusChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.TTS.STATUS_CHANGED, cb),
    onSpeakingStateChanged: (cb: (e: SpeakingStateChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.TTS.SPEAKING_STATE_CHANGED, cb),
  },

  // ── LLM ────────────────────────────────────────────────
  llm: {
    getStatus: () =>
      invoke<LLMStatus>(IPC_CHANNELS.LLM.GET_STATUS),
    getModels: () =>
      invoke<LLMModel[]>(IPC_CHANNELS.LLM.GET_MODELS),
    getActiveModel: () =>
      invoke<string | null>(IPC_CHANNELS.LLM.GET_ACTIVE_MODEL),
    setModel: (params: SetLLMModelParams) =>
      invoke<void>(IPC_CHANNELS.LLM.SET_MODEL, params),
    process: (params: LLMProcessParams) =>
      invoke<LLMProcessResult>(IPC_CHANNELS.LLM.PROCESS, params),
    cancelProcess: () =>
      invoke<void>(IPC_CHANNELS.LLM.CANCEL_PROCESS),
    getServerUrl: () =>
      invoke<string>(IPC_CHANNELS.LLM.GET_SERVER_URL),
    setServerUrl: (params: SetServerUrlParams) =>
      invoke<void>(IPC_CHANNELS.LLM.SET_SERVER_URL, params),
    pullModel: (params: PullModelParams) =>
      invoke<void>(IPC_CHANNELS.LLM.PULL_MODEL, params),

    onStatusChanged: (cb: (e: LLMStatusChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.LLM.STATUS_CHANGED, cb),
    onProcessProgress: (cb: (e: LLMProcessProgressEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.LLM.PROCESS_PROGRESS, cb),
    onPullProgress: (cb: (e: LLMPullProgressEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.LLM.PULL_PROGRESS, cb),
  },

  // ── Hotkey ─────────────────────────────────────────────
  hotkey: {
    getDictationShortcut: () =>
      invoke<HotkeyBinding>(IPC_CHANNELS.HOTKEY.GET_DICTATION_SHORTCUT),
    setDictationShortcut: (params: SetHotkeyParams) =>
      invoke<void>(IPC_CHANNELS.HOTKEY.SET_DICTATION_SHORTCUT, params),
    getHandsFreeShortcut: () =>
      invoke<HotkeyBinding>(IPC_CHANNELS.HOTKEY.GET_HANDS_FREE_SHORTCUT),
    setHandsFreeShortcut: (params: SetHotkeyParams) =>
      invoke<void>(IPC_CHANNELS.HOTKEY.SET_HANDS_FREE_SHORTCUT, params),
    getCommandShortcut: () =>
      invoke<HotkeyBinding>(IPC_CHANNELS.HOTKEY.GET_COMMAND_SHORTCUT),
    setCommandShortcut: (params: SetHotkeyParams) =>
      invoke<void>(IPC_CHANNELS.HOTKEY.SET_COMMAND_SHORTCUT, params),
    isEnabled: () =>
      invoke<boolean>(IPC_CHANNELS.HOTKEY.IS_ENABLED),
    setEnabled: (params: SetEnabledParams) =>
      invoke<void>(IPC_CHANNELS.HOTKEY.SET_ENABLED, params),
    startRecording: () =>
      invoke<void>(IPC_CHANNELS.HOTKEY.START_RECORDING),
    stopRecording: () =>
      invoke<HotkeyBinding | null>(IPC_CHANNELS.HOTKEY.STOP_RECORDING),

    onTriggered: (cb: (e: HotkeyTriggeredEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.HOTKEY.TRIGGERED, cb),
    onRecordingResult: (cb: (e: HotkeyRecordingResultEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.HOTKEY.RECORDING_RESULT, cb),
  },

  // ── Config ─────────────────────────────────────────────
  config: {
    get: (params: ConfigGetParams) =>
      invoke<unknown>(IPC_CHANNELS.CONFIG.GET, params),
    set: (params: ConfigSetParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.SET, params),
    getAll: () =>
      invoke<AppConfig>(IPC_CHANNELS.CONFIG.GET_ALL),
    reset: (params: ConfigResetParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.RESET, params),
    getTheme: () =>
      invoke<ThemeMode>(IPC_CHANNELS.CONFIG.GET_THEME),
    setTheme: (params: SetThemeParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.SET_THEME, params),
    getLanguage: () =>
      invoke<string>(IPC_CHANNELS.CONFIG.GET_LANGUAGE),
    setLanguage: (params: SetLanguageParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.SET_LANGUAGE, params),
    getAutoLaunch: () =>
      invoke<boolean>(IPC_CHANNELS.CONFIG.GET_AUTO_LAUNCH),
    setAutoLaunch: (params: SetAutoLaunchParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.SET_AUTO_LAUNCH, params),
    getCloseToTray: () =>
      invoke<boolean>(IPC_CHANNELS.CONFIG.GET_CLOSE_TO_TRAY),
    setCloseToTray: (params: SetCloseToTrayParams) =>
      invoke<void>(IPC_CHANNELS.CONFIG.SET_CLOSE_TO_TRAY, params),

    onChanged: (cb: (e: ConfigChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.CONFIG.CHANGED, cb),
  },

  // ── History ────────────────────────────────────────────
  history: {
    getAll: (params: HistoryQueryParams) =>
      invoke<HistoryPage>(IPC_CHANNELS.HISTORY.GET_ALL, params),
    getById: (params: HistoryGetByIdParams) =>
      invoke<HistoryEntry | null>(IPC_CHANNELS.HISTORY.GET_BY_ID, params),
    delete: (params: HistoryDeleteParams) =>
      invoke<void>(IPC_CHANNELS.HISTORY.DELETE, params),
    deleteAll: () =>
      invoke<void>(IPC_CHANNELS.HISTORY.DELETE_ALL),
    search: (params: HistorySearchParams) =>
      invoke<HistoryPage>(IPC_CHANNELS.HISTORY.SEARCH, params),
    export: (params: HistoryExportParams) =>
      invoke<string>(IPC_CHANNELS.HISTORY.EXPORT, params),

    onAdded: (cb: (e: HistoryEntry) => void): Unsubscribe =>
      on(IPC_CHANNELS.HISTORY.ADDED, cb),
  },

  // ── Dictionary ─────────────────────────────────────────
  dictionary: {
    getAll: (params: DictionaryQueryParams) =>
      invoke<DictionaryPage>(IPC_CHANNELS.DICTIONARY.GET_ALL, params),
    add: (params: DictionaryAddParams) =>
      invoke<DictionaryEntry>(IPC_CHANNELS.DICTIONARY.ADD, params),
    update: (params: DictionaryUpdateParams) =>
      invoke<DictionaryEntry>(IPC_CHANNELS.DICTIONARY.UPDATE, params),
    delete: (params: DictionaryDeleteParams) =>
      invoke<void>(IPC_CHANNELS.DICTIONARY.DELETE, params),
    import: (params: DictionaryImportParams) =>
      invoke<DictionaryImportResult>(IPC_CHANNELS.DICTIONARY.IMPORT, params),
    export: (params: DictionaryExportParams) =>
      invoke<string>(IPC_CHANNELS.DICTIONARY.EXPORT, params),
    search: (params: DictionarySearchParams) =>
      invoke<DictionaryPage>(IPC_CHANNELS.DICTIONARY.SEARCH, params),
  },

  // ── Window ─────────────────────────────────────────────
  window: {
    minimize: () =>
      send(IPC_CHANNELS.WINDOW.MINIMIZE),
    maximize: () =>
      send(IPC_CHANNELS.WINDOW.MAXIMIZE),
    close: () =>
      send(IPC_CHANNELS.WINDOW.CLOSE),
    isMaximized: () =>
      invoke<boolean>(IPC_CHANNELS.WINDOW.IS_MAXIMIZED),
    showRecordingTip: (params: ShowRecordingTipParams) =>
      send(IPC_CHANNELS.WINDOW.SHOW_RECORDING_TIP, params),
    hideRecordingTip: () =>
      send(IPC_CHANNELS.WINDOW.HIDE_RECORDING_TIP),
    showResultPopup: (params: ShowResultPopupParams) =>
      send(IPC_CHANNELS.WINDOW.SHOW_RESULT_POPUP, params),
    hideResultPopup: () =>
      send(IPC_CHANNELS.WINDOW.HIDE_RESULT_POPUP),
    tipMeasured: (params: TipMeasuredParams) =>
      send(IPC_CHANNELS.WINDOW.TIP_MEASURED, params),

    onTipStateChanged: (cb: (e: TipStateChangedEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.WINDOW.TIP_STATE_CHANGED, cb),
    onTipPrepare: (cb: (e: TipPrepareEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.WINDOW.TIP_PREPARE, cb),
    onTipShow: (cb: (e: TipShowEvent) => void): Unsubscribe =>
      on(IPC_CHANNELS.WINDOW.TIP_SHOW, cb),
  },

  // ── System ─────────────────────────────────────────────
  system: {
    getPlatform: () =>
      invoke<NodeJS.Platform>(IPC_CHANNELS.SYSTEM.GET_PLATFORM),
    getVersion: () =>
      invoke<string>(IPC_CHANNELS.SYSTEM.GET_VERSION),
    checkMicPermission: () =>
      invoke<PermissionStatus>(IPC_CHANNELS.SYSTEM.CHECK_MIC_PERMISSION),
    requestMicPermission: () =>
      invoke<PermissionStatus>(IPC_CHANNELS.SYSTEM.REQUEST_MIC_PERMISSION),
    showNotification: (params: ShowNotificationParams) =>
      invoke<void>(IPC_CHANNELS.SYSTEM.SHOW_NOTIFICATION, params),
    openExternal: (params: OpenExternalParams) =>
      invoke<void>(IPC_CHANNELS.SYSTEM.OPEN_EXTERNAL, params),
    getActiveApp: () =>
      invoke<ActiveAppInfo | null>(IPC_CHANNELS.SYSTEM.GET_ACTIVE_APP),
    insertText: (params: InsertTextParams) =>
      invoke<InsertTextResult>(IPC_CHANNELS.SYSTEM.INSERT_TEXT, params),
    playSound: (params: PlaySoundParams) =>
      invoke<void>(IPC_CHANNELS.SYSTEM.PLAY_SOUND, params),
    setSoundEnabled: (params: SetSoundEnabledParams) =>
      invoke<void>(IPC_CHANNELS.SYSTEM.SET_SOUND_ENABLED, params),
    isSoundEnabled: () =>
      invoke<boolean>(IPC_CHANNELS.SYSTEM.IS_SOUND_ENABLED),
  },

  // ── Stats ──────────────────────────────────────────────
  stats: {
    getSummary: () =>
      invoke<StatsSummary>(IPC_CHANNELS.STATS.GET_SUMMARY),
    getDaily: (params: StatsQueryParams) =>
      invoke<DailyStats[]>(IPC_CHANNELS.STATS.GET_DAILY, params),
    getWeekly: (params: StatsQueryParams) =>
      invoke<WeeklyStats[]>(IPC_CHANNELS.STATS.GET_WEEKLY, params),

    onUpdated: (cb: (e: StatsSummary) => void): Unsubscribe =>
      on(IPC_CHANNELS.STATS.UPDATED, cb),
  },
} as const;

// contextBridge로 렌더러에 노출
contextBridge.exposeInMainWorld('electronAPI', electronAPI);

// 렌더러에서 사용할 타입 선언
export type ElectronAPI = typeof electronAPI;
```

### 렌더러 타입 선언 (`src/renderer/electron.d.ts`)

```typescript
// src/renderer/electron.d.ts
import type { ElectronAPI } from '../preload/index';

declare global {
  interface Window {
    electronAPI: ElectronAPI;
  }
}
```

---

## 6. 채널 통계 요약

| 카테고리 | handle | on (R->M) | send (M->R) | 합계 |
|---------|--------|-----------|-------------|------|
| voice | 6 | 0 | 5 | 11 |
| audio | 4 | 0 | 1 | 5 |
| stt | 8 | 0 | 2 | 10 |
| tts | 7 | 0 | 2 | 9 |
| llm | 9 | 0 | 3 | 12 |
| hotkey | 10 | 0 | 2 | 12 |
| config | 12 | 0 | 1 | 13 |
| history | 6 | 0 | 1 | 7 |
| dictionary | 7 | 0 | 0 | 7 |
| window | 1 | 8 | 3 | 12 |
| system | 11 | 0 | 0 | 11 |
| stats | 3 | 0 | 1 | 4 |
| **합계** | **84** | **8** | **21** | **113** |

Speakly 대비:
- 제거: 클라우드 인증, WebSocket STT, 텔레메트리, 피드백, 업데이트, GenSpark 서비스 등 (~90개)
- 추가: 로컬 STT/TTS/LLM 관리, 모델 다운로드/pull, 통계 (~30개)

---

## 7. 설계 결정 사항

### 7.1 IPCResult 래퍼 패턴
모든 `handle` 채널은 `IPCResult<T>` 를 반환한다. 이는 Speakly의 NXError 패턴을 발전시킨 것으로, 렌더러에서 try/catch 없이 `success` 필드로 분기할 수 있다.

### 7.2 이벤트 구독 패턴
`on*` 메서드는 `Unsubscribe` 함수를 반환한다. React 컴포넌트에서 `useEffect` cleanup으로 사용:
```typescript
useEffect(() => {
  const unsub = window.electronAPI.voice.onStateChanged((e) => {
    setState(e.currentState);
  });
  return unsub;
}, []);
```

### 7.3 채널명 규칙
- 형식: `${namespace}:${action}` (camelCase)
- handle 채널: 동사로 시작 (`get`, `set`, `start`, `stop`, `cancel`, `delete`)
- send 이벤트: 과거분사 또는 명사 (`changed`, `progress`, `complete`, `added`)

### 7.4 Vanilla JS 팝업 통신
RecordingTip, ResultPopup 등 Vanilla JS 팝업은 별도 preload 스크립트가 필요하다. 동일한 `IPC_CHANNELS` 상수를 사용하되, `window:tip*` 채널만 노출한다.