Add Pomodoro Timer with reliable background audio

[GautamKumarOffical]

Bounty Solution Submission

Closes #1

Problem Statement

Build a minimal pomodoro timer web app prototype focused on reliable background audio notifications in Chrome browser. The main challenge is ensuring the notification sound plays even when the Chrome tab is in the background or minimized.

Solution Approach

Single pomodoro-timer.html file with embedded CSS/JS, zero external dependencies. Uses Web Audio API (AudioContext + OscillatorNode) for background-tab-safe audio, and Date.now() absolute deadlines so the timer stays accurate even when Chrome throttles inactive tabs.

Key decisions:

• Web Audio API over HTMLAudioElement: HTMLAudioElement gets throttled in background tabs; Web Audio API does not
• Absolute deadline timing: Using Date.now() + duration instead of decrementing a counter means the timer catches up after any throttling
• Dual update mechanism: requestAnimationFrame for smooth visible-tab updates + 1-second setInterval fallback for background accuracy
• Auto-reset after 3 seconds: Lets the user immediately start another Pomodoro cycle

Technical Implementation

• Package Manager: Not applicable — single HTML file, no build step
• Database Setup: Not applicable — fully client-side
• Environment Variables: None
• Build Process: None. Open pomodoro-timer.html directly in Chrome

Testing Evidence

• Test Coverage: Input validation (6 edge cases), start/pause/resume/reset flow, background audio via Web Audio API, keyboard navigation, permission handling
• Critical Flows Tested:
  1. Background audio: Set 1-min timer, switch tabs, verify sound plays at 00:00
  2. Tab inactive accuracy: Start 5-min timer, switch away for 2 min, verify ~3:00 remains on return
  3. Permission denied: Block audio in Chrome settings, verify timer still works with visual fallback
  4. Input validation: 0, -1, 1000, 25.5, "abc" — all show appropriate errors
  5. Keyboard: Tab through controls, Space to start/pause, Escape to reset
• Test Results: All flows pass in Chrome 126 desktop

Demo Evidence

• Video Demo: (Single HTML file — open in Chrome, no server needed)
• Setup: Save pomodoro-timer.html locally, open in Chrome

Setup Instructions

1. Download pomodoro-timer.html from this PR
2. Open it in Chrome desktop
3. Set minutes (1-999), click Start
4. Switch tabs to test background audio — sound plays at 00:00

Database Setup

Not applicable — no database needed

Architectural Decisions

• Single file: As requested by the bounty spec, zero dependencies
• Web Audio API: Only reliable way to play sound in Chrome background tabs
• Date.now() deadline: Immune to tab throttling — timer always shows correct remaining time
• Dual timers: rAF for smooth visuals + setInterval for background accuracy
• Visual + audio + notification: Three completion signals for maximum reliability

Browser Limitations

Documented in docs/browser-limitations.md:

• AudioContext requires user gesture to start (handled via permission banner)
• Chrome may throttle setInterval to 1s in background (sufficient for this use case)
• Desktop notifications require separate permission

---

Pre-submission Checklist:

• All bounty requirements met
• Tests documented with scenarios
• Working demo (single HTML file)
• Code is self-explanatory
• Setup instructions complete
• @adrianmurage tagged for review

I confirm this submission meets all requirements and is ready for review.

@adrianmurage