@develemit/web-hooks 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.1 - 2026-11-06
+
+- `service-worker`: `useServiceWorker({ onError })` and `registerServiceWorker({ onError })`. Called with the rejection when `register()` fails (not after unmount or dispose). The latest callback is used; a throwing callback is swallowed. Registration failure still never throws into React.
+- `push`: an empty or whitespace `vapidPublicKey` is "not ready". The on-load re-subscribe waits for the key and runs once when it arrives; `subscribe()` sets `error` to `'push key not ready'` and never prompts or calls `pushManager.subscribe`. `shouldResubscribe` takes an optional `hasKey` (default `true`); new `isKeyReady`.
+- `service-worker`: a worker that skips waiting no longer makes the tab reload unasked on `controllerchange`. The hook reports `updateAvailable` and `applyUpdate()` reloads once. **Behaviour change:** this also replaces the old behaviour of following another tab's update with an automatic reload; that tab now shows the update prompt instead. No app relied on the old behaviour, so it ships as a patch.
+
 ## 0.3.0 - 2026-11-06
 
 - `push`: `usePushSubscription({ vapidPublicKey, onSubscribe, onUnsubscribe, resubscribeOnLoad = true })` returning `{ support, permission, subscribed, busy, error, subscribe, unsubscribe }`, plus `urlBase64ToUint8Array`, `getPushSupport` (`'supported' | 'unsupported' | 'ios-needs-install'`) and the pure `shouldResubscribe`. The VAPID key is always converted to a `Uint8Array`, the browser's `pushManager.getSubscription()` is the source of truth, mounting never asks for permission, a dropped iOS subscription is re-made silently when permission is already granted, and an `onSubscribe` rejection with `status` 410 unsubscribes and subscribes once more. The package makes no HTTP requests; the app's callbacks do.

package/README.md

@@ -301,6 +301,7 @@ const { updateAvailable, applyUpdate, supported } = useServiceWorker({
   url: '/sw.js',
   scope: '/',
   enabled: process.env.NODE_ENV === 'production',
+  onError: (error) => captureError(error), // registration failed; never throws into React
 });
 if (updateAvailable) showBanner({ onTap: applyUpdate });
 ```
@@ -315,6 +316,12 @@ self.addEventListener('message', (event) => {
 });
 ```
 
+Workers that call `self.skipWaiting()` on install (as emit-infra's does) take
+control with no waiting stage. The page is never reloaded unasked: when a new
+worker takes control of a tab that was already controlled, `updateAvailable`
+becomes `true` and `applyUpdate()` reloads the page once. The same applies when
+another tab applied the update.
+
 A first install (no controller yet) is not reported as an update. In dev, call
 `unregisterAll()` to clear workers left by a production build. Browsers without
 service workers get `supported: false`.
@@ -373,6 +380,11 @@ if (push.support === 'ios-needs-install') return <InstallHint />;
 <button onClick={push.subscribe} disabled={push.busy}>Enable</button>
 ```
 
+`vapidPublicKey` may be `''` while the app is still fetching it. Until it is
+non-blank, the on-load re-subscribe is skipped (and runs once when the key
+arrives) and `subscribe()` sets `error` to `'push key not ready'` without
+asking for permission or touching the push manager.
+
 Returns `{ support, permission, subscribed, busy, error, subscribe, unsubscribe }`.
 `support` is `'supported'`, `'unsupported'` or `'ios-needs-install'`: iOS only
 allows Web Push in an installed PWA (16.4+), so an iPhone Safari tab (or any

package/dist/{chunk-UJ366T3Y.js → chunk-R2PFNE3U.js}

@@ -27,8 +27,11 @@ function readPermission() {
   if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
   return Notification.permission;
 }
-function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad }) {
-  return resubscribeOnLoad && permission === "granted" && !hasSubscription;
+function isKeyReady(key) {
+  return key.trim().length > 0;
+}
+function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad, hasKey = true }) {
+  return hasKey && resubscribeOnLoad && permission === "granted" && !hasSubscription;
 }
 function isGone(error) {
   return typeof error === "object" && error !== null && error.status === 410;
@@ -74,6 +77,7 @@ function usePushSubscription(options) {
   const [subscribed, setSubscribed] = useState(false);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState(null);
+  const hasKey = isKeyReady(options.vapidPublicKey);
   const latest = useRef(options);
   latest.current = options;
   useEffect(() => {
@@ -90,7 +94,7 @@ function usePushSubscription(options) {
         const permissionNow = readPermission();
         setPermission(permissionNow);
         if (existing) return setSubscribed(true);
-        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad })) return;
+        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad, hasKey })) return;
         await ensureSubscribed(reg, latest.current);
         if (!cancelled) setSubscribed(true);
       } catch {
@@ -99,9 +103,13 @@ function usePushSubscription(options) {
     return () => {
       cancelled = true;
     };
-  }, [resubscribeOnLoad]);
+  }, [resubscribeOnLoad, hasKey]);
   const subscribe = useCallback(async () => {
     if (getPushSupport() !== "supported") return;
+    if (!isKeyReady(latest.current.vapidPublicKey)) {
+      setError("push key not ready");
+      return;
+    }
     setError(null);
     setBusy(true);
     try {

package/dist/{chunk-JG3GPTMY.js → chunk-UVJBJETY.js}

@@ -23,17 +23,24 @@ async function unregisterAll() {
   } catch {
   }
 }
-function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = () => window.location.reload() } = {}) {
+function registerServiceWorker({ url, scope, onUpdateAvailable, onError }, { reload = () => window.location.reload() } = {}) {
   let registration;
   let disposed = false;
   let applying = false;
   const cleanups = [];
   const controlledAtStart = hasController();
-  const onControllerChange = () => {
-    if (!(applying || controlledAtStart) || reloaded) return;
+  let activatedUnasked = false;
+  const reloadOnce = () => {
+    if (reloaded) return;
     reloaded = true;
     reload();
   };
+  const onControllerChange = () => {
+    if (applying) return reloadOnce();
+    if (!controlledAtStart || activatedUnasked) return;
+    activatedUnasked = true;
+    onUpdateAvailable();
+  };
   navigator.serviceWorker.addEventListener("controllerchange", onControllerChange);
   cleanups.push(() => navigator.serviceWorker.removeEventListener("controllerchange", onControllerChange));
   const watchInstalling = (reg) => {
@@ -56,10 +63,16 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
     const onUpdateFound = () => watchInstalling(reg);
     reg.addEventListener("updatefound", onUpdateFound);
     cleanups.push(() => reg.removeEventListener("updatefound", onUpdateFound));
-  }).catch(() => {
+  }).catch((error) => {
+    if (disposed) return;
+    try {
+      onError?.(error);
+    } catch {
+    }
   });
   return {
     applyUpdate() {
+      if (activatedUnasked) return reloadOnce();
       const waiting = registration?.waiting;
       if (!waiting) return;
       applying = true;
@@ -73,9 +86,11 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
 }
 
 // src/service-worker/use-service-worker.ts
-function useServiceWorker({ url, scope, enabled = true }) {
+function useServiceWorker({ url, scope, enabled = true, onError }) {
   const [supported, setSupported] = useState(true);
   const [updateAvailable, setUpdateAvailable] = useState(false);
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
   const handle = useRef(void 0);
   useEffect(() => {
     if (!enabled) return;
@@ -83,7 +98,12 @@ function useServiceWorker({ url, scope, enabled = true }) {
       setSupported(false);
       return;
     }
-    const registered = registerServiceWorker({ url, scope, onUpdateAvailable: () => setUpdateAvailable(true) });
+    const registered = registerServiceWorker({
+      url,
+      scope,
+      onUpdateAvailable: () => setUpdateAvailable(true),
+      onError: (error) => onErrorRef.current?.(error)
+    });
     handle.current = registered;
     return () => {
       registered.dispose();

package/dist/index.cjs

@@ -1089,17 +1089,24 @@ async function unregisterAll() {
   } catch {
   }
 }
-function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = () => window.location.reload() } = {}) {
+function registerServiceWorker({ url, scope, onUpdateAvailable, onError }, { reload = () => window.location.reload() } = {}) {
   let registration;
   let disposed = false;
   let applying = false;
   const cleanups = [];
   const controlledAtStart = hasController();
-  const onControllerChange = () => {
-    if (!(applying || controlledAtStart) || reloaded) return;
+  let activatedUnasked = false;
+  const reloadOnce = () => {
+    if (reloaded) return;
     reloaded = true;
     reload();
   };
+  const onControllerChange = () => {
+    if (applying) return reloadOnce();
+    if (!controlledAtStart || activatedUnasked) return;
+    activatedUnasked = true;
+    onUpdateAvailable();
+  };
   navigator.serviceWorker.addEventListener("controllerchange", onControllerChange);
   cleanups.push(() => navigator.serviceWorker.removeEventListener("controllerchange", onControllerChange));
   const watchInstalling = (reg) => {
@@ -1122,10 +1129,16 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
     const onUpdateFound = () => watchInstalling(reg);
     reg.addEventListener("updatefound", onUpdateFound);
     cleanups.push(() => reg.removeEventListener("updatefound", onUpdateFound));
-  }).catch(() => {
+  }).catch((error) => {
+    if (disposed) return;
+    try {
+      onError?.(error);
+    } catch {
+    }
   });
   return {
     applyUpdate() {
+      if (activatedUnasked) return reloadOnce();
       const waiting = registration?.waiting;
       if (!waiting) return;
       applying = true;
@@ -1139,9 +1152,11 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
 }
 
 // src/service-worker/use-service-worker.ts
-function useServiceWorker({ url, scope, enabled = true }) {
+function useServiceWorker({ url, scope, enabled = true, onError }) {
   const [supported, setSupported] = (0, import_react18.useState)(true);
   const [updateAvailable, setUpdateAvailable] = (0, import_react18.useState)(false);
+  const onErrorRef = (0, import_react18.useRef)(onError);
+  onErrorRef.current = onError;
   const handle = (0, import_react18.useRef)(void 0);
   (0, import_react18.useEffect)(() => {
     if (!enabled) return;
@@ -1149,7 +1164,12 @@ function useServiceWorker({ url, scope, enabled = true }) {
       setSupported(false);
       return;
     }
-    const registered = registerServiceWorker({ url, scope, onUpdateAvailable: () => setUpdateAvailable(true) });
+    const registered = registerServiceWorker({
+      url,
+      scope,
+      onUpdateAvailable: () => setUpdateAvailable(true),
+      onError: (error) => onErrorRef.current?.(error)
+    });
     handle.current = registered;
     return () => {
       registered.dispose();
@@ -1324,8 +1344,11 @@ function readPermission() {
   if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
   return Notification.permission;
 }
-function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad }) {
-  return resubscribeOnLoad && permission === "granted" && !hasSubscription;
+function isKeyReady(key) {
+  return key.trim().length > 0;
+}
+function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad, hasKey = true }) {
+  return hasKey && resubscribeOnLoad && permission === "granted" && !hasSubscription;
 }
 function isGone(error) {
   return typeof error === "object" && error !== null && error.status === 410;
@@ -1371,6 +1394,7 @@ function usePushSubscription(options) {
   const [subscribed, setSubscribed] = (0, import_react21.useState)(false);
   const [busy, setBusy] = (0, import_react21.useState)(false);
   const [error, setError] = (0, import_react21.useState)(null);
+  const hasKey = isKeyReady(options.vapidPublicKey);
   const latest = (0, import_react21.useRef)(options);
   latest.current = options;
   (0, import_react21.useEffect)(() => {
@@ -1387,7 +1411,7 @@ function usePushSubscription(options) {
         const permissionNow = readPermission();
         setPermission(permissionNow);
         if (existing) return setSubscribed(true);
-        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad })) return;
+        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad, hasKey })) return;
         await ensureSubscribed(reg, latest.current);
         if (!cancelled) setSubscribed(true);
       } catch {
@@ -1396,9 +1420,13 @@ function usePushSubscription(options) {
     return () => {
       cancelled = true;
     };
-  }, [resubscribeOnLoad]);
+  }, [resubscribeOnLoad, hasKey]);
   const subscribe3 = (0, import_react21.useCallback)(async () => {
     if (getPushSupport() !== "supported") return;
+    if (!isKeyReady(latest.current.vapidPublicKey)) {
+      setError("push key not ready");
+      return;
+    }
     setError(null);
     setBusy(true);
     try {

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   deriveUpdateState,
   unregisterAll,
   useServiceWorker
-} from "./chunk-JG3GPTMY.js";
+} from "./chunk-UVJBJETY.js";
 import {
   canShareFiles,
   isShareCancel,
@@ -21,7 +21,7 @@ import {
   shouldResubscribe,
   urlBase64ToUint8Array,
   usePushSubscription
-} from "./chunk-UJ366T3Y.js";
+} from "./chunk-R2PFNE3U.js";
 import {
   nextDelay,
   useVisibilityPolling

package/dist/push.cjs

@@ -82,8 +82,11 @@ function readPermission() {
   if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
   return Notification.permission;
 }
-function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad }) {
-  return resubscribeOnLoad && permission === "granted" && !hasSubscription;
+function isKeyReady(key) {
+  return key.trim().length > 0;
+}
+function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad, hasKey = true }) {
+  return hasKey && resubscribeOnLoad && permission === "granted" && !hasSubscription;
 }
 function isGone(error) {
   return typeof error === "object" && error !== null && error.status === 410;
@@ -129,6 +132,7 @@ function usePushSubscription(options) {
   const [subscribed, setSubscribed] = (0, import_react.useState)(false);
   const [busy, setBusy] = (0, import_react.useState)(false);
   const [error, setError] = (0, import_react.useState)(null);
+  const hasKey = isKeyReady(options.vapidPublicKey);
   const latest = (0, import_react.useRef)(options);
   latest.current = options;
   (0, import_react.useEffect)(() => {
@@ -145,7 +149,7 @@ function usePushSubscription(options) {
         const permissionNow = readPermission();
         setPermission(permissionNow);
         if (existing) return setSubscribed(true);
-        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad })) return;
+        if (!shouldResubscribe({ permission: permissionNow, hasSubscription: false, resubscribeOnLoad, hasKey })) return;
         await ensureSubscribed(reg, latest.current);
         if (!cancelled) setSubscribed(true);
       } catch {
@@ -154,9 +158,13 @@ function usePushSubscription(options) {
     return () => {
       cancelled = true;
     };
-  }, [resubscribeOnLoad]);
+  }, [resubscribeOnLoad, hasKey]);
   const subscribe = (0, import_react.useCallback)(async () => {
     if (getPushSupport() !== "supported") return;
+    if (!isKeyReady(latest.current.vapidPublicKey)) {
+      setError("push key not ready");
+      return;
+    }
     setError(null);
     setBusy(true);
     try {

package/dist/push.d.cts

@@ -12,8 +12,9 @@ interface ResubscribeInput {
     permission: PushPermission;
     hasSubscription: boolean;
     resubscribeOnLoad: boolean;
+    hasKey?: boolean;
 }
-declare function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad }: ResubscribeInput): boolean;
+declare function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad, hasKey }: ResubscribeInput): boolean;
 
 interface UsePushSubscriptionOptions {
     vapidPublicKey: string;

package/dist/push.d.ts

@@ -12,8 +12,9 @@ interface ResubscribeInput {
     permission: PushPermission;
     hasSubscription: boolean;
     resubscribeOnLoad: boolean;
+    hasKey?: boolean;
 }
-declare function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad }: ResubscribeInput): boolean;
+declare function shouldResubscribe({ permission, hasSubscription, resubscribeOnLoad, hasKey }: ResubscribeInput): boolean;
 
 interface UsePushSubscriptionOptions {
     vapidPublicKey: string;

package/dist/push.js

@@ -4,7 +4,7 @@ import {
   shouldResubscribe,
   urlBase64ToUint8Array,
   usePushSubscription
-} from "./chunk-UJ366T3Y.js";
+} from "./chunk-R2PFNE3U.js";
 import "./chunk-YFMMSLMB.js";
 export {
   getPushSupport,

package/dist/service-worker.cjs

@@ -50,17 +50,24 @@ async function unregisterAll() {
   } catch {
   }
 }
-function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = () => window.location.reload() } = {}) {
+function registerServiceWorker({ url, scope, onUpdateAvailable, onError }, { reload = () => window.location.reload() } = {}) {
   let registration;
   let disposed = false;
   let applying = false;
   const cleanups = [];
   const controlledAtStart = hasController();
-  const onControllerChange = () => {
-    if (!(applying || controlledAtStart) || reloaded) return;
+  let activatedUnasked = false;
+  const reloadOnce = () => {
+    if (reloaded) return;
     reloaded = true;
     reload();
   };
+  const onControllerChange = () => {
+    if (applying) return reloadOnce();
+    if (!controlledAtStart || activatedUnasked) return;
+    activatedUnasked = true;
+    onUpdateAvailable();
+  };
   navigator.serviceWorker.addEventListener("controllerchange", onControllerChange);
   cleanups.push(() => navigator.serviceWorker.removeEventListener("controllerchange", onControllerChange));
   const watchInstalling = (reg) => {
@@ -83,10 +90,16 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
     const onUpdateFound = () => watchInstalling(reg);
     reg.addEventListener("updatefound", onUpdateFound);
     cleanups.push(() => reg.removeEventListener("updatefound", onUpdateFound));
-  }).catch(() => {
+  }).catch((error) => {
+    if (disposed) return;
+    try {
+      onError?.(error);
+    } catch {
+    }
   });
   return {
     applyUpdate() {
+      if (activatedUnasked) return reloadOnce();
       const waiting = registration?.waiting;
       if (!waiting) return;
       applying = true;
@@ -100,9 +113,11 @@ function registerServiceWorker({ url, scope, onUpdateAvailable }, { reload = ()
 }
 
 // src/service-worker/use-service-worker.ts
-function useServiceWorker({ url, scope, enabled = true }) {
+function useServiceWorker({ url, scope, enabled = true, onError }) {
   const [supported, setSupported] = (0, import_react.useState)(true);
   const [updateAvailable, setUpdateAvailable] = (0, import_react.useState)(false);
+  const onErrorRef = (0, import_react.useRef)(onError);
+  onErrorRef.current = onError;
   const handle = (0, import_react.useRef)(void 0);
   (0, import_react.useEffect)(() => {
     if (!enabled) return;
@@ -110,7 +125,12 @@ function useServiceWorker({ url, scope, enabled = true }) {
       setSupported(false);
       return;
     }
-    const registered = registerServiceWorker({ url, scope, onUpdateAvailable: () => setUpdateAvailable(true) });
+    const registered = registerServiceWorker({
+      url,
+      scope,
+      onUpdateAvailable: () => setUpdateAvailable(true),
+      onError: (error) => onErrorRef.current?.(error)
+    });
     handle.current = registered;
     return () => {
       registered.dispose();

package/dist/service-worker.d.cts

@@ -2,13 +2,14 @@ interface UseServiceWorkerOptions {
     url: string;
     scope?: string;
     enabled?: boolean;
+    onError?: (error: unknown) => void;
 }
 interface ServiceWorkerState$1 {
     supported: boolean;
     updateAvailable: boolean;
     applyUpdate: () => void;
 }
-declare function useServiceWorker({ url, scope, enabled }: UseServiceWorkerOptions): ServiceWorkerState$1;
+declare function useServiceWorker({ url, scope, enabled, onError }: UseServiceWorkerOptions): ServiceWorkerState$1;
 
 declare function unregisterAll(): Promise<void>;
 

package/dist/service-worker.d.ts

@@ -2,13 +2,14 @@ interface UseServiceWorkerOptions {
     url: string;
     scope?: string;
     enabled?: boolean;
+    onError?: (error: unknown) => void;
 }
 interface ServiceWorkerState$1 {
     supported: boolean;
     updateAvailable: boolean;
     applyUpdate: () => void;
 }
-declare function useServiceWorker({ url, scope, enabled }: UseServiceWorkerOptions): ServiceWorkerState$1;
+declare function useServiceWorker({ url, scope, enabled, onError }: UseServiceWorkerOptions): ServiceWorkerState$1;
 
 declare function unregisterAll(): Promise<void>;
 

package/dist/service-worker.js

@@ -3,7 +3,7 @@ import {
   deriveUpdateState,
   unregisterAll,
   useServiceWorker
-} from "./chunk-JG3GPTMY.js";
+} from "./chunk-UVJBJETY.js";
 export {
   deriveUpdateState,
   unregisterAll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@develemit/web-hooks",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared React behavior hooks for develemit web apps: drawer swipe, focus trap, escape key and clipboard.",
   "license": "MIT",
   "author": "Emit Dutcher",