@statewalker/webrun-http-browser 0.3.4 → 0.5.0

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region ../webrun-streams/src/collect.ts
+//#region ../webrun-streams/dist/index.js
 /** Collect all items from an async iterable into an array. */
 async function collect(input) {
 	const items = [];
@@ -28,8 +28,17 @@ async function collectString(input) {
 	for await (const chunk of input) result += chunk;
 	return result;
 }
-//#endregion
-//#region ../webrun-streams/src/errors.ts
+/**
+* Thrown by `emulateMux` and adapters when the underlying transport closes
+* while one or more `Duplex` calls are in flight. Consumers can catch by
+* `instanceof TransportClosedError` or by checking `error.name`.
+*/
+var TransportClosedError = class extends Error {
+	name = "TransportClosedError";
+	constructor(message = "transport closed") {
+		super(message);
+	}
+};
 function serializeError(error) {
 	if (error instanceof Error) {
 		const out = {
@@ -53,19 +62,113 @@ function deserializeError(error) {
 	const payload = typeof error === "string" ? { message: error } : error;
 	return Object.assign(new Error(payload.message), payload);
 }
-//#endregion
-//#region ../webrun-streams/src/emulate-mux.ts
+function newCreditLedger(initial = 0) {
+	let available = initial;
+	let failure;
+	const waiters = [];
+	const pump = () => {
+		while (waiters.length > 0 && available > 0) {
+			const next = waiters[0];
+			if (!next) return;
+			waiters.shift();
+			const granted = Math.min(next.upTo, available);
+			available -= granted;
+			next.resolve(granted);
+		}
+	};
+	return {
+		get available() {
+			return available;
+		},
+		reserve(upTo) {
+			if (failure) return Promise.reject(failure);
+			if (!(upTo >= 1)) return Promise.reject(/* @__PURE__ */ new RangeError(`newCreditLedger: reserve(${upTo}) — upTo must be at least 1`));
+			if (waiters.length === 0 && available > 0) {
+				const granted = Math.min(upTo, available);
+				available -= granted;
+				return Promise.resolve(granted);
+			}
+			return new Promise((resolve, reject) => {
+				waiters.push({
+					upTo,
+					resolve,
+					reject
+				});
+			});
+		},
+		grant(units) {
+			if (failure) return;
+			available += units;
+			pump();
+		},
+		fail(err) {
+			failure ??= err;
+			while (waiters.length > 0) waiters.shift()?.reject(err);
+		}
+	};
+}
 /**
-* Thrown by `emulateMux` and adapters when the underlying transport closes
-* while one or more `Duplex` calls are in flight. Consumers can catch by
-* `instanceof TransportClosedError` or by checking `error.name`.
+* Grants are batched: replenishing on every chunk while the receiver is
+* behind would reinvent the per-frame ACK this change exists to remove.
+* `threshold` is the fraction of the window that must drain before a grant is
+* emitted.
+*
+* The batch is flushed unconditionally once the receive queue is empty, even
+* below the threshold, so the receiver never sits on credit it owes. Note what
+* this is and is not: paired with a {@link CreditLedger}, a sender blocks only
+* at *exactly* zero credit, and at that point the receiver holds the entire
+* window as `pending` — above any threshold at or below the whole window — so
+* the threshold alone cannot deadlock that pairing. The flush is what keeps
+* that from being an argument about a global accounting identity: it is
+* locally decidable from one boolean, and it returns owed credit now rather
+* than at the next threshold crossing. It costs an extra frame only when the
+* consumer is keeping pace, which is exactly when the sender is not blocked
+* and the frame is cheap.
 */
-var TransportClosedError = class extends Error {
-	name = "TransportClosedError";
-	constructor(message = "transport closed") {
-		super(message);
-	}
-};
+function newCreditGrantor(window, threshold = .5) {
+	const trigger = Math.max(1, Math.floor(window * threshold));
+	let pending = 0;
+	return { consumed(units, queueEmpty) {
+		pending += units;
+		if (pending === 0) return 0;
+		if (pending < trigger && !queueEmpty) return 0;
+		const grant = pending;
+		pending = 0;
+		return grant;
+	} };
+}
+/**
+* Credit payloads are a single big-endian uint32, matching the frame header's
+* byte order.
+*
+* Deliberately **not** re-exported from `index.ts`: this is an internal codec
+* for the `emulateMux` wire format, not a compatibility commitment. Tests
+* import it by path.
+*/
+/** The largest credit a single frame can advertise or grant: 2^32 - 1. */
+const MAX_UINT32 = 4294967295;
+/**
+* Clamps rather than wraps. `n >>> 0` is the obvious spelling and it is wrong
+* here: 2^32 becomes **0**, so a 4 GiB window advertises *zero credit* and the
+* peer stalls forever with no error — the exact silent hang credit exists to
+* remove. 2^32 + 5 becomes 5, which looks like a working window and is worse.
+* Anything above the ceiling is advertised as the ceiling.
+*/
+function encodeUint32(n) {
+	const bytes = /* @__PURE__ */ new Uint8Array(4);
+	const clamped = Number.isFinite(n) ? Math.min(MAX_UINT32, Math.max(0, Math.floor(n))) : 0;
+	new DataView(bytes.buffer).setUint32(0, clamped, false);
+	return bytes;
+}
+/**
+* Returns `undefined` rather than a garbage number when the payload is too
+* short, so a truncated frame — or one from a peer predating credit — is
+* detectable at the call site instead of silently granting nonsense.
+*/
+function decodeUint32(bytes) {
+	if (bytes.byteLength < 4) return void 0;
+	return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, false);
+}
 const TYPE_OPEN = 1;
 const TYPE_DATA = 2;
 const TYPE_ACK = 3;
@@ -81,6 +184,7 @@ function emulateMux(channel, opts = {}) {
 	const maxStreams = opts.maxStreams ?? DEFAULT_MAX_STREAMS;
 	const mtu = opts.mtu ?? DEFAULT_MTU;
 	const maxStreamBuffer = opts.maxStreamBuffer ?? DEFAULT_MAX_STREAM_BUFFER;
+	if (!(maxStreamBuffer >= 1)) throw new RangeError(`emulateMux: maxStreamBuffer must be at least 1, got ${maxStreamBuffer}`);
 	const side = opts.side ?? "initiator";
 	const streams = /* @__PURE__ */ new Map();
 	let nextLocalId = side === "initiator" ? 2 : 1;
@@ -101,13 +205,9 @@ function emulateMux(channel, opts = {}) {
 	const teardownStream = (s, err) => {
 		if (s.closed) return;
 		s.closed = true;
-		const resolve = s.resolveAck;
-		const reject = s.rejectAck;
-		s.resolveAck = null;
-		s.rejectAck = null;
-		if (reject && err) reject(err);
-		else resolve?.();
+		s.outboundCredit.fail(err ?? new TransportClosedError("emulateMux: stream closed"));
 		s.doneIn(err);
+		s.cancelInput?.();
 		streams.delete(s.id);
 	};
 	/**
@@ -141,8 +241,8 @@ function emulateMux(channel, opts = {}) {
 			}),
 			pushIn: queue.push,
 			doneIn: queue.done,
-			resolveAck: null,
-			rejectAck: null,
+			outboundCredit: newCreditLedger(0),
+			grantor: newCreditGrantor(maxStreamBuffer),
 			closed: false,
 			inDone: false,
 			outDone: false,
@@ -151,20 +251,24 @@ function emulateMux(channel, opts = {}) {
 		return state;
 	};
 	const pumpOutbound = async (s, input) => {
+		const iterator = input[Symbol.asyncIterator]?.() ?? input[Symbol.iterator]();
+		s.cancelInput = () => {
+			iterator.return?.(void 0);
+		};
 		try {
-			for await (const chunk of input) {
+			for (;;) {
+				const next = await iterator.next();
+				if (next.done === true) break;
+				const chunk = next.value;
 				if (s.closed || muxClosed) return;
 				if (chunk.byteLength === 0) continue;
 				let off = 0;
 				while (off < chunk.byteLength) {
 					if (s.closed || muxClosed) return;
-					const end = Math.min(off + mtu, chunk.byteLength);
-					const piece = chunk.subarray(off, end);
-					sendFrame(s.id, TYPE_DATA, piece);
-					await new Promise((resolve, reject) => {
-						s.resolveAck = resolve;
-						s.rejectAck = reject;
-					});
+					const take = await s.outboundCredit.reserve(Math.min(mtu, chunk.byteLength - off));
+					if (s.closed || muxClosed) return;
+					const end = off + take;
+					sendFrame(s.id, TYPE_DATA, chunk.subarray(off, end));
 					off = end;
 				}
 			}
@@ -222,6 +326,9 @@ function emulateMux(channel, opts = {}) {
 			}
 			const s = createStream(id);
 			streams.set(id, s);
+			const advertised = decodeUint32(payload);
+			if (advertised !== void 0) s.outboundCredit.grant(advertised);
+			sendFrame(id, TYPE_ACK, encodeUint32(maxStreamBuffer));
 			runHandler(s, handler);
 			return;
 		}
@@ -239,15 +346,15 @@ function emulateMux(channel, opts = {}) {
 				const copy = payload.byteLength === 0 ? payload : new Uint8Array(payload);
 				s.pushIn(copy).then((handled) => {
 					s.queuedBytes -= copy.byteLength;
-					if (handled && !s.closed && !muxClosed) sendFrame(id, TYPE_ACK);
+					if (!handled || s.closed || muxClosed) return;
+					const grant = s.grantor.consumed(copy.byteLength, s.queuedBytes === 0);
+					if (grant > 0) sendFrame(id, TYPE_ACK, encodeUint32(grant));
 				});
 				return;
 			}
 			case TYPE_ACK: {
-				const r = s.resolveAck;
-				s.resolveAck = null;
-				s.rejectAck = null;
-				r?.();
+				const granted = decodeUint32(payload);
+				if (granted !== void 0) s.outboundCredit.grant(granted);
 				return;
 			}
 			case TYPE_END:
@@ -284,7 +391,7 @@ function emulateMux(channel, opts = {}) {
 		nextLocalId += 2;
 		const s = createStream(id);
 		streams.set(id, s);
-		sendFrame(id, TYPE_OPEN);
+		sendFrame(id, TYPE_OPEN, encodeUint32(maxStreamBuffer));
 		pumpOutbound(s, input);
 		return s.inbound;
 	};
@@ -424,8 +531,6 @@ function decodeError(buf) {
 		return new Error(textDecoder.decode(buf));
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/lines.ts
 /** Split a stream of string chunks into individual lines (delimited by \n). */
 async function* splitLines(input) {
 	let buffer = "";
@@ -444,14 +549,10 @@ async function* splitLines(input) {
 async function* joinLines(input) {
 	for await (const line of input) yield `${line}\n`;
 }
-//#endregion
-//#region ../webrun-streams/src/map.ts
 /** Apply a sync or async function to each item in a stream. */
 async function* map(input, fn) {
 	for await (const item of input) yield await fn(item);
 }
-//#endregion
-//#region ../webrun-streams/src/jsonl.ts
 /** Encode each value as a JSON line (terminated by \n). */
 async function* encodeJsonl(input) {
 	yield* map(input, (item) => `${JSON.stringify(item)}\n`);
@@ -463,8 +564,6 @@ async function* decodeJsonl(input) {
 		if (trimmed) yield JSON.parse(trimmed);
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/new-async-generator.ts
 /**
 * The newAsyncGenerator function creates async generators from callback-based initialization
 * functions, providing a bridge between imperative event handling and declarative async
@@ -617,8 +716,6 @@ async function* newAsyncGenerator(init, skipValues = false) {
 		drainQueue();
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/normalize.ts
 const utf8 = new TextEncoder();
 /**
 * Coerce common byte-like inputs into a `Uint8Array`. Strings encode as UTF-8.
@@ -639,36 +736,65 @@ function describe(value) {
 	if (t !== "object") return t;
 	return value.constructor?.name ?? "object";
 }
-//#endregion
-//#region ../webrun-streams/src/readable-streams.ts
+/**
+* The iterator ↔ `ReadableStream` boundary.
+*
+* Both adapters must carry CANCELLATION, not just data: a response body leaves
+* a handler as a `ReadableStream`, crosses a transport as an iterator, and
+* becomes a `ReadableStream` again at the caller — so when the caller walks
+* away, the only path back to the handler's producer runs through both of
+* these functions. Teardown that stops at an adapter leaves a producer running
+* for ever.
+*/
 function toReadableStream(it) {
-	return new ReadableStream({ async pull(controller) {
-		let handled = false;
-		try {
-			while (true) {
+	return new ReadableStream({
+		/**
+		* One chunk per pull. An earlier version drained the whole iterator inside
+		* a single `pull`, which defeated the stream's own backpressure (every
+		* chunk was enqueued as fast as the producer could make them, however slow
+		* the reader was) and left no point between chunks at which a cancellation
+		* could take effect.
+		*/
+		async pull(controller) {
+			try {
 				const slot = await it.next();
-				if (!slot || slot.done) break;
-				const value = await slot.value;
-				controller.enqueue(value);
+				if (!slot || slot.done) {
+					controller.close();
+					return;
+				}
+				controller.enqueue(await slot.value);
+			} catch (error) {
+				controller.error(error);
 			}
-		} catch (error) {
-			handled = true;
-			controller.error(error);
-		} finally {
-			if (!handled) controller.close();
+		},
+		/**
+		* Release the source. NOT awaited: `.return()` on an async generator that
+		* is parked awaiting its own source is queued behind that pending
+		* `next()`, so awaiting it here would hang `reader.cancel()` on exactly
+		* the producers that most need cancelling.
+		*/
+		cancel(reason) {
+			Promise.resolve(it.return?.(reason)).catch(() => {});
 		}
-	} });
+	});
 }
 async function* fromReadableStream(stream) {
 	const reader = stream.getReader();
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		if (value !== void 0) yield value;
+	let drained = false;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) {
+				drained = true;
+				break;
+			}
+			if (value !== void 0) yield value;
+		}
+	} finally {
+		if (drained) reader.releaseLock();
+		else await reader.cancel().catch(() => {});
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/recieve-iterator.ts
 /**
 * Inverse of {@link sendIterator}: turns a sequence of `{done, value, error}`
 * chunks (delivered to the supplied callback by `installer`) into an async
@@ -691,8 +817,6 @@ function recieveIterator(installer) {
 		};
 	});
 }
-//#endregion
-//#region ../webrun-streams/src/send-iterator.ts
 /**
 * Drain an async iterator into a sink that consumes one chunk at a time.
 *
@@ -716,8 +840,6 @@ async function sendIterator(send, it) {
 		});
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/text.ts
 /** Decode Uint8Array chunks to string chunks via TextDecoder, handling split multi-byte characters. */
 async function* decodeText(input) {
 	const decoder = new TextDecoder("utf-8", { fatal: false });
@@ -733,8 +855,6 @@ async function* encodeText(input) {
 	const encoder = new TextEncoder();
 	for await (const str of input) yield encoder.encode(str);
 }
-//#endregion
-//#region ../webrun-streams/src/to-chunks.ts
 const DEFAULT_CHUNK_SIZE = 16384;
 /**
 * Curried `Duplex`-shaped transformer that splits incoming `Uint8Array`s into
@@ -877,11 +997,14 @@ async function* sendStream(communicationPort, input, params = {}) {
 		params
 	}, [messageChannel.port2]);
 	const channel = newStreamChannel(messageChannel.port1);
+	let drained = false;
 	try {
 		await channel.start();
 		channel.sendAll(input);
 		yield* channel.recieveAll();
+		drained = true;
 	} finally {
+		if (!drained) channel.cancel();
 		await channel.close();
 	}
 }
@@ -909,11 +1032,33 @@ function newStreamChannel(port) {
 	const notifyAll = async (data) => {
 		for (const listener of listeners) await listener(data);
 	};
+	/**
+	* Release whatever we are sending. NOT awaited: `.return()` on an async
+	* generator parked awaiting its own source is queued behind that pending
+	* `next()`, so awaiting it here would block the message handler — and the
+	* chunk that would unblock it can only arrive through that same handler.
+	*/
+	const cancelOutgoing = () => {
+		for (const it of [...iterators]) {
+			const iterable = it;
+			Promise.resolve(iterable.return?.()).catch(() => {});
+		}
+	};
 	const channel = newInvokationChannel({
 		port,
-		handler: (data) => notifyAll(data)
+		handler: (data) => {
+			const message = data;
+			if (message?.cancel) {
+				cancelOutgoing();
+				return;
+			}
+			return notifyAll(message);
+		}
 	});
 	const start = () => channel.start();
+	const cancel = () => {
+		channel.invoke({ cancel: true }).catch(() => {});
+	};
 	const close = async () => {
 		await notifyAll({ done: true });
 		for (const it of [...iterators]) await it.return?.();
@@ -940,6 +1085,7 @@ function newStreamChannel(port) {
 	return {
 		start,
 		close,
+		cancel,
 		recieveAll,
 		sendAll
 	};
@@ -979,7 +1125,193 @@ function newRegistry(onError = console.error) {
 	});
 }
 //#endregion
-//#region ../webrun-http-streams/src/bytes.ts
+//#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;
 const EMPTY = /* @__PURE__ */ new Uint8Array(0);
@@ -1104,8 +1436,6 @@ var ByteReader = class {
 		}
 	}
 };
-//#endregion
-//#region ../webrun-http-streams/src/http1/errors.ts
 /**
 * Raised for any byte sequence this codec refuses to interpret. Every case is
 * a refusal to guess: HTTP/1.1 parsers that guess are how request smuggling
@@ -1114,8 +1444,6 @@ var ByteReader = class {
 var HttpParseError = class extends Error {
 	name = "HttpParseError";
 };
-//#endregion
-//#region ../webrun-http-streams/src/envelope.ts
 const NEWLINE = 10;
 /** Mirrors the HTTP/1.1 codec's default `maxHeaderBytes`. */
 const MAX_ENVELOPE_BYTES = 65536;
@@ -1199,8 +1527,6 @@ const jsonEnvelopeCodec = {
 	decodeRequest: (input) => decodeMessage(input),
 	decodeResponse: (input) => decodeMessage(input)
 };
-//#endregion
-//#region ../webrun-http-streams/src/http1/headers.ts
 const TCHAR = /* @__PURE__ */ new Set("!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
 const SP = 32;
 const HTAB = 9;
@@ -1376,8 +1702,6 @@ function resolveFraming(headers, version) {
 	};
 	return { kind: "none" };
 }
-//#endregion
-//#region ../webrun-http-streams/src/http1/chunked.ts
 const CRLF = new Uint8Array([13, 10]);
 const LAST_CHUNK = new Uint8Array([
 	48,
@@ -1444,8 +1768,6 @@ async function* decodeChunked(reader, maxLineBytes) {
 		}
 	}
 }
-//#endregion
-//#region ../webrun-http-streams/src/http1/decode.ts
 const VERSIONS = /* @__PURE__ */ new Set(["HTTP/1.1", "HTTP/1.0"]);
 const ABSOLUTE_FORM = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
 /**
@@ -1583,8 +1905,6 @@ async function decodeResponse(input, opts, method) {
 		toHttpParseError(err);
 	}
 }
-//#endregion
-//#region ../webrun-http-streams/src/http1/encode.ts
 /** Headers the codec owns: a caller-supplied copy is dropped and re-derived. */
 const REQUEST_OWNED = [
 	"host",
@@ -1680,8 +2000,6 @@ async function* encodeResponse(env, body, _opts, requestMethod) {
 	}
 	yield* emitBody(body, declared);
 }
-//#endregion
-//#region ../webrun-http-streams/src/http1/index.ts
 function newHttpCodec(options = {}) {
 	const opts = {
 		scheme: options.scheme ?? "http",
@@ -1698,8 +2016,6 @@ function newHttpCodec(options = {}) {
 	};
 }
 const httpCodec = newHttpCodec();
-//#endregion
-//#region ../webrun-http-streams/src/sniff.ts
 /**
 * Dispatches on byte 0. The formats are self-identifying — a JSON envelope
 * always begins `{`, which is not a token character and so can never begin an
@@ -1745,8 +2061,6 @@ function newSniffingCodec(options) {
 		}
 	};
 }
-//#endregion
-//#region ../webrun-http-streams/src/codec-default.ts
 /**
 * Writes HTTP/1.1; accepts HTTP/1.1 or the legacy JSON envelope. Used whenever
 * no `codec` option is supplied.
@@ -1755,8 +2069,6 @@ const defaultCodec = newSniffingCodec({
 	write: httpCodec,
 	accept: [httpCodec, jsonEnvelopeCodec]
 });
-//#endregion
-//#region ../webrun-http-streams/src/http-data.ts
 /** Carries the serialized JS error between two webrun peers. */
 const PEER_ERROR_HEADER = "x-webrun-error";
 /** Hard cap on the peer-error header (M3): see `encodeErrorResponse`. */
@@ -1865,8 +2177,6 @@ function httpServe(handler, options = {}) {
 		yield* replyCodec.encodeResponse(result.envelope, result.body, { method: decoded.envelope.method });
 	};
 }
-//#endregion
-//#region ../webrun-http-streams/src/request-streams.ts
 /**
 * The one place that knows a runtime may not implement request body streams,
 * and the buffering both fallbacks need. `fetch.ts` and `http-stubs.ts` each
@@ -1935,8 +2245,6 @@ async function collectBytes$1(source) {
 	}
 	return out;
 }
-//#endregion
-//#region ../webrun-http-streams/src/http-stubs.ts
 const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
 	101,
 	103,
@@ -2032,8 +2340,6 @@ function newHttpServerStub(handler) {
 		};
 	};
 }
-//#endregion
-//#region ../webrun-http-streams/src/fetch.ts
 /**
 * Connection-scoped headers. The codec surfaces them verbatim (decision 12),
 * but they are meaningless to a `Request`/`Response`, and re-emitting them
@@ -2184,8 +2490,6 @@ function abortReason(signal) {
 	err.name = "AbortError";
 	return err;
 }
-//#endregion
-//#region ../webrun-http-streams/src/duplex-site-builder.ts
 /**
 * Host a `SiteHandler` over a `Connect/Serve` pair. The `start(serve, params)`
 * call hands the handler to any `webrun-streams-*` adapter's `serve`.
@@ -2193,7 +2497,7 @@ function abortReason(signal) {
 * ```ts
 * import { SiteBuilder } from "@statewalker/webrun-site-builder";
 * import { DuplexSiteBuilder } from "@statewalker/webrun-http-streams";
-* import { serve } from "@statewalker/webrun-streams-port";
+* import { serve } from "@statewalker/webrun-rpc";
 *
 * const handler = new SiteBuilder()
 *   .setEndpoint("/api/time", () => new Response(new Date().toISOString()))
@@ -2224,8 +2528,6 @@ var DuplexSiteBuilder = class {
 		return serve(params, serveFetchOverDuplex(async (req) => handler(req), { codec: this.#codec }));
 	}
 };
-//#endregion
-//#region ../webrun-http-streams/src/http-error.ts
 var HttpError = class HttpError extends Error {
 	status;
 	statusText;
@@ -2308,13 +2610,21 @@ async function httpFromIterator(iterable) {
 	};
 }
 /**
-* @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.
 */
 function handleHttpRequests(communicationPort, handler) {
 	const serverStub = newHttpServerStub(handler);
@@ -2324,13 +2634,18 @@ function handleHttpRequests(communicationPort, handler) {
 	});
 }
 /**
-* @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.
 */
 async function sendHttpRequest(communicationPort, request) {
 	return await newHttpClientStub(async (req) => {
@@ -2369,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]);
@@ -2383,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.
@@ -2452,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;
@@ -2465,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]);
 		};
@@ -2482,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, {
@@ -2551,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, 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 };