Coordinate multi-monitor break starts

Author: tom-james-watson

CLAUDE.md

@@ -4,34 +4,34 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-BreakTimer is a cross-platform desktop application built with Electron that helps users manage periodic breaks. The app runs as a system tray application and can display break reminders as notifications or fullscreen overlays.
+Cross-platform Electron desktop app for managing periodic breaks. Runs as system tray application with notifications and fullscreen overlays.
 
 ## Architecture
 
 ### Main Process (`app/main/`)
 
-- **Entry Point**: `index.ts` - Main application entry point
-- **Core Logic**: `lib/` directory contains the main business logic:
+- **Entry Point**: `index.ts`
+- **Core Logic**: `lib/` directory:
   - `breaks.ts` - Break scheduling and management
   - `ipc.ts` - Inter-process communication handlers
-  - `store.ts` - Settings persistence using electron-store
+  - `store.ts` - Settings persistence
   - `tray.ts` - System tray integration
   - `windows.ts` - Window management
-  - `notifications.ts` - Native notification system
-  - `auto-launch.ts` - Auto-startup functionality
+  - `notifications.ts` - Native notifications
+  - `auto-launch.ts` - Auto-startup
 
 ### Renderer Process (`app/renderer/`)
 
-- **Entry Point**: `index.tsx` - React application entry point
-- **Components**: React components for UI (Break, Settings, etc.)
-- **Styling**: CSS with Tailwind CSS for component styling
-- **Sounds**: Audio files for break notifications
-- **Preload**: `preload.js` - Secure context bridge for IPC
-- **Fonts**: Inter font bundled locally in `public/fonts/`
+- **Entry Point**: `index.tsx`
+- **Components**: React components (Break, Settings, etc.)
+- **Styling**: CSS with Tailwind CSS
+- **Sounds**: Audio files for notifications
+- **Preload**: `preload.js` - Secure IPC bridge
+- **Fonts**: Inter font bundled in `public/fonts/`
 
 ### Types (`app/types/`)
 
-- Shared TypeScript type definitions for IPC, settings, and breaks
+- Shared TypeScript definitions for IPC, settings, breaks
 
 ## Common Development Commands
 
@@ -99,7 +99,7 @@ npm run package-linux        # Package for Linux
 
 ## IPC Communication
 
-The app uses a typed IPC system defined in `app/types/ipc.ts`. Main process handlers are in `app/main/lib/ipc.ts`, providing secure communication between main and renderer processes for:
+Typed IPC system in `app/types/ipc.ts` with handlers in `app/main/lib/ipc.ts`:
 
 - Settings management
 - Break control
@@ -108,7 +108,7 @@ The app uses a typed IPC system defined in `app/types/ipc.ts`. Main process hand
 
 ## Settings Architecture
 
-Settings are managed through electron-store with TypeScript interfaces defined in `app/types/settings.ts`. The store persists user preferences including:
+electron-store with TypeScript interfaces in `app/types/settings.ts`:
 
 - Break intervals and duration
 - Working hours
@@ -117,44 +117,51 @@ Settings are managed through electron-store with TypeScript interfaces defined i
 
 ## Build System
 
-- **Main Process**: Uses Webpack 5 for building the Electron main process
-- **Renderer Process**: Uses Vite for fast development and optimized production builds
-- Babel for transpiliation with TypeScript support
-- React Fast Refresh for hot module replacement (replaced react-hot-loader)
-- Production builds are optimized and minified
-- TypeScript configured with `skipLibCheck: true` to avoid node_modules type checking
+- **Main Process**: Webpack 5
+- **Renderer Process**: Vite
+- Babel + TypeScript
+- React Fast Refresh
+- TypeScript `skipLibCheck: true`
 
 ## Recent Updates
 
 ### UI and Styling
 
-- **Migrated to shadcn/ui** - Modern component library with Radix UI primitives
-- **Added Tailwind CSS** - Utility-first CSS framework for consistent styling
-- **Bundled Inter font locally** - High-quality typography with WOFF2 format for offline use
-- **Enhanced button interactions** - Improved hover/active states for better UX
+- **shadcn/ui** - Modern component library with Radix UI primitives
+- **Tailwind CSS** - Utility-first CSS framework
+- **Inter font** - Bundled locally (WOFF2)
+- **Enhanced button interactions** - Improved hover/active states
 
 ### Animation System
 
-- **Replaced react-spring with framer-motion** for better performance and modern API
-- Break window animations now use `motion.div` components
-- **Smooth progress animations** - 50ms updates for notification progress, 100ms for break window
-- Fixed infinite loop issues by using functional state updates in useEffect hooks
+- **framer-motion** - Replaced react-spring
+- `motion.div` components for break windows
+- **Smooth progress** - 50ms notification, 100ms break window updates
+- Fixed infinite loops with functional state updates
 
 ### Window Management
 
-- **Dynamic notification sizing** - Window width adjusts based on enabled buttons (450px-550px)
-- **Circular progress border** - Start button shows countdown progress around its border
-- Improved timer cleanup to prevent flickering during hot reloads
+- **Dynamic notification sizing** - 450px-550px based on enabled buttons
+- **Circular progress border** - Around Start button
+- **Multi-screen sync** - Break starts synchronized across displays
+- Timer cleanup prevents hot reload flickering
 
 ### Dependencies
 
-- **React 19** with new JSX transform (`"jsx": "react-jsx"`)
-- **TypeScript 5.8** with improved type checking
-- **Framer Motion** for smooth animations
-- **Vite** for fast development builds
+- **React 19** - New JSX transform
+- **TypeScript 5.8**
+- **Framer Motion**
+- **Vite**
 
 ### Development Experience
 
-- Fixed tsconfig.json to only check app code, not node_modules
-- Updated script names (`npm run format` instead of `prettier-fix`)
-- Improved build configuration for better hot reloading
+- tsconfig.json excludes node_modules
+- Improved hot reloading
+
+## Development Workflow
+
+**IMPORTANT**: Always run after non-trivial changes:
+
+```bash
+npm run format && npm run lint && npm run typecheck
+```

app/global.d.ts

@@ -11,12 +11,14 @@ declare const ipcRenderer: {
   invokeWasStartedFromTray: () => Promise<boolean>;
   invokeGetAppInitialized: () => Promise<boolean>;
   invokeSetAppInitialized: () => Promise<void>;
+  invokeBreakStart: () => Promise<void>;
   onPlayEndSound: (
     cb: (type: string, volume?: number) => void,
   ) => Promise<void>;
   onPlayStartSound: (
     cb: (type: string, volume?: number) => void,
   ) => Promise<void>;
+  onBreakStart: (cb: (breakEndTime: number) => void) => void;
 };
 
 declare const processEnv: {

app/main/lib/ipc.ts

@@ -45,6 +45,14 @@ ipcMain.handle(
   },
 );
 
+ipcMain.handle(IpcChannel.BreakStart, (): void => {
+  log.info(IpcChannel.BreakStart);
+  // Send break end time so all windows sync their progress to the same timeline
+  const breakLengthMs = getBreakLengthSeconds() * 1000;
+  const breakEndTime = Date.now() + breakLengthMs;
+  sendIpc(IpcChannel.BreakStart, breakEndTime);
+});
+
 ipcMain.handle(
   IpcChannel.SoundStartPlay,
   (event: IpcMainInvokeEvent, type: SoundType, volume: number = 1): void => {

app/renderer/components/break.tsx

@@ -14,6 +14,9 @@ export default function Break() {
   );
   const [ready, setReady] = useState(false);
   const [closing, setClosing] = useState(false);
+  const [sharedBreakEndTime, setSharedBreakEndTime] = useState<number | null>(
+    null,
+  );
 
   useEffect(() => {
     const init = async () => {
@@ -37,6 +40,14 @@ export default function Break() {
       setReady(true);
     };
 
+    // Listen for break start broadcasts from other windows
+    const handleBreakStart = (breakEndTime: number) => {
+      setSharedBreakEndTime(breakEndTime);
+      setCountingDown(false);
+    };
+
+    ipcRenderer.onBreakStart(handleBreakStart);
+
     // Delay or the window displays incorrectly.
     // FIXME: work out why and how to avoid this.
     setTimeout(init, 1000);
@@ -46,8 +57,8 @@ export default function Break() {
     setCountingDown(false);
   }, []);
 
-  const handleStartBreakNow = useCallback(() => {
-    setCountingDown(false);
+  const handleStartBreakNow = useCallback(async () => {
+    await ipcRenderer.invokeBreakStart();
   }, []);
 
   useEffect(() => {
@@ -168,6 +179,7 @@ export default function Break() {
             settings={settings}
             textColor={settings.textColor}
             isClosing={closing}
+            sharedBreakEndTime={sharedBreakEndTime}
           />
         )}
       </motion.div>

app/renderer/components/break/break-progress.tsx

@@ -13,6 +13,7 @@ interface BreakProgressProps {
   settings: Settings;
   textColor: string;
   isClosing?: boolean;
+  sharedBreakEndTime?: number | null;
 }
 
 export function BreakProgress({
@@ -23,6 +24,7 @@ export function BreakProgress({
   settings,
   textColor,
   isClosing = false,
+  sharedBreakEndTime = null,
 }: BreakProgressProps) {
   const [timeRemaining, setTimeRemaining] = useState<TimeRemaining | null>(
     null,
@@ -56,8 +58,14 @@ export function BreakProgress({
     }
 
     (async () => {
-      const lengthSeconds = await ipcRenderer.invokeGetBreakLength();
-      const breakEndTime = moment().add(lengthSeconds, "seconds");
+      // Use shared end time if available (from synchronized break start), otherwise calculate it
+      let breakEndTime: moment.Moment;
+      if (sharedBreakEndTime) {
+        breakEndTime = moment(sharedBreakEndTime);
+      } else {
+        const lengthSeconds = await ipcRenderer.invokeGetBreakLength();
+        breakEndTime = moment().add(lengthSeconds, "seconds");
+      }
 
       const startMsRemaining = moment(breakEndTime).diff(
         moment(),
@@ -73,14 +81,6 @@ export function BreakProgress({
             const breakDurationMs =
               new Date().getTime() - breakStartTime.getTime();
             ipcRenderer.invokeCompleteBreakTracking(breakDurationMs);
-
-            // Play end sound
-            if (settings.soundType !== SoundType.None) {
-              ipcRenderer.invokeEndSound(
-                settings.soundType,
-                settings.breakSoundVolume,
-              );
-            }
           }
 
           onEndBreak();
@@ -108,7 +108,13 @@ export function BreakProgress({
         clearTimeout(timeoutId);
       }
     };
-  }, [onEndBreak, settings, breakStartTime, isPrimaryWindow]);
+  }, [
+    onEndBreak,
+    settings,
+    breakStartTime,
+    isPrimaryWindow,
+    sharedBreakEndTime,
+  ]);
 
   const fadeIn = {
     initial: { opacity: 0 },

app/renderer/preload.js

@@ -50,6 +50,9 @@ process.once("loaded", () => {
     invokeSetAppInitialized: () => {
       return ipcRenderer.invoke("APP_INITIALIZED_SET");
     },
+    invokeBreakStart: () => {
+      return ipcRenderer.invoke("BREAK_START");
+    },
     onPlayStartSound: (cb) => {
       ipcRenderer.on("SOUND_START_PLAY", (_event, type, volume = 1) => {
         cb(type, volume);
@@ -60,5 +63,10 @@ process.once("loaded", () => {
         cb(type, volume);
       });
     },
+    onBreakStart: (cb) => {
+      ipcRenderer.on("BREAK_START", (_event, breakEndTime) => {
+        cb(breakEndTime);
+      });
+    },
   });
 });

app/types/ipc.ts

@@ -4,6 +4,7 @@ export enum IpcChannel {
   AppInitializedGet = "APP_INITIALIZED_GET",
   BreakLengthGet = "BREAK_LENGTH_GET",
   BreakPostpone = "BREAK_POSTPONE",
+  BreakStart = "BREAK_START",
   BreakWindowResize = "BREAK_WINDOW_RESIZE",
   BreakTrackingComplete = "BREAK_TRACKING_COMPLETE",
   Error = "ERROR",