@q9labsai/chalk-client 4.1.15 → 4.1.17

package/dist/{chunk-PQNSA7ZN.js → chunk-2DZUHV6I.js}

@@ -1,3 +1,44 @@
+import {
+  recordReconnect,
+  traceReconnect
+} from "./chunk-RCDXIDCN.js";
+import {
+  journeyHeaders
+} from "./chunk-HW5TTZL2.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,15 +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;
@@ -149,17 +212,26 @@ 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;
+  #pollFailures = 0;
+  #pollFailedPull = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
   #snapshot;
@@ -171,11 +243,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);
@@ -194,6 +267,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);
@@ -202,7 +288,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,
@@ -210,6 +296,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?.());
@@ -225,6 +312,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();
@@ -246,30 +334,124 @@ var CloudflareSFUClient = class {
     if (!this.#started || this.#stopped || this.#polling) return;
     this.#polling = true;
     const generation = this.#generation;
+    this.#pollFailedPull = false;
     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);
+      this.#requireGeneration(generation);
+      if (!this.#remotePullIncomplete) this.#pollFailures = 0;
     } catch (error) {
       if (generation === this.#generation && !this.#stopped) this.#reportError(error);
       throw error;
     } finally {
-      if (generation === this.#generation) this.#polling = false;
+      this.#finishPublicationPoll(generation);
     }
   }
+  #finishPublicationPoll(generation) {
+    if (generation !== this.#generation) return;
+    this.#polling = false;
+    if (!this.#pollAfterCurrent) return;
+    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);
@@ -285,26 +467,29 @@ 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);
-    this.#observeConnection(this.#connection, generation, connectionEpoch);
+    this.#rebuildPeerConnection(options.bootstrap, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
       state.transceiver = null;
       state.enabled = false;
     }
     const enabled = [...this.#localTracks.values()].filter((state) => state.desiredEnabled && state.track.readyState !== "ended");
-    this.#setPhase("recovering", null);
     await this.#activatePreparedTracks(enabled, generation);
   }
   async #activatePreparedTracks(states, generation) {
@@ -325,9 +510,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();
@@ -346,14 +534,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;
@@ -365,26 +572,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);
@@ -397,6 +599,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);
@@ -404,7 +625,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);
@@ -413,21 +634,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",
@@ -436,17 +692,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;
@@ -482,9 +741,10 @@ var CloudflareSFUClient = class {
     const cursor = this.#validatedRemotePublicationCursor(authoritative);
     if (cursor === null) return;
     const ordering = comparePublicationCursor(this.#cursor, cursor);
-    if (ordering !== "newer") return;
+    if (ordering === "stale" || ordering === "same" && !this.#remotePullIncomplete) return;
     const desired = this.#desiredRemotePublications(authoritative, cursor);
-    const toPull = [...desired].filter(([key, publication]) => this.#remoteTracks.get(key)?.publicationId !== publication.publicationId).map(([, publication]) => publication);
+    const toPull = this.#pendingRemotePulls(desired);
+    this.#pollFailedPull = true;
     const pulled = await this.#pullWithRecovery(toPull, cursor, generation);
     if (pulled === null) return;
     this.#requireGeneration(generation);
@@ -493,10 +753,24 @@ 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 {
@@ -520,7 +794,7 @@ var CloudflareSFUClient = class {
     } catch (error) {
       if (generation !== this.#generation || this.#stopped) throw error;
       if (!this.#canReplaceConnectionAfterRemotePull(error, generation)) {
-        this.#observeRemotePublicationCursor(cursor);
+        this.#observeRemotePublicationCursor(cursor, retryableRemotePull(error));
         throw error;
       }
       return this.#retryRemotePullOnReplacement(publications, cursor, generation);
@@ -539,7 +813,7 @@ var CloudflareSFUClient = class {
       return await this.#pull(publications, generation);
     } catch (error) {
       if (generation !== this.#generation || this.#stopped) throw error;
-      this.#observeRemotePublicationCursor(cursor);
+      this.#observeRemotePublicationCursor(cursor, retryableRemotePull(error));
       throw error;
     }
   }
@@ -550,7 +824,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) => {
@@ -559,17 +841,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 });
         });
@@ -581,38 +866,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);
@@ -625,6 +1023,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) {
@@ -641,11 +1040,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);
@@ -656,7 +1111,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) {
@@ -665,25 +1121,27 @@ 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.#rebuildPeerConnection(bootstrap, generation, connectionEpoch);
+    this.#retiredLocalConnection = null;
     this.#negotiatedGeneration = null;
-    this.#observeConnection(this.#connection, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
       state.transceiver = null;
       state.enabled = false;
       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) {
+  #observeRemotePublicationCursor(cursor, pullIncomplete = false) {
     this.#cursor = cursor;
+    this.#remotePullIncomplete = pullIncomplete;
     this.#publishSnapshot();
   }
   #quarantineInvalidRemotePublicationCursor(authoritative) {
@@ -697,7 +1155,19 @@ var CloudflareSFUClient = class {
     const create = this.#peerConnectionFactory ?? ((configuration) => new RTCPeerConnection(configuration));
     return create({ iceServers: [{ urls: bootstrap.stunServer }], bundlePolicy: "max-bundle" });
   }
+  #rebuildPeerConnection(bootstrap, generation, connectionEpoch) {
+    try {
+      this.#connection = this.#createPeerConnection(bootstrap);
+      this.#observeConnection(this.#connection, generation, connectionEpoch);
+    } catch (error) {
+      this.#setFailure(error, "media_failed");
+      throw error;
+    }
+  }
   #disposeConnection(stopSenders) {
+    if (!stopSenders) this.#setPhase("recovering", null);
+    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));
@@ -737,15 +1207,31 @@ 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;
+      }
+      let nextDelay = this.#pollIntervalMs;
       try {
         await this.refreshRemotePublications();
+        if (this.#remotePullIncomplete) nextDelay = this.#incompletePullDelay();
       } catch {
+        if (this.#pollFailedPull && this.#remotePullIncomplete) nextDelay = this.#incompletePullDelay();
+        else {
+          this.#pollFailures = Math.min(this.#pollFailures + 1, 6);
+          nextDelay = Math.min(this.#pollIntervalMs, (500 + Math.random() * 500) * 2 ** (this.#pollFailures - 1));
+        }
       } finally {
-        this.#schedulePoll();
+        this.#schedulePoll(nextDelay);
       }
     }, delayMs);
   }
+  #incompletePullDelay() {
+    this.#pollFailures = Math.min(this.#pollFailures + 1, 6);
+    return Math.min(this.#pollIntervalMs, 750 * 2 ** (this.#pollFailures - 1));
+  }
   #clearPoll() {
+    this.#pollFailures = 0;
     if (this.#pollTimer !== void 0) globalThis.clearTimeout(this.#pollTimer);
     this.#pollTimer = void 0;
   }
@@ -754,7 +1240,7 @@ var CloudflareSFUClient = class {
       participantId: this.#participantId,
       source: state.source,
       enabled: state.enabled,
-      publicationId: state.enabled ? state.providerPublicationId : null
+      publicationId: state.providerPublicationId
     }));
   }
   #projectRemotePublications() {
@@ -772,7 +1258,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,
@@ -908,10 +1394,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]];
     })
   );
 }
@@ -973,31 +1459,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 })
       });
@@ -1035,6 +1553,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 ?? "";
@@ -1059,12 +1596,14 @@ var CloudflareRTKClient = class {
   #clientFactory;
   #snapshotListeners = /* @__PURE__ */ new Set();
   #sourceOperations = /* @__PURE__ */ new Map();
+  #generationInvalidators = /* @__PURE__ */ new Set();
   #connection = null;
   #localTracks = /* @__PURE__ */ new Map();
   #connectionUnsubscribers = [];
   #participantUnsubscribers = /* @__PURE__ */ new Map();
   #snapshot;
   #stopped = false;
+  #generation = 0;
   #screenDisableRequested = false;
   #initialAuthToken;
   constructor(options) {
@@ -1101,16 +1640,22 @@ var CloudflareRTKClient = class {
   async clearPreparedLocalTrack(source) {
     const state = this.#localTracks.get(source);
     if (!state) return;
-    if (state.enabled) {
-      await this.#setSourceEnabled(state, false);
-    }
+    const connection = this.#connection;
     if (state.endedListener) state.track.removeEventListener("ended", state.endedListener);
     this.#localTracks.delete(source);
+    const actions = connection ? this.#sourceActions(state, connection) : null;
+    const cleanup = actions?.enabled && state.enabled ? this.#queueSourceOperation(source, () => connection === this.#connection ? actions.disable() : Promise.resolve()) : Promise.resolve();
     this.#publishSnapshot();
+    try {
+      await cleanup;
+    } catch (error) {
+      if (!isStaleGeneration(error)) throw error;
+    }
   }
   async start(localMedia) {
     if (this.#snapshot.connection.phase === "live") return;
     this.#requireStartable();
+    const generation = this.#advanceGeneration();
     this.#setPhase("connecting", null);
     try {
       const tracks = localMedia.getTracks().filter((track) => track.kind === "audio" || track.kind === "video");
@@ -1118,38 +1663,60 @@ var CloudflareRTKClient = class {
         const source = track.kind === "audio" ? "microphone" : "camera";
         if (!this.#localTracks.has(source)) this.#localTracks.set(source, { source, track, enabled: false, endedListener: null });
       }
-      await this.#openConnection(this.#initialAuthToken);
-      for (const state of this.#localTracks.values()) {
-        if (state.source === "microphone" || state.source === "camera") await this.#setSourceEnabled(state, true);
-      }
-      this.#setPhase("live", null);
+      if (!await this.#openConnection(this.#initialAuthToken, generation)) return;
+      await this.#restoreLocalTracks(generation, true);
     } catch (error) {
-      this.#setFailure(error);
-      this.#reportError(error);
+      this.#failCurrentGeneration(generation, error);
       throw error;
     }
   }
   async setLocalPublicationTarget(target) {
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result") return resolved.result;
-    const state = resolved.value;
-    const previous = this.#sourceOperations.get(target.source) ?? Promise.resolve();
-    const operation = previous.catch(() => void 0).then(async () => {
-      if (state.enabled === target.enabled) return "satisfied";
-      try {
-        await this.#setSourceEnabled(state, target.enabled);
-        return "confirmed";
-      } catch (error) {
-        this.#reportError(error);
-        return "retryable_failure";
-      }
+    const generation = this.#generation;
+    try {
+      return await this.#queueSourceOperation(target.source, () => this.#applyLocalTarget(target, generation));
+    } catch (error) {
+      return { outcome: "retryable_failure", errorCode: error instanceof CloudflareRTKError ? error.code : "media_failed" };
+    }
+  }
+  async #queueSourceOperation(source, apply) {
+    const previous = this.#sourceOperations.get(source) ?? Promise.resolve();
+    const generation = this.#generation;
+    let invalidate = () => {
+    };
+    const retired = new Promise((_resolve, reject) => {
+      invalidate = () => reject(new CloudflareRTKError("The media operation belongs to a retired connection", "stale_generation"));
+      this.#generationInvalidators.add(invalidate);
     });
-    this.#sourceOperations.set(target.source, operation);
+    const operation = Promise.race([
+      previous.catch(() => void 0).then(() => {
+        if (!this.#isCurrentGeneration(generation)) throw new CloudflareRTKError("The queued media operation belongs to a retired connection", "stale_generation");
+        return apply();
+      }),
+      retired
+    ]);
+    this.#sourceOperations.set(source, operation);
     try {
-      const outcome = await operation;
-      return { outcome, errorCode: outcome === "retryable_failure" ? "media_failed" : null };
+      return await operation;
     } finally {
-      if (this.#sourceOperations.get(target.source) === operation) this.#sourceOperations.delete(target.source);
+      this.#generationInvalidators.delete(invalidate);
+      if (this.#sourceOperations.get(source) === operation) this.#sourceOperations.delete(source);
+    }
+  }
+  async #applyLocalTarget(target, generation) {
+    if (!this.#isCurrentGeneration(generation)) return { outcome: "retryable_failure", errorCode: "stale_generation" };
+    const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
+    if (resolved.kind === "result") return resolved.result;
+    const state = resolved.value;
+    try {
+      if (!this.#connection) throw new CloudflareRTKError("The RealtimeKit connection is recovering", "stale_generation");
+      if (state.enabled === target.enabled) return { outcome: "satisfied", errorCode: null };
+      await this.#setSourceEnabled(state, target.enabled);
+      return { outcome: "confirmed", errorCode: null };
+    } catch (error) {
+      this.#reportError(error);
+      return { outcome: "retryable_failure", errorCode: error instanceof CloudflareRTKError ? error.code : "media_failed" };
     }
   }
   observeLocalPublications(listener) {
@@ -1161,31 +1728,74 @@ var CloudflareRTKClient = class {
   async restart(input) {
     if (!isRTKAccess(input)) throw new CloudflareRTKError("The RealtimeKit adapter requires a Cloudflare RealtimeKit access grant", "invalid_client");
     if (this.#stopped) throw new CloudflareRTKError("The RealtimeKit media client has stopped", "media_stopped");
+    const generation = this.#advanceGeneration();
     this.#setPhase("recovering", null);
     try {
       await this.#closeConnection();
-      await this.#openConnection(input.clientPayload.token);
-      for (const state of this.#localTracks.values()) if (state.enabled) await this.#setSourceEnabled(state, true);
-      this.#setPhase("live", null);
+      if (!this.#isCurrentGeneration(generation)) return;
+      if (!await this.#openConnection(input.clientPayload.token, generation)) return;
+      await this.#restoreLocalTracks(generation, false);
     } catch (error) {
-      this.#setFailure(error);
-      this.#reportError(error);
+      this.#failCurrentGeneration(generation, error);
       throw error;
     }
   }
   stop() {
     if (this.#stopped) return;
     this.#stopped = true;
+    this.#advanceGeneration();
     const leave = this.#closeConnection();
     void leave.catch((error) => this.#reportError(error));
     for (const state of this.#localTracks.values()) if (state.endedListener) state.track.removeEventListener("ended", state.endedListener);
     this.#localTracks.clear();
     this.#setPhase("stopped", null);
   }
-  async #openConnection(authToken) {
-    this.#connection = await this.#clientFactory({ authToken, onError: (error) => this.#reportError(error) });
-    this.#bindConnection(this.#connection);
-    await this.#connection.join();
+  #isCurrentGeneration(generation) {
+    return !this.#stopped && generation === this.#generation;
+  }
+  #advanceGeneration() {
+    const generation = ++this.#generation;
+    this.#sourceOperations.clear();
+    for (const invalidate of this.#generationInvalidators) invalidate();
+    this.#generationInvalidators.clear();
+    return generation;
+  }
+  async #restoreLocalTracks(generation, initial) {
+    for (const state of this.#localTracks.values()) {
+      if (!this.#isCurrentGeneration(generation)) return;
+      const enable = initial ? state.source !== "screen" : state.enabled;
+      if (enable) {
+        await this.#queueSourceOperation(state.source, async () => {
+          if (!this.#isCurrentGeneration(generation) || this.#localTracks.get(state.source) !== state || !initial && !state.enabled) return;
+          await this.#setSourceEnabled(state, true);
+        }).catch((error) => {
+          if (!this.#isCurrentGeneration(generation)) return;
+          if (isStaleGeneration(error) && this.#localTracks.get(state.source) !== state) return;
+          throw error;
+        });
+      }
+    }
+    if (this.#isCurrentGeneration(generation)) this.#setPhase("live", null);
+  }
+  #failCurrentGeneration(generation, error) {
+    if (!this.#isCurrentGeneration(generation)) return;
+    this.#setFailure(error);
+    this.#reportError(error);
+  }
+  async #openConnection(authToken, generation) {
+    const connection = await this.#clientFactory({ authToken, onError: (error) => this.#reportError(error) });
+    if (!this.#isCurrentGeneration(generation)) {
+      await connection.leave();
+      return false;
+    }
+    this.#connection = connection;
+    this.#bindConnection(connection);
+    await connection.join();
+    if (!this.#isCurrentGeneration(generation)) {
+      await connection.leave();
+      return false;
+    }
+    return true;
   }
   async #closeConnection() {
     const connection = this.#connection;
@@ -1237,22 +1847,44 @@ var CloudflareRTKClient = class {
   }
   async #setSourceEnabled(state, enabled) {
     const connection = this.#connection;
+    const generation = this.#generation;
     if (!connection) throw new CloudflareRTKError("The RealtimeKit connection is not active", "media_stopped");
-    if (state.source === "microphone") {
-      if (enabled) await connection.self.enableAudio(state.track);
-      else await connection.self.disableAudio();
-    } else if (state.source === "camera") {
-      if (enabled) await connection.self.enableVideo(state.track);
-      else await connection.self.disableVideo();
-    } else {
-      this.#screenDisableRequested = !enabled;
-      if (enabled) await connection.self.enableScreenShare();
-      else await connection.self.disableScreenShare();
+    const actions = this.#sourceActions(state, connection);
+    if (state.source === "screen") this.#screenDisableRequested = !enabled;
+    await actions[enabled ? "enable" : "disable"]();
+    try {
+      this.#requireCurrentSource(state, connection, generation);
+    } catch (error) {
+      if (enabled)
+        await actions.disable().catch((cause) => {
+          this.#failCurrentGeneration(generation, cause);
+          throw cause;
+        });
+      throw error;
     }
     state.enabled = enabled;
     state.track.enabled = enabled;
     this.#publishSnapshot();
   }
+  #sourceActions(state, connection) {
+    return {
+      microphone: { enabled: connection.self.audioEnabled, enable: () => connection.self.enableAudio(state.track), disable: () => connection.self.disableAudio() },
+      camera: { enabled: connection.self.videoEnabled, enable: () => connection.self.enableVideo(state.track), disable: () => connection.self.disableVideo() },
+      screen: {
+        enabled: connection.self.screenShareEnabled,
+        enable: () => connection.self.enableScreenShare(),
+        disable: () => {
+          if (connection === this.#connection) this.#screenDisableRequested = true;
+          return connection.self.disableScreenShare();
+        }
+      }
+    }[state.source];
+  }
+  #requireCurrentSource(state, connection, generation) {
+    if (!this.#isCurrentGeneration(generation) || connection !== this.#connection || this.#localTracks.get(state.source) !== state) {
+      throw new CloudflareRTKError("The local media target belongs to a replaced connection or source", "stale_generation");
+    }
+  }
   #syncLocalState(source) {
     const state = this.#localTracks.get(source);
     const connection = this.#connection;
@@ -1450,8 +2082,36 @@ function toParticipant(participant) {
     }
   };
 }
+function isStaleGeneration(error) {
+  return error instanceof CloudflareRTKError && error.code === "stale_generation";
+}
+
+// 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 {
+  describeMediaCaptureError,
   CloudflareSFUError,
   parseCloudflareSFUPublicationID,
   requireDescription,