From bbf2509a594f850413b7c93f850649039fe2caf6 Mon Sep 17 00:00:00 2001
From: "Bryan \"Beege\" Berry" <draco4king@gmail.com>
Date: Sat, 30 May 2026 19:39:11 +0900
Subject: [PATCH] feat(pomodoro): implement zero-dependency vanilla Pomodoro
 timer

Delivers the full Pomodoro timer web app per spec 2026-05-30-pomodoro-app.md.
Three static files (index.html, styles.css, app.js) work via file:// and any
static server with no build step, no CDN, and no runtime dependencies.

Key behaviors implemented:
- 25/5/15-minute Work/Short-Break/Long-Break cycle with Long Break every 4th work
- Start/Pause/Resume toggle, Reset (no cycle advance), Skip (no Pomodoro credit)
- Wall-clock-derived countdown (endAtMs reference) prevents cumulative drift
- End-of-interval: synthesized Web Audio beep + CSS flash animation; visual cue
  fires independently of audio so browser autoplay suppression is handled safely
- Completed-Pomodoro counter; no auto-start after transition (waits for Start)
- ARIA live region announces transitions; role="timer" on countdown; no color-only
  interval signaling; visible :focus-visible ring on all buttons
- No localStorage, no Notification API, no network requests

ADRs added:
- adr/2026-05-30-vanilla-single-page-no-build.md (Accepted)
- adr/2026-05-30-walltime-drift-free-countdown.md (Accepted)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 ...2026-05-30-vanilla-single-page-no-build.md |  39 ++
 ...026-05-30-walltime-drift-free-countdown.md |  35 ++
 adr/README.md                                 |   3 +-
 app.js                                        | 286 +++++++++++++
 index.html                                    |  49 +++
 plans/2026-05-30-pomodoro-app.md              | 392 ++++++++++++++++++
 specs/2026-05-30-pomodoro-app.md              | 172 ++++++++
 styles.css                                    | 145 +++++++
 8 files changed, 1120 insertions(+), 1 deletion(-)
 create mode 100644 adr/2026-05-30-vanilla-single-page-no-build.md
 create mode 100644 adr/2026-05-30-walltime-drift-free-countdown.md
 create mode 100644 app.js
 create mode 100644 index.html
 create mode 100644 plans/2026-05-30-pomodoro-app.md
 create mode 100644 specs/2026-05-30-pomodoro-app.md
 create mode 100644 styles.css

diff --git a/adr/2026-05-30-vanilla-single-page-no-build.md b/adr/2026-05-30-vanilla-single-page-no-build.md
new file mode 100644
index 0000000..5245016
--- /dev/null
+++ b/adr/2026-05-30-vanilla-single-page-no-build.md
@@ -0,0 +1,39 @@
+---
+title: Vanilla single-page app, no build step, file:// compatible
+date: 2026-05-30
+status: Accepted
+supersedes:
+superseded-by:
+---
+
+# 2026-05-30 — Vanilla single-page app, no build step, file:// compatible
+
+## Context
+The Pomodoro app spec (specs/2026-05-30-pomodoro-app.md) mandates zero runtime
+dependencies, zero build tooling, no CDN/external assets, and a hard requirement that the
+app open and fully function via `file://` as well as from any static server. Browsers
+block ES-module fetches and many cross-origin/`file://` fetches, which constrains how code
+can be split across files.
+
+## Decision
+We will build the app as three sibling static files — `index.html`, `styles.css`,
+`app.js` — loaded with relative paths via a same-origin `<link>` and a single **classic
+(non-module) `<script defer>`**. We will use no `import`/`export`, no bundler, no
+transpiler, and no package dependencies. All JavaScript lives in `app.js` wrapped to avoid
+global leakage. State is a single in-memory object rendered by hand; no framework.
+
+## Alternatives considered
+- **ES modules (`type="module"` + `import`)** — cleaner separation, but browsers block
+  module loading under `file://`, violating the hard `file://` requirement.
+- **Single inlined HTML file (CSS + JS in `<style>`/`<script>`)** — guaranteed to work
+  under `file://`, but harms readability, diffing, and editing; classic external scripts
+  work under `file://` too, so the split is safe.
+- **A framework/bundler (React/Vite/etc.)** — directly violates zero-dependency/zero-build.
+
+## Consequences
+Easier: instant load, trivial hosting, no toolchain to maintain, works offline and via
+`file://`. Harder: no module encapsulation (mitigated by an IIFE and disciplined naming);
+no automated test/build harness by default, so verification is largely manual plus a
+lightweight no-dependency assertion approach (see the plan's Test Strategy). Adds a
+follow-up convention: any future code-splitting must preserve the classic-script,
+no-`import` constraint or supersede this ADR.
diff --git a/adr/2026-05-30-walltime-drift-free-countdown.md b/adr/2026-05-30-walltime-drift-free-countdown.md
new file mode 100644
index 0000000..0206e0e
--- /dev/null
+++ b/adr/2026-05-30-walltime-drift-free-countdown.md
@@ -0,0 +1,35 @@
+---
+title: Wall-clock-derived countdown instead of accumulated ticks
+date: 2026-05-30
+status: Accepted
+supersedes:
+superseded-by:
+---
+
+# 2026-05-30 — Wall-clock-derived countdown instead of accumulated ticks
+
+## Context
+The spec requires the timer to stay accurate within ±1s over an interval and to avoid
+cumulative drift across a multi-interval session, including when browsers throttle
+background tabs. Decrementing a counter by an assumed 1000 ms per tick drifts because
+timers fire late and are throttled when the tab is backgrounded.
+
+## Decision
+We will derive remaining time from a wall-clock reference. On Start/Resume we record
+`endAtMs = Date.now() + remainingMs`; the ticker recomputes
+`remainingMs = max(0, endAtMs - Date.now())` each tick and renders the ceil-seconds value,
+firing completion at true zero. Pause snapshots `remainingMs` from the wall clock and
+clears `endAtMs`.
+
+## Alternatives considered
+- **Decrement by 1000 per `setInterval` tick** — simplest, but accumulates drift and is
+  wrong under background throttling; violates the accuracy requirement.
+- **Web Worker timer** — more robust under throttling, but adds complexity and a second
+  file/worker that complicates the `file://` constraint, for marginal benefit at this
+  scale.
+
+## Consequences
+Easier: accurate, drift-free display regardless of tick jitter or tab throttling; pause/
+resume is exact. Harder: rendering must always go through the recompute path (no caching a
+naive seconds counter); slightly more care needed so the displayed value reaches `00:00`
+exactly once and never shows negative time.
diff --git a/adr/README.md b/adr/README.md
index 7972efd..7e27a36 100644
--- a/adr/README.md
+++ b/adr/README.md
@@ -39,4 +39,5 @@ An ADR stays `Proposed` until a branch that implements it is ready to merge.
 
 | Date | Title | Status |
 |------|-------|--------|
-| _none yet_ | | |
+| 2026-05-30 | [Vanilla single-page app, no build step, file:// compatible](2026-05-30-vanilla-single-page-no-build.md) | Accepted |
+| 2026-05-30 | [Wall-clock-derived countdown instead of accumulated ticks](2026-05-30-walltime-drift-free-countdown.md) | Accepted |
diff --git a/app.js b/app.js
new file mode 100644
index 0000000..5967708
--- /dev/null
+++ b/app.js
@@ -0,0 +1,286 @@
+/* Pomodoro timer — vanilla JS, classic non-module script.
+   Wrapped in an IIFE so no names leak to the global scope.
+   No import/export; required for file:// compatibility (see ADR). */
+(function () {
+  'use strict';
+
+  // ── Config ────────────────────────────────────────────────────────────────
+  var DURATIONS_MS = {
+    work:       25 * 60 * 1000,
+    shortBreak:  5 * 60 * 1000,
+    longBreak:  15 * 60 * 1000
+  };
+
+  // A Long Break occurs after every 4 completed Work intervals.
+  var WORK_INTERVALS_PER_LONG_BREAK = 4;
+
+  // ── State ─────────────────────────────────────────────────────────────────
+  // Single in-memory object; render() derives all UI from this.
+  // No localStorage or other persistence — resets on every page load (FR13).
+  var state = {
+    intervalType:       'work',                  // 'work' | 'shortBreak' | 'longBreak'
+    status:             'ready',                  // 'ready' | 'running' | 'paused'
+    remainingMs:        DURATIONS_MS.work,
+    endAtMs:            null,                     // wall-clock deadline while running
+    completedWorkCount: 0,
+    // Counts work intervals completed since the last long break.
+    // Reset to 0 when a long break is selected as the next interval.
+    workSinceLongBreak: 0,
+    tickId:             null                      // setInterval handle
+  };
+
+  // ── Audio ─────────────────────────────────────────────────────────────────
+  // AudioContext created lazily on the first user gesture so browsers that
+  // block autoplay don't throw before any interaction.
+  var audioCtx = null;
+
+  function ensureAudioCtx() {
+    if (!audioCtx) {
+      try {
+        audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+      } catch (_) {
+        // Web Audio not available; visual cue will still fire.
+      }
+    }
+    // Resume a context that was suspended by the browser's autoplay policy.
+    if (audioCtx && audioCtx.state === 'suspended') {
+      audioCtx.resume();
+    }
+  }
+
+  // Short synthesized beep — 880 Hz, ~200 ms, with a quick gain ramp to avoid
+  // clicks. Entirely wrapped in try/catch; a failure here must never block the
+  // visual cue that follows.
+  function beep() {
+    if (!audioCtx) return;
+    try {
+      var osc  = audioCtx.createOscillator();
+      var gain = audioCtx.createGain();
+      osc.connect(gain);
+      gain.connect(audioCtx.destination);
+
+      osc.frequency.value = 880;
+      osc.type            = 'sine';
+
+      var now = audioCtx.currentTime;
+      gain.gain.setValueAtTime(0, now);
+      gain.gain.linearRampToValueAtTime(0.4, now + 0.01);   // fast attack
+      gain.gain.linearRampToValueAtTime(0, now + 0.20);     // decay
+
+      osc.start(now);
+      osc.stop(now + 0.25);
+    } catch (_) {
+      // Ignore; the visual cue fires unconditionally after this call returns.
+    }
+  }
+
+  // ── DOM references ────────────────────────────────────────────────────────
+  var elContainer    = document.querySelector('.container');
+  var elIntervalLabel = document.getElementById('interval-label');
+  var elCountdown    = document.getElementById('countdown');
+  var elCount        = document.getElementById('pomodoro-count');
+  var elAnnounce     = document.getElementById('announce');
+  var btnToggle      = document.getElementById('btn-toggle');
+  var btnReset       = document.getElementById('btn-reset');
+  var btnSkip        = document.getElementById('btn-skip');
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+  // Display ceil-seconds so 25:00 shows at the very start and 00:00 appears
+  // only at true zero (never negative).
+  function formatMMSS(ms) {
+    var totalSec = Math.ceil(Math.max(0, ms) / 1000);
+    var m = Math.floor(totalSec / 60);
+    var s = totalSec % 60;
+    return (m < 10 ? '0' : '') + m + ':' + (s < 10 ? '0' : '') + s;
+  }
+
+  var LABEL_TEXT = {
+    work:       'Work',
+    shortBreak: 'Short Break',
+    longBreak:  'Long Break'
+  };
+
+  // ── Render ────────────────────────────────────────────────────────────────
+  // Called after every state mutation and on each tick.
+  function render() {
+    elCountdown.textContent    = formatMMSS(state.remainingMs);
+    elIntervalLabel.textContent = LABEL_TEXT[state.intervalType];
+    elContainer.setAttribute('data-interval', state.intervalType);
+    elCount.textContent        = String(state.completedWorkCount);
+
+    // Toggle button label reflects current status.
+    if (state.status === 'running') {
+      btnToggle.textContent           = 'Pause';
+      btnToggle.setAttribute('aria-pressed', 'true');
+    } else if (state.status === 'paused') {
+      btnToggle.textContent           = 'Resume';
+      btnToggle.setAttribute('aria-pressed', 'false');
+    } else {
+      // 'ready'
+      btnToggle.textContent           = 'Start';
+      btnToggle.setAttribute('aria-pressed', 'false');
+    }
+
+    // Update the browser tab title as a nice-to-have readout.
+    document.title = formatMMSS(state.remainingMs) + ' — ' + LABEL_TEXT[state.intervalType];
+  }
+
+  // ── Ticker ────────────────────────────────────────────────────────────────
+  // Ticker runs at ~250 ms to keep the display responsive without wasting CPU.
+  // Remaining time is always derived from the wall-clock endAtMs reference,
+  // not accumulated from tick deltas — this prevents cumulative drift even
+  // under background tab throttling (see ADR: wall-clock-derived-countdown).
+
+  function tick() {
+    state.remainingMs = Math.max(0, state.endAtMs - Date.now());
+    render();
+    if (state.remainingMs <= 0) {
+      stopTicker();
+      completeInterval();
+    }
+  }
+
+  function stopTicker() {
+    if (state.tickId !== null) {
+      clearInterval(state.tickId);
+      state.tickId = null;
+    }
+  }
+
+  function startTicker() {
+    // Always stop first to guarantee at most one concurrent ticker.
+    stopTicker();
+    state.tickId = setInterval(tick, 250);
+  }
+
+  // ── Controls ──────────────────────────────────────────────────────────────
+
+  // start() and pause() each guard against the wrong state so that rapid or
+  // redundant clicks are no-ops (cannot spawn multiple tickers or freeze time twice).
+
+  function start() {
+    if (state.status === 'running') return; // idempotent guard
+    // Unlock AudioContext on this user gesture so the first beep can play.
+    ensureAudioCtx();
+    state.endAtMs = Date.now() + state.remainingMs;
+    state.status  = 'running';
+    startTicker();
+    render();
+  }
+
+  function pause() {
+    if (state.status !== 'running') return; // idempotent guard
+    stopTicker();
+    // Snapshot remaining time from the wall clock so Resume is exact.
+    state.remainingMs = Math.max(0, state.endAtMs - Date.now());
+    state.endAtMs     = null;
+    state.status      = 'paused';
+    render();
+  }
+
+  function togglePlay() {
+    if (state.status === 'running') {
+      pause();
+    } else {
+      start();
+    }
+  }
+
+  function reset() {
+    stopTicker();
+    state.remainingMs = DURATIONS_MS[state.intervalType];
+    state.endAtMs     = null;
+    state.status      = 'ready';
+    // Completed count and workSinceLongBreak are intentionally preserved —
+    // Reset restores the current interval's duration without touching the cycle.
+    render();
+  }
+
+  function skip() {
+    ensureAudioCtx();
+    stopTicker();
+    // Skipping does NOT count as a completed interval (see spec edge-case +
+    // acceptance criteria). Pass countCompletion:false.
+    advance({ countCompletion: false });
+  }
+
+  // ── Interval transitions ──────────────────────────────────────────────────
+
+  // Decides the next interval and resets the timer to ready.
+  // countCompletion=true  → a work interval that reached 00:00; increments the counters.
+  // countCompletion=false → a skipped interval; counters unchanged.
+  function advance(opts) {
+    var countCompletion = opts.countCompletion;
+    var current         = state.intervalType;
+    var next;
+
+    if (current === 'work') {
+      if (countCompletion) {
+        state.completedWorkCount += 1;
+        state.workSinceLongBreak += 1;
+      }
+      // A skipped work interval does NOT push toward the long-break cadence.
+      if (state.workSinceLongBreak >= WORK_INTERVALS_PER_LONG_BREAK) {
+        next = 'longBreak';
+        // Reset the toward-long-break counter now so the cycle wraps cleanly
+        // when this long break ends (edge case: Long Break → Work resets counter).
+        state.workSinceLongBreak = 0;
+      } else {
+        next = 'shortBreak';
+      }
+    } else {
+      // Any break → always back to work.
+      next = 'work';
+    }
+
+    state.intervalType = next;
+    state.remainingMs  = DURATIONS_MS[next];
+    state.endAtMs      = null;
+    // Next interval waits for Start — does not auto-start (FR11).
+    state.status       = 'ready';
+
+    render();
+    // Announce the transition to screen readers via the polite live region.
+    announce('Interval complete. Starting ' + LABEL_TEXT[next] + '.');
+  }
+
+  // ── End-of-interval cue ───────────────────────────────────────────────────
+
+  // Visual and audio cues are decoupled: the flash always fires regardless of
+  // whether the beep succeeds (audio may be suppressed by browser policy).
+  function completeInterval() {
+    beep();
+    flashVisualCue();
+    advance({ countCompletion: true });
+  }
+
+  function flashVisualCue() {
+    // Remove then re-add so repeated completions each trigger the animation.
+    elContainer.classList.remove('flash');
+    // Trigger a reflow so removing+adding in the same frame is not collapsed.
+    void elContainer.offsetWidth;
+    elContainer.classList.add('flash');
+    setTimeout(function () {
+      elContainer.classList.remove('flash');
+    }, 800);
+  }
+
+  // Updates the sr-only polite live region so assistive tech announces events
+  // without reading every countdown tick.
+  function announce(msg) {
+    elAnnounce.textContent = '';
+    // Force the DOM update so repeated identical messages are re-announced.
+    setTimeout(function () {
+      elAnnounce.textContent = msg;
+    }, 50);
+  }
+
+  // ── Event listeners ───────────────────────────────────────────────────────
+  btnToggle.addEventListener('click', togglePlay);
+  btnReset.addEventListener('click',  reset);
+  btnSkip.addEventListener('click',   skip);
+
+  // ── Initial render ────────────────────────────────────────────────────────
+  render();
+
+}());
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..68d38f9
--- /dev/null
+++ b/index.html
@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pomodoro</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <main class="container" data-interval="work">
+    <h1 class="interval-label" id="interval-label">Work</h1>
+
+    <!--
+      role="timer" marks this as a live countdown region.
+      aria-live="off" keeps assistive tech quiet on every tick;
+      interval transitions are announced via the separate #announce region instead.
+    -->
+    <div
+      class="countdown"
+      id="countdown"
+      role="timer"
+      aria-label="Time remaining"
+      aria-live="off"
+    >25:00</div>
+
+    <!-- Polite live region used to announce interval transitions and end-of-interval events -->
+    <div
+      class="sr-only"
+      id="announce"
+      aria-live="polite"
+      aria-atomic="true"
+    ></div>
+
+    <div class="pomodoro-count" aria-live="polite" aria-atomic="true">
+      Pomodoros completed: <span id="pomodoro-count">0</span>
+    </div>
+
+    <div class="controls">
+      <!-- Single toggle covers Start / Pause / Resume (FR3) -->
+      <button id="btn-toggle" type="button" aria-pressed="false">Start</button>
+      <button id="btn-reset"  type="button">Reset</button>
+      <button id="btn-skip"   type="button">Skip</button>
+    </div>
+  </main>
+
+  <!-- Classic non-module script — required for file:// compatibility -->
+  <script src="app.js" defer></script>
+</body>
+</html>
diff --git a/plans/2026-05-30-pomodoro-app.md b/plans/2026-05-30-pomodoro-app.md
new file mode 100644
index 0000000..b27be03
--- /dev/null
+++ b/plans/2026-05-30-pomodoro-app.md
@@ -0,0 +1,392 @@
+---
+title: Implementation plan — Pomodoro timer web app (zero-dependency, vanilla)
+date: 2026-05-30
+spec: specs/2026-05-30-pomodoro-app.md
+branch: feat/pomodoro-app
+---
+
+# 2026-05-30 — Pomodoro timer web app (implementation plan)
+
+## Overview
+
+Build a self-contained Pomodoro timer that runs by opening a single HTML file via
+`file://` or any static server. Vanilla HTML/CSS/JS, **zero build tooling, zero runtime
+dependencies, no CDN/external assets**. The app cycles Work (25:00) → Short Break (5:00) /
+Long Break (15:00, every 4th work), with Start/Pause/Resume, Reset, and Skip controls, a
+completed-Pomodoro counter, a drift-free wall-clock countdown, and an end-of-interval cue
+(synthesized Web Audio beep + visual flash). No persistence, no Notification API, no
+network requests at runtime.
+
+**In scope:** the full feature set in the spec's functional requirements 1–14 and all
+acceptance criteria.
+
+**Out of scope:** settings/customization UI, persistence, theming, i18n, mobile-specific
+layout work beyond basic responsiveness, browser-tab-title countdown (low-impact nice-to-have).
+
+**Branch:** `feat/pomodoro-app`
+
+## Architecture & Design
+
+### File layout
+
+The `file://` hard requirement rules out cross-file ES-module `import` (browsers block
+module fetches under `file://` via CORS). To keep concerns separated while staying within
+that constraint, ship **three sibling files loaded with relative paths** — a same-origin
+`<link rel="stylesheet">` and a **classic (non-module) `<script src>`** both load fine
+under `file://`:
+
+- `index.html` — document structure, controls, ARIA live regions. Loads `styles.css` via
+  `<link href="styles.css">` and `app.js` via `<script src="app.js" defer></script>`
+  (classic script, **no `type="module"`**).
+- `styles.css` — all styling; interval-type theming via a `data-interval` attribute on a
+  container element (no color-only signaling — also a text label).
+- `app.js` — all behavior in one classic script using an IIFE (or top-level `const`s) to
+  avoid leaking globals. No `import`/`export`.
+
+No `package.json`, no `node_modules`, no bundler config. (A tiny `package.json` with only
+a `scripts` block and **no `dependencies`/`devDependencies`** MAY be added solely to wire
+the lint step in the quality gate; if added it MUST declare zero dependencies. Default:
+omit it and run the linter via `npx` one-off so the project tree stays dependency-free —
+see Implementation Steps step 7.)
+
+### Core model (in `app.js`)
+
+A single in-memory state object drives render; no framework. Shape:
+
+```
+state = {
+  intervalType: 'work' | 'shortBreak' | 'longBreak',
+  status: 'ready' | 'running' | 'paused',   // 'ready' = full duration, not started
+  remainingMs: number,                       // ms left in current interval
+  endAtMs: number | null,                    // wall-clock target while running (Date.now()+remainingMs)
+  completedWorkCount: number,                // total completed Pomodoros this session
+  workSinceLongBreak: number,                // 0..3, resets to 0 when a long break STARTS
+  rafId / tickId: number | null,             // active ticker handle
+}
+```
+
+Fixed config constant:
+
+```
+const DURATIONS_MS = { work: 25*60*1000, shortBreak: 5*60*1000, longBreak: 15*60*1000 };
+const WORK_INTERVALS_PER_LONG_BREAK = 4;
+```
+
+### Drift-free countdown (FR timing-accuracy, edge case "no cumulative drift")
+
+Do **not** decrement a counter by 1000 each tick. On Start/Resume, compute
+`endAtMs = Date.now() + remainingMs`. The ticker (use `setInterval` at ~250 ms, or
+`requestAnimationFrame`) each tick computes `remainingMs = max(0, endAtMs - Date.now())`
+and re-renders `MM:SS` derived from that. Display value = `Math.ceil(remainingMs/1000)` so
+it shows `25:00` at start and only reaches `00:00` at true zero. When `remainingMs <= 0`,
+fire `completeInterval()`. This keeps accuracy even when background tabs throttle the
+timer, because the value is recomputed from wall clock, not accumulated.
+
+On Pause: clear ticker, set `remainingMs = max(0, endAtMs - Date.now())`, set
+`endAtMs = null`, `status = 'paused'`. Resume re-derives `endAtMs`.
+
+### Control semantics (functions in `app.js`)
+
+- `start()` — only acts when `status !== 'running'`; sets `endAtMs`, starts ticker,
+  `status='running'`. Idempotent guard satisfies "Start while running = no-op". Also
+  resumes a suspended `AudioContext` here (user-gesture audio unlock).
+- `pause()` — only acts when `status === 'running'`; freezes time. No-op otherwise.
+- `togglePlay()` — the single Start/Pause/Resume button calls `start()` or `pause()`
+  based on current `status`. (FR3 allows one toggle.)
+- `reset()` — stops ticker, `remainingMs = DURATIONS_MS[intervalType]`, `status='ready'`,
+  `endAtMs=null`. Does **not** change `completedWorkCount` or `workSinceLongBreak`, does
+  **not** advance interval (FR4, acceptance: count unchanged).
+- `skip()` — stops ticker, advances cycle via `advance({ countCompletion:false })`.
+  Skipping work does NOT increment `completedWorkCount` (edge case + acceptance).
+- `completeInterval()` — fires the end-of-interval cue (beep + visual flash), then
+  `advance({ countCompletion: true })`. Only this path (countdown reaching 0) increments
+  the Pomodoro count when the completed interval was work.
+- `advance({ countCompletion })` — pure-ish transition that:
+  1. If leaving a `work` interval and `countCompletion`, increment `completedWorkCount`
+     and increment `workSinceLongBreak`.
+  2. Choose next interval:
+     - leaving work → if `workSinceLongBreak >= WORK_INTERVALS_PER_LONG_BREAK` →
+       `longBreak` (and on the long break *starting*, reset `workSinceLongBreak = 0`);
+       else `shortBreak`.
+     - leaving any break → `work`.
+     - **Skip nuance:** when skipping a work interval (`countCompletion=false`),
+       `workSinceLongBreak` is NOT incremented, so a skipped work does not push toward the
+       long break (consistent with "only completed work counts"). Document this explicitly
+       in code comments so the long-break-cadence wrap (edge case 3) is unambiguous.
+  3. Set `remainingMs = DURATIONS_MS[next]`, `status='ready'`, `endAtMs=null`,
+     `intervalType=next`. **Does not auto-start** (FR11): next interval waits for Start.
+
+  Note on `workSinceLongBreak` reset timing: reset it to 0 at the moment a long break is
+  selected as the next interval, so that the four-work counter restarts cleanly and the
+  cycle wraps correctly (edge case 3: Long Break → Work resets the toward-long-break
+  counter appropriately).
+
+- `render()` — single function that writes derived UI from `state`: `MM:SS` text, interval
+  label ("Work" / "Short Break" / "Long Break"), `data-interval` attribute for theming,
+  completed count, and button label/`aria-pressed` (Start vs Pause). Called after every
+  state mutation and on each tick.
+
+### Audio (FR8, edge case: blocked autoplay)
+
+Lazily create one `AudioContext` on first user gesture (inside `start()` / any control
+handler). `beep()` creates an `OscillatorNode` + `GainNode`, plays a short tone
+(~440–880 Hz, ~150–250 ms) with a quick gain ramp to avoid clicks, then stops. Wrap the
+whole audio path in `try/catch` and guard on `AudioContext` existence so that if audio is
+unavailable or suppressed, **the visual cue still fires** (edge case). `beep()` is called
+only from `completeInterval()`, never from skip/reset.
+
+### Visual end-of-interval cue (FR8)
+
+Add/remove a CSS class (e.g. `flash`) on a container for a brief animation, and update the
+ARIA live region text so assistive tech announces the transition. Use a timeout to remove
+the class. The visual cue is independent of audio success.
+
+### Accessibility (NFR)
+
+- All controls are real `<button>` elements with visible text and/or `aria-label`.
+- The countdown sits in an element with `aria-live="polite"` /
+  `role="timer"`-style semantics; interval-type changes announced via a live region.
+  Avoid announcing every second too aggressively — announce interval/status changes and
+  let the visible countdown be the primary readout (document the chosen approach in code).
+- Interval type conveyed by **text label AND** color (color never the sole signal).
+- Buttons keyboard-operable by default; ensure visible focus styles in `styles.css`.
+
+### Control-flow summary
+
+`User click → handler (start/pause/reset/skip) → mutate state → (start/stop ticker) →
+render()`. `Ticker tick → recompute remainingMs from wall clock → render() →
+if remainingMs<=0: completeInterval() → beep + visual cue → advance() → render()`.
+
+## Architecture Decisions (ADRs)
+
+### ADR to add — `adr/2026-05-30-vanilla-single-page-no-build.md` (status: Proposed)
+
+```
+---
+title: Vanilla single-page app, no build step, file:// compatible
+date: 2026-05-30
+status: Proposed
+supersedes:
+superseded-by:
+---
+
+# 2026-05-30 — Vanilla single-page app, no build step, file:// compatible
+
+## Context
+The Pomodoro app spec (specs/2026-05-30-pomodoro-app.md) mandates zero runtime
+dependencies, zero build tooling, no CDN/external assets, and a hard requirement that the
+app open and fully function via `file://` as well as from any static server. Browsers
+block ES-module fetches and many cross-origin/`file://` fetches, which constrains how code
+can be split across files.
+
+## Decision
+We will build the app as three sibling static files — `index.html`, `styles.css`,
+`app.js` — loaded with relative paths via a same-origin `<link>` and a single **classic
+(non-module) `<script defer>`**. We will use no `import`/`export`, no bundler, no
+transpiler, and no package dependencies. All JavaScript lives in `app.js` wrapped to avoid
+global leakage. State is a single in-memory object rendered by hand; no framework.
+
+## Alternatives considered
+- **ES modules (`type="module"` + `import`)** — cleaner separation, but browsers block
+  module loading under `file://`, violating the hard `file://` requirement.
+- **Single inlined HTML file (CSS + JS in `<style>`/`<script>`)** — guaranteed to work
+  under `file://`, but harms readability, diffing, and editing; classic external scripts
+  work under `file://` too, so the split is safe.
+- **A framework/bundler (React/Vite/etc.)** — directly violates zero-dependency/zero-build.
+
+## Consequences
+Easier: instant load, trivial hosting, no toolchain to maintain, works offline and via
+`file://`. Harder: no module encapsulation (mitigated by an IIFE and disciplined naming);
+no automated test/build harness by default, so verification is largely manual plus a
+lightweight no-dependency assertion approach (see the plan's Test Strategy). Adds a
+follow-up convention: any future code-splitting must preserve the classic-script,
+no-`import` constraint or supersede this ADR.
+```
+
+### ADR to add — `adr/2026-05-30-walltime-drift-free-countdown.md` (status: Proposed)
+
+```
+---
+title: Wall-clock-derived countdown instead of accumulated ticks
+date: 2026-05-30
+status: Proposed
+supersedes:
+superseded-by:
+---
+
+# 2026-05-30 — Wall-clock-derived countdown instead of accumulated ticks
+
+## Context
+The spec requires the timer to stay accurate within ±1s over an interval and to avoid
+cumulative drift across a multi-interval session, including when browsers throttle
+background tabs. Decrementing a counter by an assumed 1000 ms per tick drifts because
+timers fire late and are throttled when the tab is backgrounded.
+
+## Decision
+We will derive remaining time from a wall-clock reference. On Start/Resume we record
+`endAtMs = Date.now() + remainingMs`; the ticker recomputes
+`remainingMs = max(0, endAtMs - Date.now())` each tick and renders the ceil-seconds value,
+firing completion at true zero. Pause snapshots `remainingMs` from the wall clock and
+clears `endAtMs`.
+
+## Alternatives considered
+- **Decrement by 1000 per `setInterval` tick** — simplest, but accumulates drift and is
+  wrong under background throttling; violates the accuracy requirement.
+- **Web Worker timer** — more robust under throttling, but adds complexity and a second
+  file/worker that complicates the `file://` constraint, for marginal benefit at this
+  scale.
+
+## Consequences
+Easier: accurate, drift-free display regardless of tick jitter or tab throttling; pause/
+resume is exact. Harder: rendering must always go through the recompute path (no caching a
+naive seconds counter); slightly more care needed so the displayed value reaches `00:00`
+exactly once and never shows negative time.
+```
+
+### Relevant existing ADRs for the implementer
+
+None — `adr/README.md` index is empty (`_none yet_`). The implementer creates the two ADR
+files above from this plan's content and sets their status to `Accepted` on the branch
+(per `adr/README.md` lifecycle), then adds both rows to the `adr/README.md` index table.
+
+## Implementation Steps (ordered)
+
+1. **Create `index.html`** at the worktree root with: `<!doctype html>`, `lang="en"`,
+   `<meta charset>` + `<meta name="viewport">`, `<title>Pomodoro</title>`,
+   `<link rel="stylesheet" href="styles.css">`, and a body containing: a container with a
+   `data-interval` attribute; an interval-type **text label**; the `MM:SS` countdown
+   element with `role="timer"` and an `aria-live="polite"` region for announcements; the
+   completed-Pomodoro count element; and four `<button>`s — Start/Pause toggle, Reset,
+   Skip (the toggle's label flips between "Start"/"Pause"/"Resume"). End with
+   `<script src="app.js" defer></script>` (classic script, **no `type="module"`**).
+   Traceable to FR2,3,4,5,7,9; NFR accessibility. (Verify: opens via `file://`.)
+
+2. **Create `styles.css`** with: layout, large monospace countdown, distinct visual
+   treatment per interval via `[data-interval="work"|"shortBreak"|"longBreak"]` selectors
+   (color **plus** the text label already in HTML — color not sole signal), a `flash`
+   animation class for the end-of-interval visual cue, and visible `:focus-visible`
+   styles on buttons. No external fonts/assets; system font stack only. Traceable to
+   FR7,8; NFR accessibility, no-external-assets.
+
+3. **Create `app.js` — state + render core.** Define `DURATIONS_MS`,
+   `WORK_INTERVALS_PER_LONG_BREAK`, the `state` object initialized to
+   `{ intervalType:'work', status:'ready', remainingMs:DURATIONS_MS.work, endAtMs:null,
+   completedWorkCount:0, workSinceLongBreak:0, tickId:null }`, a `formatMMSS(ms)` helper
+   (`Math.ceil(ms/1000)` → `MM:SS`, never negative), and `render()` that writes countdown
+   text, interval label, `data-interval`, count, and toggle-button label/`aria` state.
+   Wrap everything in an IIFE; no globals leaked; no `import`/`export`. Traceable to
+   FR1,2,7,9; acceptance "fresh open shows 25:00 / Work / 0 / ready".
+
+4. **Add the ticker + control functions** to `app.js`: `startTicker()`/`stopTicker()`
+   (using `setInterval` ~250 ms), `start()`, `pause()`, `togglePlay()`, `reset()`,
+   `skip()`, `completeInterval()`, and `advance({countCompletion})` exactly per the
+   "Control semantics" and "advance" design above, including the idempotent guards (no-op
+   on redundant Start/Pause; no concurrent tickers — always `stopTicker()` before
+   `startTicker()`). Wire `click` listeners on the four buttons; on initial load call
+   `render()`. Traceable to FR2,3,4,5,6,10,11; all edge cases (no double-speed, no
+   negative time, rapid-click safety, cycle wrap, skip-not-counting).
+
+5. **Add audio + visual cue** to `app.js`: lazy `AudioContext` created/resumed on first
+   control gesture; `beep()` (oscillator+gain, short tone, `try/catch`, guarded so failure
+   never throws); `flashVisualCue()` (add `flash` class + update live region, remove class
+   on timeout). Call both only from `completeInterval()`; ensure the visual cue fires even
+   if `beep()` throws/no-ops. Traceable to FR8; edge case "audio blocked → visual still
+   fires"; FR14 (no Notification API), FR12 (no network).
+
+6. **Manual verification pass against acceptance criteria** (see Test Strategy). Open
+   `index.html` via `file://` in an evergreen browser; walk each acceptance bullet; confirm
+   DevTools Network tab shows **zero** runtime requests beyond the three local files;
+   confirm reload returns to fresh state; confirm no `localStorage` writes. Traceable to
+   FR12,13; all acceptance criteria.
+
+7. **Run the project quality gate.** There is no build/test framework. The gate for this
+   change is: (a) `grep`/inspection assertions that the tree contains no `node_modules`, no
+   bundler config, and **no external URL references** in `index.html`/`styles.css`/`app.js`
+   (acceptance criterion: "no references to external URLs"); (b) run a no-install linter
+   over the static files — e.g. `npx --yes eslint@latest --no-eslintrc --env browser,es2022
+   --parser-options ecmaVersion:2022 app.js` or, if offline, a `node --check app.js` syntax
+   check plus an HTML/CSS visual review. Record the actual command used and its output.
+   **Do not add any runtime dependency or `node_modules` to satisfy this.** Traceable to
+   the spec's zero-dependency acceptance criterion and AGENTS.md "verify your work".
+
+## Interface & Compatibility
+
+- **Observable contract:** the three filenames (`index.html`, `styles.css`, `app.js`) and
+  their relative references must stay co-located so `file://` loading works. Button
+  accessible names ("Start"/"Pause"/"Resume", "Reset", "Skip") are the keyboard/AT
+  contract.
+- This is a greenfield app; no existing interfaces to preserve. No external API surface.
+
+## Data / Migration Notes
+
+None. Per FR13 the app persists nothing — no `localStorage`, cookies, IndexedDB, or files.
+All state is in-memory and resets on reload by construction. No schema, no migration.
+
+## Test Strategy
+
+No build/test framework exists, and adding one would violate the zero-dependency
+constraint. Testing is **manual against the acceptance criteria**, supported by a
+lightweight, dependency-free assertion approach using only the browser and system tools.
+
+**Manual scenarios (one per acceptance criterion — happy path + edge):**
+- *Fresh open*: load shows `25:00`, "Work", count 0, ready/stopped. (Happy path.)
+- *Start counts down*: press Start → ticks once/sec from `25:00`. Use a stopwatch or a
+  temporary fast-mode constant to verify ±1s accuracy over an interval (drift check).
+- *Pause/Resume*: Pause freezes display; Resume continues from the same value. Press Start
+  twice rapidly and Pause twice rapidly → no double-speed, no second ticker (rapid-click /
+  concurrency edge).
+- *Reset*: while running, Reset → full duration, stopped, count unchanged. (Validation of
+  no side effects.)
+- *Skip work*: Skip a work interval → advances to Short/Long break, count NOT incremented
+  (skip-semantics edge).
+- *Work completes*: let a work interval reach `00:00` (use fast-mode) → count +1, beep +
+  visual cue fire, next break loaded **ready** (not auto-started).
+- *Long-break cadence*: complete 4 work intervals → 4th completion loads Long Break
+  (15:00); confirm the toward-long-break counter resets and the cycle wraps (Long Break →
+  Work) correctly (edge case 3).
+- *No auto-start*: after any interval ends, the next stays at full duration and does not
+  count down until Start.
+- *Reload resets*: from any state, reload → fresh state, no restored data (FR13).
+- *Offline / file://*: open via `file://` with network disabled → all features work; check
+  DevTools Network shows zero requests (FR12), and Application/Storage shows no
+  `localStorage` entries (FR13).
+- *Audio blocked*: in a browser that suppresses pre-gesture audio, confirm the **visual**
+  cue still fires when an interval ends (audio-blocked edge).
+- *`00:00` boundary*: confirm the display never shows negative time and reaches `00:00`
+  exactly once per interval.
+
+**Lightweight automatable checks (system tools only, no deps):**
+- A short `assert.js` of **pure** functions (`formatMMSS`, and the `advance`/next-interval
+  selection logic factored to take state in and return next state out) runnable with
+  `node app-logic-test.js` *only if* those pure helpers are exported in a way that does not
+  break the classic-script `file://` build (e.g. via a guarded
+  `typeof module !== 'undefined' && (module.exports = ...)` at the bottom of `app.js`,
+  which is inert in the browser). This is **optional**; if it complicates the single-script
+  constraint, skip it and rely on manual testing — document the choice.
+- `grep -rIn -E "https?://|//cdn|fonts\\.|unpkg|jsdelivr|cdnjs" index.html styles.css app.js`
+  must return nothing (external-URL acceptance check).
+- `test ! -e node_modules && test ! -e package-lock.json` and a check for absent bundler
+  configs (no `webpack.config.*`, `vite.config.*`, `rollup.config.*`, `.babelrc`).
+
+**Implementer aid:** add a clearly-commented `FAST_MODE` constant (e.g. durations in
+seconds) used only during manual verification, then set it back to the real
+25/5/15-minute values before finishing — and confirm the final values in the verification
+pass. Do not ship a debug toggle.
+
+## Risk & Sequencing
+
+- **Step order:** 1→2→3 establish structure/markup/state before behavior; 4 adds the
+  ticker/transitions that depend on the state shape from 3; 5 adds cues that depend on the
+  `completeInterval` hook from 4; 6 verifies; 7 is the final quality gate. Steps 1 and 2
+  are independent of each other; 3 depends on 1's element IDs/selectors.
+- **Risk: `file://` breakage** if anyone reaches for ES modules or a fetch. *Mitigation:*
+  ADR 1 + classic `<script defer>`; verify by actually opening via `file://` in step 6.
+- **Risk: timer drift / double tickers.** *Mitigation:* wall-clock recompute (ADR 2) and a
+  single `tickId` guarded by always stopping before starting.
+- **Risk: audio autoplay policy** suppresses the beep. *Mitigation:* unlock `AudioContext`
+  on first gesture and make the visual cue independent of audio success; tested explicitly.
+- **Risk: long-break cadence off-by-one** at the cycle wrap. *Mitigation:* reset
+  `workSinceLongBreak` when the long break is selected, only count completed (not skipped)
+  work, and cover with the dedicated cadence + wrap test scenario.
+- **Risk: quality gate pulls in a dependency.** *Mitigation:* use `npx --yes` one-off or
+  `node --check`; never create `node_modules` or runtime deps (acceptance criterion).
diff --git a/specs/2026-05-30-pomodoro-app.md b/specs/2026-05-30-pomodoro-app.md
new file mode 100644
index 0000000..2468d3c
--- /dev/null
+++ b/specs/2026-05-30-pomodoro-app.md
@@ -0,0 +1,172 @@
+---
+title: Pomodoro timer web app (zero-dependency, vanilla)
+date: 2026-05-30
+status: Delivered       # Draft | Ratified | Delivered
+---
+
+# 2026-05-30 — Pomodoro timer web app (zero-dependency, vanilla)
+
+## Objective
+A user practicing the Pomodoro Technique needs a simple, reliable timer that
+alternates focused work intervals with short and long breaks, so they can manage
+attention without reaching for a paid app or installing anything. The deliverable is a
+self-contained web app built with vanilla HTML/CSS/JS that runs by opening a single file
+(or serving it statically), with **zero build tooling and zero runtime dependencies** —
+no npm packages, no bundlers, no external libraries, fonts, or CDNs.
+
+## User stories
+- As a focused worker, I want to start a 25-minute work timer so that I can commit to a
+  single block of concentrated effort.
+- As a user, I want the timer to automatically guide me through work → short break →
+  work → … → long break cycles so that I follow the technique without tracking counts
+  myself.
+- As a user, I want to pause, resume, and reset the current interval so that I can handle
+  interruptions.
+- As a user, I want a clear visual and audible signal when an interval ends so that I
+  know to switch between work and break without staring at the screen.
+- As a user, I want to skip the current interval so that I can move on early when needed.
+- As a user, I want the app to open and work with no installation, no internet, and no
+  build step so that I can use it anywhere, including offline.
+
+## Functional requirements
+1. The app MUST present three interval types: **Work**, **Short Break**, and **Long
+   Break**, with fixed durations of 25, 5, and 15 minutes respectively. There is no
+   settings UI to change durations or cadence. `[ASSUMPTION | accepted-by-user]` fixed
+   25/5/15 defaults, no customization in v1.
+2. The app MUST display the remaining time of the current interval as `MM:SS`, counting
+   down once per second.
+3. The app MUST provide a **Start** control that begins the countdown of the current
+   interval, a **Pause** control that halts it while preserving remaining time, and a
+   **Resume** control (which MAY be the same toggle as Start/Pause) that continues from
+   the preserved time.
+4. The app MUST provide a **Reset** control that returns the current interval to its full
+   duration without advancing the cycle.
+5. The app MUST provide a **Skip** control that ends the current interval immediately and
+   advances to the next interval in the cycle.
+6. The app MUST automatically advance through the Pomodoro cycle: after each completed
+   Work interval, a break begins; after every **4th** completed Work interval, the break
+   is a Long Break instead of a Short Break; after any break, a Work interval begins.
+   `[ASSUMPTION | accepted-by-user]` long-break cadence = every 4 completed work intervals.
+7. The app MUST visually indicate the current interval type (e.g., a label and/or color
+   change) so the user can tell Work from Break at a glance.
+8. The app MUST signal the end of every interval with both an audible cue and a visual
+   change. The audible cue MUST be a short synthesized beep generated in-browser via the
+   Web Audio API (no external or embedded audio asset). `[ASSUMPTION | accepted-by-user]`
+   synthesized Web Audio beep plus visual cue.
+9. The app MUST display a count of completed Work intervals (Pomodoros) for the current
+   session.
+10. When an interval's countdown reaches `00:00`, the app MUST register that interval as
+    completed and transition to the next interval per requirement 6.
+11. After an interval ends, the next interval does NOT auto-start; it loads ready and
+    waits for the user to press Start. `[ASSUMPTION | accepted-by-user]` wait for Start, no
+    auto-start.
+12. The app MUST run entirely client-side from static assets with no network requests at
+    runtime (no CDN, web font, analytics, or API calls).
+13. The app MUST NOT persist any state. Session state (completed-Pomodoro count, current
+    interval, remaining time) resets when the page is reloaded or closed. No `localStorage`
+    or other storage is used. `[ASSUMPTION | accepted-by-user]` no persistence; resets on
+    reload.
+14. The app MUST NOT use the browser Notification API. End-of-interval alerts are delivered
+    only as in-page visual and audio cues. `[ASSUMPTION | accepted-by-user]` in-page cues
+    only, no Notification API / permission prompt.
+
+## Edge cases
+- Pressing Start when already running, or Pause when already paused, MUST be a no-op (no
+  double-speed countdown, no negative time).
+- Reset while running MUST stop the countdown and restore the full duration.
+- Skip on the final state of the cycle MUST wrap correctly back into the cycle (e.g.,
+  Long Break → Work, resetting the toward-long-break counter appropriately).
+- Skipping a Work interval MUST NOT increment the completed-Pomodoro count; only a Work
+  interval that reaches `00:00` counts as a completed Pomodoro.
+  `[ASSUMPTION | accepted-by-user]` skipping a Work interval does not count as completed.
+- The timer MUST remain accurate (no cumulative drift) even if the browser throttles
+  background tabs; elapsed time SHOULD be derived from a wall-clock reference rather than
+  by assuming each tick is exactly 1000 ms.
+- Rapid repeated clicks on any control MUST NOT corrupt state (e.g., spawn multiple
+  concurrent timers).
+- `00:00` MUST never display as negative or roll past zero.
+- Browsers that block autoplaying audio until a user gesture MUST still function; the
+  visual cue MUST always fire even if the audio cue is suppressed by the browser.
+
+## Acceptance criteria
+- **Given** the app is freshly opened, **when** it loads, **then** it displays `25:00`,
+  a "Work" indicator, a completed-Pomodoro count of 0, and is in a stopped/ready state.
+- **Given** a ready Work interval, **when** the user presses Start, **then** the display
+  counts down once per second from `25:00`.
+- **Given** a running interval, **when** the user presses Pause, **then** the countdown
+  stops and the displayed time stops changing; **when** the user presses Resume,
+  **then** the countdown continues from the preserved time.
+- **Given** a running interval, **when** the user presses Reset, **then** the display
+  returns to the interval's full duration and the timer is stopped, and the
+  completed-Pomodoro count is unchanged.
+- **Given** a running Work interval, **when** the user presses Skip, **then** the app
+  advances to a Short Break (or Long Break if it was the 4th work interval) without
+  incrementing the completed-Pomodoro count.
+- **Given** a Work interval reaches `00:00`, **when** it completes, **then** the
+  completed-Pomodoro count increments by 1, an audible synthesized beep and a visual
+  end-of-interval cue fire, and the next interval (Short or Long Break per the cycle) is
+  loaded in a ready (not auto-started) state.
+- **Given** 3 Work intervals have completed in the session, **when** the 4th Work
+  interval completes, **then** the next interval loaded is a Long Break (15:00).
+- **Given** any interval has ended and the next is loaded, **when** no Start is pressed,
+  **then** the next interval remains paused at its full duration and does not count down.
+- **Given** the app is in any state, **when** the page is reloaded, **then** the app
+  returns to the fresh-open state (`25:00`, Work, count 0) with no restored session data.
+- **Given** the device has no network connection, **when** the user opens the app file,
+  **then** all functionality works with no failed network requests.
+- **Given** the app is opened directly via `file://`, **when** it loads, **then** all
+  functionality (timer, cycle advance, audio, visual cues) works without a static server.
+- **Given** the project directory, **when** inspected, **then** it contains no
+  `package.json` dependency tree, no bundler config, no `node_modules`, and no references
+  to external URLs (CDN/font/script/style).
+
+## Non-functional requirements
+- **Zero dependencies / zero build:** vanilla HTML, CSS, and JavaScript only. No npm
+  packages, bundlers (webpack/vite/rollup/esbuild), transpilers, CSS frameworks, icon
+  fonts, or CDN/external assets. The app MUST run by opening the HTML file directly via
+  `file://` and also when served by any static file server. `[ASSUMPTION | accepted-by-user]`
+  the `file://` open path is a hard requirement (rules out ES-module `import` across files,
+  which many browsers block under `file://`; JS MUST be inlined or loaded via classic
+  non-module `<script>`).
+- **Browser support:** current evergreen desktop browsers (latest Chrome, Firefox, Edge,
+  Safari). `[ASSUMPTION | LOW]` mobile/responsive support is desirable but not a hard
+  requirement.
+- **Accessibility:** controls MUST be keyboard-operable and have accessible names; the
+  countdown and interval-type changes SHOULD be announced to assistive tech (e.g., ARIA
+  live region); color MUST NOT be the sole signal of interval type.
+- **Timing accuracy:** displayed time MUST be accurate within ±1 second over a full
+  interval and MUST NOT drift cumulatively across a multi-interval session.
+- **Performance:** loads and is interactive effectively instantly (single small static
+  page); no perceptible CPU cost while idle.
+- **No telemetry / privacy:** the app MUST NOT make any outbound network request and MUST
+  NOT collect or transmit user data.
+
+## Assumptions & open questions
+All previously open questions have been resolved by the user via "accept all defaults."
+No open questions remain. The spec is `Ratified`.
+
+Resolved decisions (accepted by user):
+- `[ASSUMPTION | accepted-by-user]` **Customization:** fixed 25/5/15 durations, no
+  settings UI in v1.
+- `[ASSUMPTION | accepted-by-user]` **Persistence:** none; all session state resets on
+  reload/close (no `localStorage`).
+- `[ASSUMPTION | accepted-by-user]` **`file://` support:** opening the single HTML file via
+  `file://` is a hard requirement; no cross-file ES-module imports.
+- `[ASSUMPTION | accepted-by-user]` **Audio:** short synthesized beep via Web Audio API
+  plus a visual cue; no external/embedded audio asset.
+- `[ASSUMPTION | accepted-by-user]` **Auto-start:** the next interval waits for Start; it
+  does not auto-start.
+- `[ASSUMPTION | accepted-by-user]` **Long-break cadence:** Long Break occurs after every
+  4 completed Work intervals.
+- `[ASSUMPTION | accepted-by-user]` **Notifications:** in-page visual + audio cues only;
+  no browser Notification API / permission prompt.
+- `[ASSUMPTION | accepted-by-user]` **Skip semantics:** skipping a Work interval does NOT
+  count it as a completed Pomodoro.
+
+Remaining low-impact assumptions (unchanged, not requiring user decision):
+- `[ASSUMPTION | LOW]` Mobile/responsive support is desirable but not a hard requirement.
+- `[ASSUMPTION | LOW]` No light/dark theme toggle required; a single default theme is
+  acceptable for v1.
+- `[ASSUMPTION | LOW]` No multi-language / i18n requirement for v1 (English UI).
+- `[ASSUMPTION | LOW]` Page title (browser tab) reflecting remaining time is a
+  nice-to-have, not required.
diff --git a/styles.css b/styles.css
new file mode 100644
index 0000000..ae022ea
--- /dev/null
+++ b/styles.css
@@ -0,0 +1,145 @@
+/* System font stack — no external font fetch */
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+               Helvetica, Arial, sans-serif;
+  min-height: 100dvh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #f5f5f5;
+  color: #1a1a1a;
+  transition: background 0.3s;
+}
+
+/* ── Interval theming via data-interval attribute ───────────────────────────
+   Color is a supplementary signal; the text label in #interval-label is the
+   primary, color-independent indicator (accessibility requirement).         */
+.container[data-interval="work"] {
+  --accent: #c0392b;
+  --accent-light: #fadbd8;
+  --accent-dark: #922b21;
+}
+
+.container[data-interval="shortBreak"] {
+  --accent: #27ae60;
+  --accent-light: #d5f5e3;
+  --accent-dark: #1e8449;
+}
+
+.container[data-interval="longBreak"] {
+  --accent: #2980b9;
+  --accent-light: #d6eaf8;
+  --accent-dark: #1f618d;
+}
+
+/* ── Container ──────────────────────────────────────────────────────────── */
+.container {
+  background: #fff;
+  border-radius: 1rem;
+  padding: 2.5rem 3rem;
+  text-align: center;
+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.10);
+  max-width: 420px;
+  width: 90%;
+  border-top: 6px solid var(--accent, #c0392b);
+  transition: border-color 0.3s;
+}
+
+/* ── Interval label ─────────────────────────────────────────────────────── */
+.interval-label {
+  font-size: 1.1rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--accent, #c0392b);
+  margin-bottom: 0.75rem;
+  transition: color 0.3s;
+}
+
+/* ── Countdown display ──────────────────────────────────────────────────── */
+.countdown {
+  font-family: "Courier New", Courier, monospace;
+  font-size: clamp(3.5rem, 15vw, 6rem);
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  color: #1a1a1a;
+  margin: 0.25rem 0 1.25rem;
+  line-height: 1;
+}
+
+/* ── Completed pomodoro count ───────────────────────────────────────────── */
+.pomodoro-count {
+  font-size: 0.9rem;
+  color: #555;
+  margin-bottom: 1.75rem;
+}
+
+.pomodoro-count span {
+  font-weight: 700;
+  color: var(--accent, #c0392b);
+}
+
+/* ── Controls ───────────────────────────────────────────────────────────── */
+.controls {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+button {
+  padding: 0.6rem 1.4rem;
+  border: 2px solid var(--accent, #c0392b);
+  border-radius: 0.5rem;
+  background: transparent;
+  color: var(--accent, #c0392b);
+  font-size: 0.95rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s, color 0.15s, border-color 0.3s;
+  min-width: 80px;
+}
+
+button:hover {
+  background: var(--accent, #c0392b);
+  color: #fff;
+}
+
+/* Primary toggle inherits full-fill style while running */
+#btn-toggle[aria-pressed="true"] {
+  background: var(--accent, #c0392b);
+  color: #fff;
+}
+
+/* Visible focus ring — keyboard navigation requirement */
+button:focus-visible {
+  outline: 3px solid var(--accent-dark, #922b21);
+  outline-offset: 3px;
+}
+
+/* ── End-of-interval visual flash ───────────────────────────────────────── */
+@keyframes flash-bg {
+  0%   { background: var(--accent-light, #fadbd8); }
+  50%  { background: var(--accent-light, #fadbd8); }
+  100% { background: #fff; }
+}
+
+.container.flash {
+  animation: flash-bg 0.8s ease-out forwards;
+}
+
+/* ── Screen-reader-only utility ─────────────────────────────────────────── */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}