@ekrooh/bare 0.4.0 → 0.6.0

package/dist/runtime.mjs

@@ -1,46 +1,419 @@
-import { MessageProtocol, MessageType, createPluginRegistry, createPluginRouter } from "./index.mjs";
-import { t as createDefaultPlugins } from "./plugins-1KweEBct.mjs";
+import { _ as MAX_FRAME_BYTES, c as createRequestId, g as ErrorCode, n as createBareRuntimeContext, v as MAX_HEADER_BYTES, y as MessageType } from "./messages-CevD8qkV.mjs";
+import { t as createDefaultPlugins } from "./plugins-Ddp2AgOe.mjs";
+import { t as createLogRingBuffer } from "./store-DTg1jN5E.mjs";
 import { TextDecoder, TextEncoder } from "bare-encoding";
 import fs from "bare-fs";
 import path from "bare-path";
+import crypto from "bare-crypto";
 import http from "bare-http1";
 import ws from "bare-ws";
-import crypto from "bare-crypto";
-//#region core/lib/get-ipc.ts
+// core/lib/get-ipc.ts
 /**
-* Returns the active IPC channel.
-* In BareKit (Android), it uses BareKit.IPC.
+* Returns the active IPC channel, or null when there is no host.
+* In BareKit (Android, iOS), it uses BareKit.IPC.
 * In Bare (Sidecar), it uses Bare.IPC.
 */
 function getIPC() {
 	const IPC = typeof BareKit !== "undefined" ? BareKit.IPC : typeof Bare !== "undefined" ? Bare.IPC : void 0;
 	if (IPC && typeof IPC.resume === "function") IPC.resume();
-	return IPC;
+	return IPC ?? null;
 }
-//#endregion
-//#region core/messages/host-ipc.ts
-function toUint8Array$2(data) {
+// core/messages/bytes.ts
+/** Normalizes a binary stream chunk to a `Uint8Array` view without copying.
+* A `Buffer` is already a `Uint8Array`. Anything else (a text WebSocket
+* message, a stray object) is not a protocol frame and throws. */
+function toBytes(data) {
 	if (data instanceof Uint8Array) return data;
-	if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) return new Uint8Array(data);
-	return new Uint8Array(data);
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	throw new TypeError(`expected binary data, got ${data === null ? "null" : typeof data}`);
+}
+/** The chunk form Bare's IPC stream writes: a `Buffer` view over the same
+* memory where `Buffer` exists (on Bare `encode` already returns one), the
+* bytes themselves elsewhere. */
+function toIpcChunk(bytes) {
+	if (typeof Buffer === "undefined" || Buffer.isBuffer(bytes)) return bytes;
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+// core/messages/backpressure.ts
+/** Honours `write() === false`: once the target signals pressure, frames queue
+* (bounded) until it drains instead of piling up inside the stream. */
+function createBoundedWriter(target, options) {
+	const hardMax = options.hardMaxQueuedBytes ?? options.maxQueuedBytes * 8;
+	let queue = [];
+	let head = 0;
+	let queued = 0;
+	let blocked = false;
+	let dead = false;
+	let dropped = 0;
+	function flush() {
+		while (!blocked && head < queue.length) {
+			const next = queue[head++];
+			queued -= next.byteLength;
+			if (!target.write(next)) blocked = true;
+		}
+		if (head === queue.length) {
+			queue = [];
+			head = 0;
+		} else if (head > 1024) {
+			queue = queue.slice(head);
+			head = 0;
+		}
+		if (!blocked && dropped > 0) {
+			console.warn(`[loopback] dropped ${dropped} push frame(s) while the client was not reading`);
+			dropped = 0;
+		}
+	}
+	target.on("drain", () => {
+		blocked = false;
+		flush();
+	});
+	return {
+		write(frame, writeOptions) {
+			if (dead) return false;
+			if (!blocked && head === queue.length) {
+				if (!target.write(frame)) blocked = true;
+				return true;
+			}
+			const size = frame.byteLength;
+			if (writeOptions?.droppable) {
+				if (queued + size > options.maxQueuedBytes) {
+					if (dropped === 0) console.warn("[loopback] client is not reading; dropping push frames (newest first)");
+					dropped++;
+					return false;
+				}
+			} else if (queued > 0 && queued + size > hardMax) {
+				dead = true;
+				queue = [];
+				head = 0;
+				queued = 0;
+				options.onOverflow();
+				return false;
+			}
+			queue.push(frame);
+			queued += size;
+			return true;
+		},
+		clear() {
+			queue = [];
+			head = 0;
+			queued = 0;
+		},
+		get queuedBytes() {
+			return queued;
+		}
+	};
+}
+/** Pauses an inbound stream while too much routed work is pending, so a fast
+* sender cannot queue work faster than it completes. */
+function createInboundGate(options) {
+	let pending = 0;
+	let paused = false;
+	function done() {
+		pending--;
+		if (paused && pending <= options.low) {
+			paused = false;
+			options.resume();
+		}
+	}
+	return {
+		/** Counts `work` as pending until it settles. */
+		track(work) {
+			pending++;
+			if (!paused && pending >= options.high) {
+				paused = true;
+				options.pause();
+			}
+			work.then(done, done);
+		},
+		get pending() {
+			return pending;
+		}
+	};
+}
+// core/messages/channel-health.ts
+/**
+* Per-channel decode/framing health tracker for the host↔worklet IPC pipe.
+*
+* The IPC pipe is a raw byte stream with no reconnect seam. A single corrupted
+* byte permanently desyncs the frame boundaries, so every subsequent frame
+* fails to decode. Unconditionally clearing the decoder after each failure
+* keeps parsing garbage forever — the channel is silently dead for the rest of
+* the session, and all host-delegated invokes time out until a restart.
+*
+* Instead we count consecutive decode/framing failures and treat a sustained run
+* as a fatal, unrecoverable desync. The caller then stops parsing rather than
+* spinning on garbage. A single isolated bad chunk is tolerated (the counter
+* resets on any successful frame batch), so transient corruption does not kill a
+* healthy channel.
+*/
+var ChannelHealth = class {
+	maxConsecutiveFailures;
+	consecutiveFailures = 0;
+	fatal = false;
+	constructor(maxConsecutiveFailures = 5) {
+		this.maxConsecutiveFailures = maxConsecutiveFailures;
+	}
+	/** Record a successful frame batch; resets the consecutive-failure counter. */
+	noteSuccess() {
+		this.consecutiveFailures = 0;
+	}
+	/**
+	* Record a decode/framing failure. Returns `true` once the run of
+	* consecutive failures reaches {@link maxConsecutiveFailures}, signalling the
+	* caller that the channel is fatally desynced and parsing should stop.
+	*/
+	noteFailure() {
+		this.consecutiveFailures++;
+		if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+			this.fatal = true;
+			return true;
+		}
+		return false;
+	}
+	/** Whether a fatal, unrecoverable desync has been reached. */
+	get isFatal() {
+		return this.fatal;
+	}
+	/** Number of consecutive failures since the last successful frame batch. */
+	get failures() {
+		return this.consecutiveFailures;
+	}
+};
+// core/messages/encode-response.ts
+/** Encodes a routed response. A response that cannot be encoded (a result over
+* the 64 KB header limit, or one that does not serialize) is replaced by an
+* error response for the same request, so the caller fails fast instead of
+* waiting for a timeout that never explains why. */
+function encodeResponse(protocol, response) {
+	try {
+		return protocol.encode(MessageType.ENVELOPE, response, null);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		const tooLarge = /too large/i.test(reason);
+		console.error(`Response for ${response.pluginId}.${response.event} dropped: ${reason}`);
+		return protocol.encode(MessageType.ENVELOPE, {
+			type: "INVOKE_RESPONSE",
+			pluginId: response.pluginId,
+			event: response.event,
+			requestId: response.requestId,
+			error: {
+				code: tooLarge ? ErrorCode.FRAME_TOO_LARGE : ErrorCode.INVALID_RESPONSE,
+				message: `Response for ${response.pluginId}.${response.event} could not be sent: ${reason}`
+			}
+		}, null);
+	}
 }
-function newCorrelationId() {
-	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+// core/messages/framing.ts
+/** Smallest buffer allocated for a partial frame whose length is not yet known
+* (fewer than 7 prefix bytes have arrived). */
+const MIN_PARTIAL_BYTES = 64;
+/** A partial-frame buffer larger than this is released once drained, so one
+* large frame does not pin its memory for the rest of the session. */
+const RETAIN_BYTES = 65536;
+function createFrameDecoder(protocol) {
+	/** Partial-frame storage: the first `length` bytes are buffered data. Empty
+	* whenever nothing is buffered, so a chunk of whole frames is decoded
+	* straight from the caller's bytes without being copied in first. */
+	let buffer = /* @__PURE__ */ new Uint8Array(0);
+	let length = 0;
+	let error = null;
+	function fail(err) {
+		error = err;
+		buffer = /* @__PURE__ */ new Uint8Array(0);
+		length = 0;
+	}
+	/** Grows `buffer` to hold at least `bytes`, preserving buffered data. */
+	function reserve(bytes) {
+		if (buffer.byteLength >= bytes) return;
+		const next = new Uint8Array(Math.max(bytes, MIN_PARTIAL_BYTES));
+		next.set(buffer.subarray(0, length), 0);
+		buffer = next;
+	}
+	/** Keeps `rest` (the unconsumed tail of `source`) as the buffered partial,
+	* sized for `frameLen` when the incomplete frame's length is known. */
+	function retain(source, from, to, frameLen) {
+		const rest = to - from;
+		if (rest === 0) {
+			length = 0;
+			if (buffer.byteLength > RETAIN_BYTES) buffer = /* @__PURE__ */ new Uint8Array(0);
+			return;
+		}
+		if (source === buffer) {
+			buffer.copyWithin(0, from, to);
+			length = rest;
+			reserve(frameLen);
+			return;
+		}
+		length = 0;
+		reserve(Math.max(rest, frameLen));
+		buffer.set(source.subarray(from, to), 0);
+		length = rest;
+	}
+	function push(chunk) {
+		if (error) return [];
+		let source;
+		let end;
+		if (length === 0) {
+			source = chunk;
+			end = chunk.byteLength;
+		} else {
+			reserve(length + chunk.byteLength);
+			buffer.set(chunk, length);
+			length += chunk.byteLength;
+			source = buffer;
+			end = length;
+		}
+		const out = [];
+		let offset = 0;
+		let pendingFrameLen = 0;
+		while (end - offset >= 7) {
+			const headerLen = source[offset + 2] << 8 | source[offset + 3];
+			if (headerLen > 65535) {
+				fail(/* @__PURE__ */ new Error(`Header too large: ${headerLen} bytes, maximum is ${MAX_HEADER_BYTES}`));
+				return out;
+			}
+			const payloadLen = source[offset + 4] << 16 | source[offset + 5] << 8 | source[offset + 6];
+			const frameLen = 7 + headerLen + payloadLen;
+			if (frameLen > protocol.maxFrameBytes) {
+				fail(/* @__PURE__ */ new Error(`Frame too large: ${frameLen} bytes, maximum is ${protocol.maxFrameBytes}`));
+				return out;
+			}
+			if (end - offset < frameLen) {
+				pendingFrameLen = frameLen;
+				break;
+			}
+			const frame = Uint8Array.prototype.slice.call(source, offset, offset + frameLen);
+			offset += frameLen;
+			try {
+				out.push(protocol.decode(frame));
+			} catch (err) {
+				fail(err instanceof Error ? err : new Error(String(err)));
+				return out;
+			}
+		}
+		retain(source, offset, end, pendingFrameLen);
+		if (length > protocol.maxFrameBytes) fail(/* @__PURE__ */ new Error(`Frame buffer exceeded ${protocol.maxFrameBytes} bytes with no complete frame`));
+		return out;
+	}
+	return {
+		push,
+		clear() {
+			buffer = /* @__PURE__ */ new Uint8Array(0);
+			length = 0;
+			error = null;
+		},
+		get error() {
+			return error;
+		}
+	};
 }
-function writeEncoded(ipc, bytes) {
-	if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") ipc.write(Buffer.from(bytes));
-	else ipc.write(bytes);
+// core/messages/frame-channel.ts
+function createFrameChannel(options) {
+	const { name, protocol, router, onMalformed } = options;
+	const decoder = createFrameDecoder(protocol);
+	const health = onMalformed.kind === "tolerate" ? new ChannelHealth(onMalformed.maxConsecutiveFailures) : null;
+	const gate = options.inbound ? createInboundGate({
+		high: options.inbound.maxPending,
+		low: Math.floor(options.inbound.maxPending / 2),
+		pause: options.inbound.pause,
+		resume: options.inbound.resume
+	}) : null;
+	let stopped = false;
+	/** Handles a malformed chunk per the channel's policy. */
+	function malformed(reason) {
+		console.error(`${name} malformed frame dropped: ${reason}`);
+		if (health === null) {
+			stopped = true;
+			decoder.clear();
+			if (onMalformed.kind === "close") onMalformed.close();
+			return;
+		}
+		if (health.noteFailure()) {
+			stopped = true;
+			console.error(`${name} channel permanently desynced after repeated malformed frames; no longer parsing it`);
+		}
+		decoder.clear();
+	}
+	function route(message) {
+		const work = router.route(message.header, message.payload).then((response) => {
+			if (response) options.write(encodeResponse(protocol, response));
+		}).catch((err) => {
+			const reason = err instanceof Error ? err.message : String(err);
+			console.error(`${name} routing failed: ${reason}`);
+		});
+		gate?.track(work);
+	}
+	return {
+		push(chunk) {
+			if (stopped) return;
+			let bytes;
+			try {
+				bytes = toBytes(chunk);
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				if (health === null) {
+					malformed(reason);
+					return;
+				}
+				console.error(`${name} non-binary chunk dropped: ${reason}`);
+				return;
+			}
+			if (bytes.byteLength === 0) return;
+			const messages = decoder.push(bytes);
+			if (decoder.error) {
+				malformed(decoder.error.message);
+				return;
+			}
+			health?.noteSuccess();
+			for (const message of messages) {
+				if (options.intercept?.(message)) continue;
+				route(message);
+			}
+		},
+		close() {
+			stopped = true;
+			decoder.clear();
+		}
+	};
 }
+// core/messages/host-ipc.ts
+/** Hard ceiling on concurrently pending host calls. Above this, the oldest call
+* is dropped (its timer cleared and promise rejected) so a flood of invokes
+* cannot grow the pending map without bound. */
+const MAX_CONCURRENT_HOST_CALLS = 1024;
+/** Sane default for a host invoke: five-minute waits let a single stalled host
+* call pin a slot indefinitely, so we default to 30s instead. */
+const DEFAULT_HOST_INVOKE_TIMEOUT_MS = 3e4;
 function createHostIpcBridge(config) {
 	const { ipc, protocol } = config;
 	const pending = /* @__PURE__ */ new Map();
+	function track(requestId, slot) {
+		if (pending.size >= MAX_CONCURRENT_HOST_CALLS) {
+			const oldest = pending.keys().next().value;
+			if (oldest !== void 0) {
+				const dropped = pending.get(oldest);
+				if (dropped) {
+					clearTimeout(dropped.timer);
+					dropped.reject(/* @__PURE__ */ new Error(`host invoke dropped: too many concurrent host calls (${oldest})`));
+				}
+				pending.delete(oldest);
+			}
+		}
+		const existing = pending.get(requestId);
+		if (existing) {
+			clearTimeout(existing.timer);
+			existing.reject(/* @__PURE__ */ new Error(`host invoke superseded by a new call (${requestId})`));
+			pending.delete(requestId);
+		}
+		pending.set(requestId, slot);
+	}
 	function waitFor(requestId, expectedType, timeoutMs) {
 		return new Promise((resolve, reject) => {
 			const timer = setTimeout(() => {
 				pending.delete(requestId);
 				reject(/* @__PURE__ */ new Error(`Host IPC timeout waiting for ${String(expectedType)} (${requestId})`));
 			}, timeoutMs);
-			pending.set(requestId, {
+			track(requestId, {
 				timer,
 				resolve: (h) => {
 					clearTimeout(timer);
@@ -50,42 +423,53 @@ function createHostIpcBridge(config) {
 						return;
 					}
 					reject(/* @__PURE__ */ new Error(`Unexpected host response type ${h.type}, expected ${String(expectedType)}`));
-				}
+				},
+				reject
 			});
 		});
 	}
+	/** Classifies a pre-decoded downstream message: resolves the matching pending
+	* host call when it is a `HOST_CAPABILITIES_RESPONSE` or `HOST_INVOKE_RESPONSE`
+	* for a known `requestId`; otherwise returns false so the caller can route the
+	* message through the plugin router (host responses never reach plugins). */
+	function consumeDownstream(parsed) {
+		const h = parsed.header;
+		if (h.type !== "HOST_CAPABILITIES_RESPONSE" && h.type !== "HOST_INVOKE_RESPONSE") return false;
+		const id = h.requestId;
+		if (!id) return false;
+		const slot = pending.get(id);
+		if (!slot) return false;
+		clearTimeout(slot.timer);
+		pending.delete(id);
+		slot.resolve(h);
+		return true;
+	}
 	return {
+		tryConsumeDownstream: consumeDownstream,
 		tryConsumeDownstreamFromHost(raw) {
 			let msg;
 			try {
-				msg = protocol.decode(toUint8Array$2(raw));
-			} catch {
+				msg = protocol.decode(toBytes(raw));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.debug(`[ipc] dropped undecodable host frame: ${message}`);
 				return false;
 			}
-			const h = msg.header;
-			if (h.type !== "HOST_CAPABILITIES_RESPONSE" && h.type !== "HOST_INVOKE_RESPONSE") return false;
-			const id = h.requestId;
-			if (!id) return false;
-			const slot = pending.get(id);
-			if (!slot) return false;
-			clearTimeout(slot.timer);
-			pending.delete(id);
-			slot.resolve(h);
-			return true;
+			return consumeDownstream(msg);
 		},
 		async queryCapabilities(timeoutMs = 5e3) {
-			const requestId = newCorrelationId();
+			const requestId = createRequestId();
 			const promise = waitFor(requestId, "HOST_CAPABILITIES_RESPONSE", timeoutMs);
 			const header = {
 				type: "HOST_CAPABILITIES_QUERY",
 				requestId
 			};
-			writeEncoded(ipc, protocol.encode(MessageType.ENVELOPE, header, null));
+			ipc.write(toIpcChunk(protocol.encode(MessageType.ENVELOPE, header, null)));
 			return (await promise).capabilities ?? [];
 		},
-		async invokeOnHost(header, payload, timeoutMs = 3e5) {
-			const requestId = header.requestId;
-			if (!requestId) return null;
+		async invokeOnHost(header, payload, timeoutMs = DEFAULT_HOST_INVOKE_TIMEOUT_MS) {
+			if (!header.requestId) return null;
+			const requestId = createRequestId();
 			const promise = waitFor(requestId, "HOST_INVOKE_RESPONSE", timeoutMs);
 			const hostHeader = {
 				type: "HOST_INVOKE_REQUEST",
@@ -94,21 +478,352 @@ function createHostIpcBridge(config) {
 				event: header.event,
 				args: header.args
 			};
-			writeEncoded(ipc, protocol.encode(MessageType.ENVELOPE, hostHeader, payload));
+			ipc.write(toIpcChunk(protocol.encode(MessageType.ENVELOPE, hostHeader, payload)));
 			const hostResp = await promise;
 			return {
 				type: "INVOKE_RESPONSE",
 				pluginId: hostResp.pluginId,
 				event: hostResp.event,
-				requestId: hostResp.requestId,
+				requestId: header.requestId,
 				result: hostResp.result,
 				error: hostResp.error
 			};
 		}
 	};
 }
-//#endregion
-//#region core/server/static-file-server.ts
+// core/logs/capture.ts
+const LEVEL_RANK = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+function safeStringify(value) {
+	if (typeof value === "string") return value;
+	if (value instanceof Error) return value.stack ?? value.message;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+function formatArgs(args) {
+	if (args.length === 0) return "";
+	return args.map((a) => safeStringify(a)).join(" ");
+}
+/**
+* Installs console interception at startup: binds the original console methods,
+* forwards to them (so dev stdout and e2e console assertions stay intact), and
+* feeds a {@link LogStore}. Every step is try/catch-wrapped so a failure in the
+* seam can never break boot or swallow the consumer's own log call.
+*/
+function installConsoleCapture(store, source = "backend", options = {}) {
+	const minRank = LEVEL_RANK[options.minLevel ?? "debug"];
+	const original = {
+		debug: console.debug,
+		log: console.log,
+		info: console.info,
+		warn: console.warn,
+		error: console.error
+	};
+	const wrap = (method, level) => {
+		const recorded = LEVEL_RANK[level] >= minRank;
+		return (...args) => {
+			if (recorded) try {
+				store.append({
+					ts: Date.now(),
+					level,
+					source,
+					message: formatArgs(args)
+				});
+			} catch {}
+			try {
+				original[method].apply(console, args);
+			} catch {}
+		};
+	};
+	console.debug = wrap("debug", "debug");
+	console.log = wrap("log", "info");
+	console.info = wrap("info", "info");
+	console.warn = wrap("warn", "warn");
+	console.error = wrap("error", "error");
+	return {
+		source,
+		store,
+		restore() {
+			console.debug = original.debug;
+			console.log = original.log;
+			console.info = original.info;
+			console.warn = original.warn;
+			console.error = original.error;
+		}
+	};
+}
+// core/server/loopback-gate.ts
+const COOKIE_PREFIX = "bare_session";
+const ORIGIN_PATTERN = /^https?:\/\/[^/?#\s]+$/;
+/** Reads the token from the `X-Bare-Token` request header (parser-lowercased).
+* `fetch`-based non-browser clients that cannot carry cookies use this. It
+* travels the cleartext loopback like the cookie, and is only trusted from an
+* allowed origin. */
+function tokenFromHeaders(headers) {
+	const value = headers["x-bare-token"];
+	return typeof value === "string" ? value : null;
+}
+/** The session cookie name for a server bound on `port`. Cookies are scoped to
+* the host, not the port, so two loopback servers sharing a browser cookie
+* store (two apps' WebViews, or two desktop backends) would overwrite each
+* other's session under one fixed name. */
+function sessionCookieName(port) {
+	return `${COOKIE_PREFIX}_${port}`;
+}
+/** Reads the `name` cookie's value from the `Cookie` request header. */
+function cookieSession(headers, name) {
+	const cookie = headers["cookie"];
+	if (typeof cookie !== "string") return null;
+	for (const part of cookie.split(";")) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+	}
+	return null;
+}
+/** Derives the cookie value from the session token so the token itself is not
+* echoed into a request header a local attacker could read back. */
+function sessionNonce(token) {
+	return crypto.createHash("blake2b-256").update(token).digest("hex");
+}
+/** Constant-time string comparison. bare-crypto's `timingSafeEqual` requires
+* equal-length inputs (it throws otherwise), so guard on byte length first. */
+function secretEquals(a, b) {
+	const ab = Buffer.from(a);
+	const bb = Buffer.from(b);
+	if (ab.length !== bb.length) return false;
+	return crypto.timingSafeEqual(ab, bb);
+}
+/** URL-safe random secret for the session token / bootstrap nonce. */
+function randomSecret() {
+	return crypto.randomBytes(32).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** `host:port` forms that name the loopback interface on `port`. `localhost`
+* cannot be pointed elsewhere by a remote DNS answer, so accepting it does not
+* reopen DNS rebinding. */
+function loopbackHosts(port) {
+	return [
+		`127.0.0.1:${port}`,
+		`localhost:${port}`,
+		`[::1]:${port}`
+	];
+}
+function createLoopbackGate(options) {
+	const { auth } = options;
+	for (const origin of options.allowedOrigins ?? []) if (!ORIGIN_PATTERN.test(origin)) throw new Error(`allowedOrigins entry is not a bare origin (scheme://host[:port]): '${origin}'`);
+	const token = options.token ?? randomSecret();
+	const cookieValue = sessionNonce(token);
+	let bootstrapNonce = randomSecret();
+	/** The most recently spent bootstrap nonce, kept only to answer replays of
+	* it with 409 (valid once but consumed) instead of 401 (bad credential). */
+	let spentBootstrapNonce = null;
+	let allowedHosts = /* @__PURE__ */ new Set();
+	let allowedOrigins = /* @__PURE__ */ new Set();
+	let cookieName = COOKIE_PREFIX;
+	function hasCredential(headers) {
+		if (!auth) return true;
+		if (secretEquals(tokenFromHeaders(headers) ?? "", token)) return true;
+		return secretEquals(cookieSession(headers, cookieName) ?? "", cookieValue);
+	}
+	/** The DNS-rebinding and cross-origin rule. `Host` must name the bound
+	* server (a rebinding page sends its own hostname). An `Origin`, when sent,
+	* must be the bound origin, a loopback alias of it, or an allowed origin.
+	* A top-level navigation (the first WebView load) sends no `Origin`. */
+	function checkOrigin(headers, requireOrigin) {
+		if (allowedHosts.size === 0) return {
+			ok: false,
+			status: 403,
+			reason: "server not bound yet"
+		};
+		const host = headers["host"];
+		if (typeof host !== "string" || !allowedHosts.has(host)) return {
+			ok: false,
+			status: 403,
+			reason: `host mismatch (got ${typeof host === "string" ? `'${host}'` : "no Host header"})`
+		};
+		const origin = headers["origin"];
+		if (typeof origin !== "string" || origin.length === 0) return requireOrigin ? {
+			ok: false,
+			status: 403,
+			reason: "no Origin header"
+		} : { ok: true };
+		if (!allowedOrigins.has(origin)) return {
+			ok: false,
+			status: 403,
+			reason: `origin mismatch (got '${origin}')`
+		};
+		return { ok: true };
+	}
+	return {
+		bind(origin) {
+			const hostPort = origin.slice(origin.indexOf("://") + 3);
+			const port = hostPort.slice(hostPort.lastIndexOf(":") + 1);
+			allowedHosts = /* @__PURE__ */ new Set([hostPort, ...loopbackHosts(port)]);
+			cookieName = sessionCookieName(port);
+			allowedOrigins = /* @__PURE__ */ new Set([
+				origin,
+				...loopbackHosts(port).map((h) => `http://${h}`),
+				...options.allowedOrigins ?? []
+			]);
+		},
+		token: () => token,
+		bootstrap: () => bootstrapNonce ?? "",
+		admitRequest(headers, resource) {
+			const origin = checkOrigin(headers, false);
+			if (!origin.ok) return origin;
+			if (resource === "gated" && !hasCredential(headers)) return {
+				ok: false,
+				status: 401,
+				reason: "unauthorized"
+			};
+			return { ok: true };
+		},
+		admitUpgrade(headers) {
+			const origin = checkOrigin(headers, auth);
+			if (!origin.ok) return origin;
+			if (!hasCredential(headers)) return {
+				ok: false,
+				status: 401,
+				reason: `unauthorized (${headers["cookie"] ? "cookie present but invalid" : `no ${cookieName} cookie`})`
+			};
+			return { ok: true };
+		},
+		login(body, headers) {
+			if (!auth) return {
+				ok: true,
+				cookie: null
+			};
+			const credential = body.trim();
+			const byBootstrap = bootstrapNonce !== null && secretEquals(credential, bootstrapNonce);
+			const bySession = hasCredential(headers);
+			if (!byBootstrap && !bySession) return {
+				ok: false,
+				status: spentBootstrapNonce !== null && secretEquals(credential, spentBootstrapNonce) ? 409 : 401
+			};
+			if (byBootstrap) {
+				spentBootstrapNonce = bootstrapNonce;
+				bootstrapNonce = null;
+			}
+			return {
+				ok: true,
+				cookie: `${cookieName}=${cookieValue}; HttpOnly; SameSite=Strict; Path=/`
+			};
+		},
+		socketSource(headers) {
+			const host = headers["host"];
+			return `ws://${typeof host === "string" ? host : ""}`;
+		}
+	};
+}
+// core/server/protocol-socket.ts
+function createProtocolSocketSlot(options) {
+	const handlers = [];
+	let active = null;
+	let activeSince = 0;
+	/** The upgrade waiting out the replacement interval. At most one waits: a
+	* newer one supersedes it, since it would have evicted it on arrival. */
+	let waiting = null;
+	function accept(req, socket, head, reject) {
+		const wait = active ? activeSince + options.replaceMinIntervalMs - Date.now() : 0;
+		if (wait > 0) {
+			if (waiting) {
+				clearTimeout(waiting.timer);
+				waiting.reject("superseded by a newer upgrade", 429);
+			}
+			waiting = {
+				socket,
+				reject,
+				timer: setTimeout(() => {
+					waiting = null;
+					accept(req, socket, head, reject);
+				}, wait)
+			};
+			socket.on("close", () => {
+				if (waiting?.socket !== socket) return;
+				clearTimeout(waiting.timer);
+				waiting = null;
+			});
+			socket.on("error", () => socket.destroy());
+			return;
+		}
+		ws.Server.handshake(req, socket, head, (err) => {
+			if (err) {
+				reject(`handshake failed (${err.message})`);
+				return;
+			}
+			const raw = new ws.Socket({
+				socket,
+				isServer: true,
+				idleTimeout: options.deadPeerTimeoutMs,
+				maxPayload: MAX_FRAME_BYTES
+			});
+			const writer = createBoundedWriter(raw, {
+				maxQueuedBytes: options.maxQueuedBytes,
+				onOverflow: () => {
+					console.error("[loopback] client is not reading and responses are backing up; closing the protocol socket");
+					raw.destroy();
+				}
+			});
+			const client = {
+				on: (event, listener) => raw.on(event, listener),
+				write: (data) => writer.write(data),
+				destroy: () => raw.destroy(),
+				pause: () => raw.pause(),
+				resume: () => raw.resume()
+			};
+			const previous = active;
+			active = {
+				client,
+				writer
+			};
+			activeSince = Date.now();
+			if (previous) {
+				console.warn("[loopback] replaced the existing protocol socket");
+				previous.client.destroy();
+			}
+			raw.on("close", () => {
+				writer.clear();
+				if (active?.client === client) active = null;
+			});
+			raw.on("error", (err) => {
+				console.warn(`[loopback] protocol socket error: ${err.message}`);
+				raw.destroy();
+			});
+			socket.setTimeout(options.idleTimeoutMs, () => raw.destroy());
+			for (const handler of handlers) try {
+				handler(client, req);
+			} catch (e) {
+				const message = e instanceof Error ? e.message : String(e);
+				console.error("Error in loopback WS connection handler:", message);
+			}
+		});
+	}
+	return {
+		accept,
+		onConnection(handler) {
+			handlers.push(handler);
+		},
+		push(frame) {
+			return active ? active.writer.write(frame, { droppable: true }) : false;
+		},
+		close() {
+			active?.client.destroy();
+			if (waiting) {
+				clearTimeout(waiting.timer);
+				waiting.socket.destroy();
+				waiting = null;
+			}
+		}
+	};
+}
+// core/server/static-file-server.ts
 const MIME_BY_EXTENSION = {
 	html: "text/html",
 	js: "text/javascript",
@@ -133,36 +848,24 @@ function mimeTypeFor(filePath) {
 	const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
 	return MIME_BY_EXTENSION[ext] ?? "application/octet-stream";
 }
-/** Extracts the `token` query param from a raw query string (`a=1&token=x`). */
-function tokenFromQuery(query) {
-	for (const pair of query.split("&")) {
-		const eq = pair.indexOf("=");
-		if (eq === -1) continue;
-		if (pair.slice(0, eq) === "token") return pair.slice(eq + 1);
-	}
-	return null;
+/** Files under `assets/` whose name ends in an 8-character content hash before
+* the extension (the Vite/Rolldown default, e.g. `assets/main-DkY3x9qZ.js`)
+* are treated as content-addressed. Anything else — including `index.html` —
+* must be revalidated. */
+const HASHED_ASSET = /^assets\/[^/]+-[A-Za-z0-9_-]{8}\.[A-Za-z0-9]+$/;
+function cachePolicyFor(rel, mountIsPublic) {
+	if (!mountIsPublic) return "no-store";
+	return HASHED_ASSET.test(rel) ? "immutable" : "revalidate";
 }
-/** Reads the token from the `X-Bare-Token` request header (parser-lowercased).
-* `fetch`-based non-browser clients that cannot carry cookies use this. */
-function tokenFromHeaders(headers) {
-	const value = headers["x-bare-token"];
-	return typeof value === "string" ? value : null;
+/** Weak validator from size and mtime. Weak because the same bytes can be
+* re-written with a new mtime, which only costs one extra full response. */
+function etagFor(stat) {
+	return `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
 }
-/** Reads the `bare_session` value from the `Cookie` request header. */
-function cookieSession(headers) {
-	const cookie = headers["cookie"];
-	if (typeof cookie !== "string") return null;
-	for (const part of cookie.split(";")) {
-		const eq = part.indexOf("=");
-		if (eq === -1) continue;
-		if (part.slice(0, eq).trim() === "bare_session") return part.slice(eq + 1).trim();
-	}
-	return null;
-}
-/** Derives the cookie value from the session token so the token itself is not
-* echoed into a request header a local attacker could read back. */
-function sessionNonce(token) {
-	return crypto.createHash("blake2b-256").update(token).digest("hex");
+/** Whether an `If-None-Match` header (a list of validators, or `*`) matches. */
+function etagMatches(header, etag) {
+	if (typeof header !== "string") return false;
+	return header.split(",").some((candidate) => candidate.trim() === etag || candidate.trim() === "*");
 }
 /** Parses a `Range: bytes=<start>-<end>` header. Returns `null` when absent or
 * unsatisfiable (caller falls back to a 200 full response). */
@@ -190,59 +893,124 @@ function parseRange(value, size) {
 * Buffers, bare-http1 emits Uint8Arrays, and a setEncoding'd stream emits
 * strings — `String(uint8array)` would join bytes with commas, so decode
 * explicitly (the `/login` token body must match byte-for-byte). */
-function collectRequestBody(req) {
-	return new Promise((resolve) => {
+function collectRequestBody(req, maxBytes = Infinity) {
+	return new Promise((resolve, reject) => {
 		const decoder = new TextDecoder();
 		let body = "";
+		let byteCount = 0;
+		let exceeded = false;
 		req.on("data", (chunk) => {
-			body += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+			if (exceeded) return;
+			const str = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+			body += str;
+			byteCount += typeof chunk === "string" ? new TextEncoder().encode(chunk).byteLength : chunk.byteLength;
+			if (byteCount > maxBytes) {
+				exceeded = true;
+				reject(/* @__PURE__ */ new Error("Request body too large"));
+			}
+		});
+		req.on("end", () => {
+			if (exceeded) return;
+			const final = body + decoder.decode(/* @__PURE__ */ new Uint8Array(0));
+			if (byteCount > maxBytes) {
+				reject(/* @__PURE__ */ new Error("Request body too large"));
+				return;
+			}
+			resolve(final);
 		});
-		req.on("end", () => resolve(body + decoder.decode(/* @__PURE__ */ new Uint8Array(0))));
 	});
 }
+/** Splits a request target into its decoded path segments, or null when the
+* path cannot name a file inside a mount: a malformed escape, or a segment
+* that is `.`/`..` or carries a separator or NUL once decoded (`%2e%2e`,
+* `%2f`, `\`). Empty segments (`//`, a trailing `/`) are dropped. */
+function pathSegments(target) {
+	const rawPath = target.split(/[?#]/, 1)[0];
+	const segments = [];
+	for (const raw of rawPath.split("/")) {
+		if (raw === "") continue;
+		let segment;
+		try {
+			segment = decodeURIComponent(raw);
+		} catch {
+			return null;
+		}
+		if (segment === "." || segment === ".." || /[/\\\0]/.test(segment)) return null;
+		segments.push(segment);
+	}
+	return segments;
+}
+/** The key a mount path is stored under: the same decoded, normalized form a
+* request path is matched in, so `/media/a%20b` and `/media/a b/` name one
+* mount. A path no request could ever match is a programming error. */
+function mountKey(mountPath) {
+	const segments = pathSegments(mountPath);
+	if (segments === null) throw new Error(`invalid mount path: '${mountPath}'`);
+	return `/${segments.join("/")}`;
+}
+/** Whether a bind address names the loopback interface only. */
+function isLoopbackHost(host) {
+	return host === "localhost" || host === "::1" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host);
+}
+/** Whether `candidate` is `root` or lies below it. Both must be absolute,
+* normalized paths. */
+function isWithin(root, candidate) {
+	const rel = path.relative(root, candidate);
+	return rel === "" || rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
 /**
 * The single loopback HTTP+WS server for the worklet. One origin serves the
 * web app (`/`), the media files mounted by plugins, and the framed-protocol
 * WebSocket socket the page connects to. On device it binds `127.0.0.1` on an
-* ephemeral port. The bundled web app (directory mounts) is public content — a
-* fresh WebView must load the page before the page can `POST /login`. Mounted
-* session files (media) and the WS upgrade are gated by a per-session token,
-* accepted as a `bare_session` cookie (set via `POST /login`), the
-* `X-Bare-Token` header, or a `?token=` query param — defense in depth for
-* non-browser clients. All responses send `Referrer-Policy: no-referrer` so
-* token-bearing URLs never leak through a Referer header.
+* ephemeral port. Admission (origin rule, session credential, bootstrap login)
+* is decided by the loopback gate (`loopback-gate.ts`); the protocol socket's
+* lifecycle by the protocol socket slot (`protocol-socket.ts`). All responses
+* send `Referrer-Policy: no-referrer`.
 */
 function createLoopbackServer(options = {}) {
 	const host = options.host ?? "127.0.0.1";
 	const port = options.port ?? 0;
-	const authEnabled = options.auth ?? true;
-	const wsIdleTimeoutMs = options.wsIdleTimeoutMs ?? 6e4;
+	const auth = options.auth ?? true;
+	if (!auth && !isLoopbackHost(host)) throw new Error(`refusing to bind '${host}' with auth off: only a loopback address may serve without a credential`);
+	const gate = createLoopbackGate({
+		auth,
+		token: options.token,
+		allowedOrigins: options.allowedOrigins
+	});
+	const slot = createProtocolSocketSlot({
+		idleTimeoutMs: options.wsIdleTimeoutMs ?? 6e4,
+		deadPeerTimeoutMs: options.wsDeadPeerTimeoutMs ?? 1e4,
+		replaceMinIntervalMs: options.wsReplaceMinIntervalMs ?? 1e3,
+		maxQueuedBytes: options.wsMaxQueuedBytes ?? 2097152
+	});
 	const fileMounts = /* @__PURE__ */ new Map();
 	const dirMounts = /* @__PURE__ */ new Map();
+	const publicDirMounts = /* @__PURE__ */ new Set();
 	const routeHandlers = /* @__PURE__ */ new Map();
-	const connectionHandlers = [];
-	let token = options.token ?? null;
-	let boundOrigin = "";
 	let originPromise = null;
-	let activeSocket = null;
-	function isAuthorized(headers, query) {
-		if (!authEnabled) return true;
-		if (token === null) return false;
-		if (tokenFromQuery(query) === token) return true;
-		if (tokenFromHeaders(headers) === token) return true;
-		return cookieSession(headers) === sessionNonce(token);
-	}
 	function writeError(res, status, message) {
+		if (res.headersSent) {
+			res.destroy();
+			return;
+		}
 		res.writeHead(status, {
 			"Content-Type": "text/plain",
 			"Referrer-Policy": "no-referrer"
 		});
 		res.end(message);
 	}
+	/** Logs the cause and answers a bare 500: an exception message can carry
+	* file paths or plugin internals, which never belong in a response body. */
+	function writeInternalError(res, context, err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(`[loopback] ${context} failed: ${message}`);
+		writeError(res, 500, "Internal Server Error");
+	}
 	function handleLogin(req, res) {
-		collectRequestBody(req).then((body) => {
-			if (!(!authEnabled || token !== null && body.trim() === token)) {
-				writeError(res, 401, "Unauthorized");
+		collectRequestBody(req, 4096).then((body) => {
+			const verdict = gate.login(body, req.headers);
+			if (!verdict.ok) {
+				writeError(res, verdict.status, "Unauthorized");
 				return;
 			}
 			const headers = {
@@ -250,66 +1018,110 @@ function createLoopbackServer(options = {}) {
 				"Cache-Control": "no-store",
 				"Referrer-Policy": "no-referrer"
 			};
-			if (authEnabled && token !== null) headers["Set-Cookie"] = `bare_session=${sessionNonce(token)}; HttpOnly; SameSite=Lax; Path=/`;
+			if (verdict.cookie !== null) headers["Set-Cookie"] = verdict.cookie;
 			res.writeHead(200, headers);
 			res.end("ok");
-		});
+		}, () => writeError(res, 413, "Request Entity Too Large")).catch((err) => writeInternalError(res, "POST /login", err));
 	}
-	/** Resolves a request path to a file mount, or a directory mount + relative
-	* path. Directory mounts win on longest-prefix match. */
-	function resolveMount(cleanPath) {
+	/** Resolves a request path to a file mount, or a directory mount + the path
+	* segments below it. Directory mounts win on longest-prefix match. */
+	function resolveMount(cleanPath, segments) {
 		const fileMount = fileMounts.get(cleanPath);
 		if (fileMount) return {
 			kind: "file",
 			filePath: fileMount
 		};
 		let best = null;
-		let bestPrefix = -1;
+		let bestDepth = -1;
 		for (const [prefix, dirPath] of dirMounts) {
-			let rel;
-			if (cleanPath === prefix) rel = "";
-			else if (prefix === "/") rel = cleanPath.replace(/^\/+/, "");
-			else if (cleanPath.startsWith(`${prefix}/`)) rel = cleanPath.slice(prefix.length + 1);
-			else continue;
-			if (prefix.length > bestPrefix) {
-				best = {
-					dirPath,
-					rel
-				};
-				bestPrefix = prefix.length;
-			}
+			const prefixSegments = prefix.split("/").filter((s) => s !== "");
+			const depth = prefixSegments.length;
+			if (depth <= bestDepth) continue;
+			if (!prefixSegments.every((s, i) => segments[i] === s)) continue;
+			best = {
+				dirPath,
+				rel: segments.slice(depth),
+				public: publicDirMounts.has(prefix)
+			};
+			bestDepth = depth;
 		}
 		return best ? {
-			kind: "dir",
-			dirPath: best.dirPath,
-			rel: best.rel
+			...best,
+			kind: "dir"
 		} : null;
 	}
-	/** Resolves a directory-mount request to a concrete file, applying the SPA
-	* fallback (unknown GET navigation → `index.html`). Subresource requests
-	* (`Accept` without `text/html`) never fall back — a missing asset is a 404. */
+	/** Resolves a directory-mount request to a concrete file inside the mount
+	* root (its real path, so a symlink cannot lead outside it). Only a
+	* `public` (bootstrap) mount applies the SPA fallback (unknown navigation
+	* GET → `index.html`); a non-public directory mount 404s unknown paths so
+	* unauthenticated clients never receive bootstrap HTML. Subresource requests
+	* (`Accept` without `text/html`) never fall back — a missing asset is a
+	* 404. */
 	function resolveDirFile(mount, headers) {
-		const candidate = mount.rel === "" ? mount.dirPath : path.join(mount.dirPath, mount.rel);
+		let root;
 		try {
-			if (fs.statSync(candidate).isFile()) return candidate;
-		} catch {}
-		if (mount.rel === "") return indexHtmlIfPresent(mount.dirPath);
-		const accept = headers["accept"];
-		if (typeof accept !== "string" || !accept.includes("text/html")) return null;
-		return indexHtmlIfPresent(mount.dirPath);
-	}
-	function indexHtmlIfPresent(dirPath) {
+			root = fs.realpathSync(mount.dirPath);
+		} catch {
+			console.debug(`[static-server] mount root ${mount.dirPath} is missing — 404`);
+			return null;
+		}
+		const served = (file) => file && {
+			...file,
+			rel: path.relative(root, file.filePath).split(path.sep).join("/")
+		};
+		if (mount.rel.length > 0) {
+			const found = fileWithin(root, path.join(root, ...mount.rel));
+			if (found) return served(found);
+			if (!mount.public) return null;
+			const accept = headers["accept"];
+			if (typeof accept !== "string" || !accept.includes("text/html")) return null;
+		}
+		return served(fileWithin(root, path.join(root, "index.html")));
+	}
+	/** `candidate` as a served file when it exists, is a regular file, and its
+	* real path stays inside `root`. A missing file is routine (every SPA route,
+	* every missing asset), so it is not logged. */
+	function fileWithin(root, candidate) {
+		let real;
+		try {
+			real = fs.realpathSync(candidate);
+		} catch {
+			return null;
+		}
+		if (!isWithin(root, real)) {
+			console.warn(`[static-server] refused a path that resolves outside its mount: ${candidate}`);
+			return null;
+		}
 		try {
-			const index = path.join(dirPath, "index.html");
-			if (fs.statSync(index).isFile()) return index;
-		} catch {}
-		return null;
+			const stat = fs.statSync(real);
+			return stat.isFile() ? {
+				filePath: real,
+				stat
+			} : null;
+		} catch {
+			return null;
+		}
+	}
+	/** Strict Content-Security-Policy for HTML documents served by the loopback
+	* server. Subresources stay same-origin; `connect-src` names the one
+	* protocol socket the page may open (`ws:` alone would allow any host).
+	* `style-src` needs `'unsafe-inline'` for the bundled web app's inline
+	* styles. */
+	function cspFor(socketSource) {
+		return `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${socketSource}; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'`;
 	}
-	function serveFile(req, res, filePath) {
+	/** Policy for mounted session files (media). They are loaded by `<img>` and
+	* `<video>`, where a response CSP has no effect; it only bites when one is
+	* opened as a document, so a hostile file (an SVG with script) runs in an
+	* opaque, script-less sandbox instead of the app origin. */
+	const MOUNTED_FILE_CSP = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
+	function serveFile(req, res, filePath, knownStat, cache = "no-store", sandboxed = false) {
 		let stat;
-		try {
+		if (knownStat) stat = knownStat;
+		else try {
 			stat = fs.statSync(filePath);
 		} catch {
+			console.debug(`[static-server] serveFile: stat failed for ${filePath} — 404`);
 			writeError(res, 404, "Not found");
 			return;
 		}
@@ -317,14 +1129,19 @@ function createLoopbackServer(options = {}) {
 			writeError(res, 404, "Not found");
 			return;
 		}
+		const contentType = mimeTypeFor(filePath);
+		const cspHeader = {
+			"X-Content-Type-Options": "nosniff",
+			...sandboxed ? { "Content-Security-Policy": MOUNTED_FILE_CSP } : contentType === "text/html" ? { "Content-Security-Policy": cspFor(gate.socketSource(req.headers)) } : {}
+		};
 		const range = parseRange(req.headers["range"], stat.size);
 		if (range) {
 			res.writeHead(206, {
-				"Content-Type": mimeTypeFor(filePath),
+				"Content-Type": contentType,
 				"Content-Range": `bytes ${range.start}-${range.end}/${stat.size}`,
 				"Content-Length": range.end - range.start + 1,
 				"Accept-Ranges": "bytes",
-				"Access-Control-Allow-Origin": "*",
+				...cspHeader,
 				"Referrer-Policy": "no-referrer",
 				"Cache-Control": "no-store"
 			});
@@ -332,13 +1149,25 @@ function createLoopbackServer(options = {}) {
 			pipeFile(res, filePath, range);
 			return;
 		}
+		const cacheHeaders = cache === "no-store" ? { "Cache-Control": "no-store" } : {
+			"Cache-Control": cache === "immutable" ? "max-age=31536000, immutable" : "no-cache",
+			ETag: etagFor(stat)
+		};
+		if (cache !== "no-store" && etagMatches(req.headers["if-none-match"], cacheHeaders.ETag)) {
+			res.writeHead(304, {
+				...cacheHeaders,
+				"Referrer-Policy": "no-referrer"
+			});
+			res.end();
+			return;
+		}
 		res.writeHead(200, {
-			"Content-Type": mimeTypeFor(filePath),
+			"Content-Type": contentType,
 			"Content-Length": stat.size,
 			"Accept-Ranges": "bytes",
-			"Access-Control-Allow-Origin": "*",
+			...cspHeader,
 			"Referrer-Policy": "no-referrer",
-			"Cache-Control": "no-store"
+			...cacheHeaders
 		});
 		res.flushHeaders();
 		pipeFile(res, filePath);
@@ -363,98 +1192,98 @@ function createLoopbackServer(options = {}) {
 		});
 		stream.pipe(res);
 	}
-	const server = http.createServer((req, res) => {
-		try {
-			const [rawPath, query = ""] = (req.url ?? "/").split("?");
-			const cleanPath = rawPath.split("#")[0].replace(/\/+$/, "") || "/";
-			const headers = req.headers;
-			if (req.method === "POST" && cleanPath === "/login") {
-				handleLogin(req, res);
-				return;
-			}
-			if (cleanPath.split("/").includes("..")) {
-				writeError(res, 400, "Bad request");
-				return;
-			}
-			const route = routeHandlers.get(`${req.method} ${cleanPath}`);
-			if (route) {
-				if (!isAuthorized(headers, query)) {
-					writeError(res, 401, "Unauthorized");
-					return;
-				}
-				try {
-					route(req, res);
-				} catch (err) {
-					writeError(res, 500, err instanceof Error ? err.message : String(err));
-				}
+	function handleRequest(req, res) {
+		const headers = req.headers;
+		const segments = pathSegments(req.url ?? "/");
+		if (segments === null) {
+			writeError(res, 400, "Bad request");
+			return;
+		}
+		const cleanPath = `/${segments.join("/")}`;
+		if (req.method === "POST" && cleanPath === "/login") {
+			const verdict = gate.admitRequest(headers, "public");
+			if (!verdict.ok) {
+				writeError(res, verdict.status, "Forbidden");
 				return;
 			}
-			const mount = resolveMount(cleanPath);
-			if (!(mount !== null && mount.kind === "dir") && !isAuthorized(headers, query)) {
-				writeError(res, 401, "Unauthorized");
+			handleLogin(req, res);
+			return;
+		}
+		const route = routeHandlers.get(`${req.method} ${cleanPath}`);
+		if (route) {
+			const verdict = gate.admitRequest(headers, "gated");
+			if (!verdict.ok) {
+				writeError(res, verdict.status, verdict.status === 401 ? "Unauthorized" : "Forbidden");
 				return;
 			}
-			const filePath = mount === null ? null : mount.kind === "file" ? mount.filePath : resolveDirFile(mount, headers);
-			if (filePath === null) {
-				writeError(res, 404, "Not found");
-				return;
+			try {
+				route(req, res);
+			} catch (err) {
+				writeInternalError(res, `route ${req.method} ${cleanPath}`, err);
 			}
-			serveFile(req, res, filePath);
+			return;
+		}
+		const mount = resolveMount(cleanPath, segments);
+		const verdict = gate.admitRequest(headers, mount !== null && mount.kind === "dir" && mount.public ? "public" : "gated");
+		if (!verdict.ok) {
+			writeError(res, verdict.status, verdict.status === 401 ? "Unauthorized" : "Forbidden");
+			return;
+		}
+		if (mount === null) {
+			writeError(res, 404, "Not found");
+			return;
+		}
+		if (mount.kind === "file") {
+			serveFile(req, res, mount.filePath, void 0, "no-store", true);
+			return;
+		}
+		const resolved = resolveDirFile(mount, headers);
+		if (resolved === null) {
+			writeError(res, 404, "Not found");
+			return;
+		}
+		serveFile(req, res, resolved.filePath, resolved.stat, cachePolicyFor(resolved.rel, mount.public), !mount.public);
+	}
+	const server = http.createServer((req, res) => {
+		try {
+			handleRequest(req, res);
 		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			res.writeHead(500, { "Content-Type": "text/plain" });
-			res.end(message);
+			writeInternalError(res, `${req.method} request`, err);
 		}
 	});
 	function origin() {
 		if (!originPromise) originPromise = new Promise((resolve, reject) => {
-			token ??= crypto.randomBytes(32).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 			server.on("error", reject);
 			server.listen(port, host, () => {
 				const address = server.address();
-				boundOrigin = `http://${host}:${address.port}`;
-				resolve(boundOrigin);
+				const bound = `http://${host}:${address?.port}`;
+				gate.bind(bound);
+				resolve(bound);
 			});
 		});
 		return originPromise;
 	}
 	server.on("upgrade", (req, socket, head) => {
-		const headers = req.headers;
-		const [, query = ""] = (req.url ?? "").split("?");
-		const origin = headers["origin"];
-		if (authEnabled && typeof origin === "string" && origin.length > 0 && boundOrigin !== "" && origin !== boundOrigin) {
-			socket.destroy();
-			return;
-		}
-		if (!isAuthorized(headers, query)) {
-			socket.destroy();
-			return;
-		}
-		if (activeSocket) {
-			socket.destroy();
-			return;
-		}
-		ws.Server.handshake(req, socket, head, (err) => {
-			if (err) {
-				socket.destroy(err);
+		const reject = (reason, status) => {
+			console.error(`[loopback] upgrade rejected: ${reason}`);
+			if (status === void 0) {
+				socket.destroy();
 				return;
 			}
-			const client = new ws.Socket({
-				socket,
-				isServer: true
-			});
-			activeSocket = client;
-			client.on("close", () => {
-				if (activeSocket === client) activeSocket = null;
-			});
-			socket.setTimeout(wsIdleTimeoutMs, () => client.destroy());
-			for (const handler of connectionHandlers) try {
-				handler(client, req);
-			} catch (e) {
-				const message = e instanceof Error ? e.message : String(e);
-				console.error("Error in loopback WS connection handler:", message);
-			}
-		});
+			socket.on("finish", () => socket.destroy());
+			socket.on("error", () => socket.destroy());
+			socket.end(`HTTP/1.1 ${status} ${http.STATUS_CODES[status]}\r\nConnection: close\r
+Content-Length: 0\r
+Referrer-Policy: no-referrer\r
+\r
+`);
+		};
+		const verdict = gate.admitUpgrade(req.headers);
+		if (!verdict.ok) {
+			reject(verdict.reason, verdict.status);
+			return;
+		}
+		slot.accept(req, socket, head, reject);
 	});
 	async function url(path) {
 		return `${await origin()}${path}`;
@@ -462,56 +1291,187 @@ function createLoopbackServer(options = {}) {
 	return {
 		origin,
 		url,
-		token() {
-			return token ?? "";
-		},
+		token: () => gate.token(),
 		async credentials() {
 			const originUrl = await origin();
 			return {
 				origin: originUrl,
 				port: Number(originUrl.slice(originUrl.lastIndexOf(":") + 1)),
-				token
+				token: gate.token(),
+				bootstrap: gate.bootstrap()
 			};
 		},
 		mount(path, filePath) {
-			fileMounts.set(path, filePath);
+			fileMounts.set(mountKey(path), filePath);
 		},
 		unmount(path) {
-			fileMounts.delete(path);
+			fileMounts.delete(mountKey(path));
 		},
-		mountDir(prefix, dirPath) {
-			dirMounts.set(prefix, dirPath);
-		},
-		onConnection(handler) {
-			connectionHandlers.push(handler);
+		mountDir(prefix, dirPath, opts) {
+			const key = mountKey(prefix);
+			dirMounts.set(key, dirPath);
+			if (opts?.public) publicDirMounts.add(key);
+			else publicDirMounts.delete(key);
 		},
+		onConnection: (handler) => slot.onConnection(handler),
 		registerRoute(method, path, handler) {
 			routeHandlers.set(`${method.toUpperCase()} ${path}`, handler);
 		},
-		push(frame) {
-			if (!activeSocket) return false;
-			try {
-				activeSocket.write(frame);
-				return true;
-			} catch {
-				return false;
-			}
-		},
+		push: (frame) => slot.push(frame),
 		close(cb) {
-			if (activeSocket) try {
-				activeSocket.destroy();
-			} catch {}
+			slot.close();
 			server.close(cb);
 		}
 	};
 }
-//#endregion
-//#region core/server/websocket-server.ts
-function toUint8Array$1(data) {
-	if (data instanceof Uint8Array) return data;
-	if (data instanceof ArrayBuffer) return new Uint8Array(data);
-	throw new Error("Expected Uint8Array or ArrayBuffer from socket data");
+// core/logs/routes.ts
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/** Parses the query string, or returns null when an escape is malformed. */
+function queryParams(url) {
+	const out = {};
+	const query = (url ?? "").split("?")[1];
+	if (!query) return out;
+	for (const pair of query.split("&")) {
+		const eq = pair.indexOf("=");
+		if (eq === -1) continue;
+		try {
+			out[decodeURIComponent(pair.slice(0, eq))] = decodeURIComponent(pair.slice(eq + 1));
+		} catch {
+			return null;
+		}
+	}
+	return out;
+}
+function isLogLevel(value) {
+	return LOG_LEVELS.includes(value);
+}
+/** Longest ingested message and tag, in UTF-16 code units. The ring holds a
+* fixed number of entries, so this is what bounds its memory: without it a
+* page could pin capacity × 1 MiB in the worklet. */
+const MAX_INGEST_MESSAGE_CHARS = 8192;
+function truncate(value, max) {
+	return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+/** One entry per line: a line break inside a message would let a page write a
+* line that reads as a backend diagnostic. */
+function oneLine(value) {
+	return value.replace(/\\/g, "\\\\").replace(/\r/g, "\\r").replace(/\n/g, "\\n");
 }
+function formatText(e) {
+	const tag = e.tag ? `[${oneLine(e.tag)}] ` : "";
+	return `[${new Date(e.ts).toISOString()}] ${e.level.toUpperCase()} ${e.source} ${tag}${oneLine(e.message)}`;
+}
+/** Registers the loopback log routes on the unified server. They inherit the
+* server's auth gate and single-server rule for free:
+*
+* - `GET /logs?tail=&level=&source=&format=jsonl|text` — bulk read-back,
+*   deliberately off the framed invoke so there is no `MAX_HEADER_BYTES`
+*   ceiling.
+* - `POST /logs` — ingest for web/browser log batches (`{ source, entries }`).
+*/
+function registerLogRoutes(server, store) {
+	server.registerRoute("GET", "/logs", (req, res) => {
+		const params = queryParams(req.url);
+		if (params === null) {
+			res.writeHead(400, {
+				"Content-Type": "text/plain",
+				"Referrer-Policy": "no-referrer"
+			});
+			res.end("Bad request");
+			return;
+		}
+		const tail = params.tail === void 0 ? void 0 : Number(params.tail);
+		const level = isLogLevel(params.level) ? params.level : void 0;
+		const source = params.source === "web" || params.source === "backend" ? params.source : void 0;
+		const entries = store.view({
+			tail: tail !== void 0 && Number.isFinite(tail) ? tail : void 0,
+			level,
+			source
+		});
+		const format = params.format === "jsonl" ? "jsonl" : "text";
+		res.writeHead(200, {
+			"Content-Type": format === "jsonl" ? "application/x-ndjson" : "text/plain",
+			"Referrer-Policy": "no-referrer",
+			"Cache-Control": "no-store"
+		});
+		if (format === "jsonl") {
+			const lines = entries.map((e) => JSON.stringify(e)).join("\n");
+			res.end(lines.length > 0 ? `${lines}\n` : "");
+		} else {
+			const lines = entries.map(formatText).join("\n");
+			res.end(lines.length > 0 ? `${lines}\n` : "");
+		}
+	});
+	server.registerRoute("POST", "/logs", (req, res) => {
+		collectRequestBody(req, 1048576).then((body) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(body);
+			} catch {
+				parsed = null;
+			}
+			if (typeof parsed !== "object" || parsed === null) {
+				res.writeHead(400, {
+					"Content-Type": "text/plain",
+					"Referrer-Policy": "no-referrer"
+				});
+				res.end("Bad request");
+				return;
+			}
+			const source = "web";
+			const entries = parsed.entries;
+			const batch = Array.isArray(entries) ? entries : [];
+			let accepted = 0;
+			for (const item of batch) {
+				if (typeof item !== "object" || item === null) continue;
+				const raw = item;
+				if (typeof raw.message !== "string") continue;
+				store.append({
+					ts: Date.now(),
+					level: isLogLevel(raw.level) ? raw.level : "info",
+					source,
+					tag: typeof raw.tag === "string" ? truncate(raw.tag, 64) : void 0,
+					message: truncate(raw.message, MAX_INGEST_MESSAGE_CHARS)
+				});
+				accepted++;
+			}
+			res.writeHead(200, {
+				"Content-Type": "application/json",
+				"Referrer-Policy": "no-referrer",
+				"Cache-Control": "no-store"
+			});
+			res.end(JSON.stringify({ accepted }));
+		}, (err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error("Discarding oversized /logs batch:", message);
+			res.writeHead(413, {
+				"Content-Type": "text/plain",
+				"Referrer-Policy": "no-referrer"
+			});
+			res.end("Request Entity Too Large");
+		}).catch((err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(`[loopback] POST /logs failed: ${message}`);
+			if (res.headersSent) {
+				res.destroy();
+				return;
+			}
+			res.writeHead(500, {
+				"Content-Type": "text/plain",
+				"Referrer-Policy": "no-referrer"
+			});
+			res.end("Internal Server Error");
+		});
+	});
+}
+// core/server/websocket-server.ts
+/** Routed calls pending on one socket before it stops being read. */
+const MAX_PENDING_ROUTES = 32;
 /** Builds the push seam for the server's connected protocol socket: encodes a
 * `DISPATCH`-style envelope and writes it, mirroring how `attachWebSocketProtocol`
 * writes responses. Returns false when no socket is connected. */
@@ -524,40 +1484,49 @@ function createLoopbackPush(server, protocol) {
 /**
 * Attaches the framed-protocol socket to the unified loopback server. The
 * server owns the WebSocket upgrade (origin check, cookie/token auth, single
-* client, idle timeout); this layer only routes decoded envelopes through the
-* plugin router and writes responses back as raw frames.
+* client, idle timeout); this layer runs one frame channel per socket. A peer
+* that sends a malformed frame is not recoverable on that socket, so it is
+* torn down and the client reconnects.
 */
 function attachWebSocketProtocol(server, context) {
 	const { protocol, pluginRouter } = context;
-	server.onConnection((socket, _request) => {
-		socket.on("data", async (raw) => {
-			try {
-				const data = toUint8Array$1(raw);
-				if (data.byteLength === 0) return;
-				const parsed = protocol.decode(data);
-				const header = parsed.header;
-				const pluginResponse = await pluginRouter.route(header, parsed.payload);
-				if (pluginResponse) socket.write(protocol.encode(MessageType.ENVELOPE, pluginResponse, null));
-			} catch (err) {
-				const message = err instanceof Error ? err.message : String(err);
-				console.error("Error handling WebSocket message:", message);
+	server.onConnection((socket) => {
+		const channel = createFrameChannel({
+			name: "[ws]",
+			protocol,
+			router: pluginRouter,
+			write: (frame) => socket.write(frame),
+			onMalformed: {
+				kind: "close",
+				close: () => socket.destroy()
+			},
+			inbound: {
+				maxPending: MAX_PENDING_ROUTES,
+				pause: () => socket.pause?.(),
+				resume: () => socket.resume?.()
 			}
 		});
+		socket.on("data", (chunk) => channel.push(chunk));
+		socket.on("close", () => channel.close());
+		socket.on("error", (err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error("[ws] connection error:", message);
+			channel.close();
+			socket.destroy();
+		});
 	});
 }
-//#endregion
-//#region core/runtime.ts
+// core/runtime.ts
 function readBareArgv() {
 	return typeof Bare !== "undefined" && Array.isArray(Bare.argv) ? Bare.argv : [];
 }
 /** Resolves the host-provided worklet configuration from `start(...)`
 * arguments. On-device hosts pass `["<webAssets>", "<storage>", "<cache>"]`
-* (three existing directories, in that order), landing at `Bare.argv[0..2]`;
-* the Bare CLI (dev) passes the binary and the script path instead, so a
-* missing/absent config means dev mode (auth off, fixed port, no handoff
-* file). Falls back to the labeled CLI token syntax (see `resolveCliConfig`)
-* when the positional shape doesn't match, so the same entry works for both
-* device and dev runs. */
+* (three existing directories, in that order), landing at `Bare.argv[0..2]`.
+* Falls back to the labeled CLI token syntax (see `resolveCliConfig`) when the
+* positional shape doesn't match, so the same entry works for device and dev
+* runs. Nothing here turns auth off: the dev backend is selected only by an
+* explicit `mode=dev` token. */
 function resolveWorkletConfig() {
 	const argv = readBareArgv();
 	const webAssets = argv[0];
@@ -574,23 +1543,28 @@ function resolveWorkletConfig() {
 				cache: cacheDir
 			};
 		}
-	} catch {}
+	} catch (err) {
+		console.debug(`[runtime] config dir check failed; not a device configuration: ` + (err instanceof Error ? err.message : String(err)));
+	}
 	return resolveCliConfig(argv);
 }
 /**
-* Parses the dev/CLI labeled-token configuration from bare CLI arguments:
-* `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`, `host=<addr>`,
-* `port=<n>`, `auth=<on|off|true|false|1|0>` — a single `key=value` separator.
-* Unknown labels (e.g. `bootstrap=127.0.0.1:49737`) are ignored and stay
-* consumer-owned.
+* Parses labeled-token configuration from bare CLI arguments, one `key=value`
+* per token: `webassets=<dir>`, `storage=<dir>`, `cache=<dir>`,
+* `host=<addr>`, `port=<n>`, `auth=<on|off|true|false|1|0>`,
+* `mode=<device|dev>` and `origin=<scheme://host[:port]>` (repeatable; an
+* extra allowed page origin, e.g. the Vite dev server). Unknown labels (e.g.
+* `bootstrap=127.0.0.1:49737`) are ignored and stay consumer-owned.
 *
-* Returns the equivalent `WorkletRuntimeOptions` in **dev mode**: `deviceMode:
-* false` (so a `storage=` token does not flip auth on or make the port
-* ephemeral), `auth: false`, `port: 8080`, each overridable by a token. When
-* no labeled tokens are present it returns `{}` (plain dev defaults).
+* Without `mode=dev` the result keeps the secure device defaults (auth on, an
+* ephemeral port), and `auth=off` is ignored with a warning. `mode=dev` selects the dev backend: `deviceMode: false`,
+* `auth: false`, `port: 8080`, each overridable by a token. Returns `{}` when
+* no labeled tokens are present.
 */
 function resolveCliConfig(argv = readBareArgv()) {
 	const parsed = {};
+	const allowedOrigins = [];
+	let dev = false;
 	let matched = false;
 	for (const token of argv) {
 		const m = /^([A-Za-z][A-Za-z0-9]*)=(.*)$/.exec(token);
@@ -612,29 +1586,33 @@ function resolveCliConfig(argv = readBareArgv()) {
 				break;
 			case "port": {
 				const n = Number(value);
-				if (Number.isInteger(n) && n >= 0 && n <= 65535) parsed.port = n;
+				if (value !== "" && Number.isInteger(n) && n >= 0 && n <= 65535) parsed.port = n;
 				else console.warn(`[bare] ignoring invalid port= token: "${value}"`);
 				break;
 			}
-			case "auth": parsed.auth = value !== "off" && value !== "false" && value !== "0";
+			case "auth":
+				parsed.auth = value !== "off" && value !== "false" && value !== "0";
+				break;
+			case "mode":
+				if (value === "dev") dev = true;
+				else if (value !== "device") console.warn(`[bare] ignoring unknown mode= token: "${value}" (expected device or dev)`);
+				break;
+			case "origin": allowedOrigins.push(value);
 		}
 	}
 	if (!matched) return {};
-	return {
+	if (allowedOrigins.length > 0) parsed.allowedOrigins = allowedOrigins;
+	if (dev) return {
 		deviceMode: false,
 		auth: false,
 		port: 8080,
 		...parsed
 	};
-}
-function toUint8Array(data) {
-	if (data instanceof Uint8Array) return data;
-	if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) return new Uint8Array(data);
-	return new Uint8Array(data);
-}
-function writeIpc(ipc, bytes) {
-	if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") ipc.write(Buffer.from(bytes));
-	else ipc.write(bytes);
+	if (parsed.auth === false) {
+		console.warn("[bare] ignoring auth=off without mode=dev");
+		delete parsed.auth;
+	}
+	return parsed;
 }
 /**
 * Creates one worklet runtime — a per-instance, stateless factory (no
@@ -643,67 +1621,80 @@ function writeIpc(ipc, bytes) {
 * wire p2p". Mirrors the reference wiring in `core/main.core.ts`.
 */
 function createWorkletRuntime(options = {}) {
-	const deviceMode = options.deviceMode ?? options.storage !== void 0;
+	const deviceMode = options.deviceMode ?? true;
 	const auth = options.auth ?? deviceMode;
 	const port = options.port ?? (deviceMode ? 0 : 8080);
-	const protocol = new MessageProtocol({
-		encode: (str) => new TextEncoder().encode(str),
-		decode: (bytes) => new TextDecoder().decode(bytes)
-	});
-	let ipc;
-	try {
-		ipc = getIPC();
-	} catch {
-		ipc = void 0;
-	}
-	const hostBridge = ipc ? createHostIpcBridge({
-		ipc,
-		protocol
-	}) : null;
-	const pluginRegistry = createPluginRegistry();
+	const ipc = getIPC();
+	if (!ipc) console.debug("[runtime] no host IPC channel available, running without a host");
 	const server = createLoopbackServer({
 		host: options.host,
 		port,
 		auth,
-		wsIdleTimeoutMs: options.wsIdleTimeoutMs
+		allowedOrigins: options.allowedOrigins,
+		wsIdleTimeoutMs: options.wsIdleTimeoutMs,
+		wsDeadPeerTimeoutMs: options.wsDeadPeerTimeoutMs,
+		wsReplaceMinIntervalMs: options.wsReplaceMinIntervalMs,
+		wsMaxQueuedBytes: options.wsMaxQueuedBytes
 	});
+	let hostBridge = null;
+	const { protocol, pluginRegistry, pluginRouter } = createBareRuntimeContext([], {
+		maxInflight: options.maxInflight,
+		serialPlugins: options.serialPlugins,
+		delegateToHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null),
+		getHostCapabilities: () => hostBridge?.queryCapabilities() ?? Promise.resolve([])
+	});
+	hostBridge = ipc ? createHostIpcBridge({
+		ipc,
+		protocol
+	}) : null;
+	const logStore = createLogRingBuffer(options.logsCapacity ?? 500);
+	installConsoleCapture(logStore, "backend", { minLevel: options.logsMinLevel });
+	registerLogRoutes(server, logStore);
 	for (const plugin of createDefaultPlugins({
 		listBareCapabilities: () => pluginRegistry.listCapabilities(),
 		queryHostCapabilities: () => hostBridge?.queryCapabilities() ?? Promise.resolve([]),
 		staticServer: server,
-		invokeOnHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null)
+		invokeOnHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null),
+		store: logStore
 	})) pluginRegistry.register(plugin);
 	for (const plugin of options.plugins ?? []) pluginRegistry.register(plugin);
-	const pluginRouter = createPluginRouter(pluginRegistry, "bare", { delegateToHost: (header, payload) => hostBridge?.invokeOnHost(header, payload) ?? Promise.resolve(null) });
-	if (ipc) ipc.on("data", async (data) => {
-		try {
-			const raw = toUint8Array(data);
-			if (hostBridge?.tryConsumeDownstreamFromHost(raw)) return;
-			const parsed = protocol.decode(raw);
-			const header = parsed.header;
-			const pluginResponse = await pluginRouter.route(header, parsed.payload);
-			if (pluginResponse) writeIpc(ipc, protocol.encode(MessageType.ENVELOPE, pluginResponse, null));
-		} catch (e) {
-			const message = e instanceof Error ? e.message : String(e);
-			console.error(`Malformed IPC frame dropped: ${message}`);
-		}
-	});
+	if (ipc) {
+		const bridge = hostBridge;
+		const channel = createFrameChannel({
+			name: "[ipc]",
+			protocol,
+			router: pluginRouter,
+			write: (frame) => ipc.write(toIpcChunk(frame)),
+			onMalformed: { kind: "tolerate" },
+			intercept: (message) => bridge?.tryConsumeDownstream(message) ?? false
+		});
+		ipc.on("data", (data) => channel.push(data));
+	}
 	async function start() {
 		if (options.storage) try {
 			fs.rmSync(path.join(options.storage, "handoff.json"), { force: true });
-		} catch {}
-		if (options.webAssets) server.mountDir("/", options.webAssets);
+		} catch {
+			console.debug("[runtime] no existing handoff file to remove");
+		}
+		if (options.webAssets) server.mountDir("/", options.webAssets, { public: true });
 		attachWebSocketProtocol(server, {
 			protocol,
 			pluginRegistry,
 			pluginRouter
 		});
 		const credentials = await server.credentials();
-		if (auth && options.storage) try {
-			fs.writeFileSync(path.join(options.storage, "handoff.json"), JSON.stringify(credentials));
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			console.error(`Failed to write handoff file: ${message}`);
+		if (auth && options.storage && options.handoffFile !== false) {
+			const { origin, port, bootstrap } = credentials;
+			try {
+				fs.writeFileSync(path.join(options.storage, "handoff.json"), JSON.stringify({
+					origin,
+					port,
+					bootstrap
+				}));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				console.error(`Failed to write handoff file: ${message}`);
+			}
 		}
 		return credentials;
 	}
@@ -725,5 +1716,4 @@ function createWorkletRuntime(options = {}) {
 		}
 	};
 }
-//#endregion
 export { attachWebSocketProtocol, collectRequestBody, createLoopbackPush, createLoopbackServer, createWorkletRuntime, getIPC, resolveCliConfig, resolveWorkletConfig };