@statewalker/webrun-http-browser 0.4.2 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -48,7 +48,7 @@ npm install @statewalker/webrun-http-browser
 | Subpath | Purpose |
 | --- | --- |
 | `@statewalker/webrun-http-browser` | Page-side relay API: `newRemoteRelayChannel`, `initHttpService`, `callHttpService`, `splitServiceUrl`, `initServiceWorker`, `newServiceWorkerPort`, `getRelayWindowMessageHandler`; the MessagePort call primitives (`callChannel`, `handleChannelCalls`, `newInvokationChannel`, `sendStream`, `handleStreams`, `newRegistry`); plus everything re-exported from `@statewalker/webrun-http-streams` (`HttpError`, the client/server stubs), `@statewalker/webrun-streams` (stream and error helpers) and the `MessageTarget` family from `@statewalker/webrun-rpc` |
-| `@statewalker/webrun-http-browser/sw` | Same-origin adapter classes: `SwHttpAdapter` (page), `SwHttpDispatcher` (SW), `startHttpDispatcher` bootstrap |
+| `@statewalker/webrun-http-browser/sw` | Same-origin adapter classes: `SwHttpAdapter` (page), `SwHttpDispatcher` (SW), `startHttpDispatcher` bootstrap; `start()` options `timeout` and `reloadIfUncontrolled` |
 | `@statewalker/webrun-http-browser/relay-sw` | IIFE bundle of the relay SW runtime — load via `importScripts` from a loader script in your relay origin |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE bundle of the same-origin SW runtime — ditto, for same-origin apps |
 
@@ -124,6 +124,45 @@ const { baseUrl } = await adapter.register(`${KEY}/api/`, async (request) => {
 // fetch(`${baseUrl}anything`) is intercepted by the SW.
 ```
 
+`start()` resolves once the worker is activated **and controls the page** —
+only a controlled page's `fetch()` reaches the worker. Two options bound it:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `timeout` | `30_000` | Upper bound, in ms, for the wait for the worker to activate, take control and answer the adapter's handshake. Past it `start()` rejects with a `ServiceWorkerControlError` (see `reason`) instead of waiting forever. |
+| `reloadIfUncontrolled` | `false` | If the page is still uncontrolled once the worker is active, reload it once instead of rejecting (see below). |
+
+#### When the page is not controlled
+
+A page can load **uncontrolled although its worker is active**: a hard reload
+(Ctrl+Shift+R / Cmd+Shift+R) bypasses ServiceWorkers for that load, and the
+worker's `clients.claim()` already ran when it activated, so nothing ever
+hands the page to it. (Firefox has also been seen leaving a second page of a
+running worker uncontrolled.) `start()` then asks the worker to claim the page
+again — a `CLAIM` call this package's workers answer with `clients.claim()` —
+and waits for `controllerchange`. That takes the page over in Chromium and
+Firefox, both verified by the browser tests.
+
+If it still is not controlled (a worker that does not answer `CLAIM`, a page
+outside the worker's scope), `start()` rejects with a
+`ServiceWorkerControlError` whose `reason` is `"uncontrolled"` and whose message
+says what happened and what to do. With `reloadIfUncontrolled: true` it reloads
+the page instead — a normal reload is a controlled navigation — at most once:
+a `sessionStorage` marker makes a second uncontrolled load reject rather than
+loop. After a failure, calling `start()` again retries.
+
+```ts
+try {
+  await adapter.start();
+} catch (error) {
+  if ((error as Error).name === "ServiceWorkerControlError") showReloadPrompt();
+  else throw error;
+}
+```
+
+Check `name` or `reason`, not `instanceof`: each bundle of this package carries
+its own copy of the class.
+
 The SW script itself ships as a pre-built IIFE bundle. Put a tiny loader
 next to your app pages so the SW's default scope covers them:
 
@@ -250,9 +289,14 @@ imports keep working after those extractions. Its own surface is below.
 
 | Export | Kind | Purpose |
 | --- | --- | --- |
-| `initServiceWorker(opts)` | function | Registers a SW and resolves once it is activated **and controlling the page**. |
-| `InitServiceWorkerOptions` | interface | `{ swUrl, scopeUrl?, type? }`. |
-| `newServiceWorkerPort()` | function | A `MessagePort` that transparently bridges to the controlling SW. |
+| `initServiceWorker(opts)` | function | Registers a SW and resolves with it once it is activated: the controller, or the registration's active worker when the page is not controlled (the relay only needs to message it). Rejects with a `ServiceWorkerControlError` past `timeout`. |
+| `InitServiceWorkerOptions` | interface | `{ swUrl, scopeUrl?, type?, timeout? }`. |
+| `newServiceWorkerPort(registration?)` | function | A `MessagePort` that transparently bridges to the controlling SW, or to `registration.active` while the page is not controlled. |
+| `awaitActiveServiceWorker(registration, opts?)` | function | Resolves with the registration's worker once `activated`; rejects (`reason: "activation-timeout"`) past `timeout`. |
+| `awaitServiceWorkerControl(registration, opts?)` | function | Resolves with the controller once the page is controlled, asking the worker to claim an uncontrolled page; bounded by `timeout`, optional `reloadIfUncontrolled`. What `SwHttpAdapter.start()` uses. |
+| `handleClaimRequests(self)` | function | Worker side: answers the page's `CLAIM` call with `clients.claim()`. Both of this package's workers install it; use it in a worker of your own. |
+| `ServiceWorkerControlError` | class | `name: "ServiceWorkerControlError"`, `reason`: `"activation-timeout"` (worker did not activate in time), `"uncontrolled"` (active, but the page is not controlled), `"unresponsive"` (controls the page, did not answer `SwHttpAdapter`'s handshake). |
+| `DEFAULT_SERVICE_WORKER_TIMEOUT` / `CLAIM_CALL` | const | `30_000` ms / `"CLAIM"`. |
 
 ### Connection registry
 
@@ -310,10 +354,14 @@ src/
 │   ├── data-calls.ts              │  Transport primitives over a
 │   ├── data-channels.ts           │  `MessageTarget`: one-shot
 │   ├── message-target.ts          │  `callChannel` / `handleChannelCalls`,
-│   └── registry.ts                │  the request/response
+│   ├── registry.ts                │  the request/response
 │                                  │  `newInvokationChannel`, streaming
-│                                  │  `sendStream` / `handleStreams` with
+│   └── service-worker-control.ts  │  `sendStream` / `handleStreams` with
 │                                  │  backpressure, and `newRegistry`.
+│                                  │  Bounded waits for a worker to
+│                                  │  activate / take control, and the
+│                                  │  `CLAIM` request that takes over an
+│                                  │  uncontrolled page.
 │                                  │  Also re-exports
 │                                  │  `@statewalker/webrun-streams`.
 │                                  ┘
@@ -378,6 +426,17 @@ src/
   backpressure — each `next(value)` returns a `Promise<boolean>` that resolves
   once the consumer has dequeued — and drains in-flight producers on consumer
   exit.
+- **No literal `new URL("…", import.meta.url)` in page-side code**.
+  Bundlers (Vite among them) turn that pattern into an emitted asset at build
+  time, before tree-shaking; the relay defaults resolved `"../"` that way,
+  which is the package itself, so every Vite consumer shipped a dead copy of
+  `dist/index.js`. They resolve against a `moduleUrl` variable instead, and
+  `tests/dist/vite-consumer.dist.ts` builds a Vite app to prove nothing is
+  emitted.
+- **Uncontrolled pages are handled per mode**. Same-origin mode needs
+  control — an uncontrolled page's `fetch()` never reaches the worker — so it
+  asks the worker to claim the page. Relay mode needs only a worker to message,
+  so an uncontrolled relay page bridges to `registration.active`.
 - **SW client registry is IndexedDB-persisted**. Both `SwPortDispatcher`
   (same-origin) and `relay/index-sw.ts` keep their client-lookup tables in
   IndexedDB so a SW wake-up after idle doesn't lose its bindings.
@@ -398,6 +457,11 @@ src/
   only controls pages and fetches under `/public/`. If you need a broader
   scope, the SW script must be served with the
   `Service-Worker-Allowed` HTTP header, *or* live higher in the origin.
+- **A hard reload loads the page without its worker.** Handled — see
+  [When the page is not controlled](#when-the-page-is-not-controlled) — as long
+  as the worker answers `CLAIM`. A worker script of your own that
+  `importScripts` this package's `sw-worker.js` or `relay-sw.js` does; one
+  that does not should call `handleClaimRequests(self)`.
 - **`http://localhost` or HTTPS only.** Browsers refuse to register SWs
   on other `http://` origins.
 - **Relay mode needs an iframe-capable sandbox.** Pages with strict CSP
@@ -421,7 +485,16 @@ Runtime:
 
 Dev: TypeScript, vitest, rolldown, rimraf, `http-server` (for the
 `example:*` scripts), `@types/node` (catalog versions from the monorepo
-root).
+root), `playwright` and `vite` (for `test:browser`).
+
+## Tests
+
+- `pnpm test` — unit tests under Node, against the source.
+- `pnpm test:browser` — builds, then runs `tests/browser/` in real Chromium and
+  Firefox through Playwright against the built bundles (first visit, normal
+  reload, hard reload, second tab, the relay page, and the timeout and
+  uncontrolled errors), plus `tests/dist/`, which builds a Vite consumer of
+  the bundles. Needs the browsers: `npx playwright install chromium firefox`.
 
 ## License
 

package/dist/core/deadline.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function withDeadline<T, F>(deadline: number, promise: Promise<T>, onTimeout: () => F): Promise<T | (F extends Error ? never : F)>;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/core/deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/core/deadline.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,CAAC,GACjB,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAqB5C"}

package/dist/core/index.d.ts

@@ -3,4 +3,5 @@ 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAGA,cAAc,6BAA6B,CAAC;AAE5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAGA,cAAc,6BAA6B,CAAC;AAE5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,6BAA6B,CAAC"}

package/dist/core/service-worker-control.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+export declare const DEFAULT_SERVICE_WORKER_TIMEOUT = 30000;
+/** Channel call a page sends to ask its ServiceWorker to `clients.claim()` it. */
+export declare const CLAIM_CALL = "CLAIM";
+/**
+ * - `activation-timeout`: the worker did not activate in time.
+ * - `uncontrolled`: the worker is active but the page is not controlled by it.
+ * - `unresponsive`: the page is controlled, but the worker did not answer the
+ *   adapter's handshake in time.
+ */
+export type ServiceWorkerControlFailure = "activation-timeout" | "uncontrolled" | "unresponsive";
+/**
+ * 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.
+ */
+export declare class ServiceWorkerControlError extends Error {
+    readonly reason: ServiceWorkerControlFailure;
+    constructor(reason: ServiceWorkerControlFailure, message: string);
+}
+export interface AwaitServiceWorkerOptions {
+    /** Upper bound for the whole wait, in ms. Default `DEFAULT_SERVICE_WORKER_TIMEOUT`. */
+    timeout?: number;
+}
+export interface AwaitServiceWorkerControlOptions extends AwaitServiceWorkerOptions {
+    /**
+     * When the page is still uncontrolled after asking the worker to claim it,
+     * reload the page once instead of rejecting. A normal reload is a
+     * navigation, and navigations are controlled. Guarded by `sessionStorage`
+     * so it never loops: if the reloaded page is uncontrolled too, it rejects.
+     * Default `false`.
+     */
+    reloadIfUncontrolled?: boolean;
+    /** For tests. Default `navigator.serviceWorker`. */
+    container?: ServiceWorkerContainer;
+}
+/**
+ * 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.
+ */
+export declare function awaitActiveServiceWorker(registration: ServiceWorkerRegistration, { timeout }?: AwaitServiceWorkerOptions): Promise<ServiceWorker>;
+/**
+ * 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.
+ */
+export declare function awaitServiceWorkerControl(registration: ServiceWorkerRegistration, { timeout, reloadIfUncontrolled, container, }?: AwaitServiceWorkerControlOptions): Promise<ServiceWorker>;
+/**
+ * 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.
+ */
+export declare function handleClaimRequests(self: ServiceWorkerGlobalScope): () => void;
+//# sourceMappingURL=service-worker-control.d.ts.map

package/dist/core/service-worker-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-worker-control.d.ts","sourceRoot":"","sources":["../../src/core/service-worker-control.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAUrD,kFAAkF;AAClF,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG,cAAc,GAAG,cAAc,CAAC;AAEjG;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,YAAY,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,MAAM,EAI/D;CACF;AAED,MAAM,WAAW,yBAAyB;IACxC,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gCAAiC,SAAQ,yBAAyB;IACjF;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,yBAAyB,EACvC,EAAE,OAAwC,EAAE,GAAE,yBAA8B,GAC3E,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,yBAAyB,EACvC,EACE,OAAwC,EACxC,oBAA4B,EAC5B,SAAmC,GACpC,GAAE,gCAAqC,GACvC,OAAO,CAAC,aAAa,CAAC,CA6CxB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAM9E"}

package/dist/index.js

@@ -1125,6 +1125,192 @@ function newRegistry(onError = console.error) {
 	});
 }
 //#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/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 ../webrun-http-streams/dist/index.js
 const CR = 13;
 const LF = 10;
@@ -2498,13 +2684,25 @@ function splitServiceUrl(url, separator = "~") {
 //#endregion
 //#region src/relay/index.ts
 /**
+* The URL of this module, kept in a variable on purpose. Bundlers (Vite
+* among them) rewrite every literal `new URL("<path>", import.meta.url)` into
+* an emitted asset at build time, before tree-shaking — so the defaults below
+* made every Vite consumer of this entry emit a dead copy of the package's
+* own `dist/index.js` (`"../"` resolves to the package, hence to its `main`).
+* Resolving against a variable is the same URL at run time and invisible to
+* that transform.
+*/
+const moduleUrl = import.meta.url;
+/**
 * Returns a MessagePort that transparently bridges messages to/from the
-* ServiceWorker controlling this page.
+* page's ServiceWorker: the one controlling the page, or — when the page is
+* not controlled (a hard reload, or a page Firefox left uncontrolled) — the
+* active worker of `registration`, which answers messages all the same.
 */
-function newServiceWorkerPort() {
+function newServiceWorkerPort(registration) {
 	const channel = new MessageChannel();
 	channel.port1.onmessage = (event) => {
-		navigator.serviceWorker.controller?.postMessage(event.data, [...event.ports]);
+		(navigator.serviceWorker.controller ?? registration?.active)?.postMessage(event.data, [...event.ports]);
 	};
 	navigator.serviceWorker.addEventListener("message", (event) => {
 		channel.port1.postMessage(event.data, [...event.ports]);
@@ -2512,45 +2710,26 @@ function newServiceWorkerPort() {
 	return channel.port2;
 }
 /**
-* Registers a ServiceWorker and resolves once it's activated and controlling the page.
+* Registers a ServiceWorker and resolves with it once it is activated: the
+* worker controlling the page, or the registration's active worker when the
+* page is not controlled. Messaging works either way, which is all the relay
+* needs; nothing here waits for control, because an uncontrolled page (hard
+* reload; Firefox) may never get it. Rejects with a
+* `ServiceWorkerControlError` if activation takes longer than `timeout`.
 */
-async function initServiceWorker({ swUrl, scopeUrl, type }) {
-	await navigator.serviceWorker.register(swUrl, {
+async function initServiceWorker(options) {
+	return (await registerServiceWorker(options)).worker;
+}
+async function registerServiceWorker({ swUrl, scopeUrl, type, timeout = DEFAULT_SERVICE_WORKER_TIMEOUT }) {
+	const registration = await navigator.serviceWorker.register(swUrl, {
 		type,
 		scope: scopeUrl
 	});
-	const worker = await getServiceWorkerController();
-	await awaitServiceWorkerActivation(worker);
-	return worker;
-}
-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);
-	});
+	const active = await awaitActiveServiceWorker(registration, { timeout });
+	return {
+		registration,
+		worker: navigator.serviceWorker.controller ?? active
+	};
 }
 /**
 * Registers `handler` as the server for the given service `key` on the relay.
@@ -2581,9 +2760,11 @@ async function callHttpService(request, { key, port }) {
 /**
 * Returns a `window.onmessage` handler for use inside the relay iframe:
 * it accepts a CONNECT message, starts the relay ServiceWorker, and bridges
-* the parent's MessagePort with the SW.
+* the parent's MessagePort with the SW. If the worker cannot be started, every
+* call the parent makes on that port is answered with the error, so the
+* parent's `initHttpService` / `callHttpService` reject instead of waiting.
 */
-function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", import.meta.url)}`, scopeUrl = `${new URL("../", import.meta.url)}` } = {}) {
+function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", moduleUrl)}`, scopeUrl = `${new URL("../", moduleUrl)}`, timeout } = {}) {
 	let externalPort;
 	return async (ev) => {
 		if (ev.data?.type !== "CONNECT") return;
@@ -2594,11 +2775,19 @@ function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", impo
 			return;
 		}
 		externalPort = newExternalPort;
-		await initServiceWorker({
-			swUrl,
-			scopeUrl
-		});
-		const serviceWorkerPort = newServiceWorkerPort();
+		let registration;
+		try {
+			({registration} = await registerServiceWorker({
+				swUrl,
+				scopeUrl,
+				timeout
+			}));
+		} catch (error) {
+			const serialized = serializeError(error);
+			externalPort.onmessage = (event) => event.ports[0]?.postMessage({ error: serialized });
+			throw error;
+		}
+		const serviceWorkerPort = newServiceWorkerPort(registration);
 		serviceWorkerPort.onmessage = (event) => {
 			externalPort?.postMessage(event.data, [...event.ports]);
 		};
@@ -2611,7 +2800,7 @@ function getRelayWindowMessageHandler({ swUrl = `${new URL("./index-sw.js", impo
 * Embeds a hidden relay iframe, establishes a MessageChannel with it, and
 * returns the port to be used with `initHttpService` / `callHttpService`.
 */
-async function newRemoteRelayChannel({ baseUrl = new URL("../public-relay/", import.meta.url), url = new URL("relay.html", baseUrl), container = document.body } = {}) {
+async function newRemoteRelayChannel({ baseUrl = new URL("../public-relay/", moduleUrl), url = new URL("relay.html", baseUrl), container = document.body } = {}) {
 	const messageChannel = new MessageChannel();
 	const { iframe, promise } = newIFrame(url);
 	Object.assign(iframe.style, {
@@ -2680,4 +2869,4 @@ async function registerConnectionsHandler({ key, handler, communicationPort }) {
 	return cleanup;
 }
 //#endregion
-export { DuplexSiteBuilder, HttpError, HttpParseError, PEER_ERROR_HEADER, TransportClosedError, callChannel, callHttpService, collect, collectBytes, collectString, decodeJsonl, decodeMessage, decodeText, defaultCodec, deserializeError, emulateMux, encodeJsonl, encodeMessage, encodeText, fetchOverDuplex, fromReadableStream, getRelayWindowMessageHandler, handleChannelCalls, handleHttpRequests, handleStreams, httpCodec, httpFetch, httpServe, initHttpService, initServiceWorker, initializeConnection, joinLines, jsonEnvelopeCodec, map, newAsyncGenerator, newCreditGrantor, newCreditLedger, newHttpClientStub, newHttpCodec, newHttpServerStub, newInvokationChannel, newRegistry, newRemoteRelayChannel, newServiceWorkerPort, newSniffingCodec, normalizeToUint8Array, recieveIterator, registerConnectionsHandler, sendHttpRequest, sendIterator, sendStream, serializeError, serveFetchOverDuplex, splitLines, splitServiceUrl, toChunks, toReadableStream };
+export { CLAIM_CALL, DEFAULT_SERVICE_WORKER_TIMEOUT, DuplexSiteBuilder, HttpError, HttpParseError, PEER_ERROR_HEADER, ServiceWorkerControlError, TransportClosedError, awaitActiveServiceWorker, awaitServiceWorkerControl, callChannel, callHttpService, collect, collectBytes, collectString, decodeJsonl, decodeMessage, decodeText, defaultCodec, deserializeError, emulateMux, encodeJsonl, encodeMessage, encodeText, fetchOverDuplex, fromReadableStream, getRelayWindowMessageHandler, handleChannelCalls, handleClaimRequests, handleHttpRequests, handleStreams, httpCodec, httpFetch, httpServe, initHttpService, initServiceWorker, initializeConnection, joinLines, jsonEnvelopeCodec, map, newAsyncGenerator, newCreditGrantor, newCreditLedger, newHttpClientStub, newHttpCodec, newHttpServerStub, newInvokationChannel, newRegistry, newRemoteRelayChannel, newServiceWorkerPort, newSniffingCodec, normalizeToUint8Array, recieveIterator, registerConnectionsHandler, sendHttpRequest, sendIterator, sendStream, serializeError, serveFetchOverDuplex, splitLines, splitServiceUrl, toChunks, toReadableStream };

package/dist/relay/index-sw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAwElF"}
+{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,IAAI,CA4ElF"}