@q9labsai/chalk-client 4.1.14 → 4.1.16

package/dist/{chunk-S5OUHFGC.js → chunk-O7WTAXAY.js}

@@ -1,3 +1,44 @@
+import {
+  journeyHeaders
+} from "./chunk-HW5TTZL2.js";
+import {
+  recordReconnect,
+  traceReconnect
+} from "./chunk-RCDXIDCN.js";
+
+// src/media/camera-uplink.ts
+var CameraUplinkPolicy = class {
+  #healthySamples = 0;
+  sample(bitrate, lowActive) {
+    if (bitrate === void 0 || !Number.isFinite(bitrate) || bitrate <= 0) {
+      this.reset();
+      return lowActive;
+    }
+    if (bitrate < 15e5) {
+      this.reset();
+      return false;
+    }
+    if (lowActive) {
+      this.reset();
+      return true;
+    }
+    if (bitrate < 2e6) {
+      this.reset();
+      return false;
+    }
+    return ++this.#healthySamples >= 5;
+  }
+  reset() {
+    this.#healthySamples = 0;
+  }
+};
+function cameraUplinkBitrate(stats) {
+  for (const stat of stats) {
+    if (stat.type === "candidate-pair" && stat.state === "succeeded" && (stat.nominated || stat.selected)) return stat.availableOutgoingBitrate;
+  }
+  return void 0;
+}
+
 // src/media/observers.ts
 function subscribeSnapshot(listeners, listener) {
   listeners.add(listener);
@@ -132,14 +173,37 @@ async function waitFor(predicate, timeoutMs, timeoutMessage = "Timed out waiting
   }
 }
 
+// src/media/remote-track-response.ts
+function matchRemotePullTracks(publications, tracks) {
+  const requested = new Map(
+    publications.map((publication) => {
+      const reference = parseCloudflareSFUPublicationID(publication.publicationId);
+      return [`${reference.connectionId}\0${reference.trackName}`, publication];
+    })
+  );
+  const mids = /* @__PURE__ */ new Set();
+  return tracks.map(({ location, sessionId: connectionId, trackName, mid }) => {
+    const key = `${connectionId}\0${trackName}`;
+    const publication = requested.get(key);
+    if (location !== "remote" || !publication || !mid || mids.has(mid)) throw new CloudflareSFUError("Cloudflare SFU returned an invalid remote track identity", "invalid_publication");
+    requested.delete(key);
+    mids.add(mid);
+    return { publication, mid };
+  });
+}
+
 // src/media/client.ts
 var EMPTY_LOCAL = Object.freeze([]);
 var EMPTY_REMOTE = Object.freeze([]);
+var INVALID_PUBLICATION_SIGNATURE = "\0invalid";
 var CONNECTION_TIMEOUT_MS = 8e3;
+var NEGOTIATION_TIMEOUT_MS = 35e3;
+var PEER_OPERATION_TIMEOUT_MS = 8e3;
 var CloudflareSFUClient = class {
   #localListeners = /* @__PURE__ */ new Set();
   #onError;
   #onRemoteTrack;
+  #recordReconnect;
   #onRtcSummary;
   #onScreenEnded;
   #participantId;
@@ -148,17 +212,24 @@ var CloudflareSFUClient = class {
   #replaceMediaConnection;
   #remoteListeners = /* @__PURE__ */ new Set();
   #snapshotListeners = /* @__PURE__ */ new Set();
+  #locallyPausedSources = /* @__PURE__ */ new Set();
   #localTracks = /* @__PURE__ */ new Map();
   #reusableLocalTransceivers = /* @__PURE__ */ new Map();
+  #reusableLocalPublicationIds = /* @__PURE__ */ new Map();
   #remoteTracks = /* @__PURE__ */ new Map();
   #bootstrap;
   #connection;
+  #disposeConnectionObservation;
   #connectionEpoch = 0;
+  #retiredLocalConnection = null;
   #cursor = null;
+  #remotePullIncomplete = false;
+  #remotePullRetryAfter = /* @__PURE__ */ new Map();
   #generation = 0;
   #negotiatedGeneration = null;
   #replacementAttemptedGeneration = null;
   #polling = false;
+  #pollAfterCurrent = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
   #snapshot;
@@ -170,11 +241,12 @@ var CloudflareSFUClient = class {
     this.#participantId = options.participantId;
     this.#bootstrap = options.bootstrap;
     this.#transport = options.transport;
-    this.#pollIntervalMs = options.pollIntervalMs ?? 1e3;
+    this.#pollIntervalMs = options.pollIntervalMs ?? 15e3;
     this.#replaceMediaConnection = options.replaceMediaConnection;
     this.#onError = options.onError;
     this.#onRemoteTrack = options.onRemoteTrack;
     this.#onRtcSummary = options.onRtcSummary;
+    this.#recordReconnect = options.recordReconnect;
     this.#onScreenEnded = options.onScreenEnded;
     this.#peerConnectionFactory = options.peerConnectionFactory;
     this.#connection = this.#createPeerConnection(options.bootstrap);
@@ -193,6 +265,19 @@ var CloudflareSFUClient = class {
   subscribe(listener) {
     return subscribeSnapshot(this.#snapshotListeners, listener);
   }
+  remotePublicationResumed(publicationId) {
+    this.#remotePullRetryAfter.delete(publicationId);
+    this.remotePublicationsChanged();
+  }
+  remotePublicationsChanged() {
+    recordReconnect(this.#recordReconnect, "remote_publications_changed");
+    if (this.#polling) {
+      this.#pollAfterCurrent = true;
+      return;
+    }
+    this.#clearPoll();
+    this.#schedulePoll(0);
+  }
   prepareLocalTrack(source, track) {
     this.#requireActive();
     validateTrackSource(source, track);
@@ -201,7 +286,7 @@ var CloudflareSFUClient = class {
       source,
       track,
       transceiver: this.#reusableLocalTransceivers.get(source) ?? null,
-      providerPublicationId: null,
+      providerPublicationId: this.#reusableLocalPublicationIds.get(source) ?? null,
       pendingOperationId: null,
       pendingTrackName: null,
       desiredEnabled: false,
@@ -209,6 +294,7 @@ var CloudflareSFUClient = class {
       endedListener: null
     };
     this.#reusableLocalTransceivers.delete(source);
+    this.#reusableLocalPublicationIds.delete(source);
     if (source === "screen") {
       state.endedListener = () => {
         if (this.#localTracks.get("screen") === state) this.#invokeListener(() => this.#onScreenEnded?.());
@@ -224,6 +310,7 @@ var CloudflareSFUClient = class {
     if (!state) return;
     if (state.enabled) await this.#setPreparedTrackEnabled(state, false);
     if (state.transceiver) this.#reusableLocalTransceivers.set(source, state.transceiver);
+    if (state.providerPublicationId) this.#reusableLocalPublicationIds.set(source, state.providerPublicationId);
     this.#removeOwnedLocalTrack(state);
     this.#localTracks.delete(source);
     this.#publishSnapshot();
@@ -247,28 +334,118 @@ var CloudflareSFUClient = class {
     const generation = this.#generation;
     try {
       const transport = this.#requireTransport();
-      const authoritative = await transport.listPublications();
+      const authoritative = await traceReconnect(this.#recordReconnect, "list_publications", () => transport.listPublications());
       this.#requireGeneration(generation);
       await this.#reconcileRemotePublications(authoritative, generation);
     } catch (error) {
       if (generation === this.#generation && !this.#stopped) this.#reportError(error);
       throw error;
     } finally {
-      if (generation === this.#generation) this.#polling = false;
+      if (generation === this.#generation) {
+        this.#polling = false;
+        if (this.#pollAfterCurrent) {
+          this.#pollAfterCurrent = false;
+          this.#clearPoll();
+          this.#schedulePoll(0);
+        }
+      }
     }
   }
   async setLocalPublicationTarget(target) {
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result") return resolved.result;
     const state = resolved.value;
-    if (state.enabled === target.enabled) return { outcome: "satisfied", errorCode: null };
+    if (this.#pausedTarget(target)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
     try {
+      if (target.enabled) await this.#retireUnavailableLocalPublication(state);
+      if (this.#pausedTarget(target)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
+      if (state.enabled === target.enabled) return { outcome: "satisfied", errorCode: null };
       await this.#setPreparedTrackEnabled(state, target.enabled, target.operationId);
       return { outcome: "confirmed", errorCode: null };
     } catch (error) {
       if (!this.#stopped) this.#reportError(error);
-      return { outcome: "retryable_failure", errorCode: error instanceof CloudflareSFUError ? error.code : "media_failed" };
+      return mediaTargetFailure(error);
+    }
+  }
+  #pausedTarget(target) {
+    return target.enabled && this.#locallyPausedSources.has(target.source);
+  }
+  setLocalSourceIntent(source, enabled) {
+    if (enabled) {
+      this.#locallyPausedSources.delete(source);
+      return;
     }
+    this.#locallyPausedSources.add(source);
+    const state = this.#localTracks.get(source);
+    if (!state) return;
+    state.desiredEnabled = false;
+    state.track.enabled = false;
+  }
+  async closeForcedLocalPublication(source) {
+    this.setLocalSourceIntent(source, false);
+    await this.#retireLocalPublication(source);
+    if (!this.#replaceMediaConnection) return;
+    const generation = this.#generation;
+    await this.#serializeSDP(async () => {
+      const existing = new Set([...this.#localTracks.values()].filter((state) => state.source !== source && state.providerPublicationId !== null));
+      const states = await this.#prepareConnectionForPublication([], generation);
+      await this.#publishPreparedTracksSerialized(
+        states.filter((state) => existing.has(state)),
+        generation,
+        this.#connection,
+        this.#bootstrap.connectionId
+      );
+      this.#requireGeneration(generation);
+      this.#setPhase("live", null);
+    });
+  }
+  async #retireUnavailableLocalPublication(state) {
+    const publicationId = state.providerPublicationId;
+    if (!publicationId) return;
+    const authoritative = await traceReconnect(this.#recordReconnect, "list_publications", () => this.#requireTransport().listPublications());
+    if (authoritative.publications.some((publication) => publication.publicationId === publicationId)) return;
+    if (state.providerPublicationId === publicationId) await this.#retireLocalPublication(state.source);
+  }
+  async #retireLocalPublication(source) {
+    const state = this.#localTracks.get(source);
+    const transceiver = state?.transceiver ?? this.#reusableLocalTransceivers.get(source);
+    const publicationId = state?.providerPublicationId ?? this.#reusableLocalPublicationIds.get(source);
+    this.#reusableLocalTransceivers.delete(source);
+    this.#reusableLocalPublicationIds.delete(source);
+    if (state) {
+      state.track.enabled = false;
+      state.desiredEnabled = false;
+      state.enabled = false;
+      state.providerPublicationId = null;
+      state.transceiver = null;
+    }
+    this.#publishSnapshot();
+    this.#emitLocal();
+    if (!transceiver || !publicationId) return;
+    const connection = this.#connection;
+    const connectionId = this.#bootstrap.connectionId;
+    this.#retiredLocalConnection = connection;
+    await this.#serializeSDP(async () => {
+      if (connection !== this.#connection) return;
+      const mid = requireTransceiverMid(transceiver);
+      await this.#boundPeerOperation(transceiver.sender.replaceTrack(null));
+      transceiver.stop();
+      const offer = await traceReconnect(this.#recordReconnect, "create_offer", () => connection.createOffer());
+      await traceReconnect(this.#recordReconnect, "set_local_description", () => connection.setLocalDescription(offer));
+      try {
+        const response = await this.#requireTransport().closeTracks({
+          connectionId,
+          ...providerDescription(requireDescription(offer)),
+          tracks: [{ mid, source, publicationId }],
+          force: false
+        });
+        await this.#applyProviderDescription(response, connection);
+      } catch (error) {
+        await this.#rollbackLocalOffer(connection);
+        if (!this.#stopped) this.#reportError(error);
+        throw error;
+      }
+    });
   }
   observeLocalPublications(listener) {
     this.#localListeners.add(listener);
@@ -284,16 +461,21 @@ var CloudflareSFUClient = class {
     this.#requireActive();
     const options = "connectionId" in input ? { bootstrap: input } : input;
     validateBootstrap(options.bootstrap);
+    recordReconnect(this.#recordReconnect, "media_rebuild_start");
     const generation = ++this.#generation;
     const connectionEpoch = ++this.#connectionEpoch;
     this.#polling = false;
+    this.#pollAfterCurrent = false;
     this.#clearPoll();
+    this.#remotePullRetryAfter.clear();
     this.#disposeConnection(false);
     this.#reusableLocalTransceivers.clear();
+    this.#reusableLocalPublicationIds.clear();
     this.#clearRemoteTracks();
     this.#cursor = null;
     this.#negotiatedGeneration = null;
     this.#replacementAttemptedGeneration = null;
+    if (options.bootstrap.connectionId !== this.#bootstrap.connectionId) this.#started = false;
     this.#bootstrap = options.bootstrap;
     if (options.transport) this.#transport = options.transport;
     this.#connection = this.#createPeerConnection(options.bootstrap);
@@ -324,9 +506,12 @@ var CloudflareSFUClient = class {
     this.#generation++;
     this.#connectionEpoch++;
     this.#clearPoll();
+    this.#remotePullRetryAfter.clear();
     this.#polling = false;
+    this.#pollAfterCurrent = false;
     this.#disposeConnection(true);
     this.#reusableLocalTransceivers.clear();
+    this.#reusableLocalPublicationIds.clear();
     this.#clearRemoteTracks();
     for (const state of this.#localTracks.values()) this.#removeOwnedLocalTrack(state);
     this.#localTracks.clear();
@@ -345,14 +530,33 @@ var CloudflareSFUClient = class {
     return this.#disablePreparedTrack(state);
   }
   async #enablePreparedTrack(state, operationId) {
+    if (state.providerPublicationId && state.transceiver) {
+      state.desiredEnabled = true;
+      state.track.enabled = true;
+      try {
+        await this.#boundPeerOperation(state.transceiver.sender.replaceTrack(state.track));
+      } catch (error) {
+        state.desiredEnabled = false;
+        state.track.enabled = false;
+        throw error;
+      }
+      state.enabled = !this.#locallyPausedSources.has(state.source);
+      state.desiredEnabled = state.enabled;
+      state.track.enabled = state.enabled;
+      if (!state.enabled) await this.#boundPeerOperation(state.transceiver.sender.replaceTrack(null));
+      this.#publishSnapshot();
+      this.#emitLocal();
+      return;
+    }
     if (operationId && state.pendingOperationId !== operationId) {
       state.pendingOperationId = operationId;
       state.pendingTrackName = `${state.source}-${operationId}`;
     }
     state.desiredEnabled = true;
     state.track.enabled = true;
+    const generation = this.#generation;
     try {
-      await this.#publishPreparedTracks([state], this.#generation);
+      await this.#publishPreparedTracks([state], generation);
     } catch (error) {
       state.desiredEnabled = false;
       state.enabled = false;
@@ -364,26 +568,21 @@ var CloudflareSFUClient = class {
     const transceiver = state.transceiver;
     state.desiredEnabled = false;
     state.track.enabled = false;
-    try {
-      if (transceiver) await transceiver.sender.replaceTrack(null);
-    } catch (error) {
-      state.desiredEnabled = true;
-      state.track.enabled = true;
-      throw error;
-    }
+    const detach = transceiver ? this.#boundPeerOperation(transceiver.sender.replaceTrack(null)) : Promise.resolve();
     state.enabled = false;
-    state.providerPublicationId = null;
     state.pendingOperationId = null;
     state.pendingTrackName = null;
     this.#publishSnapshot();
     this.#emitLocal();
+    await detach;
   }
   async #publishPreparedTracks(states, generation) {
     if (states.length === 0) return;
     await this.#serializeSDP(async () => {
-      await this.#replaceDormantConnectionBeforeNegotiation(generation);
+      const pending = await this.#prepareConnectionForPublication(states, generation);
+      this.#replacementAttemptedGeneration = null;
       try {
-        await this.#publishPreparedTracksSerialized(states, generation, this.#connection, this.#bootstrap.connectionId);
+        await this.#publishPreparedTracksSerialized(pending, generation, this.#connection, this.#bootstrap.connectionId);
       } catch (error) {
         if (!this.#replaceMediaConnection || !this.#isRetryableConnectionFailure(error) || this.#replacementAttemptedGeneration === generation) throw error;
         await this.#replaceMediaConnectionForRecovery(generation);
@@ -396,6 +595,25 @@ var CloudflareSFUClient = class {
       }
     });
   }
+  async #prepareConnectionForPublication(states, generation) {
+    if (this.#retiredLocalConnection !== this.#connection || !this.#replaceMediaConnection) {
+      await this.#replaceDormantConnectionBeforeNegotiation(generation);
+      return states;
+    }
+    const authoritative = await traceReconnect(this.#recordReconnect, "list_publications", () => this.#requireTransport().listPublications());
+    this.#pauseUnavailableOtherSources(authoritative.publications, states);
+    this.#replacementAttemptedGeneration = null;
+    await this.#replaceMediaConnectionForRecovery(generation);
+    return [...this.#localTracks.values()].filter((state) => (state.desiredEnabled || states.includes(state)) && state.track.readyState !== "ended");
+  }
+  #pauseUnavailableOtherSources(publications, states) {
+    for (const state of this.#localTracks.values()) {
+      if (states.includes(state) || !state.providerPublicationId) continue;
+      if (publications.some((publication) => publication.publicationId === state.providerPublicationId)) continue;
+      state.desiredEnabled = false;
+      state.track.enabled = false;
+    }
+  }
   async #publishPreparedTracksSerialized(states, generation, connection, connectionId) {
     this.#requireGeneration(generation);
     const pendingStates = states.filter((state) => !state.enabled);
@@ -403,7 +621,7 @@ var CloudflareSFUClient = class {
     const wasLive = connectionIsLive(connection);
     const publications = [];
     try {
-      for (const state of pendingStates) publications.push(await this.#prepareLocalPublication(connection, state));
+      for (const state of pendingStates) publications.push(await this.#prepareLocalPublication(connection, state, generation));
       const response = await this.#negotiateLocalPublications(connection, connectionId, publications, generation);
       if (!wasLive) await this.#waitForConnection(connection, generation);
       this.#requireGeneration(generation);
@@ -412,21 +630,56 @@ var CloudflareSFUClient = class {
       this.#publishSnapshot();
       this.#emitLocal();
     } catch (error) {
-      await this.#rollbackLocalOffer(connection);
-      await this.#discardLocalPublications(publications);
+      if (generation === this.#generation) {
+        await this.#rollbackLocalOffer(connection);
+        await this.#discardLocalPublications(publications);
+      }
       throw error;
     }
   }
-  async #prepareLocalPublication(connection, state) {
+  async #prepareLocalPublication(connection, state, generation) {
     const reusedTransceiver = state.transceiver !== null;
-    const transceiver = state.transceiver ?? connection.addTransceiver(state.track, { direction: "sendonly" });
-    if (reusedTransceiver) await transceiver.sender.replaceTrack(state.track);
+    const transceiver = state.transceiver ?? this.#addLocalTransceiver(connection, state);
+    if (reusedTransceiver) await this.#boundPeerOperation(transceiver.sender.replaceTrack(state.track));
+    this.#requireGeneration(generation);
     state.transceiver = transceiver;
     return { state, transceiver, trackName: state.pendingTrackName ?? `${state.source}-${globalThis.crypto.randomUUID()}`, reusedTransceiver };
   }
+  #addLocalTransceiver(connection, state) {
+    if (state.source !== "camera" || firefoxCameraSimulcastUnsupported()) return connection.addTransceiver(state.track, { direction: "sendonly" });
+    const sendEncodings = [
+      { rid: "h", scaleResolutionDownBy: 1, maxBitrate: 25e5, scalabilityMode: "L1T1" },
+      { rid: "l", scaleResolutionDownBy: 2, maxBitrate: 65e4, scalabilityMode: "L1T1" }
+    ];
+    try {
+      return connection.addTransceiver(state.track, {
+        direction: "sendonly",
+        sendEncodings
+      });
+    } catch (error) {
+      if (!simulcastUnsupported(error)) throw error;
+      return connection.addTransceiver(state.track, { direction: "sendonly" });
+    }
+  }
   async #negotiateLocalPublications(connection, connectionId, publications, generation) {
-    const offer = await connection.createOffer();
-    await connection.setLocalDescription(offer);
+    let offer;
+    try {
+      offer = await traceReconnect(this.#recordReconnect, "create_offer", () => connection.createOffer());
+      await traceReconnect(this.#recordReconnect, "set_local_description", () => connection.setLocalDescription(offer));
+    } catch (error) {
+      const cameras = publications.filter(({ state, transceiver }) => state.source === "camera" && transceiver.sender.getParameters().encodings.length > 1);
+      if (!simulcastUnsupported(error) || cameras.length === 0) throw error;
+      await this.#rollbackLocalOffer(connection);
+      this.#requireGeneration(generation);
+      for (const publication of cameras) {
+        await this.#boundPeerOperation(publication.transceiver.sender.replaceTrack(null));
+        publication.transceiver.stop();
+        publication.transceiver = connection.addTransceiver(publication.state.track, { direction: "sendonly" });
+        publication.state.transceiver = publication.transceiver;
+      }
+      offer = await traceReconnect(this.#recordReconnect, "create_offer", () => connection.createOffer());
+      await traceReconnect(this.#recordReconnect, "set_local_description", () => connection.setLocalDescription(offer));
+    }
     const tracks = publications.map(
       ({ state, transceiver, trackName }) => ({
         location: "local",
@@ -435,17 +688,20 @@ var CloudflareSFUClient = class {
         source: state.source
       })
     );
-    const response = await this.#requireTransport().addTracks({ connectionId, sessionDescription: requireDescription(offer), tracks });
+    const response = await traceReconnect(this.#recordReconnect, "publish_tracks", () => this.#requireTransport().addTracks({ connectionId, ...providerDescription(requireDescription(offer)), tracks }));
     this.#requireGeneration(generation);
-    await connection.setRemoteDescription(requireSFUDescription(response.sessionDescription));
+    await this.#applyProviderDescription(response, connection);
     return response;
   }
   #confirmLocalPublications(publications, tracks) {
     for (const { state, transceiver } of publications) {
       const authoritative = tracks?.find((track) => track.location === "local" && track.mid === transceiver.mid && track.source === state.source);
       if (!authoritative?.publicationId) throw new CloudflareSFUError("Chalk did not return an authoritative local publication ID", "invalid_publication");
-      state.desiredEnabled = true;
-      state.enabled = true;
+      if (state.transceiver !== transceiver) continue;
+      state.enabled = !this.#locallyPausedSources.has(state.source);
+      state.desiredEnabled = state.enabled;
+      state.track.enabled = state.enabled;
+      if (!state.enabled) void transceiver.sender.replaceTrack(null).catch((error) => this.#reportError(error));
       state.providerPublicationId = authoritative.publicationId;
       state.pendingOperationId = null;
       state.pendingTrackName = null;
@@ -478,12 +734,13 @@ var CloudflareSFUClient = class {
     }
   }
   async #reconcileRemotePublications(authoritative, generation) {
-    const cursor = validatePublicationSnapshot(authoritative);
+    const cursor = this.#validatedRemotePublicationCursor(authoritative);
+    if (cursor === null) return;
     const ordering = comparePublicationCursor(this.#cursor, cursor);
-    if (ordering !== "newer") return;
-    const desired = desiredRemotePublications(authoritative.publications, this.#participantId);
-    const toPull = [...desired].filter(([key, publication]) => this.#remoteTracks.get(key)?.publicationId !== publication.publicationId).map(([, publication]) => publication);
-    const pulled = await this.#pull(toPull, generation);
+    if (ordering === "stale" || ordering === "same" && !this.#remotePullIncomplete) return;
+    const desired = this.#desiredRemotePublications(authoritative, cursor);
+    const toPull = this.#pendingRemotePulls(desired);
+    const pulled = await this.#pullWithRecovery(toPull, cursor, generation);
     if (pulled === null) return;
     this.#requireGeneration(generation);
     const next = reconcileRemoteTracks(desired, pulled, this.#remoteTracks);
@@ -491,10 +748,70 @@ var CloudflareSFUClient = class {
     this.#remoteTracks.clear();
     for (const [key, publication] of next) this.#remoteTracks.set(key, publication);
     this.#cursor = cursor;
+    this.#remotePullIncomplete = [...desired].some(([key, publication]) => next.get(key)?.publicationId !== publication.publicationId);
     for (const publication of pulled) this.#invokeListener(() => this.#onRemoteTrack?.(publication));
     this.#publishSnapshot();
     this.#emitRemote();
   }
+  #pendingRemotePulls(desired) {
+    const desiredIds = new Set([...desired.values()].map((publication) => publication.publicationId));
+    for (const publicationId of this.#remotePullRetryAfter.keys()) {
+      if (!desiredIds.has(publicationId)) this.#remotePullRetryAfter.delete(publicationId);
+    }
+    const now = Date.now();
+    return [...desired].filter(([key, publication]) => {
+      if (this.#remoteTracks.get(key)?.publicationId === publication.publicationId) return false;
+      const remaining = (this.#remotePullRetryAfter.get(publication.publicationId) ?? 0) - now;
+      if (remaining > 0) recordReconnect(this.#recordReconnect, "remote_pull_deferred", { remaining_ms: remaining, source: publication.source });
+      return remaining <= 0;
+    }).map(([, publication]) => publication);
+  }
+  #validatedRemotePublicationCursor(authoritative) {
+    if (this.#cursor?.signature === INVALID_PUBLICATION_SIGNATURE && this.#cursor.incarnation === authoritative.incarnation && this.#cursor.sequence === authoritative.sequence) return null;
+    try {
+      return validatePublicationSnapshot(authoritative);
+    } catch (error) {
+      this.#quarantineInvalidRemotePublicationCursor(authoritative);
+      throw error;
+    }
+  }
+  #desiredRemotePublications(authoritative, cursor) {
+    try {
+      return desiredRemotePublications(authoritative.publications, this.#participantId);
+    } catch (error) {
+      this.#observeRemotePublicationCursor(cursor);
+      throw error;
+    }
+  }
+  async #pullWithRecovery(publications, cursor, generation) {
+    try {
+      return await this.#pull(publications, generation);
+    } catch (error) {
+      if (generation !== this.#generation || this.#stopped) throw error;
+      if (!this.#canReplaceConnectionAfterRemotePull(error, generation)) {
+        this.#observeRemotePublicationCursor(cursor, retryableRemotePull(error));
+        throw error;
+      }
+      return this.#retryRemotePullOnReplacement(publications, cursor, generation);
+    }
+  }
+  #canReplaceConnectionAfterRemotePull(error, generation) {
+    return error instanceof CloudflareSFUError && error.code === "signaling_failed" && !this.#hasLiveRemoteTracks() && this.#replaceMediaConnection !== void 0 && this.#replacementAttemptedGeneration !== generation;
+  }
+  #hasLiveRemoteTracks() {
+    return [...this.#remoteTracks.values()].some((publication) => publication.track.readyState === "live");
+  }
+  async #retryRemotePullOnReplacement(publications, cursor, generation) {
+    try {
+      await this.#replaceMediaConnectionForRecovery(generation);
+      await this.#republishPreparedTracksAfterRecovery(generation);
+      return await this.#pull(publications, generation);
+    } catch (error) {
+      if (generation !== this.#generation || this.#stopped) throw error;
+      this.#observeRemotePublicationCursor(cursor, retryableRemotePull(error));
+      throw error;
+    }
+  }
   async #pull(publications, generation) {
     if (publications.length === 0) return [];
     return this.#serializeSDP(async () => {
@@ -502,7 +819,15 @@ var CloudflareSFUClient = class {
       const connectionId = this.#bootstrap.connectionId;
       const requested = publications.map((publication) => {
         const reference = parseCloudflareSFUPublicationID(publication.publicationId);
-        return { location: "remote", sessionId: reference.connectionId, trackName: reference.trackName };
+        return {
+          location: "remote",
+          sessionId: reference.connectionId,
+          trackName: reference.trackName,
+          // h sorts before l: prefer full camera quality, but keep video flowing
+          // when the publisher pauses h. Do not silently downgrade a live h layer.
+          // https://developers.cloudflare.com/realtime/sfu/features/simulcast/#quality-control
+          ...publication.source === "camera" ? { simulcast: { preferredRid: "h", priorityOrdering: "none", ridNotAvailable: "asciibetical" } } : {}
+        };
       });
       const received = /* @__PURE__ */ new Map();
       const onTrack = (event) => {
@@ -511,17 +836,20 @@ var CloudflareSFUClient = class {
       connection.addEventListener("track", onTrack);
       try {
         this.#requireGeneration(generation);
-        const response = await this.#requireTransport().addTracks({ connectionId, tracks: requested });
+        const response = await traceReconnect(this.#recordReconnect, "pull_tracks", () => this.#requireTransport().addTracks({ connectionId, tracks: requested, allowPartialRemoteTracks: true }));
         this.#requireGeneration(generation);
+        this.#recordRemotePullErrors(publications, response.trackErrors ?? []);
         const responseTracks = response.tracks ?? [];
+        const matched = matchRemotePullTracks(publications, responseTracks);
+        for (const { publication } of matched) this.#remotePullRetryAfter.delete(publication.publicationId);
         await this.#completeRenegotiation(response, connection, connectionId, generation);
+        if (matched.length === 0) return [];
         await this.#waitForConnection(connection, generation);
         this.#negotiatedGeneration = generation;
-        await waitFor(() => responseTracks.every((track) => track.mid !== void 0 && received.has(track.mid)), 5e3);
+        await traceReconnect(this.#recordReconnect, "remote_track_arrival", () => waitFor(() => responseTracks.every((track) => track.mid !== void 0 && received.has(track.mid)), 5e3));
         this.#requireGeneration(generation);
-        return publications.map((publication, index) => {
-          const responseTrack = responseTracks[index];
-          const track = responseTrack?.mid === void 0 ? void 0 : received.get(responseTrack.mid);
+        return matched.map(({ publication, mid }) => {
+          const track = received.get(mid);
           if (!track) throw new CloudflareSFUError("A negotiated remote track did not arrive", "media_failed");
           return Object.freeze({ ...publication, track });
         });
@@ -533,38 +861,151 @@ var CloudflareSFUClient = class {
       }
     });
   }
+  #recordRemotePullErrors(publications, failures) {
+    const requested = new Map(
+      publications.map((publication) => {
+        const reference = parseCloudflareSFUPublicationID(publication.publicationId);
+        return [`${reference.connectionId}\0${reference.trackName}`, publication];
+      })
+    );
+    for (const failure of failures) {
+      const publication = requested.get(`${failure.connectionId}\0${failure.trackName}`);
+      if (!publication) throw new CloudflareSFUError("Cloudflare SFU returned an unrequested remote track error", "invalid_publication");
+      const delay = 750;
+      this.#remotePullRetryAfter.set(publication.publicationId, Date.now() + delay);
+      recordReconnect(this.#recordReconnect, "remote_pull_backoff", { delay_ms: delay, retry_kind: failure.code === "empty_track_error" ? "empty_track" : "provider_error", source: publication.source });
+      this.#reportError(new CloudflareSFUError(`Cloudflare SFU remote track failed: ${failure.code}`, "media_failed", { providerCode: failure.code }));
+    }
+  }
   async #completeRenegotiation(response, connection, connectionId, generation) {
     if (!response.requiresImmediateRenegotiation) return;
-    if (!response.sessionDescription) throw new CloudflareSFUError("Cloudflare did not return a remote-track offer", "signaling_failed");
-    await connection.setRemoteDescription(response.sessionDescription);
-    const answer = await connection.createAnswer();
-    await connection.setLocalDescription(answer);
-    await this.#requireTransport().renegotiate({ connectionId, sessionDescription: requireDescription(answer) });
+    await this.#applyProviderDescription(response, connection);
+    const answer = await traceReconnect(this.#recordReconnect, "create_answer", () => connection.createAnswer());
+    await traceReconnect(this.#recordReconnect, "set_local_answer", () => connection.setLocalDescription(answer));
+    await traceReconnect(this.#recordReconnect, "renegotiate", () => this.#requireTransport().renegotiate({ connectionId, ...providerDescription(requireDescription(answer)) }));
     this.#requireGeneration(generation);
   }
+  async #applyProviderDescription(response, connection = this.#connection) {
+    await traceReconnect(this.#recordReconnect, "set_remote_description", () => connection.setRemoteDescription(requireSFUDescription(response.sessionDescription)));
+  }
   #serializeSDP(operation) {
-    const result = this.#sdpTail.then(operation, operation);
+    const generation = this.#generation;
+    const queuedAt = performance.now();
+    let expired = false;
+    let timer;
+    const timeout = new CloudflareSFUError("Cloudflare SFU negotiation timed out. Try again.", "negotiation_timeout");
+    const deadline = new Promise((_resolve, reject) => {
+      timer = globalThis.setTimeout(() => {
+        expired = true;
+        if (generation === this.#generation && !this.#stopped) this.#expireNegotiation(timeout);
+        reject(timeout);
+      }, NEGOTIATION_TIMEOUT_MS);
+    });
+    const run = () => {
+      if (expired || generation !== this.#generation) throw timeout;
+      recordReconnect(this.#recordReconnect, "sdp_queue", { duration_ms: performance.now() - queuedAt });
+      return operation();
+    };
+    const pending = this.#sdpTail.then(run, run);
+    const result = Promise.race([pending, deadline]).catch((error) => {
+      if (error instanceof CloudflareSFUError && error.code === "signaling_timeout" && generation === this.#generation && !this.#stopped) this.#expireNegotiation(error);
+      throw error;
+    }).finally(() => {
+      if (timer !== void 0) globalThis.clearTimeout(timer);
+    });
     this.#sdpTail = result.then(
       () => void 0,
       () => void 0
     );
     return result;
   }
+  async #boundPeerOperation(operation) {
+    const generation = this.#generation;
+    let timer;
+    const timeout = new CloudflareSFUError("The browser media operation timed out. Try again.", "negotiation_timeout");
+    const deadline = new Promise((_resolve, reject) => {
+      timer = globalThis.setTimeout(() => {
+        if (generation === this.#generation && !this.#stopped) this.#expireNegotiation(timeout);
+        reject(timeout);
+      }, PEER_OPERATION_TIMEOUT_MS);
+    });
+    try {
+      await Promise.race([operation, deadline]);
+    } finally {
+      if (timer !== void 0) globalThis.clearTimeout(timer);
+    }
+  }
+  #expireNegotiation(error) {
+    this.#generation++;
+    this.#connectionEpoch++;
+    this.#clearPoll();
+    this.#polling = false;
+    this.#disposeConnection(false);
+    this.#setFailure(error, "media_failed");
+  }
   #waitForConnection(connection, generation) {
-    return waitFor(
-      () => {
-        this.#requireGeneration(generation);
-        return connectionIsLive(connection);
-      },
-      CONNECTION_TIMEOUT_MS,
-      "Timed out waiting for the Cloudflare SFU peer connection"
+    return traceReconnect(
+      this.#recordReconnect,
+      "connection_ready",
+      () => waitFor(
+        () => {
+          this.#requireGeneration(generation);
+          return connectionIsLive(connection);
+        },
+        CONNECTION_TIMEOUT_MS,
+        "Timed out waiting for the Cloudflare SFU peer connection"
+      )
     );
   }
+  #cameraSimulcastSender(state) {
+    if (!state?.enabled) return void 0;
+    const sender = state.transceiver?.sender;
+    if (!sender?.track || sender.getParameters().encodings.length < 2) return void 0;
+    return sender;
+  }
+  async #applyCameraUplink(sender, report, policy) {
+    const parameters = sender.getParameters();
+    const low = parameters.encodings.find((encoding) => encoding.rid === "l");
+    if (!low) return;
+    const active = policy.sample(cameraUplinkBitrate(report.values()), low.active !== false);
+    if (active === (low.active !== false)) return;
+    low.active = active;
+    parameters.degradationPreference = "maintain-framerate";
+    await sender.setParameters(parameters);
+  }
   #observeConnection(connection, generation, connectionEpoch) {
+    this.#disposeConnectionObservation?.();
     let disposed = false;
+    let cameraTimer;
+    const cameraPolicy = new CameraUplinkPolicy();
+    let observedCamera;
+    const current = () => !disposed && generation === this.#generation && connectionEpoch === this.#connectionEpoch && !this.#stopped && connection.connectionState !== "failed" && connection.connectionState !== "closed";
+    const adaptCamera = async () => {
+      if (!current()) return;
+      try {
+        const state = this.#localTracks.get("camera");
+        if (state !== observedCamera) {
+          cameraPolicy.reset();
+          observedCamera = state;
+        }
+        const sender = this.#cameraSimulcastSender(state);
+        if (!sender) {
+          cameraPolicy.reset();
+          return;
+        }
+        const report = await connection.getStats();
+        if (!current() || this.#cameraSimulcastSender(state) !== sender || connection.signalingState !== "stable") return;
+        await this.#applyCameraUplink(sender, report, cameraPolicy);
+      } catch {
+        cameraPolicy.reset();
+      } finally {
+        if (current()) cameraTimer = globalThis.setTimeout(adaptCamera, 1e3);
+      }
+    };
     const dispose = () => {
       if (disposed) return;
       disposed = true;
+      if (cameraTimer !== void 0) globalThis.clearTimeout(cameraTimer);
       connection.removeEventListener("connectionstatechange", capture);
       connection.removeEventListener("iceconnectionstatechange", capture);
       connection.removeEventListener("signalingstatechange", capture);
@@ -577,6 +1018,7 @@ var CloudflareSFUClient = class {
     };
     const capture = () => {
       if (disposed || generation !== this.#generation || connectionEpoch !== this.#connectionEpoch || this.#stopped) return;
+      recordReconnect(this.#recordReconnect, "rtc_state", { connection_state: connection.connectionState, ice_connection_state: connection.iceConnectionState, signaling_state: connection.signalingState });
       observe();
       const recorder = this.#onRtcSummary;
       if (recorder) {
@@ -593,11 +1035,67 @@ var CloudflareSFUClient = class {
       }
       if (connection.connectionState === "closed") dispose();
     };
+    this.#disposeConnectionObservation = dispose;
+    cameraTimer = globalThis.setTimeout(adaptCamera, 1e3);
+    if (this.#recordReconnect) this.#sampleRecoveryTraffic(connection, generation, connectionEpoch);
     connection.addEventListener("connectionstatechange", capture);
     connection.addEventListener("iceconnectionstatechange", capture);
     connection.addEventListener("signalingstatechange", capture);
     capture();
   }
+  #sampleRecoveryTraffic(connection, generation, connectionEpoch) {
+    const traffic = /* @__PURE__ */ new Map();
+    let dtlsState;
+    const current = () => generation === this.#generation && connectionEpoch === this.#connectionEpoch && !this.#stopped && connection.connectionState !== "closed" && connection.connectionState !== "failed";
+    const sample = async () => {
+      if (!current()) return;
+      try {
+        const report = await connection.getStats();
+        if (!current()) return;
+        const now = performance.now();
+        report.forEach((entry) => {
+          if (entry.type === "transport") {
+            const nextState = rtcString(entry, "dtlsState");
+            if (nextState !== dtlsState) recordReconnect(this.#recordReconnect, "dtls_state", { dtls_state: nextState ?? "unknown" });
+            dtlsState = nextState;
+          }
+          this.#observeRecoveryTraffic(entry, traffic, now);
+        });
+      } catch {
+        if (current()) recordReconnect(this.#recordReconnect, "rtc_stats_unavailable");
+      }
+      if (current()) globalThis.setTimeout(() => void sample(), 250);
+    };
+    void sample();
+  }
+  #observeRecoveryTraffic(entry, traffic, now) {
+    if (entry.type !== "inbound-rtp" && entry.type !== "outbound-rtp") return;
+    const direction = entry.type === "inbound-rtp" ? "inbound" : "outbound";
+    const kind = rtcString(entry, "kind") ?? "unknown";
+    const previous = traffic.get(entry.id);
+    const next = previous ?? {
+      packets: { count: 0, lastProgress: now, stalled: false },
+      frames: { count: 0, lastProgress: now, stalled: false }
+    };
+    const packets = recoveryTrafficCount(entry, direction, "packet");
+    const frames = recoveryTrafficCount(entry, direction, "frame");
+    this.#observeTrafficCounter(next.packets, { count: packets, now, direction, kind, unit: "packet", existed: previous !== void 0 });
+    this.#observeTrafficCounter(next.frames, { count: frames, now, direction, kind, unit: "frame", existed: previous !== void 0 });
+    traffic.set(entry.id, next);
+  }
+  #observeTrafficCounter(progress, sample) {
+    const attributes = { direction: sample.direction, kind: sample.kind };
+    if (sample.count > progress.count) {
+      if (progress.count === 0) recordReconnect(this.#recordReconnect, `first_${sample.unit}`, attributes);
+      else if (progress.stalled) recordReconnect(this.#recordReconnect, sample.unit === "packet" ? "rtp_resumed" : "frame_resumed", attributes);
+      progress.lastProgress = sample.now;
+      progress.stalled = false;
+    } else if (trafficStalled(progress, sample)) {
+      progress.stalled = true;
+      recordReconnect(this.#recordReconnect, sample.unit === "packet" ? "rtp_stall" : "frame_stall", attributes);
+    }
+    progress.count = sample.count;
+  }
   async #replaceDormantConnectionBeforeNegotiation(generation) {
     if (!this.#started || this.#negotiatedGeneration === generation || this.#replacementAttemptedGeneration === generation || !this.#replaceMediaConnection) return;
     await this.#replaceMediaConnectionForRecovery(generation);
@@ -608,7 +1106,8 @@ var CloudflareSFUClient = class {
       throw new CloudflareSFUError("A fresh Cloudflare SFU connection is unavailable", "signaling_failed");
     }
     this.#replacementAttemptedGeneration = generation;
-    const bootstrap = await this.#replaceMediaConnection();
+    const replaceMediaConnection = this.#replaceMediaConnection;
+    const bootstrap = await traceReconnect(this.#recordReconnect, "replace_access", replaceMediaConnection);
     this.#requireGeneration(generation);
     validateBootstrap(bootstrap);
     if (bootstrap.connectionId === this.#bootstrap.connectionId) {
@@ -617,10 +1116,12 @@ var CloudflareSFUClient = class {
     const connectionEpoch = ++this.#connectionEpoch;
     this.#disposeConnection(false);
     this.#reusableLocalTransceivers.clear();
+    this.#reusableLocalPublicationIds.clear();
     this.#clearRemoteTracks();
     this.#cursor = null;
     this.#bootstrap = bootstrap;
     this.#connection = this.#createPeerConnection(bootstrap);
+    this.#retiredLocalConnection = null;
     this.#negotiatedGeneration = null;
     this.#observeConnection(this.#connection, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
@@ -629,6 +1130,20 @@ var CloudflareSFUClient = class {
       state.providerPublicationId = null;
     }
     this.#setPhase("recovering", null);
+    this.remotePublicationsChanged();
+  }
+  async #republishPreparedTracksAfterRecovery(generation) {
+    const enabled = [...this.#localTracks.values()].filter((state) => state.desiredEnabled && state.track.readyState !== "ended");
+    await this.#publishPreparedTracks(enabled, generation);
+  }
+  #observeRemotePublicationCursor(cursor, pullIncomplete = false) {
+    this.#cursor = cursor;
+    this.#remotePullIncomplete = pullIncomplete;
+    this.#publishSnapshot();
+  }
+  #quarantineInvalidRemotePublicationCursor(authoritative) {
+    if (!Number.isSafeInteger(authoritative.incarnation) || authoritative.incarnation < 0 || !Number.isSafeInteger(authoritative.sequence) || authoritative.sequence < 0) return;
+    this.#observeRemotePublicationCursor({ incarnation: authoritative.incarnation, sequence: authoritative.sequence, signature: INVALID_PUBLICATION_SIGNATURE });
   }
   #isRetryableConnectionFailure(error) {
     return error instanceof CloudflareSFUError && error.code === "signaling_failed" && error.options.retryableConnection === true;
@@ -638,6 +1153,8 @@ var CloudflareSFUClient = class {
     return create({ iceServers: [{ urls: bootstrap.stunServer }], bundlePolicy: "max-bundle" });
   }
   #disposeConnection(stopSenders) {
+    this.#disposeConnectionObservation?.();
+    this.#disposeConnectionObservation = void 0;
     if (stopSenders) {
       for (const sender of this.#connection.getSenders()) {
         if (sender.track) safeStopTrack(sender.track, this.#reportError.bind(this));
@@ -677,11 +1194,15 @@ var CloudflareSFUClient = class {
     if (this.#stopped || !this.#started || this.#pollTimer !== void 0) return;
     this.#pollTimer = globalThis.setTimeout(async () => {
       this.#pollTimer = void 0;
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+        this.#schedulePoll();
+        return;
+      }
       try {
         await this.refreshRemotePublications();
       } catch {
       } finally {
-        this.#schedulePoll();
+        this.#schedulePoll(this.#remotePullIncomplete ? 750 : this.#pollIntervalMs);
       }
     }, delayMs);
   }
@@ -694,7 +1215,7 @@ var CloudflareSFUClient = class {
       participantId: this.#participantId,
       source: state.source,
       enabled: state.enabled,
-      publicationId: state.enabled ? state.providerPublicationId : null
+      publicationId: state.providerPublicationId
     }));
   }
   #projectRemotePublications() {
@@ -712,7 +1233,7 @@ var CloudflareSFUClient = class {
         (state) => Object.freeze({
           source: state.source,
           enabled: state.enabled,
-          publicationId: state.enabled ? state.providerPublicationId : null,
+          publicationId: state.providerPublicationId,
           track: state.track
         })
       ) : EMPTY_LOCAL,
@@ -848,10 +1369,10 @@ function desiredRemotePublications(publications, participantId) {
 function reconcileRemoteTracks(desired, pulled, current) {
   const pulledByKey = new Map(pulled.map((publication) => [publicationKey(publication), publication]));
   return new Map(
-    [...desired].map(([key, publication]) => {
+    [...desired].flatMap(([key, publication]) => {
       const track = pulledByKey.get(key) ?? current.get(key);
-      if (!track || track.publicationId !== publication.publicationId) throw new CloudflareSFUError("Cloudflare SFU did not return a requested remote track", "media_failed");
-      return [key, track];
+      if (!track || track.publicationId !== publication.publicationId) return [];
+      return [[key, track]];
     })
   );
 }
@@ -913,31 +1434,63 @@ function publicationEqual(left, right) {
 function remotePublicationEqual(left, right) {
   return right !== void 0 && left.participantId === right.participantId && left.source === right.source && left.publicationId === right.publicationId && left.track === right.track;
 }
+function providerDescription(description) {
+  return { sessionDescription: description };
+}
+function retryableRemotePull(error) {
+  return error instanceof CloudflareSFUError && ["signaling_failed", "signaling_timeout", "media_failed", "negotiation_timeout"].includes(error.code);
+}
+function firefoxCameraSimulcastUnsupported() {
+  return typeof navigator !== "undefined" && /\bFirefox\/\d+/i.test(navigator.userAgent);
+}
+function simulcastUnsupported(error) {
+  return error instanceof Error && ["NotSupportedError", "OperationError", "TypeError"].includes(error.name);
+}
+function mediaTargetFailure(error) {
+  const code = error instanceof CloudflareSFUError ? error.code : "media_failed";
+  const ambiguous = code === "signaling_timeout" || code === "negotiation_timeout";
+  return { outcome: ambiguous ? "ambiguous" : "retryable_failure", errorCode: code };
+}
+function recoveryTrafficCount(entry, direction, unit) {
+  const property = unit === "packet" ? direction === "inbound" ? "packetsReceived" : "packetsSent" : direction === "inbound" ? "framesDecoded" : "framesEncoded";
+  return rtcNumber(entry, property) ?? 0;
+}
+function trafficStalled(progress, sample) {
+  return sample.existed && !progress.stalled && sample.now - progress.lastProgress >= 1e3 && (sample.unit === "packet" || progress.count > 0);
+}
 
 // src/media/transport.ts
+var SIGNALING_TIMEOUT_MS = 8e3;
+var CREDENTIAL_TIMEOUT_MS = 7e3;
 function createCloudflareSFUHTTPTransport(options) {
   const fetch = options.fetch ?? globalThis.fetch;
   const credential = requireCredential(options);
   const base = options.apiBaseURL.replace(/\/$/, "");
   const mediaPath = `${base}/v1/tenants/${encodeURIComponent(options.tenantId)}/spaces/${encodeURIComponent(options.spaceId)}/episodes/${encodeURIComponent(options.episodeId)}/participants/${encodeURIComponent(options.participantId)}/media/sfu`;
+  const timeoutMs = options.requestTimeoutMs ?? SIGNALING_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new CloudflareSFUError("The signaling deadline is invalid", "signaling_failed");
   const request = async (path, init) => {
-    const token = await credential();
+    const token = await withDeadline(CREDENTIAL_TIMEOUT_MS, (signal) => credential(signal));
     if (!token.trim()) throw new CloudflareSFUError("The media credential provider returned an empty token", "signaling_failed");
-    const response = await fetch(`${mediaPath}/${path}`, {
-      ...init,
-      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
-    });
-    if (!response.ok) {
-      throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
-        status: response.status,
-        retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600
+    return withDeadline(timeoutMs, async (signal) => {
+      const response = await fetch(`${mediaPath}/${path}`, {
+        ...init,
+        signal,
+        headers: { ...options.telemetry ? journeyHeaders(options.telemetry) : {}, Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
       });
-    }
-    return await response.json();
+      if (!response.ok) {
+        throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
+          status: response.status,
+          retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600
+        });
+      }
+      return await response.json();
+    });
   };
   return {
     addTracks: async (input) => {
-      const response = await request("tracks", {
+      const path = input.allowPartialRemoteTracks ? "tracks?allow_partial_remote_tracks=true" : "tracks";
+      const response = await request(path, {
         method: "POST",
         body: JSON.stringify({ connection_id: input.connectionId, session_description: input.sessionDescription, tracks: input.tracks })
       });
@@ -975,6 +1528,25 @@ function createCloudflareSFUHTTPTransport(options) {
     }
   };
 }
+async function withDeadline(timeoutMs, operation) {
+  const controller = new AbortController();
+  const timeout = new CloudflareSFUError("Cloudflare SFU signaling timed out. Try again.", "signaling_timeout");
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = globalThis.setTimeout(() => {
+      controller.abort();
+      reject(timeout);
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([Promise.resolve().then(() => operation(controller.signal)), deadline]);
+  } catch (error) {
+    if (controller.signal.aborted) throw timeout;
+    throw error;
+  } finally {
+    if (timer !== void 0) globalThis.clearTimeout(timer);
+  }
+}
 function requireCredential(options) {
   if (options.credential) return options.credential;
   if (options.bearerToken !== void 0) return () => options.bearerToken ?? "";
@@ -1391,6 +1963,30 @@ function toParticipant(participant) {
   };
 }
 
+// src/media/capture-error.ts
+function describeMediaCaptureError(cause) {
+  const name = typeof cause === "object" && cause !== null && "name" in cause ? cause.name : void 0;
+  switch (name) {
+    case "NotAllowedError":
+    case "PermissionDeniedError":
+      return { code: "permission_denied", recoverable: true, message: "Camera or microphone permission was denied. Allow access in your device settings and try again." };
+    case "NotFoundError":
+    case "DevicesNotFoundError":
+      return { code: "device_not_found", recoverable: true, message: "No matching camera or microphone was found. Connect an input device or enter with that device off." };
+    case "NotReadableError":
+    case "TrackStartError":
+      return { code: "device_busy", recoverable: true, message: "The camera or microphone could not start. Close other apps using it and try again." };
+    case "OverconstrainedError":
+    case "ConstraintNotSatisfiedError":
+      return { code: "device_constraint_invalid", recoverable: true, message: "The selected camera or microphone is unavailable. Select another input device and try again." };
+    case "SecurityError":
+    case "NotSupportedError":
+      return { code: "unsupported_environment", recoverable: false, message: "Media capture is unavailable in this environment. Use a supported browser over HTTPS or the native app." };
+    default:
+      return { code: "media_capture_failed", recoverable: true, message: "Media capture failed. Try again or enter with devices off." };
+  }
+}
+
 export {
   CloudflareSFUError,
   parseCloudflareSFUPublicationID,
@@ -1403,5 +1999,6 @@ export {
   CloudflareSFUClient,
   createCloudflareSFUHTTPTransport,
   CloudflareRTKError,
-  CloudflareRTKClient
+  CloudflareRTKClient,
+  describeMediaCaptureError
 };