Pomodoro Timer

How to use the focus timer

1. Use the 25-minute focus, 5-minute short break and 15-minute long break defaults, or enter whole durations from 1–180 minutes and a long-break frequency from 1–12. These defaults are choices, not universal prescriptions.
2. Apply settings and an optional single-line label of up to 100 Unicode code points. Before a phase starts, applied settings update its ready duration. Once running or paused, it keeps its accepted duration until an explicit Restart phase.
3. Start, pause and resume using the focused buttons. Skip asks for confirmation and shows the resulting phase before changing anything. Auto-start and sound are off by default.
4. Review totals, copy the complete session snapshot or prepare a UTF-8 text download. Reset clears counts and events, keeps applied settings, and offers Undo. Undo restores paused time, never time spent after reset.

A four-focus example

Focus 1 complete → short break
Focus 2 complete → short break
Focus 3 complete → short break
Focus 4 complete → long break
Any completed break → focus

At the default frequency of 4, only completed focus phases advance the count. Four normally completed 25-minute focus phases contribute 100 minutes to planned completed-focus time. Breaks, skips and restarts do not add to that completed total.

Skip, Restart and Reset rules

Skipping focus chooses the break that would follow completed count + 1, without actually increasing the completed count. At count 3 with frequency 4, skipping focus prepares a long break and the count stays 3. Skipping a break prepares focus. A skipped phase is recorded with its planned duration and tracked running time; the next phase waits for Start even if auto-start is enabled.

Restart discards the active phase's remaining time and accepts the applied duration afresh. A running phase restarts running; a paused phase stays paused. Restart adds no completion or skip event and no completed focus. Tracked focus time before a restart remains separately visible. Already completed phases are not restarted or skipped; start their scheduled next phase instead.

Reset clears session events and totals, returns to ready focus and stops a playing tone. Undo restores a paused snapshot and the previous settings draft. If the snapshot phase had already completed, its scheduled next phase restores paused; the recorded completion is not replayed.

Deadline timing and delayed returns

The timer reconciles a wall-clock deadline; it does not subtract one second per callback. Positive remaining seconds round up. Updates are checked about four times per second while running, when this document becomes visible, and on page-show. The visual timer does not announce every tick to screen readers; phase changes are announced politely.

Auto-start applies only when completion is observed within 2 seconds of the deadline, with no detected clock/sleep anomaly. A new phase starts from the observed transition time, not the old deadline. After a delayed callback or long suspension, at most the phase that was running completes. Resume next phase waits for an explicit action; missed cycles are never replayed.

System clock adjustments can shorten or prolong a deadline. Remaining time is capped at the amount accepted on start/resume. A detected backward clock movement, backward monotonic reading or discrepancy over 2 seconds between clocks suppresses auto-start for that phase. Browser monotonic clocks may behave differently during operating-system sleep, so tracked time is an estimate, not a certified timesheet.

What the totals mean

Focused running time uses monotonic elapsed time while focus is running, excludes pauses, and includes completed, skipped, restarted and current focus work. Each phase is clamped to its accepted planned duration after a late callback. Planned completed-focus time adds accepted durations only for completed focuses. Skipped/partial focus time and restarted focus time are separately labelled and never increase the completed total.

Whole-second total displays round down. Summary downloads include rounded tracked milliseconds, planned milliseconds, unique phase-run IDs and observation timestamps in UTC. The latest 20 events appear on screen; copy/download includes every event up to the 1000-event session limit. At that limit, export and Reset to continue.

Sound, privacy and limitations

Optional sound is a locally synthesized sine tone, bounded to 0.8 seconds. Enable it with a user action, then Test sound. Stop and disable sound closes its audio context. A blocked or suspended sound shows guidance but never blocks a state transition. Browser audio policies, background throttling, device sleep or a closed page can delay or prevent alarms; this is not a dependable wake-up or safety alarm.

Summary exports are explicitly dated snapshots; a running timer continues after capture. Timer actions and applied settings discard old download links. Clipboard failure leaves the full selectable summary and manual-copy/download guidance. Labels are literal text and are not included in page titles, URLs, analytics, logs or network requests. Nothing is stored in localStorage or IndexedDB.

This timer does not synchronize tasks, block websites, measure productivity, diagnose attention conditions or guarantee improved focus. No historical session data survives a refresh, closed tab or browser restart.