@broberg/pwa 0.3.0 → 0.4.1

package/README.md

@@ -8,6 +8,109 @@ as one small, framework- and bundler-agnostic package instead of a fifth copy.
 npm i @broberg/pwa
 ```
 
+## 0.4.1 — «Update now» now always updates (F054.9)
+
+**Take 0.4.1 if you show an update button.** In 0.4.0 a press could do nothing,
+forever: on a page opened WITHOUT an active service worker (a shift-reload, or
+the first page after registration) while a new worker was waiting, the guard
+that stops a first install from reloading a new visitor also swallowed the
+takeover the press caused. No reload, and every later press went to a worker
+that was already active. Reported by the owner after 30 presses in helpdesk.
+
+Now: after `applyUpdate()` the next takeover always reloads; a press whose
+worker already activated reloads directly; and an SW without `clientsClaim`
+reloads when the worker reaches `activated`. One reload, never two.
+`reloadOnControllerChange: false` still means you reload yourself. No API
+change; a first install still never reloads on its own.
+
+## 0.4.0 — READ, don't remember (F054.8)
+
+**Take 0.4.0.** Before it, `updateReady` could only ever go **up**, and only from
+an event: one read of `registration.waiting` at attach, plus `updatefound`. The
+interval and focus checks called `registration.update()` and never looked at
+`registration.waiting` at all. So the banner got **exactly one chance to be
+seen** — dismiss it once, or miss the seconds it was up, and nothing in the
+package could raise it again for that tab. The client then sat on the old bundle
+indefinitely.
+
+It fails in the reassuring direction: deploy green, server on the new build,
+feature live — and the only symptom available to anyone is a person saying a
+feature is missing. That is how cardmem found it, in their own copy of this
+pattern.
+
+**What changes for you:**
+
+| | 0.3.x | 0.4.0 |
+|---|---|---|
+| `updateReady` | rises once, ever | re-derived from `registration.waiting` on every interval / focus / visibility tick |
+| `subscribe()` | emits at most **once** | emits whenever the answer moves, **in both directions** |
+| "Later" | your problem | `snooze()` — 30 min by default, persisted, then it comes back |
+
+**`updateReady` CAN NOW GO FALSE.** If your code assumes it only ever rises — a
+`useState` you never reset, a banner you unmount by hand — read that line before
+upgrading. Everything else is additive.
+
+```ts
+const { updateReady, applyUpdate, snooze } = usePwaUpdate();
+// "Update" → applyUpdate()     "Later" → snooze(), NOT a local setState(false)
+```
+
+**The pattern to look for in your own code**, named by cardmem when they read
+this report against their adoption — it is not hypothetical, it is what a
+consumer writes when the flag can only ever rise:
+
+```ts
+// ⚠️ the 0.3.x shape: a local mirror, reset only on dismiss
+const [needRefresh, setNeedRefresh] = useState(false);
+useEffect(() => { if (updateReady) setNeedRefresh(true); }, [updateReady]);
+const onDismiss = () => setNeedRefresh(false);   // ← the only way down
+```
+
+That mirror cannot fall when `updateReady` does, and dismissing it is permanent
+— which is the original defect, reproduced one layer up. Drop the mirror and
+render from `updateReady` directly; wire "Later" to `snooze()`.
+
+So an upgrade here is a small **migration**, not a free version bump. It is the
+one place 0.4.0 asks anything of you.
+
+### Upgrading does NOT fix this on its own if you have your own dismissal
+
+fd-sundhed found this by reading their own installed code rather than this
+report, and it is the half that would otherwise produce a green claim and an
+unchanged user. Their banner carries a second dismissal on top of the hook:
+
+```ts
+const [dismissed] = useState(() => sessionStorage.getItem(KEY) === "1");
+if (!updateReady || dismissed) return null;   // "Later" hides it for the whole tab
+```
+
+The defect is **doubled** — ours in the hook, theirs in the component — and only
+ours goes away with a `pnpm up`. Upgrade, report it fixed, and the person still
+never sees the banner again.
+
+**So before you upgrade, grep your own component for a second way the banner can
+be hidden**: a `sessionStorage`/`localStorage` flag, a `dismissed` state, a
+`useRef` that latches. Whatever holds it down has to become the snooze, or the
+snooze is decorative.
+
+### If you need something stricter than 30 minutes
+
+`snoozeMs` is a plain number, so a large one is available and this package will
+not stop you. The honest statement is therefore narrower than "a mute is
+impossible": there is no OPTION named mute, and the default comes back.
+
+If the policy you actually want is *"gone for the rest of this tab"*, express it
+as scope rather than duration — `snoozeStorage: sessionStorage` with a long
+`snoozeMs`. It dies with the tab instead of pretending to be permanent, so a
+person who closes and reopens the app is asked again, and nobody has to reason
+about a timestamp in the year 2255.
+
+`snooze()` is deliberately not a mute, and there is no option to make it one: a
+banner that can be silenced forever is the defect above, made official. The
+snooze is persisted (`localStorage` by default, `snoozeStorage: null` for
+memory-only) so the reload the banner is *asking for* cannot defeat it.
+
+
 - **`@broberg/pwa`** — `createPwaUpdater()`, a zero-dependency controller for the
   service-worker update lifecycle (works with Serwist, Workbox or a hand-rolled SW).
 - **`@broberg/pwa/react`** — `usePwaUpdate()` hook + an **unstyled** `<PwaUpdateBanner>`

package/dist/index.cjs

@@ -4,8 +4,17 @@
 var SKIP_WAITING = "SKIP_WAITING";
 var SKIP_WAITING_MESSAGE = { type: SKIP_WAITING };
 
+// src/should-offer.ts
+function shouldOfferUpdate({ waiting, snoozedUntil, now }) {
+  if (!waiting) return false;
+  if (snoozedUntil !== null && snoozedUntil > now) return false;
+  return true;
+}
+
 // src/index.ts
 var DEFAULT_POLL_MS = 60 * 60 * 1e3;
+var DEFAULT_SNOOZE_MS = 30 * 60 * 1e3;
+var SNOOZE_KEY = "broberg-pwa:snoozed-until";
 function createPwaUpdater(options = {}) {
   const {
     swUrl = "/sw.js",
@@ -13,11 +22,11 @@ function createPwaUpdater(options = {}) {
     pollIntervalMs = DEFAULT_POLL_MS,
     updateOnFocus = true,
     reloadOnControllerChange = true,
+    snoozeMs = DEFAULT_SNOOZE_MS,
     disabled = false
   } = options;
   const listeners = /* @__PURE__ */ new Set();
   let updateReady = false;
-  let waitingWorker = null;
   const getState = () => ({ updateReady });
   const emit = () => {
     const state = getState();
@@ -34,6 +43,10 @@ function createPwaUpdater(options = {}) {
       getState,
       applyUpdate() {
       },
+      snooze() {
+      },
+      check() {
+      },
       destroy() {
         listeners.clear();
       }
@@ -44,43 +57,75 @@ function createPwaUpdater(options = {}) {
   let removeFocusListeners = null;
   let reloading = false;
   let destroyed = false;
-  const markReady = (worker) => {
-    waitingWorker = worker;
-    if (!updateReady) {
-      updateReady = true;
+  let registrationRef = null;
+  const storage = options.snoozeStorage !== void 0 ? options.snoozeStorage : typeof localStorage !== "undefined" ? localStorage : null;
+  let snoozedUntil = null;
+  const readSnooze = () => {
+    if (!storage) return snoozedUntil;
+    try {
+      const raw = storage.getItem(SNOOZE_KEY);
+      if (!raw) return null;
+      const n = Number(raw);
+      return Number.isFinite(n) ? n : null;
+    } catch {
+      return snoozedUntil;
+    }
+  };
+  const writeSnooze = (until) => {
+    snoozedUntil = until;
+    if (!storage) return;
+    try {
+      if (until === null) storage.removeItem(SNOOZE_KEY);
+      else storage.setItem(SNOOZE_KEY, String(until));
+    } catch {
+    }
+  };
+  const check = () => {
+    const waiting = registrationRef?.waiting ?? null;
+    const next = shouldOfferUpdate({
+      waiting,
+      snoozedUntil: readSnooze(),
+      now: Date.now()
+    });
+    if (next !== updateReady) {
+      updateReady = next;
       emit();
     }
   };
   let hadController = !!container.controller;
+  let applied = false;
+  const reloadOnce = () => {
+    if (!reloadOnControllerChange || reloading) return;
+    reloading = true;
+    if (typeof location !== "undefined") location.reload();
+  };
   const onControllerChange = () => {
     if (!reloadOnControllerChange || reloading) return;
-    if (!hadController) {
+    if (!hadController && !applied) {
       hadController = true;
       return;
     }
-    reloading = true;
-    if (typeof location !== "undefined") location.reload();
+    reloadOnce();
   };
   container.addEventListener("controllerchange", onControllerChange);
   const watchInstalling = (registration) => {
     const installing = registration.installing;
     if (!installing) return;
     installing.addEventListener("statechange", () => {
-      if (installing.state === "installed" && container.controller) {
-        markReady(installing);
-      }
+      if (installing.state === "installed") check();
     });
   };
   const wireFocusChecks = (registration) => {
     if (!updateOnFocus) return;
-    const check = () => {
+    const tick = () => {
+      check();
       registration.update().catch(() => {
-      });
+      }).then(check, check);
     };
-    const onFocus = () => check();
+    const onFocus = () => tick();
     const onVisibility = () => {
       if (typeof document !== "undefined" && document.visibilityState === "visible") {
-        check();
+        tick();
       }
     };
     if (typeof window !== "undefined") window.addEventListener("focus", onFocus);
@@ -97,12 +142,14 @@ function createPwaUpdater(options = {}) {
   const registrationPromise = register ? container.register(swUrl) : container.ready;
   registrationPromise.then((registration) => {
     if (destroyed) return;
-    if (registration.waiting) markReady(registration.waiting);
+    registrationRef = registration;
+    check();
     registration.addEventListener("updatefound", () => watchInstalling(registration));
     if (pollIntervalMs > 0) {
       pollId = setInterval(() => {
+        check();
         registration.update().catch(() => {
-        });
+        }).then(check, check);
       }, pollIntervalMs);
     }
     wireFocusChecks(registration);
@@ -112,8 +159,22 @@ function createPwaUpdater(options = {}) {
     subscribe,
     getState,
     applyUpdate() {
-      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);
+      const waiting = registrationRef?.waiting ?? null;
+      if (waiting) {
+        applied = true;
+        waiting.addEventListener("statechange", () => {
+          if (waiting.state === "activated") reloadOnce();
+        });
+        waiting.postMessage(SKIP_WAITING_MESSAGE);
+        return;
+      }
+      if (updateReady) reloadOnce();
+    },
+    snooze() {
+      writeSnooze(Date.now() + snoozeMs);
+      check();
     },
+    check,
     destroy() {
       destroyed = true;
       if (pollId !== null) clearInterval(pollId);
@@ -127,5 +188,6 @@ function createPwaUpdater(options = {}) {
 exports.SKIP_WAITING = SKIP_WAITING;
 exports.SKIP_WAITING_MESSAGE = SKIP_WAITING_MESSAGE;
 exports.createPwaUpdater = createPwaUpdater;
+exports.shouldOfferUpdate = shouldOfferUpdate;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/message.ts","../src/index.ts"],"names":[],"mappings":";;;AAKO,IAAM,YAAA,GAAe;AAErB,IAAM,oBAAA,GAAuB,EAAE,IAAA,EAAM,YAAA;;;ACyC5C,IAAM,eAAA,GAAkB,KAAK,EAAA,GAAK,GAAA;AAY3B,SAAS,gBAAA,CAAiB,OAAA,GAA6B,EAAC,EAAe;AAC5E,EAAA,MAAM;AAAA,IACJ,KAAA,GAAQ,QAAA;AAAA,IACR,QAAA,GAAW,IAAA;AAAA,IACX,cAAA,GAAiB,eAAA;AAAA,IACjB,aAAA,GAAgB,IAAA;AAAA,IAChB,wBAAA,GAA2B,IAAA;AAAA,IAC3B,QAAA,GAAW;AAAA,GACb,GAAI,OAAA;AAEJ,EAAA,MAAM,SAAA,uBAAgB,GAAA,EAAsC;AAC5D,EAAA,IAAI,WAAA,GAAc,KAAA;AAClB,EAAA,IAAI,aAAA,GAAsC,IAAA;AAE1C,EAAA,MAAM,QAAA,GAAW,OAAwB,EAAE,WAAA,EAAY,CAAA;AACvD,EAAA,MAAM,OAAO,MAAY;AACvB,IAAA,MAAM,QAAQ,QAAA,EAAS;AACvB,IAAA,KAAA,MAAW,QAAA,IAAY,SAAA,EAAW,QAAA,CAAS,KAAK,CAAA;AAAA,EAClD,CAAA;AACA,EAAA,MAAM,SAAA,GAAY,CAAC,QAAA,KAA6D;AAC9E,IAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,IAAA,OAAO,MAAM,SAAA,CAAU,MAAA,CAAO,QAAQ,CAAA;AAAA,EACxC,CAAA;AAEA,EAAA,MAAM,SAAA,GACJ,OAAO,SAAA,KAAc,WAAA,IAAe,eAAA,IAAmB,SAAA;AAGzD,EAAA,IAAI,QAAA,IAAY,CAAC,SAAA,EAAW;AAC1B,IAAA,OAAO;AAAA,MACL,SAAA;AAAA,MACA,QAAA;AAAA,MACA,WAAA,GAAc;AAAA,MAAC,CAAA;AAAA,MACf,OAAA,GAAU;AACR,QAAA,SAAA,CAAU,KAAA,EAAM;AAAA,MAClB;AAAA,KACF;AAAA,EACF;AAEA,EAAA,MAAM,YAAY,SAAA,CAAU,aAAA;AAC5B,EAAA,IAAI,MAAA,GAAgD,IAAA;AACpD,EAAA,IAAI,oBAAA,GAA4C,IAAA;AAChD,EAAA,IAAI,SAAA,GAAY,KAAA;AAChB,EAAA,IAAI,SAAA,GAAY,KAAA;AAEhB,EAAA,MAAM,SAAA,GAAY,CAAC,MAAA,KAAgC;AACjD,IAAA,aAAA,GAAgB,MAAA;AAChB,IAAA,IAAI,CAAC,WAAA,EAAa;AAChB,MAAA,WAAA,GAAc,IAAA;AACd,MAAA,IAAA,EAAK;AAAA,IACP;AAAA,EACF,CAAA;AAOA,EAAA,IAAI,aAAA,GAAgB,CAAC,CAAC,SAAA,CAAU,UAAA;AAChC,EAAA,MAAM,qBAAqB,MAAY;AACrC,IAAA,IAAI,CAAC,4BAA4B,SAAA,EAAW;AAC5C,IAAA,IAAI,CAAC,aAAA,EAAe;AAClB,MAAA,aAAA,GAAgB,IAAA;AAChB,MAAA;AAAA,IACF;AACA,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,IAAI,OAAO,QAAA,KAAa,WAAA,EAAa,QAAA,CAAS,MAAA,EAAO;AAAA,EACvD,CAAA;AACA,EAAA,SAAA,CAAU,gBAAA,CAAiB,oBAAoB,kBAAkB,CAAA;AAEjE,EAAA,MAAM,eAAA,GAAkB,CAAC,YAAA,KAAkD;AACzE,IAAA,MAAM,aAAa,YAAA,CAAa,UAAA;AAChC,IAAA,IAAI,CAAC,UAAA,EAAY;AACjB,IAAA,UAAA,CAAW,gBAAA,CAAiB,eAAe,MAAM;AAI/C,MAAA,IAAI,UAAA,CAAW,KAAA,KAAU,WAAA,IAAe,SAAA,CAAU,UAAA,EAAY;AAC5D,QAAA,SAAA,CAAU,UAAU,CAAA;AAAA,MACtB;AAAA,IACF,CAAC,CAAA;AAAA,EACH,CAAA;AAEA,EAAA,MAAM,eAAA,GAAkB,CAAC,YAAA,KAAkD;AACzE,IAAA,IAAI,CAAC,aAAA,EAAe;AACpB,IAAA,MAAM,QAAQ,MAAY;AACxB,MAAA,YAAA,CAAa,MAAA,EAAO,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IACtC,CAAA;AACA,IAAA,MAAM,OAAA,GAAU,MAAY,KAAA,EAAM;AAClC,IAAA,MAAM,eAAe,MAAY;AAC/B,MAAA,IAAI,OAAO,QAAA,KAAa,WAAA,IAAe,QAAA,CAAS,oBAAoB,SAAA,EAAW;AAC7E,QAAA,KAAA,EAAM;AAAA,MACR;AAAA,IACF,CAAA;AACA,IAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,MAAA,CAAO,gBAAA,CAAiB,SAAS,OAAO,CAAA;AAC3E,IAAA,IAAI,OAAO,aAAa,WAAA,EAAa;AACnC,MAAA,QAAA,CAAS,gBAAA,CAAiB,oBAAoB,YAAY,CAAA;AAAA,IAC5D;AACA,IAAA,oBAAA,GAAuB,MAAM;AAC3B,MAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,MAAA,CAAO,mBAAA,CAAoB,SAAS,OAAO,CAAA;AAC9E,MAAA,IAAI,OAAO,aAAa,WAAA,EAAa;AACnC,QAAA,QAAA,CAAS,mBAAA,CAAoB,oBAAoB,YAAY,CAAA;AAAA,MAC/D;AAAA,IACF,CAAA;AAAA,EACF,CAAA;AAIA,EAAA,MAAM,sBAAsB,QAAA,GAAW,SAAA,CAAU,QAAA,CAAS,KAAK,IAAI,SAAA,CAAU,KAAA;AAE7E,EAAA,mBAAA,CACG,IAAA,CAAK,CAAC,YAAA,KAAiB;AACtB,IAAA,IAAI,SAAA,EAAW;AACf,IAAA,IAAI,YAAA,CAAa,OAAA,EAAS,SAAA,CAAU,YAAA,CAAa,OAAO,CAAA;AACxD,IAAA,YAAA,CAAa,gBAAA,CAAiB,aAAA,EAAe,MAAM,eAAA,CAAgB,YAAY,CAAC,CAAA;AAChF,IAAA,IAAI,iBAAiB,CAAA,EAAG;AACtB,MAAA,MAAA,GAAS,YAAY,MAAM;AACzB,QAAA,YAAA,CAAa,MAAA,EAAO,CAAE,KAAA,CAAM,MAAM;AAAA,QAElC,CAAC,CAAA;AAAA,MACH,GAAG,cAAc,CAAA;AAAA,IACnB;AACA,IAAA,eAAA,CAAgB,YAAY,CAAA;AAAA,EAC9B,CAAC,CAAA,CACA,KAAA,CAAM,MAAM;AAAA,EAEb,CAAC,CAAA;AAEH,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,QAAA;AAAA,IACA,WAAA,GAAc;AACZ,MAAA,IAAI,aAAA,EAAe,aAAA,CAAc,WAAA,CAAY,oBAAoB,CAAA;AAAA,IACnE,CAAA;AAAA,IACA,OAAA,GAAU;AACR,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA,IAAI,MAAA,KAAW,IAAA,EAAM,aAAA,CAAc,MAAM,CAAA;AACzC,MAAA,oBAAA,IAAuB;AACvB,MAAA,SAAA,CAAU,mBAAA,CAAoB,oBAAoB,kBAAkB,CAAA;AACpE,MAAA,SAAA,CAAU,KAAA,EAAM;AAAA,IAClB;AAAA,GACF;AACF","file":"index.cjs","sourcesContent":["/**\n * The single source of the client↔service-worker \"activate the waiting worker\"\n * message. Both the client controller (`applyUpdate`) and the SW helper\n * (`listenForSkipWaiting`) import it so the contract can never drift.\n */\nexport const SKIP_WAITING = \"SKIP_WAITING\" as const;\n\nexport const SKIP_WAITING_MESSAGE = { type: SKIP_WAITING } as const;\n\nexport type SkipWaitingMessage = typeof SKIP_WAITING_MESSAGE;\n","import { SKIP_WAITING_MESSAGE } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */\n  applyUpdate(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n  let waitingWorker: ServiceWorker | null = null;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  const markReady = (worker: ServiceWorker): void => {\n    waitingWorker = worker;\n    if (!updateReady) {\n      updateReady = true;\n      emit();\n    }\n  };\n\n  // With `clientsClaim: true` a brand-new worker claims a previously\n  // uncontrolled page and fires `controllerchange` on the FIRST install — that\n  // is not an update, so reloading there would yank a first-time visitor out of\n  // whatever they are doing. Only a `controllerchange` that REPLACES an existing\n  // controller is a real takeover worth reloading for.\n  let hadController = !!container.controller;\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    if (!hadController) {\n      hadController = true; // first claim of an uncontrolled page — not an update\n      return;\n    }\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\" && container.controller) {\n        markReady(installing);\n      }\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    const check = (): void => {\n      registration.update().catch(() => {});\n    };\n    const onFocus = (): void => check();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        check();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      if (registration.waiting) markReady(registration.waiting);\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          registration.update().catch(() => {\n            // ignore transient update-check network errors\n          });\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);\n    },\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/message.ts","../src/should-offer.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The single source of the client↔service-worker \"activate the waiting worker\"\n * message. Both the client controller (`applyUpdate`) and the SW helper\n * (`listenForSkipWaiting`) import it so the contract can never drift.\n */\nexport const SKIP_WAITING = \"SKIP_WAITING\" as const;\n\nexport const SKIP_WAITING_MESSAGE = { type: SKIP_WAITING } as const;\n\nexport type SkipWaitingMessage = typeof SKIP_WAITING_MESSAGE;\n","/**\n * F054.8 — the decision, as a pure function.\n *\n * Split out so it can be proven with NO service worker, NO DOM and no fake\n * container: every branch is reachable from three plain values. The rest of the\n * updater is plumbing around this.\n *\n * Why it is a function and not a flag: the old updater REMEMBERED whether an\n * update was ready instead of READING whether one is waiting, so the answer\n * could only ever be given once.\n */\nexport interface ShouldOfferInput {\n  /** `registration.waiting` — read fresh at the moment of the decision. */\n  waiting: unknown;\n  /** Epoch ms until which the user has snoozed the offer, or null. */\n  snoozedUntil: number | null;\n  /** Epoch ms now. Passed in so the function stays pure and testable. */\n  now: number;\n}\n\n/**\n * Should the consumer be offered the update right now?\n *\n * WHY `controller` IS NOT A TERM HERE, though the sketch we were shown had one\n * and the old code checked it on one of its two paths.\n *\n * The old updater answered this question inconsistently: the attach path\n * (`if (registration.waiting)`) offered with no controller check, while the\n * `updatefound` path required `container.controller` to suppress a first\n * install. Same situation, two answers, depending on which path happened to see\n * it. Making them agree is part of this fix — the question is which way.\n *\n * Requiring a controller would be the tighter rule, and it would REMOVE a banner\n * that some consumer sees today: a page that is not yet controlled (no\n * `clientsClaim`, or a hard reload) but has a genuine update waiting. With\n * fd-sundhed live to 16,838 people on the current version, a change in that\n * direction is not one to make on an unverified reading.\n *\n * And the reading in question is this: a worker only enters `waiting` when\n * another worker is already ACTIVE — on a first install there is nothing to wait\n * behind, so it activates directly. If that is right, `registration.waiting`\n * being non-null already implies this is not a first install, and the controller\n * term is redundant rather than protective. **I have not verified that against a\n * real service worker.** So the old, more permissive behaviour stays as the\n * floor, and first-install suppression rides on the same fact rather than on a\n * second guard that could disagree with it.\n *\n * If someone later measures that a first-install worker CAN sit in `waiting`,\n * this is the function to add the term to — and the test to write first is the\n * one that fails today.\n */\nexport function shouldOfferUpdate({ waiting, snoozedUntil, now }: ShouldOfferInput): boolean {\n  if (!waiting) return false;\n  if (snoozedUntil !== null && snoozedUntil > now) return false;\n  return true;\n}\n","import { SKIP_WAITING_MESSAGE } from \"./message.js\";\nimport { shouldOfferUpdate } from \"./should-offer.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport { shouldOfferUpdate } from \"./should-offer.js\";\nexport type { ShouldOfferInput } from \"./should-offer.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * How long `snooze()` holds the offer down (ms). Default 30 min.\n   *\n   * F054.8 — \"Later\" is a SNOOZE, never a mute. The defect this replaced was a\n   * banner that got exactly one chance to be seen; a permanent dismiss is that\n   * defect made official.\n   */\n  snoozeMs?: number;\n  /**\n   * Where a snooze is remembered, so it survives the reload the banner is\n   * asking for. Defaults to `localStorage` when available; pass `null` to keep\n   * the snooze in memory only.\n   */\n  snoozeStorage?: Pick<Storage, \"getItem\" | \"setItem\" | \"removeItem\"> | null;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /**\n   * Tell the waiting worker to activate (posts SKIP_WAITING); the page reloads\n   * when it takes over. If an update was offered but nothing waits any more\n   * (it already activated), reloads directly. No-op when nothing was offered.\n   */\n  applyUpdate(): void;\n  /**\n   * \"Later\". Holds the offer down for `snoozeMs`, then it comes back on the\n   * next tick — this is NOT a mute, and it deliberately cannot be made one.\n   */\n  snooze(): void;\n  /** Re-read `registration.waiting` right now and emit if the answer moved. */\n  check(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\nconst DEFAULT_SNOOZE_MS = 30 * 60 * 1000;\nconst SNOOZE_KEY = \"broberg-pwa:snoozed-until\";\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    snoozeMs = DEFAULT_SNOOZE_MS,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      snooze() {},\n      check() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  // F054.8 — READ the answer, never remember it.\n  //\n  // This used to be markReady(worker), the only writer of `updateReady`, and it\n  // was guarded by `if (!updateReady)` — so `emit()` fired AT MOST ONCE for the\n  // life of the updater. Both adapters drive their state from subscribe(), so a\n  // consumer who dismissed the banner had no channel that could ever raise it\n  // again. cardmem measured the consequence in production: a client sat on an\n  // old bundle indefinitely, and the only symptom anyone had was a person\n  // saying a feature was missing.\n  //\n  // `registration` is captured once resolved so every tick can re-read\n  // `.waiting` rather than wait to be told.\n  let registrationRef: ServiceWorkerRegistration | null = null;\n\n  const storage: PwaUpdaterOptions[\"snoozeStorage\"] =\n    options.snoozeStorage !== undefined\n      ? options.snoozeStorage\n      : typeof localStorage !== \"undefined\"\n        ? localStorage\n        : null;\n\n  let snoozedUntil: number | null = null;\n  const readSnooze = (): number | null => {\n    if (!storage) return snoozedUntil;\n    try {\n      const raw = storage.getItem(SNOOZE_KEY);\n      if (!raw) return null;\n      const n = Number(raw);\n      return Number.isFinite(n) ? n : null;\n    } catch {\n      // A browser with site data blocked THROWS on read. That is not a reason to\n      // stop offering updates — fall back to the in-memory value.\n      return snoozedUntil;\n    }\n  };\n  const writeSnooze = (until: number | null): void => {\n    snoozedUntil = until;\n    if (!storage) return;\n    try {\n      if (until === null) storage.removeItem(SNOOZE_KEY);\n      else storage.setItem(SNOOZE_KEY, String(until));\n    } catch {\n      // in-memory only for this tab; already recorded above\n    }\n  };\n\n  /**\n   * Re-derive from what is true RIGHT NOW and emit only when the answer moved.\n   * Emits in BOTH directions: false→true raises the banner, true→false takes it\n   * down when the worker is gone or the user snoozed.\n   */\n  const check = (): void => {\n    const waiting = registrationRef?.waiting ?? null;\n    const next = shouldOfferUpdate({\n      waiting,\n      snoozedUntil: readSnooze(),\n      now: Date.now(),\n    });\n    if (next !== updateReady) {\n      updateReady = next;\n      emit();\n    }\n  };\n\n  // With `clientsClaim: true` a brand-new worker claims a previously\n  // uncontrolled page and fires `controllerchange` on the FIRST install — that\n  // is not an update, so reloading there would yank a first-time visitor out of\n  // whatever they are doing. Only a `controllerchange` that REPLACES an existing\n  // controller is a real takeover worth reloading for.\n  //\n  // F054.9 — BUT THE GUARD CANNOT TELL A FIRST CLAIM FROM ONE THE USER ASKED FOR.\n  // A page opened with no controller (shift-reload bypasses the SW, or the first\n  // page after registration) while a worker waits shows the banner; pressing it\n  // activates the worker, whose controllerchange the guard then swallowed. Every\n  // later press posted SKIP_WAITING to a worker that was already active. The\n  // owner pressed «Opdatér nu» 30 times in helpdesk and nothing happened.\n  // `applied` is the missing fact: after an explicit applyUpdate() the next\n  // takeover is the update, whatever the page was controlled by before.\n  let hadController = !!container.controller;\n  let applied = false;\n  const reloadOnce = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    if (!hadController && !applied) {\n      hadController = true; // first claim of an uncontrolled page — not an update\n      return;\n    }\n    reloadOnce();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\") check();\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    // update() asks the SERVER for a new worker; check() reads whether one is\n    // already WAITING. The second is the half that was missing — reg.update()\n    // resolves without firing updatefound when a worker is already waiting, so\n    // a tab that missed the original event could never learn about it.\n    const tick = (): void => {\n      check();\n      registration.update().catch(() => {}).then(check, check);\n    };\n    const onFocus = (): void => tick();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        tick();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      registrationRef = registration;\n      check();\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          check();\n          registration\n            .update()\n            .catch(() => {\n              // ignore transient update-check network errors\n            })\n            .then(check, check);\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      // Re-read, never the cached reference: the cached one can be a worker\n      // that has since ACTIVATED, and posting to it does nothing (F054.9).\n      const waiting = registrationRef?.waiting ?? null;\n      if (waiting) {\n        applied = true;\n        // Without clientsClaim an uncontrolled page never gets controllerchange,\n        // so the worker's own activation is the second signal. reloadOnce()\n        // makes the two paths safe to both fire.\n        waiting.addEventListener(\"statechange\", () => {\n          if (waiting.state === \"activated\") reloadOnce();\n        });\n        waiting.postMessage(SKIP_WAITING_MESSAGE);\n        return;\n      }\n      // Nothing waits, yet an update was offered: the worker already took over\n      // (an earlier press whose reload was lost). Reloading IS the update.\n      if (updateReady) reloadOnce();\n    },\n    snooze() {\n      writeSnooze(Date.now() + snoozeMs);\n      check();\n    },\n    check,\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -1,5 +1,57 @@
 export { S as SKIP_WAITING, a as SKIP_WAITING_MESSAGE, b as SkipWaitingMessage } from './message-CBBmtYuB.cjs';
 
+/**
+ * F054.8 — the decision, as a pure function.
+ *
+ * Split out so it can be proven with NO service worker, NO DOM and no fake
+ * container: every branch is reachable from three plain values. The rest of the
+ * updater is plumbing around this.
+ *
+ * Why it is a function and not a flag: the old updater REMEMBERED whether an
+ * update was ready instead of READING whether one is waiting, so the answer
+ * could only ever be given once.
+ */
+interface ShouldOfferInput {
+    /** `registration.waiting` — read fresh at the moment of the decision. */
+    waiting: unknown;
+    /** Epoch ms until which the user has snoozed the offer, or null. */
+    snoozedUntil: number | null;
+    /** Epoch ms now. Passed in so the function stays pure and testable. */
+    now: number;
+}
+/**
+ * Should the consumer be offered the update right now?
+ *
+ * WHY `controller` IS NOT A TERM HERE, though the sketch we were shown had one
+ * and the old code checked it on one of its two paths.
+ *
+ * The old updater answered this question inconsistently: the attach path
+ * (`if (registration.waiting)`) offered with no controller check, while the
+ * `updatefound` path required `container.controller` to suppress a first
+ * install. Same situation, two answers, depending on which path happened to see
+ * it. Making them agree is part of this fix — the question is which way.
+ *
+ * Requiring a controller would be the tighter rule, and it would REMOVE a banner
+ * that some consumer sees today: a page that is not yet controlled (no
+ * `clientsClaim`, or a hard reload) but has a genuine update waiting. With
+ * fd-sundhed live to 16,838 people on the current version, a change in that
+ * direction is not one to make on an unverified reading.
+ *
+ * And the reading in question is this: a worker only enters `waiting` when
+ * another worker is already ACTIVE — on a first install there is nothing to wait
+ * behind, so it activates directly. If that is right, `registration.waiting`
+ * being non-null already implies this is not a first install, and the controller
+ * term is redundant rather than protective. **I have not verified that against a
+ * real service worker.** So the old, more permissive behaviour stays as the
+ * floor, and first-install suppression rides on the same fact rather than on a
+ * second guard that could disagree with it.
+ *
+ * If someone later measures that a first-install worker CAN sit in `waiting`,
+ * this is the function to add the term to — and the test to write first is the
+ * one that fails today.
+ */
+declare function shouldOfferUpdate({ waiting, snoozedUntil, now }: ShouldOfferInput): boolean;
+
 interface PwaUpdaterOptions {
     /** Service-worker script URL to register. Default `/sw.js`. */
     swUrl?: string;
@@ -20,6 +72,20 @@ interface PwaUpdaterOptions {
     updateOnFocus?: boolean;
     /** Reload the page once the new worker takes control. Default `true`. */
     reloadOnControllerChange?: boolean;
+    /**
+     * How long `snooze()` holds the offer down (ms). Default 30 min.
+     *
+     * F054.8 — "Later" is a SNOOZE, never a mute. The defect this replaced was a
+     * banner that got exactly one chance to be seen; a permanent dismiss is that
+     * defect made official.
+     */
+    snoozeMs?: number;
+    /**
+     * Where a snooze is remembered, so it survives the reload the banner is
+     * asking for. Defaults to `localStorage` when available; pass `null` to keep
+     * the snooze in memory only.
+     */
+    snoozeStorage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | null;
     /**
      * Consumer guard. When `true` the updater is an inert no-op (registers
      * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`
@@ -35,8 +101,19 @@ interface PwaUpdater {
     /** Subscribe to state changes. Returns an unsubscribe fn. */
     subscribe(listener: (state: PwaUpdaterState) => void): () => void;
     getState(): PwaUpdaterState;
-    /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */
+    /**
+     * Tell the waiting worker to activate (posts SKIP_WAITING); the page reloads
+     * when it takes over. If an update was offered but nothing waits any more
+     * (it already activated), reloads directly. No-op when nothing was offered.
+     */
     applyUpdate(): void;
+    /**
+     * "Later". Holds the offer down for `snoozeMs`, then it comes back on the
+     * next tick — this is NOT a mute, and it deliberately cannot be made one.
+     */
+    snooze(): void;
+    /** Re-read `registration.waiting` right now and emit if the answer moved. */
+    check(): void;
     /** Stop polling + remove all listeners. */
     destroy(): void;
 }
@@ -52,4 +129,4 @@ interface PwaUpdater {
  */
 declare function createPwaUpdater(options?: PwaUpdaterOptions): PwaUpdater;
 
-export { type PwaUpdater, type PwaUpdaterOptions, type PwaUpdaterState, createPwaUpdater };
+export { type PwaUpdater, type PwaUpdaterOptions, type PwaUpdaterState, type ShouldOfferInput, createPwaUpdater, shouldOfferUpdate };

package/dist/index.d.ts

@@ -1,5 +1,57 @@
 export { S as SKIP_WAITING, a as SKIP_WAITING_MESSAGE, b as SkipWaitingMessage } from './message-CBBmtYuB.js';
 
+/**
+ * F054.8 — the decision, as a pure function.
+ *
+ * Split out so it can be proven with NO service worker, NO DOM and no fake
+ * container: every branch is reachable from three plain values. The rest of the
+ * updater is plumbing around this.
+ *
+ * Why it is a function and not a flag: the old updater REMEMBERED whether an
+ * update was ready instead of READING whether one is waiting, so the answer
+ * could only ever be given once.
+ */
+interface ShouldOfferInput {
+    /** `registration.waiting` — read fresh at the moment of the decision. */
+    waiting: unknown;
+    /** Epoch ms until which the user has snoozed the offer, or null. */
+    snoozedUntil: number | null;
+    /** Epoch ms now. Passed in so the function stays pure and testable. */
+    now: number;
+}
+/**
+ * Should the consumer be offered the update right now?
+ *
+ * WHY `controller` IS NOT A TERM HERE, though the sketch we were shown had one
+ * and the old code checked it on one of its two paths.
+ *
+ * The old updater answered this question inconsistently: the attach path
+ * (`if (registration.waiting)`) offered with no controller check, while the
+ * `updatefound` path required `container.controller` to suppress a first
+ * install. Same situation, two answers, depending on which path happened to see
+ * it. Making them agree is part of this fix — the question is which way.
+ *
+ * Requiring a controller would be the tighter rule, and it would REMOVE a banner
+ * that some consumer sees today: a page that is not yet controlled (no
+ * `clientsClaim`, or a hard reload) but has a genuine update waiting. With
+ * fd-sundhed live to 16,838 people on the current version, a change in that
+ * direction is not one to make on an unverified reading.
+ *
+ * And the reading in question is this: a worker only enters `waiting` when
+ * another worker is already ACTIVE — on a first install there is nothing to wait
+ * behind, so it activates directly. If that is right, `registration.waiting`
+ * being non-null already implies this is not a first install, and the controller
+ * term is redundant rather than protective. **I have not verified that against a
+ * real service worker.** So the old, more permissive behaviour stays as the
+ * floor, and first-install suppression rides on the same fact rather than on a
+ * second guard that could disagree with it.
+ *
+ * If someone later measures that a first-install worker CAN sit in `waiting`,
+ * this is the function to add the term to — and the test to write first is the
+ * one that fails today.
+ */
+declare function shouldOfferUpdate({ waiting, snoozedUntil, now }: ShouldOfferInput): boolean;
+
 interface PwaUpdaterOptions {
     /** Service-worker script URL to register. Default `/sw.js`. */
     swUrl?: string;
@@ -20,6 +72,20 @@ interface PwaUpdaterOptions {
     updateOnFocus?: boolean;
     /** Reload the page once the new worker takes control. Default `true`. */
     reloadOnControllerChange?: boolean;
+    /**
+     * How long `snooze()` holds the offer down (ms). Default 30 min.
+     *
+     * F054.8 — "Later" is a SNOOZE, never a mute. The defect this replaced was a
+     * banner that got exactly one chance to be seen; a permanent dismiss is that
+     * defect made official.
+     */
+    snoozeMs?: number;
+    /**
+     * Where a snooze is remembered, so it survives the reload the banner is
+     * asking for. Defaults to `localStorage` when available; pass `null` to keep
+     * the snooze in memory only.
+     */
+    snoozeStorage?: Pick<Storage, "getItem" | "setItem" | "removeItem"> | null;
     /**
      * Consumer guard. When `true` the updater is an inert no-op (registers
      * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`
@@ -35,8 +101,19 @@ interface PwaUpdater {
     /** Subscribe to state changes. Returns an unsubscribe fn. */
     subscribe(listener: (state: PwaUpdaterState) => void): () => void;
     getState(): PwaUpdaterState;
-    /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */
+    /**
+     * Tell the waiting worker to activate (posts SKIP_WAITING); the page reloads
+     * when it takes over. If an update was offered but nothing waits any more
+     * (it already activated), reloads directly. No-op when nothing was offered.
+     */
     applyUpdate(): void;
+    /**
+     * "Later". Holds the offer down for `snoozeMs`, then it comes back on the
+     * next tick — this is NOT a mute, and it deliberately cannot be made one.
+     */
+    snooze(): void;
+    /** Re-read `registration.waiting` right now and emit if the answer moved. */
+    check(): void;
     /** Stop polling + remove all listeners. */
     destroy(): void;
 }
@@ -52,4 +129,4 @@ interface PwaUpdater {
  */
 declare function createPwaUpdater(options?: PwaUpdaterOptions): PwaUpdater;
 
-export { type PwaUpdater, type PwaUpdaterOptions, type PwaUpdaterState, createPwaUpdater };
+export { type PwaUpdater, type PwaUpdaterOptions, type PwaUpdaterState, type ShouldOfferInput, createPwaUpdater, shouldOfferUpdate };