experimental-a2 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- ed921d5: Make WebSocket multiplexing opt-in. A `ws` client now opens one socket per
+  session by default, and `server.fetch` binds that socket to the session in its
+  upgrade URL. Set `multiplex: true` on the client API and
+  `multiplexWebSocket: true` on the server fetch options to share one socket
+  across sessions.
+
+  Client route URLs may also be functions of `sessionId`. A2 resolves them for
+  each HTTP request or WebSocket reconnect. Multiplexed WebSockets remain
+  string-only because their connection does not belong to one session.
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/actor-client.d.ts

@@ -1,4 +1,4 @@
-import { c as ActorRefusedError } from "./actor-shared-BACubf4x.js";
+import { c as ActorRefusedError } from "./actor-shared-USo5MyuF.js";
 //#region src/actor-client.d.ts
 /** The loose shape of an `actor()` definition — carried type-only. */
 type AnyActorDefinition = {

package/dist/actor-react.d.ts

@@ -1,5 +1,5 @@
 import { a as ContractEvent, s as EventDefs } from "./reducer-DJKWm3cp.js";
-import { i as ActorPresenceMap, o as ActorPresenceValues } from "./actor-shared-BACubf4x.js";
+import { i as ActorPresenceMap, o as ActorPresenceValues } from "./actor-shared-USo5MyuF.js";
 import { ActorClientCall, ActorStateOf, AnyActorDefinition } from "./actor-client.js";
 import { Connection } from "./client.js";
 //#region src/actor-react.d.ts

package/dist/{actor-shared-BACubf4x.d.ts → actor-shared-USo5MyuF.d.ts}

@@ -1,5 +1,5 @@
 import { h as StandardSchemaV1 } from "./reducer-DJKWm3cp.js";
-import { f as ScheduleTiming } from "./server-CKY3_lbw.js";
+import { f as ScheduleTiming } from "./server-DgCrSuhB.js";
 //#region src/actor-shared.d.ts
 /**
  * A handler answered by throwing `NonRetriableError`: the event
@@ -133,4 +133,4 @@ type ActorClientEventDefs<S> = {
 };
 //#endregion
 export { ActorPresenceOf as a, ActorRefusedError as c, ActorSend as d, ActorPresenceMap as i, ActorScheduleOptions as l, ActorConcurrentContext as n, ActorPresenceValues as o, ActorContext as r, ActorProtocol as s, ActorClientEventDefs as t, ActorScheduleSend as u };
-//# sourceMappingURL=actor-shared-BACubf4x.d.ts.map
+//# sourceMappingURL=actor-shared-USo5MyuF.d.ts.map

package/dist/{actor-shared-BACubf4x.d.ts.map → actor-shared-USo5MyuF.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"actor-shared-BACubf4x.d.ts","names":[],"sources":["../src/actor-shared.ts"],"mappings":";;;;;;;;;cAgCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB"}
+{"version":3,"file":"actor-shared-USo5MyuF.d.ts","names":[],"sources":["../src/actor-shared.ts"],"mappings":";;;;;;;;;cAgCa,0BAA0B;;WAE5B;;WAEA;EACT,YAAY,eAAe,mBAAmB;;;;;;;;;KAepC;EACV;EACA;;;;;;;EAOA;;;KAIU,gBAAgB,UAAU,iBAAiB;EACrD,gBAAgB;IAEd;;KAIQ,oBAAoB,QAC7B,WAAW,cAAc,EAAE;;;;;;KAQlB,iBAAiB;GAExB,yBAAA,WAAW;IAAgB,OAAO,EAAE;IAAI;IAAc,IAAI;;;;;;;;;;;;KAanD,UAAU,iBACV,WAAW,eAAe,EAAE,MACjC,QAAQ,EAAE,eACV,OAAO,EAAE;;;;;;;;;KAWJ,uBAAuB;EAAmB;;;;;;;;;;;;KAY1C,kBAAkB,iBAClB,WAAW,eAAe,EAAE,MACjC,OAAO,EAAE,gBAAgB,SAAS,yBAAyB,iBAC3D,OAAO,EAAE,IAAI,SAAS,yBAAyB;;KAI1C,aAAa,UAAU;;EAEjC,OAAO;;EAEP;;EAEA;;EAEA,QAAQ;;EAER,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;;;;;;;KASlB,uBAAuB,UAAU;;EAE3C;;EAEA;;EAEA,QAAQ;;EAER,SAAS;IAAU,OAAO;IAAY;;;EAEtC,MAAM,UAAU;;EAEhB,UAAU,kBAAkB;;KAGlB,kBAAkB;EAC5B,OAAO;;EAEP;;EAEA;;;KAWU,qBAAqB;EAC/B,kBAAkB,iBAAiB,kBAAkB"}

package/dist/actor.d.ts

@@ -1,8 +1,8 @@
 import { i as Contract, s as EventDefs, t as Reducer } from "./reducer-DJKWm3cp.js";
 import { t as A2Store } from "./store-DGHeBtIQ.js";
-import { m as Session, n as A2Server, t as A2Scheduler } from "./server-CKY3_lbw.js";
+import { m as Session, n as A2Server, t as A2Scheduler } from "./server-DgCrSuhB.js";
 import { i as A2Telemetry } from "./telemetry-CpeclqB2.js";
-import { a as ActorPresenceOf, c as ActorRefusedError, d as ActorSend, i as ActorPresenceMap, l as ActorScheduleOptions, n as ActorConcurrentContext, o as ActorPresenceValues, r as ActorContext, s as ActorProtocol, t as ActorClientEventDefs, u as ActorScheduleSend } from "./actor-shared-BACubf4x.js";
+import { a as ActorPresenceOf, c as ActorRefusedError, d as ActorSend, i as ActorPresenceMap, l as ActorScheduleOptions, n as ActorConcurrentContext, o as ActorPresenceValues, r as ActorContext, s as ActorProtocol, t as ActorClientEventDefs, u as ActorScheduleSend } from "./actor-shared-USo5MyuF.js";
 //#region src/actor.d.ts
 /**
  * One event's handler: ordinary server code. Serial by default — read

package/dist/actor.js

@@ -1,6 +1,6 @@
 import { t as contract } from "./contract-48bUMgcL.js";
 import { n as NonRetriableError, t as A2Error } from "./errors-DCk6ch5n.js";
-import { a as parsePresenceSibling, i as sseResponse, r as setServerFetchHooks, t as createServer } from "./server-CBET-jSz.js";
+import { a as parsePresenceSibling, i as sseResponse, r as setServerFetchHooks, t as createServer } from "./server-DlLyvaSH.js";
 import { a as actorFailedSchema, c as isJsonTree, i as ActorRefusedError, l as openPresenceDefs, n as ACTOR_LANE, o as actorReducer, r as ACTOR_STATE_EVENT, s as actorStateSchema, t as ACTOR_FAILED_EVENT } from "./actor-shared-DI7J5upy.js";
 //#region src/actor.ts
 /**

package/dist/ai-server.d.ts

@@ -1,5 +1,5 @@
 import { a as ContractEvent, s as EventDefs } from "./reducer-DJKWm3cp.js";
-import { n as A2Server, p as ServerOptions } from "./server-CKY3_lbw.js";
+import { n as A2Server, p as ServerOptions } from "./server-DgCrSuhB.js";
 import { AIEventDefs, AIState, AgentDefinition, AgentToolContext, AgentToolEventDefs } from "./ai.js";
 import { Instructions, LanguageModel, TextStreamPart, ToolSet, ToolSet as ToolSet$1, UIMessage, UIMessageChunk, streamText } from "ai";
 //#region src/ai-sdk-step.d.ts

package/dist/ai-server.js

@@ -1,6 +1,6 @@
 import { t as A2Error } from "./errors-DCk6ch5n.js";
 import { f as consumeSchedulerSendFailure, p as installAmbientToolScopeStorage } from "./internal-DRXJ56EI.js";
-import { r as setServerFetchHooks, t as createServer } from "./server-CBET-jSz.js";
+import { r as setServerFetchHooks, t as createServer } from "./server-DlLyvaSH.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { convertToModelMessages, stepCountIs, streamText, toUIMessageStream } from "ai";
 //#region src/ai-sdk-step.ts

package/dist/ai.d.ts

@@ -1,5 +1,5 @@
 import { h as StandardSchemaV1, i as Contract, r as AppendInput, s as EventDefs, t as Reducer } from "./reducer-DJKWm3cp.js";
-import { s as HandlerContext } from "./server-CKY3_lbw.js";
+import { s as HandlerContext } from "./server-DgCrSuhB.js";
 import { FinishReason, JSONValue, LanguageModelUsage, UIMessage, UIMessageChunk } from "ai";
 //#region src/ai.d.ts
 type AgentStatus = "idle" | "generating" | "waiting" | "failed" | "closed";

package/dist/client.d.ts

@@ -141,19 +141,25 @@ type A2Client<D extends EventDefs, S, P extends PresenceDefs = Record<never, nev
   session(sessionId: string, options?: SessionOptions<D, S>): SessionClient<D, S, P>;
 };
 /**
- * The wire the client rides. The string form is one route serving GET
+ * The wire the client rides. The first form is one route serving GET
  * (SSE stream) + POST (push). `http` splits the verbs across two
  * routes, for when platform duration limits differ per verb. `ws`
- * rides everything — every session of this client — over one
- * multiplexed WebSocket, served by `sessionsSocket`.
+ * rides everything over WebSocket, one socket per session by default.
+ * Multiplexing every session of the client is an explicit opt-in.
  */
-type ClientApi = string | {
+type SessionUrl = string | ((sessionId: string) => string);
+type ClientApi = SessionUrl | {
   type: "http";
-  push: string;
-  stream: string;
+  push: SessionUrl;
+  stream: SessionUrl;
+} | {
+  type: "ws";
+  url: SessionUrl;
+  multiplex?: false;
 } | {
   type: "ws";
   url: string;
+  multiplex: true;
 };
 /**
  * The socket surface the `ws` transport drives — satisfied structurally
@@ -198,5 +204,5 @@ type CreateClientOptions<D extends EventDefs, S, P extends PresenceDefs = Record
 };
 declare function createClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P>;
 //#endregion
-export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, createClient };
+export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, SessionUrl, createClient };
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;KAqDY;;;;;;;KAQA;EACN;;EAEA;;EAEA;;EAEA,OAAO;;EAEP;EAAgB;;EAChB;;;;;;;;;;KAUM,WAAW,UAAU,aAAa,QAAQ,cAAc;WACzD,WAAW,QAAQ,cAAc;;KAGhC;;;;;;EAMV;;EAEA;;;KAIU;;EAEV;;EAEA;;EAEA;;;KAIU,gBACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aACF;;EAGE,UAAU,YAAY;;;EAIxB,OAAO;;;;;EAKP,QAAQ,cAAc;;;EAGtB;;EAEA,SAAS;EACT,YAAY;;;;;;;KAQF,sBAAsB,UAAU;;;;;;;;;;EAU1C,YAAY,QAAQ,cAAc;;KAGxB,cACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aAAa,GAAG,sBAAsB;WAC/B;EACT,UAAU;EACV,eAAe,gBAAgB,GAAG,GAAG;;;;;;;;;;EAUrC,QAAQ,QAAQ,YAAY,OAAO,WAAW;;;;;;;;;;;EAW9C,YAAY,UAAU,qBAAqB,QAAQ,cAAc;;;;;;;;;EASjE;;;;;;EAMA;;KAGU,eAAe,UAAU,WAAW;EAC9C,eAAe;EACf;;EAEA,gBAAgB,cAAc;;;EAG9B;;KAGU,SACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,QACE,mBACA,UAAU,eAAe,GAAG,KAC3B,cAAc,GAAG,GAAG;;;;;;;;;KAUb;EAEN;EAAc;EAAc;;EAC5B;EAAY;;;;;;;KAON;WACD;EACT,KAAK;EACL,MAAM,eAAe;EACrB,iBAAiB,cAAc;EAC/B,iBACE,iBACA,WAAW;IAAS;;EAEtB,iBACE,eACA,WAAW;IAAS;IAAc;;EAEpC,iBAAiB,eAAe;;KAGtB,kCAAkC,gBAAgB;KAElD,oBACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,SAAS,QAAQ,GAAG,GAAG;;EAEvB,KAAK;;EAEL,eAAe,WAAW;;;EAG1B,YAAY;;;EAGZ;;;;;;;;EAQA;;iBAirBc,aACd,UAAU,WACV,GACA,UAAU,eAAe,sBACzB,SAAS,oBAAoB,GAAG,GAAG,KAAK,SAAS,GAAG,GAAG"}
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;KAqDY;;;;;;;KAQA;EACN;;EAEA;;EAEA;;EAEA,OAAO;;EAEP;EAAgB;;EAChB;;;;;;;;;;KAUM,WAAW,UAAU,aAAa,QAAQ,cAAc;WACzD,WAAW,QAAQ,cAAc;;KAGhC;;;;;;EAMV;;EAEA;;;KAIU;;EAEV;;EAEA;;EAEA;;;KAIU,gBACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aACF;;EAGE,UAAU,YAAY;;;EAIxB,OAAO;;;;;EAKP,QAAQ,cAAc;;;EAGtB;;EAEA,SAAS;EACT,YAAY;;;;;;;KAQF,sBAAsB,UAAU;;;;;;;;;;EAU1C,YAAY,QAAQ,cAAc;;KAGxB,cACV,UAAU,WACV,GACA,UAAU,eAAe,wBACvB,aAAa,GAAG,sBAAsB;WAC/B;EACT,UAAU;EACV,eAAe,gBAAgB,GAAG,GAAG;;;;;;;;;;EAUrC,QAAQ,QAAQ,YAAY,OAAO,WAAW;;;;;;;;;;;EAW9C,YAAY,UAAU,qBAAqB,QAAQ,cAAc;;;;;;;;;EASjE;;;;;;EAMA;;KAGU,eAAe,UAAU,WAAW;EAC9C,eAAe;EACf;;EAEA,gBAAgB,cAAc;;;EAG9B;;KAGU,SACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,QACE,mBACA,UAAU,eAAe,GAAG,KAC3B,cAAc,GAAG,GAAG;;;;;;;;;KAUb,wBAAwB;KAExB,YACR;EACE;EAAc,MAAM;EAAY,QAAQ;;EAExC;EAAY,KAAK;EAAY;;EAE7B;EAAY;EAAa;;;;;;;KAOnB;WACD;EACT,KAAK;EACL,MAAM,eAAe;EACrB,iBAAiB,cAAc;EAC/B,iBACE,iBACA,WAAW;IAAS;;EAEtB,iBACE,eACA,WAAW;IAAS;IAAc;;EAEpC,iBAAiB,eAAe;;KAGtB,kCAAkC,gBAAgB;KAElD,oBACV,UAAU,WACV,GACA,UAAU,eAAe;EAEzB,SAAS,QAAQ,GAAG,GAAG;;EAEvB,KAAK;;EAEL,eAAe,WAAW;;;EAG1B,YAAY;;;EAGZ;;;;;;;;EAQA;;iBAi6Bc,aACd,UAAU,WACV,GACA,UAAU,eAAe,sBACzB,SAAS,oBAAoB,GAAG,GAAG,KAAK,SAAS,GAAG,GAAG"}

package/dist/client.js

@@ -20,10 +20,15 @@ import { c as isWireEvent, d as parseSocketFrame, f as presencePatchFromWire, l
 const PUSH_ATTEMPTS = 3;
 const DEFAULT_GC_TIME_MS = 3e5;
 const DEFAULT_HISTORY_LIMIT = 50;
+const sessionUrl = (url, sessionId) => {
+	const resolved = typeof url === "function" ? url(sessionId) : url;
+	if (typeof resolved !== "string") throw new TypeError("a session URL function must return a string");
+	return resolved;
+};
 const httpTransport = (routes, fetchImpl, presence) => ({
 	async *connect({ sessionId, startAfter, signal }) {
-		const sep = routes.stream.includes("?") ? "&" : "?";
-		const res = await fetchImpl(`${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`, {
+		const streamUrl = sessionUrl(routes.stream, sessionId);
+		const res = await fetchImpl(`${streamUrl}${streamUrl.includes("?") ? "&" : "?"}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`, {
 			headers: { accept: "text/event-stream" },
 			signal
 		});
@@ -75,7 +80,7 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 		}
 	},
 	async push(body) {
-		const res = await fetchImpl(routes.push, {
+		const res = await fetchImpl(sessionUrl(routes.push, body.sessionId), {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify(body)
@@ -88,8 +93,8 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 		throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `push failed with ${res.status}`);
 	},
 	async history({ sessionId, gte, lte }) {
-		const sep = routes.stream.includes("?") ? "&" : "?";
-		const res = await fetchImpl(`${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`, { headers: { accept: "application/json" } });
+		const streamUrl = sessionUrl(routes.stream, sessionId);
+		const res = await fetchImpl(`${streamUrl}${streamUrl.includes("?") ? "&" : "?"}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`, { headers: { accept: "application/json" } });
 		if (!res.ok) throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `history failed with ${res.status}`);
 		const rows = await res.json();
 		if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("STORE_UNAVAILABLE", "history response was not a list of events");
@@ -98,7 +103,7 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 	sendPresence(envelope) {
 		(async () => {
 			try {
-				await (await fetchImpl(routes.push, {
+				await (await fetchImpl(sessionUrl(routes.push, envelope.sessionId), {
 					method: "POST",
 					headers: { "content-type": "application/json" },
 					body: JSON.stringify(envelope)
@@ -109,6 +114,217 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 });
 /** `WebSocket.OPEN` — fixed by the spec, identical in every runtime. */
 const WS_OPEN = 1;
+const webSocketUrl = (value) => {
+	let resolved;
+	if (/^(https?|wss?):\/\//i.test(value)) resolved = new URL(value);
+	else {
+		const base = globalThis.location?.href;
+		if (base === void 0) throw new TypeError(`cannot resolve the relative ws url '${value}' without a browser location — pass an absolute ws:// or wss:// url`);
+		resolved = new URL(value, base);
+	}
+	if (resolved.protocol === "http:") resolved.protocol = "ws:";
+	else if (resolved.protocol === "https:") resolved.protocol = "wss:";
+	return resolved;
+};
+const socketReadyWaiters = () => {
+	const sessions = /* @__PURE__ */ new Map();
+	const notify = (sessionId) => {
+		const waiters = sessions.get(sessionId);
+		if (!waiters) return;
+		sessions.delete(sessionId);
+		for (const waiter of waiters) waiter();
+	};
+	const wait = (sessionId, maxWaitMs) => new Promise((resolve) => {
+		let waiters = sessions.get(sessionId);
+		if (!waiters) {
+			waiters = /* @__PURE__ */ new Set();
+			sessions.set(sessionId, waiters);
+		}
+		let settled = false;
+		const done = () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			waiters.delete(done);
+			if (waiters.size === 0) sessions.delete(sessionId);
+			resolve();
+		};
+		const timer = setTimeout(done, maxWaitMs);
+		timer.unref?.();
+		waiters.add(done);
+	});
+	return {
+		notify,
+		wait
+	};
+};
+const rejectPendingAcks = (pending) => {
+	if (pending.size === 0) return;
+	const error = new A2Error("STORE_UNAVAILABLE", "socket closed with the ack outstanding");
+	for (const waiter of pending.values()) waiter.reject(error);
+	pending.clear();
+};
+const sessionWsTransport = (url, webSocketImpl, presence) => {
+	const connections = /* @__PURE__ */ new Map();
+	const ready = socketReadyWaiters();
+	let nextReq = 1;
+	const socketUrl = (sessionId, startAfter) => {
+		const resolved = webSocketUrl(sessionUrl(url, sessionId));
+		resolved.searchParams.set("sessionId", sessionId);
+		resolved.searchParams.set("index", String(startAfter));
+		return resolved.href;
+	};
+	return {
+		async *connect({ sessionId, startAfter, signal }) {
+			if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
+			const socket = new webSocketImpl(socketUrl(sessionId, startAfter));
+			const connection = {
+				socket,
+				pending: /* @__PURE__ */ new Map()
+			};
+			connections.set(sessionId, connection);
+			const queue = [];
+			let ended = false;
+			let failure = null;
+			let wake = null;
+			const notify = () => {
+				wake?.();
+				wake = null;
+			};
+			const finish = (error) => {
+				if (ended) return;
+				ended = true;
+				failure = error;
+				if (connections.get(sessionId) === connection) connections.delete(sessionId);
+				rejectPendingAcks(connection.pending);
+				notify();
+			};
+			socket.addEventListener("open", () => {
+				if (connections.get(sessionId) !== connection || ended) return;
+				queue.push({ kind: "ping" });
+				notify();
+				ready.notify(sessionId);
+			});
+			socket.addEventListener("message", (event) => {
+				if (connections.get(sessionId) !== connection || ended) return;
+				if (typeof event.data !== "string") return;
+				const frame = parseSocketFrame(event.data);
+				if (frame === null) return;
+				switch (frame.kind) {
+					case "ack": {
+						const waiter = connection.pending.get(frame.req);
+						if (waiter === void 0) return;
+						connection.pending.delete(frame.req);
+						if (frame.sessionId !== void 0 || "events" in frame && frame.events.some((row) => row.sessionId !== sessionId)) {
+							waiter.reject(new A2Error("STORE_UNAVAILABLE", "ack does not belong to the socket session"));
+							return;
+						}
+						if ("events" in frame) waiter.resolve(frame.events);
+						else waiter.reject(frame.error);
+						return;
+					}
+					case "event":
+						if (frame.event.sessionId !== sessionId) return;
+						queue.push({
+							kind: "event",
+							event: frame.event
+						});
+						break;
+					case "presence":
+						if (presence && frame.sessionId === void 0) queue.push({
+							kind: "presence",
+							patch: frame.patch
+						});
+						break;
+					case "presence-snapshot":
+						if (presence && frame.sessionId === void 0) queue.push({
+							kind: "presence-snapshot",
+							snapshot: frame.snapshot
+						});
+						break;
+					case "ping":
+						queue.push(frame);
+						break;
+					case "subscribed":
+					case "unsubscribed": return;
+				}
+				notify();
+			});
+			socket.addEventListener("close", (event) => {
+				finish(event.code === 1e3 ? null : /* @__PURE__ */ new Error(`socket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`));
+			});
+			socket.addEventListener("error", () => {
+				finish(/* @__PURE__ */ new Error("socket error"));
+			});
+			const onAbort = () => {
+				finish(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("stream aborted"));
+				try {
+					socket.close(1e3);
+				} catch {}
+			};
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+			try {
+				for (;;) {
+					while (queue.length > 0) yield queue.shift();
+					if (ended) {
+						if (failure) throw failure;
+						return;
+					}
+					await new Promise((resolve) => {
+						wake = resolve;
+					});
+				}
+			} finally {
+				signal.removeEventListener("abort", onAbort);
+				finish(null);
+				try {
+					socket.close(1e3);
+				} catch {}
+			}
+		},
+		async push(body) {
+			const connection = connections.get(body.sessionId);
+			if (connection === void 0 || connection.socket.readyState !== WS_OPEN) throw new A2Error("STORE_UNAVAILABLE", "no open socket for the session");
+			const req = nextReq;
+			nextReq += 1;
+			return await new Promise((resolve, reject) => {
+				connection.pending.set(req, {
+					resolve,
+					reject
+				});
+				const frame = {
+					kind: "push",
+					req,
+					events: body.events
+				};
+				try {
+					connection.socket.send(JSON.stringify(frame));
+				} catch (cause) {
+					connection.pending.delete(req);
+					reject(new A2Error("STORE_UNAVAILABLE", "socket send failed", { cause }));
+				}
+			});
+		},
+		awaitReady(sessionId, maxWaitMs) {
+			if (connections.get(sessionId)?.socket.readyState === WS_OPEN) return Promise.resolve();
+			return ready.wait(sessionId, maxWaitMs);
+		},
+		sendPresence(envelope) {
+			const connection = connections.get(envelope.sessionId);
+			if (connection === void 0 || connection.socket.readyState !== WS_OPEN) return;
+			const frame = {
+				kind: "presence",
+				...envelope.presence
+			};
+			try {
+				connection.socket.send(JSON.stringify(frame));
+			} catch {
+				return;
+			}
+		}
+	};
+};
 const wakeChannel = (channel) => {
 	channel.wake?.();
 	channel.wake = null;
@@ -119,34 +335,16 @@ const subscribeFrame = (sessions) => {
 		sessions
 	});
 };
-const wsTransport = (url, webSocketImpl, presence) => {
+const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 	const channels = /* @__PURE__ */ new Map();
 	const pending = /* @__PURE__ */ new Map();
 	/** Push retries parked in `awaitReady`, flushed per session on its
 	* subscribe confirmation. */
-	const readyWaiters = /* @__PURE__ */ new Map();
+	const ready = socketReadyWaiters();
 	let socket = null;
 	let socketOpen = false;
 	let watchdog;
 	let nextReq = 1;
-	const flushReadyWaiters = (sessionId) => {
-		const waiters = readyWaiters.get(sessionId);
-		if (!waiters) return;
-		readyWaiters.delete(sessionId);
-		for (const waiter of waiters) waiter();
-	};
-	const socketUrl = () => {
-		let resolved;
-		if (/^(https?|wss?):\/\//i.test(url)) resolved = new URL(url);
-		else {
-			const base = globalThis.location?.href;
-			if (base === void 0) throw new TypeError(`cannot resolve the relative ws url '${url}' without a browser location — pass an absolute ws:// or wss:// url`);
-			resolved = new URL(url, base);
-		}
-		if (resolved.protocol === "http:") resolved.protocol = "ws:";
-		else if (resolved.protocol === "https:") resolved.protocol = "wss:";
-		return resolved.href;
-	};
 	const trySend = (data) => {
 		if (socket === null || !socketOpen) return;
 		try {
@@ -169,11 +367,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 		socketOpen = false;
 		clearTimeout(watchdog);
 		watchdog = void 0;
-		if (pending.size > 0) {
-			const rejection = new A2Error("STORE_UNAVAILABLE", "socket closed with the ack outstanding");
-			for (const waiter of pending.values()) waiter.reject(rejection);
-			pending.clear();
-		}
+		rejectPendingAcks(pending);
 		return current;
 	};
 	const failSocket = (failure) => {
@@ -218,7 +412,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 				if (channel === void 0 || channel.ended || channel.live) return;
 				channel.live = true;
 				deliver(channel, { kind: "ping" });
-				flushReadyWaiters(frame.sessionId);
+				ready.notify(frame.sessionId);
 				return;
 			}
 			case "unsubscribed": {
@@ -267,7 +461,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 	const ensureSocket = () => {
 		if (socket !== null) return;
 		if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
-		const created = new webSocketImpl(socketUrl());
+		const created = new webSocketImpl(webSocketUrl(url).href);
 		socket = created;
 		socketOpen = false;
 		armWatchdog(created);
@@ -378,25 +572,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 		awaitReady(sessionId, maxWaitMs) {
 			const channel = channels.get(sessionId);
 			if (channel !== void 0 && channel.live && !channel.ended && socketOpen) return Promise.resolve();
-			return new Promise((resolve) => {
-				let waiters = readyWaiters.get(sessionId);
-				if (!waiters) {
-					waiters = /* @__PURE__ */ new Set();
-					readyWaiters.set(sessionId, waiters);
-				}
-				let settled = false;
-				const done = () => {
-					if (settled) return;
-					settled = true;
-					clearTimeout(timer);
-					waiters.delete(done);
-					if (waiters.size === 0) readyWaiters.delete(sessionId);
-					resolve();
-				};
-				const timer = setTimeout(done, maxWaitMs);
-				timer.unref?.();
-				waiters.add(done);
-			});
+			return ready.wait(sessionId, maxWaitMs);
 		},
 		sendPresence(envelope) {
 			const channel = channels.get(envelope.sessionId);
@@ -411,7 +587,7 @@ const wsTransport = (url, webSocketImpl, presence) => {
 	};
 };
 const transportFor = (api, fetchImpl, webSocketImpl, presence) => {
-	if (typeof api === "string") return httpTransport({
+	if (typeof api === "string" || typeof api === "function") return httpTransport({
 		push: api,
 		stream: api
 	}, fetchImpl, presence);
@@ -419,7 +595,11 @@ const transportFor = (api, fetchImpl, webSocketImpl, presence) => {
 		push: api.push,
 		stream: api.stream
 	}, fetchImpl, presence);
-	return wsTransport(api.url, webSocketImpl, presence);
+	if (api.multiplex === true) {
+		if (typeof api.url !== "string") throw new TypeError("a multiplexed WebSocket URL must be a string");
+		return multiplexedWsTransport(api.url, webSocketImpl, presence);
+	}
+	return sessionWsTransport(api.url, webSocketImpl, presence);
 };
 function createClient(options) {
 	const { reducer, api } = options;