⏱️ Rapid Development Timer Assistant

┌─────────────────────────────────────────────────────────────┐
│  ██████╗ ███████╗██╗   ██╗    ████████╗██╗███╗   ███╗███████╗
│  ██╔══██╗██╔════╝██║   ██║    ╚══██╔══╝██║████╗ ████║██╔════╝
│  ██║  ██║█████╗  ██║   ██║       ██║   ██║██╔████╔██║█████╗  
│  ██║  ██║██╔══╝  ╚██╗ ██╔╝       ██║   ██║██║╚██╔╝██║██╔══╝  
│  ██████╔╝███████╗ ╚████╔╝        ██║   ██║██║ ╚═╝ ██║███████╗
│  ╚═════╝ ╚══════╝  ╚═══╝         ╚═╝   ╚═╝╚═╝     ╚═╝╚══════╝
│                                                                
│  [STATUS: ACTIVE] [VERSION: 2.0] [MODE: PRODUCTION]          
└─────────────────────────────────────────────────────────────┘

A military-grade 15-minute sprint timer engineered for maximum productivity and uninterrupted focus sessions.

---

🎯 MISSION OBJECTIVE

Precision-engineered focus timer built for developers who demand reliability, accuracy, and zero distractions. No bloat. No bullshit. Just pure, focused development sprints.

---

⚡ CORE FEATURES

[✓] 15-minute sprint timer with millisecond precision
[✓] Pomodoro cycle: Enforced 10-min breaks after 4 sessions
[✓] Web Worker background execution (tab-independent)
[✓] Persistent state across page reloads/crashes
[✓] Enforced audio + visual notifications
[✓] Smart extension warnings (2nd & 3rd+ extensions)
[✓] Session counter tracking (X/4 to break)
[✓] Dark/Light theme with localStorage persistence
[✓] Active task tracking with pulsating indicators
[✓] One-touch keyboard shortcuts (Enter to start)
[✓] Task completion logging & history
[✓] Zero external dependencies

---

🔧 TECHNICAL STACK

Frontend:      Pure Vanilla JavaScript (ES6+)
Styling:       CSS3 with CSS Variables
Threading:     Web Worker API
Storage:       localStorage API
Notifications: Web Notifications API + HTML5 Audio
Architecture:  Event-driven, stateful persistence

---

🚀 DEPLOYMENT

# Clone the repository
git clone https://github.com/bobvasic/Rapid-Development-Timer-Assistant.git

# Navigate to directory
cd Rapid-Development-Timer-Assistant

# Serve locally (Python 3)
python3 -m http.server 8080

# OR use any static server
npx serve .

# Access at: http://localhost:8080

---

💡 HOW IT WORKS

🍅 Pomodoro Break Cycle

┌──────────────────────────────────────────────────────┐
│ Session 1 (15 min) → Complete/Extend               │
│ Session 2 (15 min) → Complete/Extend               │
│ Session 3 (15 min) → Complete/Extend               │
│ Session 4 (15 min) → BREAK ENFORCED                │
│                                                      │
│ ☕️ Break Modal → Start 10-Minute Break             │
│ Break Timer (10 min) → Notification + Audio        │
│ → Cycle resets → Start new session                 │
└──────────────────────────────────────────────────────┘

Break Enforcement Logic:

• After 4 completed sessions (1 hour), break modal appears
• User must start break before continuing
• Complete/Extend buttons hidden until break taken
• Break completion resets session counter to 0/4
• All state persists across page reloads

⚠️ Smart Extension Warnings

┌──────────────────────────────────────────────────────┐
│ 1st Extension  → ✓ Normal (no warning)             │
│ 2nd Extension  → ⚠️ ORANGE WARNING (focus!)         │
│ 3rd+ Extension → 🚨 RED ALERT (finish it!)          │
└──────────────────────────────────────────────────────┘

✅ Cross-Tab/Window Reliability

┌─────────────────────────────────────────────────┐
│ Different Tab      → ✓ Timer continues          │
│ Different Window   → ✓ Notification appears     │
│ Different App      → ✓ OS-level alert + audio   │
│ Page Reload        → ✓ Timer restores           │
│ Audio Playback     → ✓ Enforced after user act  │
└─────────────────────────────────────────────────┘

🔊 Notification System

• System Notifications: OS-level alerts appear regardless of active window
• Audio Enforcement: Unlocked on first interaction, bypasses autoplay policies
• Persistent Alerts: Notifications require manual dismissal
• Multi-Attempt Playback: Retry mechanism ensures audio plays

💾 State Persistence

• Timestamp-Based: Accurate time tracking using Date.now()
• Auto-Save: State saved every second to localStorage
• Crash Recovery: Automatically restores timer on page reopen
• Elapsed Calculation: Smart math recovers exact remaining time

⚙️ Web Worker Architecture

Main Thread              Web Worker Thread
    │                           │
    ├──[START TIMER]───────────>│
    │                           │
    │<────[TICK UPDATE]─────────┤ (every 1s)
    │                           │
    │<────[COMPLETE]────────────┤ (at 0s)
    │                           │

---

🎨 UI FEATURES

🌙 Dark Mode         → Automatic theme switching
🟠 Active Indicator  → Pulsating orange status dot
📊 Task Log          → Complete history with timestamps
⌨️  Keyboard Shortcuts → Enter to start, instant flow
🔔 Visual Feedback   → Real-time countdown display

---

📋 USAGE

Basic Flow

1. Enter Task Name → Type your focus objective
2. Press Enter or click "Start 15-Minute Sprint"
3. Stay Focused → Timer runs in background
4. Get Notified → Audio + visual alert at completion
5. Complete or Extend → Mark done or add 15 more minutes

Pomodoro Cycle Flow

┌─────────────────────────────────────────────────────┐
│ 1. Complete 4 focus sessions (15 min each)         │
│ 2. Break modal appears (enforced)                  │
│ 3. Click "☕️ Start 10-Minute Break"                │
│ 4. Break countdown begins (10:00 → 0:00)           │
│ 5. Notification: "Break Complete!"                 │
│ 6. Enter new task and start next cycle             │
└─────────────────────────────────────────────────────┘

Session Counter: Top-right displays Sessions: X/4

• Increments after each completed 15-minute session
• Resets to 0/4 after break completion
• Persists across page reloads

Keyboard Shortcuts

[Enter]  → Start timer (when in task input field)
[Click]  → Toggle dark/light mode (theme button)

---

🛡️ RELIABILITY GUARANTEES

Feature	Status	Notes
Background Timing	[ACTIVE]	Web Worker immune to throttling
Audio Playback	[ENFORCED]	Multi-retry with user interaction unlock
State Recovery	[PERSISTENT]	Survives crashes, reloads, closures
Cross-Tab Sync	[OPERATIONAL]	Notification system OS-level
Accuracy	[±1s]	Timestamp-based calculation

---

🧪 TESTED ENVIRONMENTS

✓ Chrome/Chromium 90+
✓ Firefox 88+
✓ Safari 14+
✓ Edge 90+
✓ Mobile Browsers (iOS/Android)

---

📝 FILE STRUCTURE

Rapid-Development-Timer-Assistant/
├── index.html          # Main application
├── timer-worker.js     # Web Worker for background timing
├── favicon.svg         # App icon
└── README.md          # This file

---

🔐 PRIVACY & SECURITY

[✓] No external API calls
[✓] No tracking or analytics
[✓] No cookies
[✓] No data transmission
[✓] 100% client-side execution
[✓] localStorage only (local machine)

---

🤝 CONTRIBUTING

Found a bug? Have an enhancement?

# Fork the repo
git fork https://github.com/bobvasic/Rapid-Development-Timer-Assistant.git

# Create feature branch
git checkout -b feature/your-enhancement

# Commit changes
git commit -m "feat: your enhancement description"

# Push and create PR
git push origin feature/your-enhancement

---

📄 LICENSE

MIT License - Use freely, modify as needed, attribution appreciated.

---

🎯 MISSION STATUS: OPERATIONAL

┌────────────────────────────────────────┐
│  System Status: [●] ONLINE            │
│  Timer Accuracy: [±1s]                │
│  Notification: [●] ACTIVE             │
│  Audio System: [●] OPERATIONAL        │
│  Web Worker: [●] RUNNING              │
│  State Persist: [●] ENABLED           │
└────────────────────────────────────────┘

Stay focused. Ship code. Repeat. 🚀

---

⭐ Star this repo | 🐛 Report Bug | 💡 Request Feature

Made with ⚡ by developers, for developers