@signalwire/js 4.0.0-rc.1 → 4.0.0-rc.2

package/dist/browser.mjs

@@ -9015,6 +9015,143 @@ var Destroyable = class {
 	}
 };
 
+//#endregion
+//#region src/core/constants.ts
+const INVITE_VERSION = 1e3;
+const DEFAULT_ICE_CANDIDATE_TIMEOUT_MS = 600;
+const DEFAULT_ICE_GATHERING_TIMEOUT_MS = 6e3;
+const DEFAULT_RECONNECT_CALLS_TIMEOUT_MS = 300 * 1e3;
+const DEFAULT_CONNECTION_TIMEOUT_MS = 1e4;
+const DEFAULT_RECONNECT_DELAY_MIN_MS = 100;
+const DEFAULT_RECONNECT_DELAY_MAX_MS = 3e3;
+const DEFAULT_DEVICE_DEBOUNCE_TIME_MS = 1500;
+const DEFAULT_DEVICE_POLLING_INTERVAL_MS = 0;
+const PREFERENCES_STORAGE_KEY = "sw:preferences";
+/** Scope value that enables automatic token refresh. */
+const SAT_REFRESH_SCOPE = "sat:refresh";
+/** API endpoints for device token operations. */
+const DEVICE_TOKEN_ENDPOINT = "/api/fabric/subscriber/devices/token";
+const DEVICE_REFRESH_ENDPOINT = "/api/fabric/subscriber/devices/refresh";
+/** Default device token TTL in seconds (15 minutes). */
+const DEVICE_TOKEN_DEFAULT_EXPIRE_IN = 900;
+/** Buffer time in milliseconds before expiry to trigger refresh. */
+const DEVICE_TOKEN_REFRESH_BUFFER_MS = 3e4;
+/** Maximum retry attempts for device token refresh on transient failure. */
+const DEVICE_TOKEN_REFRESH_MAX_RETRIES = 3;
+/** Base delay in milliseconds for exponential backoff on refresh retry. */
+const DEVICE_TOKEN_REFRESH_RETRY_BASE_MS = 1e3;
+/** Maximum retry attempts for developer credential refresh on transient failure. */
+const CREDENTIAL_REFRESH_MAX_RETRIES = 5;
+/** Base delay in milliseconds for exponential backoff on credential refresh retry. */
+const CREDENTIAL_REFRESH_RETRY_BASE_MS = 1e3;
+/** Maximum delay in milliseconds for credential refresh backoff. */
+const CREDENTIAL_REFRESH_MAX_DELAY_MS = 3e4;
+/** Buffer in milliseconds before token expiry to trigger refresh. */
+const CREDENTIAL_REFRESH_BUFFER_MS = 5e3;
+/**
+* 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
+* leaving the session with no active refresh mechanism.
+*/
+const CREDENTIAL_ACTIVATE_TIMEOUT_MS = 3e4;
+/** JSON-RPC error code for requester validation failure (corrupted auth state). */
+const RPC_ERROR_REQUESTER_VALIDATION_FAILED = -32003;
+/** JSON-RPC error code for invalid params (e.g., missing authentication block). */
+const RPC_ERROR_INVALID_PARAMS = -32602;
+/** JSON-RPC error code for authentication failure (invalid token, missing DPoP, etc.). */
+const RPC_ERROR_AUTHENTICATION_FAILED = -32002;
+/** Error names browsers use for a media permission denial (user or policy). */
+const MEDIA_ACCESS_DENIAL_NAMES = [
+	"NotAllowedError",
+	"SecurityError",
+	"PermissionDeniedError"
+];
+/** Default polling interval for RTCPeerConnection.getStats() in milliseconds. */
+const DEFAULT_STATS_POLLING_INTERVAL_MS = 1e3;
+/** Number of initial samples used to build a baseline for spike detection. */
+const DEFAULT_STATS_BASELINE_SAMPLES = 10;
+/** Duration in ms with no inbound audio packets before emitting a critical issue. */
+const DEFAULT_STATS_NO_PACKET_THRESHOLD_MS = 2e3;
+/** Multiplier applied to baseline RTT to detect a warning-level RTT spike. */
+const DEFAULT_STATS_RTT_SPIKE_MULTIPLIER = 3;
+/** Packet loss fraction (0-1) above which a warning is emitted. */
+const DEFAULT_STATS_PACKET_LOSS_THRESHOLD = .05;
+/** Multiplier applied to baseline jitter to detect a jitter spike. */
+const DEFAULT_STATS_JITTER_SPIKE_MULTIPLIER = 4;
+/** Number of seconds of metrics history to retain. */
+const DEFAULT_STATS_HISTORY_SIZE = 30;
+/** Maximum keyframe requests allowed within a single burst window. */
+const DEFAULT_KEYFRAME_MAX_BURST$1 = 3;
+/** Duration of the keyframe burst window in milliseconds. */
+const DEFAULT_KEYFRAME_BURST_WINDOW_MS$1 = 3e3;
+/** Cooldown period in ms after burst limit is reached before allowing more keyframes. */
+const DEFAULT_KEYFRAME_COOLDOWN_MS$1 = 1e4;
+/** Minimum time between re-INVITE attempts in milliseconds. */
+const DEFAULT_REINVITE_DEBOUNCE_TIME_MS = 1e4;
+/** Maximum number of re-INVITE attempts per call. */
+const DEFAULT_REINVITE_MAX_ATTEMPTS = 3;
+/** Timeout for a single re-INVITE attempt in milliseconds. */
+const DEFAULT_REINVITE_TIMEOUT_MS = 5e3;
+/** Debounce window in ms to collapse multiple detection signals into one trigger. */
+const DEFAULT_RECOVERY_DEBOUNCE_TIME_MS = 2e3;
+/** Cooldown period in ms between recovery attempts. */
+const DEFAULT_RECOVERY_COOLDOWN_MS = 1e4;
+/** Grace period in ms before treating ICE 'disconnected' as a failure. */
+const DEFAULT_ICE_DISCONNECTED_GRACE_PERIOD_MS = 3e3;
+/** Timeout for a single ICE restart attempt in milliseconds. */
+const DEFAULT_ICE_RESTART_TIMEOUT_MS$1 = 5e3;
+/** Maximum recovery attempts before emitting 'max_attempts_reached'. */
+const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
+/** Upper bound in ms for waiting on iceGatheringState === 'complete' after an ICE restart. */
+const ICE_GATHERING_COMPLETE_TIMEOUT_MS = 1e4;
+/** Upper bound in ms for waiting on RTCPeerConnection.connectionState === 'connected' after a recovery ICE restart. */
+const PEER_CONNECTION_RECOVERY_WAIT_MS = 5e3;
+/** Polling interval in ms while waiting for RTCPeerConnection.connectionState to transition. */
+const PEER_CONNECTION_RECOVERY_POLL_MS = 100;
+/** Polling interval for LocalAudioPipeline.level$ (ms). ~30fps is smooth for meters. */
+const AUDIO_LEVEL_POLL_INTERVAL_MS = 33;
+/** RMS level threshold (0..1) above which the local participant is considered speaking. */
+const VAD_THRESHOLD = .03;
+/** Hold window in ms below the threshold before speaking$ flips back to false. */
+const VAD_HOLD_MS = 250;
+/** Whether to persist device selections to storage by default. */
+const DEFAULT_PERSIST_DEVICE_SELECTION = true;
+/** Whether to auto-apply device changes to active calls by default. */
+const DEFAULT_SYNC_DEVICES_TO_ACTIVE_CALLS = true;
+/** Storage keys for persisted device selections. */
+const DEVICE_STORAGE_KEY_AUDIO_INPUT = "sw:device:audioinput";
+const DEVICE_STORAGE_KEY_AUDIO_OUTPUT = "sw:device:audiooutput";
+const DEVICE_STORAGE_KEY_VIDEO_INPUT = "sw:device:videoinput";
+/** Whether to auto-mute video when the tab becomes hidden. */
+const DEFAULT_AUTO_MUTE_VIDEO_ON_HIDDEN = false;
+/** Whether to re-enumerate devices when the page becomes visible. */
+const DEFAULT_REFRESH_DEVICES_ON_VISIBLE = true;
+/** Whether to check peer connection health when the page becomes visible. */
+const DEFAULT_CHECK_CONNECTION_ON_VISIBLE = true;
+/** Whether automatic video degradation on low bandwidth is enabled. */
+const DEFAULT_ENABLE_AUTO_DEGRADATION = true;
+/** Bitrate in kbps below which video is automatically disabled. */
+const DEFAULT_DEGRADATION_BITRATE_THRESHOLD_KBPS = 150;
+/** Bitrate in kbps above which video is automatically re-enabled (hysteresis). */
+const DEFAULT_DEGRADATION_RECOVERY_THRESHOLD_KBPS = 300;
+/** Whether relay-only escalation is enabled as a last-resort recovery tier. */
+const DEFAULT_ENABLE_RELAY_FALLBACK = true;
+/** Whether to listen for browser online/offline/connection events. */
+const DEFAULT_ENABLE_NETWORK_CHANGE_DETECTION = true;
+/** Whether to intercept server-sent media-timeout hangups and attempt recovery. */
+const DEFAULT_ENABLE_SERVER_HANGUP_INTERCEPTION = true;
+/** Default video track constraints applied when video is enabled without explicit constraints. */
+const DEFAULT_VIDEO_CONSTRAINTS = {
+	width: { ideal: 1280 },
+	height: { ideal: 720 },
+	aspectRatio: 16 / 9
+};
+/** Whether stereo Opus is enabled by default. */
+const DEFAULT_STEREO_AUDIO = false;
+/** Max average bitrate for stereo Opus in bits per second. */
+const DEFAULT_STEREO_MAX_AVERAGE_BITRATE = 51e4;
+
 //#endregion
 //#region src/core/errors.ts
 var UnexpectedError = class extends Error {
@@ -9224,6 +9361,33 @@ var MediaTrackError = class extends Error {
 		this.name = "MediaTrackError";
 	}
 };
+/** True when a `getUserMedia`/`getDisplayMedia` rejection is a permission denial. */
+function isMediaAccessDenial(originalError) {
+	return originalError instanceof Error && MEDIA_ACCESS_DENIAL_NAMES.includes(originalError.name);
+}
+/**
+* Failure to acquire local media (camera, microphone, or screen capture)
+* via `getUserMedia`/`getDisplayMedia`.
+*
+* Non-fatal by default: screenshare and additional-device failures never
+* end the call, and main-connection failures degrade to receive-only when
+* possible. The wrapping site sets `fatal` to `true` only when the call
+* cannot continue (receive-only fallback disabled or no receive intent).
+*/
+var MediaAccessError = class extends Error {
+	constructor(operation, media, originalError, fatal = false) {
+		super(`Media access ${isMediaAccessDenial(originalError) ? "denied" : "failed"} for ${operation} (${media})`, { cause: originalError instanceof Error ? originalError : void 0 });
+		this.operation = operation;
+		this.media = media;
+		this.originalError = originalError;
+		this.fatal = fatal;
+		this.name = "MediaAccessError";
+	}
+	/** True when the underlying failure is a permission denial (user or policy). */
+	get denied() {
+		return isMediaAccessDenial(this.originalError);
+	}
+};
 var DPoPInitError = class extends Error {
 	constructor(originalError, message = "Failed to initialize DPoP key pair") {
 		super(message, { cause: originalError instanceof Error ? originalError : void 0 });
@@ -9873,137 +10037,6 @@ var DeviceHistoryManager = class {
 	}
 };
 
-//#endregion
-//#region src/core/constants.ts
-const INVITE_VERSION = 1e3;
-const DEFAULT_ICE_CANDIDATE_TIMEOUT_MS = 600;
-const DEFAULT_ICE_GATHERING_TIMEOUT_MS = 6e3;
-const DEFAULT_RECONNECT_CALLS_TIMEOUT_MS = 300 * 1e3;
-const DEFAULT_CONNECTION_TIMEOUT_MS = 1e4;
-const DEFAULT_RECONNECT_DELAY_MIN_MS = 100;
-const DEFAULT_RECONNECT_DELAY_MAX_MS = 3e3;
-const DEFAULT_DEVICE_DEBOUNCE_TIME_MS = 1500;
-const DEFAULT_DEVICE_POLLING_INTERVAL_MS = 0;
-const PREFERENCES_STORAGE_KEY = "sw:preferences";
-/** Scope value that enables automatic token refresh. */
-const SAT_REFRESH_SCOPE = "sat:refresh";
-/** API endpoints for device token operations. */
-const DEVICE_TOKEN_ENDPOINT = "/api/fabric/subscriber/devices/token";
-const DEVICE_REFRESH_ENDPOINT = "/api/fabric/subscriber/devices/refresh";
-/** Default device token TTL in seconds (15 minutes). */
-const DEVICE_TOKEN_DEFAULT_EXPIRE_IN = 900;
-/** Buffer time in milliseconds before expiry to trigger refresh. */
-const DEVICE_TOKEN_REFRESH_BUFFER_MS = 3e4;
-/** Maximum retry attempts for device token refresh on transient failure. */
-const DEVICE_TOKEN_REFRESH_MAX_RETRIES = 3;
-/** Base delay in milliseconds for exponential backoff on refresh retry. */
-const DEVICE_TOKEN_REFRESH_RETRY_BASE_MS = 1e3;
-/** Maximum retry attempts for developer credential refresh on transient failure. */
-const CREDENTIAL_REFRESH_MAX_RETRIES = 5;
-/** Base delay in milliseconds for exponential backoff on credential refresh retry. */
-const CREDENTIAL_REFRESH_RETRY_BASE_MS = 1e3;
-/** Maximum delay in milliseconds for credential refresh backoff. */
-const CREDENTIAL_REFRESH_MAX_DELAY_MS = 3e4;
-/** Buffer in milliseconds before token expiry to trigger refresh. */
-const CREDENTIAL_REFRESH_BUFFER_MS = 5e3;
-/**
-* 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
-* leaving the session with no active refresh mechanism.
-*/
-const CREDENTIAL_ACTIVATE_TIMEOUT_MS = 3e4;
-/** JSON-RPC error code for requester validation failure (corrupted auth state). */
-const RPC_ERROR_REQUESTER_VALIDATION_FAILED = -32003;
-/** JSON-RPC error code for invalid params (e.g., missing authentication block). */
-const RPC_ERROR_INVALID_PARAMS = -32602;
-/** JSON-RPC error code for authentication failure (invalid token, missing DPoP, etc.). */
-const RPC_ERROR_AUTHENTICATION_FAILED = -32002;
-/** Default polling interval for RTCPeerConnection.getStats() in milliseconds. */
-const DEFAULT_STATS_POLLING_INTERVAL_MS = 1e3;
-/** Number of initial samples used to build a baseline for spike detection. */
-const DEFAULT_STATS_BASELINE_SAMPLES = 10;
-/** Duration in ms with no inbound audio packets before emitting a critical issue. */
-const DEFAULT_STATS_NO_PACKET_THRESHOLD_MS = 2e3;
-/** Multiplier applied to baseline RTT to detect a warning-level RTT spike. */
-const DEFAULT_STATS_RTT_SPIKE_MULTIPLIER = 3;
-/** Packet loss fraction (0-1) above which a warning is emitted. */
-const DEFAULT_STATS_PACKET_LOSS_THRESHOLD = .05;
-/** Multiplier applied to baseline jitter to detect a jitter spike. */
-const DEFAULT_STATS_JITTER_SPIKE_MULTIPLIER = 4;
-/** Number of seconds of metrics history to retain. */
-const DEFAULT_STATS_HISTORY_SIZE = 30;
-/** Maximum keyframe requests allowed within a single burst window. */
-const DEFAULT_KEYFRAME_MAX_BURST$1 = 3;
-/** Duration of the keyframe burst window in milliseconds. */
-const DEFAULT_KEYFRAME_BURST_WINDOW_MS$1 = 3e3;
-/** Cooldown period in ms after burst limit is reached before allowing more keyframes. */
-const DEFAULT_KEYFRAME_COOLDOWN_MS$1 = 1e4;
-/** Minimum time between re-INVITE attempts in milliseconds. */
-const DEFAULT_REINVITE_DEBOUNCE_TIME_MS = 1e4;
-/** Maximum number of re-INVITE attempts per call. */
-const DEFAULT_REINVITE_MAX_ATTEMPTS = 3;
-/** Timeout for a single re-INVITE attempt in milliseconds. */
-const DEFAULT_REINVITE_TIMEOUT_MS = 5e3;
-/** Debounce window in ms to collapse multiple detection signals into one trigger. */
-const DEFAULT_RECOVERY_DEBOUNCE_TIME_MS = 2e3;
-/** Cooldown period in ms between recovery attempts. */
-const DEFAULT_RECOVERY_COOLDOWN_MS = 1e4;
-/** Grace period in ms before treating ICE 'disconnected' as a failure. */
-const DEFAULT_ICE_DISCONNECTED_GRACE_PERIOD_MS = 3e3;
-/** Timeout for a single ICE restart attempt in milliseconds. */
-const DEFAULT_ICE_RESTART_TIMEOUT_MS$1 = 5e3;
-/** Maximum recovery attempts before emitting 'max_attempts_reached'. */
-const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
-/** Upper bound in ms for waiting on iceGatheringState === 'complete' after an ICE restart. */
-const ICE_GATHERING_COMPLETE_TIMEOUT_MS = 1e4;
-/** Upper bound in ms for waiting on RTCPeerConnection.connectionState === 'connected' after a recovery ICE restart. */
-const PEER_CONNECTION_RECOVERY_WAIT_MS = 5e3;
-/** Polling interval in ms while waiting for RTCPeerConnection.connectionState to transition. */
-const PEER_CONNECTION_RECOVERY_POLL_MS = 100;
-/** Polling interval for LocalAudioPipeline.level$ (ms). ~30fps is smooth for meters. */
-const AUDIO_LEVEL_POLL_INTERVAL_MS = 33;
-/** RMS level threshold (0..1) above which the local participant is considered speaking. */
-const VAD_THRESHOLD = .03;
-/** Hold window in ms below the threshold before speaking$ flips back to false. */
-const VAD_HOLD_MS = 250;
-/** Whether to persist device selections to storage by default. */
-const DEFAULT_PERSIST_DEVICE_SELECTION = true;
-/** Whether to auto-apply device changes to active calls by default. */
-const DEFAULT_SYNC_DEVICES_TO_ACTIVE_CALLS = true;
-/** Storage keys for persisted device selections. */
-const DEVICE_STORAGE_KEY_AUDIO_INPUT = "sw:device:audioinput";
-const DEVICE_STORAGE_KEY_AUDIO_OUTPUT = "sw:device:audiooutput";
-const DEVICE_STORAGE_KEY_VIDEO_INPUT = "sw:device:videoinput";
-/** Whether to auto-mute video when the tab becomes hidden. */
-const DEFAULT_AUTO_MUTE_VIDEO_ON_HIDDEN = false;
-/** Whether to re-enumerate devices when the page becomes visible. */
-const DEFAULT_REFRESH_DEVICES_ON_VISIBLE = true;
-/** Whether to check peer connection health when the page becomes visible. */
-const DEFAULT_CHECK_CONNECTION_ON_VISIBLE = true;
-/** Whether automatic video degradation on low bandwidth is enabled. */
-const DEFAULT_ENABLE_AUTO_DEGRADATION = true;
-/** Bitrate in kbps below which video is automatically disabled. */
-const DEFAULT_DEGRADATION_BITRATE_THRESHOLD_KBPS = 150;
-/** Bitrate in kbps above which video is automatically re-enabled (hysteresis). */
-const DEFAULT_DEGRADATION_RECOVERY_THRESHOLD_KBPS = 300;
-/** Whether relay-only escalation is enabled as a last-resort recovery tier. */
-const DEFAULT_ENABLE_RELAY_FALLBACK = true;
-/** Whether to listen for browser online/offline/connection events. */
-const DEFAULT_ENABLE_NETWORK_CHANGE_DETECTION = true;
-/** Whether to intercept server-sent media-timeout hangups and attempt recovery. */
-const DEFAULT_ENABLE_SERVER_HANGUP_INTERCEPTION = true;
-/** Default video track constraints applied when video is enabled without explicit constraints. */
-const DEFAULT_VIDEO_CONSTRAINTS = {
-	width: { ideal: 1280 },
-	height: { ideal: 720 },
-	aspectRatio: 16 / 9
-};
-/** Whether stereo Opus is enabled by default. */
-const DEFAULT_STEREO_AUDIO = false;
-/** Max average bitrate for stereo Opus in bits per second. */
-const DEFAULT_STEREO_MAX_AVERAGE_BITRATE = 51e4;
-
 //#endregion
 //#region src/utils/time.ts
 function fromSecToMs(seconds) {
@@ -14051,12 +14084,21 @@ var SelfParticipant = class extends Participant {
 			noise_suppression: true
 		});
 	}
-	/** Starts sharing the local screen. */
+	/**
+	* Starts sharing the local screen.
+	*
+	* The call is unaffected when acquisition fails.
+	*
+	* @throws The raw `getDisplayMedia` error. A dismissed picker or a
+	* permission denial rejects with a `NotAllowedError` `DOMException` —
+	* inspect `error.name` to tell benign cancels apart from real failures.
+	*/
 	async startScreenShare() {
 		try {
 			await this.vertoManager.addScreenMedia();
 		} catch (error) {
 			logger$24.error("[Participant.startScreenShare] Screen share error:", error);
+			throw error;
 		}
 	}
 	/** Observable of the current screen share status. */
@@ -14071,12 +14113,20 @@ var SelfParticipant = class extends Participant {
 	async stopScreenShare() {
 		return this.vertoManager.removeScreenMedia();
 	}
-	/** Adds an additional media input device to the call. */
+	/**
+	* Adds an additional media input device to the call.
+	*
+	* The call is unaffected when acquisition fails.
+	*
+	* @throws The raw `getUserMedia` error (e.g. `NotAllowedError` on
+	* permission denial) — inspect `error.name` to decide how to react.
+	*/
 	async addAdditionalDevice(options) {
 		try {
 			await this.vertoManager.addInputDevice(options);
 		} catch (error) {
-			logger$24.error("[Participant.startScreenShare] Screen share error:", error);
+			logger$24.error("[Participant.addAdditionalDevice] Additional device error:", error);
+			throw error;
 		}
 	}
 	/** Removes an additional media input device by ID. */
@@ -15708,7 +15758,7 @@ var RTCPeerConnectionController = class extends Destroyable {
 				logger$17.debug(`[RTCPeerConnectionController] ${kind} input device selected:`, deviceInfo?.label);
 			} catch (error) {
 				logger$17.error(`[RTCPeerConnectionController] Failed to select ${kind} input device:`, error);
-				this._errors$.next(toError(error));
+				this._errors$.next(new MediaTrackError("updateSelectedInputDevice", kind, error));
 				throw error;
 			}
 		};
@@ -15930,7 +15980,7 @@ var RTCPeerConnectionController = class extends Destroyable {
 			case "main":
 			default: return {
 				...options,
-				offerToReceiveAudio: true,
+				offerToReceiveAudio: this.options.receiveAudio ?? true,
 				offerToReceiveVideo: this.options.receiveVideo ?? Boolean(this.inputVideoDeviceConstraints)
 			};
 		}
@@ -16084,13 +16134,14 @@ var RTCPeerConnectionController = class extends Destroyable {
 	*/
 	async acceptInbound(mediaOverrides) {
 		if (mediaOverrides) {
-			const { audio, video, receiveAudio, receiveVideo } = mediaOverrides;
+			const { audio, video, receiveAudio, receiveVideo, fallbackToReceiveOnly } = mediaOverrides;
 			this.options = {
 				...this.options,
 				...audio !== void 0 ? { audio } : {},
 				...video !== void 0 ? { video } : {},
 				...receiveAudio !== void 0 ? { receiveAudio } : {},
-				...receiveVideo !== void 0 ? { receiveVideo } : {}
+				...receiveVideo !== void 0 ? { receiveVideo } : {},
+				...fallbackToReceiveOnly !== void 0 ? { fallbackToReceiveOnly } : {}
 			};
 			this.transceiverController?.updateOptions({
 				receiveAudio: this.receiveAudio,
@@ -16247,7 +16298,19 @@ var RTCPeerConnectionController = class extends Destroyable {
 	}
 	async setupLocalTracks() {
 		logger$17.debug("[RTCPeerConnectionController] Setting up local tracks/transceivers.");
-		const localStream = this.localStream ?? await this.localStreamController.buildLocalStream();
+		if (this.hasNoLocalMediaToSend()) {
+			if (!this.receiveAudio && !this.receiveVideo) throw new InvalidParams("Call requests no media: enable audio/video or receiveAudio/receiveVideo");
+			logger$17.debug("[RTCPeerConnectionController] No local media requested; negotiating receive-only.");
+			this.setupReceiveOnlyTransceivers();
+			return;
+		}
+		let localStream;
+		try {
+			localStream = this.localStream ?? await this.localStreamController.buildLocalStream();
+		} catch (error) {
+			this.handleLocalMediaFailure(error);
+			return;
+		}
 		if (this.transceiverController?.useAddStream ?? false) {
 			logger$17.warn("[RTCPeerConnectionController] Using deprecated addStream API to add local stream.");
 			this.peerConnection?.addStream(localStream);
@@ -16274,6 +16337,48 @@ var RTCPeerConnectionController = class extends Destroyable {
 			}
 		}
 	}
+	/** True for a main connection with no local media to send. */
+	hasNoLocalMediaToSend() {
+		const hasInputStreams = Boolean(this.options.inputAudioStream ?? this.options.inputVideoStream);
+		return this.propose === "main" && !this.localStream && !hasInputStreams && !this.inputAudioDeviceConstraints && !this.inputVideoDeviceConstraints;
+	}
+	/** The media kinds this connection wants to send: 'audiovideo' | 'video' | 'audio'. */
+	get requestedMediaKinds() {
+		const wantsAudio = Boolean(this.inputAudioDeviceConstraints);
+		const wantsVideo = Boolean(this.inputVideoDeviceConstraints);
+		if (wantsAudio && wantsVideo) return "audiovideo";
+		return wantsVideo ? "video" : "audio";
+	}
+	/**
+	* Handle a local media acquisition failure with a typed, semantically
+	* accurate MediaAccessError created at the acquisition site:
+	* - Auxiliary connections (screenshare / additional-device) throw a
+	*   non-fatal error — VertoManager surfaces it and the call is unaffected.
+	* - The main connection degrades to receive-only when allowed (default),
+	*   otherwise fails with a fatal error.
+	*/
+	handleLocalMediaFailure(error) {
+		if (this.propose === "screenshare") throw new MediaAccessError("startScreenShare", "screen", error, false);
+		if (this.propose === "additional-device") throw new MediaAccessError("addInputDevice", this.requestedMediaKinds, error, false);
+		const canReceive = this.receiveAudio || this.receiveVideo;
+		if (!((this.options.fallbackToReceiveOnly ?? true) && canReceive)) throw new MediaAccessError("acquireLocalMedia", this.requestedMediaKinds, error, true);
+		logger$17.warn("[RTCPeerConnectionController] Local media unavailable; continuing receive-only:", error);
+		this._errors$.next(new MediaAccessError("acquireLocalMedia", this.requestedMediaKinds, error, false));
+		this.setupReceiveOnlyTransceivers();
+	}
+	/**
+	* Negotiate receive-only m-lines when there are no local tracks to send.
+	* Only offer-type connections add transceivers — answer-type connections
+	* reuse the transceivers created from the remote offer.
+	*/
+	setupReceiveOnlyTransceivers() {
+		if (this.type !== "offer") return;
+		if (this.transceiverController?.useAddTransceivers ?? false) {
+			this.peerConnection?.addTransceiver("audio", { direction: this.receiveAudio ? "recvonly" : "inactive" });
+			this.peerConnection?.addTransceiver("video", { direction: this.receiveVideo ? "recvonly" : "inactive" });
+		}
+		if (!this.isNegotiating) this.negotiationNeeded$.next();
+	}
 	async getUserMedia(constraints) {
 		return (this.options.webRTCApiProvider?.mediaDevices ?? navigator.mediaDevices).getUserMedia(constraints);
 	}
@@ -16310,7 +16415,7 @@ var RTCPeerConnectionController = class extends Destroyable {
 			stream = await this.getUserMedia({ audio: constraints });
 		} catch (error) {
 			logger$17.error("[RTCPeerConnectionController] Failed to re-acquire mic for pipeline restore:", error);
-			this._errors$.next(toError(error));
+			this._errors$.next(new MediaTrackError("restoreAudioPipelineInput", "audio", error));
 			return;
 		}
 		const newTrack = stream.getAudioTracks().at(0);
@@ -16372,7 +16477,7 @@ var RTCPeerConnectionController = class extends Destroyable {
 			logger$17.debug(`[RTCPeerConnectionController] ${track.kind} track added:`, track.id);
 		} catch (error) {
 			logger$17.error(`[RTCPeerConnectionController] Failed to add ${track.kind} track:`, error);
-			this._errors$.next(toError(error));
+			this._errors$.next(new MediaTrackError("addLocalTrack", track.kind, error));
 			throw error;
 		}
 	}
@@ -16397,7 +16502,7 @@ var RTCPeerConnectionController = class extends Destroyable {
 			logger$17.debug(`[RTCPeerConnectionController] ${sender.track?.kind} track removed:`, trackId);
 		} catch (error) {
 			logger$17.error(`[RTCPeerConnectionController] Failed to remove ${sender.track?.kind} track:`, error);
-			this._errors$.next(toError(error));
+			this._errors$.next(new MediaTrackError("removeLocalTrack", sender.track?.kind ?? "unknown", error));
 			throw error;
 		}
 	}
@@ -17006,6 +17111,7 @@ var WebRTCVertoManager = class extends VertoManager {
 			inputVideoStream: options.inputVideoStream,
 			receiveAudio: options.receiveAudio,
 			receiveVideo: options.receiveVideo,
+			fallbackToReceiveOnly: options.fallbackToReceiveOnly,
 			webRTCApiProvider: this.webRTCApiProvider,
 			preferredVideoCodecs: options.preferredVideoCodecs,
 			preferredAudioCodecs: options.preferredAudioCodecs,
@@ -17232,9 +17338,11 @@ var WebRTCVertoManager = class extends VertoManager {
 		await this.initAdditionalPeerConnection("screenshare", options);
 	}
 	async initAdditionalPeerConnection(propose, options) {
+		const isScreenShare = propose === "screenshare";
+		let firstPeerConnectionError;
 		let rtcPeerConnController = null;
 		try {
-			this._screenShareStatus$.next("starting");
+			if (isScreenShare) this._screenShareStatus$.next("starting");
 			rtcPeerConnController = new RTCPeerConnectionController({
 				...options,
 				...this.RTCPeerConnectionConfig,
@@ -17242,21 +17350,27 @@ var WebRTCVertoManager = class extends VertoManager {
 				webRTCApiProvider: this.webRTCApiProvider
 			}, void 0, this.deviceController);
 			this.setupLocalDescriptionHandler(rtcPeerConnController);
-			if (propose === "screenshare") this._screenShareId = rtcPeerConnController.id;
+			if (isScreenShare) this._screenShareId = rtcPeerConnController.id;
 			this._rtcPeerConnectionsMap.set(rtcPeerConnController.id, rtcPeerConnController);
 			this._rtcPeerConnections$.next(Array.from(this._rtcPeerConnectionsMap.values()));
 			this.subscribeTo(rtcPeerConnController.errors$, (error) => {
-				this.onError?.(error);
+				firstPeerConnectionError ??= error;
+				this.onError?.(error, { fatal: false });
 			});
 			await (0, import_cjs$15.firstValueFrom)(rtcPeerConnController.connectionState$.pipe((0, import_cjs$15.filter)((state) => state === "connected"), (0, import_cjs$15.take)(1), (0, import_cjs$15.timeout)(this._screenShareTimeoutMs), (0, import_cjs$15.takeUntil)(this.destroyed$)));
-			this._screenShareStatus$.next("started");
-			logger$16.info("[WebRTCManager] Screen share started successfully.");
+			if (isScreenShare) this._screenShareStatus$.next("started");
+			logger$16.info(`[WebRTCManager] Additional peer connection connected (${propose}).`);
 			return rtcPeerConnController.id;
 		} catch (error) {
 			logger$16.warn("[WebRTCManager] Error initializing additional peer connection:", error);
-			this.onError?.(error instanceof Error ? error : new Error(String(error), { cause: error }));
 			if (rtcPeerConnController) rtcPeerConnController.destroy();
-			this._screenShareStatus$.next("none");
+			if (isScreenShare) this._screenShareStatus$.next("none");
+			if (firstPeerConnectionError) throw firstPeerConnectionError instanceof MediaAccessError && firstPeerConnectionError.originalError instanceof Error ? firstPeerConnectionError.originalError : firstPeerConnectionError;
+			if (error instanceof import_cjs$15.EmptyError) {
+				logger$16.debug("[WebRTCManager] Additional peer connection aborted before connecting.");
+				return;
+			}
+			throw error instanceof Error ? error : new Error(String(error), { cause: error });
 		}
 	}
 	async removeInputDevices(id) {
@@ -19197,6 +19311,7 @@ function inferCallErrorKind(error) {
 	if (error instanceof RPCTimeoutError) return "timeout";
 	if (error instanceof JSONRPCError) return "signaling";
 	if (error instanceof MediaTrackError) return "media";
+	if (error instanceof MediaAccessError) return "media";
 	if (error instanceof WebSocketConnectionError || error instanceof TransportConnectionError) return "network";
 	return "internal";
 }
@@ -19213,6 +19328,7 @@ const RECOVERABLE_RPC_CODES = new Set([
 function isFatalError(error) {
 	if (error instanceof VertoPongError) return false;
 	if (error instanceof MediaTrackError) return false;
+	if (error instanceof MediaAccessError) return error.fatal;
 	if (error instanceof RPCTimeoutError) return false;
 	if (error instanceof JSONRPCError && RECOVERABLE_RPC_CODES.has(error.code)) return false;
 	return true;
@@ -19238,10 +19354,10 @@ var CallFactory = class {
 				return {
 					vertoManager: new WebRTCVertoManager(callInstance, this.attachManager, this.deviceController, this.webRTCApiProvider, {
 						nodeId: options.nodeId,
-						onError: (error) => {
+						onError: (error, options$1) => {
 							const callError = {
 								kind: inferCallErrorKind(error),
-								fatal: isFatalError(error),
+								fatal: options$1?.fatal ?? isFatalError(error),
 								error,
 								callId: callInstance.id
 							};
@@ -19704,6 +19820,17 @@ var PendingRPC = class PendingRPC {
 //#region src/managers/ClientSessionManager.ts
 var import_cjs$7 = require_cjs();
 const logger$9 = getLogger();
+/**
+* Decide whether an error emitted on `call.errors$` during dial should
+* abort the dial. A non-fatal MediaAccessError means the call degraded to
+* receive-only and still connects — everything else rejects `dial()` with
+* the real cause.
+*
+* Pure function — exported for unit testing.
+*/
+function shouldAbortDial(callError) {
+	return callError.fatal || !(callError.error instanceof MediaAccessError);
+}
 const getAddressSearchURI = (options) => {
 	const to = options.to?.split("?")[0];
 	const from$9 = options.from?.startsWith("subscriber://") ? options.from.replace("subscriber://", "") : options.from;
@@ -20130,7 +20257,7 @@ var ClientSessionManager = class extends Destroyable {
 				to: destinationURI,
 				...options
 			});
-			await (0, import_cjs$7.firstValueFrom)((0, import_cjs$7.race)(callSession.selfId$.pipe((0, import_cjs$7.filter)((id) => Boolean(id)), (0, import_cjs$7.take)(1), (0, import_cjs$7.timeout)(this.callCreateTimeout)), callSession.errors$.pipe((0, import_cjs$7.take)(1), (0, import_cjs$7.switchMap)((callError) => (0, import_cjs$7.throwError)(() => callError.error)))));
+			await (0, import_cjs$7.firstValueFrom)((0, import_cjs$7.race)(callSession.selfId$.pipe((0, import_cjs$7.filter)((id) => Boolean(id)), (0, import_cjs$7.take)(1), (0, import_cjs$7.timeout)(this.callCreateTimeout)), callSession.errors$.pipe((0, import_cjs$7.filter)(shouldAbortDial), (0, import_cjs$7.take)(1), (0, import_cjs$7.switchMap)((callError) => (0, import_cjs$7.throwError)(() => callError.error)))));
 			this._calls$.next({
 				[`${callSession.id}`]: callSession,
 				...this._calls$.value
@@ -21842,7 +21969,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);
 		}
@@ -22377,7 +22504,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`
@@ -22399,7 +22526,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);
 	}
 };
@@ -22423,5 +22550,5 @@ emitReadyEvent();
 if (typeof process === "undefined") globalThis.process = { env: { NODE_ENV: "production" } };
 
 //#endregion
-export { Address, CallCreateError, ClientPreferences, CollectionFetchError, DPoPInitError, DeviceTokenError, EmbedTokenCredentialProvider, InvalidCredentialsError, 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, 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 };
 //# sourceMappingURL=browser.mjs.map