@statewalker/webrun-http-browser 0.3.4 → 0.5.0

package/README.md

@@ -30,6 +30,15 @@ the raw platform APIs, and this package fills them:
 Combining both modes means the same handler code works in an app you
 control *and* in an embed you don't.
 
+## Install
+
+```sh
+npm install @statewalker/webrun-http-browser
+```
+
+Browser-only — it needs `navigator.serviceWorker`, so a secure context
+(`https://` or `localhost`) is required. No peer dependencies.
+
 ## How to use
 
 ```sh
@@ -38,8 +47,8 @@ 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) and `@statewalker/webrun-streams` (stream and error helpers) |
-| `@statewalker/webrun-http-browser/sw` | Same-origin adapter classes: `SwHttpAdapter` (page), `SwHttpDispatcher` (SW), `startHttpDispatcher` bootstrap |
+| `@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; `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 |
 
@@ -115,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:
 
@@ -215,6 +263,87 @@ Why it's interesting:
   no tooling. Shows how small the glue between a platform API and a
   `(Request) ⇒ Response` handler can be.
 
+## Exports
+
+The package root re-exports everything from
+[`@statewalker/webrun-streams`](../webrun-streams) and
+[`@statewalker/webrun-http-streams`](../webrun-http-streams), so existing
+imports keep working after those extractions. Its own surface is below.
+
+### Relay mode
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `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. |
+| `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. |
+| `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` | interface | Its result shape. |
+
+### ServiceWorker lifecycle
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `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
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `initializeConnection(opts)` | function | Sends `CONNECT` for a service `key`; resolves a `MessagePort`, or `null` if no such service. |
+| `InitializeConnectionOptions` | interface | `{ key, communicationPort, ...extra }` — extra fields ride along in the CONNECT payload. |
+| `registerConnectionsHandler(opts)` | function | Registers a `key` and answers inbound `CONNECT`s. Returns a cleanup that unregisters. |
+| `RegisterConnectionsHandlerOptions` | interface | `{ key, handler, communicationPort }`. |
+
+### Messaging primitives
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `callChannel(target, type, data, port?)` | function | One typed request/response over a `MessageTarget`. |
+| `handleChannelCalls(target, type, handler)` | function | Answer those calls. Returns an unsubscribe. |
+| `ChannelCallHandler` | type | The handler signature the two above exchange. |
+| `newInvokationChannel(opts)` | function | Multiplexed invocations over one target. |
+| `InvocationChannel` / `NewInvocationChannelOptions` | interface | Its result and options. |
+| `handleStreams(...)` / `StreamHandler<T>` | function / type | Stream-shaped invocations over the same channel. |
+
+> **These stream primitives have no backpressure.** `sendStream`'s chunk sender
+> discards the promise it is handed, so a fast producer over a slow consumer
+> accumulates without bound; there is also no per-stream timeout and no chunking
+> to a transport's message ceiling. `@statewalker/webrun-rpc`'s `duplexOverPort`
+> is the replacement — one `Duplex` over one port, with the confirmation
+> withheld until the consumer has pulled. Migrating this package onto it is
+> planned, not done.
+| `MessageTarget` / `MessageSource` / `MessageSink` / `MessageListener` | interface / type | The structural port view everything above accepts — a `MessagePort`, a `Worker`, or a SW bridge. Defined in [`@statewalker/webrun-streams`](../webrun-streams) and re-exported here. |
+| `newRegistry(onError?)` | function | Small cleanup registry used for teardown. |
+| `Registry` / `NewRegistryResult` / `CleanupAction` | interface / type | Its shapes. |
+
+### HTTP over a port
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `sendHttpRequest(port, request)` | function | **Deprecated.** Ship a `Request` over a `MessageTarget`, await the `Response`. |
+| `handleHttpRequests(port, handler)` | function | **Deprecated.** Serve an `HttpHandler` on the other end of one. |
+
+### Subpath entry points
+
+| 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/sw-worker` | IIFE same-origin SW runtime, loadable via `importScripts(...)`. |
+
 ## Internals
 
 ### Source layout
@@ -225,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`.
 │                                  ┘
@@ -293,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.
@@ -313,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
@@ -336,8 +485,17 @@ 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
 
-MIT © statewalker
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/core/data-channels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-channels.d.ts","sourceRoot":"","sources":["../../src/core/data-channels.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqBzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,EACnC,IAAI,EACJ,OAEC,EACD,OAAuB,EACvB,SAAuC,GACxC,EAAE,2BAA2B,GAAG,iBAAiB,CAoEjD;AAED,wBAAuB,UAAU,CAAC,CAAC,EACjC,iBAAiB,EAAE,aAAa,EAChC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAYlC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,MAAM,IAAI,CAqBZ"}
+{"version":3,"file":"data-channels.d.ts","sourceRoot":"","sources":["../../src/core/data-channels.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqBzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CAC1B;AAED,wBAAgB,oBAAoB,CAAC,EACnC,IAAI,EACJ,OAEC,EACD,OAAuB,EACvB,SAAuC,GACxC,EAAE,2BAA2B,GAAG,iBAAiB,CAoEjD;AAED,wBAAuB,UAAU,CAAC,CAAC,EACjC,iBAAiB,EAAE,aAAa,EAChC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAmBlC;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD,wBAAgB,aAAa,CAAC,CAAC,EAC7B,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,MAAM,IAAI,CAqBZ"}

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/message-target.d.ts

@@ -1,16 +1,2 @@
-export type MessageListener = (event: MessageEvent) => void | Promise<void>;
-/** An object we can listen for `"message"` events on. */
-export interface MessageSource {
-    addEventListener(type: "message", listener: MessageListener): void;
-    removeEventListener(type: "message", listener: MessageListener): void;
-    start?(): void | Promise<void>;
-}
-/** An object we can post messages to (with optional transferable list). */
-export interface MessageSink {
-    postMessage(message: unknown, transfer?: Transferable[]): void;
-}
-/** Full-duplex message target: both sends and receives. */
-export interface MessageTarget extends MessageSource, MessageSink {
-    close?(): void | Promise<void>;
-}
+export type { MessageListener, MessageSink, MessageSource, MessageTarget, } from "@statewalker/webrun-rpc";
 //# sourceMappingURL=message-target.d.ts.map

package/dist/core/message-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../../src/core/message-target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACnE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;CAChE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAc,SAAQ,aAAa,EAAE,WAAW;IAC/D,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}
+{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../../src/core/message-target.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,GACd,MAAM,yBAAyB,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/http/http-send-recieve.d.ts

@@ -1,23 +1,36 @@
 import { type HttpHandler } from "@statewalker/webrun-http-streams";
 import type { MessageTarget } from "../core/message-target.js";
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port`. Once a `MessagePort` is established between
- * page and worker, `httpServe(port, handler)` provides equivalent semantics
- * with `callBidi` multiplexing, full-duplex streaming, and `AbortSignal`.
- * This helper remains for existing ServiceWorker setups that still consume the
- * `MessageTarget` surface; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Serve an `HttpHandler` over a `MessageTarget`, using this package's own
+ * `handleStreams` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `serveDuplexOverPort`, and serve HTTP on that with
+ * `httpServe(handler, options)` from `@statewalker/webrun-http-streams`.
+ *
+ * That path has backpressure; **this one does not.** `sendStream`'s chunk
+ * sender discards the promise it is given, so a fast producer over a slow
+ * consumer accumulates without bound. It also has no per-stream timeout and no
+ * chunking to a transport's message ceiling.
+ *
+ * Kept for existing ServiceWorker setups built on the `MessageTarget` surface.
  */
 export declare function handleHttpRequests(communicationPort: MessageTarget, handler: HttpHandler): () => void;
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port/fetch`. Once the page and SW share a
- * `MessagePort`, `fetchOverPort(port, request)` provides the same
- * `Request → Response` semantics with multiplexing via `callBidi`, JSONL
- * envelope framing, and native `AbortSignal` support. This helper remains for
- * existing ServiceWorker setups; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Ship a `Request` over a `MessageTarget` and await the `Response`, using this
+ * package's own `sendStream` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `duplexOverPort`, and drive HTTP over it with `httpFetch` from
+ * `@statewalker/webrun-http-streams`.
+ *
+ * Same caveat as {@link handleHttpRequests}: the transport underneath this
+ * helper has no backpressure, no per-stream timeout, and no chunking to a
+ * transport's message ceiling. Kept for existing ServiceWorker setups.
  */
 export declare function sendHttpRequest(communicationPort: MessageTarget, request: Request): Promise<Response>;
 //# sourceMappingURL=http-send-recieve.d.ts.map

package/dist/http/http-send-recieve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-send-recieve.d.ts","sourceRoot":"","sources":["../../src/http/http-send-recieve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA+B/D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,WAAW,GACnB,MAAM,IAAI,CAOZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAOnB"}
+{"version":3,"file":"http-send-recieve.d.ts","sourceRoot":"","sources":["../../src/http/http-send-recieve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAMjB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA+B/D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,WAAW,GACnB,MAAM,IAAI,CAOZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,iBAAiB,EAAE,aAAa,EAChC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAOnB"}