Project 22: Pomodoro Timer (Focus Pro)

📋 Project Brief

Build a Pomodoro productivity timer with browser notifications, ambient sound integration, session logging, and a distraction counter. This project focuses on timer precision, the Notification API, and building tools that support the "flow state."

✅ Feature Requirements

Feature 1: Browser Notifications

Acceptance Criteria:

• When a Pomodoro ends, trigger a browser notification even if the tab is in the background
• Request notification permission on first use
• Notification title: "⏰ Time's Up!"; body: "Take a 5-minute break" (or "15-minute break")
• Handle "Permission Denied" gracefully — fall back to an in-page alert + sound

Feature 2: Session Logs

Acceptance Criteria:

• Track how many Pomodoros were completed today, this week, and all-time
• A daily log shows: start time, end time, duration, and task label for each session
• A weekly bar chart visualizes Pomodoros per day
• Data persists in localStorage

Feature 3: Ambient Sound

Acceptance Criteria:

• Built-in ambient sounds: Rain, Coffee Shop, White Noise, Forest, Lo-fi Beats
• Sound plays during work sessions and auto-pauses during breaks (configurable)
• Volume slider independent of system volume
• Sound loops seamlessly without audible gaps

Feature 4: Custom Intervals

Acceptance Criteria:

• Default: 25-min work / 5-min short break / 15-min long break (every 4 Pomodoros)
• All intervals adjustable via a settings panel
• Settings persist in localStorage
• A "Preset" system: "Classic (25/5/15)", "Short (15/3/10)", "Long (50/10/20)"

Feature 5: Distraction Counter

Acceptance Criteria:

• A floating "I got distracted" button the user clicks whenever they lose focus
• Distractions are logged per session with timestamps
• End-of-session summary shows: "Focus score: X distractions in 25 minutes"
• Historical trend: "Your average distractions per session is decreasing 📉"

📊 Timer State Machine

State	Description	Transitions To
idle	No timer running	working (on Start)
working	Focus timer counting down	short_break, long_break (on complete), idle (on Reset)
short_break	5-min break timer	working (on complete or Skip)
long_break	15-min break (every 4th cycle)	working (on complete or Skip)
paused	Timer frozen	Previous state (on Resume)

🧪 Testing Checklist

• Unit test timer accuracy (mock Date.now for predictable tests)
• Unit test state machine transitions
• Unit test session logging and statistics calculations
• Integration test: completing 4 Pomodoros triggers a long break
• A11y: timer value announced to screen readers; notification fallback works

🚀 Stretch Goals

• Add task labels: associate each Pomodoro with a specific task
• Implement "Focus Mode" that blocks distracting URLs (browser extension)
• Add Spotify integration to play a focus playlist
• Create a widget that floats on the desktop (PWA)