@alexkroman1/aai-ui 5.14.0 → 6.2.0

package/dist/{message-list-CcjgWRVZ.js → message-list-BwA3rdPi.js}

@@ -261,11 +261,25 @@ const DOT_STYLES = [
 	animation: "aai-bounce 1.4s infinite ease-in-out both",
 	animationDelay: `${delay}s`
 }));
-/** Animated three-dot "thinking" indicator. @internal */
+/**
+* Animated three-dot "thinking" indicator.
+*
+* `role="status"` with a label, for the same reason `ConsoleShell` announces
+* its error banner: three animated dots are the only signal that the agent is
+* working on a reply, and to a screen reader they are three empty `<div>`s.
+* It is also the indicator's semantic handle — a spec asserting its presence by
+* counting `.rounded-full` elements breaks when the three dots become a spinner
+* (correct behaviour, red test) and again when any sibling row gains a round
+* badge (wrong behaviour, green test).
+*
+* @internal
+*/
 function ThinkingDots() {
 	const theme = useTheme();
 	const muted = inkTint(theme.text, theme.surface, 75);
 	return /* @__PURE__ */ jsx("div", {
+		role: "status",
+		"aria-label": "Thinking",
 		className: "flex items-center gap-2 text-sm font-medium min-h-5",
 		style: { color: muted },
 		children: DOT_STYLES.map((style, i) => /* @__PURE__ */ jsx("div", {

package/dist/page.d.ts

@@ -0,0 +1,88 @@
+/** @jsxImportSource react */
+/**
+ * `page()` — mount a WORKFLOW APP's UI: React, theme, no session.
+ *
+ * The twin of `client()` for an agent whose front door is a form rather than a
+ * microphone (`workflowApp()`). It is a separate entry rather than
+ * an option on `client()` because of what `client()` unavoidably does: it
+ * constructs a `SessionCore`, which owns a WebSocket URL provider, an audio
+ * graph, and a microphone request. A flag would have to make all of that
+ * conditional, and every session hook would then have to answer "what does this
+ * mean with no session?" — so the honest split is two mounts. A page that wants
+ * voice uses `client()`; a page that wants neither audio nor a socket uses this.
+ *
+ * Authoring is otherwise identical — the file is still `client.tsx`, still
+ * React, still Tailwind, still the same theme tokens — so a workflow app reads
+ * like every other agent. What it reaches for instead of `useSession()` is
+ * `createWorkflowApi()` / `useWorkflowRun()`.
+ */
+import { type ComponentType } from "react";
+import type { ClientTheme } from "./types.ts";
+/**
+ * Configuration for {@link page}.
+ *
+ * @public
+ */
+export type PageConfig = {
+    /**
+     * The root component. Required — a workflow app has no default shell to fall
+     * back to, because there is no session for one to render.
+     */
+    component: ComponentType;
+    /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
+    target?: string | HTMLElement;
+    /**
+     * Page title. Set only when given, so a title the HTML shell declared is never
+     * clobbered — the same rule `client()`'s custom-component tier follows.
+     */
+    name?: string;
+    /** Theme color overrides, read by the same tokens the voice components use. */
+    theme?: ClientTheme;
+};
+/**
+ * Handle returned by {@link page}. `Disposable`, so `using` works.
+ *
+ * @public
+ */
+export type PageHandle = {
+    /** Unmount the React tree. */
+    dispose(): void;
+    /** Alias for `dispose` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Mount a page for an agent whose work happens in workflows.
+ *
+ * There is deliberately no session, no microphone, and no socket: the component
+ * talks to the agent over the workflow HTTP API
+ * (`createWorkflowApi`/`useWorkflowRun`), which is durable and outlives the tab.
+ *
+ * @example
+ * ```tsx
+ * import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+ * import { useState } from "react";
+ *
+ * // Hoisted: a client built in render is a new object every render.
+ * const api = createWorkflowApi();
+ *
+ * function App() {
+ *   const [runId, setRunId] = useState<string>();
+ *   const { run } = useWorkflowRun(runId, { api });
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => void api.start("digest", { topic: "ai" }).then(setRunId)}
+ *     >
+ *       {run ? run.status : "Start"}
+ *     </button>
+ *   );
+ * }
+ *
+ * page({ name: "Digest", component: App });
+ * ```
+ *
+ * @throws If the target element is not found in the DOM.
+ *
+ * @public
+ */
+export declare function page(config: PageConfig): PageHandle;

package/dist/{session-core-BA8H3qtF.js → session-core-ClKdVgRU.js}

@@ -1,7 +1,8 @@
 import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
 import { CLIENT_CONFIG_PATH, ClientConfigResponseSchema, ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
-import { DEFAULT_MAX_HISTORY, WS_OPEN, errorMessage, safeJsonParse, toArgsRecord } from "@alexkroman1/aai";
-import { createEpoch } from "@alexkroman1/aai/internal";
+import { DEFAULT_MAX_HISTORY, errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { omitUndefined, toArgsRecord } from "@alexkroman1/aai/utils";
+import { WS_OPEN, createEpoch } from "@alexkroman1/aai/internal";
 import ReconnectingWebSocket from "partysocket/ws";
 //#region client-config.ts
 /**
@@ -252,6 +253,180 @@ function reconnectPending(socket) {
 	return socket instanceof ReconnectingWebSocket && socket.shouldReconnect && socket.retryCount < RECONNECT_OPTIONS.maxRetries;
 }
 //#endregion
+//#region session-core-url.ts
+/** Build the session WebSocket URL from the platform URL and resume state. */
+function buildWsUrl(platformUrl, resume, sessionId) {
+	return applyResumeParams(buildAgentUrl(platformUrl, "websocket"), resume, sessionId);
+}
+/**
+* Turn a broker-provided session URL (`sessionUrl` from `GET client-config`
+* — the agent's live sandbox endpoint) into this attempt's connect URL.
+*/
+function buildBrokeredWsUrl(sessionUrl, resume, sessionId) {
+	return applyResumeParams(new URL(sessionUrl), resume, sessionId);
+}
+const WS_PROTOCOLS = {
+	"https:": "wss:",
+	"http:": "ws:"
+};
+function applyResumeParams(wsUrl, resume, sessionId) {
+	wsUrl.protocol = WS_PROTOCOLS[wsUrl.protocol] ?? wsUrl.protocol;
+	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
+	else if (resume) wsUrl.searchParams.set("resume", "1");
+	return wsUrl;
+}
+//#endregion
+//#region session-resume-store.ts
+/**
+* Where a session id survives a page RELOAD.
+*
+* The id is what `?sessionId=` presents on reconnect, and it is the key the
+* agent's slot state and event log live under — so a reload that cannot produce
+* it starts a brand-new session, and a UI driven by `useAgentState` comes back
+* empty even though the agent still holds the cart. The server side of the
+* reconstitution was already built (`pushStateSnapshot` force-pushes the
+* projection after hydration on every start, `state.updated` lands in
+* `agentState`); what was missing is that nothing in the browser remembered the
+* id across a reload. `onSessionId`/`resumeSessionId` let a client wire it by
+* hand and exactly one of fourteen templates did, which is the shape of a
+* default in the wrong place.
+*
+* **`sessionStorage`, deliberately, and this is the opposite call from the
+* studio's session token.** A reload and a same-tab navigation survive it; a new
+* tab and a visit tomorrow do not, which is what we want here rather than a
+* limitation: presenting a day-old id suppresses the greeting
+* (`parseWsUpgradeParams` keys that off the id's mere presence) and rejoins a
+* conversation whose context is long gone. The studio token is a credential
+* whose value is not being asked to sign out; this is a pointer into a live call.
+*
+* Keyed by the agent's own URL, so two agents served from one origin — which is
+* every deployed agent, at `/:slug/` — cannot inherit each other's session.
+*
+* Every access is guarded: storage throws outright in some contexts (Safari
+* private mode, storage blocked by policy), and a session that cannot be
+* remembered must degrade to today's behaviour rather than failing to start.
+*/
+const PREFIX = "aai:session:";
+/** One agent's slot in storage. */
+function keyFor(platformUrl) {
+	try {
+		return `${PREFIX}${new URL(platformUrl, globalThis.location?.href).href}`;
+	} catch {
+		return `${PREFIX}${platformUrl}`;
+	}
+}
+/** The stored session id for this agent, or undefined. @internal */
+function readStoredSessionId(platformUrl) {
+	try {
+		return globalThis.sessionStorage?.getItem(keyFor(platformUrl)) ?? void 0;
+	} catch {
+		return;
+	}
+}
+/** Remember this agent's session id for the next load. @internal */
+function writeStoredSessionId(platformUrl, sessionId) {
+	try {
+		globalThis.sessionStorage?.setItem(keyFor(platformUrl), sessionId);
+	} catch {}
+}
+/**
+* Forget it, so the next load is a NEW session.
+*
+* Called from `end()`, which is the clear-and-forget the "New Conversation"
+* button runs: leaving the id behind there would have the next load rejoin the
+* conversation the user just discarded, greeting suppressed.
+*
+* @internal
+*/
+function clearStoredSessionId(platformUrl) {
+	try {
+		globalThis.sessionStorage?.removeItem(keyFor(platformUrl));
+	} catch {}
+}
+//#endregion
+//#region session-core-dial.ts
+/**
+* How the next connection attempt is DIALLED, and the resume identity it dials
+* with.
+*
+* Split out of `session-core.ts` at the 500-line cap, along the seam that file
+* already established when it moved socket plumbing into
+* `session-core-reconnect.ts`: the state machine there reads as protocol logic,
+* and this is the address it sends it to. What makes it one module rather than
+* three extracted functions is that the three pieces of mutable state involved —
+* the session id, whether this connection has ever completed a handshake, and
+* whether the server is a broker — are read by nothing else in the core, and
+* every one of them is only meaningful in the sentence "the URL for the next
+* attempt".
+*/
+/** @internal */
+function createDialer(options) {
+	/**
+	* The session ID to resume: seeded from `options.resumeSessionId`, else from
+	* what a previous LOAD of this page stored, then kept current from every
+	* `config` frame. Reconnect URLs carry it as `?sessionId=<id>` so the server
+	* re-registers the SAME session id — that key is what the session's slot state
+	* and event log live under, so an attempt that omits it gets a fresh session
+	* with none of the agent's context.
+	*
+	* Reading it from storage is what makes a page RELOAD resume, and so what makes
+	* the server's `syncState` push reach a UI that would otherwise come back
+	* empty. See `session-resume-store.ts`.
+	*/
+	let sessionId = options.resumeSessionId ?? readStoredSessionId(options.platformUrl);
+	/** Whether a handshake has completed on this core — the `resume=1` fallback. */
+	let hasConnected = false;
+	/**
+	* Whether `platformUrl` is a broker (its `client-config` names a
+	* `sessionUrl`). A server is one or it isn't — it never flips mid-session — so
+	* once a non-broker is observed, later reconnects skip the `client-config`
+	* re-fetch that would only fall through to `buildWsUrl` (every reconnect on
+	* `aai dev` / self-hosted otherwise pays a wasted GET). `undefined` until the
+	* first fetch settles.
+	*/
+	let serverIsBroker;
+	/**
+	* The WebSocket URL for the *next* connection attempt. Evaluated per attempt
+	* (partysocket takes it as an async URL provider):
+	*
+	* - `GET client-config` is re-fetched every attempt. When it names a
+	*   `sessionUrl` — the platform's broker pointing at the agent's live sandbox
+	*   — the session connects DIRECTLY there. The URL changes when the sandbox is
+	*   replaced (idle eviction, redeploy), which is exactly when a reconnect
+	*   happens, so per-attempt brokering is what makes reconnects land on the
+	*   replacement. Without one (`aai dev`, older servers), the same-origin
+	*   `websocket` path is used.
+	* - Once the first `config` arrives, every reconnect carries `?sessionId=<id>`
+	*   and the server resumes the SAME session (id, tool state) instead of minting
+	*   a new one. `resume=1` remains only as the greeting-suppression fallback for
+	*   a server whose config carried no id.
+	*/
+	async function url() {
+		const cfg = serverIsBroker === false ? null : await loadClientConfig(options.platformUrl);
+		if (cfg) serverIsBroker = cfg.sessionUrl !== void 0;
+		return (cfg?.sessionUrl ? buildBrokeredWsUrl(cfg.sessionUrl, hasConnected, sessionId) : buildWsUrl(options.platformUrl, hasConnected, sessionId)).toString();
+	}
+	return {
+		url,
+		open: () => {
+			if (options.WebSocket) return new options.WebSocket(buildWsUrl(options.platformUrl, hasConnected, sessionId).toString());
+			return openReconnectingSocket(url);
+		},
+		configured: (sid) => {
+			if (sid) {
+				sessionId = sid;
+				writeStoredSessionId(options.platformUrl, sid);
+			}
+			hasConnected = true;
+		},
+		forget: () => {
+			sessionId = void 0;
+			clearStoredSessionId(options.platformUrl);
+			hasConnected = false;
+		}
+	};
+}
+//#endregion
 //#region session-core-handshake.ts
 /**
 * The deadline on a socket that opened but never became a session.
@@ -287,6 +462,8 @@ const HANDSHAKE_TIMEOUT_MS = 1e4;
 * budget for this failure mode — without one, a permanently wedged peer would
 * be re-dialed every ~10s forever, which is the unbounded retry loop
 * `RECONNECT_OPTIONS.maxRetries` exists to prevent.
+*
+* CONSECUTIVE is the whole of it, and only `succeeded()` says so — see its doc.
 */
 const MAX_HANDSHAKE_TIMEOUTS = 3;
 /**
@@ -322,7 +499,11 @@ function createHandshakeGuard(opts) {
 			disarm();
 			timer = setTimeout(fire, HANDSHAKE_TIMEOUT_MS);
 		},
-		disarm
+		disarm,
+		succeeded() {
+			disarm();
+			timeouts = 0;
+		}
 	};
 }
 //#endregion
@@ -346,7 +527,7 @@ const MAX_MESSAGES = DEFAULT_MAX_HISTORY;
 const MAX_PREINIT_AUDIO_CHUNKS = 100;
 /**
 * Snapshot fields cleared when a session's conversation state is wiped —
-* shared by the initial snapshot, `resetState()`, and the server `reset` event.
+* shared by the initial snapshot, `resetState()`, and `session.reset`.
 * The empty arrays are safe to share: snapshot collections are never mutated
 * in place, only replaced.
 */
@@ -404,7 +585,7 @@ function createMessageHandlers(deps) {
 		});
 	}
 	/**
-	* `agent_transcript` carries the reply's text so far as a full-replacement
+	* The agent-transcript events carry the reply's text so far as a full-replacement
 	* snapshot (see the protocol schema), so it renders as the live assistant
 	* bubble and only becomes a message when the reply closes. Pipeline mode sends
 	* one per piece of speech, so appending each would break a single reply into a
@@ -418,7 +599,7 @@ function createMessageHandlers(deps) {
 		updateState({ agentTranscript: text });
 	}
 	/**
-	* The reply is over (`reply_done`, or `cancelled` for a barge-in): move
+	* The reply is over (`reply.completed`, or `reply.cancelled` for a barge-in): move
 	* whatever was spoken into the conversation. A cancelled reply still keeps its
 	* text — the caller heard that much, and dropping it would leave the
 	* transcript claiming the agent never spoke.
@@ -459,7 +640,8 @@ function createMessageHandlers(deps) {
 	/**
 	* Return to "listening" at a turn boundary — unless the session is over.
 	*
-	* `reply_done`, `cancelled` and `reset` each wrote `state: "listening"`
+	* `reply.completed`, `reply.cancelled` and `session.reset` each wrote
+	* `state: "listening"`
 	* unconditionally, which is the second half of the same bug
 	* `clearRecoveredError`'s latch covers: the host's fatal paths all call
 	* `terminate()`, and terminating emits `onCancelled()`. So the frame that
@@ -495,22 +677,23 @@ function createMessageHandlers(deps) {
 	}
 	/** Single entry point for all server->client session events. */
 	function handleEvent(e) {
-		if (e.type !== "error") clearRecoveredError();
+		if (e.type !== "error.reported") clearRecoveredError();
 		switch (e.type) {
-			case "speech_started":
+			case "speech.started":
 				updateState({ userTranscript: "" });
 				break;
-			case "speech_stopped": break;
-			case "user_transcript":
+			case "speech.stopped": break;
+			case "user-transcript.committed":
 				handleUserTranscriptEvent(e.text);
 				break;
-			case "user_transcript_partial":
+			case "user-transcript.updated":
 				updateState({ userTranscript: e.text });
 				break;
-			case "agent_transcript":
+			case "agent-transcript.updated":
+			case "agent-transcript.committed":
 				handleAgentTranscriptEvent(e.text);
 				break;
-			case "tool_call":
+			case "tool.called":
 				updateState({ toolCalls: appendCapped(getSnapshot().toolCalls, {
 					callId: e.toolCallId,
 					name: e.toolName,
@@ -520,7 +703,7 @@ function createMessageHandlers(deps) {
 					afterMessageId: getSnapshot().messages.at(-1)?.id ?? -1
 				}, MAX_MESSAGES) });
 				break;
-			case "tool_call_done": {
+			case "tool.completed": {
 				const tcs = getSnapshot().toolCalls;
 				const idx = tcs.findIndex((tc) => tc.callId === e.toolCallId);
 				if (idx !== -1) {
@@ -535,31 +718,53 @@ function createMessageHandlers(deps) {
 				}
 				break;
 			}
-			case "reply_done":
+			case "reply.completed":
 				commitAgentTranscript();
 				toListening();
 				break;
-			case "cancelled":
+			case "reply.cancelled":
 				conn.turn.bump();
 				conn.voiceIO?.flush();
 				commitAgentTranscript();
 				toListening({ userTranscript: null });
 				break;
-			case "reset":
+			case "session.reset":
 				conn.turn.bump();
 				conn.voiceIO?.flush();
 				toListening(conn.fatalError ? {} : CLEARED_SESSION_STATE);
 				break;
-			case "custom_event":
+			case "custom.emitted":
 				appendCustomEvent(e.event, e.data);
 				break;
-			case "agent_state":
+			case "state.updated":
 				updateState({ agentState: e.state });
 				break;
-			case "error":
+			case "history.restored": {
+				messageSeq = 0;
+				toolCallSeq = 0;
+				const restored = e.messages.slice(-MAX_MESSAGES).map((m) => ({
+					id: ++messageSeq,
+					role: m.role,
+					content: m.content
+				}));
+				updateState({
+					messages: restored,
+					toolCalls: e.toolCalls.slice(-MAX_MESSAGES).map((tc) => ({
+						callId: tc.callId,
+						name: tc.name,
+						args: toArgsRecord(tc.args),
+						status: tc.status,
+						...omitUndefined({ result: tc.result }),
+						seq: ++toolCallSeq,
+						afterMessageId: restored[tc.afterMessageIndex]?.id ?? -1
+					}))
+				});
+				break;
+			}
+			case "error.reported":
 				handleErrorEvent(e);
 				break;
-			case "idle_timeout":
+			case "session.timed-out":
 				deps.conn.retiredByServer = true;
 				break;
 			default: break;
@@ -619,7 +824,7 @@ function createMessageHandlers(deps) {
 			return;
 		}
 		const msg = parsed.data;
-		if (msg.type === "config") {
+		if (msg.type === "session.configured") {
 			conn.fatalError = false;
 			return {
 				sampleRate: msg.sampleRate,
@@ -627,7 +832,7 @@ function createMessageHandlers(deps) {
 				sid: msg.sessionId
 			};
 		}
-		if (msg.type === "audio_done") {
+		if (msg.type === "audio.completed") {
 			playAudioDone();
 			return;
 		}
@@ -639,29 +844,6 @@ function createMessageHandlers(deps) {
 	};
 }
 //#endregion
-//#region session-core-url.ts
-/** Build the session WebSocket URL from the platform URL and resume state. */
-function buildWsUrl(platformUrl, resume, sessionId) {
-	return applyResumeParams(buildAgentUrl(platformUrl, "websocket"), resume, sessionId);
-}
-/**
-* Turn a broker-provided session URL (`sessionUrl` from `GET client-config`
-* — the agent's live sandbox endpoint) into this attempt's connect URL.
-*/
-function buildBrokeredWsUrl(sessionUrl, resume, sessionId) {
-	return applyResumeParams(new URL(sessionUrl), resume, sessionId);
-}
-const WS_PROTOCOLS = {
-	"https:": "wss:",
-	"http:": "ws:"
-};
-function applyResumeParams(wsUrl, resume, sessionId) {
-	wsUrl.protocol = WS_PROTOCOLS[wsUrl.protocol] ?? wsUrl.protocol;
-	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
-	else if (resume) wsUrl.searchParams.set("resume", "1");
-	return wsUrl;
-}
-//#endregion
 //#region session-core.ts
 /**
 * Framework-agnostic voice session core.
@@ -755,25 +937,7 @@ function createSessionCore(options) {
 		preInitDone: false
 	};
 	let connectionController = null;
-	let hasConnected = false;
-	/**
-	* The session ID to resume: seeded from `options.resumeSessionId`, then
-	* kept current from every `config` frame. Reconnect URLs carry it as
-	* `?sessionId=<id>` so the server re-registers the SAME session id —
-	* that key is what per-session tool state (`ctx.state`) lives under, so
-	* a reconnect that omits it gets a fresh session with none of the
-	* agent's context, greeting suppression aside.
-	*/
-	let sessionId = options.resumeSessionId;
-	/**
-	* Whether `platformUrl` is a broker (its `client-config` names a
-	* `sessionUrl`). A server is one or it isn't — it never flips mid-session
-	* — so once a non-broker is observed, later reconnects skip the
-	* `client-config` re-fetch that would only fall through to `buildWsUrl`
-	* (every reconnect on `aai dev` / self-hosted otherwise pays a wasted GET).
-	* `undefined` until the first fetch settles.
-	*/
-	let serverIsBroker;
+	const dialer = createDialer(options);
 	function cleanupAudio() {
 		conn.audioSetupInFlight = false;
 		conn.turn.bump();
@@ -814,51 +978,21 @@ function createSessionCore(options) {
 		conn.ws?.close();
 		conn.ws = null;
 	}
-	/** React to the server's `config` message: record it, set up the audio
-	*  path for the session's mode, and replay history on reconnect. */
-	function onServerConfig(config) {
-		if (config.sid) {
-			sessionId = config.sid;
-			options.onSessionId?.(config.sid);
-		}
-		const isReconnect = hasConnected;
-		hasConnected = true;
-		initAudioCapture(conn, config, audioDeps);
-		if (isReconnect && currentSnapshot.messages.length > 0) sendJson({
-			type: "history",
-			messages: currentSnapshot.messages.map((m) => ({
-				role: m.role,
-				content: m.content
-			}))
-		});
-	}
 	/**
-	* The WebSocket URL for the *next* connection attempt. Evaluated per
-	* attempt (partysocket takes it as an async URL provider):
+	* React to the server's `session.configured` frame: record it and set up the
+	* session's audio path.
 	*
-	* - `GET client-config` is re-fetched every attempt. When it names a
-	*   `sessionUrl` — the platform's broker pointing at the agent's live
-	*   sandbox — the session connects DIRECTLY there. The URL changes when
-	*   the sandbox is replaced (idle eviction, redeploy), which is exactly
-	*   when a reconnect happens, so per-attempt brokering is what makes
-	*   reconnects land on the replacement. Without one (`aai dev`, older
-	*   servers), the same-origin `websocket` path is used.
-	* - Once the first `config` arrives, every reconnect carries
-	*   `?sessionId=<id>` and the server resumes the SAME session (id, tool
-	*   state) instead of minting a new one. `resume=1` remains only as the
-	*   greeting-suppression fallback for a server whose config carried no id.
+	* **It no longer replays history, and the deletion is the point.** A reconnect
+	* used to push this snapshot's `messages` back, making the CLIENT the authority
+	* on the agent's memory; the server restores the conversation from its own
+	* retained event stream now, which also covers what a client cannot — a second
+	* tab, a call resuming onto a replacement sandbox, a reopened tab. This
+	* snapshot's `messages` are untouched: nothing clears the transcript on screen.
 	*/
-	async function currentWsUrl() {
-		const cfg = serverIsBroker === false ? null : await loadClientConfig(options.platformUrl);
-		if (cfg) serverIsBroker = cfg.sessionUrl !== void 0;
-		return (cfg?.sessionUrl ? buildBrokeredWsUrl(cfg.sessionUrl, hasConnected, sessionId) : buildWsUrl(options.platformUrl, hasConnected, sessionId)).toString();
-	}
-	/** Open a socket: an injected constructor as-is (tests — connects to the
-	*  same-origin path, no brokering), or partysocket's reconnecting
-	*  WebSocket — same interface, plus reconnect-on-close. */
-	function openSocket() {
-		if (options.WebSocket) return new options.WebSocket(buildWsUrl(options.platformUrl, hasConnected, sessionId).toString());
-		return openReconnectingSocket(currentWsUrl);
+	function onServerConfig(config) {
+		dialer.configured(config.sid);
+		if (config.sid) options.onSessionId?.(config.sid);
+		initAudioCapture(conn, config, audioDeps);
 	}
 	function connect(opts) {
 		if (opts?.signal?.aborted) {
@@ -877,7 +1011,7 @@ function createSessionCore(options) {
 		connectionController = controller;
 		const { signal: sig } = controller;
 		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
-		const socket = openSocket();
+		const socket = dialer.open();
 		socket.binaryType = "arraybuffer";
 		conn.ws = socket;
 		let socketErrored = false;
@@ -912,7 +1046,7 @@ function createSessionCore(options) {
 		socket.addEventListener("message", (event) => {
 			const config = handleMessage(event.data);
 			if (!config) return;
-			handshake.disarm();
+			handshake.succeeded();
 			onServerConfig(config);
 		}, { signal: sig });
 		socket.addEventListener("error", () => {
@@ -996,8 +1130,7 @@ function createSessionCore(options) {
 	}
 	function end() {
 		teardownConnection();
-		sessionId = void 0;
-		hasConnected = false;
+		dialer.forget();
 		updateState({
 			...CLEARED_SESSION_STATE,
 			state: "disconnected",

package/dist/session-core-dial.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How the next connection attempt is DIALLED, and the resume identity it dials
+ * with.
+ *
+ * Split out of `session-core.ts` at the 500-line cap, along the seam that file
+ * already established when it moved socket plumbing into
+ * `session-core-reconnect.ts`: the state machine there reads as protocol logic,
+ * and this is the address it sends it to. What makes it one module rather than
+ * three extracted functions is that the three pieces of mutable state involved —
+ * the session id, whether this connection has ever completed a handshake, and
+ * whether the server is a broker — are read by nothing else in the core, and
+ * every one of them is only meaningful in the sentence "the URL for the next
+ * attempt".
+ */
+import type { WebSocketConstructor } from "./types.ts";
+/** What the dialer needs from the session's options. */
+export type DialOptions = {
+    platformUrl: string;
+    /** Tests inject one; it connects to the same-origin path and never reconnects. */
+    WebSocket?: WebSocketConstructor | undefined;
+    /** An id the caller manages itself — wins over what a previous load stored. */
+    resumeSessionId?: string | undefined;
+};
+export type Dialer = {
+    /** The URL for the next attempt — partysocket's async provider. */
+    url(): Promise<string>;
+    /** A socket for this attempt. */
+    open(): InstanceType<WebSocketConstructor>;
+    /**
+     * A completed handshake: adopt the server's session id and record that this
+     * connection has been established, so every later attempt resumes.
+     */
+    configured(sid: string | undefined): void;
+    /** Drop the resume identity, so the next connect is a NEW session. */
+    forget(): void;
+};
+/** @internal */
+export declare function createDialer(options: DialOptions): Dialer;