Relevant source files

The following files were used as context for generating this wiki page: - [src/preload/floatingPreload.ts](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/preload/floatingPreload.ts) - [src/renderer/shared/types.ts](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/renderer/shared/types.ts) - [src/main/windowManager.ts](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/main/windowManager.ts) - [src/main/ipcHandlers.ts](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/main/ipcHandlers.ts) - [src/renderer/floating/App.tsx](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/renderer/floating/App.tsx) - [src/renderer/freeze/App.tsx](https://github.com/5u2ny/focus-pomodoro-app/blob/main/src/renderer/freeze/App.tsx)

# Preload Scripts Preload scripts in the Focus Pomodoro App serve as the secure bridge between the Electron main process and the renderer processes. By utilizing Electron's `contextBridge` and `ipcRenderer`, these scripts expose a limited, well-defined API (the `focusAPI`) to the frontend windows without compromising security via full `nodeIntegration`. The application utilizes two primary preload scripts—`floatingPreload.ts` and `freezePreload.ts`—to facilitate communication for the floating HUD and the full-screen break overlays respectively. These scripts ensure that the React-based frontend can trigger system actions like starting timers or resizing windows while receiving real-time updates from the background `TimerEngine`. ## Architecture and Security The preload scripts act as a gateway that translates frontend function calls into Inter-Process Communication (IPC) messages. This architecture adheres to the principle of least privilege by only exposing necessary functions defined in the `FocusAPI` interface. ```mermaid flowchart TD subgraph Renderer_Process ["Renderer Process (React)"] UI[UI Components] --> API_Call["window.focusAPI.startTimer()"] end subgraph Preload_Layer ["Preload Script"] CB["contextBridge.exposeInMainWorld"] IR["ipcRenderer.invoke / ipcRenderer.on"] end subgraph Main_Process ["Main Process (Node.js)"] IPCH["ipcHandlers.ts"] TE["TimerEngine"] WM["WindowManager"] end API_Call --> CB CB --> IR IR -- "IPC.TIMER_START" --> IPCH IPCH --> TE TE -- "IPC.TIMER_TICK" --> WM WM -- "webContents.send" --> IR IR --> UI ``` *The diagram illustrates the secure flow of data and commands between the UI and the system-level processes via the preload layer.* Sources: [src/preload/floatingPreload.ts:4-21](), [src/main/windowManager.ts:60-75](), [src/main/ipcHandlers.ts:16-30]() ## The FocusAPI Interface The `focusAPI` is the central object injected into the global `window` scope of the renderer processes. It is categorized into two types of operations: **Invocations** (Renderer to Main) and **Listeners** (Main to Renderer). ### Renderer-to-Main Invocations These methods use `ipcRenderer.invoke` to request actions from the main process. | Method | Parameters | Return Type | Description | | :--- | :--- | :--- | :--- | | `startTimer` | None | `Promise` | Starts the Pomodoro timer. | | `pauseTimer` | None | `Promise` | Pauses the active timer. | | `resetTimer` | None | `Promise` | Resets the timer to the current phase's start. | | `skipPhase` | None | `Promise` | Skips to the next phase (e.g., Focus to Break). | | `setTask` | `task: string` | `Promise` | Updates the current focus task description. | | `getSettings` | None | `Promise`| Retrieves current user settings from the store. | | `saveSettings`| `s: AppSettings`| `Promise` | Saves new configuration settings. | | `getState` | None | `Promise` | Gets the full current state of the application. | | `resizeWindow`| `height: number` | `Promise` | Programmatically resizes the floating HUD. | Sources: [src/renderer/shared/types.ts:45-55](), [src/preload/floatingPreload.ts:5-14]() ### Main-to-Renderer Event Listeners These methods allow the renderer to register callbacks that react to system-level events pushed by the main process. | Listener Method | Callback Data | Purpose | | :--- | :--- | :--- | | `onTimerTick` | `{ remainingSeconds, phase, isRunning }` | Updates the countdown UI every second. | | `onPhaseChanged`| `{ newPhase, cycleCount }` | Notifies UI of transition between focus/break. | | `onFreezeEnter` | `{ phase, durationSeconds }` | Triggers the full-screen overlay visibility. | | `onFreezeTick` | `{ remainingSeconds }` | Updates the overlay countdown. | | `onFreezeExit` | None | Hides the full-screen overlay. | | `onStateUpdated` | `AppState` | Syncs the entire UI state with the `stateStore`. | Sources: [src/renderer/shared/types.ts:57-63](), [src/preload/floatingPreload.ts:16-21]() ## Implementation Details ### Window Management and Preload Injection The `WindowManager` class in the main process is responsible for injecting the correct preload script into each window during creation. This is configured via the `webPreferences` object. ```typescript // src/main/windowManager.ts const win = new BrowserWindow({ // ... window configuration webPreferences: { preload: path.join(__dirname, '..', 'preload', 'floatingPreload.js'), contextIsolation: true, nodeIntegration: false, sandbox: false, }, }) ``` Sources: [src/main/windowManager.ts:68-73](), [src/main/windowManager.ts:114-119]() ### Event Handling Sequence When a phase changes (e.g., from Focus to Short Break), a sequence of IPC events is triggered and captured by the preload script to update the UI. ```mermaid sequenceDiagram participant TE as TimerEngine (Main) participant IPCH as IPCHandlers (Main) participant WM as WindowManager (Main) participant PS as Preload Script participant UI as React App TE->>IPCH: phaseComplete Event IPCH->>WM: showFreeze() WM->>PS: Send IPC.FREEZE_ENTER PS->>UI: Trigger onFreezeEnter callback UI->>UI: Set visible = true & Update phase colors loop Every Second WM->>PS: Send IPC.FREEZE_TICK PS->>UI: Trigger onFreezeTick(remaining) end ``` *This sequence shows how the preload script facilitates the transition from the main process's logic to the renderer's visual updates.* Sources: [src/main/ipcHandlers.ts:39-50](), [src/renderer/freeze/App.tsx:48-61](), [src/main/windowManager.ts:173-188]() ## Summary Preload scripts are essential for maintaining a secure and responsive UI in the Focus Pomodoro App. By isolating sensitive Electron APIs and exposing only a structured `focusAPI`, they allow the React frontend to interact with the timer logic and window controls while staying in sync with the application's background state. This ensures that features like the eye-strain shield and Pomodoro breaks function seamlessly across multiple displays.