Pomodoro Timer Prototype - Development Instructions

[adrianmurage]

Project Overview

Build a minimal pomodoro timer web app prototype focused on reliable background audio notifications in Chrome browser.

Core Functionality Requirements

Timer Features

• Single HTML page with configurable timer input (minutes only)
• Timer display showing MM:SS format countdown
• Start/pause button controls
• When timer reaches 00:00: stop, play notification sound, reset display back to original configured time
• Single repeating timer (no pomodoro cycle tracking)

Critical Background Audio Requirement

• Notification sound MUST play even when Chrome tab is in background or minimized
• Handle any browser audio restrictions/permissions needed for background playbook
• Use a simple chime/beep sound
• This is the main technical challenge and should be prioritized

Interface Requirements

• Minimal design: timer input field, timer display, and start/pause buttons only
• Clean, functional layout
• No external dependencies if possible

Technical Requirements

• Single HTML file with embedded CSS/JS
• Primary target: Recent versions of Chrome desktop
• Focus on background audio functionality working reliably
• Timer must continue counting accurately when tab is inactive

Testing Requirements

Core Testing Scenarios

1. Background Audio Test: Set a short timer (30 seconds), start it, switch to another tab/app, verify sound plays when timer ends
2. Permission Testing: Test with Chrome's sound/notification permissions both allowed and blocked
3. Tab Inactive Test: Verify timer continues counting down accurately when tab is not focused
4. Input Validation: Test with various inputs (negative numbers, zero, very large numbers)

Browser Permission Scenarios

• Test initial load (first-time user)
• Test when user denies audio permissions
• Test when user initially denies, then grants permissions later

User Experience Considerations

Audio Permissions

• If browser blocks audio permissions, show clear message asking user to enable sound
• Provide instructions on how to enable audio permissions in Chrome if needed
• Graceful degradation if audio fails

Input Validation

• Minutes input should accept reasonable limits (1-999 minutes)
• Handle invalid inputs (negative numbers, non-numeric, empty)
• Clear feedback for invalid inputs

Visual Feedback

• Provide visual indication when timer starts/pauses/ends
• Visual notification should work even if sound fails
• Clear state indication (running, paused, completed)

Error Handling Requirements

Audio Failures

• Handle case where user denies audio permissions gracefully
• Timer should still function visually even if sound doesn't work
• Don't break the app if audio context fails

Input Errors

• Validate timer input before starting
• Handle edge cases (0 minutes, decimal inputs, etc.)
• Provide user-friendly error messages

Accessibility Requirements

• Ensure keyboard navigation works (tab through controls, spacebar to start/pause)
• Timer display should be readable by screen readers
• Buttons should have appropriate ARIA labels
• Sufficient color contrast for visibility

Browser Scope & Limitations

• Primary target: Recent versions of Chrome desktop
• Document any limitations discovered with background tabs/audio policies
• Note any fallback behaviors for unsupported features

Success Criteria

1. Timer functions correctly with configurable minutes
2. Audio notification plays reliably when tab is in background
3. Clean, minimal interface that's easy to use
4. Graceful handling of permission denials
5. Accurate timekeeping regardless of tab focus state

Deliverables

• Single HTML file with embedded CSS/JS
• Brief documentation of any browser limitations found
• Testing notes on background audio reliability

[adrianmurage]

If you would like to negotiate the price for this bounty. All discussions happen here. And you have to justify your negotiation to me. And people can bid against your negotiated amount.

The value of this is however capped at $400

[NeshJesse]

small question.Based on your requirements for User experience under visual feedback as shown below,:User Experience ConsiderationsAudio Permissions - If browser blocks audio permissions, show clear message asking user to enable sound - Provide instructions on how to enable audio permissions in Chrome if needed - Graceful degradation if audio fails Input Validation - Minutes input should accept reasonable limits (1-999 minutes) - Handle invalid inputs (negative numbers, non-numeric, empty) - Clear feedback for invalid inputs Visual Feedback - Provide visual indication when timer starts/pauses/ends - Visual notification should work even if sound fails - Clear state indication (running, paused, completed) Under visual notification should work even if sound fails,should the visual feedback be given when the user is inside another app or tab? That would clarify if push notifications are needed or not since they are not part of the requirements

…

On Mon, Jun 23, 2025 at 12:27 AM Adrian Murage ***@***.***> wrote: *adrianmurage* left a comment (AkongaLabs/OSS-bounties#1) <#1 (comment)> If you would like to negotiate the price for this bounty. All discussions happen here. And you have to justify your negotiation to me. And people can bid against your negotiated amount. The value of this is however capped at $400 — Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A5AR5GSQ7OJEJOCWWZL7END3E4NUBAVCNFSM6AAAAAB73ZJR4OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSOJUGQ3DEMRWG4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[tigawanna]

Seeking clarity on this part

Single HTML file with embedded CSS/JS

1. Does this mean inlining the css and js with <script> and <style> tags which excludes the use of things like vite that would output the html , css and js
2. If 1 is true , are workers exempted from this?
3. is the submission done as a PR to this repository?

[adrianmurage]

Seeking clarity on this part

Single HTML file with embedded CSS/JS

1. Does this mean inlining the css and js with <script> and <style> tags which excludes the use of things like vite that would output the html , css and js
2. If 1 is true , are workers exempted from this?
3. is the submission done as a PR to this repository?

Yes @tigawanna

1. It means inlining the css and js.
2. The problem can be solved without workers. So that's the technical challenge bit. But a solution with workers can and will be considered as a valid submission.
3. Yes, the submission is done as a PR to this repo.

Looking forward to seeing your submission 🚀

[adrianmurage]

small question.Based on your requirements for User experience under visual
feedback as shown below,:User Experience ConsiderationsAudio Permissions

• If browser blocks audio permissions, show clear message asking user to
  enable sound
• Provide instructions on how to enable audio permissions in Chrome if
  needed
• Graceful degradation if audio fails

Input Validation

• Minutes input should accept reasonable limits (1-999 minutes)
• Handle invalid inputs (negative numbers, non-numeric, empty)
• Clear feedback for invalid inputs

Visual Feedback

• Provide visual indication when timer starts/pauses/ends
• Visual notification should work even if sound fails
• Clear state indication (running, paused, completed)

Under visual notification should work even if sound fails,should the visual
feedback be given when the user is inside another app or tab?
That would clarify if push notifications are needed or not since they are
not part of the requirements
…

@NeshJesse

In this case, the visual notification was ambiguous so the engineer would ideally have a "dealer's choice" situation.
However, remember the point is to be a problem solver and offer "edge-case" solving solutions. So someone who thinks about the idea of push notifications to improve UX would have the "better solution" and would stand a stronger chance at getting the win on the bounty.

[NeshJesse]

Noted.I figured push notifications will be a good visual indicator and incorporated it in my solution.Hope you will like it,dont forget to unmute your machine and turn off do not disturb.I did that and forgot about it.I though the app was the problem,turns out it was my machine

[adrianmurage]

Love that improvement. Will review your work over the next 48 hours and get back to you.