Pomodoro Timer

The Pomodoro Timer supports the Pomodoro Technique, a time-management method built around clear focus and break intervals. The classic pattern is 25 minutes of focused work, a short break of about 5 minutes, and a longer rest after several rounds. Its value is not the exact number, but the boundary it creates: tasks feel smaller, distractions can be postponed, and breaks prevent attention from fading unnoticed. The tool fits studying, writing, programming, household tasks, administrative work, and routines that benefit from a rhythm. For meetings, deep creative flow, caregiving, or physically demanding work, the session and break lengths should be adapted rather than followed rigidly.

The Pomodoro Technique was published by Francesco Cirillo in the late 1980s and codifies a four-phase cycle: a 25-minute focus interval (one pomodoro), a 5-minute short break, repeated for four rounds, then a 15-30 minute long break. The schedule is a finite state machine over four states (`work`, `shortBreak`, `longBreak`, `idle`) with transitions driven by a single countdown timer; the round counter increments after each `work -> break` transition and the long-break branch fires when `round % roundsBeforeLong === 0`. Variants like 50/10 (deep work) and 52/17 (Draugiem Group productivity study) are exposed by parameterizing the same FSM. Naive timing uses `setInterval(tick, 1000)` and decrements a counter, but JavaScript timer drift accumulates: each callback may fire 1003-1020 ms late under main-thread contention, and the HTML5 Page Visibility API combined with browser policy clamps hidden-tab timers to roughly 1 Hz in Chrome/Firefox/Safari (Safari can go as low as 1 fire/min). The drift-resistant pattern stores `endTimestamp = performance.now() + remainingMs` at start, then recomputes `remainingMs = Math.max(0, endTimestamp - performance.now())` on every tick - so a tab that resumes after 10 minutes of background time immediately catches up rather than counting 10 fictional seconds. `performance.now()` is the high-resolution monotonic clock that is immune to wall-clock adjustments (NTP, manual time changes); `Date.now()` is used only when persisting the deadline across a page refresh. Four browser APIs make the timer usable while the user works elsewhere. Web Audio API generates the end-of-phase beep with zero asset cost: `new AudioContext()` -> `createOscillator()` at 800 Hz -> `createGain()` ramped down over 200 ms -> `start()` then `stop(currentTime + 0.2)`. The Notifications API surfaces a system-level alert after one-time consent through `Notification.requestPermission()`, then `new Notification('Focus complete', { body, icon, tag: 'pomodoro' })` (the `tag` deduplicates rapid fires). The Wake Lock API requests `navigator.wakeLock.request('screen')` to keep the display awake during a focus session and releases it during breaks. The `document.title` is rewritten on each tick to `mm:ss - Focus` so the time stays visible in the tab strip. Settings (durations, auto-start, sound) persist via `localStorage` (synchronous, ~5 MB origin quota); circular progress is an SVG `<circle>` whose `stroke-dasharray = 2 * pi * r` and `stroke-dashoffset = dasharray * (1 - elapsed/total)` animate the ring without canvas overhead. Background research on attention - Cirillo's 25-minute boundary, but also work on time perception in ADHD and the cost of context switching - explains why hard interruption beats a soft 'just five more minutes'.

• FSM over four states (work/shortBreak/longBreak/idle); long break fires when `round % roundsBeforeLong === 0`. Default 25/5/15 minutes, 4 rounds; variants 50/10/30 (deep work) and 52/17 (Draugiem study).
• Drift-resistant timing: store `endTimestamp = performance.now() + remainingMs` and recompute `remainingMs = endTimestamp - performance.now()` each tick - immune to `setInterval` slip and to hidden-tab throttling clamps.
• `performance.now()` is the high-resolution monotonic clock (unaffected by NTP or manual wall-clock changes); `Date.now()` is only used to persist the deadline across page reload.
• End-of-phase beep via Web Audio API: `new AudioContext()` -> `createOscillator()` (800 Hz sine) -> `createGain()` with linear ramp to 0 over 200 ms -> `start()`/`stop()`. Zero audio assets shipped.
• System alerts via Notifications API: `Notification.requestPermission()` once, then `new Notification(title, { body, tag: 'pomodoro' })`; the `tag` deduplicates if multiple phases end while the tab is hidden.
• Screen Wake Lock API: `navigator.wakeLock.request('screen')` during focus to suppress display sleep; release on break. Wake locks are auto-released when the tab loses visibility and must be re-acquired on `visibilitychange`.
• Persistence and UI: `localStorage` (~5 MB quota) for durations/auto-start/sound; SVG ring uses `stroke-dasharray = 2*pi*r` and animates `stroke-dashoffset`; `document.title` rewritten to `mm:ss - Phase` for tab-strip visibility.