@broberg/pwa 0.1.0

package/dist/react.cjs

@@ -0,0 +1,189 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react.tsx
+
+// src/message.ts
+var SKIP_WAITING = "SKIP_WAITING";
+var SKIP_WAITING_MESSAGE = { type: SKIP_WAITING };
+
+// src/index.ts
+var DEFAULT_POLL_MS = 60 * 60 * 1e3;
+function createPwaUpdater(options = {}) {
+  const {
+    swUrl = "/sw.js",
+    register = true,
+    pollIntervalMs = DEFAULT_POLL_MS,
+    updateOnFocus = true,
+    reloadOnControllerChange = true,
+    disabled = false
+  } = options;
+  const listeners = /* @__PURE__ */ new Set();
+  let updateReady = false;
+  let waitingWorker = null;
+  const getState = () => ({ updateReady });
+  const emit = () => {
+    const state = getState();
+    for (const listener of listeners) listener(state);
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  const supported = typeof navigator !== "undefined" && "serviceWorker" in navigator;
+  if (disabled || !supported) {
+    return {
+      subscribe,
+      getState,
+      applyUpdate() {
+      },
+      destroy() {
+        listeners.clear();
+      }
+    };
+  }
+  const container = navigator.serviceWorker;
+  let pollId = null;
+  let removeFocusListeners = null;
+  let reloading = false;
+  let destroyed = false;
+  const markReady = (worker) => {
+    waitingWorker = worker;
+    if (!updateReady) {
+      updateReady = true;
+      emit();
+    }
+  };
+  const onControllerChange = () => {
+    if (!reloadOnControllerChange || reloading) return;
+    reloading = true;
+    if (typeof location !== "undefined") location.reload();
+  };
+  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);
+      }
+    });
+  };
+  const wireFocusChecks = (registration) => {
+    if (!updateOnFocus) return;
+    const check = () => {
+      registration.update().catch(() => {
+      });
+    };
+    const onFocus = () => check();
+    const onVisibility = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "visible") {
+        check();
+      }
+    };
+    if (typeof window !== "undefined") window.addEventListener("focus", onFocus);
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", onVisibility);
+    }
+    removeFocusListeners = () => {
+      if (typeof window !== "undefined") window.removeEventListener("focus", onFocus);
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", onVisibility);
+      }
+    };
+  };
+  const registrationPromise = register ? container.register(swUrl) : container.ready;
+  registrationPromise.then((registration) => {
+    if (destroyed) return;
+    if (registration.waiting) markReady(registration.waiting);
+    registration.addEventListener("updatefound", () => watchInstalling(registration));
+    if (pollIntervalMs > 0) {
+      pollId = setInterval(() => {
+        registration.update().catch(() => {
+        });
+      }, pollIntervalMs);
+    }
+    wireFocusChecks(registration);
+  }).catch(() => {
+  });
+  return {
+    subscribe,
+    getState,
+    applyUpdate() {
+      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);
+    },
+    destroy() {
+      destroyed = true;
+      if (pollId !== null) clearInterval(pollId);
+      removeFocusListeners?.();
+      container.removeEventListener("controllerchange", onControllerChange);
+      listeners.clear();
+    }
+  };
+}
+function usePwaUpdate(options = {}) {
+  const { swUrl, pollIntervalMs, reloadOnControllerChange, disabled } = options;
+  const [updateReady, setUpdateReady] = react.useState(false);
+  const updaterRef = react.useRef(null);
+  react.useEffect(() => {
+    const updater = createPwaUpdater({
+      swUrl,
+      pollIntervalMs,
+      reloadOnControllerChange,
+      disabled
+    });
+    updaterRef.current = updater;
+    setUpdateReady(updater.getState().updateReady);
+    const unsubscribe = updater.subscribe((state) => setUpdateReady(state.updateReady));
+    return () => {
+      unsubscribe();
+      updater.destroy();
+      updaterRef.current = null;
+    };
+  }, [swUrl, pollIntervalMs, reloadOnControllerChange, disabled]);
+  return {
+    updateReady,
+    applyUpdate: () => updaterRef.current?.applyUpdate()
+  };
+}
+var DEFAULT_LABELS = {
+  title: "New version available",
+  body: "Reload to get the latest version.",
+  update: "Update",
+  dismiss: "Later",
+  close: "Close"
+};
+function PwaUpdateBanner({
+  updateReady,
+  onUpdate,
+  onDismiss,
+  labels,
+  className
+}) {
+  if (!updateReady) return null;
+  const l = { ...DEFAULT_LABELS, ...labels };
+  const dismiss = () => onDismiss?.();
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { role: "status", "aria-live": "polite", "data-testid": "pwa-update-banner", className, children: [
+    /* @__PURE__ */ jsxRuntime.jsx("p", { "data-testid": "pwa-update-title", children: l.title }),
+    l.body ? /* @__PURE__ */ jsxRuntime.jsx("p", { "data-testid": "pwa-update-body", children: l.body }) : null,
+    /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", "data-testid": "pwa-update-confirm", onClick: onUpdate, children: l.update }),
+    /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", "data-testid": "pwa-update-dismiss", onClick: dismiss, children: l.dismiss }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        "data-testid": "pwa-update-close",
+        "aria-label": l.close,
+        onClick: dismiss,
+        children: "\xD7"
+      }
+    )
+  ] });
+}
+
+exports.PwaUpdateBanner = PwaUpdateBanner;
+exports.usePwaUpdate = usePwaUpdate;
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map

package/dist/react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/message.ts","../src/index.ts","../src/react.tsx"],"names":["useState","useRef","useEffect","jsxs","jsx"],"mappings":"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","file":"react.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  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\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","import { useEffect, useRef, useState } from \"react\";\nimport { createPwaUpdater, type PwaUpdater, type PwaUpdaterOptions } from \"./index.js\";\n\n/**\n * React binding for {@link createPwaUpdater}. Returns whether an update is\n * ready plus the `applyUpdate` action. The controller is created once and\n * torn down on unmount.\n */\nexport function usePwaUpdate(options: PwaUpdaterOptions = {}): {\n  updateReady: boolean;\n  applyUpdate: () => void;\n} {\n  const { swUrl, pollIntervalMs, reloadOnControllerChange, disabled } = options;\n  const [updateReady, setUpdateReady] = useState(false);\n  const updaterRef = useRef<PwaUpdater | null>(null);\n\n  useEffect(() => {\n    const updater = createPwaUpdater({\n      swUrl,\n      pollIntervalMs,\n      reloadOnControllerChange,\n      disabled,\n    });\n    updaterRef.current = updater;\n    setUpdateReady(updater.getState().updateReady);\n    const unsubscribe = updater.subscribe((state) => setUpdateReady(state.updateReady));\n    return () => {\n      unsubscribe();\n      updater.destroy();\n      updaterRef.current = null;\n    };\n  }, [swUrl, pollIntervalMs, reloadOnControllerChange, disabled]);\n\n  return {\n    updateReady,\n    applyUpdate: () => updaterRef.current?.applyUpdate(),\n  };\n}\n\nexport interface PwaUpdateBannerLabels {\n  title?: string;\n  body?: string;\n  update?: string;\n  dismiss?: string;\n  close?: string;\n}\n\nconst DEFAULT_LABELS: Required<PwaUpdateBannerLabels> = {\n  title: \"New version available\",\n  body: \"Reload to get the latest version.\",\n  update: \"Update\",\n  dismiss: \"Later\",\n  close: \"Close\",\n};\n\nexport interface PwaUpdateBannerProps {\n  /** From `usePwaUpdate().updateReady`. Nothing renders when false. */\n  updateReady: boolean;\n  /** From `usePwaUpdate().applyUpdate`. */\n  onUpdate: () => void;\n  /** Optional dismiss handler (wired to both \"Later\" and the close ✕). */\n  onDismiss?: () => void;\n  /** Override any of the built-in strings (i18n). */\n  labels?: PwaUpdateBannerLabels;\n  /** Your class(es) — the skeleton carries NO colours or design-system styling. */\n  className?: string;\n}\n\n/**\n * Unstyled, accessible \"new version available\" banner skeleton. It ships\n * structure + a11y + stable testids only; you own the look via `className`\n * and your design tokens. Prefer {@link usePwaUpdate} directly if you'd rather\n * build the UI yourself.\n */\nexport function PwaUpdateBanner({\n  updateReady,\n  onUpdate,\n  onDismiss,\n  labels,\n  className,\n}: PwaUpdateBannerProps) {\n  if (!updateReady) return null;\n  const l = { ...DEFAULT_LABELS, ...labels };\n  const dismiss = () => onDismiss?.();\n  return (\n    <div role=\"status\" aria-live=\"polite\" data-testid=\"pwa-update-banner\" className={className}>\n      <p data-testid=\"pwa-update-title\">{l.title}</p>\n      {l.body ? <p data-testid=\"pwa-update-body\">{l.body}</p> : null}\n      <button type=\"button\" data-testid=\"pwa-update-confirm\" onClick={onUpdate}>\n        {l.update}\n      </button>\n      <button type=\"button\" data-testid=\"pwa-update-dismiss\" onClick={dismiss}>\n        {l.dismiss}\n      </button>\n      <button\n        type=\"button\"\n        data-testid=\"pwa-update-close\"\n        aria-label={l.close}\n        onClick={dismiss}\n      >\n        {\"×\"}\n      </button>\n    </div>\n  );\n}\n"]}

package/dist/react.d.cts

@@ -0,0 +1,67 @@
+import * as react from 'react';
+
+interface PwaUpdaterOptions {
+    /** Service-worker script URL to register. Default `/sw.js`. */
+    swUrl?: string;
+    /**
+     * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the
+     * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)
+     * — the updater then attaches to the existing registration via
+     * `navigator.serviceWorker.ready` instead of registering again. Default `true`.
+     */
+    register?: boolean;
+    /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */
+    pollIntervalMs?: number;
+    /**
+     * Also check for an update when the tab regains focus / becomes visible.
+     * A constantly-focused tab never fires `visibilitychange`, so `focus` is the
+     * one that catches "user came back to the app". Default `true`.
+     */
+    updateOnFocus?: boolean;
+    /** Reload the page once the new worker takes control. Default `true`. */
+    reloadOnControllerChange?: boolean;
+    /**
+     * Consumer guard. When `true` the updater is an inert no-op (registers
+     * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`
+     * — the package never hardcodes an environment or a `.native` check.
+     */
+    disabled?: boolean;
+}
+
+/**
+ * React binding for {@link createPwaUpdater}. Returns whether an update is
+ * ready plus the `applyUpdate` action. The controller is created once and
+ * torn down on unmount.
+ */
+declare function usePwaUpdate(options?: PwaUpdaterOptions): {
+    updateReady: boolean;
+    applyUpdate: () => void;
+};
+interface PwaUpdateBannerLabels {
+    title?: string;
+    body?: string;
+    update?: string;
+    dismiss?: string;
+    close?: string;
+}
+interface PwaUpdateBannerProps {
+    /** From `usePwaUpdate().updateReady`. Nothing renders when false. */
+    updateReady: boolean;
+    /** From `usePwaUpdate().applyUpdate`. */
+    onUpdate: () => void;
+    /** Optional dismiss handler (wired to both "Later" and the close ✕). */
+    onDismiss?: () => void;
+    /** Override any of the built-in strings (i18n). */
+    labels?: PwaUpdateBannerLabels;
+    /** Your class(es) — the skeleton carries NO colours or design-system styling. */
+    className?: string;
+}
+/**
+ * Unstyled, accessible "new version available" banner skeleton. It ships
+ * structure + a11y + stable testids only; you own the look via `className`
+ * and your design tokens. Prefer {@link usePwaUpdate} directly if you'd rather
+ * build the UI yourself.
+ */
+declare function PwaUpdateBanner({ updateReady, onUpdate, onDismiss, labels, className, }: PwaUpdateBannerProps): react.JSX.Element | null;
+
+export { PwaUpdateBanner, type PwaUpdateBannerLabels, type PwaUpdateBannerProps, usePwaUpdate };

package/dist/react.d.ts

@@ -0,0 +1,67 @@
+import * as react from 'react';
+
+interface PwaUpdaterOptions {
+    /** Service-worker script URL to register. Default `/sw.js`. */
+    swUrl?: string;
+    /**
+     * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the
+     * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)
+     * — the updater then attaches to the existing registration via
+     * `navigator.serviceWorker.ready` instead of registering again. Default `true`.
+     */
+    register?: boolean;
+    /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */
+    pollIntervalMs?: number;
+    /**
+     * Also check for an update when the tab regains focus / becomes visible.
+     * A constantly-focused tab never fires `visibilitychange`, so `focus` is the
+     * one that catches "user came back to the app". Default `true`.
+     */
+    updateOnFocus?: boolean;
+    /** Reload the page once the new worker takes control. Default `true`. */
+    reloadOnControllerChange?: boolean;
+    /**
+     * Consumer guard. When `true` the updater is an inert no-op (registers
+     * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`
+     * — the package never hardcodes an environment or a `.native` check.
+     */
+    disabled?: boolean;
+}
+
+/**
+ * React binding for {@link createPwaUpdater}. Returns whether an update is
+ * ready plus the `applyUpdate` action. The controller is created once and
+ * torn down on unmount.
+ */
+declare function usePwaUpdate(options?: PwaUpdaterOptions): {
+    updateReady: boolean;
+    applyUpdate: () => void;
+};
+interface PwaUpdateBannerLabels {
+    title?: string;
+    body?: string;
+    update?: string;
+    dismiss?: string;
+    close?: string;
+}
+interface PwaUpdateBannerProps {
+    /** From `usePwaUpdate().updateReady`. Nothing renders when false. */
+    updateReady: boolean;
+    /** From `usePwaUpdate().applyUpdate`. */
+    onUpdate: () => void;
+    /** Optional dismiss handler (wired to both "Later" and the close ✕). */
+    onDismiss?: () => void;
+    /** Override any of the built-in strings (i18n). */
+    labels?: PwaUpdateBannerLabels;
+    /** Your class(es) — the skeleton carries NO colours or design-system styling. */
+    className?: string;
+}
+/**
+ * Unstyled, accessible "new version available" banner skeleton. It ships
+ * structure + a11y + stable testids only; you own the look via `className`
+ * and your design tokens. Prefer {@link usePwaUpdate} directly if you'd rather
+ * build the UI yourself.
+ */
+declare function PwaUpdateBanner({ updateReady, onUpdate, onDismiss, labels, className, }: PwaUpdateBannerProps): react.JSX.Element | null;
+
+export { PwaUpdateBanner, type PwaUpdateBannerLabels, type PwaUpdateBannerProps, usePwaUpdate };

package/dist/react.js

@@ -0,0 +1,186 @@
+import { useState, useRef, useEffect } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/react.tsx
+
+// src/message.ts
+var SKIP_WAITING = "SKIP_WAITING";
+var SKIP_WAITING_MESSAGE = { type: SKIP_WAITING };
+
+// src/index.ts
+var DEFAULT_POLL_MS = 60 * 60 * 1e3;
+function createPwaUpdater(options = {}) {
+  const {
+    swUrl = "/sw.js",
+    register = true,
+    pollIntervalMs = DEFAULT_POLL_MS,
+    updateOnFocus = true,
+    reloadOnControllerChange = true,
+    disabled = false
+  } = options;
+  const listeners = /* @__PURE__ */ new Set();
+  let updateReady = false;
+  let waitingWorker = null;
+  const getState = () => ({ updateReady });
+  const emit = () => {
+    const state = getState();
+    for (const listener of listeners) listener(state);
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  const supported = typeof navigator !== "undefined" && "serviceWorker" in navigator;
+  if (disabled || !supported) {
+    return {
+      subscribe,
+      getState,
+      applyUpdate() {
+      },
+      destroy() {
+        listeners.clear();
+      }
+    };
+  }
+  const container = navigator.serviceWorker;
+  let pollId = null;
+  let removeFocusListeners = null;
+  let reloading = false;
+  let destroyed = false;
+  const markReady = (worker) => {
+    waitingWorker = worker;
+    if (!updateReady) {
+      updateReady = true;
+      emit();
+    }
+  };
+  const onControllerChange = () => {
+    if (!reloadOnControllerChange || reloading) return;
+    reloading = true;
+    if (typeof location !== "undefined") location.reload();
+  };
+  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);
+      }
+    });
+  };
+  const wireFocusChecks = (registration) => {
+    if (!updateOnFocus) return;
+    const check = () => {
+      registration.update().catch(() => {
+      });
+    };
+    const onFocus = () => check();
+    const onVisibility = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "visible") {
+        check();
+      }
+    };
+    if (typeof window !== "undefined") window.addEventListener("focus", onFocus);
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", onVisibility);
+    }
+    removeFocusListeners = () => {
+      if (typeof window !== "undefined") window.removeEventListener("focus", onFocus);
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", onVisibility);
+      }
+    };
+  };
+  const registrationPromise = register ? container.register(swUrl) : container.ready;
+  registrationPromise.then((registration) => {
+    if (destroyed) return;
+    if (registration.waiting) markReady(registration.waiting);
+    registration.addEventListener("updatefound", () => watchInstalling(registration));
+    if (pollIntervalMs > 0) {
+      pollId = setInterval(() => {
+        registration.update().catch(() => {
+        });
+      }, pollIntervalMs);
+    }
+    wireFocusChecks(registration);
+  }).catch(() => {
+  });
+  return {
+    subscribe,
+    getState,
+    applyUpdate() {
+      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);
+    },
+    destroy() {
+      destroyed = true;
+      if (pollId !== null) clearInterval(pollId);
+      removeFocusListeners?.();
+      container.removeEventListener("controllerchange", onControllerChange);
+      listeners.clear();
+    }
+  };
+}
+function usePwaUpdate(options = {}) {
+  const { swUrl, pollIntervalMs, reloadOnControllerChange, disabled } = options;
+  const [updateReady, setUpdateReady] = useState(false);
+  const updaterRef = useRef(null);
+  useEffect(() => {
+    const updater = createPwaUpdater({
+      swUrl,
+      pollIntervalMs,
+      reloadOnControllerChange,
+      disabled
+    });
+    updaterRef.current = updater;
+    setUpdateReady(updater.getState().updateReady);
+    const unsubscribe = updater.subscribe((state) => setUpdateReady(state.updateReady));
+    return () => {
+      unsubscribe();
+      updater.destroy();
+      updaterRef.current = null;
+    };
+  }, [swUrl, pollIntervalMs, reloadOnControllerChange, disabled]);
+  return {
+    updateReady,
+    applyUpdate: () => updaterRef.current?.applyUpdate()
+  };
+}
+var DEFAULT_LABELS = {
+  title: "New version available",
+  body: "Reload to get the latest version.",
+  update: "Update",
+  dismiss: "Later",
+  close: "Close"
+};
+function PwaUpdateBanner({
+  updateReady,
+  onUpdate,
+  onDismiss,
+  labels,
+  className
+}) {
+  if (!updateReady) return null;
+  const l = { ...DEFAULT_LABELS, ...labels };
+  const dismiss = () => onDismiss?.();
+  return /* @__PURE__ */ jsxs("div", { role: "status", "aria-live": "polite", "data-testid": "pwa-update-banner", className, children: [
+    /* @__PURE__ */ jsx("p", { "data-testid": "pwa-update-title", children: l.title }),
+    l.body ? /* @__PURE__ */ jsx("p", { "data-testid": "pwa-update-body", children: l.body }) : null,
+    /* @__PURE__ */ jsx("button", { type: "button", "data-testid": "pwa-update-confirm", onClick: onUpdate, children: l.update }),
+    /* @__PURE__ */ jsx("button", { type: "button", "data-testid": "pwa-update-dismiss", onClick: dismiss, children: l.dismiss }),
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        "data-testid": "pwa-update-close",
+        "aria-label": l.close,
+        onClick: dismiss,
+        children: "\xD7"
+      }
+    )
+  ] });
+}
+
+export { PwaUpdateBanner, usePwaUpdate };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/message.ts","../src/index.ts","../src/react.tsx"],"names":[],"mappings":"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","file":"react.js","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  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\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","import { useEffect, useRef, useState } from \"react\";\nimport { createPwaUpdater, type PwaUpdater, type PwaUpdaterOptions } from \"./index.js\";\n\n/**\n * React binding for {@link createPwaUpdater}. Returns whether an update is\n * ready plus the `applyUpdate` action. The controller is created once and\n * torn down on unmount.\n */\nexport function usePwaUpdate(options: PwaUpdaterOptions = {}): {\n  updateReady: boolean;\n  applyUpdate: () => void;\n} {\n  const { swUrl, pollIntervalMs, reloadOnControllerChange, disabled } = options;\n  const [updateReady, setUpdateReady] = useState(false);\n  const updaterRef = useRef<PwaUpdater | null>(null);\n\n  useEffect(() => {\n    const updater = createPwaUpdater({\n      swUrl,\n      pollIntervalMs,\n      reloadOnControllerChange,\n      disabled,\n    });\n    updaterRef.current = updater;\n    setUpdateReady(updater.getState().updateReady);\n    const unsubscribe = updater.subscribe((state) => setUpdateReady(state.updateReady));\n    return () => {\n      unsubscribe();\n      updater.destroy();\n      updaterRef.current = null;\n    };\n  }, [swUrl, pollIntervalMs, reloadOnControllerChange, disabled]);\n\n  return {\n    updateReady,\n    applyUpdate: () => updaterRef.current?.applyUpdate(),\n  };\n}\n\nexport interface PwaUpdateBannerLabels {\n  title?: string;\n  body?: string;\n  update?: string;\n  dismiss?: string;\n  close?: string;\n}\n\nconst DEFAULT_LABELS: Required<PwaUpdateBannerLabels> = {\n  title: \"New version available\",\n  body: \"Reload to get the latest version.\",\n  update: \"Update\",\n  dismiss: \"Later\",\n  close: \"Close\",\n};\n\nexport interface PwaUpdateBannerProps {\n  /** From `usePwaUpdate().updateReady`. Nothing renders when false. */\n  updateReady: boolean;\n  /** From `usePwaUpdate().applyUpdate`. */\n  onUpdate: () => void;\n  /** Optional dismiss handler (wired to both \"Later\" and the close ✕). */\n  onDismiss?: () => void;\n  /** Override any of the built-in strings (i18n). */\n  labels?: PwaUpdateBannerLabels;\n  /** Your class(es) — the skeleton carries NO colours or design-system styling. */\n  className?: string;\n}\n\n/**\n * Unstyled, accessible \"new version available\" banner skeleton. It ships\n * structure + a11y + stable testids only; you own the look via `className`\n * and your design tokens. Prefer {@link usePwaUpdate} directly if you'd rather\n * build the UI yourself.\n */\nexport function PwaUpdateBanner({\n  updateReady,\n  onUpdate,\n  onDismiss,\n  labels,\n  className,\n}: PwaUpdateBannerProps) {\n  if (!updateReady) return null;\n  const l = { ...DEFAULT_LABELS, ...labels };\n  const dismiss = () => onDismiss?.();\n  return (\n    <div role=\"status\" aria-live=\"polite\" data-testid=\"pwa-update-banner\" className={className}>\n      <p data-testid=\"pwa-update-title\">{l.title}</p>\n      {l.body ? <p data-testid=\"pwa-update-body\">{l.body}</p> : null}\n      <button type=\"button\" data-testid=\"pwa-update-confirm\" onClick={onUpdate}>\n        {l.update}\n      </button>\n      <button type=\"button\" data-testid=\"pwa-update-dismiss\" onClick={dismiss}>\n        {l.dismiss}\n      </button>\n      <button\n        type=\"button\"\n        data-testid=\"pwa-update-close\"\n        aria-label={l.close}\n        onClick={dismiss}\n      >\n        {\"×\"}\n      </button>\n    </div>\n  );\n}\n"]}

package/dist/sw.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+// src/message.ts
+var SKIP_WAITING = "SKIP_WAITING";
+var SKIP_WAITING_MESSAGE = { type: SKIP_WAITING };
+
+// src/sw.ts
+function listenForSkipWaiting(scope) {
+  const target = scope ?? globalThis;
+  target.addEventListener("message", (event) => {
+    if (event.data?.type === SKIP_WAITING) {
+      void target.skipWaiting();
+    }
+  });
+}
+
+exports.SKIP_WAITING = SKIP_WAITING;
+exports.SKIP_WAITING_MESSAGE = SKIP_WAITING_MESSAGE;
+exports.listenForSkipWaiting = listenForSkipWaiting;
+//# sourceMappingURL=sw.cjs.map
+//# sourceMappingURL=sw.cjs.map

package/dist/sw.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/message.ts","../src/sw.ts"],"names":[],"mappings":";;;AAKO,IAAM,YAAA,GAAe;AAErB,IAAM,oBAAA,GAAuB,EAAE,IAAA,EAAM,YAAA;;;ACyBrC,SAAS,qBAAqB,KAAA,EAAgC;AACnE,EAAA,MAAM,SACJ,KAAA,IAAU,UAAA;AACZ,EAAA,MAAA,CAAO,gBAAA,CAAiB,SAAA,EAAW,CAAC,KAAA,KAAU;AAC5C,IAAA,IAAK,KAAA,CAAM,IAAA,EAA4B,IAAA,KAAS,YAAA,EAAc;AAC5D,MAAA,KAAK,OAAO,WAAA,EAAY;AAAA,IAC1B;AAAA,EACF,CAAC,CAAA;AACH","file":"sw.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 } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\n/**\n * The minimal slice of a service-worker global scope this helper needs.\n * Kept as a local interface so the package doesn't pull in the `webworker`\n * TS lib (which clashes with `dom`) and stays trivially testable.\n */\nexport interface SkipWaitingScope {\n  addEventListener(\n    type: \"message\",\n    listener: (event: { data?: unknown }) => void,\n  ): void;\n  skipWaiting(): Promise<void> | void;\n}\n\n/**\n * Wire the service-worker side of the update handshake: when the client calls\n * `applyUpdate()` (posts `SKIP_WAITING`), the worker activates immediately.\n *\n * Call it once inside your service worker, before other setup:\n *\n * ```ts\n * import { listenForSkipWaiting } from \"@broberg/pwa/sw\";\n * listenForSkipWaiting();\n * ```\n *\n * Serwist/Workbox users: keep `skipWaiting: false` (so activation is\n * user-gated by the banner, not automatic) and `clientsClaim: true`.\n */\nexport function listenForSkipWaiting(scope?: SkipWaitingScope): void {\n  const target =\n    scope ?? (globalThis as unknown as SkipWaitingScope);\n  target.addEventListener(\"message\", (event) => {\n    if ((event.data as { type?: string })?.type === SKIP_WAITING) {\n      void target.skipWaiting();\n    }\n  });\n}\n"]}

package/dist/sw.d.cts

@@ -0,0 +1,30 @@
+export { S as SKIP_WAITING, a as SKIP_WAITING_MESSAGE, b as SkipWaitingMessage } from './message-CBBmtYuB.cjs';
+
+/**
+ * The minimal slice of a service-worker global scope this helper needs.
+ * Kept as a local interface so the package doesn't pull in the `webworker`
+ * TS lib (which clashes with `dom`) and stays trivially testable.
+ */
+interface SkipWaitingScope {
+    addEventListener(type: "message", listener: (event: {
+        data?: unknown;
+    }) => void): void;
+    skipWaiting(): Promise<void> | void;
+}
+/**
+ * Wire the service-worker side of the update handshake: when the client calls
+ * `applyUpdate()` (posts `SKIP_WAITING`), the worker activates immediately.
+ *
+ * Call it once inside your service worker, before other setup:
+ *
+ * ```ts
+ * import { listenForSkipWaiting } from "@broberg/pwa/sw";
+ * listenForSkipWaiting();
+ * ```
+ *
+ * Serwist/Workbox users: keep `skipWaiting: false` (so activation is
+ * user-gated by the banner, not automatic) and `clientsClaim: true`.
+ */
+declare function listenForSkipWaiting(scope?: SkipWaitingScope): void;
+
+export { type SkipWaitingScope, listenForSkipWaiting };