@statewalker/webrun-http-browser 0.4.2 → 0.6.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,8 +48,9 @@ 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/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` | 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. No declarations: it takes its options from `self.RELAY_OPTIONS` |
+| `@statewalker/webrun-http-browser/relay-worker` | The same runtime as a typed ES module, for a host that bundles its own relay worker: `startRelayServiceWorker(self, options)`, plus `RelayServiceWorkerOptions` and `MountSpec` to type them (including a hand-written `self.RELAY_OPTIONS`) |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE bundle of the same-origin SW runtime — ditto, for same-origin apps |
 
 ## Examples
@@ -101,6 +102,125 @@ const res = await callHttpService(
 serving a mini site; [`demo/demo-2.html`](./demo/demo-2.html) pipes a
 local-disk folder (File System Access API) through it.
 
+### Mounting a service at a path
+
+A service can claim a path prefix instead of living at `/~<key>/`. Both the
+key and the path are the caller's, and several services can share **one**
+relay connection — the shape mounts exist for is an app at the origin root
+and, say, a gateway one level down, both reachable through the same iframe:
+
+```ts
+const connection = await newRemoteRelayChannel(/* … */);
+
+await initHttpService(appHandler, { key: "app", path: "/", port: connection.port });
+await initHttpService(meshHandler, { key: "mesh", path: "/peers/", port: connection.port });
+```
+
+A `CONNECT` is routed to the service named in its `key`, so the two never see
+each other's calls even though they share one port. (Earlier builds routed
+every `CONNECT` on a connection to every registered service, which collided
+whenever more than one service shared a port — fixed before this shipped.)
+
+The worker routes by the longest matching path prefix, so a catch-all at `/`
+does not shadow `/peers/`, and registration order does not matter. A service
+registered with no `path` is reachable at `/~<key>/`, exactly as before —
+unless the host declared that key in `mounts`, in which case the host's mount
+stands and the page need not repeat it.
+
+**A request that matches no mount is not the relay's** — the worker does not
+answer it at all, so the browser performs it exactly as it would with no
+worker installed. That is what lets a host serve its own files from the same
+origin, and it is why a root mount needs `exclude`.
+
+**The matched prefix is NOT stripped.** A handler mounted at `/peers/`
+receives `/peers/12D3Koo/llm`, not `/12D3Koo/llm` — the request reaches it
+with the path the browser asked for, whichever mount matched. A handler that
+wants to route relative to its mount keeps its own `basePath` and strips the
+prefix itself.
+
+These options are read by `startRelayServiceWorker`, which a host that
+bundles its own relay worker imports from
+`@statewalker/webrun-http-browser/relay-worker` and calls directly (see the
+options table below for the prebuilt-bundle equivalent):
+
+```ts
+import { startRelayServiceWorker } from "@statewalker/webrun-http-browser/relay-worker";
+
+startRelayServiceWorker(self, {
+  exclude: (url) =>
+    url.pathname === "/index.html" ||
+    url.pathname === "/relay.html" ||
+    url.pathname === "/relay-sw.js",
+  takeover: "first-wins",
+  canRegister: (client, _key) => new URL(client.url).pathname === "/relay.html",
+  decorateResponse: (response) => withMyHeaders(response),
+});
+```
+
+> **Mounting at `/` — set `takeover: "first-wins"` and `canRegister`.**
+> The default is `takeover: "last-wins"` with no `canRegister`, which is what
+> the relay has always done: the last page to REGISTER a key gets it. Before
+> mounts the worst that bought a rogue or buggy same-origin page was
+> `/~<key>/`; with mounts it can claim the **origin root**, and the mount is
+> persisted in IndexedDB, so it outlives the page and every worker restart.
+> On an origin where more than the host's own page can reach the relay,
+> `takeover: "first-wins"` keeps a live holder's key and `canRegister` says
+> which client may ask for it — set both, together, for any mount at `/`.
+
+A root mount claims *every* path under the worker's scope, including the
+host's own navigation. If `exclude` only covers the relay page and its
+worker script, a reload requests the host's own entry page — say
+`/index.html` — through the mount too, the mount has no handler for it, and
+the origin cannot come back. `exclude` needs three things, always: the relay
+page, the worker script, and the host's own entry page. That third one is
+easy to miss because nothing fails until the first reload.
+
+An excluded page is one the worker does not answer, and in Firefox such a
+page can load **uncontrolled** even while the worker is running — then its
+own `fetch()` never reaches the worker and its mounts look dead. The remedy
+is the one this package already ships for that case: call
+`awaitServiceWorkerControl(registration)` (exported from the package root)
+before relying on `fetch()` from an excluded page. A page *served by* a mount
+is a navigation the worker answers, so it is controlled from its first byte
+and needs nothing.
+
+#### `self.RELAY_OPTIONS` — options for the prebuilt worker
+
+`dist/relay-sw.js` is an IIFE loaded via classic `importScripts`, so a host
+that uses the shipped worker (rather than building its own from
+`startRelayServiceWorker`) cannot pass options as arguments. It reads them
+instead from `self.RELAY_OPTIONS`, which the host's own tiny worker script
+sets *before* importing the bundle:
+
+```js
+// relay-sw.js — served next to your relay page.
+self.RELAY_OPTIONS = {
+  exclude: (url) => url.pathname === "/index.html" || url.pathname === "/relay.html" || url.pathname === "/relay-sw.js",
+  takeover: "first-wins",
+};
+importScripts("/path/to/node_modules/@statewalker/webrun-http-browser/dist/relay-sw.js");
+```
+
+This is the only way a prebuilt-worker host reaches `exclude`, `takeover`,
+`canRegister` or `decorateResponse` — omit it and the worker boots with `{}`,
+exactly as it did before mounts. The bundle ships no declarations, so to type
+that object (in a TypeScript loader script, or to check it before shipping)
+import the type from the runtime entry:
+
+```ts
+import type { RelayServiceWorkerOptions } from "@statewalker/webrun-http-browser/relay-worker";
+
+declare const self: ServiceWorkerGlobalScope & { RELAY_OPTIONS?: RelayServiceWorkerOptions };
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `mounts` | none | A fixed table, for a host that knows its services at build time. Each entry is `{ key, path? , match? }`. A key declared here is the host's: a page's REGISTER or UNREGISTER for the same key never replaces or removes it, so the page can register with no `path` of its own. |
+| `exclude` | none | Paths the relay never claims — neither through the table nor through the `/~<key>/` spelling. Checked first. |
+| `canRegister` | everyone | Refuse a registration from the wrong page. |
+| `takeover` | `"last-wins"` | `"first-wins"` keeps a live holder's key. |
+| `decorateResponse` | none | Stamp headers on responses the relay makes; not applied to network fetches. |
+
 ### Same-origin mode
 
 Your page registers its own SW, handlers are local to the page:
@@ -124,6 +244,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:
 
@@ -238,21 +397,28 @@ imports keep working after those extractions. Its own surface is below.
 | `newRemoteRelayChannel(opts?)` | function | Embeds the hidden relay iframe, handshakes a `MessageChannel`, resolves a `RemoteRelayChannel`. |
 | `RemoteRelayChannelOptions` | interface | `baseUrl`, `url`, `container` — where the relay lives and what to append the iframe to. |
 | `RemoteRelayChannel` | interface | `{ baseUrl, port, close() }`. |
-| `initHttpService(handler, opts)` | function | Registers `handler` as the server for a service `key` on the relay. Returns a cleanup. |
+| `initHttpService(handler, opts)` | function | Registers `handler` as the server for a service `key` on the relay, optionally mounted at `path`. Several services may share one `port`. Returns a cleanup. |
 | `callHttpService(request, opts)` | function | Sends a `Request` to the service under `key`; resolves its `Response`. |
-| `ServiceOptions` | interface | `{ key: string; port: MessageTarget }` — shared by the two above. |
+| `ServiceOptions` | interface | `{ key: string; path?: string; port: MessageTarget }` — shared by the two above. `path` mounts the service (see [Mounting a service at a path](#mounting-a-service-at-a-path)); omitted, it stays at `/~<key>/`. |
 | `getRelayWindowMessageHandler(opts?)` | function | The `window.onmessage` handler that runs *inside* the relay iframe. |
 | `RelayWindowHandlerOptions` | interface | `swUrl`, `scopeUrl` for that handler. |
-| `splitServiceUrl(url, separator?)` | function | Splits a relay URL into service key + remaining path (default separator `~`). |
+| `splitServiceUrl(url, separator?)` | function | Splits a relay URL into service key + remaining path (default separator `~`); anchored to the pathname, so a query string like `?q=~foo` is never read as a service. |
 | `SplitServiceUrl` | interface | Its result shape. |
+| `startRelayServiceWorker(self, opts?)` | function | The SW side of the relay: routes `fetch` to the client that registered a mount, and answers `REGISTER`/`UNREGISTER`/`CONNECT`. Not re-exported from the package root — it is what the prebuilt `dist/relay-sw.js` calls internally; see [`self.RELAY_OPTIONS`](#selfrelay_options--options-for-the-prebuilt-worker). |
+| `RelayServiceWorkerOptions` | interface | `{ mounts?, exclude?, canRegister?, takeover?, decorateResponse? }` — see the options table in [Mounting a service at a path](#mounting-a-service-at-a-path). |
 
 ### ServiceWorker lifecycle
 
 | 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
 
@@ -297,7 +463,7 @@ imports keep working after those extractions. Its own surface is below.
 | Entry | Purpose |
 | --- | --- |
 | `@statewalker/webrun-http-browser/sw` | `SwHttpAdapter` — the same-origin ServiceWorker adapter. |
-| `@statewalker/webrun-http-browser/relay-sw` | IIFE relay SW runtime, loadable via `importScripts(...)`. |
+| `@statewalker/webrun-http-browser/relay-sw` | IIFE relay SW runtime, loadable via `importScripts(...)`. Reads its options from `self.RELAY_OPTIONS`, set before the `importScripts` call. |
 | `@statewalker/webrun-http-browser/sw-worker` | IIFE same-origin SW runtime, loadable via `importScripts(...)`. |
 
 ## Internals
@@ -310,10 +476,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 +548,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 +579,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 +607,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"}