From 3811791daad098271d2005831c3953f15295bd68 Mon Sep 17 00:00:00 2001
From: marcosgilf <marcosenrique.gil@ingka.ikea.com>
Date: Fri, 14 Aug 2026 17:56:00 +0200
Subject: [PATCH 1/4] feat(pwa): prompt before activating updates

---
 README.md                     |   5 +-
 astro.config.mjs              |   2 +-
 docs/spec.md                  |  23 +++++-
 src/client/pwa-update.test.ts | 149 ++++++++++++++++++++++++++++++++++
 src/client/pwa-update.ts      |  69 ++++++++++++++++
 src/env.d.ts                  |   1 +
 src/layouts/AppLayout.astro   |  26 +++++-
 src/pages/down.astro          |   7 +-
 src/pages/index.astro         |   7 +-
 src/styles/app.css            |  18 ++++
 10 files changed, 294 insertions(+), 13 deletions(-)
 create mode 100644 src/client/pwa-update.test.ts
 create mode 100644 src/client/pwa-update.ts

diff --git a/README.md b/README.md
index 577c48c..23aa20d 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,10 @@ is a Tabata whether or not anything is labelled "Tabata".
 - **Accurate by construction** — state is derived from a wall-clock timestamp with a pure
   `phaseAt(elapsed, routine)`; nothing accumulates ticks, so nothing drifts.
 - **Offline-first** — precached service worker, no backend, no accounts, no analytics. Installable as
-  **Timer**; updates are picked up on page reload, not via a modal prompt.
+  **Timer**; waiting updates stay pending until user activates **Reload to update**.
+- **Prompted updates** — the native update button appears on every page, including standalone display.
+  Running or paused Routines require one leave confirmation; Cancel keeps current version and Routine.
+  No update ever reloads automatically.
 - **Progressive enhancement** — audio session, Wake Lock and vibration are feature-detected and no-ops
   where absent. The app is fully correct without any of them.
 - **Semantic and accessible** — [Pico CSS](https://picocss.com/) classless, WCAG 2.2 AA in every slice.
diff --git a/astro.config.mjs b/astro.config.mjs
index 2035987..fd86400 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -6,7 +6,7 @@ import { defineConfig } from "astro/config";
 export default defineConfig({
   integrations: [
     AstroPWA({
-      registerType: "autoUpdate",
+      registerType: "prompt",
       manifest: {
         name: "Timer",
         short_name: "Timer",
diff --git a/docs/spec.md b/docs/spec.md
index 2c278c9..9f5a8a3 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -417,10 +417,26 @@ layer below is feature-detected, adds capability where present, and is a no-op w
   pnpm, or the build fails with `Rolldown failed to resolve import "workbox-window"`.
 - Add `/// <reference types="vite-plugin-pwa/client" />` to `src/env.d.ts` for the virtual-module types.
 - **`registerType: 'prompt'`, never `autoUpdate`** — an auto-reload mid-Routine would destroy the
-  running clock. The update prompt is a plain `.astro` component with a `<script>`.
+  running clock. The update control is plain Astro markup with a thin `<script>`.
 - Precache everything: the app is static with no API. Measured cost: 1.3 KB `sw.js` + 15 KB workbox
   (SW scope only), 1.27 KB gzip on the page.
 
+#### Update activation
+
+- Use `registerType: 'prompt'`, never `autoUpdate`. A waiting worker must not activate or reload while
+  someone is using a Routine.
+- Capture `updateSW` from `registerSW({ onNeedRefresh })`. Keep native **Reload to update** hidden until
+  `onNeedRefresh` fires; reveal it on every page, including standalone display mode. Keep it visible until
+  activation or page reload — never auto-dismiss it.
+- Clicking the button calls `updateSW(true)`. It is the only update activation path and reloads once into
+  the waiting version. No toast dependency, popover/polyfill, polling or custom service-worker manager.
+- A Routine is active when started and not Done. **Paused counts as active** because reload discards its
+  in-memory Clock. Active Routines get one native leave-confirmation decision before activation; Cancel
+  preserves current page, version and Routine, with button still visible. Idle and Done activate without
+  confirmation. The confirmed decision suppresses any second beforeunload prompt.
+- Registration errors are swallowed; update support must never affect timer behavior or offline use of the
+  current version.
+
 ### Install and manifest
 
 - Chromium installability requires `name`/`short_name`, **192px and 512px** icons, `start_url`,
@@ -578,8 +594,9 @@ Genuinely undecided. An implementer should raise these rather than assume.
   app is live at `timer.marcosgilf.com`.
 - **Default values for `Prefs`** — only `prepareMs` has a stated default (10s). Starting `muted`,
   `volume`, `ticks` and `vibrate` values are unspecified.
-- ~~**Update-prompt UI**~~ — resolved: no prompt. The service worker auto-updates and the new build
-  is picked up on page reload, so timing is never interrupted.
+- ~~**Update-prompt UI**~~ — resolved: a native **Reload to update** button appears when a worker waits.
+  Activation is user-controlled; running and paused Routines require one leave confirmation, while idle
+  and Done activate without confirmation. No automatic reload.
 - **Install guidance copy for iOS** — decided that it must be static copy (no
   `beforeinstallprompt`), but not what it says or which screen hosts it.
 - ~~**App name, iconography, favicon/manifest icon set, `theme_color`**~~ — resolved: app name
diff --git a/src/client/pwa-update.test.ts b/src/client/pwa-update.test.ts
new file mode 100644
index 0000000..e083f40
--- /dev/null
+++ b/src/client/pwa-update.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPwaUpdateController, type RegisterSW } from "./pwa-update.ts";
+
+const createHarness = () => {
+  let routineActive = false;
+  let onNeedRefresh = () => {};
+  const updateSW = vi.fn<ReturnType<RegisterSW>>();
+  updateSW.mockResolvedValue(undefined);
+  const registerSW = vi.fn<RegisterSW>((options) => {
+    onNeedRefresh = options.onNeedRefresh;
+    return updateSW;
+  });
+  const confirmLeave = vi.fn(() => true);
+  const onUpdateReady = vi.fn();
+  const onActivationConfirmed = vi.fn();
+  const onActivationFailed = vi.fn();
+  const controller = createPwaUpdateController({
+    registerSW,
+    isRoutineActive: () => routineActive,
+    confirmLeave,
+    onUpdateReady,
+    onActivationConfirmed,
+    onActivationFailed,
+  });
+
+  return {
+    controller,
+    get onNeedRefresh() {
+      return onNeedRefresh;
+    },
+    updateSW,
+    confirmLeave,
+    onUpdateReady,
+    onActivationConfirmed,
+    onActivationFailed,
+    setRoutineActive: (active: boolean) => {
+      routineActive = active;
+    },
+  };
+};
+
+describe("PWA update controller", () => {
+  it("starts current and becomes ready only when service worker needs refresh", () => {
+    const harness = createHarness();
+
+    expect(harness.controller.ready).toBe(false);
+    harness.controller.register();
+    expect(harness.controller.ready).toBe(false);
+
+    harness.onNeedRefresh();
+
+    expect(harness.controller.ready).toBe(true);
+    expect(harness.onUpdateReady).toHaveBeenCalledOnce();
+  });
+
+  it("activates ready update immediately when no Routine is active", async () => {
+    const harness = createHarness();
+    harness.controller.register();
+    harness.onNeedRefresh();
+
+    await expect(harness.controller.activate()).resolves.toBe(true);
+
+    expect(harness.confirmLeave).not.toHaveBeenCalled();
+    expect(harness.onActivationConfirmed).not.toHaveBeenCalled();
+    expect(harness.updateSW).toHaveBeenCalledOnce();
+    expect(harness.updateSW).toHaveBeenCalledWith(true);
+  });
+
+  it("keeps update ready and current Routine when active user cancels", async () => {
+    const harness = createHarness();
+    harness.setRoutineActive(true);
+    harness.confirmLeave.mockReturnValue(false);
+    harness.controller.register();
+    harness.onNeedRefresh();
+
+    await expect(harness.controller.activate()).resolves.toBe(false);
+
+    expect(harness.confirmLeave).toHaveBeenCalledOnce();
+    expect(harness.onActivationConfirmed).not.toHaveBeenCalled();
+    expect(harness.updateSW).not.toHaveBeenCalled();
+    expect(harness.controller.ready).toBe(true);
+  });
+
+  it("confirms active Routine once before activating waiting update", async () => {
+    const harness = createHarness();
+    harness.setRoutineActive(true);
+    harness.controller.register();
+    harness.onNeedRefresh();
+
+    await expect(harness.controller.activate()).resolves.toBe(true);
+
+    expect(harness.confirmLeave).toHaveBeenCalledOnce();
+    expect(harness.onActivationConfirmed).toHaveBeenCalledOnce();
+    expect(harness.updateSW).toHaveBeenCalledOnce();
+    expect(harness.updateSW).toHaveBeenCalledWith(true);
+  });
+
+  it("allows retry when waiting-version activation fails", async () => {
+    const harness = createHarness();
+    harness.updateSW.mockRejectedValueOnce(new Error("activation failed"));
+    harness.controller.register();
+    harness.onNeedRefresh();
+
+    await expect(harness.controller.activate()).resolves.toBe(false);
+    await expect(harness.controller.activate()).resolves.toBe(true);
+
+    expect(harness.onActivationFailed).toHaveBeenCalledOnce();
+    expect(harness.updateSW).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not activate twice while first activation is in flight", async () => {
+    const harness = createHarness();
+    let resolveUpdate = () => {};
+    harness.updateSW.mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveUpdate = resolve;
+        }),
+    );
+    harness.controller.register();
+    harness.onNeedRefresh();
+
+    const first = harness.controller.activate();
+    const second = harness.controller.activate();
+    resolveUpdate();
+
+    await expect(first).resolves.toBe(true);
+    await expect(second).resolves.toBe(false);
+    expect(harness.updateSW).toHaveBeenCalledOnce();
+  });
+
+  it("leaves timer behavior alone when registration fails", () => {
+    const onUpdateReady = vi.fn();
+    const registerSW = vi.fn(() => {
+      throw new Error("registration failed");
+    });
+    const controller = createPwaUpdateController({
+      registerSW,
+      isRoutineActive: () => true,
+      confirmLeave: vi.fn(),
+      onUpdateReady,
+      onActivationConfirmed: vi.fn(),
+    });
+
+    expect(() => controller.register()).not.toThrow();
+    expect(controller.ready).toBe(false);
+    expect(onUpdateReady).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/client/pwa-update.ts b/src/client/pwa-update.ts
new file mode 100644
index 0000000..ab6d1ea
--- /dev/null
+++ b/src/client/pwa-update.ts
@@ -0,0 +1,69 @@
+export type UpdateSW = (reloadPage?: boolean) => Promise<void>;
+
+export type RegisterSW = (options: {
+  onNeedRefresh: () => void;
+  onRegisterError: (error: unknown) => void;
+}) => UpdateSW;
+
+type PwaUpdateControllerOptions = {
+  registerSW: RegisterSW;
+  isRoutineActive: () => boolean;
+  confirmLeave: () => boolean;
+  onUpdateReady: () => void;
+  onActivationConfirmed: () => void;
+  onActivationFailed?: () => void;
+};
+
+export const createPwaUpdateController = ({
+  registerSW,
+  isRoutineActive,
+  confirmLeave,
+  onUpdateReady,
+  onActivationConfirmed,
+  onActivationFailed,
+}: PwaUpdateControllerOptions) => {
+  let updateSW: UpdateSW | null = null;
+  let updateReady = false;
+  let activationStarted = false;
+
+  const register = () => {
+    try {
+      updateSW = registerSW({
+        onNeedRefresh: () => {
+          updateReady = true;
+          onUpdateReady();
+        },
+        onRegisterError: () => {},
+      });
+    } catch {
+      // Service-worker support is an enhancement. Timer behavior stays independent.
+    }
+  };
+
+  const activate = async (): Promise<boolean> => {
+    if (!updateReady || !updateSW || activationStarted) return false;
+
+    const routineActive = isRoutineActive();
+    if (routineActive && !confirmLeave()) return false;
+
+    activationStarted = true;
+
+    try {
+      if (routineActive) onActivationConfirmed();
+      await updateSW(true);
+      return true;
+    } catch {
+      activationStarted = false;
+      onActivationFailed?.();
+      return false;
+    }
+  };
+
+  return {
+    register,
+    activate,
+    get ready() {
+      return updateReady;
+    },
+  };
+};
diff --git a/src/env.d.ts b/src/env.d.ts
index 7bfa427..ea29537 100644
--- a/src/env.d.ts
+++ b/src/env.d.ts
@@ -4,5 +4,6 @@ declare module "virtual:pwa-register" {
   export function registerSW(options?: {
     onNeedRefresh?: () => void;
     onOfflineReady?: () => void;
+    onRegisterError?: (error: unknown) => void;
   }): (reloadPage?: boolean) => Promise<void>;
 }
diff --git a/src/layouts/AppLayout.astro b/src/layouts/AppLayout.astro
index 38039e1..40add22 100644
--- a/src/layouts/AppLayout.astro
+++ b/src/layouts/AppLayout.astro
@@ -35,8 +35,9 @@ const deployLabel =
     <link rel="manifest" href="/manifest.webmanifest" />
     <title>{title}</title>
   </head>
-  <body>
+  <body data-routine-active="false">
     <slot />
+    <button type="button" class="update-control" data-update-control hidden>Reload to update</button>
     <footer class="app-footer">
       {deployLabel && <small class="deploy-clue" aria-label={`Deployment context ${deployLabel}`}>{deployLabel}</small>}
       <small class="app-version" aria-label={`Timer version ${version}`}>v{version}</small>
@@ -44,8 +45,29 @@ const deployLabel =
 
     <script>
       import { registerSW } from "virtual:pwa-register";
+      import { createPwaUpdateController, type RegisterSW } from "../client/pwa-update.ts";
 
-      registerSW();
+      const updateControl = document.querySelector<HTMLButtonElement>("[data-update-control]")!;
+      const registerServiceWorker: RegisterSW = (options) => registerSW(options);
+      const update = createPwaUpdateController({
+        registerSW: registerServiceWorker,
+        isRoutineActive: () => document.body.dataset.routineActive === "true",
+        confirmLeave: () => window.confirm("Leave the active Routine and reload?"),
+        onUpdateReady: () => {
+          updateControl.hidden = false;
+        },
+        onActivationConfirmed: () => {
+          document.body.dataset.navigationConfirmed = "true";
+        },
+        onActivationFailed: () => {
+          delete document.body.dataset.navigationConfirmed;
+        },
+      });
+
+      updateControl.addEventListener("click", () => {
+        void update.activate();
+      });
+      update.register();
     </script>
   </body>
 </html>
diff --git a/src/pages/down.astro b/src/pages/down.astro
index d93c520..c3f03b9 100644
--- a/src/pages/down.astro
+++ b/src/pages/down.astro
@@ -111,6 +111,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     configuredDuration.textContent = formatElapsed(durationMs);
     configuredDuration.dateTime = `PT${durationMs / 1000}S`;
     const status = isFinished ? "Done" : isRunning(clock) ? "Running" : clock.startedAt === null ? "" : "Paused";
+    document.body.dataset.routineActive = String(!isFinished && clock.startedAt !== null);
     const nextTitle = status ? `${status} · ${visible} - Down Timer` : `${visible} - Down Timer`;
     if (nextTitle !== pageTitle) {
       pageTitle = nextTitle;
@@ -226,8 +227,8 @@ import AppLayout from "../layouts/AppLayout.astro";
   let confirmedNavigation = false;
   document.querySelectorAll<HTMLAnchorElement>("a[href]").forEach((link) => {
     link.addEventListener("click", (event) => {
-      if (!isRunning(clock) || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-      if (!window.confirm("Leave the running Routine?")) {
+      if (document.body.dataset.routineActive !== "true" || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      if (!window.confirm("Leave the active Routine?")) {
         event.preventDefault();
         return;
       }
@@ -237,7 +238,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   });
 
   window.addEventListener("beforeunload", (event) => {
-    if (!isRunning(clock) || confirmedNavigation) return;
+    if (document.body.dataset.routineActive !== "true" || confirmedNavigation || document.body.dataset.navigationConfirmed === "true") return;
     event.preventDefault();
   });
 
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 42d4f84..7d98fbf 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -99,6 +99,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     display.dateTime = `PT${state.displayMs / 1000}S`;
     display.setAttribute("aria-label", announceElapsed(state.displayMs));
     const status = isFinished ? "Done" : isRunning(clock) ? "Running" : clock.startedAt === null ? "" : "Paused";
+    document.body.dataset.routineActive = String(!isFinished && clock.startedAt !== null);
     const nextTitle = status ? `${status} · ${visible} - Timer` : `${visible} - Timer`;
     if (nextTitle !== pageTitle) {
       pageTitle = nextTitle;
@@ -209,8 +210,8 @@ import AppLayout from "../layouts/AppLayout.astro";
   let confirmedNavigation = false;
   document.querySelectorAll<HTMLAnchorElement>("a[href]").forEach((link) => {
     link.addEventListener("click", (event) => {
-      if (!isRunning(clock) || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-      if (!window.confirm("Leave the running Routine?")) {
+      if (document.body.dataset.routineActive !== "true" || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      if (!window.confirm("Leave the active Routine?")) {
         event.preventDefault();
         return;
       }
@@ -220,7 +221,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   });
 
   window.addEventListener("beforeunload", (event) => {
-    if (!isRunning(clock) || confirmedNavigation) return;
+    if (document.body.dataset.routineActive !== "true" || confirmedNavigation || document.body.dataset.navigationConfirmed === "true") return;
     event.preventDefault();
   });
 
diff --git a/src/styles/app.css b/src/styles/app.css
index a8cd3b3..ee1bd2a 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -23,6 +23,7 @@ body > main {
   width: 100%;
   max-width: none;
   padding: 1rem max(0.5rem, env(safe-area-inset-left)) 1rem max(0.5rem, env(safe-area-inset-right));
+  padding-bottom: calc(7rem + env(safe-area-inset-bottom));
   overflow-x: hidden;
   text-align: center;
 }
@@ -228,6 +229,23 @@ body > main {
   font-variant-numeric: tabular-nums;
 }
 
+.update-control {
+  position: fixed;
+  z-index: 2;
+  inset-inline: max(0.5rem, env(safe-area-inset-left)) max(0.5rem, env(safe-area-inset-right));
+  bottom: calc(3rem + env(safe-area-inset-bottom));
+  width: fit-content;
+  max-width: 100%;
+  margin: 0 auto;
+  padding-inline: 0.75rem;
+  white-space: normal;
+}
+
+.update-control:focus-visible {
+  outline: 3px solid var(--pico-primary);
+  outline-offset: 3px;
+}
+
 .app-footer {
   display: flex;
   align-items: center;

From 2d9cb85eaf01a68fa151ec233fca155a1c2c2ea9 Mon Sep 17 00:00:00 2001
From: marcosgilf <marcosenrique.gil@ingka.ikea.com>
Date: Fri, 14 Aug 2026 21:38:37 +0200
Subject: [PATCH 2/4] feat(pwa): activate updates on counter start

---
 README.md                     |  7 +++--
 docs/spec.md                  | 37 +++++++++++++------------
 src/client/pwa-update.test.ts | 51 +++++++----------------------------
 src/client/pwa-update.ts      | 45 +++++++++++++------------------
 src/layouts/AppLayout.astro   | 41 +++++++++++++++++++---------
 src/pages/down.astro          |  3 ++-
 src/pages/index.astro         |  3 ++-
 src/styles/app.css            | 25 +++++------------
 8 files changed, 88 insertions(+), 124 deletions(-)

diff --git a/README.md b/README.md
index 23aa20d..b14c253 100644
--- a/README.md
+++ b/README.md
@@ -26,10 +26,9 @@ is a Tabata whether or not anything is labelled "Tabata".
 - **Accurate by construction** — state is derived from a wall-clock timestamp with a pure
   `phaseAt(elapsed, routine)`; nothing accumulates ticks, so nothing drifts.
 - **Offline-first** — precached service worker, no backend, no accounts, no analytics. Installable as
-  **Timer**; waiting updates stay pending until user activates **Reload to update**.
-- **Prompted updates** — the native update button appears on every page, including standalone display.
-  Running or paused Routines require one leave confirmation; Cancel keeps current version and Routine.
-  No update ever reloads automatically.
+  **Timer**; waiting updates stay pending until a counter activates them.
+- **Automatic updates** — starting or restarting any counter activates a waiting worker and reloads into
+  the new build. The bottom version shows green **NEW vx.x.x** for the current app session.
 - **Progressive enhancement** — audio session, Wake Lock and vibration are feature-detected and no-ops
   where absent. The app is fully correct without any of them.
 - **Semantic and accessible** — [Pico CSS](https://picocss.com/) classless, WCAG 2.2 AA in every slice.
diff --git a/docs/spec.md b/docs/spec.md
index 9f5a8a3..3a43834 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -328,7 +328,7 @@ No theme override — `prefers-color-scheme` only, and nothing is stored for it.
 
 The whole prototype is one `.astro` file: plain DOM, CSS custom properties, `rAF`, native
 `<input inputmode="numeric">`. Nothing in the UI justifies an island, and nothing in the PWA layer
-does either — registration, update prompt, Wake Lock, audio session and haptics are all plain DOM APIs.
+does either — registration, update activation, Wake Lock, audio session and haptics are all plain DOM APIs.
 
 ---
 
@@ -416,26 +416,26 @@ layer below is feature-detected, adds capability where present, and is a no-op w
   `virtual:pwa-register` by hand; (2) **`workbox-window` must be an explicit devDependency** under
   pnpm, or the build fails with `Rolldown failed to resolve import "workbox-window"`.
 - Add `/// <reference types="vite-plugin-pwa/client" />` to `src/env.d.ts` for the virtual-module types.
-- **`registerType: 'prompt'`, never `autoUpdate`** — an auto-reload mid-Routine would destroy the
-  running clock. The update control is plain Astro markup with a thin `<script>`.
+- **`registerType: 'prompt'`, never `autoUpdate`** — hold a waiting worker until a counter activates it.
+  The activation path is a thin Astro script around the service-worker registration wrapper.
 - Precache everything: the app is static with no API. Measured cost: 1.3 KB `sw.js` + 15 KB workbox
   (SW scope only), 1.27 KB gzip on the page.
 
 #### Update activation
 
-- Use `registerType: 'prompt'`, never `autoUpdate`. A waiting worker must not activate or reload while
-  someone is using a Routine.
-- Capture `updateSW` from `registerSW({ onNeedRefresh })`. Keep native **Reload to update** hidden until
-  `onNeedRefresh` fires; reveal it on every page, including standalone display mode. Keep it visible until
-  activation or page reload — never auto-dismiss it.
-- Clicking the button calls `updateSW(true)`. It is the only update activation path and reloads once into
-  the waiting version. No toast dependency, popover/polyfill, polling or custom service-worker manager.
-- A Routine is active when started and not Done. **Paused counts as active** because reload discards its
-  in-memory Clock. Active Routines get one native leave-confirmation decision before activation; Cancel
-  preserves current page, version and Routine, with button still visible. Idle and Done activate without
-  confirmation. The confirmed decision suppresses any second beforeunload prompt.
-- Registration errors are swallowed; update support must never affect timer behavior or offline use of the
-  current version.
+- Use `registerType: 'prompt'`, never `autoUpdate`. Capture `updateSW` from
+  `registerSW({ onNeedRefresh })`; a waiting worker stays idle until counter activation.
+- Every counter start path — count-up, count down, and restart — emits one activation event. If a worker
+  waits, the event calls `updateSW(true)` and reloads automatically into the waiting version. If the
+  readiness callback arrives just after the event, activation starts as soon as it is ready. Pause and
+  resume do not emit activation events.
+- No update button, confirmation prompt, toast dependency, popover/polyfill, polling or custom
+  service-worker manager. Automatic reload is intentional and may discard a newly started in-memory
+  Clock; the next page starts with the new build.
+- Before activation, store a session marker. The new build prefixes the bottom version with green
+  **NEW vX.X.X** for the current app session. Clear the marker only when activation fails. Version
+  highlighting is optional; storage failures do not block update activation or timer behavior.
+- Registration errors are swallowed; offline use of the current version remains unaffected.
 
 ### Install and manifest
 
@@ -594,9 +594,8 @@ Genuinely undecided. An implementer should raise these rather than assume.
   app is live at `timer.marcosgilf.com`.
 - **Default values for `Prefs`** — only `prepareMs` has a stated default (10s). Starting `muted`,
   `volume`, `ticks` and `vibrate` values are unspecified.
-- ~~**Update-prompt UI**~~ — resolved: a native **Reload to update** button appears when a worker waits.
-  Activation is user-controlled; running and paused Routines require one leave confirmation, while idle
-  and Done activate without confirmation. No automatic reload.
+- ~~**Update-prompt UI**~~ — resolved: no update control. A waiting worker activates and reloads when any
+  counter starts or restarts; the new build labels its bottom version **NEW vX.X.X** in green for current app session.
 - **Install guidance copy for iOS** — decided that it must be static copy (no
   `beforeinstallprompt`), but not what it says or which screen hosts it.
 - ~~**App name, iconography, favicon/manifest icon set, `theme_color`**~~ — resolved: app name
diff --git a/src/client/pwa-update.test.ts b/src/client/pwa-update.test.ts
index e083f40..302d67c 100644
--- a/src/client/pwa-update.test.ts
+++ b/src/client/pwa-update.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, it, vi } from "vitest";
 import { createPwaUpdateController, type RegisterSW } from "./pwa-update.ts";
 
 const createHarness = () => {
-  let routineActive = false;
   let onNeedRefresh = () => {};
   const updateSW = vi.fn<ReturnType<RegisterSW>>();
   updateSW.mockResolvedValue(undefined);
@@ -10,16 +9,11 @@ const createHarness = () => {
     onNeedRefresh = options.onNeedRefresh;
     return updateSW;
   });
-  const confirmLeave = vi.fn(() => true);
-  const onUpdateReady = vi.fn();
-  const onActivationConfirmed = vi.fn();
+  const onActivationStarted = vi.fn();
   const onActivationFailed = vi.fn();
   const controller = createPwaUpdateController({
     registerSW,
-    isRoutineActive: () => routineActive,
-    confirmLeave,
-    onUpdateReady,
-    onActivationConfirmed,
+    onActivationStarted,
     onActivationFailed,
   });
 
@@ -29,13 +23,8 @@ const createHarness = () => {
       return onNeedRefresh;
     },
     updateSW,
-    confirmLeave,
-    onUpdateReady,
-    onActivationConfirmed,
+    onActivationStarted,
     onActivationFailed,
-    setRoutineActive: (active: boolean) => {
-      routineActive = active;
-    },
   };
 };
 
@@ -50,49 +39,32 @@ describe("PWA update controller", () => {
     harness.onNeedRefresh();
 
     expect(harness.controller.ready).toBe(true);
-    expect(harness.onUpdateReady).toHaveBeenCalledOnce();
+    expect(harness.updateSW).not.toHaveBeenCalled();
   });
 
-  it("activates ready update immediately when no Routine is active", async () => {
+  it("activates ready update automatically when a counter starts", async () => {
     const harness = createHarness();
     harness.controller.register();
     harness.onNeedRefresh();
 
     await expect(harness.controller.activate()).resolves.toBe(true);
 
-    expect(harness.confirmLeave).not.toHaveBeenCalled();
-    expect(harness.onActivationConfirmed).not.toHaveBeenCalled();
+    expect(harness.onActivationStarted).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledWith(true);
   });
 
-  it("keeps update ready and current Routine when active user cancels", async () => {
+  it("waits for update readiness when counter starts first", async () => {
     const harness = createHarness();
-    harness.setRoutineActive(true);
-    harness.confirmLeave.mockReturnValue(false);
     harness.controller.register();
-    harness.onNeedRefresh();
 
     await expect(harness.controller.activate()).resolves.toBe(false);
-
-    expect(harness.confirmLeave).toHaveBeenCalledOnce();
-    expect(harness.onActivationConfirmed).not.toHaveBeenCalled();
     expect(harness.updateSW).not.toHaveBeenCalled();
-    expect(harness.controller.ready).toBe(true);
-  });
 
-  it("confirms active Routine once before activating waiting update", async () => {
-    const harness = createHarness();
-    harness.setRoutineActive(true);
-    harness.controller.register();
     harness.onNeedRefresh();
 
-    await expect(harness.controller.activate()).resolves.toBe(true);
-
-    expect(harness.confirmLeave).toHaveBeenCalledOnce();
-    expect(harness.onActivationConfirmed).toHaveBeenCalledOnce();
+    expect(harness.onActivationStarted).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledOnce();
-    expect(harness.updateSW).toHaveBeenCalledWith(true);
   });
 
   it("allows retry when waiting-version activation fails", async () => {
@@ -130,20 +102,15 @@ describe("PWA update controller", () => {
   });
 
   it("leaves timer behavior alone when registration fails", () => {
-    const onUpdateReady = vi.fn();
     const registerSW = vi.fn(() => {
       throw new Error("registration failed");
     });
     const controller = createPwaUpdateController({
       registerSW,
-      isRoutineActive: () => true,
-      confirmLeave: vi.fn(),
-      onUpdateReady,
-      onActivationConfirmed: vi.fn(),
+      onActivationStarted: vi.fn(),
     });
 
     expect(() => controller.register()).not.toThrow();
     expect(controller.ready).toBe(false);
-    expect(onUpdateReady).not.toHaveBeenCalled();
   });
 });
diff --git a/src/client/pwa-update.ts b/src/client/pwa-update.ts
index ab6d1ea..a46ecf2 100644
--- a/src/client/pwa-update.ts
+++ b/src/client/pwa-update.ts
@@ -7,49 +7,28 @@ export type RegisterSW = (options: {
 
 type PwaUpdateControllerOptions = {
   registerSW: RegisterSW;
-  isRoutineActive: () => boolean;
-  confirmLeave: () => boolean;
-  onUpdateReady: () => void;
-  onActivationConfirmed: () => void;
+  onActivationStarted: () => void;
   onActivationFailed?: () => void;
 };
 
 export const createPwaUpdateController = ({
   registerSW,
-  isRoutineActive,
-  confirmLeave,
-  onUpdateReady,
-  onActivationConfirmed,
+  onActivationStarted,
   onActivationFailed,
 }: PwaUpdateControllerOptions) => {
   let updateSW: UpdateSW | null = null;
   let updateReady = false;
+  let activationRequested = false;
   let activationStarted = false;
 
-  const register = () => {
-    try {
-      updateSW = registerSW({
-        onNeedRefresh: () => {
-          updateReady = true;
-          onUpdateReady();
-        },
-        onRegisterError: () => {},
-      });
-    } catch {
-      // Service-worker support is an enhancement. Timer behavior stays independent.
-    }
-  };
-
   const activate = async (): Promise<boolean> => {
+    activationRequested = true;
     if (!updateReady || !updateSW || activationStarted) return false;
 
-    const routineActive = isRoutineActive();
-    if (routineActive && !confirmLeave()) return false;
-
     activationStarted = true;
 
     try {
-      if (routineActive) onActivationConfirmed();
+      onActivationStarted();
       await updateSW(true);
       return true;
     } catch {
@@ -59,6 +38,20 @@ export const createPwaUpdateController = ({
     }
   };
 
+  const register = () => {
+    try {
+      updateSW = registerSW({
+        onNeedRefresh: () => {
+          updateReady = true;
+          if (activationRequested) void activate();
+        },
+        onRegisterError: () => {},
+      });
+    } catch {
+      // Service-worker support is an enhancement. Timer behavior stays independent.
+    }
+  };
+
   return {
     register,
     activate,
diff --git a/src/layouts/AppLayout.astro b/src/layouts/AppLayout.astro
index 40add22..145b2f4 100644
--- a/src/layouts/AppLayout.astro
+++ b/src/layouts/AppLayout.astro
@@ -35,36 +35,51 @@ const deployLabel =
     <link rel="manifest" href="/manifest.webmanifest" />
     <title>{title}</title>
   </head>
-  <body data-routine-active="false">
+  <body>
     <slot />
-    <button type="button" class="update-control" data-update-control hidden>Reload to update</button>
     <footer class="app-footer">
       {deployLabel && <small class="deploy-clue" aria-label={`Deployment context ${deployLabel}`}>{deployLabel}</small>}
-      <small class="app-version" aria-label={`Timer version ${version}`}>v{version}</small>
+      <small class="app-version" data-app-version aria-label={`Timer version ${version}`}>v{version}</small>
     </footer>
 
     <script>
       import { registerSW } from "virtual:pwa-register";
       import { createPwaUpdateController, type RegisterSW } from "../client/pwa-update.ts";
 
-      const updateControl = document.querySelector<HTMLButtonElement>("[data-update-control]")!;
+      const appVersion = document.querySelector<HTMLElement>("[data-app-version]")!;
+      const updateMarker = "timer:update-activated";
+
+      try {
+        if (sessionStorage.getItem(updateMarker) === "true") {
+          const versionLabel = appVersion.getAttribute("aria-label") ?? "Timer version";
+          appVersion.textContent = `NEW ${appVersion.textContent ?? ""}`;
+          appVersion.dataset.updated = "true";
+          appVersion.setAttribute("aria-label", `New ${versionLabel}`);
+        }
+      } catch {
+        // Version highlighting is optional. Timer behavior stays independent.
+      }
+
       const registerServiceWorker: RegisterSW = (options) => registerSW(options);
       const update = createPwaUpdateController({
         registerSW: registerServiceWorker,
-        isRoutineActive: () => document.body.dataset.routineActive === "true",
-        confirmLeave: () => window.confirm("Leave the active Routine and reload?"),
-        onUpdateReady: () => {
-          updateControl.hidden = false;
-        },
-        onActivationConfirmed: () => {
-          document.body.dataset.navigationConfirmed = "true";
+        onActivationStarted: () => {
+          try {
+            sessionStorage.setItem(updateMarker, "true");
+          } catch {
+            // Session storage is optional. Update activation still proceeds.
+          }
         },
         onActivationFailed: () => {
-          delete document.body.dataset.navigationConfirmed;
+          try {
+            sessionStorage.removeItem(updateMarker);
+          } catch {
+            // Session storage is optional. Timer behavior stays independent.
+          }
         },
       });
 
-      updateControl.addEventListener("click", () => {
+      window.addEventListener("timer:counter-activated", () => {
         void update.activate();
       });
       update.register();
diff --git a/src/pages/down.astro b/src/pages/down.astro
index c3f03b9..55697fa 100644
--- a/src/pages/down.astro
+++ b/src/pages/down.astro
@@ -154,6 +154,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   };
 
   const startRunning = () => {
+    window.dispatchEvent(new Event("timer:counter-activated"));
     isFinished = false;
     setUrlState("running");
     clock = start(reset(), Date.now());
@@ -238,7 +239,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   });
 
   window.addEventListener("beforeunload", (event) => {
-    if (document.body.dataset.routineActive !== "true" || confirmedNavigation || document.body.dataset.navigationConfirmed === "true") return;
+    if (document.body.dataset.routineActive !== "true" || confirmedNavigation) return;
     event.preventDefault();
   });
 
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 7d98fbf..b5a5b37 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -144,6 +144,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   };
 
   const startRunning = () => {
+    window.dispatchEvent(new Event("timer:counter-activated"));
     isFinished = false;
     setUrlState("running");
     clock = start(reset(), Date.now());
@@ -221,7 +222,7 @@ import AppLayout from "../layouts/AppLayout.astro";
   });
 
   window.addEventListener("beforeunload", (event) => {
-    if (document.body.dataset.routineActive !== "true" || confirmedNavigation || document.body.dataset.navigationConfirmed === "true") return;
+    if (document.body.dataset.routineActive !== "true" || confirmedNavigation) return;
     event.preventDefault();
   });
 
diff --git a/src/styles/app.css b/src/styles/app.css
index ee1bd2a..e05cc56 100644
--- a/src/styles/app.css
+++ b/src/styles/app.css
@@ -23,7 +23,7 @@ body > main {
   width: 100%;
   max-width: none;
   padding: 1rem max(0.5rem, env(safe-area-inset-left)) 1rem max(0.5rem, env(safe-area-inset-right));
-  padding-bottom: calc(7rem + env(safe-area-inset-bottom));
+  padding-bottom: calc(3rem + env(safe-area-inset-bottom));
   overflow-x: hidden;
   text-align: center;
 }
@@ -229,23 +229,6 @@ body > main {
   font-variant-numeric: tabular-nums;
 }
 
-.update-control {
-  position: fixed;
-  z-index: 2;
-  inset-inline: max(0.5rem, env(safe-area-inset-left)) max(0.5rem, env(safe-area-inset-right));
-  bottom: calc(3rem + env(safe-area-inset-bottom));
-  width: fit-content;
-  max-width: 100%;
-  margin: 0 auto;
-  padding-inline: 0.75rem;
-  white-space: normal;
-}
-
-.update-control:focus-visible {
-  outline: 3px solid var(--pico-primary);
-  outline-offset: 3px;
-}
-
 .app-footer {
   display: flex;
   align-items: center;
@@ -267,6 +250,12 @@ body > main {
   user-select: none;
 }
 
+.app-version[data-updated="true"] {
+  color: #39d353;
+  font-weight: 700;
+  opacity: 1;
+}
+
 .deploy-clue {
   letter-spacing: 0.08em;
   text-transform: uppercase;

From 0424764aad79d1b7c7ccc490832cd82930a316ea Mon Sep 17 00:00:00 2001
From: marcosgilf <marcosenrique.gil@ingka.ikea.com>
Date: Fri, 14 Aug 2026 22:56:06 +0200
Subject: [PATCH 3/4] fix(pwa): update immediately when idle

---
 README.md                     |  6 +++---
 docs/spec.md                  | 22 ++++++++++----------
 src/client/pwa-update.test.ts | 38 +++++++++++++++++++++--------------
 src/client/pwa-update.ts      |  8 ++++----
 src/layouts/AppLayout.astro   |  5 +++--
 src/pages/down.astro          |  3 ++-
 src/pages/index.astro         |  3 ++-
 7 files changed, 48 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index b14c253..9202523 100644
--- a/README.md
+++ b/README.md
@@ -26,9 +26,9 @@ is a Tabata whether or not anything is labelled "Tabata".
 - **Accurate by construction** — state is derived from a wall-clock timestamp with a pure
   `phaseAt(elapsed, routine)`; nothing accumulates ticks, so nothing drifts.
 - **Offline-first** — precached service worker, no backend, no accounts, no analytics. Installable as
-  **Timer**; waiting updates stay pending until a counter activates them.
-- **Automatic updates** — starting or restarting any counter activates a waiting worker and reloads into
-  the new build. The bottom version shows green **NEW vx.x.x** for the current app session.
+  **Timer**; waiting updates apply immediately when no Routine is active.
+- **Automatic updates** — an active or paused Routine defers a waiting worker until Done or Reset. The
+  new build reloads automatically, then the bottom version shows green **NEW vx.x.x** for the current app session.
 - **Progressive enhancement** — audio session, Wake Lock and vibration are feature-detected and no-ops
   where absent. The app is fully correct without any of them.
 - **Semantic and accessible** — [Pico CSS](https://picocss.com/) classless, WCAG 2.2 AA in every slice.
diff --git a/docs/spec.md b/docs/spec.md
index 3a43834..5386536 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -416,22 +416,21 @@ layer below is feature-detected, adds capability where present, and is a no-op w
   `virtual:pwa-register` by hand; (2) **`workbox-window` must be an explicit devDependency** under
   pnpm, or the build fails with `Rolldown failed to resolve import "workbox-window"`.
 - Add `/// <reference types="vite-plugin-pwa/client" />` to `src/env.d.ts` for the virtual-module types.
-- **`registerType: 'prompt'`, never `autoUpdate`** — hold a waiting worker until a counter activates it.
-  The activation path is a thin Astro script around the service-worker registration wrapper.
+- **`registerType: 'prompt'`, never `autoUpdate`** — activate a waiting worker immediately when no
+  Routine is active. The activation path is a thin Astro script around the service-worker registration wrapper.
 - Precache everything: the app is static with no API. Measured cost: 1.3 KB `sw.js` + 15 KB workbox
   (SW scope only), 1.27 KB gzip on the page.
 
 #### Update activation
 
 - Use `registerType: 'prompt'`, never `autoUpdate`. Capture `updateSW` from
-  `registerSW({ onNeedRefresh })`; a waiting worker stays idle until counter activation.
-- Every counter start path — count-up, count down, and restart — emits one activation event. If a worker
-  waits, the event calls `updateSW(true)` and reloads automatically into the waiting version. If the
-  readiness callback arrives just after the event, activation starts as soon as it is ready. Pause and
-  resume do not emit activation events.
+  `registerSW({ onNeedRefresh })`. When the callback fires, activate immediately if no Routine is active;
+  otherwise leave the worker waiting.
+- A running or paused Routine counts as active. When it reaches Done or the user presses Reset, emit an
+  inactive event and retry `updateSW(true)`. This applies update without discarding an in-memory Clock.
 - No update button, confirmation prompt, toast dependency, popover/polyfill, polling or custom
-  service-worker manager. Automatic reload is intentional and may discard a newly started in-memory
-  Clock; the next page starts with the new build.
+  service-worker manager. Standalone Home Screen PWAs use the same service-worker lifecycle: on launch,
+  registration checks for an update; `updateSW(true)` activates it and reloads the page.
 - Before activation, store a session marker. The new build prefixes the bottom version with green
   **NEW vX.X.X** for the current app session. Clear the marker only when activation fails. Version
   highlighting is optional; storage failures do not block update activation or timer behavior.
@@ -594,8 +593,9 @@ Genuinely undecided. An implementer should raise these rather than assume.
   app is live at `timer.marcosgilf.com`.
 - **Default values for `Prefs`** — only `prepareMs` has a stated default (10s). Starting `muted`,
   `volume`, `ticks` and `vibrate` values are unspecified.
-- ~~**Update-prompt UI**~~ — resolved: no update control. A waiting worker activates and reloads when any
-  counter starts or restarts; the new build labels its bottom version **NEW vX.X.X** in green for current app session.
+- ~~**Update-prompt UI**~~ — resolved: no update control. A waiting worker activates immediately when
+  idle, or after an active Routine reaches Done/Reset; the new build labels its bottom version **NEW vX.X.X**
+  in green for the current app session.
 - **Install guidance copy for iOS** — decided that it must be static copy (no
   `beforeinstallprompt`), but not what it says or which screen hosts it.
 - ~~**App name, iconography, favicon/manifest icon set, `theme_color`**~~ — resolved: app name
diff --git a/src/client/pwa-update.test.ts b/src/client/pwa-update.test.ts
index 302d67c..99650b6 100644
--- a/src/client/pwa-update.test.ts
+++ b/src/client/pwa-update.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import { createPwaUpdateController, type RegisterSW } from "./pwa-update.ts";
 
 const createHarness = () => {
+  let routineActive = false;
   let onNeedRefresh = () => {};
   const updateSW = vi.fn<ReturnType<RegisterSW>>();
   updateSW.mockResolvedValue(undefined);
@@ -13,6 +14,7 @@ const createHarness = () => {
   const onActivationFailed = vi.fn();
   const controller = createPwaUpdateController({
     registerSW,
+    isRoutineActive: () => routineActive,
     onActivationStarted,
     onActivationFailed,
   });
@@ -25,44 +27,47 @@ const createHarness = () => {
     updateSW,
     onActivationStarted,
     onActivationFailed,
+    setRoutineActive: (active: boolean) => {
+      routineActive = active;
+    },
   };
 };
 
 describe("PWA update controller", () => {
-  it("starts current and becomes ready only when service worker needs refresh", () => {
+  it("activates waiting update immediately when no Routine is active", () => {
     const harness = createHarness();
-
-    expect(harness.controller.ready).toBe(false);
     harness.controller.register();
-    expect(harness.controller.ready).toBe(false);
 
     harness.onNeedRefresh();
 
     expect(harness.controller.ready).toBe(true);
-    expect(harness.updateSW).not.toHaveBeenCalled();
-  });
-
-  it("activates ready update automatically when a counter starts", async () => {
-    const harness = createHarness();
-    harness.controller.register();
-    harness.onNeedRefresh();
-
-    await expect(harness.controller.activate()).resolves.toBe(true);
-
     expect(harness.onActivationStarted).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledWith(true);
   });
 
-  it("waits for update readiness when counter starts first", async () => {
+  it("keeps waiting update while Routine is active", async () => {
     const harness = createHarness();
+    harness.setRoutineActive(true);
     harness.controller.register();
 
+    harness.onNeedRefresh();
+
+    expect(harness.controller.ready).toBe(true);
+    expect(harness.updateSW).not.toHaveBeenCalled();
     await expect(harness.controller.activate()).resolves.toBe(false);
     expect(harness.updateSW).not.toHaveBeenCalled();
+  });
 
+  it("activates deferred update when Routine becomes inactive", async () => {
+    const harness = createHarness();
+    harness.setRoutineActive(true);
+    harness.controller.register();
     harness.onNeedRefresh();
 
+    harness.setRoutineActive(false);
+
+    await expect(harness.controller.activate()).resolves.toBe(true);
     expect(harness.onActivationStarted).toHaveBeenCalledOnce();
     expect(harness.updateSW).toHaveBeenCalledOnce();
   });
@@ -82,6 +87,7 @@ describe("PWA update controller", () => {
 
   it("does not activate twice while first activation is in flight", async () => {
     const harness = createHarness();
+    harness.setRoutineActive(true);
     let resolveUpdate = () => {};
     harness.updateSW.mockImplementation(
       () =>
@@ -91,6 +97,7 @@ describe("PWA update controller", () => {
     );
     harness.controller.register();
     harness.onNeedRefresh();
+    harness.setRoutineActive(false);
 
     const first = harness.controller.activate();
     const second = harness.controller.activate();
@@ -107,6 +114,7 @@ describe("PWA update controller", () => {
     });
     const controller = createPwaUpdateController({
       registerSW,
+      isRoutineActive: () => false,
       onActivationStarted: vi.fn(),
     });
 
diff --git a/src/client/pwa-update.ts b/src/client/pwa-update.ts
index a46ecf2..1e39129 100644
--- a/src/client/pwa-update.ts
+++ b/src/client/pwa-update.ts
@@ -7,23 +7,23 @@ export type RegisterSW = (options: {
 
 type PwaUpdateControllerOptions = {
   registerSW: RegisterSW;
+  isRoutineActive: () => boolean;
   onActivationStarted: () => void;
   onActivationFailed?: () => void;
 };
 
 export const createPwaUpdateController = ({
   registerSW,
+  isRoutineActive,
   onActivationStarted,
   onActivationFailed,
 }: PwaUpdateControllerOptions) => {
   let updateSW: UpdateSW | null = null;
   let updateReady = false;
-  let activationRequested = false;
   let activationStarted = false;
 
   const activate = async (): Promise<boolean> => {
-    activationRequested = true;
-    if (!updateReady || !updateSW || activationStarted) return false;
+    if (!updateReady || !updateSW || activationStarted || isRoutineActive()) return false;
 
     activationStarted = true;
 
@@ -43,7 +43,7 @@ export const createPwaUpdateController = ({
       updateSW = registerSW({
         onNeedRefresh: () => {
           updateReady = true;
-          if (activationRequested) void activate();
+          if (!isRoutineActive()) void activate();
         },
         onRegisterError: () => {},
       });
diff --git a/src/layouts/AppLayout.astro b/src/layouts/AppLayout.astro
index 145b2f4..0753576 100644
--- a/src/layouts/AppLayout.astro
+++ b/src/layouts/AppLayout.astro
@@ -35,7 +35,7 @@ const deployLabel =
     <link rel="manifest" href="/manifest.webmanifest" />
     <title>{title}</title>
   </head>
-  <body>
+  <body data-routine-active="false">
     <slot />
     <footer class="app-footer">
       {deployLabel && <small class="deploy-clue" aria-label={`Deployment context ${deployLabel}`}>{deployLabel}</small>}
@@ -63,6 +63,7 @@ const deployLabel =
       const registerServiceWorker: RegisterSW = (options) => registerSW(options);
       const update = createPwaUpdateController({
         registerSW: registerServiceWorker,
+        isRoutineActive: () => document.body.dataset.routineActive === "true",
         onActivationStarted: () => {
           try {
             sessionStorage.setItem(updateMarker, "true");
@@ -79,7 +80,7 @@ const deployLabel =
         },
       });
 
-      window.addEventListener("timer:counter-activated", () => {
+      window.addEventListener("timer:counter-inactive", () => {
         void update.activate();
       });
       update.register();
diff --git a/src/pages/down.astro b/src/pages/down.astro
index 55697fa..f96e076 100644
--- a/src/pages/down.astro
+++ b/src/pages/down.astro
@@ -135,6 +135,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     setUrlState("done");
     announce(`Done count down: ${announceElapsed(durationMs)}.`);
     paint();
+    window.dispatchEvent(new Event("timer:counter-inactive"));
   };
 
   const paint = () => {
@@ -154,7 +155,6 @@ import AppLayout from "../layouts/AppLayout.astro";
   };
 
   const startRunning = () => {
-    window.dispatchEvent(new Event("timer:counter-activated"));
     isFinished = false;
     setUrlState("running");
     clock = start(reset(), Date.now());
@@ -203,6 +203,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     stopTicking();
     announce("Reset.");
     paint();
+    window.dispatchEvent(new Event("timer:counter-inactive"));
   });
 
   const configurationUrl = new URL("/configuration", location.origin);
diff --git a/src/pages/index.astro b/src/pages/index.astro
index b5a5b37..2a8e8ef 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -125,6 +125,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     setUrlState("done");
     announce(`Done: ${announceElapsed(MAX_ELAPSED_MS)}.`);
     paint();
+    window.dispatchEvent(new Event("timer:counter-inactive"));
   };
 
   const paint = () => {
@@ -144,7 +145,6 @@ import AppLayout from "../layouts/AppLayout.astro";
   };
 
   const startRunning = () => {
-    window.dispatchEvent(new Event("timer:counter-activated"));
     isFinished = false;
     setUrlState("running");
     clock = start(reset(), Date.now());
@@ -193,6 +193,7 @@ import AppLayout from "../layouts/AppLayout.astro";
     stopTicking();
     announce("Reset.");
     paint();
+    window.dispatchEvent(new Event("timer:counter-inactive"));
   });
 
   document.addEventListener("visibilitychange", () => {

From 0fd4e81633ad599d43ba6abf9409d842c7c0758a Mon Sep 17 00:00:00 2001
From: marcosgilf <marcosenrique.gil@ingka.ikea.com>
Date: Fri, 14 Aug 2026 23:05:54 +0200
Subject: [PATCH 4/4] fix(pwa): clear update highlight after reload

---
 README.md                   | 2 +-
 docs/spec.md                | 8 ++++----
 src/layouts/AppLayout.astro | 1 +
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9202523..83b5332 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ is a Tabata whether or not anything is labelled "Tabata".
 - **Offline-first** — precached service worker, no backend, no accounts, no analytics. Installable as
   **Timer**; waiting updates apply immediately when no Routine is active.
 - **Automatic updates** — an active or paused Routine defers a waiting worker until Done or Reset. The
-  new build reloads automatically, then the bottom version shows green **NEW vx.x.x** for the current app session.
+  new build reloads automatically, then the bottom version shows green **NEW vx.x.x** for that reload only.
 - **Progressive enhancement** — audio session, Wake Lock and vibration are feature-detected and no-ops
   where absent. The app is fully correct without any of them.
 - **Semantic and accessible** — [Pico CSS](https://picocss.com/) classless, WCAG 2.2 AA in every slice.
diff --git a/docs/spec.md b/docs/spec.md
index 5386536..5705bf3 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -431,9 +431,9 @@ layer below is feature-detected, adds capability where present, and is a no-op w
 - No update button, confirmation prompt, toast dependency, popover/polyfill, polling or custom
   service-worker manager. Standalone Home Screen PWAs use the same service-worker lifecycle: on launch,
   registration checks for an update; `updateSW(true)` activates it and reloads the page.
-- Before activation, store a session marker. The new build prefixes the bottom version with green
-  **NEW vX.X.X** for the current app session. Clear the marker only when activation fails. Version
-  highlighting is optional; storage failures do not block update activation or timer behavior.
+- Before activation, store a session marker. The new build consumes the marker on first render, prefixes
+  the bottom version with green **NEW vX.X.X**, then clears it. Version highlighting is optional; storage
+  failures do not block update activation or timer behavior.
 - Registration errors are swallowed; offline use of the current version remains unaffected.
 
 ### Install and manifest
@@ -595,7 +595,7 @@ Genuinely undecided. An implementer should raise these rather than assume.
   `volume`, `ticks` and `vibrate` values are unspecified.
 - ~~**Update-prompt UI**~~ — resolved: no update control. A waiting worker activates immediately when
   idle, or after an active Routine reaches Done/Reset; the new build labels its bottom version **NEW vX.X.X**
-  in green for the current app session.
+  in green for that reload only.
 - **Install guidance copy for iOS** — decided that it must be static copy (no
   `beforeinstallprompt`), but not what it says or which screen hosts it.
 - ~~**App name, iconography, favicon/manifest icon set, `theme_color`**~~ — resolved: app name
diff --git a/src/layouts/AppLayout.astro b/src/layouts/AppLayout.astro
index 0753576..8a88c0f 100644
--- a/src/layouts/AppLayout.astro
+++ b/src/layouts/AppLayout.astro
@@ -51,6 +51,7 @@ const deployLabel =
 
       try {
         if (sessionStorage.getItem(updateMarker) === "true") {
+          sessionStorage.removeItem(updateMarker);
           const versionLabel = appVersion.getAttribute("aria-label") ?? "Timer version";
           appVersion.textContent = `NEW ${appVersion.textContent ?? ""}`;
           appVersion.dataset.updated = "true";