@statewalker/webrun-http-browser 0.3.4 → 0.4.2

package/dist/index.js

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