@statewalker/webrun-http-browser 0.3.4 → 0.5.0

package/dist/sw.js

@@ -1,30 +1,4 @@
-//#region ../webrun-http-streams/src/bytes.ts
-function toAsyncIterator(input) {
-	const asyncIter = input[Symbol.asyncIterator];
-	if (asyncIter) return asyncIter.call(input);
-	const syncIter = input[Symbol.iterator]();
-	return { next() {
-		return Promise.resolve(syncIter.next());
-	} };
-}
-/**
-* Discard an iterable we are contractually forbidden from consuming — a body
-* skipped for HEAD/204, or one abandoned because the peer reported an error.
-*
-* The `.next()` is not optional: `.return()` on a generator still in suspended
-* start is a no-op, so the body never runs and its `try/finally` never unwinds.
-* Without it a wrapped ReadableStream or socket is never cancelled.
-*/
-async function discard(source) {
-	if (source === void 0) return;
-	const it = toAsyncIterator(source);
-	try {
-		await it.next();
-		await it.return?.();
-	} catch {}
-}
-//#endregion
-//#region ../webrun-streams/src/errors.ts
+//#region ../webrun-streams/dist/index.js
 function serializeError(error) {
 	if (error instanceof Error) {
 		const out = {
@@ -48,8 +22,8 @@ function deserializeError(error) {
 	const payload = typeof error === "string" ? { message: error } : error;
 	return Object.assign(new Error(payload.message), payload);
 }
-//#endregion
-//#region ../webrun-streams/src/new-async-generator.ts
+new TextEncoder();
+new TextDecoder();
 /**
 * The newAsyncGenerator function creates async generators from callback-based initialization
 * functions, providing a bridge between imperative event handling and declarative async
@@ -202,36 +176,66 @@ async function* newAsyncGenerator(init, skipValues = false) {
 		drainQueue();
 	}
 }
-//#endregion
-//#region ../webrun-streams/src/readable-streams.ts
+new TextEncoder();
+/**
+* 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
@@ -254,8 +258,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.
 *
@@ -280,7 +282,760 @@ async function sendIterator(send, it) {
 	}
 }
 //#endregion
-//#region ../webrun-http-streams/src/request-streams.ts
+//#region ../webrun-http-streams/dist/index.js
+const CR = 13;
+const LF = 10;
+const EMPTY = /* @__PURE__ */ new Uint8Array(0);
+var ByteStreamError = class extends Error {
+	name = "ByteStreamError";
+};
+function toAsyncIterator(input) {
+	const asyncIter = input[Symbol.asyncIterator];
+	if (asyncIter) return asyncIter.call(input);
+	const syncIter = input[Symbol.iterator]();
+	return { next() {
+		return Promise.resolve(syncIter.next());
+	} };
+}
+/**
+* Discard an iterable we are contractually forbidden from consuming — a body
+* skipped for HEAD/204, or one abandoned because the peer reported an error.
+*
+* The `.next()` is not optional: `.return()` on a generator still in suspended
+* start is a no-op, so the body never runs and its `try/finally` never unwinds.
+* Without it a wrapped ReadableStream or socket is never cancelled.
+*/
+async function discard(source) {
+	if (source === void 0) return;
+	const it = toAsyncIterator(source);
+	try {
+		await it.next();
+		await it.return?.();
+	} catch {}
+}
+function concatChunks(parts, totalLen) {
+	if (parts.length === 1) {
+		const only = parts[0];
+		if (only !== void 0) return only;
+	}
+	const out = new Uint8Array(totalLen);
+	let off = 0;
+	for (const p of parts) {
+		out.set(p, off);
+		off += p.byteLength;
+	}
+	return out;
+}
+/**
+* Pull-based reader over a byte source. Holds at most one pending buffer, and
+* hands out `subarray` views rather than copies — a body never passes through
+* an allocation here.
+*/
+var ByteReader = class {
+	#iter;
+	#buf = EMPTY;
+	#done = false;
+	constructor(input) {
+		this.#iter = toAsyncIterator(input);
+	}
+	/** Bytes already pulled from the source but not yet consumed. */
+	bufferedLength() {
+		return this.#buf.byteLength;
+	}
+	/** Pull one more non-empty chunk. Returns false at end of stream. */
+	async #pull() {
+		if (this.#done) return false;
+		while (true) {
+			const next = await this.#iter.next();
+			if (next.done) {
+				this.#done = true;
+				return false;
+			}
+			const chunk = next.value;
+			if (chunk.byteLength === 0) continue;
+			this.#buf = this.#buf.byteLength === 0 ? chunk : concatChunks([this.#buf, chunk], this.#buf.byteLength + chunk.byteLength);
+			return true;
+		}
+	}
+	async peekByte() {
+		while (this.#buf.byteLength === 0) if (!await this.#pull()) return void 0;
+		return this.#buf[0];
+	}
+	/** Up to `max` bytes. `undefined` means end of stream. */
+	async readSome(max) {
+		while (this.#buf.byteLength === 0) if (!await this.#pull()) return void 0;
+		const take = Math.min(max, this.#buf.byteLength);
+		const out = this.#buf.subarray(0, take);
+		this.#buf = this.#buf.subarray(take);
+		return out;
+	}
+	/**
+	* One CRLF-terminated line, without the CRLF. A bare LF is rejected: real
+	* peers always send CRLF, and tolerating a bare LF is precisely the lenience
+	* that lets request smuggling through a proxy pair.
+	*
+	* The `maxBytes` bound is best-effort: it only rejects a line if the check
+	* happens to run before the line is fully buffered. A line already sitting in
+	* the buffer bypasses the check. Callers needing a hard per-line limit or
+	* aggregate bounds must keep their own running total.
+	*/
+	async readLine(maxBytes) {
+		let searched = 0;
+		while (true) {
+			const idx = this.#buf.indexOf(LF, searched);
+			if (idx !== -1) {
+				if (idx === 0 || this.#buf[idx - 1] !== CR) throw new ByteStreamError("bare LF line terminator; CRLF required");
+				const line = this.#buf.subarray(0, idx - 1);
+				this.#buf = this.#buf.subarray(idx + 1);
+				return line;
+			}
+			searched = this.#buf.byteLength;
+			if (searched > maxBytes) throw new ByteStreamError(`line exceeds ${maxBytes} bytes without CRLF`);
+			if (!await this.#pull()) throw new ByteStreamError(`stream ended after ${searched} bytes without CRLF`);
+		}
+	}
+	/** Everything not yet consumed, lazily. */
+	async *rest() {
+		while (true) {
+			if (this.#buf.byteLength > 0) {
+				const out = this.#buf;
+				this.#buf = EMPTY;
+				yield out;
+				continue;
+			}
+			if (!await this.#pull()) return;
+		}
+	}
+};
+/**
+* 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
+* works.
+*/
+var HttpParseError = class extends Error {
+	name = "HttpParseError";
+};
+const NEWLINE = 10;
+/** Mirrors the HTTP/1.1 codec's default `maxHeaderBytes`. */
+const MAX_ENVELOPE_BYTES = 65536;
+const encoder$1 = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+* Encode an HTTP envelope plus optional body as one continuous byte stream:
+*
+*     <JSON.stringify(envelope)>\n<body bytes...>
+*
+* `JSON.stringify` with default whitespace never emits a literal `\n`, so the
+* first `0x0a` byte unambiguously terminates the envelope.
+*
+* This is the same wire shape used by the legacy `webrun-http-port` package.
+*/
+async function* encodeMessage(envelope, body) {
+	yield encoder$1.encode(`${JSON.stringify(envelope)}\n`);
+	if (!body) return;
+	for await (const chunk of body) if (chunk.byteLength > 0) yield chunk;
+}
+/**
+* Consume an envelope-then-body byte stream. Returns the parsed envelope and
+* an async iterable over the remaining body bytes.
+*/
+async function decodeMessage(input) {
+	const iter = toAsyncIterator(input);
+	const accum = [];
+	let accumLen = 0;
+	let before;
+	let tail;
+	while (true) {
+		const next = await iter.next();
+		if (next.done) throw new HttpParseError(`decodeMessage: stream ended after ${accumLen} bytes without delimiter (\\n)`);
+		const chunk = next.value;
+		if (chunk.byteLength === 0) continue;
+		const nl = chunk.indexOf(NEWLINE);
+		if (nl === -1) {
+			accum.push(chunk);
+			accumLen += chunk.byteLength;
+			if (accumLen > MAX_ENVELOPE_BYTES) throw new HttpParseError(`decodeMessage: envelope exceeds ${MAX_ENVELOPE_BYTES} bytes without delimiter (\\n)`);
+			continue;
+		}
+		accum.push(chunk.subarray(0, nl));
+		accumLen += nl;
+		before = concatChunks(accum, accumLen);
+		tail = chunk.subarray(nl + 1);
+		break;
+	}
+	let envelope;
+	try {
+		envelope = JSON.parse(decoder.decode(before));
+	} catch (err) {
+		throw new HttpParseError(`decodeMessage: malformed envelope JSON at bytes 0..${before.byteLength}: ${err.message}`);
+	}
+	async function* body() {
+		if (tail.byteLength > 0) yield tail;
+		while (true) {
+			const next = await iter.next();
+			if (next.done) return;
+			if (next.value.byteLength > 0) yield next.value;
+		}
+	}
+	return {
+		envelope,
+		body: body()
+	};
+}
+const OPEN_BRACE = 123;
+/**
+* The original wire format — `<JSON.stringify(envelope)>\n<body bytes…>` —
+* expressed as a `MessageCodec`. Direction-agnostic: requests and responses
+* serialise identically.
+*
+* Retained so a peer pair can be upgraded in either order; see ADR-0006.
+*/
+const jsonEnvelopeCodec = {
+	name: "json-envelope",
+	sniff: (byte) => byte === OPEN_BRACE,
+	encodeRequest: (env, body) => encodeMessage(env, body),
+	encodeResponse: (env, body) => encodeMessage(env, body),
+	decodeRequest: (input) => decodeMessage(input),
+	decodeResponse: (input) => decodeMessage(input)
+};
+const TCHAR = /* @__PURE__ */ new Set("!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
+const SP = 32;
+const HTAB = 9;
+function isTokenChar(byte) {
+	return byte > SP && byte < 127 && TCHAR.has(String.fromCharCode(byte));
+}
+function isToken(value) {
+	if (value.length === 0) return false;
+	for (const ch of value) if (!TCHAR.has(ch)) return false;
+	return true;
+}
+/**
+* Header bytes are latin-1: byte-preserving, matching Node, and lossless
+* across a decode/encode round-trip. Control characters are rejected
+* separately by `assertValidHeaderValue`.
+*/
+function decodeLatin1(bytes) {
+	let out = "";
+	for (const byte of bytes) out += String.fromCharCode(byte);
+	return out;
+}
+function encodeLatin1(text) {
+	const out = new Uint8Array(text.length);
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code > 255) throw new HttpParseError(`not latin-1 encodable: ${JSON.stringify(text)}`);
+		out[i] = code;
+	}
+	return out;
+}
+const HOST_IP_LITERAL = /^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+const HOST_REG_NAME = /^[A-Za-z0-9._~-]+(:\d{1,5})?$/;
+/**
+* Validates a value that is about to become (or was read as) a `Host`
+* header: untrusted input either way, so an unrecognised shape is a refusal,
+* not a guess. Rejects a present-but-empty value, one carrying userinfo
+* (`evil.com@good.com`), and — the reason this also runs on encode — one
+* smuggling a CRLF-terminated line into the authority of a caller-supplied
+* url. Never applied to trusted configuration (a codec's `opts.host`).
+*/
+function assertValidHost(host) {
+	if (!HOST_IP_LITERAL.test(host) && !HOST_REG_NAME.test(host)) throw new HttpParseError(`invalid Host header: ${JSON.stringify(host)}`);
+}
+/**
+* A request-target must be entirely visible ASCII (RFC 9110 VCHAR) — nothing
+* `<= 0x20` (space and every control character, CR/LF included) and nothing
+* `>= 0x7F` (DEL and beyond). Applied on encode (`splitTarget`, so a
+* caller-supplied url can never inject a second request line) and on decode
+* (so a relay that decodes then re-encodes can never put an embedded control
+* character back on the wire).
+*/
+function assertValidTarget(target) {
+	for (let i = 0; i < target.length; i++) {
+		const code = target.charCodeAt(i);
+		if (code <= SP || code >= 127) throw new HttpParseError(`invalid request-target: ${JSON.stringify(target)}`);
+	}
+}
+/**
+* Shared control-character check behind both `assertValidHeaderValue` and
+* `assertValidStatusText` — the two were previously checked by different,
+* looser rules (statusText only rejected CR/LF), which is exactly the
+* asymmetry class C1 and M5 are both instances of. `label` is prepended
+* verbatim to each message, so callers keep their own wording.
+*/
+function assertNoControlChars(label, value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code === 13 || code === 10) throw new HttpParseError(`${label} contains CR or LF`);
+		if (code < SP && code !== HTAB || code === 127) throw new HttpParseError(`${label} contains a control character`);
+		if (code > 255) throw new HttpParseError(`${label} is not latin-1 encodable`);
+	}
+}
+function assertValidHeaderValue(name, value) {
+	assertNoControlChars(`header "${name}" value`, value);
+}
+/** Same character class as a header value (M5) — CR/LF, every C0 control, and DEL. */
+function assertValidStatusText(value) {
+	assertNoControlChars("statusText", value);
+}
+function encodeHeaderLines(headers) {
+	let out = "";
+	for (const [name, value] of headers) {
+		if (!isToken(name)) throw new HttpParseError(`invalid header name: ${JSON.stringify(name)}`);
+		assertValidHeaderValue(name, value);
+		out += `${name}: ${value}\r\n`;
+	}
+	return out;
+}
+/**
+* Read to the blank line. `alreadyUsed` is the byte count of the start line,
+* so the bound covers the whole head section rather than the headers alone.
+*/
+async function readHeaderSection(reader, maxHeaderBytes, alreadyUsed) {
+	const headers = [];
+	let used = alreadyUsed;
+	while (true) {
+		const remaining = maxHeaderBytes - used;
+		if (remaining <= 0) throw new HttpParseError(`head section exceeds ${maxHeaderBytes} bytes`);
+		const lineBytes = await reader.readLine(remaining);
+		used += lineBytes.byteLength + 2;
+		if (used > maxHeaderBytes) throw new HttpParseError(`head section exceeds ${maxHeaderBytes} bytes`);
+		if (lineBytes.byteLength === 0) return headers;
+		if (lineBytes[0] === SP || lineBytes[0] === HTAB) throw new HttpParseError("obs-fold header continuation is not accepted");
+		const line = decodeLatin1(lineBytes);
+		const colon = line.indexOf(":");
+		if (colon <= 0) throw new HttpParseError(`malformed header line: ${JSON.stringify(line)}`);
+		const name = line.slice(0, colon);
+		if (!isToken(name)) throw new HttpParseError(`invalid header name: ${JSON.stringify(name)}`);
+		const value = line.slice(colon + 1).replace(/^[ \t]+/, "").replace(/[ \t]+$/, "");
+		assertValidHeaderValue(name, value);
+		headers.push([name, value]);
+	}
+}
+function getAll(headers, name) {
+	const lower = name.toLowerCase();
+	return headers.filter(([k]) => k.toLowerCase() === lower).map(([, v]) => v);
+}
+function withoutHeaders(headers, names) {
+	const drop = new Set(names.map((n) => n.toLowerCase()));
+	return headers.filter(([k]) => !drop.has(k.toLowerCase()));
+}
+/**
+* Parse a `Content-Length` field into a single validated value.
+*
+* RFC 9110 §8.6 permits the value to be a comma-separated list of identical
+* numbers (a relay may have appended one), so the list is folded; differing
+* values are a refusal, not a choice. Shared by `resolveFraming` on decode and
+* by the encoder's declared-length check, which previously carried its own
+* copy that did NOT split on commas — so decode accepted `5, 5` while encode
+* rejected it, and a relay that decoded then re-encoded threw.
+*
+* Returns undefined when the field is absent.
+*/
+function parseContentLength(values) {
+	if (values.length === 0) return void 0;
+	const unique = new Set(values.flatMap((v) => v.split(",").map((s) => s.trim())));
+	if (unique.size !== 1) throw new HttpParseError(`conflicting Content-Length values: ${[...unique].join(", ")}`);
+	const raw = [...unique][0];
+	if (!/^\d{1,15}$/.test(raw)) throw new HttpParseError(`invalid Content-Length: ${JSON.stringify(raw)}`);
+	return Number(raw);
+}
+/**
+* Statuses that carry no body whatever the headers say (RFC 9110 §8.6): 1xx,
+* 204 and 304. Defined once because the encoder must not frame a body for
+* them and the decoder must not try to read one — two lists that agreed today
+* and were free to drift tomorrow.
+*
+* A response to HEAD is also bodyless, but that depends on the request rather
+* than the status, so callers test it separately.
+*/
+function isBodylessStatus(status) {
+	return status < 200 || status === 204 || status === 304;
+}
+/**
+* RFC 9112 §6.3, with every ambiguity turned into a refusal. In particular a
+* message declaring both Content-Length and Transfer-Encoding is rejected
+* rather than resolved — disagreeing on which one wins is request smuggling.
+*/
+function resolveFraming(headers, version) {
+	const te = getAll(headers, "transfer-encoding");
+	const cl = getAll(headers, "content-length");
+	if (te.length > 0 && cl.length > 0) throw new HttpParseError("message declares both Content-Length and Transfer-Encoding; refusing (request smuggling)");
+	if (te.length > 0) {
+		const encodings = te.join(",").split(",").map((s) => s.trim().toLowerCase()).filter((s) => s !== "");
+		if (encodings.length !== 1 || encodings[0] !== "chunked") throw new HttpParseError(`unsupported Transfer-Encoding: ${JSON.stringify(te.join(", "))}`);
+		if (version === "HTTP/1.0") throw new HttpParseError("Transfer-Encoding is not valid in HTTP/1.0");
+		return { kind: "chunked" };
+	}
+	const length = parseContentLength(cl);
+	if (length !== void 0) return {
+		kind: "length",
+		length
+	};
+	return { kind: "none" };
+}
+const CRLF = new Uint8Array([13, 10]);
+const LAST_CHUNK = new Uint8Array([
+	48,
+	13,
+	10,
+	13,
+	10
+]);
+const encoder = new TextEncoder();
+/**
+* Chunk sizes are written in HEXADECIMAL — a 21-byte chunk is `15`. Writing
+* them in decimal is the defect note 15 found in @libp2p/http, and it is the
+* one that cannot be caught downstream: decimal digits are also valid hex, so
+* a conforming parser silently reads the wrong length.
+*
+* Zero-length source chunks are skipped; a zero-sized chunk on the wire is the
+* body terminator.
+*/
+async function* encodeChunked(body) {
+	for await (const chunk of body) {
+		if (chunk.byteLength === 0) continue;
+		yield encoder.encode(`${chunk.byteLength.toString(16)}\r\n`);
+		yield chunk;
+		yield CRLF;
+	}
+	yield LAST_CHUNK;
+}
+/**
+* Decode a chunked body, yielding data chunks as they arrive. Nothing is
+* accumulated: a chunk larger than the transport's frame is yielded in pieces.
+*/
+async function* decodeChunked(reader, maxLineBytes) {
+	while (true) {
+		const sizeLine = decodeLatin1(await reader.readLine(maxLineBytes));
+		const semicolon = sizeLine.indexOf(";");
+		const sizeText = semicolon === -1 ? sizeLine : sizeLine.slice(0, semicolon);
+		if (!/^[0-9a-fA-F]{1,32}$/.test(sizeText)) throw new HttpParseError(`invalid chunk size: ${JSON.stringify(sizeLine)}`);
+		const size = Number.parseInt(sizeText, 16);
+		if (!Number.isSafeInteger(size)) throw new HttpParseError(`chunk size is too large: ${JSON.stringify(sizeLine)}`);
+		if (size === 0) {
+			let used = 0;
+			while (true) {
+				const remaining = maxLineBytes - used;
+				if (remaining <= 0) throw new HttpParseError(`trailer section exceeds ${maxLineBytes} bytes`);
+				const lineBytes = await reader.readLine(remaining);
+				used += lineBytes.byteLength + 2;
+				if (used > maxLineBytes) throw new HttpParseError(`trailer section exceeds ${maxLineBytes} bytes`);
+				if (lineBytes.byteLength === 0) break;
+			}
+			return;
+		}
+		let remaining = size;
+		while (remaining > 0) {
+			const part = await reader.readSome(remaining);
+			if (part === void 0) throw new HttpParseError(`chunk truncated: ${remaining} of ${size} bytes missing`);
+			remaining -= part.byteLength;
+			yield part;
+		}
+		try {
+			if ((await reader.readLine(2)).byteLength !== 0) throw new HttpParseError("chunk data not terminated by CRLF");
+		} catch (err) {
+			if (err instanceof ByteStreamError) throw new HttpParseError("chunk data not terminated by CRLF");
+			throw err;
+		}
+	}
+}
+const VERSIONS = /* @__PURE__ */ new Set(["HTTP/1.1", "HTTP/1.0"]);
+const ABSOLUTE_FORM = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/**
+* One message per Duplex call (ADR-0006), so bytes after a complete message
+* are an error. Checked against what is ALREADY BUFFERED rather than by
+* awaiting end-of-stream: a live socket from a keep-alive peer never reaches
+* EOF, so awaiting one would hang instead of failing.
+*/
+function assertNoBufferedBytes(reader) {
+	const extra = reader.bufferedLength();
+	if (extra > 0) throw new HttpParseError(`${extra} trailing bytes after a complete message`);
+}
+/**
+* The public error contract (I2): everything leaving `decodeRequest` /
+* `decodeResponse` is an `HttpParseError`, whether the refusal happened
+* synchronously (a malformed start line or header) or lazily while the body
+* is later drained. `ByteStreamError` — the `ByteReader`'s own class, never
+* exported — is the one thing converted here, message and all preserved via
+* `cause`. Anything else is a genuine failure of the underlying source (a
+* dropped socket, say) and must reach the caller unchanged: blanket-catching
+* would hide that distinction.
+*/
+function toHttpParseError(err) {
+	if (err instanceof ByteStreamError) throw new HttpParseError(err.message, { cause: err });
+	throw err;
+}
+/** Applies `toHttpParseError` across the whole lifetime of a body generator. */
+async function* convertBodyErrors(source) {
+	try {
+		yield* source;
+	} catch (err) {
+		toHttpParseError(err);
+	}
+}
+async function* readBody(reader, framing, opts, noneMeansEof) {
+	if (framing.kind === "chunked") {
+		yield* decodeChunked(reader, opts.maxHeaderBytes);
+		assertNoBufferedBytes(reader);
+		return;
+	}
+	if (framing.kind === "length") {
+		let remaining = framing.length;
+		while (remaining > 0) {
+			const part = await reader.readSome(remaining);
+			if (part === void 0) throw new HttpParseError(`body truncated: ${remaining} of ${framing.length} bytes missing`);
+			remaining -= part.byteLength;
+			yield part;
+		}
+		assertNoBufferedBytes(reader);
+		return;
+	}
+	if (noneMeansEof) {
+		yield* reader.rest();
+		return;
+	}
+	assertNoBufferedBytes(reader);
+}
+/**
+* `readLine`'s bound is best-effort — it is skipped when the line is already
+* buffered — so a very long start line can reach these messages intact. Since
+* a refusal is now echoed back to the sender in a 400 body, quote only enough
+* to diagnose rather than reflecting the whole thing.
+*/
+function quoteLine(line) {
+	const MAX = 120;
+	return line.length <= MAX ? JSON.stringify(line) : `${JSON.stringify(line.slice(0, MAX))} (truncated from ${line.length} chars)`;
+}
+async function decodeRequest(input, opts) {
+	const reader = new ByteReader(input);
+	try {
+		const startBytes = await reader.readLine(opts.maxHeaderBytes);
+		const startLine = decodeLatin1(startBytes);
+		const parts = startLine.split(" ");
+		if (parts.length !== 3) throw new HttpParseError(`malformed request line: ${quoteLine(startLine)}`);
+		const [method, target, version] = parts;
+		if (!isToken(method)) throw new HttpParseError(`invalid method: ${JSON.stringify(method)}`);
+		if (!VERSIONS.has(version)) throw new HttpParseError(`unsupported HTTP version: ${JSON.stringify(version)}`);
+		if (target === "*") throw new HttpParseError("asterisk-form request target is not supported");
+		assertValidTarget(target);
+		const headers = await readHeaderSection(reader, opts.maxHeaderBytes, startBytes.byteLength + 2);
+		const hosts = getAll(headers, "host");
+		if (hosts.length > 1) throw new HttpParseError("multiple Host headers");
+		const host = hosts[0];
+		let url;
+		if (target.startsWith("/")) {
+			if (version === "HTTP/1.1" && host === void 0) throw new HttpParseError("HTTP/1.1 request has no Host header");
+			if (host !== void 0) assertValidHost(host);
+			url = `${opts.scheme}://${host ?? opts.host}${target}`;
+		} else if (ABSOLUTE_FORM.test(target)) url = target;
+		else throw new HttpParseError(`unsupported request target: ${JSON.stringify(target)}`);
+		try {
+			new URL(url);
+		} catch {
+			throw new HttpParseError(`decoded url is not a valid URL: ${JSON.stringify(url)}`);
+		}
+		return {
+			envelope: {
+				url,
+				method,
+				headers
+			},
+			body: convertBodyErrors(readBody(reader, resolveFraming(headers, version), opts, false))
+		};
+	} catch (err) {
+		toHttpParseError(err);
+	}
+}
+async function decodeResponse(input, opts, method) {
+	const reader = new ByteReader(input);
+	try {
+		const startBytes = await reader.readLine(opts.maxHeaderBytes);
+		const startLine = decodeLatin1(startBytes);
+		const firstSp = startLine.indexOf(" ");
+		if (firstSp === -1) throw new HttpParseError(`malformed status line: ${quoteLine(startLine)}`);
+		const version = startLine.slice(0, firstSp);
+		if (!VERSIONS.has(version)) throw new HttpParseError(`unsupported HTTP version: ${JSON.stringify(version)}`);
+		const afterVersion = startLine.slice(firstSp + 1);
+		const secondSp = afterVersion.indexOf(" ");
+		const codeText = secondSp === -1 ? afterVersion : afterVersion.slice(0, secondSp);
+		if (!/^\d{3}$/.test(codeText)) throw new HttpParseError(`invalid status code: ${JSON.stringify(codeText)}`);
+		const status = Number(codeText);
+		const statusText = secondSp === -1 ? "" : afterVersion.slice(secondSp + 1);
+		const headers = await readHeaderSection(reader, opts.maxHeaderBytes, startBytes.byteLength + 2);
+		const bodyless = isBodylessStatus(status) || method.toUpperCase() === "HEAD";
+		const framing = bodyless ? { kind: "none" } : resolveFraming(headers, version);
+		return {
+			envelope: {
+				status,
+				statusText,
+				headers
+			},
+			body: convertBodyErrors(readBody(reader, framing, opts, !bodyless))
+		};
+	} catch (err) {
+		toHttpParseError(err);
+	}
+}
+/** Headers the codec owns: a caller-supplied copy is dropped and re-derived. */
+const REQUEST_OWNED = [
+	"host",
+	"connection",
+	"transfer-encoding"
+];
+const RESPONSE_OWNED = ["connection", "transfer-encoding"];
+/**
+* Split a URL into an origin-form request target and an authority *without*
+* going through `new URL()`. `URL` normalises percent-encoding and would
+* re-serialise the target — which is the exact class of defect note 15 found
+* in @libp2p/http, where rebuilding the request line silently dropped
+* `url.search`. Here the target is a verbatim slice of the caller's string.
+*/
+function splitTarget(url, opts) {
+	if (url.startsWith("/")) {
+		assertValidTarget(url);
+		return {
+			target: url,
+			authority: opts.host
+		};
+	}
+	const match = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/?#]*)([^#]*)/.exec(url);
+	if (!match) throw new HttpParseError(`cannot derive a request target from url: ${JSON.stringify(url)}`);
+	const rawAuthority = match[1];
+	if (rawAuthority === "") throw new HttpParseError(`url has no authority: ${JSON.stringify(url)}`);
+	const at = rawAuthority.lastIndexOf("@");
+	const authority = at === -1 ? rawAuthority : rawAuthority.slice(at + 1);
+	assertValidHost(authority);
+	const rawTarget = match[2];
+	const target = rawTarget === "" ? "/" : rawTarget.startsWith("/") ? rawTarget : `/${rawTarget}`;
+	assertValidTarget(target);
+	return {
+		target,
+		authority
+	};
+}
+async function* emitBody(body, declared) {
+	if (declared === void 0) {
+		yield* encodeChunked(body);
+		return;
+	}
+	let sent = 0;
+	for await (const chunk of body) {
+		if (chunk.byteLength === 0) continue;
+		sent += chunk.byteLength;
+		if (sent > declared) throw new HttpParseError(`body exceeds declared Content-Length ${declared} (${sent} bytes so far)`);
+		yield chunk;
+	}
+	if (sent !== declared) throw new HttpParseError(`body is ${sent} bytes but Content-Length declares ${declared}`);
+}
+async function* encodeRequest(env, body, opts) {
+	if (!isToken(env.method)) throw new HttpParseError(`invalid method: ${JSON.stringify(env.method)}`);
+	const { target, authority } = splitTarget(env.url, opts);
+	if (authority === "") throw new HttpParseError("no Host available: url has no authority and no host is configured");
+	const carried = withoutHeaders(env.headers, REQUEST_OWNED);
+	const declared = parseContentLength(getAll(carried, "content-length"));
+	let head = `${env.method} ${target} HTTP/1.1\r\n`;
+	head += `Host: ${authority}\r\n`;
+	head += encodeHeaderLines(carried);
+	head += "Connection: close\r\n";
+	if (body !== void 0 && declared === void 0) head += "Transfer-Encoding: chunked\r\n";
+	head += "\r\n";
+	yield encodeLatin1(head);
+	if (body === void 0) {
+		if (declared !== void 0 && declared !== 0) throw new HttpParseError(`body is 0 bytes but Content-Length declares ${declared}`);
+		return;
+	}
+	yield* emitBody(body, declared);
+}
+async function* encodeResponse(env, body, _opts, requestMethod) {
+	if (!Number.isInteger(env.status) || env.status < 100 || env.status > 599) throw new HttpParseError(`invalid status: ${env.status}`);
+	const reason = env.statusText ?? "";
+	assertValidStatusText(reason);
+	const bodylessStatus = isBodylessStatus(env.status);
+	const bodyless = bodylessStatus || requestMethod?.toUpperCase() === "HEAD";
+	const owned = bodylessStatus ? [...RESPONSE_OWNED, "content-length"] : RESPONSE_OWNED;
+	const carried = withoutHeaders(env.headers, owned);
+	const declared = parseContentLength(getAll(carried, "content-length"));
+	let head = `HTTP/1.1 ${env.status} ${reason}\r\n`;
+	head += encodeHeaderLines(carried);
+	head += "Connection: close\r\n";
+	if (!bodyless && body !== void 0 && declared === void 0) head += "Transfer-Encoding: chunked\r\n";
+	head += "\r\n";
+	yield encodeLatin1(head);
+	if (bodyless) {
+		await discard(body);
+		return;
+	}
+	if (body === void 0) {
+		if (declared !== void 0 && declared !== 0) throw new HttpParseError(`body is 0 bytes but Content-Length declares ${declared}`);
+		return;
+	}
+	yield* emitBody(body, declared);
+}
+function newHttpCodec(options = {}) {
+	const opts = {
+		scheme: options.scheme ?? "http",
+		host: options.host ?? "localhost",
+		maxHeaderBytes: options.maxHeaderBytes ?? 65536
+	};
+	return {
+		name: "http/1.1",
+		sniff: (byte) => isTokenChar(byte),
+		encodeRequest: (env, body) => encodeRequest(env, body, opts),
+		encodeResponse: (env, body, o) => encodeResponse(env, body, opts, o?.method),
+		decodeRequest: (input) => decodeRequest(input, opts),
+		decodeResponse: (input, o) => decodeResponse(input, opts, o.method)
+	};
+}
+const httpCodec = newHttpCodec();
+/**
+* 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
+* HTTP start-line — so no negotiation handshake, magic prefix, or version byte
+* is needed.
+*
+* This is what makes a mixed-version peer pair safe: readers accept either
+* format, so the two ends can be upgraded in any order.
+*/
+function newSniffingCodec(options) {
+	const { write, accept } = options;
+	async function pick(input) {
+		const reader = new ByteReader(input);
+		const first = await reader.peekByte();
+		if (first === void 0) throw new HttpParseError("sniff: stream ended before any bytes arrived");
+		const codec = accept.find((c) => c.sniff(first));
+		if (!codec) throw new HttpParseError(`sniff: no accepted codec recognises a message starting with byte 0x${first.toString(16).padStart(2, "0")}`);
+		return {
+			codec,
+			input: reader.rest()
+		};
+	}
+	return {
+		name: `sniff(write=${write.name}; accept=${accept.map((c) => c.name).join(",")})`,
+		sniff: (byte) => accept.some((c) => c.sniff(byte)),
+		encodeRequest: (env, body) => write.encodeRequest(env, body),
+		encodeResponse: (env, body, o) => write.encodeResponse(env, body, o),
+		decodeRequest: async (input) => {
+			const picked = await pick(input);
+			try {
+				return {
+					...await picked.codec.decodeRequest(picked.input),
+					codec: picked.codec
+				};
+			} catch (error) {
+				if (error !== null && typeof error === "object") error.codec = picked.codec;
+				throw error;
+			}
+		},
+		decodeResponse: async (input, o) => {
+			const picked = await pick(input);
+			return picked.codec.decodeResponse(picked.input, o);
+		}
+	};
+}
+newSniffingCodec({
+	write: httpCodec,
+	accept: [httpCodec, jsonEnvelopeCodec]
+});
 /**
 * 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
@@ -349,8 +1104,6 @@ async function collectBytes(source) {
 	}
 	return out;
 }
-//#endregion
-//#region ../webrun-http-streams/src/http-stubs.ts
 const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([
 	101,
 	103,
@@ -528,11 +1281,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();
 	}
 }
@@ -560,11 +1316,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?.();
@@ -591,6 +1369,7 @@ function newStreamChannel(port) {
 	return {
 		start,
 		close,
+		cancel,
 		recieveAll,
 		sendAll
 	};
@@ -618,13 +1397,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);
@@ -634,13 +1421,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) => {
@@ -731,6 +1523,29 @@ function handleChannelCalls(target, callType, handler) {
 	return () => target.removeEventListener("message", listener);
 }
 //#endregion
+//#region src/core/deadline.ts
+/**
+* Settles like `promise` if it settles before `deadline` (a `Date.now()`
+* value). Otherwise calls `onTimeout`: an `Error` it returns rejects, any
+* other value resolves. Internal; not re-exported.
+*/
+function withDeadline(deadline, promise, onTimeout) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			const outcome = onTimeout();
+			if (outcome instanceof Error) reject(outcome);
+			else resolve(outcome);
+		}, Math.max(0, deadline - Date.now()));
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+//#endregion
 //#region src/core/registry.ts
 function newRegistry(onError = console.error) {
 	let counter = 0;
@@ -765,6 +1580,169 @@ function newRegistry(onError = console.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 src/sw/sw-dispatcher.ts
 /**
 * Page-side counterpart: registers a ServiceWorker and sets up a
@@ -792,7 +1770,7 @@ var SwPortHandler = class {
 	}
 	get serviceWorkerUrl() {
 		if (!this._serviceWorkerUrl) {
-			const url = this.options.serviceWorkerUrl ? new URL(this.options.serviceWorkerUrl) : new URL("./index-sw.js", this.rootUrl);
+			const url = this.options.serviceWorkerUrl ? resolveWorkerUrl(this.options.serviceWorkerUrl) : new URL("./index-sw.js", this.rootUrl);
 			this._serviceWorkerUrl = `${url}`;
 		}
 		return this._serviceWorkerUrl;
@@ -813,6 +1791,15 @@ var SwPortHandler = class {
 	_getRegistrationInfo() {
 		return { key: this.key };
 	}
+	/**
+	* Registers the worker and waits until it is activated and controls this
+	* page, then opens the port to it. The page must be controlled, because
+	* only a controlled page's `fetch()` reaches the worker. When the page
+	* loaded uncontrolled (a hard reload does that), the worker is asked to
+	* claim it. Rejects with a `ServiceWorkerControlError` when that fails or
+	* `timeout` passes (`reason` says which step); a later `start()` tries
+	* again.
+	*/
 	async start() {
 		if (!this._registrationPromise) this._registrationPromise = (async () => {
 			const [register, cleanup] = newRegistry();
@@ -822,13 +1809,25 @@ var SwPortHandler = class {
 			});
 			const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl, { scope: this.scope });
 			register(() => registration.unregister());
-			register(handleChannelCalls(navigator.serviceWorker, "UPDATE_COMMUNICATION_PORT", async (_event, _params, port) => {
+			const stopListening = handleChannelCalls(navigator.serviceWorker, "UPDATE_COMMUNICATION_PORT", async (_event, _params, port) => {
 				await this._setCommunicationPort(port);
 				return this._getRegistrationInfo();
-			}));
-			this._serviceWorker = await getServiceWorkerController();
-			await awaitServiceWorkerActivation(this._serviceWorker);
-			await this._updateCommunicationChannel();
+			});
+			register(stopListening);
+			const timeout = this.options.timeout ?? 3e4;
+			const deadline = Date.now() + timeout;
+			try {
+				this._serviceWorker = await awaitServiceWorkerControl(registration, {
+					timeout,
+					reloadIfUncontrolled: this.options.reloadIfUncontrolled
+				});
+				await withDeadline(deadline, this._updateCommunicationChannel(), () => new ServiceWorkerControlError("unresponsive", `ServiceWorker "${this._serviceWorker?.scriptURL}" controls this page but did not answer the UPDATE_COMMUNICATION_PORT handshake within ${timeout} ms. Check that the worker script runs this package's same-origin dispatcher (it importScripts \`sw-worker.js\`, or calls \`startHttpDispatcher\`).`));
+			} catch (error) {
+				stopListening();
+				this._cleanupRegistrations = void 0;
+				this._registrationPromise = void 0;
+				throw error;
+			}
 		})();
 		return this._registrationPromise;
 	}
@@ -842,35 +1841,6 @@ var SwPortHandler = class {
 		}
 	}
 };
-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);
-	});
-}
 /**
 * ServiceWorker-side counterpart: maintains an index of connected clients keyed by
 * clientId, persisted in IndexedDB so it can reclaim ports across SW restarts.
@@ -918,7 +1888,8 @@ var SwPortDispatcher = class {
 		return this.claimedKeys.has(key);
 	}
 	start() {
-		this._cleanup = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
+		const stopClaims = handleClaimRequests(this.self);
+		const stopPortUpdates = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
 			const clientId = event.source?.id;
 			this.log("[UPDATE_COMMUNICATION_PORT]", clientId, channelInfo);
 			await this._updateChannelInfo({
@@ -928,6 +1899,10 @@ var SwPortDispatcher = class {
 			});
 			return { ...channelInfo };
 		});
+		this._cleanup = () => {
+			stopClaims();
+			stopPortUpdates();
+		};
 		this.self.addEventListener("install", (event) => {
 			this.log("Skip waiting on install.", event);
 			this.self.skipWaiting();
@@ -993,6 +1968,21 @@ var SwPortDispatcher = class {
 		return index;
 	}
 };
+/**
+* Resolve a `serviceWorkerUrl` option the way a page would: relative to the
+* current document. Absolute urls pass through untouched. A url that cannot
+* be resolved is reported with the option name and the offending value,
+* because the raw `TypeError: Failed to construct 'URL': Invalid URL` says
+* neither.
+*/
+function resolveWorkerUrl(serviceWorkerUrl) {
+	const base = globalThis.location?.href;
+	try {
+		return new URL(serviceWorkerUrl, base);
+	} catch (error) {
+		throw new Error(`Invalid serviceWorkerUrl: ${JSON.stringify(serviceWorkerUrl)}` + (base ? ` (relative to ${base})` : " (no document to resolve it against)"), { cause: error });
+	}
+}
 //#endregion
 //#region src/sw/http-sw-dispatcher.ts
 var SwHttpAdapter = class extends SwPortHandler {