@signalwire/js 4.0.0-dev-20260714201720 → 4.0.0-dev-20260721161304

package/dist/browser.mjs

@@ -9049,6 +9049,14 @@ const CREDENTIAL_REFRESH_MAX_DELAY_MS = 3e4;
 /** Buffer in milliseconds before token expiry to trigger refresh. */
 const CREDENTIAL_REFRESH_BUFFER_MS = 5e3;
 /**
+* Clock-skew allowance (ms) for treating an in-memory credential as expired
+* when deciding whether a fresh (re)connect must re-mint the token before
+* authenticating. A token within this window of its `expiry_at` is treated as
+* stale so the reconnect re-mints via the credential provider instead of
+* replaying a dead token (which the server rejects with -32003).
+*/
+const CREDENTIAL_EXPIRY_SKEW_MS = 3e4;
+/**
 * Maximum time the coordinator will wait for `DeviceTokenManager.activate()`
 * to resolve before treating the activation as failed and falling back to
 * the developer-provided refresh path. Prevents a wedged HTTP layer from
@@ -9281,6 +9289,20 @@ var CallCreateError = class extends Error {
 		this.name = "CallCreateError";
 	}
 };
+var CallNotReadyError = class extends Error {
+	constructor(callId, options) {
+		super(`Call "${callId}" has no self member context yet: selfId/nodeId have not been received from the server`, options);
+		this.callId = callId;
+		this.name = "CallNotReadyError";
+	}
+};
+var ParticipantNotReadyError = class extends Error {
+	constructor(memberId, options) {
+		super(`Participant "${memberId}" has no call context yet: its member state (call_id/node_id) has not been received from the server`, options);
+		this.memberId = memberId;
+		this.name = "ParticipantNotReadyError";
+	}
+};
 var JSONRPCError = class extends Error {
 	constructor(code, message, data, options, requestId) {
 		super(message, options);
@@ -13644,9 +13666,9 @@ const initialState = {};
 * the local participant with additional device control.
 */
 var Participant = class extends Destroyable {
-	constructor(id, executeMethod, deviceController) {
+	constructor(id, callExecuteMethod, deviceController) {
 		super();
-		this.executeMethod = executeMethod;
+		this.callExecuteMethod = callExecuteMethod;
 		this.deviceController = deviceController;
 		this._state$ = this.createBehaviorSubject(initialState);
 		this.id = id;
@@ -13868,22 +13890,55 @@ var Participant = class extends Destroyable {
 	get value() {
 		return this._state$.value;
 	}
+	/**
+	* Target triple for member RPCs, built from the participant's own state.
+	* The backend locates the member's session by the target `call_id`/`node_id`,
+	* so this must always be the participant's own call context — never the
+	* local call's id (issue #19400).
+	*
+	* Reading it doubles as a readiness probe: it throws until the first full
+	* member event (`member.joined`/`member.updated` or the `call.joined`
+	* roster) arrives, and never regresses afterwards.
+	*
+	* @throws {ParticipantNotReadyError} If the member state has not been
+	* received yet (e.g. a participant first seen via `member.talking`) — an
+	* empty call context can never address the member, so fail fast instead of
+	* sending a doomed RPC.
+	*/
+	get target() {
+		const { call_id, node_id } = this._state$.value;
+		if (!call_id || !node_id) throw new ParticipantNotReadyError(this.id);
+		return {
+			member_id: this.id,
+			call_id,
+			node_id
+		};
+	}
+	/**
+	* Executes a member RPC against this participant, injecting its own
+	* {@link target} as the target.
+	*
+	* @throws {ParticipantNotReadyError} Via {@link target}, when the
+	* member state has not been received yet.
+	*/
+	async executeMethod(method, args) {
+		return this.callExecuteMethod(this.target, method, args);
+	}
 	/** Toggles the deafened state (mutes/unmutes incoming audio). */
 	async toggleDeaf() {
-		const method = toggleDeafMethod(this.deaf);
-		await this.executeMethod(this.id, method, {});
+		await this.executeMethod(toggleDeafMethod(this.deaf), {});
 	}
 	/** Toggles the hand-raised state. */
 	async toggleHandraise() {
-		await this.executeMethod(this.id, toggleHandraiseMethod(this.handraised), {});
+		await this.executeMethod(toggleHandraiseMethod(this.handraised), {});
 	}
 	/** Mutes the participant's audio. */
 	async mute() {
-		await this.executeMethod(this.id, "call.mute", { channels: ["audio"] });
+		await this.executeMethod("call.mute", { channels: ["audio"] });
 	}
 	/** Unmutes the participant's audio. */
 	async unmute() {
-		await this.executeMethod(this.id, "call.unmute", { channels: ["audio"] });
+		await this.executeMethod("call.unmute", { channels: ["audio"] });
 	}
 	/** Toggles the participant's audio mute state. */
 	async toggleMute() {
@@ -13891,11 +13946,11 @@ var Participant = class extends Destroyable {
 	}
 	/** Mutes the participant's video. */
 	async muteVideo() {
-		await this.executeMethod(this.id, "call.mute", { channels: ["video"] });
+		await this.executeMethod("call.mute", { channels: ["video"] });
 	}
 	/** Unmutes the participant's video. */
 	async unmuteVideo() {
-		await this.executeMethod(this.id, "call.unmute", { channels: ["video"] });
+		await this.executeMethod("call.unmute", { channels: ["video"] });
 	}
 	/** Toggles the participant's video mute state. */
 	async toggleMuteVideo() {
@@ -13903,7 +13958,7 @@ var Participant = class extends Destroyable {
 	}
 	/** Toggles echo cancellation on the audio input. */
 	async toggleEchoCancellation() {
-		await this.executeMethod(this.id, "call.audioflags.set", {
+		await this.executeMethod("call.audioflags.set", {
 			echo_cancellation: !this.echoCancellation,
 			auto_gain: this.autoGain,
 			noise_suppression: this.noiseSuppression
@@ -13911,7 +13966,7 @@ var Participant = class extends Destroyable {
 	}
 	/** Toggles automatic gain control on the audio input. */
 	async toggleAudioInputAutoGain() {
-		await this.executeMethod(this.id, "call.audioflags.set", {
+		await this.executeMethod("call.audioflags.set", {
 			echo_cancellation: this.echoCancellation,
 			auto_gain: !this.autoGain,
 			noise_suppression: this.noiseSuppression
@@ -13919,7 +13974,7 @@ var Participant = class extends Destroyable {
 	}
 	/** Toggles noise suppression on the audio input. */
 	async toggleNoiseSuppression() {
-		await this.executeMethod(this.id, "call.audioflags.set", {
+		await this.executeMethod("call.audioflags.set", {
 			echo_cancellation: this.echoCancellation,
 			auto_gain: this.autoGain,
 			noise_suppression: !this.noiseSuppression
@@ -13927,7 +13982,7 @@ var Participant = class extends Destroyable {
 	}
 	/** Toggles low-bitrate mode for this participant's media. */
 	async toggleLowbitrate() {
-		await this.executeMethod(this.id, "call.lowbitrate.set", { lowbitrate: !this.lowbitrate });
+		await this.executeMethod("call.lowbitrate.set", { lowbitrate: !this.lowbitrate });
 	}
 	/**
 	* Adjusts the **conference-only** microphone energy gate / sensitivity level
@@ -13943,7 +13998,7 @@ var Participant = class extends Destroyable {
 	*   (integer, larger values are more sensitive).
 	*/
 	async setAudioInputSensitivity(value) {
-		await this.executeMethod(this.id, "call.microphone.sensitivity.set", { sensitivity: value });
+		await this.executeMethod("call.microphone.sensitivity.set", { sensitivity: value });
 	}
 	/**
 	* Sets the **server-side** microphone volume on this participant's bridged
@@ -13956,7 +14011,7 @@ var Participant = class extends Destroyable {
 	* @param value - Volume level (0-100).
 	*/
 	async setAudioInputVolume(value) {
-		await this.executeMethod(this.id, "call.microphone.volume.set", { volume: value });
+		await this.executeMethod("call.microphone.volume.set", { volume: value });
 	}
 	/**
 	* Sets the **server-side** speaker volume on this participant's bridged call
@@ -13970,45 +14025,31 @@ var Participant = class extends Destroyable {
 	* @param value - Volume level (0-100).
 	*/
 	async setAudioOutputVolume(value) {
-		await this.executeMethod(this.id, "call.speaker.volume.set", { volume: value });
+		await this.executeMethod("call.speaker.volume.set", { volume: value });
 	}
 	/**
 	* Sets the participant's position in the video layout.
 	*
-	* Requires the `member.position` capability. The gateway keys positions by the
-	* **target member's own** `call_id`/`node_id` (see issue #19400 and the legacy
-	* `setPositions` implementation), so this sends the participant's own call
-	* context — matching {@link Participant.remove}. A resolved promise does not
-	* guarantee a visible change: the backend silently returns `200` (no-op) for
-	* non-conference targets.
+	* Requires the `member.position` capability. The gateway requires a
+	* `targets` array of `{ target, position }` entries (issue #19400). A
+	* resolved promise does not guarantee a visible change: the backend silently
+	* returns `200` (no-op) for non-conference targets.
 	*
 	* @param value - The {@link VideoPosition} to assign (e.g. `'auto'`, `'reserved-0'`).
 	*/
 	async setPosition(value) {
-		const state = this._state$.value;
-		const target = {
-			member_id: this.id,
-			call_id: state.call_id ?? "",
-			node_id: state.node_id ?? ""
-		};
-		await this.executeMethod(target, "call.member.position.set", { targets: [{
-			target,
+		await this.executeMethod("call.member.position.set", { targets: [{
+			target: this.target,
 			position: value
 		}] });
 	}
 	/** Removes this participant from the call. */
 	async remove() {
-		const state = this._state$.value;
-		const target = {
-			member_id: this.id,
-			call_id: state.call_id ?? "",
-			node_id: state.node_id ?? ""
-		};
-		await this.executeMethod(target, "call.member.remove", {});
+		await this.executeMethod("call.member.remove", { targets: [this.target] });
 	}
 	/** Ends the call for this participant. */
 	async end() {
-		await this.executeMethod(this.id, "call.end", {});
+		await this.executeMethod("call.end", {});
 	}
 	/**
 	* Replaces custom metadata for this participant.
@@ -14028,7 +14069,7 @@ var Participant = class extends Destroyable {
 	}
 	/** Destroys the participant, releasing all subscriptions and references. */
 	destroy() {
-		this.executeMethod = void 0;
+		this.callExecuteMethod = void 0;
 		super.destroy();
 	}
 };
@@ -14040,8 +14081,8 @@ var Participant = class extends Destroyable {
 */
 var SelfParticipant = class extends Participant {
 	/** @internal */
-	constructor(id, executeMethod, vertoManager, deviceController) {
-		super(id, executeMethod, deviceController);
+	constructor(id, callExecuteMethod, vertoManager, deviceController) {
+		super(id, callExecuteMethod, deviceController);
 		this.vertoManager = vertoManager;
 		this._studioAudio$ = this.createBehaviorSubject(false);
 		this.capabilities = new SelfCapabilities();
@@ -14065,7 +14106,7 @@ var SelfParticipant = class extends Participant {
 	async enableStudioAudio() {
 		if (this._studioAudio$.value) return;
 		this._studioAudio$.next(true);
-		await this.executeMethod(this.id, "call.audioflags.set", {
+		await this.executeMethod("call.audioflags.set", {
 			echo_cancellation: false,
 			auto_gain: false,
 			noise_suppression: false
@@ -14078,7 +14119,7 @@ var SelfParticipant = class extends Participant {
 	async disableStudioAudio() {
 		if (!this._studioAudio$.value) return;
 		this._studioAudio$.next(false);
-		await this.executeMethod(this.id, "call.audioflags.set", {
+		await this.executeMethod("call.audioflags.set", {
 			echo_cancellation: true,
 			auto_gain: true,
 			noise_suppression: true
@@ -18299,12 +18340,6 @@ function mosToQualityLevel(mos) {
 var import_cjs$11 = require_cjs();
 const logger$12 = getLogger();
 /**
-* Verto method for setting member layout positions. Its gateway DTO requires a
-* `targets` array whose entries are `{ target, position }` (NOT bare targets),
-* so {@link WebRTCCall.buildMethodParams} special-cases it. See issue #19400.
-*/
-const POSITION_SET_METHOD = "call.member.position.set";
-/**
 * Ratio between the critical and warning RTT spike multipliers.
 * Warning threshold = baseline * warningMultiplier (default 3x)
 * Critical threshold = baseline * warningMultiplier * RTT_CRITICAL_TO_WARNING_RATIO
@@ -18455,7 +18490,7 @@ var WebRTCCall = class extends Destroyable {
 	/** Toggles the call lock state, preventing or allowing new participants from joining. */
 	async toggleLock() {
 		const method = this.locked ? "call.unlock" : "call.lock";
-		await this.executeMethod(this.selfId ?? "", method, {});
+		await this.executeMethod(this.callSelf, method, {});
 	}
 	/**
 	* Toggles the hold state of the call (pauses/resumes local media transmission).
@@ -18504,14 +18539,24 @@ var WebRTCCall = class extends Destroyable {
 	*
 	* Constructs call context (node_id, call_id, member_id) and sends the RPC request.
 	*
-	* @param target - Target member ID string, or a {@link MemberTarget} object.
+	* @param target - Target {@link MemberTarget} triple, or the local member's
+	*   ID string for self-operations (any other string is rejected — a bare
+	*   member id cannot carry the remote member's own call context).
 	* @param method - Verto method name (e.g. `'call.mute'`, `'call.member.remove'`).
 	* @param args - Parameters for the RPC method.
 	* @returns The RPC response.
+	* @throws {CallNotReadyError} If the call has no self member context yet.
+	* @throws {InvalidParams} If a string target is not the local member's ID.
 	* @throws {JSONRPCError} If the RPC call returns an error.
 	*/
 	async executeMethod(target, method, args) {
-		const params = this.buildMethodParams(target, args, method);
+		const self = this.callSelf;
+		if (typeof target === "string" && target !== self.member_id) throw new InvalidParams(`Target member ID ${target} does not match call's self member ID ${self.member_id}`);
+		const params = {
+			...args,
+			self,
+			target: typeof target === "string" ? self : target
+		};
 		const request = buildRPCRequest({
 			method,
 			params
@@ -18525,29 +18570,23 @@ var WebRTCCall = class extends Destroyable {
 			throw error;
 		}
 	}
-	buildMethodParams(target, args, method) {
-		const self = {
-			node_id: this.nodeId ?? "",
-			call_id: this.id,
-			member_id: this.vertoManager.selfId ?? ""
-		};
-		if (method === POSITION_SET_METHOD) return {
-			...args,
-			self
-		};
-		if (typeof target === "object") return {
-			...args,
-			self,
-			targets: [target]
-		};
+	/**
+	* The local leg's member triple — sent as `self` in every member RPC
+	* envelope, and as the `target` of call-scoped self-operations (e.g. lock,
+	* layout).
+	*
+	* @throws {CallNotReadyError} Before `call.joined` delivers the self member
+	* context (`selfId`/`nodeId`) — an RPC without it cannot be routed, so fail
+	* fast instead of sending a doomed request.
+	*/
+	get callSelf() {
+		const node_id = this.nodeId;
+		const member_id = this.vertoManager.selfId;
+		if (!node_id || !member_id) throw new CallNotReadyError(this.id);
 		return {
-			...args,
-			self,
-			target: {
-				node_id: this.nodeId ?? "",
-				call_id: this.id,
-				member_id: target
-			}
+			node_id,
+			call_id: this.id,
+			member_id
 		};
 	}
 	/** Observable of the current call status (e.g. `'ringing'`, `'connected'`). */
@@ -19110,12 +19149,17 @@ var WebRTCCall = class extends Destroyable {
 	*
 	* **These operations are NOT atomic.** The layout is applied first, then each
 	* member position sequentially, so members may briefly flash into their
-	* default slots before being moved to the requested positions.
+	* default slots before being moved to the requested positions. Targeted
+	* members are validated upfront, though: when any of them has no
+	* {@link Participant.target | member call context} yet, the whole call
+	* rejects before any request is sent and the layout is left unchanged.
 	*
 	* @param layout - Layout name (must be one of {@link layouts}).
 	* @param positions - Optional map of member IDs to {@link VideoPosition} values.
 	*   When omitted or empty, only the layout is changed.
 	* @throws {InvalidParams} If the layout is not in the available {@link layouts}.
+	* @throws {ParticipantNotReadyError} If a targeted member's call context has
+	*   not been received yet — thrown before any request is sent.
 	*
 	* @example
 	* ```ts
@@ -19126,18 +19170,19 @@ var WebRTCCall = class extends Destroyable {
 	*/
 	async setLayout(layout, positions) {
 		if (!this.layouts.includes(layout)) throw new InvalidParams(`Layout ${layout} is not available in the current call layouts: ${this.layouts.join(", ")}`);
-		const selfId = await (0, import_cjs$11.firstValueFrom)(this.selfId$.pipe((0, import_cjs$11.filter)((id) => id !== null)));
-		await this.executeMethod(selfId, "call.layout.set", { layout });
-		const positionEntries = Object.entries(positions ?? {});
-		if (positionEntries.length === 0) return;
-		for (const [memberId, position] of positionEntries) {
+		const targets = [];
+		for (const [memberId, position] of Object.entries(positions ?? {})) {
 			const participant = this.participants.find((p) => p.id === memberId);
 			if (!participant) {
 				logger$12.warn(`[Call] setLayout: member ${memberId} not found in participants; skipping position ${position}`);
 				continue;
 			}
-			await participant.setPosition(position);
+			participant.target;
+			targets.push([participant, position]);
 		}
+		const selfId = await (0, import_cjs$11.firstValueFrom)(this.selfId$.pipe((0, import_cjs$11.filter)((id) => id !== null)));
+		await this.executeMethod(selfId, "call.layout.set", { layout });
+		for (const [participant, position] of targets) await participant.setPosition(position);
 	}
 	/**
 	* Transfers the call to another destination.
@@ -20056,9 +20101,9 @@ var ClientSessionManager = class extends Destroyable {
 	}
 	async handleAuthenticationError(error) {
 		logger$9.error("Authentication error:", error);
-		const isRecoverableAuthError = error instanceof JSONRPCError && (error.code === RPC_ERROR_REQUESTER_VALIDATION_FAILED || error.code === RPC_ERROR_INVALID_PARAMS || error.code === RPC_ERROR_AUTHENTICATION_FAILED);
+		const isRecoverableAuthError$1 = error instanceof JSONRPCError && (error.code === RPC_ERROR_REQUESTER_VALIDATION_FAILED || error.code === RPC_ERROR_INVALID_PARAMS || error.code === RPC_ERROR_AUTHENTICATION_FAILED);
 		const hasStoredState = await (0, import_cjs$7.firstValueFrom)(this.authorizationState$.pipe((0, import_cjs$7.take)(1))) !== void 0;
-		if (isRecoverableAuthError && hasStoredState) {
+		if (isRecoverableAuthError$1 && hasStoredState) {
 			logger$9.debug("[Session] Recoverable auth error — cleaning up stored state and reconnecting fresh");
 			try {
 				await this.cleanupStoredConnectionParams();
@@ -20154,9 +20199,13 @@ var ClientSessionManager = class extends Destroyable {
 		const isReconnect = hasReconnectState && storedToken;
 		let dpopToken;
 		if (isReconnect) logger$9.debug("[Session] Reconnecting with stored jwt_token + authorization_state");
-		else if (this.onBeforeReconnect && this.clientBound) {
-			logger$9.debug("[Session] Refreshing credentials before fresh connect");
-			await this.onBeforeReconnect();
+		else {
+			const credential = this.getCredential();
+			const credentialExpired = credential.expiry_at !== void 0 && credential.expiry_at <= Date.now() + CREDENTIAL_EXPIRY_SKEW_MS;
+			if (this.onBeforeReconnect && (this.clientBound || credentialExpired)) {
+				logger$9.debug("[Session] Refreshing credentials before fresh connect");
+				await this.onBeforeReconnect();
+			}
 		}
 		if ((!isReconnect || this.clientBound) && this.dpopManager?.initialized) try {
 			dpopToken = await this.dpopManager.createRpcProof({ method: "signalwire.connect" });
@@ -20512,7 +20561,7 @@ var DeviceTokenManager = class extends Destroyable {
 			await session.reauthenticate(tokenData.token, rpcProof, { clientBound: true });
 			updateCredential({ token: tokenData.token });
 			logger$7.info("[DeviceToken] Client Bound SAT activated successfully");
-			this._currentToken$.next(tokenData);
+			this.emitCurrentToken(tokenData);
 			return { activated: true };
 		} catch (error) {
 			logger$7.error("[DeviceToken] Failed to activate Client Bound SAT:", error);
@@ -20524,6 +20573,21 @@ var DeviceTokenManager = class extends Destroyable {
 		}
 	}
 	/**
+	* Emit a freshly received token to the reactive pipeline, stamping an
+	* absolute `expires_at` when the response carried only `expires_in`.
+	* Resolving the expiry at RECEIVE time (not at read time) is what lets
+	* {@link refreshNowIfDue} detect due-ness on resume: a bare `expires_in`
+	* re-resolved later would always compute a full TTL from "now" and never
+	* cross the refresh buffer.
+	*/
+	emitCurrentToken(token) {
+		const stamped = token.expires_at ? token : {
+			...token,
+			expires_at: resolveExpiresAt(token)
+		};
+		this._currentToken$.next(stamped);
+	}
+	/**
 	* Returns true when the cached token has enough headroom before expiry to
 	* be safely reused on reactivation. The headroom matches the refresh
 	* buffer, so a token within the refresh window is treated as stale (the
@@ -20616,7 +20680,7 @@ var DeviceTokenManager = class extends Destroyable {
 			const currentToken = this.getCredential().token;
 			if (!currentToken) throw new TokenRefreshError("No current token available for refresh");
 			const newTokenData = await this.retryRefresh(session, currentToken, updateCredential);
-			this._currentToken$.next(newTokenData);
+			this.emitCurrentToken(newTokenData);
 		} catch (error) {
 			logger$7.error("[DeviceToken] Automatic Client Bound SAT refresh failed:", error);
 			this.errorHandler(error instanceof TokenRefreshError ? error : new TokenRefreshError("Automatic token refresh failed", error));
@@ -20643,6 +20707,22 @@ var DeviceTokenManager = class extends Destroyable {
 		throw lastError instanceof Error ? lastError : new TokenRefreshError("All refresh retries exhausted", lastError);
 	}
 	/**
+	* Force an immediate refresh when the cached Client Bound SAT is already
+	* past its refresh window. Called on resume from suspension where
+	* background-tab throttling can delay the reactive timer past the buffer.
+	* A no-op when no token is cached or it still has headroom; the normal
+	* {@link executeRefresh} guards (paused / in-progress / unauthenticated)
+	* still apply.
+	*/
+	refreshNowIfDue() {
+		const token = this._currentToken$.value;
+		if (!token) return;
+		if (resolveExpiresAt(token) * 1e3 - Date.now() <= DEVICE_TOKEN_REFRESH_BUFFER_MS) {
+			logger$7.debug("[DeviceToken] Resume: cached SAT past refresh window; refreshing now");
+			this.executeRefresh();
+		}
+	}
+	/**
 	* Stops the reactive refresh pipeline from firing. Use when the underlying
 	* session is being torn down (e.g., during {@link SignalWire.disconnect})
 	* so a scheduled refresh cannot fire against a destroyed session.
@@ -20693,6 +20773,7 @@ var CredentialRefreshCoordinator = class extends Destroyable {
 		this.deps = deps;
 		this._activating = false;
 		this._activationGeneration = 0;
+		this._developerRefreshInProgress = false;
 		if (dpopManager?.initialized) this._deviceTokenManager = (deps.deviceTokenManagerFactory ?? defaultDeviceTokenManagerFactory)(dpopManager, deps.http, (error) => deps.notifier.onError(error), () => deps.store.read());
 	}
 	/** True when the Client Bound SAT path is available (DPoP initialized). */
@@ -20711,28 +20792,120 @@ var CredentialRefreshCoordinator = class extends Destroyable {
 	* invokes `deps.onRefreshExhausted` so the orchestrator can disconnect.
 	*/
 	scheduleDeveloperRefresh(provider, expiresAt, attempt = 0) {
+		this._activeProvider = provider;
 		if (this._developerTimerId !== void 0) clearTimeout(this._developerTimerId);
 		const refreshInterval = attempt === 0 ? Math.max(expiresAt - Date.now() - CREDENTIAL_REFRESH_BUFFER_MS, 1e3) : Math.min(CREDENTIAL_REFRESH_RETRY_BASE_MS * Math.pow(2, attempt) * (.5 + Math.random() * .5), CREDENTIAL_REFRESH_MAX_DELAY_MS);
-		this._developerTimerId = setTimeout(async () => {
+		this._developerTimerId = setTimeout(() => {
+			this._developerTimerId = void 0;
+			this.executeDeveloperRefresh(provider, expiresAt, attempt);
+		}, refreshInterval);
+	}
+	/**
+	* Runs the developer-provided refresh once: mints a new credential, stores
+	* and persists it, reauthenticates the live session (via the notifier), and
+	* reschedules against the new expiry. On failure retries with backoff up to
+	* {@link CREDENTIAL_REFRESH_MAX_RETRIES}, then signals exhaustion.
+	*
+	* Shared by the scheduled timer tick and {@link forceRefreshIfDue}. The
+	* `_developerRefreshInProgress` guard prevents the two from overlapping.
+	*/
+	async executeDeveloperRefresh(provider, expiresAt, attempt) {
+		if (this._developerRefreshInProgress) {
+			logger$6.debug("[Coordinator] Developer refresh already in progress; skipping");
+			return;
+		}
+		this._developerRefreshInProgress = true;
+		try {
+			const newCredentials = await this.refreshCredential(provider);
+			this.deps.store.write(newCredentials);
+			this.deps.store.persist(newCredentials);
 			try {
-				if (!provider.refresh) throw new InvalidCredentialsError("Credential provider does not support refresh");
-				const newCredentials = await provider.refresh();
-				this.deps.store.write(newCredentials);
-				this.deps.store.persist(newCredentials);
-				logger$6.info("[Coordinator] Credentials refreshed successfully.");
-				if (newCredentials.expiry_at) this.scheduleDeveloperRefresh(provider, newCredentials.expiry_at, 0);
-			} catch (error) {
-				const nextAttempt = attempt + 1;
-				logger$6.error(`[Coordinator] Credential refresh failed (attempt ${nextAttempt}/${CREDENTIAL_REFRESH_MAX_RETRIES}):`, error);
-				this.deps.notifier.onError(error instanceof Error ? error : new Error(String(error), { cause: error }));
-				if (nextAttempt < CREDENTIAL_REFRESH_MAX_RETRIES) this.scheduleDeveloperRefresh(provider, expiresAt, nextAttempt);
-				else {
-					logger$6.error("[Coordinator] Credential refresh exhausted all retries. Disconnecting.");
-					this.deps.notifier.onError(new TokenRefreshError("Credential refresh failed after max retries"));
-					this.deps.notifier.onRefreshExhausted();
-				}
+				await this.deps.notifier.onCredentialRefreshed(newCredentials);
+			} catch (reauthError) {
+				logger$6.warn("[Coordinator] onCredentialRefreshed rejected (non-fatal):", reauthError);
 			}
-		}, refreshInterval);
+			logger$6.info("[Coordinator] Credentials refreshed successfully.");
+			if (newCredentials.expiry_at) this.scheduleDeveloperRefresh(provider, newCredentials.expiry_at, 0);
+		} catch (error) {
+			const nextAttempt = attempt + 1;
+			logger$6.error(`[Coordinator] Credential refresh failed (attempt ${nextAttempt}/${CREDENTIAL_REFRESH_MAX_RETRIES}):`, error);
+			this.deps.notifier.onError(error instanceof Error ? error : new Error(String(error), { cause: error }));
+			if (nextAttempt < CREDENTIAL_REFRESH_MAX_RETRIES) this.scheduleDeveloperRefresh(provider, expiresAt, nextAttempt);
+			else {
+				logger$6.error("[Coordinator] Credential refresh exhausted all retries. Disconnecting.");
+				this.deps.notifier.onError(new TokenRefreshError("Credential refresh failed after max retries"));
+				this.deps.notifier.onRefreshExhausted();
+			}
+		} finally {
+			this._developerRefreshInProgress = false;
+		}
+	}
+	/**
+	* Force an immediate refresh when the current credential is already past its
+	* scheduled refresh window. Called on resume from suspension, where
+	* background-tab timer throttling can delay the armed refresh well past
+	* expiry, leaving the live session stale.
+	*
+	* Routes to whichever mechanism is armed: the developer timer if armed,
+	* otherwise the Client Bound SAT pipeline. A no-op when nothing is due.
+	*/
+	forceRefreshIfDue() {
+		if (this._developerTimerId !== void 0 && this._activeProvider) {
+			const expiry = this.deps.store.read().expiry_at;
+			if (expiry !== void 0 && Date.now() >= expiry - CREDENTIAL_REFRESH_BUFFER_MS) {
+				logger$6.debug("[Coordinator] Resume: credential past refresh window; forcing refresh");
+				clearTimeout(this._developerTimerId);
+				this._developerTimerId = void 0;
+				this.executeDeveloperRefresh(this._activeProvider, expiry, 0);
+			}
+			return;
+		}
+		this._deviceTokenManager?.refreshNowIfDue();
+	}
+	/**
+	* Sync the credential's expiry from the server-provided authorization (the
+	* `signalwire.connect` result). SATs are opaque JWE, so
+	* `fabric_subscriber.expires_at` is the authoritative expiry of the token
+	* the session actually connected with — the provider-reported `expiry_at`
+	* is only a hint (and may be wrong or absent). Corrects the stored
+	* credential and re-arms the developer refresh timer against the real
+	* deadline when the provider supports `refresh()`.
+	*/
+	syncExpiryFromAuthorization(authorization, provider) {
+		const expiresAtSec = authorization?.fabric_subscriber?.expires_at;
+		if (!expiresAtSec) return;
+		const expiryAt = expiresAtSec * 1e3;
+		const credential = this.deps.store.read();
+		if (credential.expiry_at === expiryAt) return;
+		logger$6.debug(`[Coordinator] Correcting credential expiry from server authorization: ${new Date(expiryAt).toISOString()}`);
+		const updated = {
+			...credential,
+			expiry_at: expiryAt
+		};
+		this.deps.store.write(updated);
+		this.deps.store.persist(updated);
+		if (provider?.refresh) this.scheduleDeveloperRefresh(provider, expiryAt);
+	}
+	/**
+	* Invoke `provider.refresh()` deduped against any concurrent developer
+	* refresh. Concurrent callers — the scheduled tick, a resume-forced refresh,
+	* and the orchestrator's -32003 recovery / reconnect re-mint — share one
+	* in-flight promise, so a provider backed by one-time-use rotating refresh
+	* tokens is never invoked twice in parallel.
+	*
+	* The caller owns applying the returned credential (store write, session
+	* reauth, rescheduling); this method only serializes the network call.
+	*/
+	async refreshCredential(provider) {
+		if (this._refreshInFlight) return this._refreshInFlight;
+		if (!provider.refresh) throw new InvalidCredentialsError("Credential provider does not support refresh");
+		const run = provider.refresh();
+		this._refreshInFlight = run;
+		const clear = () => {
+			if (this._refreshInFlight === run) this._refreshInFlight = void 0;
+		};
+		run.then(clear, clear);
+		return run;
 	}
 	/**
 	* Cancels any scheduled developer-provided refresh. Idempotent.
@@ -21512,6 +21685,33 @@ var TransportManager = class extends Destroyable {
 	}
 };
 
+//#endregion
+//#region src/utils/authRecovery.ts
+/**
+* Walk an error's `error`/`cause` chain looking for a {@link JSONRPCError}.
+* Errors thrown by call creation are wrapped (e.g. `CallCreateError`), so the
+* underlying signaling error is nested. Bounded by a visited set to guard
+* against cyclic causes.
+*/
+function findJSONRPCError(error) {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current instanceof Error && !seen.has(current)) {
+		seen.add(current);
+		if (current instanceof JSONRPCError) return current;
+		current = current.error ?? current.cause;
+	}
+}
+/**
+* Whether an error is a session-recoverable authentication failure
+* (`-32002` authentication failed or `-32003` requester validation failed)
+* that a credential re-mint + retry can heal.
+*/
+function isRecoverableAuthError(error) {
+	const rpcError = findJSONRPCError(error);
+	return rpcError !== void 0 && (rpcError.code === RPC_ERROR_REQUESTER_VALIDATION_FAILED || rpcError.code === RPC_ERROR_AUTHENTICATION_FAILED);
+}
+
 //#endregion
 //#region src/clients/SignalWire.ts
 var import_cjs$1 = require_cjs();
@@ -21627,7 +21827,8 @@ var SignalWire = class extends Destroyable {
 			notifier: {
 				onError: (error) => this._errors$.next(error),
 				onWarning: (warning) => this._warnings$.next(warning),
-				onRefreshExhausted: () => void this.disconnect()
+				onRefreshExhausted: () => void this.disconnect(),
+				onCredentialRefreshed: async (credential) => this.reauthenticateLiveSession(credential)
 			},
 			store: {
 				read: () => this._deps.credential,
@@ -21684,14 +21885,123 @@ var SignalWire = class extends Destroyable {
 		}
 		this._deps.credential = _credentials;
 		this.persistCredential(_credentials);
-		if (this.isConnected && this._clientSession.authenticated && _credentials.token) try {
-			await this._clientSession.reauthenticate(_credentials.token);
+		await this.reauthenticateLiveSession(_credentials);
+	}
+	/**
+	* Reauthenticate the currently-open session with a freshly obtained
+	* credential so the new token takes effect on the live socket immediately —
+	* not just on the next reconnect. No-op when the session is not
+	* connected/authenticated or the credential carries no token (e.g. an
+	* authorization-state-only refresh). Non-fatal: reauth failures surface on
+	* `errors$` without aborting the refresh that triggered this.
+	*/
+	async reauthenticateLiveSession(credential) {
+		if (!this.isConnected || !this._clientSession.authenticated || !credential.token) return;
+		try {
+			await this._clientSession.reauthenticate(credential.token);
 			logger$1.info("[SignalWire] Session refreshed with new credentials.");
 		} catch (error) {
 			logger$1.error("[SignalWire] Failed to refresh session with new credentials:", error);
 			this._errors$.next(error instanceof Error ? error : new Error(String(error), { cause: error }));
 		}
 	}
+	/**
+	* One-shot recovery for a live session that failed with a recoverable auth
+	* error (`-32002`/`-32003`) because its token went stale — e.g. a refresh
+	* timer that was throttled while the tab was backgrounded.
+	*
+	* Two steps, first that succeeds wins:
+	*   1. Reauthenticate with the in-memory token (a fresh DPoP proof is
+	*      generated automatically). Heals a session whose token was already
+	*      refreshed by the coordinator but never applied to the open socket,
+	*      and a client-bound session whose server-side auth merely drifted.
+	*   2. Re-mint via the developer provider's `refresh()` and reauthenticate.
+	*      Skipped for client-bound sessions (the DeviceTokenManager owns their
+	*      refresh; re-minting a base SAT here would drop the DPoP binding).
+	*
+	* @param allowRemint - Whether step 2 (provider re-mint) may run. Callers
+	*   pass `false` for non-auth failures so a transient network error never
+	*   escalates to a token re-mint; step 1 (in-memory reauth) always runs.
+	* @returns `true` if the session was reauthenticated, `false` otherwise.
+	*/
+	async recoverStaleCredential(allowRemint = true) {
+		const currentToken = this._deps.credential.token;
+		if (currentToken) try {
+			await this._clientSession.reauthenticate(currentToken);
+			return true;
+		} catch (error) {
+			logger$1.debug("[SignalWire] In-memory reauth failed during recovery:", error);
+		}
+		if (!allowRemint || this._clientSession.clientBound || !this._credentialProvider?.refresh) return false;
+		try {
+			const newCredentials = await this.remintCredential(this._credentialProvider);
+			if (!newCredentials.token) return false;
+			this._deps.credential = newCredentials;
+			this.persistCredential(newCredentials);
+			await this._clientSession.reauthenticate(newCredentials.token);
+			if (newCredentials.expiry_at) this._refreshCoordinator?.scheduleDeveloperRefresh(this._credentialProvider, newCredentials.expiry_at);
+			return true;
+		} catch (error) {
+			logger$1.error("[SignalWire] Credential recovery failed:", error);
+			return false;
+		}
+	}
+	/**
+	* Re-mint a credential via `provider.refresh()`, routed through the
+	* coordinator's shared in-flight guard so concurrent re-mint paths (a
+	* scheduled/resume refresh, -32003 recovery, and reconnect) never fire a
+	* second `provider.refresh()` in parallel — which rotating one-time-use
+	* refresh tokens reject. Falls back to a direct call only if the coordinator
+	* has not been constructed yet.
+	*/
+	async remintCredential(provider) {
+		if (this._refreshCoordinator) return this._refreshCoordinator.refreshCredential(provider);
+		if (!provider.refresh) throw new InvalidCredentialsError("Credential provider does not support refresh");
+		return provider.refresh();
+	}
+	/**
+	* Re-mint credentials before a fresh (re)connect (`onBeforeReconnect` hook).
+	* The session invokes this only when it is client-bound OR the in-memory
+	* token is expired. The re-mint mechanism depends on the binding:
+	*   - Client-bound: `authenticate()` with the DPoP fingerprint to obtain a
+	*     fresh base SAT the upcoming reconnect can re-bind (the
+	*     DeviceTokenManager re-activates afterwards).
+	*   - Unbound: the developer's non-interactive `refresh()` handler.
+	*     `authenticate()` is deliberately NOT used here — it may be interactive
+	*     (a login prompt) and must not fire on a background reconnect.
+	*
+	* Rejects on failure so the session aborts the reconnect rather than
+	* replaying a stale token.
+	*/
+	async refreshCredentialForReconnect() {
+		if (!this._credentialProvider) return;
+		try {
+			let newCredentials;
+			if (this._clientSession.clientBound) {
+				const fingerprint = this._dpopManager?.initialized ? this._dpopManager.fingerprint : void 0;
+				logger$1.debug("[SignalWire] Re-minting client-bound base SAT before reconnect");
+				newCredentials = await this._credentialProvider.authenticate(fingerprint ? { fingerprint } : void 0);
+			} else if (this._credentialProvider.refresh) {
+				logger$1.debug("[SignalWire] Refreshing unbound credential before reconnect");
+				newCredentials = await this.remintCredential(this._credentialProvider);
+			} else {
+				logger$1.warn("[SignalWire] [SW-NO-REFRESH-HANDLER] Token expired on reconnect but no refresh handler; reconnecting with the existing token.");
+				return;
+			}
+			if (!newCredentials.token) {
+				logger$1.warn("[SignalWire] Re-minted credential has no token; keeping the existing credential for reconnect.");
+				return;
+			}
+			this._deps.credential = newCredentials;
+			this.persistCredential(newCredentials);
+			if (newCredentials.expiry_at && this._credentialProvider.refresh) this._refreshCoordinator?.scheduleDeveloperRefresh(this._credentialProvider, newCredentials.expiry_at);
+			logger$1.debug("[SignalWire] Credential refreshed successfully for reconnect");
+		} catch (error) {
+			logger$1.error("[SignalWire] Failed to refresh credentials for reconnect:", error);
+			this._errors$.next(error instanceof Error ? error : new Error(String(error), { cause: error }));
+			throw error;
+		}
+	}
 	/** Persist credential to localStorage when persistSession is enabled. */
 	persistCredential(credential) {
 		if (!credential.token) return;
@@ -21778,24 +22088,13 @@ var SignalWire = class extends Destroyable {
 		this._attachManager = new AttachManager(this._deps.storage, this._deps.deviceController, PreferencesContainer.instance.reconnectCallsTimeout, this._deps.attachedCallsKey);
 		this._clientSession = new ClientSessionManager(() => this._deps.credential, this._transport, this._deps.storage, this._deps.authorizationStateKey, this._deps.deviceController, this._attachManager, this._deps.webRTCApiProvider, this._dpopManager, this._networkMonitor?.networkChange$);
 		this._publicSession = new ClientSessionWrapper(this._clientSession);
-		this._clientSession.onBeforeReconnect = async () => {
-			if (!this._credentialProvider) return;
-			try {
-				const fingerprint = this._dpopManager?.initialized ? this._dpopManager.fingerprint : void 0;
-				logger$1.debug("[SignalWire] Credential expired, refreshing before reconnect");
-				const newCredentials = await this._credentialProvider.authenticate(fingerprint ? { fingerprint } : void 0);
-				this._deps.credential = newCredentials;
-				if (newCredentials.expiry_at && this._credentialProvider.refresh) this._refreshCoordinator?.scheduleDeveloperRefresh(this._credentialProvider, newCredentials.expiry_at);
-				logger$1.debug("[SignalWire] Credential refreshed successfully for reconnect");
-			} catch (error) {
-				logger$1.error("[SignalWire] Failed to refresh credentials for reconnect:", error);
-				this._errors$.next(error instanceof Error ? error : new Error(String(error), { cause: error }));
-				throw error;
-			}
-		};
+		this._clientSession.onBeforeReconnect = async () => this.refreshCredentialForReconnect();
 		this.subscribeTo(this._clientSession.errors$, (error) => {
 			this._errors$.next(error);
 		});
+		this.subscribeTo(this._clientSession.authorization$, (authorization) => {
+			this._refreshCoordinator?.syncExpiryFromAuthorization(authorization, this._credentialProvider);
+		});
 		await this._clientSession.connect();
 		await this._refreshCoordinator?.activate(this._deps.user, this._clientSession);
 		this.subscribeTo(this._clientSession.authenticated$.pipe((0, import_cjs$1.skip)(1), (0, import_cjs$1.filter)(Boolean)), async () => {
@@ -21958,6 +22257,13 @@ var SignalWire = class extends Destroyable {
 		}
 		try {
 			this._visibilityController = new VisibilityController();
+			this.subscribeTo(this._visibilityController.visibilityChange$.pipe((0, import_cjs$1.filter)((event) => event.to === "visible")), () => {
+				try {
+					this._refreshCoordinator?.forceRefreshIfDue();
+				} catch (error) {
+					logger$1.warn("[SignalWire] Resume credential revalidation failed (non-fatal):", error);
+				}
+			});
 			this.subscribeTo(this._visibilityController.visibilityChange$.pipe((0, import_cjs$1.filter)((event) => event.to === "visible" && PreferencesContainer.instance.refreshDevicesOnVisible)), () => {
 				logger$1.debug("[SignalWire] Page visible, re-enumerating devices");
 				try {
@@ -21969,7 +22275,7 @@ var SignalWire = class extends Destroyable {
 			logger$1.warn("[SignalWire] Failed to initialize VisibilityController:", error);
 		}
 		try {
-			this._diagnosticsCollector = new DiagnosticsCollector({ sdkVersion: "4.0.0-rc.1" });
+			this._diagnosticsCollector = new DiagnosticsCollector({ sdkVersion: "4.0.0-rc.2" });
 		} catch (error) {
 			logger$1.warn("[SignalWire] Failed to initialize DiagnosticsCollector:", error);
 		}
@@ -22040,21 +22346,23 @@ var SignalWire = class extends Destroyable {
 				this._errors$.next(error instanceof Error ? error : new Error(String(error), { cause: error }));
 				throw error;
 			}
-			logger$1.debug("[SignalWire] Failed to register user, trying reauthentication...");
-			try {
-				await this._clientSession.reauthenticate(this._deps.credential.token);
-				logger$1.debug("[SignalWire] Reauthentication successful, retrying register()");
+			logger$1.debug("[SignalWire] Failed to register user, attempting credential recovery...");
+			let failureCause = error;
+			if (await this.recoverStaleCredential(isRecoverableAuthError(error))) try {
+				logger$1.debug("[SignalWire] Recovery succeeded, retrying register()");
 				await this._transport.execute(RPCExecute({
 					method: "subscriber.online",
 					params: {}
 				}));
 				this._isRegistered$.next(true);
-			} catch (reauthError) {
-				logger$1.error("[SignalWire] Reauthentication failed during register():", reauthError);
-				const registerError = new InvalidCredentialsError("Failed to register user, and reauthentication attempt also failed. Please check your credentials.", { cause: reauthError instanceof Error ? reauthError : new Error(String(reauthError), { cause: reauthError }) });
-				this._errors$.next(registerError);
-				throw registerError;
+				return;
+			} catch (retryError) {
+				logger$1.error("[SignalWire] Register retry after recovery failed:", retryError);
+				failureCause = retryError;
 			}
+			const registerError = new InvalidCredentialsError("Failed to register user, and credential recovery also failed. Please check your credentials.", { cause: failureCause instanceof Error ? failureCause : new Error(String(failureCause), { cause: failureCause }) });
+			this._errors$.next(registerError);
+			throw registerError;
 		}
 	}
 	/**
@@ -22107,7 +22415,15 @@ var SignalWire = class extends Destroyable {
 		};
 		await this.waitAuthentication();
 		logger$1.debug("[SignalWire] Dialing with options:", computed_options);
-		return this._clientSession.createOutboundCall(destination, computed_options);
+		try {
+			return await this._clientSession.createOutboundCall(destination, computed_options);
+		} catch (error) {
+			if (!isRecoverableAuthError(error)) throw error;
+			logger$1.debug("[SignalWire] Dial hit a recoverable auth error; recovering credential and retrying once");
+			if (!await this.recoverStaleCredential()) throw error;
+			await this.waitAuthentication();
+			return this._clientSession.createOutboundCall(destination, computed_options);
+		}
 	}
 	/**
 	* Runs a multi-phase connectivity test against the given destination.
@@ -22504,7 +22820,7 @@ var StaticCredentialProvider = class {
 /**
 * Library version from package.json, injected at build time.
 */
-const version = "4.0.0-rc.1";
+const version = "4.0.0-rc.2";
 /**
 * Flag indicating the library has been loaded and is ready to use.
 * For UMD builds: `window.SignalWire.ready`
@@ -22526,7 +22842,7 @@ const ready = true;
 */
 const emitReadyEvent = () => {
 	if (typeof window !== "undefined") {
-		const event = new CustomEvent("signalwire:js:ready", { detail: { version: "4.0.0-rc.1" } });
+		const event = new CustomEvent("signalwire:js:ready", { detail: { version: "4.0.0-rc.2" } });
 		window.dispatchEvent(event);
 	}
 };
@@ -22550,5 +22866,5 @@ emitReadyEvent();
 if (typeof process === "undefined") globalThis.process = { env: { NODE_ENV: "production" } };
 
 //#endregion
-export { Address, CallCreateError, ClientPreferences, CollectionFetchError, DPoPInitError, DeviceTokenError, EmbedTokenCredentialProvider, InvalidCredentialsError, MediaAccessError, MediaTrackError, MessageParseError, OverconstrainedFallbackError, Participant, PreflightError, RecoveryError, SelfCapabilities, SelfParticipant, SignalWire, StaticCredentialProvider, TokenRefreshError, UnexpectedError, User, VertoPongError, WebRTCCall, embeddableCall, getLogger, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
+export { Address, CallCreateError, CallNotReadyError, ClientPreferences, CollectionFetchError, DPoPInitError, DeviceTokenError, EmbedTokenCredentialProvider, InvalidCredentialsError, MediaAccessError, MediaTrackError, MessageParseError, OverconstrainedFallbackError, Participant, ParticipantNotReadyError, PreflightError, RecoveryError, SelfCapabilities, SelfParticipant, SignalWire, StaticCredentialProvider, TokenRefreshError, UnexpectedError, User, VertoPongError, WebRTCCall, embeddableCall, getLogger, isSelfParticipant, ready, setDebugOptions, setLogLevel, setLogger, version };
 //# sourceMappingURL=browser.mjs.map