@statewalker/webrun-http-browser 0.4.2 → 0.6.0

package/src/relay/index.ts

@@ -1,19 +1,38 @@
 import type { HttpHandler } from "@statewalker/webrun-http-streams";
-import { callChannel, handleChannelCalls } from "../core/data-calls.js";
+import { serializeError } from "@statewalker/webrun-streams";
+import { type ChannelCallHandler, callChannel } from "../core/data-calls.js";
 import type { MessageTarget } from "../core/message-target.js";
 import { newRegistry } from "../core/registry.js";
+import {
+  awaitActiveServiceWorker,
+  DEFAULT_SERVICE_WORKER_TIMEOUT,
+} from "../core/service-worker-control.js";
 import { handleHttpRequests, sendHttpRequest } from "../http/http-send-recieve.js";
 
 export * from "./split-service-url.js";
 
+/**
+ * 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: string = 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.
  */
-export function newServiceWorkerPort(): MessagePort {
+export function newServiceWorkerPort(registration?: ServiceWorkerRegistration): MessagePort {
   const channel = new MessageChannel();
   channel.port1.onmessage = (event) => {
-    navigator.serviceWorker.controller?.postMessage(event.data, [...event.ports]);
+    const worker = navigator.serviceWorker.controller ?? registration?.active;
+    worker?.postMessage(event.data, [...event.ports]);
   };
   navigator.serviceWorker.addEventListener("message", (event) => {
     channel.port1.postMessage(event.data, [...event.ports]);
@@ -25,55 +44,47 @@ export interface InitServiceWorkerOptions {
   swUrl: string;
   scopeUrl?: string;
   type?: WorkerType;
+  /**
+   * Upper bound, in ms, for the wait for the worker to activate; past it the
+   * promise rejects with a `ServiceWorkerControlError`. Default
+   * `DEFAULT_SERVICE_WORKER_TIMEOUT` (30 s).
+   */
+  timeout?: number;
 }
 
 /**
- * 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`.
  */
-export async function initServiceWorker({
+export async function initServiceWorker(options: InitServiceWorkerOptions): Promise<ServiceWorker> {
+  return (await registerServiceWorker(options)).worker;
+}
+
+async function registerServiceWorker({
   swUrl,
   scopeUrl,
   type,
-}: InitServiceWorkerOptions): Promise<ServiceWorker> {
-  await navigator.serviceWorker.register(swUrl, { type, scope: scopeUrl });
-  const worker = await getServiceWorkerController();
-  await awaitServiceWorkerActivation(worker);
-  return worker;
-}
-
-function getServiceWorkerController(): Promise<ServiceWorker> {
-  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: ServiceWorker): Promise<void> {
-  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);
-  });
+  timeout = DEFAULT_SERVICE_WORKER_TIMEOUT,
+}: InitServiceWorkerOptions): Promise<{
+  registration: ServiceWorkerRegistration;
+  worker: ServiceWorker;
+}> {
+  const registration = await navigator.serviceWorker.register(swUrl, { type, scope: scopeUrl });
+  const active = await awaitActiveServiceWorker(registration, { timeout });
+  return { registration, worker: navigator.serviceWorker.controller ?? active };
 }
 
 export interface ServiceOptions {
   key: string;
+  /**
+   * Where this service is mounted on the relay origin, e.g. `/` or `/peers/`.
+   * Omitted, the service stays reachable at `/~<key>/`, as before mounts.
+   */
+  path?: string;
   port: MessageTarget;
 }
 
@@ -83,10 +94,11 @@ export interface ServiceOptions {
  */
 export async function initHttpService(
   handler: HttpHandler,
-  { key, port }: ServiceOptions,
+  { key, path, port }: ServiceOptions,
 ): Promise<() => void> {
   return await registerConnectionsHandler({
     key,
+    path,
     communicationPort: port,
     handler: async (_event, _data, callPort) => {
       handleHttpRequests(callPort, handler);
@@ -111,16 +123,21 @@ export async function callHttpService(
 export interface RelayWindowHandlerOptions {
   swUrl?: string;
   scopeUrl?: string;
+  /** Passed to `initServiceWorker`: how long to wait for the relay worker to activate. */
+  timeout?: number;
 }
 
 /**
  * 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.
  */
 export function getRelayWindowMessageHandler({
-  swUrl = `${new URL("./index-sw.js", import.meta.url)}`,
-  scopeUrl = `${new URL("../", import.meta.url)}`,
+  swUrl = `${new URL("./index-sw.js", moduleUrl)}`,
+  scopeUrl = `${new URL("../", moduleUrl)}`,
+  timeout,
 }: RelayWindowHandlerOptions = {}): (ev: MessageEvent) => Promise<void> {
   let externalPort: MessagePort | undefined;
   return async (ev) => {
@@ -132,8 +149,15 @@ export function getRelayWindowMessageHandler({
       return;
     }
     externalPort = newExternalPort;
-    await initServiceWorker({ swUrl, scopeUrl });
-    const serviceWorkerPort = newServiceWorkerPort();
+    let registration: ServiceWorkerRegistration;
+    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]);
     };
@@ -160,7 +184,7 @@ export interface RemoteRelayChannel {
  * returns the port to be used with `initHttpService` / `callHttpService`.
  */
 export async function newRemoteRelayChannel({
-  baseUrl = new URL("../public-relay/", import.meta.url),
+  baseUrl = new URL("../public-relay/", moduleUrl),
   url = new URL("relay.html", baseUrl),
   container = document.body,
 }: RemoteRelayChannelOptions = {}): Promise<RemoteRelayChannel> {
@@ -240,22 +264,72 @@ export async function initializeConnection({
 
 export interface RegisterConnectionsHandlerOptions {
   key: string;
+  /** Where this service is mounted; see `ServiceOptions.path`. */
+  path?: string;
   handler: (event: MessageEvent, data: unknown, port: MessagePort) => boolean | Promise<boolean>;
   communicationPort: MessageTarget;
 }
 
 export async function registerConnectionsHandler({
   key,
+  path,
   handler,
   communicationPort,
 }: RegisterConnectionsHandlerOptions): Promise<() => void> {
   const [register, cleanup] = newRegistry();
-  await callChannel(communicationPort, "REGISTER", { key });
+  // `path` is omitted rather than sent as undefined: the worker distinguishes
+  // "mounted at /" from "not mounted", and a key with no path keeps /~<key>/.
+  await callChannel(communicationPort, "REGISTER", path == null ? { key } : { key, path });
   register(() => callChannel(communicationPort, "UNREGISTER", { key }));
   register(
-    handleChannelCalls(communicationPort, "CONNECT", async (event, data, port) => {
+    handleKeyedChannelCalls(communicationPort, "CONNECT", key, async (event, data, port) => {
       return await handler(event, data, port);
     }),
   );
   return cleanup;
 }
+
+/**
+ * `handleChannelCalls`, but only for calls whose `params.key` is `key`.
+ *
+ * ONE CONNECTION CARRIES SEVERAL SERVICES — an app at `/` and a mesh gateway
+ * at `/peers/` over one relay iframe is the shape mounts exist for. Plain
+ * `handleChannelCalls` cannot do that: every listener it has for a call type
+ * runs on every message, and each is handed the SAME reply port and the SAME
+ * transferred stream port. Two services then both serve the one channel the
+ * worker is reading, and its response comes back with both bodies in it.
+ *
+ * WHY NOT A FILTER INSIDE THE HANDLER. Returning `false` for a foreign key
+ * does not help: `handleChannelCalls` still replies, `callChannel` resolves on
+ * the FIRST reply it receives, and the loser's `false` reaches the worker as
+ * "the client refused" — a 403, non-deterministically. A service that is not
+ * the addressee must stay SILENT and leave the transferred port untouched.
+ *
+ * Local to this module on purpose. `handleChannelCalls` is also used where a
+ * call carries no key (REGISTER/UNREGISTER, and the worker's own CONNECT in
+ * `index-sw.ts`, which is the other direction), so its semantics must not
+ * change.
+ */
+function handleKeyedChannelCalls(
+  target: MessageTarget,
+  callType: string,
+  key: string,
+  handler: ChannelCallHandler,
+): () => void {
+  const listener = async (event: MessageEvent) => {
+    const data = event.data as { type?: string; params?: { key?: unknown } } | null | undefined;
+    if (!data || data.type !== callType) return;
+    if (data.params?.key !== key) return;
+    const [port, ...transfers] = (event.ports ?? []) as MessagePort[];
+    const response: { result?: unknown; error?: unknown } = {};
+    try {
+      response.result = await handler(event, data.params, ...transfers);
+    } catch (error) {
+      response.error = serializeError(error);
+    }
+    port?.postMessage(response);
+  };
+  target.addEventListener("message", listener);
+  target.start?.();
+  return () => target.removeEventListener("message", listener);
+}

package/src/relay/mount-table.ts

@@ -0,0 +1,115 @@
+/**
+ * Which registered service owns a URL.
+ *
+ * A pure lookup: no ServiceWorker, no storage, no I/O, so the routing rules
+ * can be tested as arithmetic rather than through a browser.
+ *
+ * TWO KINDS OF MOUNT, AND WHY BOTH. A `path` is a prefix, which is all most
+ * hosts need and costs nothing to match. A `match` predicate is the escape
+ * hatch for anything richer -- a host that wants URLPattern brings it and pays
+ * for it; this file must stay dependency-free, because it runs in a
+ * ServiceWorker that has to start fast.
+ *
+ * SPECIFICITY, NOT REGISTRATION ORDER. Prefixes are tried longest-first, so a
+ * catch-all at "/" cannot swallow "/peers/" and a host need not register in a
+ * careful order. Predicates are opaque -- nothing can be said about how
+ * specific they are -- so they are tried after every prefix, in the order they
+ * were registered.
+ */
+
+export interface MountSpec {
+  /** A path prefix, e.g. `/peers/`. `/` is the whole origin. */
+  path?: string;
+  /** Anything richer. Consulted only when no prefix matches. */
+  match?: (url: URL) => boolean;
+}
+
+export interface MountTable {
+  /** Add or replace the mount for `key`. */
+  set(key: string, spec: MountSpec): void;
+  remove(key: string): void;
+  /** The key that owns `url`, or `undefined` — meaning "not the relay's". */
+  find(url: URL): string | undefined;
+  /**
+   * Is `url` reserved by `exclude`? `find` already applies it, but the relay
+   * has a SECOND route — the `/~<key>/` spelling, which does not go through
+   * the table at all — and "an excluded path is never claimed" has to hold
+   * for both. The predicate lives here so there is one copy of it.
+   */
+  excludes(url: URL): boolean;
+}
+
+export interface MountTableOptions {
+  /**
+   * Paths the relay never claims, checked BEFORE the table. A root mount
+   * matches every path, so a host with files of its own (a relay page, a
+   * worker, hashed assets) is unusable without this.
+   */
+  exclude?: (url: URL) => boolean;
+}
+
+interface Entry {
+  key: string;
+  /** `""` for a predicate-only mount; otherwise `/` or `/a/b/`. */
+  prefix: string;
+  match?: (url: URL) => boolean;
+  /** Registration order, to break ties between predicates. */
+  seq: number;
+}
+
+/** `/` stays `/`; `/peers` and `/peers/` both become `/peers/`. */
+function normalise(path: string): string {
+  if (path === "" || path === "/") return "/";
+  const withSlash = path.startsWith("/") ? path : `/${path}`;
+  return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
+}
+
+/** Does `prefix` own `pathname`? `/peers/` owns `/peers/`, `/peers` and `/peers/x`. */
+function owns(prefix: string, pathname: string): boolean {
+  if (prefix === "/") return true;
+  if (pathname.startsWith(prefix)) return true;
+  return `${pathname}/` === prefix;
+}
+
+export function newMountTable(options: MountTableOptions = {}): MountTable {
+  const entries = new Map<string, Entry>();
+  let seq = 0;
+
+  return {
+    set(key, spec) {
+      entries.set(key, {
+        key,
+        prefix: spec.path == null ? "" : normalise(spec.path),
+        match: spec.match,
+        seq: seq++,
+      });
+    },
+
+    remove(key) {
+      entries.delete(key);
+    },
+
+    excludes(url) {
+      return options.exclude?.(url) === true;
+    },
+
+    find(url) {
+      if (options.exclude?.(url) === true) return undefined;
+
+      let best: Entry | undefined;
+      for (const entry of entries.values()) {
+        if (entry.prefix === "" || !owns(entry.prefix, url.pathname)) continue;
+        if (best == null || entry.prefix.length > best.prefix.length) best = entry;
+      }
+      if (best != null) return best.key;
+
+      const predicates = [...entries.values()]
+        .filter((entry) => entry.match != null)
+        .sort((a, b) => a.seq - b.seq);
+      for (const entry of predicates) {
+        if (entry.match?.(url) === true) return entry.key;
+      }
+      return undefined;
+    },
+  };
+}

package/src/relay/split-service-url.ts

@@ -12,19 +12,79 @@ export interface SplitServiceUrl {
  */
 export function splitServiceUrl(url: URL | string, separator = "~"): SplitServiceUrl {
   const str = `${url}`;
-  const idx = str.indexOf(separator);
-  let baseUrl = "";
-  let key = "";
-  let path = "";
-  if (idx >= 0) {
-    baseUrl = str.substring(0, idx + separator.length);
-    str.substring(idx + separator.length).replace(/^([^/]+)/, (match, $1) => {
-      baseUrl += match;
-      if (baseUrl.length < str.length) baseUrl += "/";
-      key = $1;
-      path = str.substring(baseUrl.length);
-      return "";
-    });
+  const empty = { url: str, key: "", baseUrl: "", path: "" };
+
+  // Strip query and fragment to prevent false positives on `?q=~foo` or `#~FS`.
+  // Extract the prefix (origin) and path from the input verbatim, preserving case
+  // and form (e.g., `//host` vs. `http://host`, `HTTPS://` vs. `https://`).
+  const hashIdx = str.indexOf("#");
+  const queryIdx = str.indexOf("?");
+  let strippedEnd = str.length;
+  if (hashIdx >= 0) strippedEnd = Math.min(strippedEnd, hashIdx);
+  if (queryIdx >= 0) strippedEnd = Math.min(strippedEnd, queryIdx);
+  const stripped = str.slice(0, strippedEnd);
+
+  // Identify where the path begins in the input. Three cases:
+  // 1. scheme://authority/path — prefix is scheme://authority
+  // 2. //authority/path — prefix is //authority
+  // 3. relative path — prefix is empty
+  let prefixEnd = 0;
+  const schemeMatch = stripped.match(/^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//);
+  if (schemeMatch) {
+    // scheme://authority/path — find the next / after the scheme
+    prefixEnd = schemeMatch[0].length;
+    const slashIdx = stripped.indexOf("/", prefixEnd);
+    if (slashIdx >= 0) {
+      prefixEnd = slashIdx;
+    } else {
+      return empty; // No path
+    }
+  } else if (stripped.startsWith("//")) {
+    // //authority/path — find the next / after the //
+    prefixEnd = 2;
+    const slashIdx = stripped.indexOf("/", prefixEnd);
+    if (slashIdx >= 0) {
+      prefixEnd = slashIdx;
+    } else {
+      return empty; // No path
+    }
   }
+  // else prefixEnd = 0: relative URL
+
+  const prefix = stripped.slice(0, prefixEnd);
+  const pathPart = stripped.slice(prefixEnd);
+
+  // Check if pathPart starts with the separator, anchored at the segment boundary.
+  // With an authority the path always begins with `/`, so the separator must be
+  // at `/<separator>`. Without one the input is either ROOT-RELATIVE
+  // (`/~FS/a/b` -- `location.pathname`, or any root-absolute href) or plain
+  // relative (`~FS/a/b`), and both are accepted: treating "no authority" as
+  // "relative" made every root-relative caller get nothing back.
+  let keyStart: number;
+  let rooted = false;
+  if (prefix === "") {
+    if (pathPart.startsWith(`/${separator}`)) {
+      rooted = true;
+      keyStart = separator.length + 1;
+    } else if (pathPart.startsWith(separator)) {
+      keyStart = separator.length;
+    } else {
+      return empty;
+    }
+  } else {
+    if (!pathPart.startsWith(`/${separator}`)) return empty;
+    keyStart = separator.length + 1;
+  }
+
+  const rest = pathPart.slice(keyStart);
+  const slash = rest.indexOf("/");
+  const key = slash < 0 ? rest : rest.slice(0, slash);
+  if (key === "") return empty;
+
+  // The base keeps the input's own form: `https://host/~FS/`, `//host/~FS/`,
+  // `/~FS/` and `~FS/` each round-trip as written.
+  const base = prefix === "" ? (rooted ? "/" : "") : `${prefix}/`;
+  const baseUrl = `${base}${separator}${key}${slash < 0 ? "" : "/"}`;
+  const path = slash < 0 ? "" : rest.slice(slash + 1);
   return { url: str, key, baseUrl, path };
 }

package/src/relay-sw.ts

@@ -1,7 +1,15 @@
 /// <reference lib="webworker" />
 
-import { startRelayServiceWorker } from "./relay/index-sw.js";
+import { type RelayServiceWorkerOptions, startRelayServiceWorker } from "./relay/index-sw.js";
 
-declare const self: ServiceWorkerGlobalScope;
+declare const self: ServiceWorkerGlobalScope & { RELAY_OPTIONS?: RelayServiceWorkerOptions };
 
-startRelayServiceWorker(self);
+// OPTIONS FROM A GLOBAL, because this bundle is loaded by `importScripts` from
+// a host's own worker script, which runs first and can set them. A classic
+// worker cannot pass arguments any other way, and module service workers are
+// not reachable through the relay page's registration (the bundle is IIFE, and
+// `getRelayWindowMessageHandler` registers with no `type`).
+//
+// Absent, the options are `{}` -- exactly what this file passed before, so a
+// host that only `importScripts`es the bundle sees no change.
+startRelayServiceWorker(self, self.RELAY_OPTIONS ?? {});

package/src/relay-worker.ts

@@ -0,0 +1,20 @@
+/**
+ * The relay ServiceWorker runtime, for a host that builds its own worker.
+ *
+ * TWO WAYS TO SHIP THE RELAY WORKER, and this is the typed one. A host that
+ * takes the prebuilt bundle loads `@statewalker/webrun-http-browser/relay-sw`
+ * through classic `importScripts` and passes its options in
+ * `self.RELAY_OPTIONS`, which cannot be typed from the outside because that
+ * bundle ships no declarations. A host that bundles its own worker imports
+ * this module instead and calls `startRelayServiceWorker(self, { … })`
+ * directly, with `RelayServiceWorkerOptions` to type the options — including
+ * `self.RELAY_OPTIONS`, for a host writing the tiny loader script by hand.
+ *
+ * Kept as its own entry rather than re-exported from the package root: this
+ * code only runs inside a ServiceWorker, and the root entry is what pages
+ * import.
+ */
+
+export type { RelayServiceWorkerOptions } from "./relay/index-sw.js";
+export { startRelayServiceWorker } from "./relay/index-sw.js";
+export type { MountSpec } from "./relay/mount-table.js";

package/src/sw/sw-dispatcher.ts

@@ -1,12 +1,32 @@
 import { get, set } from "idb-keyval";
 import { callChannel, handleChannelCalls } from "../core/data-calls.js";
+import { withDeadline } from "../core/deadline.js";
 import { newRegistry } from "../core/registry.js";
+import {
+  awaitServiceWorkerControl,
+  DEFAULT_SERVICE_WORKER_TIMEOUT,
+  handleClaimRequests,
+  ServiceWorkerControlError,
+} from "../core/service-worker-control.js";
 
 export interface SwPortHandlerOptions {
   key: string;
   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 {
@@ -84,6 +104,15 @@ export class SwPortHandler {
     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(): Promise<void> {
     if (!this._registrationPromise) {
       this._registrationPromise = (async () => {
@@ -97,20 +126,44 @@ export class SwPortHandler {
         });
         register(() => registration.unregister());
 
-        register(
-          handleChannelCalls(
-            navigator.serviceWorker,
-            "UPDATE_COMMUNICATION_PORT",
-            async (_event, _params, port: MessagePort) => {
-              await this._setCommunicationPort(port);
-              return this._getRegistrationInfo();
-            },
-          ),
+        const stopListening = handleChannelCalls(
+          navigator.serviceWorker,
+          "UPDATE_COMMUNICATION_PORT",
+          async (_event, _params, port: MessagePort) => {
+            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 ?? DEFAULT_SERVICE_WORKER_TIMEOUT;
+        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) {
+          // Forget this attempt so a later start() retries. Stop listening,
+          // but keep the registration: the worker is fine — it is this page
+          // that is not controlled, and other pages may be using the worker.
+          stopListening();
+          this._cleanupRegistrations = undefined;
+          this._registrationPromise = undefined;
+          throw error;
+        }
       })();
     }
     return this._registrationPromise;
@@ -129,37 +182,6 @@ export class SwPortHandler {
   }
 }
 
-function getServiceWorkerController(): Promise<ServiceWorker> {
-  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: ServiceWorker): Promise<void> {
-  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);
-  });
-}
-
 export interface SwPortDispatcherOptions {
   self: ServiceWorkerGlobalScope;
   log?: (...args: unknown[]) => void;
@@ -221,7 +243,8 @@ export class SwPortDispatcher {
   }
 
   start(): void {
-    this._cleanup = handleChannelCalls(
+    const stopClaims = handleClaimRequests(this.self);
+    const stopPortUpdates = handleChannelCalls(
       this.self,
       "UPDATE_COMMUNICATION_PORT",
       async (event, channelInfo, port: MessagePort) => {
@@ -232,6 +255,10 @@ export class SwPortDispatcher {
         return { ...(channelInfo as ChannelInfo) };
       },
     );
+    this._cleanup = () => {
+      stopClaims();
+      stopPortUpdates();
+    };
 
     this.self.addEventListener("install", (event) => {
       this.log("Skip waiting on install.", event);