devflare 1.0.0-next.7 → 1.0.0-next.71

package/dist/_chunks/context-DGMev2AF.js

@@ -0,0 +1,2515 @@
+import { wrapEnvSendEmailBindings } from "../utils/send-email.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/bridge/v2/wire.ts
+/** Binary frame kinds */
+const BinaryKind = {
+	StreamChunk: 1,
+	WsData: 2
+};
+/** Binary frame flags */
+const BinaryFlags = {
+	FIN: 1,
+	TEXT: 2
+};
+/** Encode a binary frame */
+function encodeBinaryFrame(kind, id, seq, flags, payload) {
+	const frame = new Uint8Array(10 + payload.byteLength);
+	const view = new DataView(frame.buffer);
+	view.setUint8(0, kind);
+	view.setUint32(1, id, true);
+	view.setUint32(5, seq, true);
+	view.setUint8(9, flags);
+	frame.set(payload, 10);
+	return frame;
+}
+/** Parse a JSON message from string */
+function parseJsonMsg(data) {
+	const msg = JSON.parse(data);
+	if (typeof msg !== "object" || msg === null || !("t" in msg)) throw new Error("Invalid message: missing type field");
+	return msg;
+}
+/** Stringify a JSON message */
+function stringifyJsonMsg(msg) {
+	return JSON.stringify(msg);
+}
+let streamIdCounter = 0;
+let wsIdCounter = 0;
+/** Generate unique stream ID */
+function nextStreamId() {
+	return ++streamIdCounter;
+}
+/** Generate unique WebSocket proxy ID */
+function nextWsId() {
+	return ++wsIdCounter;
+}
+/** Default chunk size for streaming (256 KB) */
+const DEFAULT_CHUNK_SIZE = 256 * 1024;
+/** Threshold for switching to HTTP transfer (512 KB — workerd ~1MB WS message limit). */
+const HTTP_TRANSFER_THRESHOLD = 512 * 1024;
+//#endregion
+//#region src/bridge/websocket-constructor.ts
+let wsPackageConstructorPromise = null;
+/**
+* Lazily import the `ws` package's WebSocket constructor (memoized). Used as the
+* Node fallback and whenever custom upgrade headers are required — unlike the
+* platform global, the `ws` constructor accepts an options object with headers.
+*
+* @returns The `ws` package WebSocket constructor.
+* @throws When the `ws` package does not export a usable WebSocket implementation.
+*/
+async function importWsPackageConstructor() {
+	if (!wsPackageConstructorPromise) wsPackageConstructorPromise = (async () => {
+		const wsModule = await new Function("specifier", [
+			"return ",
+			"import",
+			"(specifier)"
+		].join(""))("ws");
+		const defaultExport = wsModule.default;
+		const wsConstructor = wsModule.WebSocket ?? (typeof defaultExport === "object" && defaultExport !== null ? defaultExport.WebSocket : void 0) ?? defaultExport;
+		if (typeof wsConstructor !== "function") throw new Error("Could not load a WebSocket client implementation from the ws package");
+		return wsConstructor;
+	})();
+	return wsPackageConstructorPromise;
+}
+/**
+* Return the runtime's global WebSocket constructor, or null when the runtime
+* has none (older Node without a global WebSocket).
+*
+* @param runtimeWebSocket - The candidate global (defaults to `globalThis.WebSocket`).
+* @returns The global constructor, or null.
+*/
+function getRuntimeWebSocketConstructor(runtimeWebSocket = globalThis.WebSocket) {
+	if (typeof runtimeWebSocket === "function") return runtimeWebSocket;
+	return null;
+}
+/**
+* Resolve a WebSocket constructor for the bridge socket: prefer the runtime
+* global, fall back to the `ws` package.
+*
+* @param runtimeWebSocket - The candidate global (defaults to `globalThis.WebSocket`).
+* @returns A usable WebSocket constructor.
+*/
+async function resolveBridgeWebSocketConstructor(runtimeWebSocket = globalThis.WebSocket) {
+	const runtimeConstructor = getRuntimeWebSocketConstructor(runtimeWebSocket);
+	if (runtimeConstructor) return runtimeConstructor;
+	return importWsPackageConstructor();
+}
+/**
+* Resolve the WebSocket constructor for a Durable Object pass-through
+* connection. Custom upgrade headers require the `ws` package (whose constructor
+* accepts an options object); the global WebSocket (undici/Bun) cannot set
+* request headers, so it is used only when there are no headers to forward.
+*
+* @param hasHeaders - Whether application headers must ride the upgrade request.
+* @returns A WebSocket constructor suitable for the connection.
+*/
+async function resolveDoWebSocketConstructor(hasHeaders) {
+	if (hasHeaders) return importWsPackageConstructor();
+	return resolveBridgeWebSocketConstructor();
+}
+//#endregion
+//#region src/bridge/do-websocket-connect.ts
+/**
+* Hop-by-hop / WebSocket-control request headers that the WebSocket client sets
+* itself. They must never be copied from the user's `connect(url, { headers })`
+* onto the outgoing upgrade — a duplicate `Upgrade`/`Sec-WebSocket-*` breaks the
+* handshake (the `ws` package rejects it). Auth/cookie headers are preserved.
+*/
+const WS_CONTROL_HEADERS = new Set([
+	"upgrade",
+	"connection",
+	"host",
+	"sec-websocket-key",
+	"sec-websocket-version",
+	"sec-websocket-extensions",
+	"sec-websocket-protocol"
+]);
+/**
+* Strip WebSocket-control headers from user-supplied upgrade headers, leaving
+* only the application headers (auth, cookies) worth forwarding to the DO.
+*
+* @param headers - Header tuples from `connect(url, { headers })`, or undefined.
+* @returns A plain object of the forwardable headers (may be empty).
+*/
+function forwardableUpgradeHeaders(headers) {
+	const out = {};
+	for (const [key, value] of headers ?? []) if (!WS_CONTROL_HEADERS.has(key.toLowerCase())) out[key] = value;
+	return out;
+}
+/**
+* Normalize an inbound WebSocket payload to the `Uint8Array | string` contract
+* the DO Socket facade expects: text frames stay strings, binary frames become
+* a `Uint8Array` view regardless of whether the runtime delivered an
+* `ArrayBuffer`, a `Buffer`, or another typed-array/DataView.
+*
+* @param data - The raw `MessageEvent.data` from the DO pass-through socket.
+* @returns The payload as a string (text) or `Uint8Array` (binary).
+*/
+function normalizeIncomingWsData(data) {
+	if (typeof data === "string") return data;
+	if (data instanceof Uint8Array) return data;
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	if (ArrayBuffer.isView(data)) {
+		const view = data;
+		return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+	}
+	return String(data);
+}
+/**
+* Open a real pass-through WebSocket to a Durable Object through the gateway's
+* `/_devflare/do-ws` endpoint. Unlike the legacy relay, this is a standalone
+* connection with its own lifecycle, so it is unaffected by the bridge client's
+* `disconnect()`/reconnect bookkeeping.
+*
+* @param bridgeUrl - The bridge/gateway base URL (e.g. `ws://127.0.0.1:8787`).
+* @param binding - DO namespace binding name (e.g. `DOC_ROOM`).
+* @param idHex - Already-resolved Durable Object id, hex form.
+* @param targetUrl - The DO fetch URL the caller passed to `stub.connect(url)`.
+* @param headers - Optional upgrade headers (auth/cookies) forwarded to the DO.
+* @returns A proxy surface (send/close/onMessage/onClose) over the socket.
+* @throws When the pass-through socket fails to open (bad binding/id, or the DO
+*   rejected the upgrade).
+*/
+async function openDurableObjectWebSocket(bridgeUrl, binding, idHex, targetUrl, headers) {
+	const wsUrl = new URL(bridgeUrl);
+	wsUrl.pathname = "/_devflare/do-ws";
+	wsUrl.searchParams.set("binding", binding);
+	wsUrl.searchParams.set("id", idHex);
+	wsUrl.searchParams.set("u", targetUrl);
+	const forwardHeaders = forwardableUpgradeHeaders(headers);
+	const hasHeaders = Object.keys(forwardHeaders).length > 0;
+	const WebSocketCtor = await resolveDoWebSocketConstructor(hasHeaders);
+	const socket = hasHeaders ? new WebSocketCtor(wsUrl.toString(), { headers: forwardHeaders }) : new WebSocketCtor(wsUrl.toString());
+	socket.binaryType = "arraybuffer";
+	let opened = false;
+	let messageHandler = null;
+	let closeHandler = null;
+	const pendingMessages = [];
+	let pendingClose = null;
+	socket.onmessage = (event) => {
+		const data = normalizeIncomingWsData(event.data);
+		if (messageHandler) messageHandler(data);
+		else pendingMessages.push(data);
+	};
+	await new Promise((resolve, reject) => {
+		socket.onopen = () => {
+			opened = true;
+			resolve();
+		};
+		socket.onerror = () => {
+			if (!opened) reject(/* @__PURE__ */ new Error(`DO WebSocket connection failed: ${binding}/${idHex}`));
+		};
+		socket.onclose = (event) => {
+			if (!opened) {
+				reject(/* @__PURE__ */ new Error(`DO WebSocket closed before open: ${binding}/${idHex}`));
+				return;
+			}
+			if (closeHandler) closeHandler(event?.code, event?.reason);
+			else pendingClose = {
+				code: event?.code,
+				reason: event?.reason
+			};
+		};
+	});
+	return {
+		wid: nextWsId(),
+		send: (data) => socket.send(data),
+		close: (code, reason) => socket.close(code, reason),
+		onMessage: (handler) => {
+			messageHandler = handler;
+			if (pendingMessages.length > 0) for (const data of pendingMessages.splice(0)) handler(data);
+		},
+		onClose: (handler) => {
+			closeHandler = handler;
+			if (pendingClose) {
+				handler(pendingClose.code, pendingClose.reason);
+				pendingClose = null;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/bridge/log.ts
+const isDebugEnabled = () => {
+	try {
+		const env = globalThis.process?.env;
+		return Boolean(env?.DEVFLARE_DEBUG_BRIDGE);
+	} catch {
+		return false;
+	}
+};
+const bridgeLog = {
+	warn(message, error) {
+		if (!isDebugEnabled()) return;
+		console.warn(`[devflare:bridge] ${message}`, error);
+	},
+	debug(message, error) {
+		if (!isDebugEnabled()) return;
+		console.debug(`[devflare:bridge] ${message}`, error);
+	}
+};
+/** WebSocket close code used when v2 ↔ v1 mismatch is detected at handshake. */
+const TRANSPORT_V2_UNSUPPORTED_VERSION_CLOSE_CODE = 4001;
+/**
+* Binary frame kinds for v2. Values 1 (StreamChunk) and 2 (WsData) are
+* deliberately stable with v1 so a future shared decoder can route either
+* version's frames. Value 3 (BodyChunk) is new in v2 for HTTP body streams.
+*/
+const TransportV2BinaryKind = {
+	StreamChunk: 1,
+	WsData: 2,
+	BodyChunk: 3
+};
+/** Binary frame flags for v2. */
+const TransportV2BinaryFlags = {
+	FIN: 1,
+	TEXT: 2,
+	ABORT: 4
+};
+/** Decode a v2 binary frame. Pure; returns a view that aliases the input bytes. */
+function decodeTransportV2BinaryFrame(frame) {
+	if (frame.byteLength < 10) throw new Error(`Invalid transport v2 binary frame: too short (${frame.byteLength} bytes, need at least 10)`);
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const kind = view.getUint8(0);
+	if (kind !== TransportV2BinaryKind.StreamChunk && kind !== TransportV2BinaryKind.WsData && kind !== TransportV2BinaryKind.BodyChunk) throw new Error(`Invalid transport v2 binary frame: unknown kind ${kind}`);
+	return {
+		kind,
+		id: view.getUint32(1, true),
+		seq: view.getUint32(5, true),
+		flags: view.getUint8(9),
+		payload: frame.subarray(10)
+	};
+}
+/** True when the FIN flag is set on a v2 binary frame. */
+function transportV2IsFin(flags) {
+	return (flags & TransportV2BinaryFlags.FIN) !== 0;
+}
+/** True when the ABORT flag is set on a v2 binary frame. */
+function transportV2IsAbort(flags) {
+	return (flags & TransportV2BinaryFlags.ABORT) !== 0;
+}
+const KNOWN_V2_CONTROL_TYPES = new Set([
+	"hello",
+	"welcome",
+	"body.open",
+	"body.end",
+	"body.abort"
+]);
+/**
+* Parse a JSON string as a v2-specific control message. Returns the typed
+* message or throws if the payload is not a recognised v2 control type.
+*
+* Callers that need to multiplex v1 `JsonMsg` and v2 control messages should
+* inspect the `t` field first and dispatch accordingly; this helper is
+* deliberately strict so that v2-only code paths never silently accept v1
+* payloads.
+*/
+function parseTransportV2ControlMsg(data) {
+	const msg = JSON.parse(data);
+	if (typeof msg !== "object" || msg === null || !("t" in msg)) throw new Error("Invalid transport v2 control message: missing type field");
+	if (!KNOWN_V2_CONTROL_TYPES.has(msg.t)) throw new Error(`Invalid transport v2 control message: unknown type "${msg.t}"`);
+	if (msg.t === "hello" || msg.t === "welcome") {
+		if (msg.protocolVersion !== 2) throw new Error(`Invalid transport v2 ${msg.t}: protocolVersion ${msg.protocolVersion} != 2`);
+		if (!Array.isArray(msg.capabilities)) throw new Error(`Invalid transport v2 ${msg.t}: capabilities must be an array`);
+	}
+	return msg;
+}
+/** Stringify a v2 control message. Pure. */
+function stringifyTransportV2ControlMsg(msg) {
+	return JSON.stringify(msg);
+}
+/**
+* Compute the capability intersection a server should announce in its
+* `welcome` reply, given its own supported set and the client's `hello`
+* advertisement. Order is deterministic (sorted) so the wire output is
+* reproducible across runs.
+*/
+function negotiateTransportV2Capabilities(supported, advertised) {
+	const supportedSet = new Set(supported);
+	const intersection = advertised.filter((cap) => supportedSet.has(cap));
+	return [...new Set(intersection)].sort();
+}
+//#endregion
+//#region src/bridge/v2/body-streams.ts
+/**
+* Tracks in-flight v2 body streams on the reader side. The codec routes
+* incoming `body.open` / `body.end` / `body.abort` control messages and
+* `BodyChunk` binary frames here; consumers of v2 RPC results obtain a
+* `ReadableStream<Uint8Array>` to attach to a `Request` / `Response`.
+*/
+var TransportV2BodyReaderRegistry = class {
+	#streams = /* @__PURE__ */ new Map();
+	/** Register a new body stream and return the reader-side `ReadableStream`. Idempotent: returns the existing stream if `bid` is already registered. */
+	getOrOpen(bid) {
+		const existing = this.#streams.get(bid);
+		if (existing !== void 0) return existing.stream;
+		return this.open(bid);
+	}
+	/** Register a new body stream and return the reader-side `ReadableStream`. Throws if `bid` is already registered. */
+	open(bid) {
+		if (this.#streams.has(bid)) throw new Error(`v2 body reader already registered for bid ${bid}`);
+		const state = {
+			controller: null,
+			stream: null,
+			closed: false
+		};
+		state.stream = new ReadableStream({
+			start: (controller) => {
+				state.controller = controller;
+			},
+			cancel: () => {
+				state.closed = true;
+				this.#streams.delete(bid);
+			}
+		});
+		this.#streams.set(bid, state);
+		return state.stream;
+	}
+	/** Push a decoded BodyChunk frame to the matching reader. */
+	pushChunk(frame) {
+		if (frame.kind !== TransportV2BinaryKind.BodyChunk) throw new Error(`v2 body reader received non-BodyChunk frame (kind=${frame.kind})`);
+		const state = this.#streams.get(frame.id);
+		if (state === void 0 || state.closed) return;
+		const isFin = transportV2IsFin(frame.flags);
+		if (transportV2IsAbort(frame.flags)) {
+			state.closed = true;
+			state.controller?.error(/* @__PURE__ */ new Error(`v2 body stream ${frame.id} aborted by writer`));
+			this.#streams.delete(frame.id);
+			return;
+		}
+		if (frame.payload.byteLength > 0) state.controller?.enqueue(new Uint8Array(frame.payload));
+		if (isFin) {
+			state.closed = true;
+			state.controller?.close();
+			this.#streams.delete(frame.id);
+		}
+	}
+	/** Handle a `body.end` control message (writer signalled clean end). */
+	end(bid) {
+		const state = this.#streams.get(bid);
+		if (state === void 0 || state.closed) return;
+		state.closed = true;
+		state.controller?.close();
+		this.#streams.delete(bid);
+	}
+	/** Handle a `body.abort` control message. */
+	abort(bid, reason) {
+		const state = this.#streams.get(bid);
+		if (state === void 0 || state.closed) return;
+		state.closed = true;
+		state.controller?.error(new Error(reason ?? `v2 body stream ${bid} aborted`));
+		this.#streams.delete(bid);
+	}
+	/** Number of currently open reader-side body streams (for tests/diagnostics). */
+	get size() {
+		return this.#streams.size;
+	}
+};
+//#endregion
+//#region src/bridge/v2/codec.ts
+/**
+* v2 codec attached to a single `WebSocketLike`. Owns handshake state, the
+* frame demultiplexer, RPC pending-call table, and the body-stream registry.
+*/
+var TransportV2Codec = class {
+	bodyReaders = new TransportV2BodyReaderRegistry();
+	#socket;
+	#capabilities;
+	#options;
+	#handshakeResolver = null;
+	#handshakePromise;
+	#sentHello = false;
+	#receivedHello = false;
+	#receivedWelcome = false;
+	#negotiated = null;
+	#pendingRpc = /* @__PURE__ */ new Map();
+	#nextBid = 1;
+	#nextRpcId = 1;
+	#closed = false;
+	constructor(socket, options = {}) {
+		this.#socket = socket;
+		this.#capabilities = options.capabilities ?? [];
+		this.#options = options;
+		this.#handshakePromise = new Promise((resolve, reject) => {
+			this.#handshakeResolver = {
+				resolve,
+				reject
+			};
+		});
+		socket.onmessage = (event) => this.#onMessage(event);
+		socket.onclose = () => this.#onClose();
+		socket.onerror = (event) => this.#onError(event.error);
+	}
+	/** Allocate a fresh body id (writer side). */
+	allocateBid() {
+		return this.#nextBid++;
+	}
+	/** Allocate a fresh RPC id (caller side). */
+	allocateRpcId() {
+		return `v2_rpc_${this.#nextRpcId++}`;
+	}
+	/** Send the `hello` frame. Called once by the side that initiates the handshake. */
+	sendHello() {
+		if (this.#sentHello) return;
+		this.#sentHello = true;
+		const hello = {
+			t: "hello",
+			protocolVersion: 2,
+			capabilities: [...this.#capabilities]
+		};
+		this.#socket.send(stringifyTransportV2ControlMsg(hello));
+	}
+	/** Promise that resolves once the handshake completes. */
+	get handshake() {
+		return this.#handshakePromise;
+	}
+	/** Negotiated capabilities once the handshake completes. */
+	get negotiated() {
+		return this.#negotiated;
+	}
+	sendText(message) {
+		if (this.#closed) throw new Error("cannot send on a closed v2 codec");
+		this.#socket.send(message);
+	}
+	sendBinary(frame) {
+		if (this.#closed) throw new Error("cannot send on a closed v2 codec");
+		this.#socket.send(frame);
+	}
+	/** Send a typed RPC call and resolve with the peer's `rpc.ok` result. */
+	call(method, params = []) {
+		const id = this.allocateRpcId();
+		const call = {
+			t: "rpc.call",
+			id,
+			method,
+			params
+		};
+		const promise = new Promise((resolve, reject) => {
+			this.#pendingRpc.set(id, {
+				resolve,
+				reject
+			});
+		});
+		this.sendText(JSON.stringify(call));
+		return promise;
+	}
+	/** Send an `rpc.ok` reply for a previously-received call. */
+	respondOk(id, result) {
+		const reply = {
+			t: "rpc.ok",
+			id,
+			result
+		};
+		this.sendText(JSON.stringify(reply));
+	}
+	/** Send an `rpc.err` reply for a previously-received call. */
+	respondErr(id, error) {
+		const reply = {
+			t: "rpc.err",
+			id,
+			error
+		};
+		this.sendText(JSON.stringify(reply));
+	}
+	/**
+	* Send an out-of-band structured `error` frame (B5-frame). Use for
+	* failures that are not scoped to a single RPC call id — e.g. malformed
+	* incoming frames, stream/ws aborts that need a typed cause, or gateway
+	* bookkeeping errors. Replaces silent `catch {}` fallthroughs.
+	*/
+	sendWireError(err) {
+		const frame = {
+			t: "error",
+			...err
+		};
+		this.sendText(JSON.stringify(frame));
+	}
+	/** Register a reader-side body stream. Returns the `ReadableStream`. Idempotent across the codec's `body.open` arrival. */
+	openBodyReader(bid) {
+		return this.bodyReaders.getOrOpen(bid);
+	}
+	/** Replace the `onRpcCall` handler after construction. Useful for one-shot tests and for higher RPC layers that build the handler lazily. */
+	setRpcCallHandler(handler) {
+		this.#options = {
+			...this.#options,
+			onRpcCall: handler
+		};
+	}
+	/** Close the underlying transport with an optional code/reason. */
+	close(code, reason) {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#failPending(/* @__PURE__ */ new Error("v2 transport closed"));
+		this.#socket.close(code, reason);
+	}
+	get isClosed() {
+		return this.#closed;
+	}
+	#onMessage(event) {
+		const { data } = event;
+		if (typeof data === "string") this.#onText(data);
+		else if (data instanceof Uint8Array) this.#onBinary(data);
+		else if (data instanceof ArrayBuffer) this.#onBinary(new Uint8Array(data));
+	}
+	#onText(data) {
+		let msg;
+		try {
+			msg = parseTransportV2ControlMsg(data);
+		} catch {
+			const rpc = tryParseRpcMsg(data);
+			if (rpc !== null) {
+				this.#onRpcMessage(rpc);
+				return;
+			}
+			const wireErr = tryParseWireError(data);
+			if (wireErr !== null) {
+				this.#options.onWireError?.(wireErr);
+				return;
+			}
+			this.#options.onUnknownControl?.(data);
+			return;
+		}
+		switch (msg.t) {
+			case "hello":
+				this.#onHello(msg);
+				break;
+			case "welcome":
+				this.#onWelcome(msg);
+				break;
+			case "body.open":
+				this.bodyReaders.getOrOpen(msg.bid);
+				break;
+			case "body.end":
+				this.bodyReaders.end(msg.bid);
+				break;
+			case "body.abort":
+				this.bodyReaders.abort(msg.bid, msg.error);
+				break;
+		}
+	}
+	#onBinary(data) {
+		let frame;
+		try {
+			frame = decodeTransportV2BinaryFrame(data);
+		} catch {
+			return;
+		}
+		if (frame.kind === TransportV2BinaryKind.BodyChunk) {
+			this.bodyReaders.pushChunk(frame);
+			return;
+		}
+		this.#options.onUnknownBinary?.(frame);
+	}
+	#onRpcMessage(msg) {
+		switch (msg.t) {
+			case "rpc.call":
+				this.#options.onRpcCall?.(msg);
+				break;
+			case "rpc.ok": {
+				const pending = this.#pendingRpc.get(msg.id);
+				if (pending !== void 0) {
+					this.#pendingRpc.delete(msg.id);
+					pending.resolve(msg.result);
+				}
+				break;
+			}
+			case "rpc.err": {
+				const pending = this.#pendingRpc.get(msg.id);
+				if (pending !== void 0) {
+					this.#pendingRpc.delete(msg.id);
+					const err = new Error(msg.error.message);
+					Object.assign(err, {
+						code: msg.error.code,
+						details: msg.error.details
+					});
+					pending.reject(err);
+				}
+				break;
+			}
+		}
+	}
+	#onHello(msg) {
+		if (this.#receivedHello) {
+			this.close(TRANSPORT_V2_UNSUPPORTED_VERSION_CLOSE_CODE, "duplicate hello");
+			return;
+		}
+		this.#receivedHello = true;
+		const negotiated = negotiateTransportV2Capabilities(this.#capabilities, msg.capabilities);
+		const welcome = {
+			t: "welcome",
+			protocolVersion: 2,
+			capabilities: negotiated
+		};
+		this.#socket.send(stringifyTransportV2ControlMsg(welcome));
+		this.#completeHandshake({
+			protocolVersion: 2,
+			capabilities: negotiated
+		});
+	}
+	#onWelcome(msg) {
+		if (this.#receivedWelcome) return;
+		this.#receivedWelcome = true;
+		this.#completeHandshake({
+			protocolVersion: 2,
+			capabilities: msg.capabilities
+		});
+	}
+	#completeHandshake(result) {
+		if (this.#negotiated !== null) return;
+		this.#negotiated = result;
+		this.#handshakeResolver?.resolve(result);
+		this.#handshakeResolver = null;
+	}
+	#onClose() {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#failPending(/* @__PURE__ */ new Error("v2 transport closed"));
+	}
+	#onError(error) {
+		const wrapped = error instanceof Error ? error : new Error(String(error));
+		this.#failPending(wrapped);
+	}
+	#failPending(error) {
+		const resolver = this.#handshakeResolver;
+		if (resolver !== null) {
+			this.#handshakeResolver = null;
+			resolver.reject(error);
+		}
+		for (const pending of this.#pendingRpc.values()) pending.reject(error);
+		this.#pendingRpc.clear();
+	}
+};
+function tryParseRpcMsg(data) {
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || !("t" in parsed)) return null;
+	const t = parsed.t;
+	if (t === "rpc.call" || t === "rpc.ok" || t === "rpc.err") return parsed;
+	return null;
+}
+function tryParseWireError(data) {
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || !("t" in parsed)) return null;
+	const candidate = parsed;
+	if (candidate.t !== "error") return null;
+	const scope = candidate.scope;
+	if (scope !== "transport" && scope !== "rpc" && scope !== "stream" && scope !== "ws") return null;
+	const err = candidate.error;
+	if (!err || typeof err.code !== "string" || typeof err.message !== "string") return null;
+	return parsed;
+}
+//#endregion
+//#region src/bridge/v2/value-serialization.ts
+/**
+* Read every `Set-Cookie` header value as a SEPARATE string.
+*
+* `Headers.forEach`/`entries()`/`get()` fold multiple `Set-Cookie` headers into
+* one comma-joined value (the Fetch spec's sort-and-combine), which corrupts
+* cookies: the second cookie's attributes bleed into the first. Only the
+* dedicated accessors keep them apart — the standard `getSetCookie()` (Bun,
+* Node, and workerd on a compatibility date ≥ 2023-08-01) or workerd's legacy
+* `getAll('set-cookie')` (present on older compat dates that predate
+* `getSetCookie`).
+*
+* @param headers - The header set to read.
+* @returns Each `Set-Cookie` value in insertion order, or `null` when the
+*   runtime exposes neither accessor — the caller then keeps the combined value
+*   rather than dropping the header.
+*/
+function readSetCookieValues(headers) {
+	const accessors = headers;
+	if (typeof accessors.getSetCookie === "function") {
+		const values = accessors.getSetCookie();
+		return Array.isArray(values) ? values : null;
+	}
+	if (typeof accessors.getAll === "function") try {
+		const values = accessors.getAll("set-cookie");
+		return Array.isArray(values) ? values : null;
+	} catch {
+		return null;
+	}
+	return null;
+}
+/**
+* Flatten a `Headers` set to `[name, value]` pairs WITHOUT collapsing multiple
+* `Set-Cookie` headers into one, so a response setting several cookies survives
+* the bridge round-trip byte-faithfully.
+*
+* Non-cookie headers are emitted via `forEach` as before. `Set-Cookie` is
+* enumerated separately (see `readSetCookieValues`) and appended as its own pair
+* per cookie, so the reconstructing `new Headers(pairs)` re-`append`s each one.
+* When the runtime can split neither (no `getSetCookie`/`getAll`), the combined
+* `forEach` value is kept verbatim — graceful degradation, never a dropped
+* header.
+*
+* @param headers - The header set to flatten.
+* @returns `[name, value]` pairs safe to round-trip; each `Set-Cookie` is a
+*   distinct pair.
+*/
+function serializeHeaders(headers) {
+	const setCookies = readSetCookieValues(headers);
+	const pairs = [];
+	headers.forEach((value, key) => {
+		if (setCookies !== null && key.toLowerCase() === "set-cookie") return;
+		pairs.push([key, value]);
+	});
+	if (setCookies) for (const cookie of setCookies) pairs.push(["set-cookie", cookie]);
+	return pairs;
+}
+/** Serialize a Request to a POJO */
+async function serializeRequest(request, options) {
+	const streams = [];
+	const threshold = options?.httpThreshold ?? 524288;
+	const headers = serializeHeaders(request.headers);
+	let body = null;
+	if (request.body) {
+		const bytes = await request.arrayBuffer();
+		if (bytes.byteLength > threshold) throw new Error("Request body exceeds the bridge inline limit (~512 KB) and large request-body streaming is not yet supported over the local bridge. Send the payload in smaller chunks or via an R2 binding for now.");
+		if (bytes.byteLength > 0) body = {
+			type: "bytes",
+			data: base64Encode(new Uint8Array(bytes))
+		};
+	}
+	return {
+		serialized: {
+			url: request.url,
+			method: request.method,
+			headers,
+			body,
+			redirect: request.redirect
+		},
+		streams
+	};
+}
+/** Deserialize a Request from a POJO */
+function deserializeRequest(serialized, getStream) {
+	let body = null;
+	if (serialized.body) switch (serialized.body.type) {
+		case "bytes":
+			body = base64Decode(serialized.body.data);
+			break;
+		case "stream":
+			if (getStream) body = getStream(serialized.body.sid) ?? null;
+			break;
+	}
+	return new Request(serialized.url, {
+		method: serialized.method,
+		headers: serialized.headers,
+		body,
+		redirect: serialized.redirect
+	});
+}
+/** Serialize a Response to a POJO */
+async function serializeResponse(response, options) {
+	const streams = [];
+	const threshold = options?.httpThreshold ?? 524288;
+	const headers = serializeHeaders(response.headers);
+	let body = null;
+	if (response.body) {
+		const bytes = await response.arrayBuffer();
+		if (bytes.byteLength > threshold) {
+			const sid = nextStreamId();
+			const payload = new Uint8Array(bytes);
+			const frameSize = HTTP_TRANSFER_THRESHOLD;
+			const stream = new ReadableStream({ start(controller) {
+				for (let offset = 0; offset < payload.byteLength; offset += frameSize) controller.enqueue(payload.slice(offset, Math.min(offset + frameSize, payload.byteLength)));
+				controller.close();
+			} });
+			streams.push({
+				sid,
+				stream
+			});
+			body = {
+				type: "stream",
+				sid
+			};
+		} else if (bytes.byteLength > 0) body = {
+			type: "bytes",
+			data: base64Encode(new Uint8Array(bytes))
+		};
+	}
+	return {
+		serialized: {
+			status: response.status,
+			statusText: response.statusText,
+			headers,
+			body
+		},
+		streams
+	};
+}
+/** Deserialize a Response from a POJO */
+function deserializeResponse(serialized, getStream) {
+	let body = null;
+	if (serialized.body) switch (serialized.body.type) {
+		case "bytes":
+			body = base64Decode(serialized.body.data);
+			break;
+		case "stream":
+			if (getStream) body = getStream(serialized.body.sid) ?? null;
+			break;
+	}
+	return new Response(body, {
+		status: serialized.status,
+		statusText: serialized.statusText,
+		headers: serialized.headers
+	});
+}
+/** Serialize a value that may contain special types */
+async function serializeValue(value, options) {
+	const streams = [];
+	return {
+		value: await serializeValueInternal(value, streams, options),
+		streams
+	};
+}
+async function serializeValueInternal(value, streams, options) {
+	if (value === null || value === void 0) return value;
+	if (value instanceof Request) {
+		const { serialized, streams: reqStreams } = await serializeRequest(value, options);
+		streams.push(...reqStreams);
+		return {
+			__type: "Request",
+			...serialized
+		};
+	}
+	if (value instanceof Response) {
+		const { serialized, streams: resStreams } = await serializeResponse(value, options);
+		streams.push(...resStreams);
+		return {
+			__type: "Response",
+			...serialized
+		};
+	}
+	if (value instanceof ReadableStream) {
+		const sid = nextStreamId();
+		streams.push({
+			sid,
+			stream: value
+		});
+		return {
+			__type: "ReadableStream",
+			sid
+		};
+	}
+	if (value instanceof Uint8Array) return {
+		__type: "Uint8Array",
+		data: base64Encode(value)
+	};
+	if (value instanceof ArrayBuffer) return {
+		__type: "ArrayBuffer",
+		data: base64Encode(new Uint8Array(value))
+	};
+	if (value instanceof Date) return {
+		__devflare: "date",
+		iso: value.toISOString()
+	};
+	if (value instanceof URL) return {
+		__devflare: "url",
+		href: value.href
+	};
+	if (value instanceof Error) {
+		const encoded = {
+			__devflare: "error",
+			name: value.name,
+			message: value.message
+		};
+		if (value.stack) encoded.stack = value.stack;
+		return encoded;
+	}
+	if (value instanceof Map) {
+		const entries = [];
+		for (const [k, v] of value.entries()) entries.push([await serializeValueInternal(k, streams, options), await serializeValueInternal(v, streams, options)]);
+		return {
+			__devflare: "map",
+			entries
+		};
+	}
+	if (value instanceof Set) {
+		const values = [];
+		for (const v of value.values()) values.push(await serializeValueInternal(v, streams, options));
+		return {
+			__devflare: "set",
+			values
+		};
+	}
+	if (Array.isArray(value)) return Promise.all(value.map((v) => serializeValueInternal(v, streams, options)));
+	if (typeof value === "object") {
+		const result = {};
+		for (const [k, v] of Object.entries(value)) result[k] = await serializeValueInternal(v, streams, options);
+		return result;
+	}
+	return value;
+}
+/** Deserialize a value that may contain special types */
+function deserializeValue(value, getStream) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "object" && value !== null) {
+		const obj = value;
+		if (typeof obj.__devflare === "string") switch (obj.__devflare) {
+			case "date": return new Date(obj.iso);
+			case "url": return new URL(obj.href);
+			case "error": {
+				const err = new Error(obj.message);
+				if (typeof obj.name === "string") err.name = obj.name;
+				if (typeof obj.stack === "string") err.stack = obj.stack;
+				return err;
+			}
+			case "map": {
+				const entries = obj.entries ?? [];
+				const map = /* @__PURE__ */ new Map();
+				for (const [k, v] of entries) map.set(deserializeValue(k, getStream), deserializeValue(v, getStream));
+				return map;
+			}
+			case "set": {
+				const values = obj.values ?? [];
+				const set = /* @__PURE__ */ new Set();
+				for (const v of values) set.add(deserializeValue(v, getStream));
+				return set;
+			}
+		}
+		if (obj.__type === "Request") return deserializeRequest(obj, getStream);
+		if (obj.__type === "Response") return deserializeResponse(obj, getStream);
+		if (obj.__type === "ReadableStream") {
+			const sid = obj.sid;
+			return getStream?.(sid) ?? null;
+		}
+		if (obj.__type === "Uint8Array") return base64Decode(obj.data);
+		if (obj.__type === "ArrayBuffer") return base64Decode(obj.data).buffer;
+		if (obj.__type === "R2Object") return deserializeR2Object(obj);
+		if (obj.__type === "R2ObjectBody") return deserializeR2ObjectBody(obj);
+		if (Array.isArray(value)) return value.map((v) => deserializeValue(v, getStream));
+		const result = {};
+		for (const [k, v] of Object.entries(obj)) result[k] = deserializeValue(v, getStream);
+		return result;
+	}
+	return value;
+}
+function applySerializedHttpMetadata(headers, httpMetadata) {
+	if (httpMetadata?.contentType) headers.set("Content-Type", httpMetadata.contentType);
+	if (httpMetadata?.contentLanguage) headers.set("Content-Language", httpMetadata.contentLanguage);
+	if (httpMetadata?.contentDisposition) headers.set("Content-Disposition", httpMetadata.contentDisposition);
+	if (httpMetadata?.contentEncoding) headers.set("Content-Encoding", httpMetadata.contentEncoding);
+	if (httpMetadata?.cacheControl) headers.set("Cache-Control", httpMetadata.cacheControl);
+	if (httpMetadata?.cacheExpiry) headers.set("Expires", new Date(httpMetadata.cacheExpiry).toUTCString());
+}
+function createSerializedR2Metadata(serialized) {
+	return {
+		key: serialized.key,
+		version: serialized.version,
+		size: serialized.size,
+		etag: serialized.etag,
+		httpEtag: serialized.httpEtag,
+		checksums: serialized.checksums,
+		uploaded: serialized.uploaded ? new Date(serialized.uploaded) : /* @__PURE__ */ new Date(),
+		httpMetadata: serialized.httpMetadata,
+		customMetadata: serialized.customMetadata,
+		range: serialized.range,
+		storageClass: serialized.storageClass,
+		writeHttpMetadata(headers) {
+			applySerializedHttpMetadata(headers, serialized.httpMetadata);
+		}
+	};
+}
+/** Deserialize R2Object (metadata only) */
+function deserializeR2Object(obj) {
+	return { ...createSerializedR2Metadata(obj) };
+}
+/** Deserialize R2ObjectBody (with body data) */
+function deserializeR2ObjectBody(obj) {
+	const serialized = obj;
+	const bodyBytes = serialized.bodyData ? base64Decode(serialized.bodyData) : new Uint8Array(0);
+	return {
+		...createSerializedR2Metadata(serialized),
+		body: new ReadableStream({ start(controller) {
+			controller.enqueue(bodyBytes);
+			controller.close();
+		} }),
+		bodyUsed: false,
+		async arrayBuffer() {
+			const copy = new Uint8Array(bodyBytes.byteLength);
+			copy.set(bodyBytes);
+			return copy.buffer;
+		},
+		async text() {
+			return new TextDecoder().decode(bodyBytes);
+		},
+		async json() {
+			const text = new TextDecoder().decode(bodyBytes);
+			return JSON.parse(text);
+		},
+		async blob() {
+			const contentType = serialized.httpMetadata?.contentType || "application/octet-stream";
+			const buffer = bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength);
+			return new Blob([buffer], { type: contentType });
+		}
+	};
+}
+/** Encode Uint8Array to base64 string */
+function base64Encode(bytes) {
+	if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+	let binary = "";
+	for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+/** Decode base64 string to Uint8Array */
+function base64Decode(str) {
+	if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(str, "base64"));
+	const binary = atob(str);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+//#endregion
+//#region src/bridge/client.ts
+var BridgeWsAdapter = class {
+	onmessage = null;
+	onclose = null;
+	onerror = null;
+	#ws;
+	constructor(ws) {
+		this.#ws = ws;
+	}
+	send(data) {
+		this.#ws.send(data);
+	}
+	close(code, reason) {
+		this.#ws.close(code, reason);
+	}
+};
+const BRIDGE_CLIENT_CAPABILITIES = [
+	"streams",
+	"ws-relay",
+	"http-transfer"
+];
+var BridgeClient = class {
+	ws = null;
+	codec = null;
+	adapter = null;
+	url;
+	autoReconnect;
+	reconnectDelay;
+	connectTimeout;
+	activeStreams = /* @__PURE__ */ new Map();
+	wsProxies = /* @__PURE__ */ new Map();
+	pendingWsOpens = /* @__PURE__ */ new Map();
+	outgoingStreams = /* @__PURE__ */ new Map();
+	eventListeners = /* @__PURE__ */ new Map();
+	connectPromise = null;
+	isConnected = false;
+	constructor(options = {}) {
+		this.url = options.url ?? `ws://localhost:8787`;
+		this.autoReconnect = options.autoReconnect ?? true;
+		this.reconnectDelay = options.reconnectDelay ?? 1e3;
+		this.connectTimeout = options.connectTimeout ?? 5e3;
+	}
+	/** Get the WebSocket URL */
+	getUrl() {
+		return this.url;
+	}
+	/** Get the HTTP URL for transfer endpoint */
+	getHttpUrl() {
+		return this.url.replace(/^ws:\/\//, "http://").replace(/^wss:\/\//, "https://");
+	}
+	/** Connect to the bridge */
+	async connect() {
+		if (this.isConnected) return;
+		if (this.connectPromise) return this.connectPromise;
+		const WebSocketCtor = getRuntimeWebSocketConstructor();
+		const promise = WebSocketCtor ? this.openConnection(WebSocketCtor) : this.openConnectionWithPackageFallback();
+		this.connectPromise = promise;
+		promise.catch(() => {
+			if (this.connectPromise === promise) this.connectPromise = null;
+		});
+		return promise;
+	}
+	async openConnectionWithPackageFallback() {
+		const WebSocketCtor = await importWsPackageConstructor();
+		return this.openConnection(WebSocketCtor);
+	}
+	openConnection(WebSocketCtor) {
+		return new Promise((resolve, reject) => {
+			let socket = null;
+			const isCurrent = () => socket !== null && this.ws === socket;
+			const releaseConnectSlot = () => {
+				if (isCurrent()) this.connectPromise = null;
+			};
+			const timeout = setTimeout(() => {
+				socket?.close();
+				reject(/* @__PURE__ */ new Error(`Connection timeout: ${this.url}`));
+			}, this.connectTimeout);
+			try {
+				socket = new WebSocketCtor(this.url);
+				this.ws = socket;
+				socket.binaryType = "arraybuffer";
+				const adapter = new BridgeWsAdapter(socket);
+				this.adapter = adapter;
+				socket.onopen = () => {
+					clearTimeout(timeout);
+					if (!isCurrent()) {
+						socket?.close();
+						reject(/* @__PURE__ */ new Error(`Bridge connection superseded: ${this.url}`));
+						return;
+					}
+					this.codec = new TransportV2Codec(adapter, {
+						capabilities: [...BRIDGE_CLIENT_CAPABILITIES],
+						onUnknownControl: (data) => this.handleJsonMessage(data),
+						onUnknownBinary: (frame) => this.handleV2BinaryFrame(frame)
+					});
+					this.codec.sendHello();
+					this.codec.handshake.catch(() => {});
+					this.isConnected = true;
+					releaseConnectSlot();
+					resolve();
+				};
+				socket.onerror = (event) => {
+					clearTimeout(timeout);
+					releaseConnectSlot();
+					adapter.onerror?.({ error: event.error });
+					reject(/* @__PURE__ */ new Error("WebSocket connection failed"));
+				};
+				socket.onclose = (event) => {
+					adapter.onclose?.({
+						code: event?.code ?? 1006,
+						reason: event?.reason ?? ""
+					});
+					if (!isCurrent()) return;
+					this.handleDisconnect();
+				};
+				socket.onmessage = (event) => {
+					adapter.onmessage?.({ data: event.data });
+				};
+			} catch (error) {
+				clearTimeout(timeout);
+				reject(error);
+			}
+		});
+	}
+	/** Disconnect from the bridge and tear down all pending state */
+	disconnect() {
+		this.autoReconnect = false;
+		this.codec?.close();
+		this.codec = null;
+		this.adapter = null;
+		this.ws?.close();
+		this.ws = null;
+		this.isConnected = false;
+		this.cleanupPending(/* @__PURE__ */ new Error("Bridge disconnected"));
+		this.eventListeners.clear();
+	}
+	/** Alias for disconnect() */
+	close() {
+		this.disconnect();
+	}
+	/** Check if connected */
+	get connected() {
+		return this.isConnected;
+	}
+	handleDisconnect() {
+		this.isConnected = false;
+		this.codec?.close();
+		this.codec = null;
+		this.adapter = null;
+		this.ws = null;
+		this.cleanupPending(/* @__PURE__ */ new Error("Bridge disconnected"));
+		if (this.autoReconnect) setTimeout(() => {
+			this.connect().catch((error) => {
+				bridgeLog.warn("auto-reconnect attempt failed", error);
+			});
+		}, this.reconnectDelay);
+	}
+	/** Reject/close all pending streams and ws proxies (codec owns RPC pending). */
+	cleanupPending(error) {
+		for (const pending of this.pendingWsOpens.values()) pending.reject(error);
+		this.pendingWsOpens.clear();
+		for (const stream of this.activeStreams.values()) {
+			stream.closed = true;
+			if (stream.pendingPull) {
+				stream.pendingPull.reject(error);
+				stream.pendingPull = null;
+			}
+			try {
+				stream.controller.error(error);
+			} catch {}
+		}
+		this.activeStreams.clear();
+		for (const proxy of this.wsProxies.values()) try {
+			proxy.onClose(1006, error.message);
+		} catch {}
+		this.wsProxies.clear();
+		this.outgoingStreams.clear();
+	}
+	/** Call an RPC method */
+	async call(method, params, timeoutMs = 3e4) {
+		await this.ensureConnected();
+		const codec = this.codec;
+		if (!codec) throw new Error("Bridge disconnected");
+		const { value: serializedParams, streams } = await serializeValue(params);
+		for (const streamRef of streams) this.outgoingStreams.set(streamRef.sid, streamRef);
+		const callPromise = codec.call(method, serializedParams);
+		let timeoutHandle = null;
+		const timeoutPromise = new Promise((_, reject) => {
+			timeoutHandle = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`RPC timeout: ${method}`));
+			}, timeoutMs);
+		});
+		try {
+			return deserializeValue(await Promise.race([callPromise, timeoutPromise]), (sid) => this.createReadableStream(sid));
+		} catch (error) {
+			if (!this.isConnected && error instanceof Error && /v2 transport closed|transport/.test(error.message)) throw new Error("Bridge disconnected");
+			throw error;
+		} finally {
+			if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+		}
+	}
+	/**
+	* Subscribe to bridge `event` notifications for a topic.
+	*
+	* Pass `'*'` to receive every event regardless of topic. Returns an
+	* unsubscribe function; calling it removes this listener. Subscriptions
+	* survive auto-reconnect and are only dropped on an explicit disconnect().
+	*
+	* NOTE: no gateway currently emits `event` frames, so listeners will not
+	* fire until an event producer is wired on the gateway side. The subscriber
+	* surface is provided so consumers can register ahead of that work.
+	*/
+	on(topic, cb) {
+		let set = this.eventListeners.get(topic);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.eventListeners.set(topic, set);
+		}
+		set.add(cb);
+		return () => {
+			const current = this.eventListeners.get(topic);
+			if (!current) return;
+			current.delete(cb);
+			if (current.size === 0) this.eventListeners.delete(topic);
+		};
+	}
+	/**
+	* Create a proxied WebSocket to a Durable Object via the in-process bridge
+	* relay (`ws.open` control frame → gateway `stub.fetch()` pump → `WsData`
+	* frames).
+	*
+	* DEPRECATED for DO connect(): this relay pumps the DO's WebSocket in-process,
+	* which does NOT trigger workerd's hibernation dispatch — so a DO that uses
+	* `ctx.acceptWebSocket()` never sees `webSocketMessage`/`webSocketClose` and
+	* cross-socket `ctx.getWebSockets()` broadcasts never cross. `connect()` now
+	* uses `openDoWebSocket()` (a real pass-through) instead. This method is
+	* retained for the `ws-relay` wire capability and backward compatibility.
+	*/
+	async createWsProxy(binding, id, url, headers) {
+		await this.ensureConnected();
+		const wid = nextWsId();
+		const proxy = {
+			clientWs: null,
+			onMessage: () => {},
+			onClose: () => {}
+		};
+		this.wsProxies.set(wid, proxy);
+		const openedPromise = new Promise((resolve, reject) => {
+			this.pendingWsOpens.set(wid, {
+				resolve,
+				reject
+			});
+		});
+		const msg = {
+			t: "ws.open",
+			wid,
+			target: {
+				binding,
+				id,
+				url,
+				headers
+			}
+		};
+		this.send(msg);
+		try {
+			await openedPromise;
+		} catch (error) {
+			this.wsProxies.delete(wid);
+			throw error;
+		}
+		return {
+			wid,
+			send: (data) => {
+				const payload = typeof data === "string" ? new TextEncoder().encode(data) : data;
+				const flags = typeof data === "string" ? BinaryFlags.TEXT : 0;
+				const frame = encodeBinaryFrame(BinaryKind.WsData, wid, 0, flags, payload);
+				this.sendBinary(frame);
+			},
+			close: (code, reason) => {
+				const closeMsg = {
+					t: "ws.close",
+					wid,
+					code,
+					reason
+				};
+				this.send(closeMsg);
+				this.wsProxies.delete(wid);
+			},
+			onMessage: (handler) => {
+				proxy.onMessage = handler;
+			},
+			onClose: (handler) => {
+				proxy.onClose = handler;
+			}
+		};
+	}
+	/**
+	* Open a REAL WebSocket to the gateway's DO pass-through endpoint
+	* (`/_devflare/do-ws`), which forwards the upgrade to the target Durable
+	* Object and passes through its `101` response.
+	*
+	* This is the ONLY way a bridged DO WebSocket triggers the runtime's
+	* hibernation dispatch under miniflare: the gateway returns the DO's client
+	* socket for a genuine inbound connection, so workerd pumps it and invokes
+	* `webSocketMessage`/`webSocketClose` and delivers `ctx.getWebSockets()`
+	* broadcasts. The legacy in-process relay (`createWsProxy` + gateway
+	* `stub.fetch()` pump) never fires hibernation, so two sockets to the same
+	* `getByName(id)` could not see each other's messages. Here they share ONE DO
+	* instance and broadcast across each other, exactly as on real Cloudflare.
+	*
+	* Unlike `createWsProxy`, this does not multiplex over the bridge socket: it
+	* is a standalone connection (see `openDurableObjectWebSocket`) with its own
+	* lifecycle, so it is unaffected by the bridge client's disconnect/reconnect
+	* bookkeeping. It also does not require the bridge socket to be connected.
+	*
+	* @param binding - DO namespace binding name (e.g. `DOC_ROOM`).
+	* @param idHex - Already-resolved Durable Object id, hex form.
+	* @param targetUrl - The DO fetch URL the caller passed to `stub.connect(url)`.
+	* @param headers - Optional upgrade headers (auth/cookies) forwarded to the DO.
+	* @returns A minimal proxy surface (send/close/onMessage/onClose) over the socket.
+	* @throws When the pass-through socket fails to open (bad binding/id, or the
+	*   DO rejected the upgrade).
+	*/
+	async openDoWebSocket(binding, idHex, targetUrl, headers) {
+		return openDurableObjectWebSocket(this.url, binding, idHex, targetUrl, headers);
+	}
+	/** Create a readable stream that pulls from the bridge */
+	createReadableStream(sid) {
+		return new ReadableStream({
+			start: (controller) => {
+				this.activeStreams.set(sid, {
+					controller,
+					buffer: [],
+					creditRemaining: 0,
+					pendingPull: null,
+					ended: false,
+					closed: false
+				});
+			},
+			pull: async (controller) => {
+				const stream = this.activeStreams.get(sid);
+				if (!stream || stream.closed) return;
+				if (stream.buffer.length > 0) {
+					const chunk = stream.buffer.shift();
+					controller.enqueue(chunk);
+					return;
+				}
+				if (stream.ended) {
+					controller.close();
+					this.activeStreams.delete(sid);
+					return;
+				}
+				const pullMsg = {
+					t: "stream.pull",
+					sid,
+					creditBytes: DEFAULT_CHUNK_SIZE * 4
+				};
+				this.send(pullMsg);
+				await new Promise((resolve, reject) => {
+					stream.pendingPull = {
+						resolve,
+						reject
+					};
+				});
+				stream.pendingPull = null;
+				if (stream.closed) return;
+				if (stream.buffer.length > 0) {
+					const chunk = stream.buffer.shift();
+					controller.enqueue(chunk);
+					return;
+				}
+				if (stream.ended) {
+					controller.close();
+					this.activeStreams.delete(sid);
+				}
+			},
+			cancel: () => {
+				const stream = this.activeStreams.get(sid);
+				if (stream) {
+					stream.closed = true;
+					if (stream.pendingPull) {
+						stream.pendingPull.reject(/* @__PURE__ */ new Error("Stream cancelled"));
+						stream.pendingPull = null;
+					}
+				}
+				this.activeStreams.delete(sid);
+			}
+		});
+	}
+	handleJsonMessage(data) {
+		try {
+			const msg = parseJsonMsg(data);
+			switch (msg.t) {
+				case "event":
+					this.handleEvent(msg);
+					break;
+				case "stream.pull":
+					this.handleStreamPull(msg);
+					break;
+				case "stream.end":
+					this.handleStreamEnd(msg);
+					break;
+				case "stream.abort":
+					this.handleStreamAbort(msg);
+					break;
+				case "ws.opened":
+					this.handleWsOpened(msg);
+					break;
+				case "ws.close":
+					this.handleWsClose(msg);
+					break;
+			}
+		} catch (error) {
+			console.error("[devflare bridge client] parse error:", data, error);
+		}
+	}
+	/**
+	* Receive a v2 binary frame. Frame format is byte-identical to the legacy
+	* v1 frames for kinds 1 (StreamChunk) and 2 (WsData); v2 owns kind 3
+	* (BodyChunk) which the codec handles internally before reaching here.
+	*/
+	handleV2BinaryFrame(frame) {
+		switch (frame.kind) {
+			case BinaryKind.StreamChunk:
+				this.handleStreamChunk(frame);
+				break;
+			case BinaryKind.WsData:
+				this.handleWsData(frame);
+				break;
+		}
+	}
+	handleEvent(msg) {
+		this.dispatchEvent(this.eventListeners.get(msg.topic), msg.data, msg.topic);
+		this.dispatchEvent(this.eventListeners.get("*"), msg.data, msg.topic);
+	}
+	dispatchEvent(listeners, data, topic) {
+		if (!listeners) return;
+		for (const cb of [...listeners]) try {
+			cb(data);
+		} catch (error) {
+			bridgeLog.warn(`event listener for topic "${topic}" threw`, error);
+		}
+	}
+	handleStreamPull(msg) {
+		const streamRef = this.outgoingStreams.get(msg.sid);
+		if (!streamRef) return;
+		this.pumpStream(streamRef, msg.creditBytes);
+	}
+	async pumpStream(streamRef, creditBytes) {
+		const reader = streamRef.stream.getReader();
+		let sent = 0;
+		let seq = 0;
+		try {
+			while (sent < creditBytes) {
+				const { done, value } = await reader.read();
+				if (done) {
+					this.send({
+						t: "stream.end",
+						sid: streamRef.sid
+					});
+					this.outgoingStreams.delete(streamRef.sid);
+					break;
+				}
+				if (value) {
+					const frame = encodeBinaryFrame(BinaryKind.StreamChunk, streamRef.sid, seq++, 0, value);
+					this.sendBinary(frame);
+					sent += value.byteLength;
+				}
+			}
+		} catch (error) {
+			this.send({
+				t: "stream.abort",
+				sid: streamRef.sid,
+				error: String(error)
+			});
+			this.outgoingStreams.delete(streamRef.sid);
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	handleStreamChunk(decoded) {
+		const stream = this.activeStreams.get(decoded.id);
+		if (!stream || stream.closed) return;
+		stream.buffer.push(decoded.payload);
+		if (stream.pendingPull) {
+			const pending = stream.pendingPull;
+			stream.pendingPull = null;
+			pending.resolve();
+		}
+	}
+	handleStreamEnd(msg) {
+		const stream = this.activeStreams.get(msg.sid);
+		if (!stream) return;
+		stream.ended = true;
+		if (stream.pendingPull) {
+			const pending = stream.pendingPull;
+			stream.pendingPull = null;
+			pending.resolve();
+		}
+	}
+	handleStreamAbort(msg) {
+		const stream = this.activeStreams.get(msg.sid);
+		if (!stream) return;
+		const err = new Error(msg.error ?? "Stream aborted");
+		stream.closed = true;
+		if (stream.pendingPull) {
+			const pending = stream.pendingPull;
+			stream.pendingPull = null;
+			pending.reject(err);
+		}
+		try {
+			stream.controller.error(err);
+		} catch {}
+		this.activeStreams.delete(msg.sid);
+	}
+	handleWsData(decoded) {
+		const proxy = this.wsProxies.get(decoded.id);
+		if (!proxy) return;
+		const data = (decoded.flags & BinaryFlags.TEXT) !== 0 ? new TextDecoder().decode(decoded.payload) : decoded.payload;
+		proxy.onMessage(data);
+	}
+	handleWsClose(msg) {
+		const proxy = this.wsProxies.get(msg.wid);
+		if (!proxy) return;
+		proxy.onClose(msg.code, msg.reason);
+		this.wsProxies.delete(msg.wid);
+	}
+	handleWsOpened(msg) {
+		const pending = this.pendingWsOpens.get(msg.wid);
+		if (!pending) return;
+		this.pendingWsOpens.delete(msg.wid);
+		pending.resolve();
+	}
+	async ensureConnected() {
+		if (!this.isConnected) await this.connect();
+	}
+	send(msg) {
+		const codec = this.codec;
+		if (!codec || !this.isConnected) throw new Error("Not connected to bridge");
+		codec.sendText(stringifyJsonMsg(msg));
+	}
+	sendBinary(frame) {
+		const codec = this.codec;
+		if (!codec || !this.isConnected) throw new Error("Not connected to bridge");
+		codec.sendBinary(frame);
+	}
+};
+let defaultClient = null;
+/** Get or create the default bridge client */
+function getClient(options) {
+	if (!defaultClient) defaultClient = new BridgeClient(options);
+	return defaultClient;
+}
+//#endregion
+//#region src/bridge/proxy.ts
+function createKVProxy(client, bindingName) {
+	return {
+		async get(key, options) {
+			return client.call(`${bindingName}.kv.get`, [key, options]);
+		},
+		async put(key, value, options) {
+			await client.call(`${bindingName}.kv.put`, [
+				key,
+				value,
+				options
+			]);
+		},
+		async delete(key) {
+			await client.call(`${bindingName}.kv.delete`, [key]);
+		},
+		async list(options) {
+			return client.call(`${bindingName}.kv.list`, [options]);
+		},
+		async getWithMetadata(key, options) {
+			return client.call(`${bindingName}.kv.getWithMetadata`, [key, options]);
+		}
+	};
+}
+function createR2Proxy(client, bindingName) {
+	return {
+		async head(key) {
+			return client.call(`${bindingName}.r2.head`, [key]);
+		},
+		async get(key, options) {
+			return client.call(`${bindingName}.r2.get`, [key, options]);
+		},
+		async put(key, value, options) {
+			if (getValueSize(value) > 524288) {
+				const transferId = `${bindingName}:${key}`;
+				const transferUrl = client.getHttpUrl().replace(/\/$/, "") + `/_devflare/transfer/${encodeURIComponent(transferId)}`;
+				const response = await fetch(transferUrl, {
+					method: "PUT",
+					body: value,
+					headers: { ...options?.httpMetadata?.contentType ? { "Content-Type": options.httpMetadata.contentType } : {} }
+				});
+				if (!response.ok) {
+					const error = await response.text();
+					throw new Error(`HTTP transfer failed: ${error}`);
+				}
+				return deserializeValue(await response.json());
+			}
+			return client.call(`${bindingName}.r2.put`, [
+				key,
+				value,
+				options
+			]);
+		},
+		async delete(keys) {
+			await client.call(`${bindingName}.r2.delete`, [keys]);
+		},
+		async list(options) {
+			return client.call(`${bindingName}.r2.list`, [options]);
+		},
+		async createMultipartUpload(key, options) {
+			return client.call(`${bindingName}.r2.createMultipartUpload`, [key, options]);
+		},
+		async resumeMultipartUpload(key, uploadId) {
+			return client.call(`${bindingName}.r2.resumeMultipartUpload`, [key, uploadId]);
+		}
+	};
+}
+function getValueSize(value) {
+	if (value instanceof Blob) return value.size;
+	if (value instanceof ArrayBuffer) return value.byteLength;
+	if (value instanceof Uint8Array) return value.byteLength;
+	if (typeof value === "string") return new TextEncoder().encode(value).byteLength;
+	if (value instanceof ReadableStream) return Number.POSITIVE_INFINITY;
+	return 0;
+}
+function createD1Proxy(client, bindingName) {
+	return {
+		prepare(sql) {
+			return createD1StatementProxy(client, bindingName, sql, []);
+		},
+		async batch(statements) {
+			const serialized = statements.map((stmt) => {
+				const s = stmt;
+				return {
+					sql: s._sql,
+					bindings: s._bindings
+				};
+			});
+			return client.call(`${bindingName}.d1.batch`, [serialized]);
+		},
+		async exec(sql) {
+			return client.call(`${bindingName}.d1.exec`, [sql]);
+		},
+		async dump() {
+			return client.call(`${bindingName}.d1.dump`, []);
+		}
+	};
+}
+function createD1StatementProxy(client, bindingName, sql, bindings) {
+	return {
+		_sql: sql,
+		_bindings: bindings,
+		bind(...values) {
+			return createD1StatementProxy(client, bindingName, sql, values);
+		},
+		async first(column) {
+			return client.call(`${bindingName}.d1.stmt.first`, [
+				sql,
+				...bindings,
+				column
+			]);
+		},
+		async all() {
+			return client.call(`${bindingName}.d1.stmt.all`, [sql, ...bindings]);
+		},
+		async run() {
+			return client.call(`${bindingName}.d1.stmt.run`, [sql, ...bindings]);
+		},
+		async raw(options) {
+			return client.call(`${bindingName}.d1.stmt.raw`, [
+				sql,
+				...bindings,
+				options
+			]);
+		}
+	};
+}
+function createDOProxy(client, bindingName, proxyOptions = {}) {
+	return {
+		idFromName(name) {
+			return createDOIdProxy(client, bindingName, {
+				type: "name",
+				value: name,
+				jurisdiction: proxyOptions.jurisdiction
+			});
+		},
+		idFromString(hexId) {
+			return createDOIdProxy(client, bindingName, {
+				type: "hex",
+				value: hexId,
+				jurisdiction: proxyOptions.jurisdiction
+			});
+		},
+		newUniqueId(options) {
+			return createDOIdProxy(client, bindingName, {
+				type: "unique",
+				value: crypto.randomUUID().replace(/-/g, ""),
+				options,
+				jurisdiction: proxyOptions.jurisdiction
+			});
+		},
+		get(id) {
+			return createDOStubProxy(client, bindingName, id._idInfo, proxyOptions);
+		},
+		getByName(name) {
+			const id = this.idFromName(name);
+			return this.get(id);
+		},
+		jurisdiction(jurisdiction) {
+			return createDOProxy(client, bindingName, {
+				...proxyOptions,
+				jurisdiction
+			});
+		}
+	};
+}
+function createDOIdProxy(client, bindingName, idInfo) {
+	return {
+		_idInfo: idInfo,
+		toString() {
+			if (idInfo.type === "hex") return idInfo.value;
+			return `${idInfo.type}:${idInfo.value}`;
+		},
+		equals(other) {
+			return this.toString() === other.toString();
+		}
+	};
+}
+function createDOStubProxy(client, bindingName, idInfo, proxyOptions = {}) {
+	const { transformResult } = proxyOptions;
+	let resolvedId = null;
+	const resolveId = async () => {
+		if (resolvedId) return resolvedId;
+		switch (idInfo.type) {
+			case "name":
+				resolvedId = await client.call(`${bindingName}.do.idFromName`, [idInfo.value, idInfo.jurisdiction]);
+				break;
+			case "hex":
+				resolvedId = {
+					__type: "DOId",
+					hex: idInfo.value
+				};
+				break;
+			case "unique":
+				resolvedId = await client.call(`${bindingName}.do.newUniqueId`, [idInfo.options, idInfo.jurisdiction]);
+				break;
+		}
+		return resolvedId;
+	};
+	return new Proxy({
+		async fetch(input, init) {
+			const id = await resolveId();
+			const { serialized } = await serializeRequest(input instanceof Request ? input : new Request(input, init));
+			return deserializeResponse(await client.call(`${bindingName}.do.fetch`, [
+				bindingName,
+				id,
+				serialized
+			]));
+		},
+		async connect(url, options) {
+			const id = await resolveId();
+			const headersList = [];
+			if (options?.headers) new Headers(options.headers).forEach((value, key) => {
+				headersList.push([key, value]);
+			});
+			const wsProxy = await client.openDoWebSocket(bindingName, id.hex, url, headersList);
+			let readController = null;
+			const readable = new ReadableStream({
+				start(controller) {
+					readController = controller;
+				},
+				cancel() {
+					wsProxy.close();
+				}
+			});
+			wsProxy.onMessage((data) => {
+				if (readController) {
+					const chunk = typeof data === "string" ? new TextEncoder().encode(data) : data;
+					readController.enqueue(chunk);
+				}
+			});
+			wsProxy.onClose((code, reason) => {
+				if (readController) readController.close();
+			});
+			return {
+				readable,
+				writable: new WritableStream({
+					write(chunk) {
+						wsProxy.send(chunk);
+					},
+					close() {
+						wsProxy.close(1e3, "Normal closure");
+					},
+					abort(reason) {
+						wsProxy.close(1001, reason?.toString() ?? "Aborted");
+					}
+				}),
+				get opened() {
+					return Promise.resolve({
+						remoteAddress: "127.0.0.1",
+						localAddress: "127.0.0.1"
+					});
+				},
+				get closed() {
+					return new Promise((resolve) => {
+						wsProxy.onClose(() => resolve());
+					});
+				},
+				close() {
+					wsProxy.close(1e3, "Normal closure");
+					return Promise.resolve();
+				},
+				startTls() {
+					throw new Error("startTls() is not supported on a Durable Object WebSocket connection. StartTLS applies to raw TCP sockets (cloudflare:sockets connect()), not WebSocket-tunneled DO connections, whose transport is already secured by the connection itself.");
+				}
+			};
+		},
+		get id() {
+			return createDOIdProxy(client, bindingName, idInfo);
+		},
+		get name() {
+			return idInfo.type === "name" ? idInfo.value : void 0;
+		}
+	}, { get(target, prop) {
+		if (prop in target) return target[prop];
+		if (typeof prop === "symbol") return;
+		if (prop === "then" || prop === "catch" || prop === "finally") return;
+		return async (...args) => {
+			const id = await resolveId();
+			let result = await client.call(`${bindingName}.do.rpc`, [
+				bindingName,
+				id,
+				prop,
+				args
+			]);
+			if (transformResult) result = transformResult(result);
+			return result;
+		};
+	} });
+}
+function isResponseLike(value) {
+	return value instanceof Response;
+}
+function createServiceProxy(client, bindingName, proxyOptions = {}) {
+	const { transformResult } = proxyOptions;
+	return new Proxy({ async fetch(input, init) {
+		const { serialized } = await serializeRequest(input instanceof Request ? input : new Request(input, init));
+		const result = await client.call(`${bindingName}.service.fetch`, [serialized]);
+		if (isResponseLike(result)) return result;
+		return deserializeResponse(result);
+	} }, { get(target, prop) {
+		if (typeof prop !== "string") return;
+		if (prop in target) return target[prop];
+		if (prop === "then" || prop === "catch" || prop === "finally") return;
+		if (prop === "toString") return () => `[DevflareServiceBinding ${bindingName}]`;
+		return async (...args) => {
+			let result = await client.call(`${bindingName}.service.rpc`, [prop, args]);
+			if (transformResult) result = transformResult(result);
+			return result;
+		};
+	} });
+}
+const EMPTY_QUEUE_METRICS = {
+	backlogCount: 0,
+	backlogBytes: 0
+};
+function createQueueResponse() {
+	return { metadata: { metrics: EMPTY_QUEUE_METRICS } };
+}
+function createQueueProxy(client, bindingName) {
+	return {
+		async metrics() {
+			return EMPTY_QUEUE_METRICS;
+		},
+		async send(message, options) {
+			await client.call(`${bindingName}.queue.send`, [message, options]);
+			return createQueueResponse();
+		},
+		async sendBatch(messages, options) {
+			await client.call(`${bindingName}.queue.sendBatch`, [messages, options]);
+			return createQueueResponse();
+		}
+	};
+}
+function createAIProxy(client, bindingName) {
+	return { async run(model, inputs, options) {
+		return client.call(`${bindingName}.ai.run`, [
+			model,
+			inputs,
+			options
+		]);
+	} };
+}
+function createSendEmailProxy(client, bindingName) {
+	return { async send(message) {
+		return client.call(`${bindingName}.email.send`, [message]);
+	} };
+}
+function createWorkflowInstanceProxy(client, bindingName, id) {
+	return {
+		id,
+		async pause() {
+			await client.call(`${bindingName}.workflow.pause`, [id]);
+		},
+		async resume() {
+			await client.call(`${bindingName}.workflow.resume`, [id]);
+		},
+		async terminate() {
+			await client.call(`${bindingName}.workflow.terminate`, [id]);
+		},
+		async restart() {
+			await client.call(`${bindingName}.workflow.restart`, [id]);
+		},
+		async status() {
+			return client.call(`${bindingName}.workflow.status`, [id]);
+		},
+		async sendEvent(event) {
+			await client.call(`${bindingName}.workflow.sendEvent`, [id, event]);
+		}
+	};
+}
+function createWorkflowProxy(client, bindingName) {
+	const toInstance = (value) => {
+		const id = value?.id;
+		if (typeof id !== "string") throw new Error(`Workflow ${bindingName} returned an instance without a string id.`);
+		return createWorkflowInstanceProxy(client, bindingName, id);
+	};
+	return {
+		async create(options) {
+			return toInstance(await client.call(`${bindingName}.workflow.create`, [options]));
+		},
+		async get(id) {
+			return toInstance(await client.call(`${bindingName}.workflow.get`, [id]));
+		}
+	};
+}
+/** Module-level storage for binding hints */
+let globalBindingHints = {};
+/**
+* Create an env proxy that routes all binding access through the bridge
+*/
+function createEnvProxy(options = {}) {
+	const client = options.client ?? getClient();
+	const bindingProxies = /* @__PURE__ */ new Map();
+	const doProxyOptions = { transformResult: options.transformResult };
+	const serviceProxyOptions = { transformResult: options.transformResult };
+	const strict = options.strict === true;
+	const hints = {
+		...globalBindingHints,
+		...options.hints
+	};
+	return new Proxy({}, {
+		get(target, prop) {
+			if (typeof prop !== "string") return void 0;
+			if (bindingProxies.has(prop)) return bindingProxies.get(prop);
+			const hint = hints[prop];
+			if (!hint && strict) return;
+			let proxy;
+			switch (hint) {
+				case "kv":
+					proxy = createKVProxy(client, prop);
+					break;
+				case "r2":
+					proxy = createR2Proxy(client, prop);
+					break;
+				case "d1":
+					proxy = createD1Proxy(client, prop);
+					break;
+				case "do":
+					proxy = createDOProxy(client, prop, doProxyOptions);
+					break;
+				case "queue":
+					proxy = createQueueProxy(client, prop);
+					break;
+				case "ai":
+					proxy = createAIProxy(client, prop);
+					break;
+				case "service":
+					proxy = createServiceProxy(client, prop, serviceProxyOptions);
+					break;
+				case "sendEmail":
+					proxy = createSendEmailProxy(client, prop);
+					break;
+				case "workflow":
+					proxy = createWorkflowProxy(client, prop);
+					break;
+				case "secret":
+				case "var":
+					proxy = createSimpleBindingProxy(client, prop);
+					break;
+				default: proxy = createGenericBindingProxy(client, prop);
+			}
+			bindingProxies.set(prop, proxy);
+			return proxy;
+		},
+		has(target, prop) {
+			return typeof prop === "string" && (!strict || prop in hints);
+		},
+		ownKeys() {
+			return Object.keys(hints);
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (typeof prop === "string" && (!strict || prop in hints)) return {
+				configurable: true,
+				enumerable: true,
+				writable: false
+			};
+		}
+	});
+}
+function createGenericBindingProxy(client, bindingName) {
+	return new Proxy({}, { get(target, prop) {
+		if (typeof prop !== "string") return void 0;
+		if ([
+			"get",
+			"put",
+			"delete",
+			"list",
+			"getWithMetadata"
+		].includes(prop)) return createKVProxy(client, bindingName)[prop];
+		if ([
+			"idFromName",
+			"idFromString",
+			"newUniqueId",
+			"get"
+		].includes(prop)) return createDOProxy(client, bindingName)[prop];
+		if ([
+			"prepare",
+			"batch",
+			"exec",
+			"dump"
+		].includes(prop)) return createD1Proxy(client, bindingName)[prop];
+		if (["head"].includes(prop)) return createR2Proxy(client, bindingName)[prop];
+		return async (...args) => {
+			return client.call(`${bindingName}.${prop}`, args);
+		};
+	} });
+}
+function createSimpleBindingProxy(client, bindingName) {
+	let cachedValue;
+	let fetched = false;
+	let pendingValue = null;
+	const loadValue = () => {
+		if (fetched) return Promise.resolve(cachedValue);
+		if (!pendingValue) pendingValue = client.call(`${bindingName}.var.value`, []).then((value) => {
+			cachedValue = value;
+			fetched = true;
+			return value;
+		}).catch((error) => {
+			pendingValue = null;
+			throw error;
+		});
+		return pendingValue;
+	};
+	return {
+		then(resolve, reject) {
+			return loadValue().then(resolve ?? void 0, reject ?? void 0);
+		},
+		toString() {
+			if (!fetched) throw new Error(`Binding ${bindingName} not yet fetched. Use await.`);
+			return String(cachedValue);
+		}
+	};
+}
+let globalEnvProxy = null;
+/**
+* Get the global env proxy for bridge RPC.
+*
+* @internal
+* Internal bridge surface — not part of the documented public API. Prefer
+* `import { env } from 'devflare'`, which transparently picks the right
+* source (request context, test context, or bridge) for the current
+* environment. `bridgeEnv` is retained as an internal escape hatch for the
+* bridge implementation itself and may change without a major version bump.
+*
+* @example
+* ```ts
+* await bridgeEnv.MY_KV.get('key')
+* await bridgeEnv.MY_DO.get(id).fetch(request)
+* ```
+*/
+const bridgeEnv = new Proxy({}, { get(target, prop) {
+	if (!globalEnvProxy) globalEnvProxy = createEnvProxy({ lazy: true });
+	return globalEnvProxy[prop];
+} });
+/**
+* Initialize the env proxy with specific options
+*/
+function initEnv(options = {}) {
+	globalEnvProxy = createEnvProxy(options);
+	return globalEnvProxy;
+}
+/**
+* Set binding hints for better proxy creation
+* Hints help the bridge create optimized proxies for each binding type
+*/
+function setBindingHints(hints) {
+	globalBindingHints = {
+		...globalBindingHints,
+		...hints
+	};
+	globalEnvProxy = null;
+}
+//#endregion
+//#region src/runtime/context-events.ts
+function createLocals$1(locals) {
+	return locals ?? {};
+}
+/**
+* Builds the shared scaffold used by every event builder: a wrapped runtime env
+* (with SendEmail bindings proxied) plus a locals bag. Every event type layers
+* its specific fields on top of this shell.
+*/
+function prepareEventShell(env, options = {}) {
+	return {
+		env: wrapEnvSendEmailBindings(env),
+		locals: createLocals$1(options.locals)
+	};
+}
+function createAugmentedTarget(target, extra) {
+	return new Proxy(target, {
+		get(target, prop) {
+			if (prop in extra) return extra[prop];
+			const value = Reflect.get(target, prop, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+		has(target, prop) {
+			return prop in extra || prop in target;
+		},
+		ownKeys(target) {
+			return Array.from(new Set([...Reflect.ownKeys(target), ...Reflect.ownKeys(extra)]));
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (prop in extra) return {
+				configurable: true,
+				enumerable: true,
+				writable: false,
+				value: extra[prop]
+			};
+			return Reflect.getOwnPropertyDescriptor(target, prop);
+		}
+	});
+}
+function createBaseEvent(type, env, ctx, options = {}) {
+	return {
+		type,
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		request: options.request ?? null,
+		params: options.params
+	};
+}
+function createFetchEvent(request, env, ctx, options = {}) {
+	return createAugmentedTarget(request, {
+		type: "fetch",
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		url: new URL(request.url),
+		request,
+		params: options.params ?? {}
+	});
+}
+function createQueueEvent(batch, env, ctx, options = {}) {
+	return createAugmentedTarget(batch, {
+		type: "queue",
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		batch
+	});
+}
+function createScheduledEvent(controller, env, ctx, options = {}) {
+	return createAugmentedTarget(controller, {
+		type: "scheduled",
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		controller
+	});
+}
+function createEmailEvent(message, env, ctx, options = {}) {
+	return createAugmentedTarget(message, {
+		type: "email",
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		message
+	});
+}
+function createTailEvent(events, env, ctx, options = {}) {
+	return createAugmentedTarget(events, {
+		type: "tail",
+		ctx,
+		...prepareEventShell(env, { locals: options.locals }),
+		events
+	});
+}
+function createDurableObjectFetchEvent(request, env, state, options = {}) {
+	return createAugmentedTarget(request, {
+		type: "durable-object-fetch",
+		ctx: state,
+		state,
+		...prepareEventShell(env, { locals: options.locals }),
+		request
+	});
+}
+function createDurableObjectAlarmEvent(env, state, options = {}) {
+	return {
+		type: "durable-object-alarm",
+		ctx: state,
+		state,
+		...prepareEventShell(env, { locals: options.locals })
+	};
+}
+function createDurableObjectWebSocketMessageEvent(ws, message, env, state, options = {}) {
+	return createAugmentedTarget(ws, {
+		type: "durable-object-websocket-message",
+		ctx: state,
+		state,
+		...prepareEventShell(env, { locals: options.locals }),
+		ws,
+		message
+	});
+}
+function createDurableObjectWebSocketCloseEvent(ws, code, reason, wasClean, env, state, options = {}) {
+	return createAugmentedTarget(ws, {
+		type: "durable-object-websocket-close",
+		ctx: state,
+		state,
+		...prepareEventShell(env, { locals: options.locals }),
+		ws,
+		code,
+		reason,
+		wasClean
+	});
+}
+function createDurableObjectWebSocketErrorEvent(ws, error, env, state, options = {}) {
+	return createAugmentedTarget(ws, {
+		type: "durable-object-websocket-error",
+		ctx: state,
+		state,
+		...prepareEventShell(env, { locals: options.locals }),
+		ws,
+		error
+	});
+}
+function createDefaultEvent(env, ctx, request, type, locals) {
+	switch (type) {
+		case "fetch":
+			if (request && ctx) return createFetchEvent(request, env, ctx, { locals });
+			return createBaseEvent(type, env, ctx, {
+				locals,
+				request
+			});
+		case "durable-object-fetch":
+			if (request && ctx) return createDurableObjectFetchEvent(request, env, ctx, { locals });
+			return createBaseEvent(type, env, ctx, {
+				locals,
+				request
+			});
+		case "durable-object-alarm":
+			if (ctx) return createDurableObjectAlarmEvent(env, ctx, { locals });
+			return createBaseEvent(type, env, ctx, { locals });
+		case "queue":
+		case "scheduled":
+		case "email":
+		case "tail":
+		case "durable-object-websocket-message":
+		case "durable-object-websocket-close":
+		case "durable-object-websocket-error": return createBaseEvent(type, env, ctx, {
+			locals,
+			request
+		});
+		default: throw new Error(`createDefaultEvent: unknown event type ${String(type)}`);
+	}
+}
+//#endregion
+//#region src/runtime/validation.ts
+/**
+* Error thrown when accessing context properties outside an active handler trail
+*/
+var ContextAccessError = class ContextAccessError extends Error {
+	contextName;
+	propertyName;
+	constructor(contextName, propertyName, message) {
+		super(message ?? `Cannot access ${contextName}.${propertyName} outside of an active Devflare handler trail.\n\nThis typically happens when:\n  1. Accessing ${contextName} at module top-level (during import)\n  2. Accessing ${contextName} in a callback that runs after the handler ends\n  3. Accessing ${contextName} in a setTimeout/setInterval callback\n\nMove the access inside your handler function or middleware.`);
+		this.name = "ContextAccessError";
+		this.contextName = contextName;
+		this.propertyName = propertyName;
+	}
+	/**
+	* Builds a `ContextAccessError` for the "no active handler trail" failure mode
+	* (no AsyncLocalStorage store), with guidance toward the most common causes.
+	* Pass `message` to override the default `nodejs_compat`-mentioning guidance.
+	*/
+	static contextUnavailable(message) {
+		return new ContextAccessError("context", "<unavailable>", message ?? "Context not available. Devflare uses AsyncLocalStorage to carry the active event through fetch, queue, scheduled, email, tail, and Durable Object handler call chains.\n\nThis usually means one of:\n\n1. Accessing context at module top-level (runs at cold start, not per-request)\n2. Accessing context in setTimeout/setInterval callbacks\n3. Missing 'nodejs_compat' compatibility flag in your worker config\n\nFix: Move the access inside your handler, middleware, or a helper called from that handler trail.\nLearn more: https://devflare.dev/docs/context-errors");
+	}
+};
+function createContextProxy(getter, name, options = {}) {
+	const mutable = options.mutable ?? true;
+	return new Proxy({}, {
+		get(_target, prop) {
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) throw new ContextAccessError(name, String(prop));
+			return ctx[prop];
+		},
+		set(_target, prop, value) {
+			if (!mutable) throw new TypeError(`Cannot assign to '${String(prop)}' on '${name}' because it is read-only.\nUse 'locals' for mutable request-scoped data.`);
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) throw new ContextAccessError(name, String(prop));
+			ctx[prop] = value;
+			return true;
+		},
+		deleteProperty(_target, prop) {
+			if (!mutable) throw new TypeError(`Cannot delete property '${String(prop)}' from '${name}' because it is read-only.`);
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) return true;
+			return Reflect.deleteProperty(ctx, prop);
+		},
+		has(_target, prop) {
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) return false;
+			return prop in ctx;
+		},
+		ownKeys(_target) {
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) return [];
+			return Reflect.ownKeys(ctx);
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			const ctx = getter();
+			if (ctx === void 0 || ctx === null) return;
+			const descriptor = Reflect.getOwnPropertyDescriptor(ctx, prop);
+			if (!descriptor) return;
+			if (!mutable) return {
+				...descriptor,
+				writable: false
+			};
+			return descriptor;
+		}
+	});
+}
+//#endregion
+//#region src/runtime/context.ts
+const storage = new AsyncLocalStorage();
+function createLocals() {
+	return {};
+}
+function runWithContext(env, ctx, request, fn, type = "fetch") {
+	return runWithEventContext(createDefaultEvent(env, ctx, request, type, createLocals()), fn);
+}
+function runWithEventContext(event, fn) {
+	const context = {
+		env: event.env,
+		ctx: event.ctx,
+		request: event.request ?? null,
+		locals: event.locals,
+		type: event.type,
+		event
+	};
+	return storage.run(context, fn);
+}
+function getContext() {
+	const context = storage.getStore();
+	if (!context) throw ContextAccessError.contextUnavailable();
+	return context;
+}
+function getContextOrNull() {
+	return storage.getStore() ?? null;
+}
+function getEventContext() {
+	return getContext().event;
+}
+function getEventContextOrNull() {
+	return getContextOrNull()?.event ?? null;
+}
+function hasContext() {
+	return storage.getStore() !== void 0;
+}
+function createEventAccessor(name, matcher) {
+	const accessor = (() => {
+		const currentEvent = getEventContextOrNull();
+		if (!currentEvent) throw ContextAccessError.contextUnavailable();
+		if (!matcher(currentEvent)) throw ContextAccessError.contextUnavailable(`${name} is not available in the current '${currentEvent.type}' context.
+
+Devflare stores event objects in AsyncLocalStorage so helpers called within a handler can reach the active event.
+Use ${name}.safe() to return null instead of throwing, or call the getter that matches the active surface.`);
+		return currentEvent;
+	});
+	accessor.safe = () => {
+		const currentEvent = getEventContextOrNull();
+		return currentEvent && matcher(currentEvent) ? currentEvent : null;
+	};
+	return accessor;
+}
+function isFetchEvent(event) {
+	return event.type === "fetch" && event.request instanceof Request;
+}
+function isQueueEvent(event) {
+	return event.type === "queue" && "batch" in event;
+}
+function isScheduledEvent(event) {
+	return event.type === "scheduled" && "controller" in event;
+}
+function isEmailEvent(event) {
+	return event.type === "email" && "message" in event;
+}
+function isTailEvent(event) {
+	return event.type === "tail" && Array.isArray(event) && "events" in event;
+}
+function isDurableObjectEvent(event) {
+	return event.type.startsWith("durable-object-") && "state" in event;
+}
+function isDurableObjectFetchEvent(event) {
+	return event.type === "durable-object-fetch" && event.request instanceof Request;
+}
+function isDurableObjectAlarmEvent(event) {
+	return event.type === "durable-object-alarm" && "state" in event;
+}
+function isDurableObjectWebSocketMessageEvent(event) {
+	return event.type === "durable-object-websocket-message" && "ws" in event && "message" in event;
+}
+function isDurableObjectWebSocketCloseEvent(event) {
+	return event.type === "durable-object-websocket-close" && "ws" in event && "code" in event;
+}
+function isDurableObjectWebSocketErrorEvent(event) {
+	return event.type === "durable-object-websocket-error" && "ws" in event && "error" in event;
+}
+const getFetchEvent = createEventAccessor("getFetchEvent()", isFetchEvent);
+const getQueueEvent = createEventAccessor("getQueueEvent()", isQueueEvent);
+const getScheduledEvent = createEventAccessor("getScheduledEvent()", isScheduledEvent);
+const getEmailEvent = createEventAccessor("getEmailEvent()", isEmailEvent);
+const getTailEvent = createEventAccessor("getTailEvent()", isTailEvent);
+const getDurableObjectEvent = createEventAccessor("getDurableObjectEvent()", isDurableObjectEvent);
+const getDurableObjectFetchEvent = createEventAccessor("getDurableObjectFetchEvent()", isDurableObjectFetchEvent);
+const getDurableObjectAlarmEvent = createEventAccessor("getDurableObjectAlarmEvent()", isDurableObjectAlarmEvent);
+const getDurableObjectWebSocketMessageEvent = createEventAccessor("getDurableObjectWebSocketMessageEvent()", isDurableObjectWebSocketMessageEvent);
+const getDurableObjectWebSocketCloseEvent = createEventAccessor("getDurableObjectWebSocketCloseEvent()", isDurableObjectWebSocketCloseEvent);
+const getDurableObjectWebSocketErrorEvent = createEventAccessor("getDurableObjectWebSocketErrorEvent()", isDurableObjectWebSocketErrorEvent);
+//#endregion
+export { createTailEvent as A, createDurableObjectWebSocketCloseEvent as C, createFetchEvent as D, createEmailEvent as E, BridgeClient as F, getClient as I, createEnvProxy as M, initEnv as N, createQueueEvent as O, setBindingHints as P, createDurableObjectFetchEvent as S, createDurableObjectWebSocketMessageEvent as T, runWithContext as _, getDurableObjectFetchEvent as a, createContextProxy as b, getDurableObjectWebSocketMessageEvent as c, getEventContextOrNull as d, getFetchEvent as f, hasContext as g, getTailEvent as h, getDurableObjectEvent as i, bridgeEnv as j, createScheduledEvent as k, getEmailEvent as l, getScheduledEvent as m, getContextOrNull as n, getDurableObjectWebSocketCloseEvent as o, getQueueEvent as p, getDurableObjectAlarmEvent as r, getDurableObjectWebSocketErrorEvent as s, getContext as t, getEventContext as u, runWithEventContext as v, createDurableObjectWebSocketErrorEvent as w, createDurableObjectAlarmEvent as x, ContextAccessError as y };