Make It Tick — The Live Clock & Focus Timer

Why the site had no JavaScript (and why that's about to change, carefully)

The dashboard was built with a rule at the very top of index.php: "No JavaScript. Navigation = query string." That's not laziness — it's a real philosophy. Server-rendered pages are simpler to reason about, they work with JS disabled, they don't break when a script errors, and there's no client/server state to keep in sync. For 90% of this dashboard, that rule is great and we're keeping it.

But a clock that updates every second, and a countdown that ticks down, are the 10% that physically cannot be server-rendered. The server renders the page once and then it's frozen — PHP has no way to reach back into an already-sent page and change the time. Only code running in the browser can do that. So we add a thin JavaScript layer for exactly these cases and nothing more. The fancy name for "works without JS, gets better with it" is progressive enhancement, and it's the grown-up way to add interactivity without throwing away the sturdy server-rendered foundation.

🐍 Python brain: setInterval(fn, 1000) is roughly "call this function every 1000ms." The closest Python feeling is a loop with time.sleep(1), or threading.Timer — except JavaScript is single-threaded with an event loop, so setInterval schedules the call and lets the browser keep doing everything else in between. Nothing blocks.

The ticking clock

This is the gentlest possible intro to JS, so let's savor it. In index.php the clock is just a span the server fills in once: <span class="clock" id="clock">14:32:07</span>. The server-rendered time is the fallback — if JavaScript never runs, you still see a (frozen) correct-at-load-time clock. Then app.js brings it to life:

function initClock() {
    var el = document.getElementById('clock');
    if (!el) return;                       // clock not on this page? bail.
    function tick() { el.textContent = fmtClock(new Date()); }
    tick();                                // paint immediately, don't wait 1s
    setInterval(tick, 1000);               // then every second forever
}

Three things worth noticing. First, that if (!el) return; guard — the clock is on every page, but writing the guard anyway is a habit that makes every module safe to run everywhere. Second, we call tick() once immediately so the clock updates the instant the page loads, instead of sitting on the stale server value for a full second. Third, textContent (not innerHTML) — we're setting plain text, and textContent can't accidentally inject HTML, so it's both faster and safer.

The focus timer — a tiny state machine

Here's where it gets fun. A countdown timer is the classic first "real" piece of interactive code because it forces you to think in state: a few variables that together describe "what's happening right now," plus functions that move between those states. Our timer tracks four things:

• minutes — the selected block length (5, 25, or 50)
• remaining — seconds left on the current countdown
• running — are we currently counting down?
• ticker — the handle returned by setInterval, so we can clearInterval to pause

The whole thing is just a handful of small functions that read and write those four variables. start() kicks off (or pauses) the countdown. reset() puts remaining back to the full length. finish() fires when we hit zero. Here's the heart of it:

function start() {
    if (running) {              // already running -> this click means "pause"
        stop();
        setLabel('⏸ PAUSED · ' + fmtMMSS(remaining));
        return;
    }
    if (remaining <= 0) reset();
    running = true;
    ticker = setInterval(function () {
        remaining -= 1;
        if (remaining <= 0) { finish(); return; }
        render();               // repaint "MM:SS"
    }, 1000);
}

The "click START again to pause" trick is the bit people find slick. One button, two meanings, decided by the running flag. When you pause, we clearInterval(ticker) so the countdown literally stops scheduling itself; the remaining value just sits there frozen until you hit start again. That's the beauty of holding state in variables — pausing is "stop the interval and don't touch the number."

The mode buttons (5 / 25 / 50) each carry a data-min attribute in the HTML, so clicking one is just "read that number, make it the new minutes, reset." We'll talk about data-* attributes properly in the next chapter — they're how the server hands little bits of data to the JavaScript.

How it's loaded — and why nothing explodes on other tabs

At the very bottom of index.php, just before </body>, there's one new line: <script src="app.js" defer></script>. The defer attribute tells the browser "download this in the background and run it after the HTML is parsed" — which means the script never blocks the page from rendering, and by the time it runs, all the elements it needs already exist.

Here's the clever part that keeps everything tidy: app.js has three modules (clock, timer, player) and it tries to start all three on every page. But each one begins with a guard like if (!disp) return;. On the Work tab there's no audio player, so the player module instantly bails. On the Music tab there's no timer display, so the timer module bails. Same script everywhere, but each piece only actually runs where its HTML exists. No errors, no "cannot read property of null," no per-page script juggling.