How the timers stay accurate

Every timer built on the timing engine — the countdown, the Pomodoro timer, the interval timer and the speech timer — stores an epoch anchor: a single instant, recorded when the timer starts, as the value the platform's Date.now() reports. It stores nothing else about time: no count of ticks and no running total of seconds, since either would be a second copy of the truth that could disagree with the first.

Every example in this guide starts from one fixed instant, 2026-03-03T14:00:00.000Z, which is a constant in the page rather than the time you opened it. Start the countdown at its default length of 5 minutes — the default you can change in the tool — at that instant and the engine records this, and only this:

{"status":"running","endsAt":1772546700000}

The status says the run is live, and endsAt is the instant it should reach zero: 5 minutes after the start, which is the default duration added to the anchor. A count-up run stores the opposite anchor, the instant it started from, under anchorAt. The countdown and the Pomodoro timer use the first shape; the interval timer and the speech timer use the second. Both shapes have a third form, idle, which stores nothing at all.

On each frame the display is derived from the difference between the stored end and now. The function that does it takes the run and the instant — plus one display option, covered below, that keeps counting past zero — and nothing that depends on an earlier call: there is no argument for the previous reading, the number of frames so far, or how long ago the last one ran. Here is the default 00:05:00 countdown read at six instants after its start, chosen to be irregular on purpose. The Display column is what the countdown tool shows: it always carries the hours field, even on a value this short.

Read any row on its own. Its reading does not depend on whether the rows above it ever happened. A page that ran a thousand frames and a page that ran one arrive at the same number for the same instant, and that is the whole of the drift-free claim: nothing accumulates, so there is nothing for error to accumulate in.

Past the end, the remaining time is clamped at zero for the timers that stop there, and the run reports itself expired. The same function has an option to keep counting below zero, so that a display can show how far over it is rather than a frozen 00:00:00; the clock formatter renders such a value with a leading minus, rounded away from zero, so one millisecond past the end formats as -00:01. The speech timer, which keeps counting past zero, arrives at its figure another way: it holds a count-up anchor, takes its remaining time as the talk's length minus the time elapsed, and presents the amount over behind a plus sign. A talk of the default length, 20 minutes — a default you can change before the talk starts — reads +00:01 one millisecond past its end. The speech-timer guide covers that readout and its bands.

A paused run cannot hold an end instant, because the end is no longer approaching, so pausing converts the run into a balance. Pause the default countdown 2 minutes after its start and the stored state becomes:

{"status":"paused","remainingMs":180000}

That balance reads 00:03:00 at the pause and still reads 00:03:00 7 minutes later, because a paused run has no anchor to measure against. Resuming adds the balance to the instant of the resume to make a new end: resume after those 7 minutes and the display reads 00:03:00, the figure it was paused at, while the stored end has moved 7 minutes later than the original, to 12 minutes after the start — exactly the paused length, because that is the only thing that changed.

The count-up state does the same thing in the other direction. A count-up run started at the fixed instant reads 06:00 when it is paused 6 minutes in, stores {"status":"paused","elapsedMs":360000}, and still reads 06:00 after 14 minutes on pause. On resume the anchor moves forward to 14 minutes after the original start, so that now minus anchor continues from the stored total: 21 minutes after the original start it reads 07:00. Paused time is simply not counted.

A single countdown has one anchor. The Pomodoro timer has a sequence of them, one per phase, and this is where a tick-counting design would leak time: if each phase started from the moment the page noticed the previous one had ended, every boundary would carry the latency of the tick that noticed it. The engine chains each phase from the previous phase's end instant instead, and its header states the consequence: a hundred consecutive phases end exactly where arithmetic says they should.

Run from the fixed instant with the defaults (25 minutes of focus, 5 minutesfor the short break, both editable in the timer's settings), the demonstration rolls the session forward at five instants chosen to land late, the first of them 400 milliseconds after the first boundary. Every boundary the engine reports falls on the arithmetic instant, not on the tick that found it:

After the last of those ticks, 1 hour 1 minute 37 seconds in, the session is in a focus phase that ends 1 hour 25 minutes after the start, and the display reads 23:23. Roll the same session forward once instead, straight from its start to that last instant. The single call crosses 4 boundaries where the five calls crossed 4, the stored end instants are identical, and the display reads 23:23. The engine's own comment on this function says it is safe to call from a quarter-second tick or after twenty minutes in the background, with an identical result either way; the figures above are that statement run. The interval timer needs no chain at all: its session is compiled into a flat plan with cumulative offsets, so “where am I?” is one subtraction against the single start epoch.

Running state is written to this browser's storage as epochs, never as “seconds left”. The persistence helpers are pure: they take and return strings, and the timer components own the storage calls. Save the default countdown 1 minute 30 seconds after its start and the envelope written is:

{"v":1,"savedAt":1772546490000,"state":{"status":"running","endsAt":1772546700000}}

It carries a version, the saved instant and the run exactly as the engine holds it. Decode it 1 minute 50 seconds later, as a reload would, and the restored run reads 00:01:40. Had the envelope held the balance at saving, 00:03:30, a reload would have shown that stale figure and the 1 minute 50 seconds away would have vanished. Because it holds the end instant, the reload lands where the wall clock says it should, which is what the engine means by resuming after a phone has been in a pocket.

The saved instant is checked against the clock before anything is restored: an envelope older than 12 hours is discarded, and so is one dated further ahead of the clock than the engine tolerates. With the reload instant above as the clock, the example envelope is restored, and four others fare as follows:

• An envelope saved 11 hours 59 minutes earlier is kept.
• An envelope saved 12 hours 1 minute earlier is discarded.
• An envelope dated 30 minutes ahead of the clock is kept.
• An envelope dated 2 hours ahead of the clock is discarded.

A discarded envelope opens the timer idle rather than resuming something stale, and each timer writes under its own versioned key, for example wrldclock.timer.countdown.v1.

The clock string rounds seconds up, so a fresh 25:00 timer reads 25:00 rather than one second less, and the display changes only once a whole second has gone. Here is the default focus interval formatted at six remaining values, each a fixed number of milliseconds after its start:

Negative values are rendered with a leading minus and rounded away from zero for the same reason. That is the formatter's rule rather than any readout's: the speech timer hands the formatter the amount over as a positive number and adds the plus sign itself, so one millisecond past the end it shows +00:01 where the formatter alone would give -00:01. Zero itself has no sign and reads 00:00:

Hours appear once there is an hour to show, as in 01:00:01. The countdown tool is the exception: it forces the hours field on every reading, so its default duration reads 00:05:00 rather than 05:00, and that is why the countdown figures in this guide carry three fields where the focus interval's carry two. The browser tab title uses the same clock string followed by the phase label, so the Pomodoro session above would show as 23:23 · Focus in the tab strip.

What the anchors guarantee is narrow and exact: whenever a tick does run, the display is correct for that instant, and a reload resumes from the stored epochs. The behaviours below are described, not simulated: they come from the tool pages and the engine, not from anything measured on your device.

• The countdown recomputes the remaining time from the system clock several times a second, and while it runs the browser tab shows the remaining time, so a backgrounded timer is still readable from the tab strip. The same holds for every timer on the engine: because the reading is derived from the clock rather than from a tick counter, a backgrounded tab catches up exactly when you return.
• The alarm is not built on this engine. It is scheduled inside its own page, so the tab has to stay open for it to sound, and phones and laptops that fall asleep can delay or suppress the tone entirely.
• The stopwatch is not built on it either. It measures elapsed time against a monotonic browser clock, so it is unaffected by the system clock being corrected while it runs; its own page says to treat its hundredths as accurate to a few hundredths rather than to the millisecond, since browser timers are deliberately coarse.