Add background audio Pomodoro prototype

[Peter7896]

Bounty Solution Submission

Closes #1

Problem Statement

This submission adds a minimal Chrome-focused Pomodoro prototype for reliable completion alerts when the timer tab is inactive or in the background.

Solution Approach

The app is a single pomodoro-timer.html file with inline CSS and JavaScript. It unlocks Web Audio from the Start action, uses an absolute Date.now() deadline so inactive-tab ticks catch up instead of drifting, adds an inline worker tick source, requests desktop notifications asynchronously, and keeps page flash plus document-title fallback active when sound or notification permissions are blocked.

The timer starts immediately after the user action. Audio and notification permission work never blocks the core countdown, so denied or delayed browser prompts cannot leave the app stuck before start or at completion.

Technical Implementation

• Package Manager: Not applicable. This bounty asks for a single HTML file; no package manager or build step is used.
• Database Setup: Not applicable. The app is fully client-side.
• Environment Variables: None.
• Build Process: None. Open pomodoro-timer.html directly in Chrome or serve the repository as static files.

Testing Evidence

• Test Coverage: Static single-file checks, embedded JavaScript syntax validation, required browser capability hooks, input validation, start/pause/reset behavior, completion reset behavior, and console-error checks.
• Critical Flows Tested: Invalid 0 input, 1-minute start flow, pause, reset, full 1-minute completion, audio/notification fallback messaging, title updates, and no console errors.
• Test Results:
  • node tests/pomodoro-static-check.js -> pomodoro static checks OK
  • git diff --check -> passed with no output
  • Chrome local static-server check -> invalid input blocked start, running state counted down from the absolute deadline, pause/reset worked, and full 1-minute completion reset the display back to 01:00 with no console errors.

Demo Evidence

• Live Demo: https://htmlpreview.github.io/?https://github.com/Peter7896/OSS-bounties/blob/peter7896/pomodoro-background-audio-hardening/pomodoro-timer.html

Setup Instructions

1. Open pomodoro-timer.html in recent Chrome desktop.
2. Enter a whole number from 1 to 999 minutes.
3. Click Start once while the tab is visible so Chrome can unlock sound.
4. Switch to another tab or app and wait for completion.
5. If sound is blocked, allow site sound from the address bar, unmute the tab, and confirm the page flash/title/desktop-notification fallback still reports completion.
6. Optional static check: run node tests/pomodoro-static-check.js from the repository root.

Database Setup

Not applicable. No database, migrations, seeds, or services are required.

Architectural Decisions

The countdown is computed from an absolute deadline rather than interval counts, which avoids drift when Chrome slows inactive-tab callbacks. Completion handling does not wait indefinitely on Web Audio or Notification permission promises; visual completion and reset proceed independently, while audio is attempted with a timeout. The app also uses document-title changes and desktop notifications as fallback signals, and keeps everything self-contained in one HTML app file.

Bun/Yarn Justification

Not applicable. The issue-specific requirement is a standalone HTML file with embedded CSS and JavaScript, so using Bun or Yarn would add unnecessary setup.

---

Pre-submission Checklist:

• All bounty requirements met
• Tests written and passing
• Working demo available
• Code is self-explanatory
• Setup instructions complete
• @adrianmurage tagged for review

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

[Peter7896]

@adrianmurage This submission is ready for review. GitHub did not allow a formal review request from my fork, so I am tagging you here as requested in the submission instructions.