@statewalker/webrun-http-browser 0.10.0 → 0.12.1

package/dist/sw.js

@@ -1920,6 +1920,99 @@ async function* throughAbort(input, signal) {
 	}
 }
 /**
+* Runs `fn` on a later task, never a microtask: a producer looping on
+* `whenPortReady` must let the transport's own events run. `setImmediate`
+* where it exists; elsewhere a `MessageChannel`, because nested `setTimeout`s
+* are clamped to 4 ms in browsers.
+*/
+const setImmediateFn = globalThis.setImmediate;
+/** @internal */
+const nextTask = setImmediateFn ? (fn) => {
+	setImmediateFn(fn);
+} : (() => {
+	let channel;
+	const queue = [];
+	return (fn) => {
+		if (!channel) {
+			channel = new MessageChannel();
+			channel.port1.onmessage = () => queue.shift()?.();
+		}
+		queue.push(fn);
+		channel.port2.postMessage(0);
+	};
+})();
+const states = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortSendState(port, state) {
+	states.set(port, state);
+}
+/**
+* Bytes queued on `port` because its window is spent (0 for a port without
+* flow control). A sender that should not queue without bound waits for
+* `whenPortReady` before posting more.
+*/
+function portBufferedAmount(port) {
+	return states.get(port)?.bufferedAmount() ?? 0;
+}
+/**
+* Resolves once at most `below` bytes are queued on `port`, always on a later
+* task (for a port without flow control, on the next one).
+*/
+function whenPortReady(port, below = 0) {
+	return states.get(port)?.ready(below) ?? new Promise((resolve) => nextTask(resolve));
+}
+const agreements = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortAgreement(port, agreement) {
+	agreements.set(port, agreement);
+}
+/**
+* @internal What has been agreed with the peer on `port` so far; `undefined`
+* on a port without a window. Not exported from the package.
+*/
+function portAgreement(port) {
+	return agreements.get(port)?.();
+}
+const ends = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortEndState(port, state) {
+	ends.set(port, state);
+}
+/**
+* @internal End this side's direction of `port`: an `end` is queued behind
+* everything already posted on it, and anything posted afterwards is dropped.
+* `false`, and nothing changes, when `end` was not agreed (no window, the
+* handshake not answered yet, or a peer that does not speak it): the caller
+* then closes the port. Never waits on the peer. Not exported from the package.
+*/
+function endPort(port) {
+	return ends.get(port)?.end() ?? false;
+}
+/**
+* @internal Resolves once the peer has ended its direction of `port`. It never
+* settles otherwise: not on a port where `end` is not agreed when it is asked
+* (no window, the handshake not answered yet, a peer or codec without it), and
+* not when the port closes first, so a caller races it against the port's
+* close signal. Not exported from the package.
+*/
+function whenPortEnded(port) {
+	let waiting = peerEnds.get(port);
+	if (!waiting) {
+		let resolve = () => {};
+		const promise = new Promise((r) => {
+			resolve = r;
+		});
+		if (!ends.get(port)?.watchPeerEnd(resolve)) return promise;
+		waiting = {
+			promise,
+			resolve
+		};
+		peerEnds.set(port, waiting);
+	}
+	return waiting.promise;
+}
+const peerEnds = /* @__PURE__ */ new WeakMap();
+/**
 * Makes `target` disposable with `await using`: installs `dispose` as its
 * `[Symbol.asyncDispose]`, where the runtime defines the symbol. Hand-written
 * iterators lose what a native generator gets from `AsyncIteratorPrototype`;
@@ -1991,6 +2084,61 @@ function returningAtOnce(gen, abandon) {
 * tests and adapters assert on it.
 */
 const STREAM_ABORT = "webrun-rpc:stream-abort";
+/**
+* The `type` of a pipelined chunk: a plain port message, not a `callPort`
+* request, sent only on a port where both ends agreed `pipeline`. The window's
+* credit is its confirmation.
+*/
+const CHUNK = "webrun-rpc:chunk";
+/**
+* What a pipelined chunk counts beyond its bytes, against the window, on the
+* receiving side. Both codecs' windows count more for the chunk's envelope
+* (the estimate at least 64, msgpack's keys alone more than this), so an honest
+* sender never makes the receiver count past the window; a sender of empty
+* chunks still cannot have it hold an unbounded number of them.
+*/
+const CHUNK_OVERHEAD = 32;
+/**
+* The bytes of `view` as a plain `Uint8Array` that owns its whole buffer:
+* `view` itself when it already is one, else a copy. Structured clone carries
+* and keeps a view's whole `ArrayBuffer`, and a byte codec may decode into
+* views of the frame, while the window and the receiver's count see only the
+* view: a 4 KiB `subarray` of a 4 MiB buffer would cost 4 MiB per chunk.
+* Copied with the `Uint8Array` constructor, not `slice()`: a Node `Buffer`'s
+* `slice()` is another view on the same memory.
+*/
+function ownBytes(view) {
+	if (view instanceof Uint8Array && view.constructor === Uint8Array && view.byteOffset === 0 && view.byteLength === view.buffer.byteLength) return view;
+	return new Uint8Array(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+}
+/**
+* A producer's chunk as bytes this end may send, in either mode: any view or
+* `ArrayBuffer`, normalised by `ownBytes`. Anything else fails the stream here,
+* as the producer's own error, rather than reaching a peer that would refuse it.
+*/
+/**
+* A received confirmed chunk's value, as its own bytes, put back in place of
+* the original in `chunk`: `listenPort` keeps the request until the handler
+* returns, and the original would keep its whole buffer that long. A function
+* of its own, so that no temporary of the suspended handler holds the
+* original either.
+*/
+function adoptValue(chunk) {
+	const original = chunk.value;
+	if (ArrayBuffer.isView(original)) chunk.value = ownBytes(original);
+	return chunk.value;
+}
+function chunkBytes(value) {
+	if (ArrayBuffer.isView(value)) return ownBytes(value);
+	if (value instanceof ArrayBuffer || Object.prototype.toString.call(value) === "[object ArrayBuffer]") return new Uint8Array(value);
+	throw new TypeError(`webrun-rpc: a stream chunk must be bytes (a typed array, a DataView or an ArrayBuffer), got ${value === null ? "null" : typeof value}`);
+}
+const MIXED_MESSAGE = "webrun-rpc: peer mixed confirmed and pipelined chunks; the stream port is closed";
+/** This end may pipeline its own chunks: agreed, and the window holds them. */
+const mayPipeline = (port) => {
+	const agreement = portAgreement(port);
+	return !!agreement?.enforced && agreement.caps.has("pipeline");
+};
 /** Caller's input travels on this channel; the handler listens on it. */
 const CHANNEL_IN = "in";
 /** The handler's output travels on this channel; the caller listens on it. */
@@ -2003,7 +2151,9 @@ const CHANNEL_OUT = "out";
 * same way on the other channel. Within each direction the next chunk is never
 * sent until the previous one has been delivered *and* pulled past by the
 * consumer (spec D11) — the reply to a chunk call *is* the confirmation, and
-* `listenPort` withholds it until then.
+* `listenPort` withholds it until then. On a port whose window both ends
+* speak and that agreed `pipeline`, chunks go as plain messages instead, and
+* the window's credit is the confirmation: up to a window is in flight.
 *
 * A stream port carries exactly one invocation. To make several calls, open
 * several ports: `mux.openPort({ kind: "stream" })` per call.
@@ -2020,22 +2170,49 @@ function serveDuplexOverPort(port, handler, options = {}) {
 	const notice = installAbortNotice(port, controller);
 	abortOnPortClose(port, controller);
 	const clock = installStreamTimeout(controller, options.timeout);
-	const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch);
+	const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch, notice);
 	let output;
 	try {
 		output = handler(inbound.stream);
 	} catch (err) {
-		const pump = sendChunks(port, CHANNEL_OUT, failing(err), options, controller.signal, clock.touch);
+		const pump = sendChunks(port, CHANNEL_OUT, failing(err), options, controller.signal, clock.touch, () => {});
 		pump.catch(() => {});
 		disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
 		return teardownOnce(controller, notice, clock, inbound, void 0);
 	}
-	const pump = sendChunks(port, CHANNEL_OUT, output, options, controller.signal, clock.touch);
+	let onSent = () => {};
+	const sent = new Promise((resolve) => {
+		onSent = resolve;
+	});
+	const pump = sendChunks(port, CHANNEL_OUT, output, options, controller.signal, clock.touch, onSent);
 	pump.catch(() => {});
 	disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+	endServedStream(port, sent, inbound.over);
 	return teardownOnce(controller, notice, clock, inbound, output);
 }
 /**
+* The serving side's normal finish. Once the handler's last chunk has gone
+* without an error, and no more input is coming (`over`: the caller's last
+* chunk arrived without an error and was read, or the caller ended its
+* direction behind it, for a handler that did not read all its input), this
+* side ends its direction too, where `end` was agreed. Without `end` nothing
+* happens here: the caller closes the port. A stream that never gets that far
+* was abandoned, and the caller's notice and `close` free the port; this then
+* never resumes. It needs no race against the port's close signal: nothing
+* awaits it, and what keeps it waiting is the input's watcher, a listener of
+* the port that a close drops, after which the wait is collected.
+*
+* Nothing this side still posts is lost behind its `end`. The caller ends only
+* once its own last chunk was confirmed, so no confirmation is owed to it
+* here, and what the freed port's close signal aborts has settled: the last
+* chunk has left, and input nobody reads is dropped, as on a close.
+*/
+async function endServedStream(port, sent, over) {
+	await sent;
+	await over;
+	endPort(port);
+}
+/**
 * A stream that completes normally has nobody left to call the returned
 * teardown — the caller only knows the stream ended, not that it must also
 * dispose the serve-side handle. Without this, the last `touch()`'s timer
@@ -2075,22 +2252,31 @@ function runCallerSide(port, input, options) {
 	const notice = installAbortNotice(port, controller);
 	abortOnPortClose(port, controller);
 	const clock = installStreamTimeout(controller, options.timeout);
-	const inbound = receiveChunks(port, CHANNEL_OUT, controller, clock.touch);
-	const pump = sendChunks(port, CHANNEL_IN, input, options, controller.signal, clock.touch);
+	const inbound = receiveChunks(port, CHANNEL_OUT, controller, clock.touch, notice);
+	let sent = false;
+	const pump = sendChunks(port, CHANNEL_IN, input, options, controller.signal, clock.touch, () => {
+		sent = true;
+	});
 	pump.catch(() => {});
 	return returningAtOnce((async function* () {
+		let received = false;
 		try {
 			yield* inbound.stream;
+			received = true;
 		} finally {
+			const ended = received && sent;
 			if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the caller abandoned the stream"));
-			notice.post();
+			if (!ended) notice.post();
 			notice.stop();
 			clock.stop();
 			inbound.stop();
 			await pump.catch(() => {});
-			try {
-				await port.close?.();
-			} catch {}
+			if (!(ended && endPort(port))) {
+				notice.post();
+				try {
+					await port.close?.();
+				} catch {}
+			}
 		}
 	})(), () => {
 		if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the caller abandoned the stream"));
@@ -2184,7 +2370,7 @@ function installStreamTimeout(controller, timeout) {
 * the local consumer has not started iterating, an inbound chunk waits for it —
 * which is the correct backpressure, and different from having no listener.
 */
-function receiveChunks(port, channelName, controller, touch) {
+function receiveChunks(port, channelName, controller, touch, notice) {
 	let deliver;
 	const waiting = [];
 	let finished = false;
@@ -2194,25 +2380,64 @@ function receiveChunks(port, channelName, controller, touch) {
 	const ended = new Promise((resolve) => {
 		resolveEnded = resolve;
 	});
+	let resolveOver = () => {};
+	const over = new Promise((resolve) => {
+		resolveOver = resolve;
+	});
 	let aborted = false;
 	let abortReason;
 	const ready = () => deliver || finished ? Promise.resolve() : new Promise((r) => waiting.push(r));
 	const wake = () => {
 		for (const r of waiting.splice(0)) r();
 	};
-	const off = listenPort(port, async ({ done, value, error }) => {
+	const violate = (message) => {
+		poison = new Error(message);
+		controller.abort(poison);
+		setTimeout(() => {
+			try {
+				port.close?.();
+			} catch {}
+		}, 0);
+		return poison;
+	};
+	let lastChunkArrived = false;
+	let watching = false;
+	const watchPeerEnd = () => {
+		if (watching) return true;
+		if (!portAgreement(port)?.caps.has("end")) return false;
+		watching = true;
+		whenPortEnded(port).then(() => {
+			port.removeEventListener("message", watcher);
+			if (lastChunkArrived) {
+				resolveOver();
+				return;
+			}
+			notice.post();
+			violate("webrun-rpc: the peer ended its direction without finishing it; the stream port is closed");
+		});
+		return true;
+	};
+	const watcher = (event) => {
+		const data = event.data;
+		if (data?.channelName !== channelName) return;
+		const chunk = data.type === CHUNK ? data.chunk : data.type === "request" ? data.params : void 0;
+		if (!chunk) return;
+		if (!watchPeerEnd()) {
+			port.removeEventListener("message", watcher);
+			return;
+		}
+		if (chunk.done && !chunk.error) lastChunkArrived = true;
+	};
+	port.addEventListener("message", watcher);
+	watchPeerEnd();
+	let held = 0;
+	const off = listenPort(port, async (params) => {
+		const { done, error } = params;
+		const value = adoptValue(params);
 		touch();
 		if (poison) throw poison;
-		if (outstanding) {
-			poison = /* @__PURE__ */ new Error("webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed");
-			controller.abort(poison);
-			setTimeout(() => {
-				try {
-					port.close?.();
-				} catch {}
-			}, 0);
-			throw poison;
-		}
+		if (held > 0) throw violate(MIXED_MESSAGE);
+		if (outstanding) throw violate("webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed");
 		outstanding = true;
 		try {
 			await ready();
@@ -2222,15 +2447,60 @@ function receiveChunks(port, channelName, controller, touch) {
 				value,
 				error: error ? deserializeError(error) : void 0
 			});
+			if (done && !error) resolveOver();
 		} finally {
 			outstanding = false;
 		}
 		if (done) resolveEnded();
 	}, { channelName });
+	const onChunk = (event) => {
+		const data = event.data;
+		if (data?.type !== CHUNK || data.channelName !== channelName || !data.chunk) return;
+		if (poison) return;
+		const agreement = portAgreement(port);
+		if (!agreement?.caps.has("pipeline")) {
+			violate("webrun-rpc: peer sent a pipelined chunk where pipelining was not agreed");
+			return;
+		}
+		if (outstanding) {
+			violate(MIXED_MESSAGE);
+			return;
+		}
+		if (data.chunk.value !== void 0 && !ArrayBuffer.isView(data.chunk.value)) {
+			violate("webrun-rpc: peer sent a pipelined chunk whose value is not bytes");
+			return;
+		}
+		if (held > agreement.window) {
+			violate(`webrun-rpc: peer sent past the window (${agreement.window} bytes) without waiting for credit; the stream port is closed`);
+			return;
+		}
+		touch();
+		const { done, error } = data.chunk;
+		const value = data.chunk.value && ownBytes(data.chunk.value);
+		const size = (value?.byteLength ?? 0) + CHUNK_OVERHEAD;
+		held += size;
+		return (async () => {
+			try {
+				await ready();
+				if (finished) return;
+				await deliver?.({
+					done,
+					value,
+					error: error ? deserializeError(error) : void 0
+				});
+				if (done && !error) resolveOver();
+				if (done) resolveEnded();
+			} finally {
+				held -= size;
+			}
+		})();
+	};
+	port.addEventListener("message", onChunk);
 	const detach = () => {
 		finished = true;
 		wake();
 		off();
+		port.removeEventListener("message", onChunk);
 		controller.signal.removeEventListener("abort", onAbort);
 		resolveEnded();
 	};
@@ -2260,25 +2530,35 @@ function receiveChunks(port, channelName, controller, touch) {
 			return detach;
 		}),
 		stop: detach,
-		ended
+		ended,
+		over
 	};
 }
 /**
 * The sending half of one direction: one `callPort` per chunk, one call
-* outstanding at a time (spec D11/D12), with no per-chunk deadline (spec D8).
+* outstanding at a time (spec D11/D12), with no per-chunk deadline (spec D8) —
+* or, once pipelining is agreed, plain chunk messages held back by the window.
+* `onSent` runs once the end of the output has left without an error: posted
+* when pipelined, confirmed when not.
 */
-async function sendChunks(port, channelName, output, { maxMessageSize, log }, signal, touch) {
+async function sendChunks(port, channelName, output, { maxMessageSize, log }, signal, touch, onSent) {
 	const framed = maxMessageSize ? toChunks(maxMessageSize)(output) : output;
 	const stream = throughAbort(framed, signal);
 	const producer = output;
 	const returnProducer = () => void Promise.resolve(producer.return?.()).catch(() => {});
 	if (framed !== output) signal.addEventListener("abort", returnProducer, { once: true });
+	let onAborted = () => {};
+	const aborted = new Promise((resolve) => {
+		onAborted = () => resolve();
+	});
+	if (signal.aborted) onAborted();
+	else signal.addEventListener("abort", onAborted, { once: true });
 	try {
 		await sendIterator(async ({ done, value, error }) => {
 			if (signal.aborted) return;
 			const chunk = {
 				done,
-				value,
+				value: done ? value : chunkBytes(value),
 				error: error === void 0 ? void 0 : serializeError(error)
 			};
 			log?.("[duplexOverPort] send", {
@@ -2286,48 +2566,34 @@ async function sendChunks(port, channelName, output, { maxMessageSize, log }, si
 				done,
 				size: value?.byteLength
 			});
+			if (mayPipeline(port)) {
+				port.postMessage({
+					type: CHUNK,
+					channelName,
+					chunk
+				});
+				touch();
+				if (done && !error) onSent();
+				if (portBufferedAmount(port) > 0) await Promise.race([whenPortReady(port), aborted]);
+				return;
+			}
 			await callPort(port, chunk, {
 				channelName,
 				timeout: NO_TIMEOUT,
 				signal
 			});
 			touch();
+			if (done && !error) onSent();
 		}, stream);
 	} catch (err) {
 		if (signal.aborted) return;
 		throw err;
 	} finally {
 		signal.removeEventListener("abort", returnProducer);
+		signal.removeEventListener("abort", onAborted);
 	}
 }
 /**
-* Runs `fn` on a later task, never a microtask: a producer looping on
-* `whenPortReady` must let the transport's own events run. `setImmediate`
-* where it exists; elsewhere a `MessageChannel`, because nested `setTimeout`s
-* are clamped to 4 ms in browsers.
-*/
-const setImmediateFn = globalThis.setImmediate;
-/** @internal */
-const nextTask = setImmediateFn ? (fn) => {
-	setImmediateFn(fn);
-} : (() => {
-	let channel;
-	const queue = [];
-	return (fn) => {
-		if (!channel) {
-			channel = new MessageChannel();
-			channel.port1.onmessage = () => queue.shift()?.();
-		}
-		queue.push(fn);
-		channel.port2.postMessage(0);
-	};
-})();
-const states = /* @__PURE__ */ new WeakMap();
-/** @internal Registered by the multiplexer for each port with a window. */
-function setPortSendState(port, state) {
-	states.set(port, state);
-}
-/**
 * One virtual port.
 *
 * `deliver` and `markClosed` are deliberately not on `port`: the consumer holds
@@ -2405,6 +2671,21 @@ function newVirtualPort(send, requestClose) {
 const KEEPALIVE_ID = Number.MAX_SAFE_INTEGER;
 /** The longest delay a timer holds; past it `setInterval` fires at once. */
 const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+* What a windowed port offers in its `open`: every capability this end
+* speaks. `end` only over a codec that reads it (`PortCodec.halfClose`).
+*/
+function ownCaps(codec) {
+	return codec.halfClose ? ["pipeline", "end"] : ["pipeline"];
+}
+/**
+* The capabilities in a peer's `caps` that this end speaks too, or
+* `undefined` when the peer listed none (it is then treated as an older peer).
+*/
+function sharedCaps(own, listed) {
+	if (!Array.isArray(listed)) return void 0;
+	return new Set(own.filter((cap) => listed.includes(cap)));
+}
 /** Ceiling on concurrently open virtual ports. Bounds the id table only. */
 const DEFAULT_MAX_PORTS = 1024;
 /**
@@ -2468,6 +2749,8 @@ function multiplexPort(port, options) {
 	let muxClosed = false;
 	/** This end counts encoded bytes and reassembles frames. */
 	const exactCodec = codec.encode != null && codec.decode != null;
+	/** What this end offers on a windowed port. */
+	const caps = ownCaps(codec);
 	const post = (envelope, transfer) => {
 		if (muxClosed) return;
 		codecPost(envelope, transfer);
@@ -2525,13 +2808,39 @@ function multiplexPort(port, options) {
 			port.postMessage(bytes);
 		} catch {}
 	};
+	/**
+	* Both directions have ended: free the id as a close would, with no `close`
+	* on the wire (each end frees it on its own once it has seen both ends).
+	* Aborting the close signal is how the port's consumer learns it is gone.
+	*/
+	const freeIfEnded = (id, c) => {
+		const entry = open.get(id);
+		if (!c.endSent || !c.peerEnded || entry?.credit !== c) return;
+		freePartial(entry);
+		open.delete(id);
+		leaks?.unregister(entry.handle);
+		entry.handle.markClosed(/* @__PURE__ */ new Error("webrun-rpc: the port ended in both directions"));
+	};
+	/** A peer that broke the port's protocol: hold none of its traffic, and close. */
+	const failPort = (id, entry, error, reason) => {
+		freePartial(entry);
+		dropOutgoing(id);
+		open.delete(id);
+		releaseWaiters(entry.credit);
+		entry.handle.markClosed(error);
+		post({
+			type: "close",
+			id,
+			reason
+		});
+	};
 	const releaseWaiters = (c) => {
 		for (const w of c?.waiters.splice(0) ?? []) w.resolve();
 	};
 	const flush = (c) => {
 		while (c.queue.length) {
 			const next = c.queue[0];
-			if (c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window) break;
+			if (next.size > 0 && c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window) break;
 			c.queue.shift();
 			c.queued -= next.size;
 			c.outstanding += next.size;
@@ -2569,15 +2878,20 @@ function multiplexPort(port, options) {
 			enforced: false,
 			opener,
 			exact,
+			caps: /* @__PURE__ */ new Set(),
 			outstanding: 0,
 			queue: [],
 			queued: 0,
 			unconsumed: 0,
 			waiters: [],
 			toGrant: 0,
-			grantScheduled: false
+			grantScheduled: false,
+			ending: false,
+			endSent: false,
+			peerEnded: false
 		} : void 0;
 		const self = newVirtualPort((payload, transfer) => {
+			if (c?.ending) return;
 			touch(id);
 			const envelope = {
 				type: "message",
@@ -2664,6 +2978,38 @@ function multiplexPort(port, options) {
 					});
 				})
 			});
+			setPortEndState(self.port, {
+				end: () => {
+					if (isClosed() || !c.caps.has("end")) return false;
+					if (c.ending) return true;
+					c.ending = true;
+					c.queue.push({
+						size: 0,
+						send: () => sendOnPort(id, () => {
+							if (open.get(id)?.credit !== c) return;
+							post({
+								type: "end",
+								id
+							});
+							c.endSent = true;
+							freeIfEnded(id, c);
+						})
+					});
+					flush(c);
+					return true;
+				},
+				watchPeerEnd: (resolve) => {
+					if (!c.caps.has("end")) return false;
+					if (c.peerEnded) resolve();
+					else c.onPeerEnd = new WeakRef(resolve);
+					return true;
+				}
+			});
+			setPortAgreement(self.port, () => ({
+				window: c.window,
+				caps: c.caps,
+				enforced: c.enforced
+			}));
 		}
 		const record = {
 			deliver: self.deliver,
@@ -2715,16 +3061,24 @@ function multiplexPort(port, options) {
 			}
 			const handle = attach(envelope.id, envelope.meta, envelope.window, false, envelope.exact === true && exactCodec);
 			const credit = open.get(envelope.id)?.credit;
-			if (credit) post(credit.exact ? {
-				type: "credit",
-				id: envelope.id,
-				bytes: 0,
-				exact: true
-			} : {
-				type: "credit",
-				id: envelope.id,
-				bytes: 0
-			});
+			const listed = sharedCaps(caps, envelope.caps);
+			if (credit) {
+				const ack = credit.exact ? {
+					type: "credit",
+					id: envelope.id,
+					bytes: 0,
+					exact: true
+				} : {
+					type: "credit",
+					id: envelope.id,
+					bytes: 0
+				};
+				if (listed) credit.caps = listed;
+				post(listed ? {
+					...ack,
+					caps: [...listed]
+				} : ack);
+			}
 			let accepted = false;
 			if (onPort) try {
 				accepted = onPort(handle.port, envelope.meta) !== false;
@@ -2752,6 +3106,7 @@ function multiplexPort(port, options) {
 					c.exact = false;
 					c.outstanding = 0;
 				}
+				c.caps = sharedCaps(caps, envelope.caps) ?? /* @__PURE__ */ new Set();
 				post({
 					type: "credit",
 					id: envelope.id,
@@ -2763,6 +3118,10 @@ function multiplexPort(port, options) {
 			flush(c);
 			return;
 		}
+		if ((envelope.type === "message" || envelope.type === "frame") && entry?.credit?.peerEnded) {
+			failPort(envelope.id, entry, /* @__PURE__ */ new Error("webrun-rpc: the peer sent on a port after its end"), "protocol");
+			return;
+		}
 		if (envelope.type === "message") {
 			const sizeOf = (c) => (c.exact ? byteLengthOf(event.data) : void 0) ?? estimateMessageSize(envelope.payload);
 			if (!entry) return;
@@ -2787,16 +3146,7 @@ function multiplexPort(port, options) {
 			const charged = partial.room == null ? Math.max(0, partial.bytes + size - c.window) : 0;
 			const overrun = partial.room != null && partial.bytes + size > partial.room ? `what the window left (${partial.room} of ${c.window} bytes, ${partial.owed} still owed)` : reassembling - partial.charged + charged > maxReassembledBytes ? `maxReassembledBytes (${maxReassembledBytes} bytes past the window, across all ports)` : void 0;
 			if (overrun) {
-				freePartial(entry);
-				dropOutgoing(envelope.id);
-				open.delete(envelope.id);
-				releaseWaiters(c);
-				entry.handle.markClosed(/* @__PURE__ */ new RangeError(`webrun-rpc: a framed message passed ${overrun}`));
-				post({
-					type: "close",
-					id: envelope.id,
-					reason: "max-reassembled-bytes"
-				});
+				failPort(envelope.id, entry, /* @__PURE__ */ new RangeError(`webrun-rpc: a framed message passed ${overrun}`), "max-reassembled-bytes");
 				return;
 			}
 			partial.bytes += size;
@@ -2816,6 +3166,19 @@ function multiplexPort(port, options) {
 			entry.handle.deliver(inner.payload, whole.byteLength);
 			return;
 		}
+		if (envelope.type === "end") {
+			if (!entry) return;
+			const c = entry.credit;
+			if (!c?.caps.has("end")) {
+				failPort(envelope.id, entry, /* @__PURE__ */ new Error("webrun-rpc: the peer ended a port where end was not agreed"), "protocol");
+				return;
+			}
+			touch(envelope.id);
+			c.peerEnded = true;
+			c.onPeerEnd?.deref()?.();
+			freeIfEnded(envelope.id, c);
+			return;
+		}
 		dropOutgoing(envelope.id);
 		if (!entry) return;
 		freePartial(entry);
@@ -2897,12 +3260,14 @@ function multiplexPort(port, options) {
 				id,
 				meta,
 				window,
-				exact: true
+				exact: true,
+				caps: [...caps]
 			} : {
 				type: "open",
 				id,
 				meta,
-				window
+				window,
+				caps: [...caps]
 			} : {
 				type: "open",
 				id,
@@ -3057,7 +3422,7 @@ function isEnvelope(value) {
 	const candidate = value;
 	if (typeof candidate.id !== "number") return false;
 	if (!Number.isInteger(candidate.id) || candidate.id < 0) return false;
-	return candidate.type === "open" || candidate.type === "message" || candidate.type === "close" || candidate.type === "credit" || candidate.type === "frame" || candidate.type === "ping" || candidate.type === "pong";
+	return candidate.type === "open" || candidate.type === "message" || candidate.type === "close" || candidate.type === "credit" || candidate.type === "frame" || candidate.type === "ping" || candidate.type === "pong" || candidate.type === "end";
 }
 /**
 * For ports whose messages are structured values — a real `MessagePort`, a
@@ -3069,6 +3434,7 @@ function isEnvelope(value) {
 * not send anything a byte codec could not also carry.
 */
 const structuredCodec = {
+	halfClose: true,
 	post(port, envelope, transfer) {
 		if (transfer && transfer.length > 0) port.postMessage(envelope, transfer);
 		else port.postMessage(envelope);
@@ -3106,10 +3472,15 @@ function asyncDisposable(target, dispose) {
 * own `handleStreams` / `sendStream` (no backpressure); version 2 is
 * webrun-rpc's `connect` / `serve` over `overPipe` with webrun-http-streams'
 * `fetchOverDuplex` / `serveFetchOverDuplex`: one port per link, calls
-* multiplexed on it, each call a stream with a one-chunk window in both
-* directions, and cancellation that reaches the handler.
+* multiplexed on it, each call a stream with backpressure in both
+* directions, and cancellation that reaches the handler. A call's port with a
+* window (`HttpLinkOptions.window`) pipelines its chunks where both ends speak
+* it, and goes one confirmed chunk at a time otherwise, so the window needs
+* no new version.
 */
 const HTTP_LINK_PROTOCOL = "webrun-http-link/2";
+/** The calling end's default `HttpLinkOptions.window`: 256 KiB. */
+const DEFAULT_HTTP_LINK_WINDOW = 262144;
 /**
 * Why a request failed when its link went away under it: the far side (the
 * handler, or the ServiceWorker) was lost. The request may or may not have
@@ -3128,12 +3499,13 @@ var LinkLostError = class extends Error {
 */
 const LINK_CLOSE = "webrun-http:link-close";
 /** Opens the calling end of a link on `port` (one port per link). */
-async function connectHttpLink(port, { streamTimeout, maxPorts } = {}) {
+async function connectHttpLink(port, { streamTimeout, maxPorts, window = DEFAULT_HTTP_LINK_WINDOW } = {}) {
 	const { call, close } = await connect({
 		mux: overPipe(port, {
 			codec: structuredCodec,
 			side: "initiator",
-			maxPorts
+			maxPorts,
+			window
 		}),
 		timeout: streamTimeout
 	});
@@ -3664,6 +4036,7 @@ var PortSocketCore = class extends EventTarget {
 			code,
 			reason
 		});
+		if (!Number.isFinite(this._closeTimeoutMs)) return;
 		this._closeTimer = this._timers.setTimeout(() => this._finish(1006, "", false), this._closeTimeoutMs);
 	}
 	_onCloseFrame(code, reason) {
@@ -3742,7 +4115,8 @@ function isApplicationCloseCode(code) {
 *   `whenDrained(limit)` waits for it to fall: the backpressure a producer
 *   applies.
 * - When the client's pings stop for three heartbeat periods (a closed tab, a
-*   terminated worker), the socket closes with 1006.
+*   terminated worker), the socket closes with 1006. With `watch: "first-ping"`
+*   the watch starts only once the client pings.
 */
 var ServerWebSocket = class extends PortSocketCore {
 	static CONNECTING = 0;
@@ -3751,55 +4125,150 @@ var ServerWebSocket = class extends PortSocketCore {
 	static CLOSED = 3;
 	url;
 	protocol;
+	_binaryType = "arraybuffer";
+	_options;
 	_accepted = false;
+	_detached = false;
 	_queue = [];
 	_heartbeatMs = DEFAULT_HEARTBEAT_MS;
 	_lastPing = Date.now();
+	/** Whether a ping (with a period a timer takes) arrived already. */
+	_pinged = false;
 	_watch;
 	constructor(port, options = {}) {
 		super({
 			timers: options.timers,
 			closeTimeoutMs: options.closeTimeoutMs
 		});
+		this._options = options;
 		this.url = options.url ?? "";
 		this.protocol = options.protocol ?? "";
 		this._attach(port);
 		this._state = 1;
-		this._watchHeartbeat();
+		if (options.watch !== "first-ping") this._watchHeartbeat();
 	}
 	/** Whether `accept()` was called. */
 	get accepted() {
 		return this._accepted;
 	}
+	/** How binary messages arrive: `ArrayBuffer`s (the default) or `Blob`s. Other values are ignored. */
+	get binaryType() {
+		return this._binaryType;
+	}
+	set binaryType(value) {
+		if (value === "blob" || value === "arraybuffer") this._binaryType = value;
+	}
+	/**
+	* Hands this end's transport to another holder before it was accepted: the port to give the
+	* client (a pair's end returned in a 101, say), with the frames that reached this end first
+	* delivered ahead of the rest. This end is closed then, with no event, and answers nothing.
+	*/
+	detach() {
+		const port = this._port;
+		if (!port || this._accepted || this._state !== 1) throw new DOMException("Only an open end that was not accepted can be detached.", "InvalidStateError");
+		this._detached = true;
+		this._port = void 0;
+		port.onmessage = null;
+		let owed = this.bufferedAmount;
+		this._state = 3;
+		this._onClosed();
+		this._wakeDrainWaiters();
+		const queued = this._queue.splice(0);
+		if (queued.length === 0 && owed === 0) return port;
+		const relay = new MessageChannel();
+		const holder = relay.port2;
+		const closing = /* @__PURE__ */ new Set();
+		const end = () => {
+			port.onmessage = null;
+			holder.onmessage = null;
+			port.close();
+			holder.close();
+		};
+		const sawClose = (way) => {
+			closing.add(way);
+			if (closing.size === 2) end();
+		};
+		for (const frame of queued) {
+			postFrame(holder, frame);
+			if (frame.t === "c") closing.add("in");
+		}
+		holder.onmessage = (event) => {
+			port.postMessage(event.data, transferables(event.data));
+			if (event.data?.t === "c") sawClose("out");
+		};
+		port.onmessage = (event) => {
+			const data = event.data;
+			if (data?.t === "a" && typeof data.n === "number" && owed > 0) {
+				const absorbed = Math.min(owed, data.n);
+				owed -= absorbed;
+				if (data.n > absorbed) holder.postMessage({
+					t: "a",
+					n: data.n - absorbed
+				});
+				return;
+			}
+			holder.postMessage(event.data, transferables(event.data));
+			if (data?.t === "c") sawClose("in");
+		};
+		port.addEventListener?.("close", end);
+		holder.addEventListener?.("close", end);
+		return relay.port1;
+	}
 	/** Starts delivering events, the queued ones first. */
 	accept() {
+		if (this._detached) throw new DOMException("This end was detached; it cannot be accepted.", "InvalidStateError");
 		if (this._accepted) return;
 		this._accepted = true;
-		for (const frame of this._queue.splice(0)) super._deliver(frame);
+		for (const frame of this._queue.splice(0)) this._deliver(frame);
 	}
 	send(data) {
-		if (!this._accepted) throw new DOMException("accept() the socket before sending on it.", "InvalidStateError");
+		if (this._detached) throw new DOMException("This end was detached; it cannot send.", "InvalidStateError");
+		if (!this._accepted && !this._options.sendBeforeAccept) throw new DOMException("accept() the socket before sending on it.", "InvalidStateError");
 		this._sendData(isBinary(data) ? toArrayBuffer(data) : String(data));
 	}
-	close(code = 1e3, reason = "") {
-		if (!isSendableCloseCode(code)) throw new DOMException(`${code} is not a close code an endpoint may send.`, "InvalidAccessError");
+	close(code, reason = "") {
+		this.checkClose(code, reason);
+		this._startClose(code ?? this._options.defaultCloseCode ?? 1e3, reason);
+	}
+	/**
+	* Refuses a `close()` the endpoint may not make: by default a code outside RFC 6455 §7.4's
+	* sendable ones, or a reason over 123 bytes. A subclass with another platform's rules
+	* overrides it.
+	*/
+	checkClose(code, reason) {
+		if (code !== void 0 && !isSendableCloseCode(code)) throw new DOMException(`${code} is not a close code an endpoint may send.`, "InvalidAccessError");
 		if (utf8Length(reason) > 123) throw new DOMException("The close reason is longer than 123 bytes.", "SyntaxError");
-		this._startClose(code, reason);
 	}
 	_deliver(frame) {
 		if (!this._accepted) {
 			this._queue.push(frame);
 			return;
 		}
+		if (frame.t === "m" && this._state === 2 && this._options.deliverWhileClosing) {
+			this._dispatchMessage(frame.d);
+			this._consumed(messageSize(frame.d));
+			return;
+		}
 		super._deliver(frame);
 	}
 	_dispatchMessage(data) {
-		this.dispatchEvent(new MessageEvent("message", { data }));
+		const delivered = typeof data !== "string" && this._binaryType === "blob" ? new Blob([data]) : data;
+		this.dispatchEvent(new MessageEvent("message", { data: delivered }));
 	}
 	_onPing(hb) {
 		this._post({ t: "q" });
 		this._lastPing = Date.now();
-		if (hb !== this._heartbeatMs) {
+		if (this._state === 3) return;
+		const keep = this._options.heartbeatPeriod === "first" && this._pinged;
+		if (!(hb > 0 && hb < 2 ** 31 - 1)) {
+			if (!keep && this._watch !== void 0) {
+				this._timers.clearInterval(this._watch);
+				this._watch = void 0;
+			}
+			return;
+		}
+		this._pinged = true;
+		if (!keep && (this._watch === void 0 || hb !== this._heartbeatMs)) {
 			this._heartbeatMs = hb;
 			this._watchHeartbeat();
 		}
@@ -3821,6 +4290,11 @@ function isSendableCloseCode(code) {
 	if (code >= 3e3 && code <= 4999) return true;
 	return code >= 1e3 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006;
 }
+/** The buffers a relayed frame carries, to transfer rather than copy. */
+function transferables(data) {
+	const d = data?.d;
+	return d instanceof ArrayBuffer ? [d] : [];
+}
 //#endregion
 //#region src/ws/upgrade.ts
 /**
@@ -3852,6 +4326,7 @@ function newWebSocketUpgradeRequest(url, { protocols = [], headers } = {}) {
 	all.set("connection", "Upgrade");
 	all.set("sec-websocket-version", "13");
 	if (!all.has("sec-websocket-key")) all.set("sec-websocket-key", randomKey());
+	all.delete("sec-websocket-protocol");
 	if (protocols.length > 0) all.set("sec-websocket-protocol", protocols.join(", "));
 	if (!all.has("x-webrun-ws-version")) all.set(WS_VERSION_HEADER, `2`);
 	return withHeaders(new Request(httpUrl, {
@@ -3911,6 +4386,23 @@ function upgradeWebSocket(request, options = {}) {
 		url: request.url,
 		protocol
 	});
+	const response = webSocketUpgradeResponse(channel.port2, protocol);
+	Object.defineProperty(response, "webSocket", {
+		value: socket,
+		configurable: true
+	});
+	return {
+		socket,
+		response
+	};
+}
+/**
+* A 101 for a socket whose server end the handler runs itself, on the other end of `port`
+* (a server of its own over this package's frames, say): what `upgradeWebSocket` returns, minus
+* the `ServerWebSocket`. The host hands `port` to the caller as it would for `upgradeWebSocket`
+* (`takePort`), and `protocol` (`""` for none) is the subprotocol picked.
+*/
+function webSocketUpgradeResponse(port, protocol = "") {
 	const response = new Response(null, {
 		status: 200,
 		headers: protocol ? { "sec-websocket-protocol": protocol } : {}
@@ -3924,23 +4416,16 @@ function upgradeWebSocket(request, options = {}) {
 			value: "Switching Protocols",
 			configurable: true
 		},
-		webSocket: {
-			value: socket,
-			configurable: true
-		},
 		[UPGRADE]: {
 			value: {
-				port: channel.port2,
+				port,
 				protocol
 			},
 			configurable: true,
 			writable: true
 		}
 	});
-	return {
-		socket,
-		response
-	};
+	return response;
 }
 /**
 * The port to hand to the caller, for a response from `upgradeWebSocket`.
@@ -4008,6 +4493,51 @@ function randomKey() {
 	return btoa(String.fromCharCode(...bytes));
 }
 //#endregion
+//#region src/sw/protocol.ts
+/**
+* The messages between pages, Dedicated Workers and the same-origin
+* ServiceWorker. Internal: the shapes may change between versions, which is
+* why every hand-shake carries `HTTP_LINK_PROTOCOL`.
+*
+* THREE PORTS PER HANDLER LINK. A page makes the channels and hands one end of
+* each to the handler (itself, or a worker) and the other to the
+* ServiceWorker; after that it carries nothing:
+*
+* - `down`: ServiceWorker → handler, the requests the handler serves;
+* - `ctl`: a raw port next to them, for what HTTP over a stream cannot carry,
+*   transferred `MessagePort`s (WebSocket hand-over);
+* - `up` (workers only): handler → ServiceWorker, the requests the handler
+*   sends through the router (to other handlers).
+*/
+/** Page → ServiceWorker: attach a handler link. The name is the one version 1 used. */
+const ATTACH_CALL = "UPDATE_COMMUNICATION_PORT";
+/** Page → ServiceWorker: remove a handler link now. */
+const DETACH_CALL = "webrun-http:detach";
+/** Page → ServiceWorker: stop routing to a link, let its requests finish, then remove it. */
+const DRAIN_CALL = "webrun-http:drain";
+/** Page → ServiceWorker: open a WebSocket to a handler. */
+const WS_CONNECT_CALL = "webrun-http:ws-connect";
+/** ServiceWorker → pages: attach your links again (the ServiceWorker restarted). */
+const NEED_LINKS_CALL = "webrun-http:need-links";
+/**
+* Page → ServiceWorker, plain messages (no reply). A message to the
+* ServiceWorker object is an event: it starts a stopped worker and resets its
+* idle timer. Port messages do neither.
+*/
+const WAKE_MESSAGE = "webrun-http:wake";
+const KEEPALIVE_MESSAGE = "webrun-http:keepalive";
+/** Page ↔ worker: what `attachWorker` and `serveHttpInWorker` exchange. */
+const WORKER_HELLO = "webrun-http:worker-hello";
+/** `headers` as pairs a `postMessage` can carry (a `Headers` object cannot be cloned). */
+function headerPairs(headers) {
+	if (headers === void 0) return void 0;
+	const pairs = [];
+	new Headers(headers).forEach((value, name) => {
+		pairs.push([name, value]);
+	});
+	return pairs;
+}
+//#endregion
 //#region src/sw/handler-endpoint.ts
 /** The message calls through a lost ServiceWorker fail with. */
 const ROUTER_LOST_MESSAGE = "The ServiceWorker was lost while this call was in flight";
@@ -4091,8 +4621,11 @@ var HandlerEndpoint = class {
 		this._startKeepAlive();
 		return await link.up.send(request);
 	}
-	/** Opens a socket to the handler `url` routes to, through the ServiceWorker. */
-	async connectWebSocket(url, protocols = []) {
+	/**
+	* Opens a socket to the handler `url` routes to, through the ServiceWorker. The handler sees
+	* `headers` on the upgrade request, and so does a `route` function choosing it.
+	*/
+	async connectWebSocket(url, protocols = [], headers) {
 		const link = await this._linkWith("ctl");
 		const id = this._sockets.newId();
 		const answer = this._sockets.wait(id, this.options.wsConnectTimeoutMs ?? 15e3, `the socket request for ${url}`);
@@ -4100,7 +4633,8 @@ var HandlerEndpoint = class {
 			t: "ws-open",
 			id,
 			url,
-			protocols
+			protocols,
+			headers: headerPairs(headers)
 		});
 		return await answer;
 	}
@@ -4519,8 +5053,9 @@ async function awaitServiceWorkerControl(registration, { timeout = DEFAULT_SERVI
 * Returns a function that stops answering.
 */
 function handleClaimRequests(self) {
-	return handleChannelCalls(self, CLAIM_CALL, (event) => {
-		const claimed = self.clients.claim().then(() => true);
+	const sw = self;
+	return handleChannelCalls(sw, CLAIM_CALL, (event) => {
+		const claimed = sw.clients.claim().then(() => true);
 		event.waitUntil?.(claimed);
 		return claimed;
 	});
@@ -4792,43 +5327,22 @@ async function sendHttpRequest(communicationPort, request) {
 	})(request);
 }
 //#endregion
-//#region src/sw/protocol.ts
-/**
-* The messages between pages, Dedicated Workers and the same-origin
-* ServiceWorker. Internal: the shapes may change between versions, which is
-* why every hand-shake carries `HTTP_LINK_PROTOCOL`.
-*
-* THREE PORTS PER HANDLER LINK. A page makes the channels and hands one end of
-* each to the handler (itself, or a worker) and the other to the
-* ServiceWorker; after that it carries nothing:
-*
-* - `down`: ServiceWorker → handler, the requests the handler serves;
-* - `ctl`: a raw port next to them, for what HTTP over a stream cannot carry,
-*   transferred `MessagePort`s (WebSocket hand-over);
-* - `up` (workers only): handler → ServiceWorker, the requests the handler
-*   sends through the router (to other handlers).
-*/
-/** Page → ServiceWorker: attach a handler link. The name is the one version 1 used. */
-const ATTACH_CALL = "UPDATE_COMMUNICATION_PORT";
-/** Page → ServiceWorker: remove a handler link now. */
-const DETACH_CALL = "webrun-http:detach";
-/** Page → ServiceWorker: stop routing to a link, let its requests finish, then remove it. */
-const DRAIN_CALL = "webrun-http:drain";
-/** Page → ServiceWorker: open a WebSocket to a handler. */
-const WS_CONNECT_CALL = "webrun-http:ws-connect";
-/** ServiceWorker → pages: attach your links again (the ServiceWorker restarted). */
-const NEED_LINKS_CALL = "webrun-http:need-links";
+//#region src/sw/http-sw-dispatcher.ts
 /**
-* Page → ServiceWorker, plain messages (no reply). A message to the
-* ServiceWorker object is an event: it starts a stopped worker and resets its
-* idle timer. Port messages do neither.
+* The default key: the url's first path segment under `scope`, decoded; none outside it, at the
+* scope itself, or for a segment that does not decode.
 */
-const WAKE_MESSAGE = "webrun-http:wake";
-const KEEPALIVE_MESSAGE = "webrun-http:keepalive";
-/** Page ↔ worker: what `attachWorker` and `serveHttpInWorker` exchange. */
-const WORKER_HELLO = "webrun-http:worker-hello";
-//#endregion
-//#region src/sw/http-sw-dispatcher.ts
+function scopeKey(url, scope) {
+	const href = `${url}`;
+	if (!href.startsWith(scope)) return void 0;
+	const key = href.substring(scope.length).replace(/[?#].*$/, "").split("/")[0];
+	if (!key) return void 0;
+	try {
+		return decodeURIComponent(key);
+	} catch {
+		return;
+	}
+}
 /** One attached handler link, as the ServiceWorker holds it. */
 var HandlerEntry = class {
 	key;
@@ -4868,7 +5382,8 @@ const TIMED_OUT = Symbol("timed-out");
 * (`SwHttpAdapter.register`) or in Dedicated Workers
 * (`SwHttpAdapter.attachWorker` + `serveHttpInWorker`).
 *
-* A url `<scope>/<key>/...` belongs to the handlers of `key`. Of those, the
+* A url `<scope>/<key>/...` belongs to the handlers of `key` (the `key`
+* option maps urls to keys some other way). Of those, the
 * `route` option picks one per request. Requests and responses stream with
 * backpressure in both directions, and an aborted fetch reaches the handler
 * as a cancellation (webrun-rpc + webrun-http-streams).
@@ -4887,6 +5402,8 @@ const TIMED_OUT = Symbol("timed-out");
 */
 var SwHttpDispatcher = class {
 	self;
+	/** `self`, with the WebWorker lib's types this module compiles with. */
+	_sw;
 	log;
 	options;
 	table = new HandlerTable();
@@ -4909,19 +5426,22 @@ var SwHttpDispatcher = class {
 	constructor(options) {
 		this.options = options;
 		this.self = options.self;
+		this._sw = options.self;
 		this.log = options.log ?? (() => {});
 		if (locksAvailable()) this.routerLock = newLockName("webrun-http-router");
 	}
 	get scope() {
-		return `${new URL("./", this.self.location.href)}`;
+		return this._sw.registration?.scope ?? `${new URL("./", this._sw.location.href)}`;
 	}
-	/** The key `url` belongs to: its first path segment under the scope. */
+	/** The key `url` belongs to (the `key` option; by default its first path segment under the scope). */
 	keyOf(url) {
-		const href = `${url}`;
-		const scope = this.scope;
-		if (!href.startsWith(scope)) return void 0;
-		const key = href.substring(scope.length).replace(/[?#].*$/, "").split("/")[0];
-		return key ? decodeURIComponent(key) : void 0;
+		let parsed;
+		try {
+			parsed = new URL(`${url}`);
+		} catch {
+			return;
+		}
+		return (this.options.key ?? scopeKey)(parsed, this.scope);
 	}
 	/** Whether `key` has ever been served on this worker. */
 	isClaimedKey(key) {
@@ -4932,7 +5452,7 @@ var SwHttpDispatcher = class {
 		return this.claimedKeys.has(key) || this.table.all(key).length > 0;
 	}
 	start() {
-		const self = this.self;
+		const self = this._sw;
 		if (this.routerLock) this._routerHeld = holdLock(this.routerLock).then(() => {});
 		this._restored = this._restoreClaimedKeys();
 		const latch = () => {
@@ -4952,8 +5472,8 @@ var SwHttpDispatcher = class {
 			return true;
 		}), handleChannelCalls(self, WS_CONNECT_CALL, async (event, params) => {
 			if (!this._isOwnClient(event)) throw new Error("Only this origin's pages may open sockets");
-			const { url, protocols } = params;
-			const connection = await this.connectWebSocket(url, protocols ?? []);
+			const { url, protocols, headers } = params;
+			const connection = await this.connectWebSocket(url, protocols ?? [], this._socketHeaders(headers, "page"));
 			return withTransfer(connection, [connection.port]);
 		}));
 		const onMessage = (event) => {
@@ -4971,10 +5491,10 @@ var SwHttpDispatcher = class {
 			this.log("Claim control over all clients.");
 			event.waitUntil(self.clients.claim());
 		};
-		const onFetch = (event) => this._onFetch(event);
+		const onFetch = (event) => void this.handleFetch(event);
 		self.addEventListener("install", onInstall);
 		self.addEventListener("activate", onActivate);
-		self.addEventListener("fetch", onFetch);
+		if (this.options.handleFetch !== false) self.addEventListener("fetch", onFetch);
 		this._cleanup.push(() => {
 			self.removeEventListener("install", onInstall);
 			self.removeEventListener("activate", onActivate);
@@ -4989,37 +5509,60 @@ var SwHttpDispatcher = class {
 	}
 	/**
 	* Answers `request` as a fetch under the scope would be: through the
-	* handler its key routes to. A url outside the scope, or of a key this
-	* worker never served, goes to the network.
+	* handler its key routes to. A url with no key (by default, one outside the
+	* scope), or of a key this worker never served, goes to the network.
 	*/
 	async dispatch(request) {
 		const key = this.keyOf(request.url);
 		if (key === void 0) return await fetch(request);
 		await this._restored.catch(() => {});
 		const entry = await this._acquire(request, key);
-		if (entry === TIMED_OUT) return new Response(null, {
-			status: 503,
-			statusText: "Service Unavailable (no handler attached in time)"
-		});
+		if (entry === TIMED_OUT) return await this._failed(request, { kind: "timeout" });
 		if (!entry) {
 			if (!this.serves(key)) return await fetch(request);
-			return new Response(null, {
-				status: 404,
-				statusText: "Not Found (no active handler)"
-			});
+			return await this._failed(request, { kind: "gone" });
 		}
 		try {
 			return await entry.link.send(request);
 		} catch (error) {
 			this.log("[dispatch] failed", key, error);
-			return new Response(errorMessage(error), {
-				status: 502,
-				statusText: "Bad Gateway",
-				headers: { "content-type": "text/plain; charset=utf-8" }
+			return await this._failed(request, {
+				kind: "lost",
+				error
 			});
 		}
 	}
 	/**
+	* After `start()`: settles once the keys this worker served before a restart are read back
+	* (whatever the outcome). Until then `serves()` may answer `false` for a key it will serve.
+	*/
+	get ready() {
+		return this._restored.then(() => {}, () => {});
+	}
+	_socketHeaders(headers, from) {
+		return this.options.socketHeaders ? this.options.socketHeaders(headers, from) : headers;
+	}
+	async _failed(request, failure) {
+		if (this.options.failure) try {
+			return await this.options.failure(request, failure);
+		} catch (error) {
+			this.log("[dispatch] the failure option threw; answering by default", error);
+		}
+		if (failure.kind === "timeout") return new Response(null, {
+			status: 503,
+			statusText: "Service Unavailable (no handler attached in time)"
+		});
+		if (failure.kind === "gone") return new Response(null, {
+			status: 404,
+			statusText: "Not Found (no active handler)"
+		});
+		return new Response(errorMessage(failure.error), {
+			status: 502,
+			statusText: "Bad Gateway",
+			headers: { "content-type": "text/plain; charset=utf-8" }
+		});
+	}
+	/**
 	* Opens a socket to the handler `url` routes to: the handler accepts or
 	* refuses it like an HTTP upgrade, and the socket's port comes back. After
 	* that the socket runs between the caller and the handler directly; this
@@ -5031,7 +5574,7 @@ var SwHttpDispatcher = class {
 			headers
 		});
 		const key = this.keyOf(request.url);
-		if (key === void 0) throw new Error(`${url} is outside this ServiceWorker's scope`);
+		if (key === void 0) throw new Error(`${url} belongs to no key of this ServiceWorker`);
 		await this._restored.catch(() => {});
 		const entry = await this._acquire(request, key);
 		if (!entry || entry === TIMED_OUT) throw new Error(`No handler serves ${url}`);
@@ -5047,20 +5590,47 @@ var SwHttpDispatcher = class {
 		});
 		return await answer;
 	}
-	_onFetch(event) {
-		const request = event.request;
+	/**
+	* Answers `event` if it is the dispatcher's, with `request` (default `event.request`; a host
+	* may pass a rewritten one, with headers it adds). Returns whether it called `respondWith`;
+	* when it did not, the event is the caller's to answer or to leave to the network. For a host
+	* that listens to `fetch` itself (`handleFetch: false`); call it synchronously in the event's
+	* listener, as `respondWith` must be.
+	*
+	* It takes a same-origin request whose key (the `key` option) a handler serves, and also:
+	* - a navigation under the scope whose key nobody serves (answered by `unserved`);
+	* - before the stored keys are read (the first requests after a restart), every request with
+	*   a key, since only then is it known whose it is: one nobody serves gets what it would have
+	*   got after, `unserved` for a navigation and the network for anything else.
+	* So a host with a page of its own for urls nobody serves gives it as `unserved`, rather than
+	* deciding before calling this.
+	*/
+	handleFetch(event, request = event.request) {
+		const navigation = event.request.mode === "navigate";
+		if (new URL(request.url).origin !== this._sw.location.origin) return false;
 		const key = this.keyOf(request.url);
-		if (key === void 0) return;
+		if (key === void 0) return false;
 		if (this._restoreSettled) {
-			if (this.serves(key)) event.respondWith(this.dispatch(request));
-			else if (request.mode === "navigate") event.respondWith(fetch(request));
-			return;
+			if (this.serves(key)) {
+				event.respondWith(this.dispatch(request));
+				return true;
+			}
+			if (navigation) {
+				event.respondWith(this._unserved(request));
+				return true;
+			}
+			return false;
 		}
 		event.respondWith((async () => {
 			await this._restored.catch(() => {});
-			if (!this.serves(key)) return await fetch(request);
-			return await this.dispatch(request);
+			if (this.serves(key)) return await this.dispatch(request);
+			return navigation ? await this._unserved(request) : await fetch(request);
 		})());
+		return true;
+	}
+	/** What a request the dispatcher took, and no handler serves, gets: `unserved`, or the network. */
+	async _unserved(request) {
+		return await (this.options.unserved ?? fetch)(request);
 	}
 	async _attach(event, params, ports) {
 		const clientId = event.source?.id;
@@ -5079,8 +5649,11 @@ var SwHttpDispatcher = class {
 		}
 		const ctl = params.ctl ? rest.shift() : void 0;
 		const up = params.up ? rest.shift() : void 0;
-		const streamTimeout = this.options.streamTimeout;
-		const link = await connectHttpLink(down, { streamTimeout });
+		const { streamTimeout, window } = this.options;
+		const link = await connectHttpLink(down, {
+			streamTimeout,
+			window
+		});
 		const entry = new HandlerEntry(params.key, params.id ?? clientId ?? crypto.randomUUID(), params.owner ?? crypto.randomUUID(), params.meta, link, ctl, clientId, params.ownerLock);
 		if (up) entry.closeUp = await serveHttpLink(up, (request) => this.dispatch(request), { streamTimeout });
 		if (ctl) ctl.onmessage = (message) => this._onControl(entry, message.data);
@@ -5159,20 +5732,35 @@ var SwHttpDispatcher = class {
 	* its key, waiting for one when there is none.
 	*/
 	async _acquire(request, key) {
+		const deadline = Date.now() + (this.options.attachTimeoutMs ?? 15e3);
 		const picked = await this._pick(request, key);
 		if (picked) return picked;
-		if (this.table.all(key).length > 0) return await this.table.waitFor(key, this.options.attachTimeoutMs ?? 15e3, this.table.live(key).length > 0) ? await this._pick(request, key) ?? TIMED_OUT : TIMED_OUT;
-		const vacantUntil = this._vacant.get(key) ?? 0;
-		if (vacantUntil > Date.now()) return await this.table.waitFor(key, vacantUntil - Date.now()) ? await this._pick(request, key) ?? TIMED_OUT : TIMED_OUT;
-		if (!this.serves(key)) return void 0;
-		await this._askForLinks(key);
-		return await this._pick(request, key);
+		if (this.table.all(key).length === 0) {
+			const vacantUntil = this._vacant.get(key) ?? 0;
+			if (vacantUntil > Date.now()) return await this._waitToPick(request, key, vacantUntil);
+			if (!this.serves(key)) return void 0;
+			await this._askForLinks(key);
+			const relinked = await this._pick(request, key);
+			if (relinked) return relinked;
+			if (this.table.all(key).length === 0) return void 0;
+		}
+		return await this._waitToPick(request, key, deadline);
+	}
+	/** Waits for attaches until `route` accepts a handler, or `until` passes. */
+	async _waitToPick(request, key, until) {
+		for (;;) {
+			const left = until - Date.now();
+			if (left <= 0) return TIMED_OUT;
+			await this.table.waitFor(key, Math.min(left, 1e3), this.table.live(key).length > 0);
+			const picked = await this._pick(request, key);
+			if (picked) return picked;
+		}
 	}
 	async _pick(request, key) {
 		let live = this.table.live(key);
 		for (const entry of live) {
 			if (entry.ownerLock || !entry.clientId) continue;
-			if (!await this.self.clients.get(entry.clientId)) this._close(entry, new LinkLostError(HANDLER_LOST_MESSAGE));
+			if (!await this._sw.clients.get(entry.clientId)) this._close(entry, new LinkLostError(HANDLER_LOST_MESSAGE));
 		}
 		live = this.table.live(key);
 		if (live.length === 0) return void 0;
@@ -5196,7 +5784,7 @@ var SwHttpDispatcher = class {
 	}
 	async _linkRound(key) {
 		const timeout = this.options.relinkTimeoutMs ?? 3e3;
-		const windows = await this.self.clients.matchAll({
+		const windows = await this._sw.clients.matchAll({
 			type: "window",
 			includeUncontrolled: true
 		});
@@ -5234,7 +5822,7 @@ var SwHttpDispatcher = class {
 				entry.sockets.fail(message.id, new Error(message.message));
 				return;
 			case "ws-open":
-				this.connectWebSocket(message.url, message.protocols).then(({ port, protocol }) => entry.ctl?.postMessage({
+				this.connectWebSocket(message.url, message.protocols, this._socketHeaders(message.headers, "handler")).then(({ port, protocol }) => entry.ctl?.postMessage({
 					t: "ws-opened",
 					id: message.id,
 					protocol,
@@ -5251,7 +5839,7 @@ var SwHttpDispatcher = class {
 		const source = event.source;
 		if (!source?.url) return false;
 		try {
-			return new URL(source.url).origin === this.self.location.origin;
+			return new URL(source.url).origin === this._sw.location.origin;
 		} catch {
 			return false;
 		}
@@ -5275,6 +5863,7 @@ var SwHttpDispatcher = class {
 * that stops it.
 */
 function startHttpDispatcher(options) {
+	if (options.handleFetch === false) throw new Error("startHttpDispatcher: handleFetch: false needs a dispatcher to call handleFetch on; construct it instead: new SwHttpDispatcher({ self, handleFetch: false }).start()");
 	const dispatcher = new SwHttpDispatcher(options);
 	dispatcher.start();
 	return () => {
@@ -5449,6 +6038,8 @@ var SwPortHandler = class {
 */
 var SwPortDispatcher = class {
 	self;
+	/** `self`, with the WebWorker lib's types this module compiles with. */
+	_sw;
 	log;
 	handlersIndex = /* @__PURE__ */ new Map();
 	/**
@@ -5462,10 +6053,11 @@ var SwPortDispatcher = class {
 	_activationPromise;
 	constructor({ self, log = () => {} }) {
 		this.self = self;
+		this._sw = self;
 		this.log = log;
 	}
 	get scope() {
-		return `${new URL("./", this.self.location.href)}`;
+		return this._sw.registration?.scope ?? `${new URL("./", this._sw.location.href)}`;
 	}
 	/**
 	* Look up the active channel for a key. Returns `undefined` when there
@@ -5478,7 +6070,7 @@ var SwPortDispatcher = class {
 			if (channelInfo.key !== key) continue;
 			const clientId = channelInfo.clientId;
 			if (!clientId) continue;
-			if (!await this.self.clients.get(clientId)) {
+			if (!await this._sw.clients.get(clientId)) {
 				this.handlersIndex.delete(clientId);
 				continue;
 			}
@@ -5490,8 +6082,8 @@ var SwPortDispatcher = class {
 		return this.claimedKeys.has(key);
 	}
 	start() {
-		const stopClaims = handleClaimRequests(this.self);
-		const stopPortUpdates = handleChannelCalls(this.self, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
+		const stopClaims = handleClaimRequests(this._sw);
+		const stopPortUpdates = handleChannelCalls(this._sw, "UPDATE_COMMUNICATION_PORT", async (event, channelInfo, port) => {
 			const clientId = event.source?.id;
 			this.log("[UPDATE_COMMUNICATION_PORT]", clientId, channelInfo);
 			await this._updateChannelInfo({
@@ -5505,14 +6097,14 @@ var SwPortDispatcher = class {
 			stopClaims();
 			stopPortUpdates();
 		};
-		this.self.addEventListener("install", (event) => {
+		this._sw.addEventListener("install", (event) => {
 			this.log("Skip waiting on install.", event);
-			this.self.skipWaiting();
+			this._sw.skipWaiting();
 		});
-		this.self.addEventListener("activate", (event) => {
+		this._sw.addEventListener("activate", (event) => {
 			this.log("Claim control over all clients.", event);
 			event.waitUntil((async () => {
-				await this.self.clients.claim();
+				await this._sw.clients.claim();
 				await this._checkActivation();
 			})());
 		});
@@ -5562,7 +6154,7 @@ var SwPortDispatcher = class {
 		for (const clientId of this.handlersIndex.keys()) ids.add(clientId);
 		const index = /* @__PURE__ */ new Map();
 		for (const clientId of ids) {
-			const client = await this.self.clients.get(clientId);
+			const client = await this._sw.clients.get(clientId);
 			if (client) index.set(clientId, client);
 			else this.handlersIndex.delete(clientId);
 		}
@@ -5842,7 +6434,10 @@ var SwHttpAdapter = class {
 		return this.options.key;
 	}
 	get scope() {
-		return this.options.scope ?? new URL("./", this.serviceWorkerUrl).pathname;
+		if (this.options.scope) return this.options.scope;
+		const registration = this.options.registration;
+		if (registration) return new URL(registration.scope).pathname;
+		return new URL("./", this.serviceWorkerUrl).pathname;
 	}
 	/**
 	* The scope as a url on the worker's origin. Resolved against the worker's
@@ -5853,6 +6448,8 @@ var SwHttpAdapter = class {
 	* sits next to it).
 	*/
 	get rootUrl() {
+		const registration = this.options.registration;
+		if (registration && !this.options.serviceWorkerUrl) return new URL(this.scope, registration.scope);
 		const base = this.options.serviceWorkerUrl ? this.serviceWorkerUrl : import.meta.url;
 		return new URL(this.scope, base);
 	}
@@ -5874,7 +6471,10 @@ var SwHttpAdapter = class {
 	*/
 	async start() {
 		if (!this._registrationPromise) this._registrationPromise = (async () => {
-			const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl, { scope: this.scope });
+			const registration = this.options.registration ?? await navigator.serviceWorker.register(this.serviceWorkerUrl, {
+				scope: this.scope,
+				...this.options.type ? { type: this.options.type } : {}
+			});
 			this._registration = registration;
 			const stopListening = handleChannelCalls(navigator.serviceWorker, NEED_LINKS_CALL, async (_event, params) => {
 				await this.relink(params?.routerLock);
@@ -5904,7 +6504,7 @@ var SwHttpAdapter = class {
 		})();
 		return this._registrationPromise;
 	}
-	/** Detaches every link, and unregisters the worker. */
+	/** Detaches every link, and unregisters the worker (unless the page passed its `registration`). */
 	async stop() {
 		for (const cleanup of this._cleanup.splice(0)) cleanup();
 		for (const worker of [...this._workers]) await worker.detach().catch(() => {});
@@ -5921,7 +6521,7 @@ var SwHttpAdapter = class {
 		this._registration = void 0;
 		this._registrationPromise = void 0;
 		try {
-			await registration?.unregister();
+			if (!this.options.registration) await registration?.unregister();
 		} catch (error) {
 			console.log("Service Worker unregistration failed: ", error);
 		}
@@ -5995,10 +6595,10 @@ var SwHttpAdapter = class {
 	/**
 	* Opens the transport of a socket to the handler `url` routes to: a handler
 	* of this page directly, any other through the ServiceWorker. Resolves once
-	* the handler accepted. An arrow function, so it can be handed around:
-	* `createWebSocketClass(adapter.connectWebSocket)`.
+	* the handler accepted. The handler sees `headers` on the upgrade request. An arrow function,
+	* so it can be handed around: `createWebSocketClass(adapter.connectWebSocket)`.
 	*/
-	connectWebSocket = async (url, protocols = []) => {
+	connectWebSocket = async (url, protocols = [], headers) => {
 		const httpUrl = new URL(`${url}`, globalThis.location?.href);
 		if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
 		else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
@@ -6006,7 +6606,8 @@ var SwHttpAdapter = class {
 		if (local) {
 			const result = await serveWebSocketUpgrade(local, {
 				url: `${httpUrl}`,
-				protocols
+				protocols,
+				headers
 			});
 			if (!result.ok) throw new Error(result.message);
 			return {
@@ -6017,7 +6618,8 @@ var SwHttpAdapter = class {
 		await this.start();
 		return await callChannelWithin(this._callTimeout(), this._worker(), WS_CONNECT_CALL, {
 			url: `${httpUrl}`,
-			protocols
+			protocols,
+			headers: headerPairs(headers)
 		});
 	};
 	/**
@@ -6313,11 +6915,11 @@ function serveHttpInWorker(handler, options = {}) {
 	};
 	scope.addEventListener("message", onMessage);
 	const baseUrl = () => globalThis.location?.href;
-	const connectWebSocket = (url, protocols = []) => {
+	const connectWebSocket = (url, protocols = [], headers) => {
 		const httpUrl = new URL(`${url}`, baseUrl());
 		if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
 		else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
-		return endpoint.connectWebSocket(`${httpUrl}`, protocols);
+		return endpoint.connectWebSocket(`${httpUrl}`, protocols, headers);
 	};
 	let WebSocketClass;
 	return {
@@ -6344,4 +6946,4 @@ function serveHttpInWorker(handler, options = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_HEARTBEAT_MS, HANDLER_LOST_MESSAGE, HTTP_LINK_PROTOCOL, HandlerEndpoint, HandlerTable, LinkLostError, PortRendezvous, ROUTER_LOST_MESSAGE, ServerWebSocket, SwHttpAdapter, SwHttpDispatcher, SwPortDispatcher, SwPortHandler, WS_PORT_PROTOCOL_VERSION, WS_VERSION_HEADER, WsCloseEvent, connectHttpLink, connectWebSocketThroughServiceWorker, createWebSocketClass, holdLock, isWebSocketUpgrade, leastInflightRoute, locksAvailable, newLockName, newWebSocketUpgradeRequest, requestedProtocols, serveHttpInWorker, serveHttpLink, serveWebSocketUpgrade, serviceWorkerWebSocketClass, startHttpDispatcher, takePort, takeUpgrade, trackedLink, upgradeWebSocket, watchLock, withHeaders };
+export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_HEARTBEAT_MS, HANDLER_LOST_MESSAGE, HTTP_LINK_PROTOCOL, HandlerEndpoint, HandlerTable, LinkLostError, PortRendezvous, ROUTER_LOST_MESSAGE, ServerWebSocket, SwHttpAdapter, SwHttpDispatcher, SwPortDispatcher, SwPortHandler, WS_PORT_PROTOCOL_VERSION, WS_VERSION_HEADER, WsCloseEvent, connectHttpLink, connectWebSocketThroughServiceWorker, createWebSocketClass, holdLock, isWebSocketUpgrade, leastInflightRoute, locksAvailable, newLockName, newWebSocketUpgradeRequest, requestedProtocols, scopeKey, serveHttpInWorker, serveHttpLink, serveWebSocketUpgrade, serviceWorkerWebSocketClass, startHttpDispatcher, takePort, takeUpgrade, trackedLink, upgradeWebSocket, watchLock, webSocketUpgradeResponse, withHeaders };