Guides

The tools act. A countdown runs, a pomodoro session moves from focus to break, an interval timer moves to the next round, a speech timer changes band. The guides explain the design behind those actions in the terms the engine itself uses: the epoch anchor every timer stores and subtracts from on each frame, the phase ends that the next phase is chained from, the flat plan an interval session compiles to, and the bands a speech timer chooses purely from the remaining time.

The engine's modules carry their own design statements in their headers, and those statements are the source for every guide. No figure on these pages is typed in by hand: each default is read from the engine's settings, each example is run through the engine's own functions on fixed inputs when the site is built, and the result is formatted by the engine's own formatters. Change a default in the code and the guides change with it.

Every default a guide names is the default you can change on the tool page. Every worked example states its fixed inputs, an instant or a date chosen for the page, so the figures can be checked and will reproduce on a rebuild. The one exception is the countdown guide's zone-dependent rows: the engine parses a wall-clock target in the zone of the device it runs on, so those rows are evaluated in the zone of the machine that built the page, and the guide names that zone beside them. Each guide ends with a short set of questions, answered from the same material.

Each guide also says where the mechanism stops. The alarm is scheduled inside its 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. For the anchored timers the guarantee is narrower and exact: whenever a tick does run, the display is correct for that instant, and a reload resumes from the stored epochs. What a page cannot do while it is closed is described in the guides, not simulated.

Every timer stores an epoch anchor and derives its display from now minus that anchor on each frame. Nothing accumulates per-tick deltas, so a timer left running for an hour is as accurate as one that has just started, however irregular the ticks. The guide shows what a fresh run actually stores, using the default countdown of 5 minutes started at a fixed instant; why seconds round up, so the engine's bare clock string for that fresh run is 05:00 and the countdown tool, which always shows hours, first reads 00:05:00; and how a reload resumes from the stored epochs rather than from a remembered number of seconds, with saved runs older than 12 hours discarded.

Read: How the timers stay accurate

The countdown has two modes. Duration mode runs a fixed span, 5 minutes by default, and clamps anything beyond its ceiling: asked for 1000 hours, the engine keeps 99 hours. Target mode parses a plain date-and-time string in your own time zone, so a count that spans a daylight-saving change is short or long by exactly one hour, which is what a wall clock does. The guide measures that hour on fixed dates, once in a fixed named zone and once through the engine in the zone of the machine that built the page, which it names beside the figures; shows how a time the clocks skip is resolved; and notes that the finish message is cut to 120 characters.

Read: Counting down to a date across daylight saving

The defaults are 25 minutes of focus, a short break of 5 minutes after each interval and a long break of 15 minutes once every 4 intervals, towards a goal of 8 focus intervals; every value can be changed. When a phase ends, the next is chained from the previous phase's end instant, not from the tick that noticed, so a long session ends where arithmetic says it should. The guide lists the phase sequence, computes the default session's length with breaks included (4 hours 5 minutes), and does the same for two altered configurations.

Read: Pomodoro intervals as the engine runs them

A session compiles to a flat plan of steps, each carrying its cumulative offset from the start instant, so “where am I?” is one subtraction against the start epoch. The default structure of 8 rounds, 40 seconds of work and 20 seconds of rest, with a lead-in of 10 seconds and a cool-down of 1 minute, compiles to 17 steps and 8 minutes 50 seconds in all; the rest after the final round is dropped. The guide reads the position at several elapsed values, counts completed rounds, and compiles other structures the same way.

Read: Interval timer rounds and phases

A speaker watches one thing: how much room is left. The timer reports a band chosen purely from the remaining milliseconds, and every band carries a text label as well as a colour. The defaults are a talk of 20 minutes with the wrap-up band from 5 minutes remaining and the final band from 1 minute. Thresholds are inclusive, so exactly 1 minute left already reads “Final minute” and exactly zero reads “Over time”. The guide walks through the bands, shows how the engine's formatter renders a negative balance with a leading minus and how the stage presents that same balance as time over, counting up with a plus sign, and covers the count-up option.

Read: Speech timer warning bands

Every timer can be configured from the query string; the default pomodoro settings share as ?work=25m&break=5m&long=15m&every=4&goal=8&auto=1. Parsing is forgiving about form and strict about validity. A compound token such as 1h30m reads as 1 hour 30 minutes, clock tokens and bare numbers are understood too, and a token the parser cannot read, 25mm say, is ignoredand the default kept, so a mangled link still opens a working timer. The guide tables the token forms and each timer's share output.

Read: Shareable timer links

The calculator is proleptic Gregorian and uses integer arithmetic, Sakamoto's weekday algorithm and Julian Day Numbers, so it is independent of Date, the local time zone and the two-digit-year quirk: a date maps to the same weekday whoever runs it. Thursday, July 4, 1776 is the fixed example. The leap-year rule is shown on two century years (1900 is common, 2000 is leap), day counts and date shifts are worked on fixed dates, and the “Monday's Child” lines appear as the traditional verse they are.

Read: How the day of the week is worked out

The guides sit beside the tools they describe. The countdown, pomodoro timer, interval timer and speech timer share the anchor engine and the query-string presets. The alarm and the stopwatch have no guide of their own; their pages carry the explanation, and the methodology page places them beside the engine. The day-of-the-week calculator has the calendar guide, and the time-zone converter explains itself on its own page.

For the whole engine on one page, section by section and with the same computed figures, read the methodology.