@statewalker/webrun-http-browser 0.4.2 → 0.6.0

package/dist/sw/sw-dispatcher.d.ts

@@ -3,6 +3,19 @@ export interface SwPortHandlerOptions {
     scope?: string;
     serviceWorkerUrl?: string;
     bindPort: (port: MessagePort) => void | Promise<void>;
+    /**
+     * Upper bound, in ms, for `start()`'s wait for the worker to activate, take
+     * control of the page and answer the handshake. `start()` rejects with a
+     * `ServiceWorkerControlError` past it instead of waiting forever.
+     * Default `DEFAULT_SERVICE_WORKER_TIMEOUT` (30 s).
+     */
+    timeout?: number;
+    /**
+     * If the page is still uncontrolled once the worker is active — after a
+     * hard reload, say — and the worker does not take it over when asked,
+     * reload the page once instead of rejecting. Default `false`.
+     */
+    reloadIfUncontrolled?: boolean;
 }
 interface ChannelInfo {
     key: string;
@@ -28,6 +41,15 @@ export declare class SwPortHandler {
     protected _setCommunicationPort(port: MessagePort): Promise<void>;
     protected _updateCommunicationChannel(): Promise<void>;
     protected _getRegistrationInfo(): ChannelInfo;
+    /**
+     * Registers the worker and waits until it is activated and controls this
+     * page, then opens the port to it. The page must be controlled, because
+     * only a controlled page's `fetch()` reaches the worker. When the page
+     * loaded uncontrolled (a hard reload does that), the worker is asked to
+     * claim it. Rejects with a `ServiceWorkerControlError` when that fails or
+     * `timeout` passes (`reason` says which step); a later `start()` tries
+     * again.
+     */
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/dist/sw/sw-dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sw-dispatcher.d.ts","sourceRoot":"","sources":["../../src/sw/sw-dispatcher.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAC7C,OAAO,CAAC,qBAAqB,CAAC,CAAa;IAE3C,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,OAAO,IAAI,GAAG,CAEjB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAa7B;IAED,UAAgB,wBAAwB,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAG9E;IAED,UAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;IAED,UAAgB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3D;IAED,SAAS,CAAC,oBAAoB,IAAI,WAAW,CAE5C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA8B3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1B;CACF;AAiCD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,2BAAkC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,cAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAE3C,YAAY,EAAE,IAAI,EAAE,GAAc,EAAE,EAAE,uBAAuB,EAG5D;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAgBnE;IAED,yDAAyD;IACzD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED,KAAK,IAAI,IAAI,CA2BZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAED,OAAO,CAAC,gBAAgB;YAOV,SAAS;YAgBT,kBAAkB;YAWlB,cAAc;YAOd,gBAAgB;CAY/B"}
+{"version":3,"file":"sw-dispatcher.d.ts","sourceRoot":"","sources":["../../src/sw/sw-dispatcher.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,cAAc,CAAC,CAAgB;IACvC,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAC7C,OAAO,CAAC,qBAAqB,CAAC,CAAa;IAE3C,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,OAAO,IAAI,GAAG,CAEjB;IAED,IAAI,gBAAgB,IAAI,MAAM,CAa7B;IAED,UAAgB,wBAAwB,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAG9E;IAED,UAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;IAED,UAAgB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3D;IAED,SAAS,CAAC,oBAAoB,IAAI,WAAW,CAE5C;IAED;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAsD3B;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAU1B;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,2BAAkC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,cAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAE3C,YAAY,EAAE,IAAI,EAAE,GAAc,EAAE,EAAE,uBAAuB,EAG5D;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;OAIG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAgBnE;IAED,yDAAyD;IACzD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjC;IAED,KAAK,IAAI,IAAI,CAgCZ;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;IAED,OAAO,CAAC,gBAAgB;YAOV,SAAS;YAgBT,kBAAkB;YAWlB,cAAc;YAOd,gBAAgB;CAY/B"}

package/dist/sw-worker.js

@@ -1341,7 +1341,7 @@
 		})(request);
 	}
 	//#endregion
-	//#region ../../../../node_modules/.pnpm/idb-keyval@6.3.0/node_modules/idb-keyval/dist/index.js
+	//#region ../../node_modules/.pnpm/idb-keyval@6.3.0/node_modules/idb-keyval/dist/index.js
 	function promisifyRequest(request) {
 		return new Promise((resolve, reject) => {
 			request.oncomplete = request.onsuccess = () => resolve(request.result);
@@ -1424,6 +1424,22 @@
 		return () => target.removeEventListener("message", listener);
 	}
 	//#endregion
+	//#region src/core/service-worker-control.ts
+	/** Channel call a page sends to ask its ServiceWorker to `clients.claim()` it. */
+	const CLAIM_CALL = "CLAIM";
+	/**
+	* ServiceWorker side: answers the page's `CLAIM` request with
+	* `clients.claim()`, which takes over every uncontrolled client in scope.
+	* Returns a function that stops answering.
+	*/
+	function handleClaimRequests(self) {
+		return handleChannelCalls(self, CLAIM_CALL, (event) => {
+			const claimed = self.clients.claim().then(() => true);
+			event.waitUntil?.(claimed);
+			return claimed;
+		});
+	}
+	//#endregion
 	//#region src/sw/sw-dispatcher.ts
 	/**
 	* ServiceWorker-side counterpart: maintains an index of connected clients keyed by
@@ -1472,7 +1488,8 @@
 			return this.claimedKeys.has(key);
 		}
 		start() {
-			this._cleanup = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
+			const stopClaims = handleClaimRequests(this.self);
+			const stopPortUpdates = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
 				const clientId = event.source?.id;
 				this.log("[UPDATE_COMMUNICATION_PORT]", clientId, channelInfo);
 				await this._updateChannelInfo({
@@ -1482,6 +1499,10 @@
 				});
 				return { ...channelInfo };
 			});
+			this._cleanup = () => {
+				stopClaims();
+				stopPortUpdates();
+			};
 			this.self.addEventListener("install", (event) => {
 				this.log("Skip waiting on install.", event);
 				this.self.skipWaiting();

package/dist/sw.js

@@ -1440,7 +1440,7 @@ async function sendHttpRequest(communicationPort, request) {
 	})(request);
 }
 //#endregion
-//#region ../../../../node_modules/.pnpm/idb-keyval@6.3.0/node_modules/idb-keyval/dist/index.js
+//#region ../../node_modules/.pnpm/idb-keyval@6.3.0/node_modules/idb-keyval/dist/index.js
 function promisifyRequest(request) {
 	return new Promise((resolve, reject) => {
 		request.oncomplete = request.onsuccess = () => resolve(request.result);
@@ -1523,6 +1523,29 @@ function handleChannelCalls(target, callType, handler) {
 	return () => target.removeEventListener("message", listener);
 }
 //#endregion
+//#region src/core/deadline.ts
+/**
+* Settles like `promise` if it settles before `deadline` (a `Date.now()`
+* value). Otherwise calls `onTimeout`: an `Error` it returns rejects, any
+* other value resolves. Internal; not re-exported.
+*/
+function withDeadline(deadline, promise, onTimeout) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			const outcome = onTimeout();
+			if (outcome instanceof Error) reject(outcome);
+			else resolve(outcome);
+		}, Math.max(0, deadline - Date.now()));
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+//#endregion
 //#region src/core/registry.ts
 function newRegistry(onError = console.error) {
 	let counter = 0;
@@ -1557,6 +1580,169 @@ function newRegistry(onError = console.error) {
 	});
 }
 //#endregion
+//#region src/core/service-worker-control.ts
+/**
+* How long, by default, the page waits for its ServiceWorker to activate and
+* to take control before giving up. Generous: a first install downloads and
+* evaluates the worker script, which on a slow link takes seconds.
+*/
+const DEFAULT_SERVICE_WORKER_TIMEOUT = 3e4;
+/**
+* How long the page waits for `controllerchange` once the worker has
+* answered the `CLAIM` request. `clients.claim()` resolves only after the
+* browser has queued that event, so this is a grace period for delivery, not
+* a second budget.
+*/
+const CLAIM_GRACE_MS = 1e3;
+/** Channel call a page sends to ask its ServiceWorker to `clients.claim()` it. */
+const CLAIM_CALL = "CLAIM";
+/**
+* Why a page could not get a working ServiceWorker. `reason` says which wait
+* failed; check it (or `name`) rather than `instanceof`, because each of this
+* package's bundles carries its own copy of this class.
+*/
+var ServiceWorkerControlError = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "ServiceWorkerControlError";
+		this.reason = reason;
+	}
+};
+/**
+* Resolves with the registration's worker once it is `activated`. Rejects
+* with a `ServiceWorkerControlError` (`reason: "activation-timeout"`) if that
+* takes longer than `timeout` — an install that throws or never finishes
+* would otherwise leave the caller waiting forever.
+*/
+async function awaitActiveServiceWorker(registration, { timeout = DEFAULT_SERVICE_WORKER_TIMEOUT } = {}) {
+	return await withDeadline(Date.now() + timeout, waitForActivated(registration), () => {
+		const worker = registration.installing ?? registration.waiting ?? registration.active;
+		return new ServiceWorkerControlError("activation-timeout", `ServiceWorker ${scriptUrl(worker)} (scope ${registration.scope}) did not activate within ${timeout} ms` + (worker ? `; it is "${worker.state}"` : "") + ". Check the worker script for errors during install (DevTools → Application → Service Workers), or raise the `timeout` option.");
+	});
+}
+/**
+* Resolves with the ServiceWorker that controls this page, once `registration`
+* has an activated worker and the page is controlled by it.
+*
+* A page can stay uncontrolled while its worker is active, and then no
+* `controllerchange` ever fires on its own:
+* - a hard reload (Ctrl+Shift+R) bypasses the worker for that load, and the
+*   worker's `clients.claim()` already ran when it activated;
+* - Firefox can leave a page loaded while the worker is running uncontrolled.
+*
+* So when the page is uncontrolled, this asks the active worker to claim it
+* again (a `CLAIM` channel call — this package's workers answer it) and waits
+* for `controllerchange`. Every wait is bounded by `timeout`. If control never
+* comes it reloads once (`reloadIfUncontrolled`) or rejects with a
+* `ServiceWorkerControlError` (`reason: "uncontrolled"`) that says what
+* happened and what to do.
+*/
+async function awaitServiceWorkerControl(registration, { timeout = DEFAULT_SERVICE_WORKER_TIMEOUT, reloadIfUncontrolled = false, container = navigator.serviceWorker } = {}) {
+	const deadline = Date.now() + timeout;
+	const controlled = waitForController(container);
+	try {
+		const active = await awaitActiveServiceWorker(registration, { timeout });
+		let controller = container.controller;
+		if (!controller) controller = await withDeadline(deadline, (async () => {
+			await Promise.race([callChannel(active, CLAIM_CALL, {}), controlled.promise]);
+			return await Promise.race([controlled.promise, delay(CLAIM_GRACE_MS, null)]);
+		})(), () => null);
+		if (controller) {
+			forgetReload(registration);
+			return controller;
+		}
+		if (reloadIfUncontrolled && markReload(registration)) {
+			location.reload();
+			return await new Promise(() => {});
+		}
+		forgetReload(registration);
+		throw new ServiceWorkerControlError("uncontrolled", `This page is not controlled by its ServiceWorker ${scriptUrl(active)} (scope ${registration.scope}), although the worker is active, and the worker did not take control when asked (clients.claim()) within ${timeout} ms. This happens after a hard reload (Ctrl+Shift+R / Cmd+Shift+R), which bypasses ServiceWorkers for that load, and in Firefox for some pages opened while the worker was already running. Requests from this page would not reach the worker. Reload the page normally, pass \`reloadIfUncontrolled: true\` to do that automatically, check that the page is inside the worker's scope, and that the worker answers the "${CLAIM_CALL}" request (this package's workers do).`);
+	} finally {
+		controlled.cancel();
+	}
+}
+/**
+* ServiceWorker side: answers the page's `CLAIM` request with
+* `clients.claim()`, which takes over every uncontrolled client in scope.
+* Returns a function that stops answering.
+*/
+function handleClaimRequests(self) {
+	return handleChannelCalls(self, CLAIM_CALL, (event) => {
+		const claimed = self.clients.claim().then(() => true);
+		event.waitUntil?.(claimed);
+		return claimed;
+	});
+}
+function waitForActivated(registration) {
+	return new Promise((resolve) => {
+		const watched = /* @__PURE__ */ new Set();
+		const check = () => {
+			const active = registration.active;
+			if (active?.state === "activated") {
+				registration.removeEventListener("updatefound", watch);
+				for (const worker of watched) worker.removeEventListener("statechange", check);
+				resolve(active);
+				return;
+			}
+			watch();
+		};
+		function watch() {
+			for (const worker of [
+				registration.installing,
+				registration.waiting,
+				registration.active
+			]) {
+				if (!worker || watched.has(worker)) continue;
+				watched.add(worker);
+				worker.addEventListener("statechange", check);
+			}
+		}
+		registration.addEventListener("updatefound", watch);
+		check();
+	});
+}
+function waitForController(container) {
+	let cancel = () => {};
+	return {
+		promise: new Promise((resolve) => {
+			const onChange = () => {
+				if (!container.controller) return;
+				cancel();
+				resolve(container.controller);
+			};
+			cancel = () => container.removeEventListener("controllerchange", onChange);
+			container.addEventListener("controllerchange", onChange);
+		}),
+		cancel
+	};
+}
+function delay(ms, value) {
+	return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+function scriptUrl(worker) {
+	return worker?.scriptURL ? `"${worker.scriptURL}"` : "(no worker)";
+}
+function reloadKey(registration) {
+	return `webrun-http-browser:reloaded-uncontrolled:${registration.scope}`;
+}
+/** Records the reload about to happen. `false` if one already happened, or if it cannot be recorded. */
+function markReload(registration) {
+	try {
+		const key = reloadKey(registration);
+		if (sessionStorage.getItem(key)) return false;
+		sessionStorage.setItem(key, "1");
+		return true;
+	} catch {
+		return false;
+	}
+}
+function forgetReload(registration) {
+	try {
+		sessionStorage.removeItem(reloadKey(registration));
+	} catch {}
+}
+//#endregion
 //#region src/sw/sw-dispatcher.ts
 /**
 * Page-side counterpart: registers a ServiceWorker and sets up a
@@ -1605,6 +1791,15 @@ var SwPortHandler = class {
 	_getRegistrationInfo() {
 		return { key: this.key };
 	}
+	/**
+	* Registers the worker and waits until it is activated and controls this
+	* page, then opens the port to it. The page must be controlled, because
+	* only a controlled page's `fetch()` reaches the worker. When the page
+	* loaded uncontrolled (a hard reload does that), the worker is asked to
+	* claim it. Rejects with a `ServiceWorkerControlError` when that fails or
+	* `timeout` passes (`reason` says which step); a later `start()` tries
+	* again.
+	*/
 	async start() {
 		if (!this._registrationPromise) this._registrationPromise = (async () => {
 			const [register, cleanup] = newRegistry();
@@ -1614,13 +1809,25 @@ var SwPortHandler = class {
 			});
 			const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl, { scope: this.scope });
 			register(() => registration.unregister());
-			register(handleChannelCalls(navigator.serviceWorker, "UPDATE_COMMUNICATION_PORT", async (_event, _params, port) => {
+			const stopListening = handleChannelCalls(navigator.serviceWorker, "UPDATE_COMMUNICATION_PORT", async (_event, _params, port) => {
 				await this._setCommunicationPort(port);
 				return this._getRegistrationInfo();
-			}));
-			this._serviceWorker = await getServiceWorkerController();
-			await awaitServiceWorkerActivation(this._serviceWorker);
-			await this._updateCommunicationChannel();
+			});
+			register(stopListening);
+			const timeout = this.options.timeout ?? 3e4;
+			const deadline = Date.now() + timeout;
+			try {
+				this._serviceWorker = await awaitServiceWorkerControl(registration, {
+					timeout,
+					reloadIfUncontrolled: this.options.reloadIfUncontrolled
+				});
+				await withDeadline(deadline, this._updateCommunicationChannel(), () => new ServiceWorkerControlError("unresponsive", `ServiceWorker "${this._serviceWorker?.scriptURL}" controls this page but did not answer the UPDATE_COMMUNICATION_PORT handshake within ${timeout} ms. Check that the worker script runs this package's same-origin dispatcher (it importScripts \`sw-worker.js\`, or calls \`startHttpDispatcher\`).`));
+			} catch (error) {
+				stopListening();
+				this._cleanupRegistrations = void 0;
+				this._registrationPromise = void 0;
+				throw error;
+			}
 		})();
 		return this._registrationPromise;
 	}
@@ -1634,35 +1841,6 @@ var SwPortHandler = class {
 		}
 	}
 };
-function getServiceWorkerController() {
-	return new Promise((resolve) => {
-		const container = navigator.serviceWorker;
-		if (container.controller) {
-			resolve(container.controller);
-			return;
-		}
-		const onChange = () => {
-			if (!container.controller) return;
-			resolve(container.controller);
-			container.removeEventListener("controllerchange", onChange);
-		};
-		container.addEventListener("controllerchange", onChange);
-	});
-}
-function awaitServiceWorkerActivation(worker) {
-	return new Promise((resolve) => {
-		if (worker.state === "activated") {
-			resolve();
-			return;
-		}
-		const onStateChange = () => {
-			if (worker.state !== "activated") return;
-			worker.removeEventListener("statechange", onStateChange);
-			resolve();
-		};
-		worker.addEventListener("statechange", onStateChange);
-	});
-}
 /**
 * ServiceWorker-side counterpart: maintains an index of connected clients keyed by
 * clientId, persisted in IndexedDB so it can reclaim ports across SW restarts.
@@ -1710,7 +1888,8 @@ var SwPortDispatcher = class {
 		return this.claimedKeys.has(key);
 	}
 	start() {
-		this._cleanup = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
+		const stopClaims = handleClaimRequests(this.self);
+		const stopPortUpdates = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
 			const clientId = event.source?.id;
 			this.log("[UPDATE_COMMUNICATION_PORT]", clientId, channelInfo);
 			await this._updateChannelInfo({
@@ -1720,6 +1899,10 @@ var SwPortDispatcher = class {
 			});
 			return { ...channelInfo };
 		});
+		this._cleanup = () => {
+			stopClaims();
+			stopPortUpdates();
+		};
 		this.self.addEventListener("install", (event) => {
 			this.log("Skip waiting on install.", event);
 			this.self.skipWaiting();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "ServiceWorker-based HTTP server for browsers, with relay and same-origin dispatch modes",
@@ -29,6 +29,10 @@
     "./relay-sw": {
       "default": "./dist/relay-sw.js"
     },
+    "./relay-worker": {
+      "types": "./dist/relay-worker.d.ts",
+      "import": "./dist/relay-worker.js"
+    },
     "./sw-worker": {
       "default": "./dist/sw-worker.js"
     }
@@ -47,11 +51,14 @@
     "@statewalker/webrun-streams": "0.2.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
     "@types/node": "^26.2.0",
     "http-server": "^14.1.1",
+    "playwright": "^1.62.1",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10"
   },
   "sideEffects": false,
@@ -61,6 +68,7 @@
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "test:browser": "pnpm run build && vitest run --config vitest.browser.config.ts",
     "lint": "biome check src tests",
     "serve": "http-server -p 5173 -c-1 -s .",
     "example:same-origin": "pnpm run build && http-server -p 5173 -c-1 -o /public/index.html .",

package/src/core/deadline.ts

@@ -0,0 +1,31 @@
+/**
+ * Settles like `promise` if it settles before `deadline` (a `Date.now()`
+ * value). Otherwise calls `onTimeout`: an `Error` it returns rejects, any
+ * other value resolves. Internal; not re-exported.
+ */
+export function withDeadline<T, F>(
+  deadline: number,
+  promise: Promise<T>,
+  onTimeout: () => F,
+): Promise<T | (F extends Error ? never : F)> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => {
+        const outcome = onTimeout();
+        if (outcome instanceof Error) reject(outcome);
+        else resolve(outcome as F extends Error ? never : F);
+      },
+      Math.max(0, deadline - Date.now()),
+    );
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}

package/src/core/index.ts

@@ -7,3 +7,4 @@ export * from "./data-calls.js";
 export * from "./data-channels.js";
 export * from "./message-target.js";
 export * from "./registry.js";
+export * from "./service-worker-control.js";