@q9labsai/chalk-client 5.2.5 → 5.3.0

package/dist/{chunk-FD25AMLG.js → chunk-3TGVTP6Z.js}

@@ -1,3 +1,145 @@
+// src/media/receive-stall.ts
+var RECEIVE_STALL_WINDOW_MS = 7e3;
+var RECEIVE_STARTUP_GRACE_MS = 2e4;
+var MAX_SAMPLE_GAP_MS = 3e3;
+var ReceiveStallDetector = class {
+  #progress = /* @__PURE__ */ new Map();
+  #sampledAt;
+  forget(publicationId) {
+    this.#progress.delete(publicationId);
+  }
+  clear() {
+    this.#progress.clear();
+    this.#sampledAt = void 0;
+  }
+  sample(now, tracks) {
+    if (this.#sampledAt !== void 0 && (now - this.#sampledAt > MAX_SAMPLE_GAP_MS || now < this.#sampledAt)) this.clear();
+    this.#sampledAt = now;
+    const observed = new Set(tracks.map((track) => track.publicationId));
+    for (const id of this.#progress.keys()) if (!observed.has(id)) this.#progress.delete(id);
+    const observations = tracks.map((track) => ({ id: track.publicationId, outcome: this.#observeTrack(now, track) }));
+    return {
+      stalled: observations.filter((track) => track.outcome === "stalled").map((track) => track.id),
+      resumed: observations.filter((track) => track.outcome === "resumed").map((track) => track.id),
+      advanced: observations.filter((track) => track.outcome === "advanced" || track.outcome === "resumed").map((track) => track.id)
+    };
+  }
+  #observeTrack(now, { publicationId, trackId, packets }) {
+    const previous = this.#progress.get(publicationId);
+    const sameTrack = previous?.trackId === trackId;
+    if (sameTrack && previous.packets === packets) {
+      const window = previous.flowing ? RECEIVE_STALL_WINDOW_MS : RECEIVE_STARTUP_GRACE_MS;
+      return now - previous.advancedAt >= window ? "stalled" : null;
+    }
+    return this.#advanceTrack(now, { publicationId, trackId, packets }, previous);
+  }
+  #advanceTrack(now, { publicationId, trackId, packets }, previous) {
+    const advanced = previous?.trackId === trackId && packets > previous.packets;
+    const flowingSince = advanced && now - previous.advancedAt < RECEIVE_STALL_WINDOW_MS ? previous.flowingSince : now;
+    this.#progress.set(publicationId, { trackId, packets, advancedAt: now, flowing: advanced, flowingSince });
+    if (!advanced) return null;
+    return now - flowingSince >= RECEIVE_STALL_WINDOW_MS ? "resumed" : "advanced";
+  }
+};
+var MAX_RECEIVE_REBUILDS = 2;
+var MAX_RECEIVE_OBSERVATIONS = 32;
+var ReceiveStallRecovery = class {
+  #detector = new ReceiveStallDetector();
+  #attempts = /* @__PURE__ */ new Map();
+  #identities = /* @__PURE__ */ new Map();
+  #expected = /* @__PURE__ */ new Set();
+  #screens = /* @__PURE__ */ new Set();
+  #stalled = /* @__PURE__ */ new Set();
+  #active = [];
+  #observations = Object.freeze([]);
+  get observations() {
+    return this.#observations;
+  }
+  expect(publications, participantId) {
+    const enabled = publications.filter((publication) => publication.participantId !== participantId && publication.enabled);
+    this.#expected = new Set(enabled.flatMap((publication) => publication.publicationId ? [publication.publicationId] : []));
+    this.#screens = new Set(enabled.filter((publication) => publication.source === "screen").map((publication) => publication.participantId));
+    this.#pruneWithdrawn(publications);
+    for (const publication of this.#identities.values()) {
+      if (this.#isExpected(publication)) continue;
+      this.#detector.forget(publication.publicationId);
+      this.#stalled.delete(publication.publicationId);
+    }
+    this.#active = [...this.#identities.values()].filter((publication) => this.#isExpected(publication)).map((publication) => publication.publicationId);
+  }
+  suspend() {
+    this.#expected.clear();
+    this.#screens.clear();
+    this.clear();
+  }
+  #pruneWithdrawn(publications) {
+    const advertised = new Set(publications.map((publication) => publication.publicationId));
+    const screens = new Set(publications.filter((publication) => publication.source === "screen").map((publication) => publication.participantId));
+    for (const [key, publication] of this.#identities) {
+      if (advertised.has(publication.publicationId) || publication.source === "screen_audio" && screens.has(publication.participantId)) continue;
+      this.#forget(publication.publicationId);
+      this.#identities.delete(key);
+    }
+  }
+  isStalled(publicationId) {
+    return this.#stalled.has(publicationId);
+  }
+  canRebuild() {
+    return this.#active.length > 0 && this.#active.every((id) => this.#stalled.has(id) && (this.#attempts.get(id) ?? 0) < MAX_RECEIVE_REBUILDS);
+  }
+  reserveRebuild() {
+    if (!this.canRebuild()) return false;
+    for (const id of this.#active) this.#attempts.set(id, (this.#attempts.get(id) ?? 0) + 1);
+    return true;
+  }
+  clear() {
+    this.#detector.clear();
+    this.#stalled.clear();
+    this.#active = [];
+  }
+  sample(now, connection, report, tracks) {
+    const active = [...tracks].filter((publication) => this.#isExpected(publication));
+    for (const publication of active) this.#rememberIdentity(publication);
+    this.#active = active.map((publication) => publication.publicationId);
+    const samples = active.flatMap((publication) => receivePacketSample(connection, report, publication) ?? []);
+    const { stalled, advanced, resumed } = this.#detector.sample(now, samples);
+    for (const id of resumed) this.#attempts.delete(id);
+    const newlyStalled = stalled.filter((id) => !this.#stalled.has(id));
+    this.#stalled = new Set(stalled);
+    if (newlyStalled.length) this.#record(now);
+    return { stalled, advanced, newlyStalled };
+  }
+  #isExpected(publication) {
+    return publication.source === "screen_audio" ? this.#screens.has(publication.participantId) : this.#expected.has(publication.publicationId);
+  }
+  #rememberIdentity(publication) {
+    const key = `${publication.participantId}\0${publication.source}`;
+    const previous = this.#identities.get(key);
+    if (previous && previous.publicationId !== publication.publicationId) this.#forget(previous.publicationId);
+    this.#identities.set(key, publication);
+  }
+  #forget(id) {
+    this.#detector.forget(id);
+    this.#stalled.delete(id);
+    this.#attempts.delete(id);
+  }
+  #record(now) {
+    const observation = Object.freeze({ event: "receive_stalled", scope: this.#active.every((id) => this.#stalled.has(id)) ? "all" : "partial", observedAtMs: now, expectedTracks: this.#active.length, stalledTracks: this.#stalled.size });
+    this.#observations = Object.freeze([...this.#observations.slice(-(MAX_RECEIVE_OBSERVATIONS - 1)), observation]);
+  }
+};
+function receivePacketSample(connection, report, publication) {
+  const rows = [...report.values()].filter((row) => row.type === "inbound-rtp" && row.trackIdentifier === publication.track.id);
+  if (rows.some((row) => !Number.isSafeInteger(row.packetsReceived) || row.packetsReceived < 0)) return;
+  if (publication.track.kind === "audio" && !audioPacketCadenceKnown(connection, report, publication.track, rows)) return;
+  return { publicationId: publication.publicationId, trackId: publication.track.id, packets: rows.reduce((sum, row) => sum + row.packetsReceived, 0) };
+}
+function audioPacketCadenceKnown(connection, report, track, rows) {
+  const negotiated = rows.length ? rows.map((row) => row.codecId ? report.get(row.codecId) : void 0) : connection.getReceivers().find((receiver) => receiver.track.id === track.id)?.getParameters().codecs ?? [];
+  const opus = negotiated.filter((codec) => codec?.mimeType?.toLowerCase() === "audio/opus");
+  return opus.length > 0 && opus.every((codec) => typeof codec.sdpFmtpLine === "string");
+}
+
 // src/media/camera-uplink.ts
 var CameraUplinkPolicy = class {
   #healthySamples = 0;
@@ -234,10 +376,12 @@ function classifyMediaFailure(cause, fallbackStep) {
 // src/media/client.ts
 var EMPTY_LOCAL = Object.freeze([]);
 var EMPTY_REMOTE = Object.freeze([]);
+var EMPTY_RECEIVE_STALLS = Object.freeze([]);
 var INVALID_PUBLICATION_SIGNATURE = "\0invalid";
 var CONNECTION_TIMEOUT_MS = 8e3;
 var NEGOTIATION_TIMEOUT_MS = 35e3;
 var PEER_OPERATION_TIMEOUT_MS = 8e3;
+var CAPTURE_REUSE_WINDOW_MS = 2e4;
 var CloudflareSFUClient = class {
   #localListeners = /* @__PURE__ */ new Set();
   #onError;
@@ -250,7 +394,7 @@ var CloudflareSFUClient = class {
   #remoteListeners = /* @__PURE__ */ new Set();
   #snapshotListeners = /* @__PURE__ */ new Set();
   #failureOwners = /* @__PURE__ */ new WeakMap();
-  #locallyPausedSources = /* @__PURE__ */ new Set();
+  #locallyPausedSources = /* @__PURE__ */ new Map();
   #localTracks = /* @__PURE__ */ new Map();
   #ownedPublications = /* @__PURE__ */ new Set();
   #remoteTracks = /* @__PURE__ */ new Map();
@@ -259,9 +403,12 @@ var CloudflareSFUClient = class {
   #disposeConnectionObservation;
   #connectionEpoch = 0;
   #retiredLocalConnection = null;
+  #retiredLocalCause = "forced_pause";
+  #replacementCause;
   #cursor = null;
   #remotePullIncomplete = false;
-  #remotePullRetryAfter = /* @__PURE__ */ new Map();
+  #remotePullRetries = /* @__PURE__ */ new Map();
+  #receiveProgress = new ReceiveStallRecovery();
   #remoteParticipantIds = null;
   #remoteParticipantRevision = 0;
   #subscribedPublicationIds = /* @__PURE__ */ new Set();
@@ -278,6 +425,7 @@ var CloudflareSFUClient = class {
   #retirement = Promise.resolve();
   #snapshot;
   #started = false;
+  #receivingInitial = false;
   #stopped = false;
   #transport;
   constructor(options) {
@@ -297,6 +445,7 @@ var CloudflareSFUClient = class {
       cursor: null,
       localTracks: EMPTY_LOCAL,
       remoteTracks: EMPTY_REMOTE,
+      receiveStalls: this.#receiveProgress.observations,
       failure: null
     });
     this.#observeConnection(this.#connection, this.#generation, this.#connectionEpoch);
@@ -308,7 +457,7 @@ var CloudflareSFUClient = class {
     return subscribeSnapshot(this.#snapshotListeners, listener);
   }
   remotePublicationResumed(publicationId) {
-    this.#remotePullRetryAfter.delete(publicationId);
+    this.#remotePullRetries.delete(publicationId);
     this.remotePublicationsChanged();
   }
   remoteParticipantsChanged(participantIds) {
@@ -317,7 +466,9 @@ var CloudflareSFUClient = class {
     this.#remotePullIncomplete = true;
     this.remotePublicationsChanged();
   }
-  remotePublicationsChanged() {
+  remotePublicationsChanged(publications, projectionState = "available") {
+    if (projectionState === "unavailable") this.#receiveProgress.suspend();
+    else if (publications) this.#receiveProgress.expect(publications, this.#participantId);
     if (this.#polling) {
       this.#pollAfterCurrent = true;
       return;
@@ -363,9 +514,9 @@ var CloudflareSFUClient = class {
   }
   async #clearPreparedTrack(state, stopTrack = true) {
     const source = state.source;
-    if (source === "screen" || source === "screen_audio" || state.track.readyState === "ended") {
+    if (source === "screen" || source === "screen_audio") {
       try {
-        this.#pauseLocalSource(source);
+        this.#pauseLocalSource(source, "capture_cleanup");
         await this.#retireOwnedPublications();
       } finally {
         this.#removeOwnedLocalTrack(state, stopTrack);
@@ -382,20 +533,30 @@ var CloudflareSFUClient = class {
     this.#publishSnapshot();
     this.#emitLocal();
   }
-  async start(localMedia) {
+  async start(localMedia, beforePublish) {
     if (this.#started) return;
     this.#requireActive();
-    const tracks = localMedia.getTracks().filter((track) => track.kind === "audio" || track.kind === "video");
-    for (const track of tracks) this.prepareLocalTrack(track.kind === "audio" ? "microphone" : "camera", track);
     const generation = this.#generation;
     this.#setPhase("connecting", null);
+    if (beforePublish) {
+      this.#receivingInitial = true;
+      this.#schedulePoll(0);
+      try {
+        localMedia = await beforePublish();
+      } finally {
+        this.#receivingInitial = false;
+      }
+      if (generation !== this.#generation || this.#stopped) return;
+    }
+    const tracks = localMedia.getTracks().filter((track) => track.kind === "audio" || track.kind === "video");
+    for (const track of tracks) this.prepareLocalTrack(track.kind === "audio" ? "microphone" : "camera", track);
     await this.#activatePreparedTracks(
       [...this.#localTracks.values()].filter((state) => state.source === "microphone" || state.source === "camera"),
       generation
     );
   }
   async refreshRemotePublications() {
-    if (!this.#started || this.#stopped || this.#polling) return;
+    if (!this.#started && !this.#receivingInitial || this.#stopped || this.#polling) return;
     this.#polling = true;
     const generation = this.#generation;
     this.#pollFailedPull = false;
@@ -431,6 +592,10 @@ var CloudflareSFUClient = class {
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result" && resolved.result.outcome !== "satisfied") return resolved.result;
     const outcome = resolved.kind === "state" && resolved.value.enabled ? "confirmed" : "satisfied";
+    if (target.source !== "screen" && this.#locallyPausedSources.get(target.source) === "capture_cleanup") {
+      await this.pauseLocalCapture(target.source);
+      return { outcome, errorCode: null };
+    }
     this.#pauseLocalSource(target.source);
     try {
       await this.#retireOwnedPublications();
@@ -449,29 +614,56 @@ var CloudflareSFUClient = class {
       await this.#retireUnavailableLocalPublication(state);
       if (this.#locallyPausedSources.has(target.source)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
       if (state.enabled) return { outcome: "satisfied", errorCode: null };
-      await this.#enablePreparedTrack(state);
+      if (!await this.#enablePreparedTrack(state)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
       return { outcome: "confirmed", errorCode: null };
     } catch (error) {
       if (generation === this.#generation && !this.#stopped) this.#reportError(error);
       return mediaTargetFailure(error);
     }
   }
-  setLocalSourceIntent(source, enabled) {
+  async pauseLocalCapture(source) {
+    this.#locallyPausedSources.set(source, "capture_cleanup");
+    const state = this.#localTracks.get(source);
+    if (state) await this.#disablePreparedTrack(state);
+  }
+  setLocalSourceIntent(source, enabled, cause = "forced_pause") {
     const sources = localSourceGroup(source);
     for (const item of sources) {
       if (enabled) this.#locallyPausedSources.delete(item);
-      else this.#locallyPausedSources.add(item);
+      else this.#locallyPausedSources.set(item, cause);
     }
-    if (!enabled) this.#pauseLocalSource(source);
+    if (!enabled) this.#pauseLocalSource(source, cause);
     return enabled ? Promise.resolve() : this.#retireOwnedPublications();
   }
-  async closeForcedLocalPublication(source) {
+  async closeForcedLocalPublication(source, cause = "forced_pause") {
+    const connection = this.#connection;
+    const generationAtClose = this.#generation;
     const sources = localSourceGroup(source);
     const ownsPublication = [...this.#ownedPublications].some((item) => sources.includes(item.state.source));
-    await this.setLocalSourceIntent(source, false);
-    if (!ownsPublication || !this.#replaceMediaConnection) return;
+    const canRecover = ownsPublication && this.#replaceMediaConnection !== void 0;
+    let failedRetirement;
+    try {
+      await this.setLocalSourceIntent(source, false, cause);
+    } catch (error) {
+      if (!canRecover) throw error;
+      failedRetirement = this.#fenceFailedClose(error, connection, generationAtClose, cause);
+      if (!failedRetirement) return;
+    }
+    if (!canRecover) return;
+    await this.#restoreEnabledSourcesAfterClose(source);
+    if (this.#retirement !== failedRetirement) await this.#retirement;
+  }
+  #fenceFailedClose(error, connection, generation, cause) {
+    const failures = error instanceof AggregateError ? error.errors : [error];
+    if (!failures.every((failure) => this.#isRetryableConnectionFailure(failure))) throw error;
+    if (connection !== this.#connection || generation !== this.#generation) return;
+    this.#retiredLocalConnection = connection;
+    this.#retiredLocalCause = cause;
+    return this.#retirement;
+  }
+  #restoreEnabledSourcesAfterClose(source) {
     const generation = this.#generation;
-    await this.#serializeSDP(async () => {
+    return 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(
@@ -483,7 +675,6 @@ var CloudflareSFUClient = class {
       this.#requireGeneration(generation);
       this.#setPhase("live", null);
     });
-    await this.#retirement;
   }
   async #retireUnavailableLocalPublication(state) {
     const publicationId = state.providerPublicationId;
@@ -491,16 +682,15 @@ var CloudflareSFUClient = class {
     const authoritative = await this.#signal(() => this.#requireTransport().listPublications());
     if (authoritative.publications.some((publication) => publication.publicationId === publicationId)) return;
     if (state.providerPublicationId === publicationId) {
-      this.#pauseLocalSource(state.source);
+      this.#pauseLocalSource(state.source, "discovery_absent");
       await this.#retireOwnedPublications();
     }
   }
-  #pauseLocalSource(source) {
+  #pauseLocalSource(source, cause = "forced_pause") {
     const sources = localSourceGroup(source);
     for (const publication of this.#ownedPublications) {
       if (!sources.includes(publication.state.source)) continue;
-      this.#markPublicationRetiring(publication);
-      this.#retiredLocalConnection = this.#connection;
+      this.#markPublicationRetiring(publication, cause);
     }
     for (const state of this.#localTracks.values()) {
       if (!sources.includes(state.source)) continue;
@@ -510,7 +700,7 @@ var CloudflareSFUClient = class {
     this.#publishSnapshot();
     this.#emitLocal();
   }
-  #retireOwnedPublications() {
+  #retireOwnedPublications(reportFailure = this.#reportError.bind(this)) {
     const publications = [...this.#ownedPublications].filter((item) => item.lifecycle.kind === "retiring" && item.lifecycle.handle);
     const retirement = (async () => {
       const errors = [];
@@ -519,7 +709,7 @@ var CloudflareSFUClient = class {
           await this.#serializeSDP(() => this.#closeOwnedPublication(publication), true);
         } catch (error) {
           errors.push(error);
-          if (!this.#stopped) this.#reportError(error);
+          if (!this.#stopped) reportFailure(error);
         }
       }
       if (this.#stopped && this.#ownedPublications.size === 0) this.#transport = void 0;
@@ -529,15 +719,24 @@ var CloudflareSFUClient = class {
     });
     return this.#retirement = retirement;
   }
-  #markPublicationRetiring(publication) {
+  #markPublicationRetiring(publication, cause = "publish_failure") {
     const phase = publication.lifecycle;
-    if (phase.kind === "pending" || phase.kind === "confirmed") publication.lifecycle = { kind: "retiring", handle: phase.kind === "confirmed" ? phase.handle : null, detached: false };
+    if (phase.kind === "pending" || phase.kind === "confirmed") publication.lifecycle = { kind: "retiring", handle: phase.kind === "confirmed" ? phase.handle : null, detached: false, cause };
+  }
+  #markBundledTransportRetiring(publication) {
+    const bundleTag = /(?:^|\r?\n)a=group:BUNDLE[ \t]+(\S+)/.exec(publication.connection.localDescription?.sdp ?? "")?.[1];
+    if (!bundleTag || publication.transceiver.mid !== null && publication.transceiver.mid === bundleTag) {
+      if (this.#retiredLocalConnection === publication.connection) return;
+      this.#retiredLocalConnection = publication.connection;
+      if (publication.lifecycle.kind === "retiring") this.#retiredLocalCause = publication.lifecycle.cause;
+    }
   }
   async #closeOwnedPublication(publication) {
     const phase = publication.lifecycle;
     if (phase.kind !== "retiring" || !phase.handle) return;
     const handle = phase.handle;
     const { connection, connectionId, transceiver, state } = publication;
+    this.#markBundledTransportRetiring(publication);
     let closed = connection.connectionState === "closed";
     try {
       if (!phase.detached && !closed) {
@@ -574,13 +773,16 @@ var CloudflareSFUClient = class {
     this.#requireActive();
     const options = "connectionId" in input ? { bootstrap: input } : input;
     validateBootstrap(options.bootstrap);
-    if (options.bootstrap.connectionId !== this.#bootstrap.connectionId) this.#fenceLocalPublications();
+    if (options.bootstrap.connectionId !== this.#bootstrap.connectionId) {
+      this.#fenceLocalPublications();
+      this.#replacementCause = "access_refresh";
+    }
     const generation = ++this.#generation;
     const connectionEpoch = ++this.#connectionEpoch;
     this.#polling = false;
     this.#pollAfterCurrent = false;
     this.#clearPoll();
-    this.#remotePullRetryAfter.clear();
+    this.#remotePullRetries.clear();
     this.#disposeConnection(false);
     for (const publication of this.#ownedPublications) this.#markPublicationRetiring(publication);
     void this.#retireOwnedPublications();
@@ -618,11 +820,12 @@ var CloudflareSFUClient = class {
       return;
     }
     this.#stopped = true;
+    this.#receiveProgress.expect([], this.#participantId);
     this.#subscribedPublicationIds.clear();
     this.#generation++;
     this.#connectionEpoch++;
     this.#clearPoll();
-    this.#remotePullRetryAfter.clear();
+    this.#remotePullRetries.clear();
     this.#polling = false;
     this.#pollAfterCurrent = false;
     this.#disposeConnection(true);
@@ -645,35 +848,64 @@ var CloudflareSFUClient = class {
   }
   async #enablePreparedTrack(state) {
     const generation = this.#generation;
-    state.desiredEnabled = true;
-    state.track.enabled = true;
     try {
-      if (state.providerPublicationId && state.transceiver) {
-        await this.#boundPeerOperation(state.transceiver.sender.replaceTrack(state.track));
-        state.enabled = !this.#locallyPausedSources.has(state.source);
-        state.desiredEnabled = state.enabled;
-        state.track.enabled = state.enabled;
-        if (!state.enabled) {
-          this.#pauseLocalSource(state.source);
-          await this.#retireOwnedPublications();
-        }
-        this.#publishSnapshot();
-        this.#emitLocal();
-        return;
-      }
+      await this.#retireExpiredCapture(state);
+      if (this.#locallyPausedSources.has(state.source)) return false;
+      state.desiredEnabled = true;
+      state.track.enabled = true;
+      if (state.providerPublicationId && state.transceiver) return await this.#reattachLocalTrack(state, state.transceiver);
       await this.#publishPreparedTracks([state], generation);
       if (this.#remoteRecoveryGeneration !== generation) this.#replacementAttemptedGeneration = null;
+      return state.enabled;
     } catch (error) {
       if (generation === this.#generation) {
-        this.#pauseLocalSource(state.source);
+        this.#pauseLocalSource(state.source, "enable_failure");
         await this.#retireOwnedPublications().catch(() => {
         });
       }
       throw error;
     }
   }
+  async #retireExpiredCapture(state) {
+    const publication = [...this.#ownedPublications].find((item) => item.transceiver === state.transceiver && item.lifecycle.kind === "confirmed");
+    if (!publication || publication.detachedAt === null || Date.now() - publication.detachedAt < CAPTURE_REUSE_WINDOW_MS) return;
+    this.#pauseLocalSource(state.source, "capture_cleanup");
+    try {
+      await this.#retireOwnedPublications((error) => {
+        if (!this.#isExpiredRetiredConnection(error)) this.#reportError(error);
+      });
+    } catch (error) {
+      if (!this.#isExpiredRetiredConnection(error)) throw error;
+      this.#fenceLocalPublications();
+    }
+  }
+  #isExpiredRetiredConnection(error) {
+    if (!this.#replaceMediaConnection || this.#retiredLocalConnection !== this.#connection) return false;
+    if (error instanceof AggregateError) return error.errors.every((cause) => this.#isRetryableConnectionFailure(cause));
+    return this.#isRetryableConnectionFailure(error);
+  }
+  async #reattachLocalTrack(state, transceiver) {
+    await this.#boundPeerOperation(transceiver.sender.replaceTrack(state.track));
+    const cause = this.#locallyPausedSources.get(state.source);
+    state.enabled = cause === void 0;
+    state.desiredEnabled = state.enabled;
+    state.track.enabled = state.enabled;
+    if (cause === "capture_cleanup") await this.#disablePreparedTrack(state);
+    else if (cause) {
+      this.#pauseLocalSource(state.source, cause);
+      await this.#retireOwnedPublications();
+    } else {
+      for (const publication of this.#ownedPublications) if (publication.transceiver === transceiver) publication.detachedAt = null;
+    }
+    this.#publishSnapshot();
+    this.#emitLocal();
+    return state.enabled;
+  }
   async #disablePreparedTrack(state) {
     const transceiver = state.transceiver;
+    for (const publication of this.#ownedPublications) {
+      if (publication.transceiver === transceiver && publication.lifecycle.kind === "confirmed") publication.detachedAt ??= Date.now();
+    }
     state.desiredEnabled = false;
     state.track.enabled = false;
     const detach = transceiver ? this.#boundPeerOperation(transceiver.sender.replaceTrack(null)) : Promise.resolve();
@@ -691,7 +923,7 @@ var CloudflareSFUClient = class {
           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);
+          await this.#replaceMediaConnectionForRecovery(generation, "local_signaling_failure");
           await this.#publishPreparedTracksSerialized(
             [...this.#localTracks.values()].filter((state) => (state.desiredEnabled || states.includes(state)) && state.track.readyState !== "ended"),
             generation,
@@ -713,14 +945,14 @@ var CloudflareSFUClient = class {
     const authoritative = await this.#signal(() => this.#requireTransport().listPublications());
     this.#pauseUnavailableOtherSources(authoritative.publications, states);
     this.#replacementAttemptedGeneration = null;
-    await this.#replaceMediaConnectionForRecovery(generation);
+    await this.#replaceMediaConnectionForRecovery(generation, this.#retiredLocalCause);
     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;
-      this.#pauseLocalSource(state.source);
+      this.#pauseLocalSource(state.source, "discovery_absent");
     }
     void this.#retireOwnedPublications();
   }
@@ -750,7 +982,7 @@ var CloudflareSFUClient = class {
   }
   async #prepareLocalPublication(connection, state, generation) {
     const transceiver = state.transceiver ?? this.#addLocalTransceiver(connection, state);
-    const publication = { state, transceiver, trackName: `${state.source}-${globalThis.crypto.randomUUID()}`, connection, connectionId: this.#bootstrap.connectionId, lifecycle: { kind: "pending" } };
+    const publication = { state, transceiver, trackName: `${state.source}-${globalThis.crypto.randomUUID()}`, connection, connectionId: this.#bootstrap.connectionId, detachedAt: null, lifecycle: { kind: "pending" } };
     this.#ownedPublications.add(publication);
     if (state.transceiver) await this.#boundPeerOperation(transceiver.sender.replaceTrack(state.track));
     this.#requireGeneration(generation);
@@ -798,7 +1030,7 @@ var CloudflareSFUClient = class {
         source: state.source
       })
     );
-    const response = await this.#signal(() => this.#requireTransport().addTracks({ connectionId, sessionDescription, tracks }), { generation, connectionId });
+    const response = await this.#signal(() => this.#addTracks({ connectionId, sessionDescription, tracks }), { generation, connectionId });
     this.#recordLocalPublicationHandles(publications, response.tracks);
     this.#requireGeneration(generation);
     await this.#applyProviderDescription(response, connection);
@@ -824,7 +1056,7 @@ var CloudflareSFUClient = class {
         state.providerPublicationId = lifecycle.handle.publicationId;
         continue;
       }
-      this.#markPublicationRetiring(publication);
+      this.#markPublicationRetiring(publication, this.#locallyPausedSources.get(state.source) ?? "publish_failure");
       if (state.transceiver === transceiver) {
         this.#clearLocalPublication(state);
       }
@@ -849,9 +1081,8 @@ var CloudflareSFUClient = class {
     if (cursor === null) return;
     const participantRevision = this.#remoteParticipantRevision;
     const desired = this.#desiredRemotePublications(authoritative, cursor);
-    const toPull = this.#pendingRemotePulls(desired);
     this.#pollFailedPull = true;
-    const pulled = await this.#pullWithRecovery(toPull, cursor, generation);
+    const pulled = await this.#pullWithRecovery(desired, cursor, generation);
     if (pulled === null) return;
     this.#requireGeneration(generation);
     const next = reconcileRemoteTracks(desired, pulled, this.#remoteTracks);
@@ -871,16 +1102,18 @@ var CloudflareSFUClient = class {
   }
   #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);
+    for (const publicationId of this.#remotePullRetries.keys()) {
+      if (!desiredIds.has(publicationId)) this.#remotePullRetries.delete(publicationId);
     }
     for (const publicationId of this.#subscribedPublicationIds) {
       if (!desiredIds.has(publicationId)) this.#subscribedPublicationIds.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 (this.#remoteTracks.get(key)?.publicationId === publication.publicationId) {
+        if (!this.#receiveProgress.canRebuild() || !this.#replaceMediaConnection) return false;
+      }
+      const remaining = (this.#remotePullRetries.get(publication.publicationId)?.retryAfter ?? 0) - now;
       return remaining <= 0;
     }).map(([, publication]) => publication);
   }
@@ -908,7 +1141,14 @@ var CloudflareSFUClient = class {
   #canSubscribeToRemotePublication(publication) {
     return this.#remoteParticipantIds === null || this.#remoteParticipantIds.has(publication.participantId) || this.#subscribedPublicationIds.has(publication.publicationId);
   }
-  async #pullWithRecovery(publications, cursor, generation) {
+  async #pullWithRecovery(desired, cursor, generation) {
+    const pending = this.#pendingRemotePulls(desired);
+    const receiveStalled = pending.some((publication) => this.#receiveProgress.isStalled(publication.publicationId));
+    const publications = receiveStalled ? [...desired.values()] : pending;
+    if (receiveStalled) {
+      if (!this.#replaceMediaConnection || !this.#receiveProgress.reserveRebuild()) return [];
+      return this.#retryRemotePullOnReplacement(publications, cursor, generation, "receive_stalled");
+    }
     try {
       return await this.#pull(publications, generation);
     } catch (error) {
@@ -921,19 +1161,25 @@ var CloudflareSFUClient = class {
     }
   }
   #canReplaceConnectionAfterRemotePull(error, generation) {
-    return this.#isRetryableConnectionFailure(error) && !this.#hasLiveRemoteTracks() && this.#replaceMediaConnection !== void 0 && this.#replacementAttemptedGeneration !== generation;
+    const gone = error instanceof CloudflareSFUError && (error.options.status === 404 || error.options.status === 410);
+    return this.#isRetryableConnectionFailure(error) && (gone || !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) {
+  async #retryRemotePullOnReplacement(publications, cursor, generation, cause = "remote_signaling_failure") {
     this.#remoteRecoveryGeneration = generation;
+    const connection = this.#connection;
     try {
-      await this.#replaceMediaConnectionForRecovery(generation);
+      await this.#replaceMediaConnectionForRecovery(generation, cause);
       await this.#republishPreparedTracksAfterRecovery(generation);
       return await this.#pull(publications, generation);
     } catch (error) {
       if (generation !== this.#generation || this.#stopped) throw error;
+      if (cause === "receive_stalled" && connection === this.#connection) {
+        this.#replacementAttemptedGeneration = null;
+        for (const publication of publications) this.#backoffRemotePull(publication.publicationId, true);
+      }
       this.#observeRemotePublicationCursor(cursor, retryableRemotePull(error));
       throw error;
     }
@@ -974,7 +1220,10 @@ var CloudflareSFUClient = class {
   }
   #deferRemotePulls(publications, error) {
     const retryAfter = retryableRemotePull(error) ? Date.now() + 15e3 : Number.POSITIVE_INFINITY;
-    for (const publication of publications) this.#remotePullRetryAfter.set(publication.publicationId, retryAfter);
+    for (const publication of publications) {
+      const failures = this.#remotePullRetries.get(publication.publicationId)?.failures ?? 0;
+      this.#remotePullRetries.set(publication.publicationId, { retryAfter, failures, receiveStalled: this.#remotePullRetries.get(publication.publicationId)?.receiveStalled });
+    }
   }
   async #pullBatch(publications, generation) {
     if (publications.length === 0) return [];
@@ -1000,12 +1249,17 @@ var CloudflareSFUClient = class {
       connection.addEventListener("track", onTrack);
       try {
         this.#requireGeneration(generation);
-        const response = await this.#signal(() => this.#requireTransport().addTracks({ connectionId, tracks: requested, allowPartialRemoteTracks: true }), { generation, connectionId });
+        const response = await this.#signal(() => this.#addTracks({ connectionId, tracks: requested, allowPartialRemoteTracks: true }), {
+          generation,
+          connectionId
+        });
         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);
+        for (const { publication } of matched) {
+          if (!this.#remotePullRetries.get(publication.publicationId)?.receiveStalled) this.#remotePullRetries.delete(publication.publicationId);
+        }
         await this.#completeRenegotiation(response, connection, connectionId, generation);
         if (matched.length === 0) return [];
         await this.#waitForConnection(connection, generation);
@@ -1035,11 +1289,33 @@ var CloudflareSFUClient = class {
     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 = 15e3;
-      this.#remotePullRetryAfter.set(publication.publicationId, Date.now() + delay);
+      this.#backoffRemotePull(publication.publicationId);
       this.#reportError(new CloudflareSFUError(`Cloudflare SFU remote track failed: ${failure.code}`, "media_failed", { providerCode: failure.code }));
     }
   }
+  #backoffRemotePull(publicationId, receiveStalled = false) {
+    const previous = this.#remotePullRetries.get(publicationId) ?? { retryAfter: 0, failures: 0 };
+    const failures = Math.min(previous.failures + 1, 6);
+    this.#remotePullRetries.set(publicationId, { retryAfter: Date.now() + Math.min(15e3, 750 * 2 ** (failures - 1)), failures, receiveStalled: receiveStalled || previous.receiveStalled });
+  }
+  #canObserveReceiveProgress(connection) {
+    return this.#started && connectionIsLive(connection) && (typeof document === "undefined" || document.visibilityState !== "hidden");
+  }
+  #observeReceiveProgress(connection, report) {
+    if (!this.#canObserveReceiveProgress(connection)) {
+      this.#receiveProgress.clear();
+      return;
+    }
+    const { stalled, advanced } = this.#receiveProgress.sample(performance.now(), connection, report, this.#remoteTracks.values());
+    for (const publicationId of advanced) this.#remotePullRetries.delete(publicationId);
+    this.#publishSnapshot();
+    if (!this.#receiveProgress.canRebuild()) return;
+    for (const publicationId of stalled) {
+      if (!this.#remotePullRetries.get(publicationId)?.receiveStalled) this.#backoffRemotePull(publicationId, true);
+    }
+    this.#remotePullIncomplete = true;
+    this.remotePublicationsChanged();
+  }
   async #completeRenegotiation(response, connection, connectionId, generation) {
     if (!response.requiresImmediateRenegotiation) return;
     await this.#applyProviderDescription(response, connection);
@@ -1145,14 +1421,12 @@ var CloudflareSFUClient = class {
           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);
+        if (!current() || connection.signalingState !== "stable") return;
+        this.#observeReceiveProgress(connection, report);
+        const sender = this.#cameraSimulcastSender(state);
+        if (!sender) cameraPolicy.reset();
+        else await this.#applyCameraUplink(sender, report, cameraPolicy);
       } catch {
         cameraPolicy.reset();
       } finally {
@@ -1187,9 +1461,14 @@ var CloudflareSFUClient = class {
   }
   async #replaceDormantConnectionBeforeNegotiation(generation) {
     if (!this.#started || this.#negotiatedGeneration === generation || this.#replacementAttemptedGeneration === generation || !this.#replaceMediaConnection) return;
-    await this.#replaceMediaConnectionForRecovery(generation);
+    await this.#replaceMediaConnectionForRecovery(generation, "dormant_connection");
+  }
+  #addTracks(input) {
+    const replacementCause = this.#replacementCause;
+    this.#replacementCause = void 0;
+    return this.#requireTransport().addTracks({ ...input, replacementCause });
   }
-  async #replaceMediaConnectionForRecovery(generation) {
+  async #replaceMediaConnectionForRecovery(generation, cause) {
     this.#requireGeneration(generation);
     if (!this.#replaceMediaConnection || this.#replacementAttemptedGeneration === generation) {
       throw new CloudflareSFUError("A fresh Cloudflare SFU connection is unavailable", "signaling_failed");
@@ -1209,6 +1488,7 @@ var CloudflareSFUClient = class {
     this.#cursor = null;
     this.#bootstrap = bootstrap;
     this.#rebuildPeerConnection(bootstrap, generation, connectionEpoch);
+    this.#replacementCause = cause;
     this.#retiredLocalConnection = null;
     this.#negotiatedGeneration = null;
     for (const state of this.#localTracks.values()) {
@@ -1248,6 +1528,7 @@ var CloudflareSFUClient = class {
     }
   }
   #disposeConnection(stopSenders) {
+    this.#receiveProgress.clear();
     if (!stopSenders) this.#setPhase("recovering", null);
     this.#disposeConnectionObservation?.();
     this.#disposeConnectionObservation = void 0;
@@ -1285,7 +1566,7 @@ var CloudflareSFUClient = class {
     this.#emitRemote();
   }
   #schedulePoll(delayMs = this.#pollIntervalMs) {
-    if (this.#stopped || !this.#started || this.#pollTimer !== void 0) return;
+    if (this.#stopped || !this.#started && !this.#receivingInitial || this.#pollTimer !== void 0) return;
     this.#pollTimer = globalThis.setTimeout(async () => {
       this.#pollTimer = void 0;
       if (typeof document !== "undefined" && document.visibilityState === "hidden") {
@@ -1344,6 +1625,7 @@ var CloudflareSFUClient = class {
         })
       ) : EMPTY_LOCAL,
       remoteTracks: this.#remoteTracks.size ? [...this.#remoteTracks.values()] : EMPTY_REMOTE,
+      receiveStalls: this.#receiveProgress.observations,
       failure
     });
     if (snapshotEqual(this.#snapshot, next)) return;
@@ -1468,7 +1750,7 @@ function snapshotEqual(left, right) {
   return snapshotMetadataEqual(left, right) && left.localTracks.every((publication, index) => publicationEqual(publication, right.localTracks[index])) && left.remoteTracks.every((publication, index) => remotePublicationEqual(publication, right.remoteTracks[index]));
 }
 function snapshotMetadataEqual(left, right) {
-  return connectionEqual(left.connection, right.connection) && cursorEqual(left.cursor, right.cursor) && failureEqual(left.failure, right.failure) && left.localTracks.length === right.localTracks.length && left.remoteTracks.length === right.remoteTracks.length;
+  return (left.receiveStalls ?? EMPTY_RECEIVE_STALLS) === (right.receiveStalls ?? EMPTY_RECEIVE_STALLS) && connectionEqual(left.connection, right.connection) && cursorEqual(left.cursor, right.cursor) && failureEqual(left.failure, right.failure) && left.localTracks.length === right.localTracks.length && left.remoteTracks.length === right.remoteTracks.length;
 }
 function connectionEqual(left, right) {
   return left.phase === right.phase && left.peerConnectionState === right.peerConnectionState && left.iceConnectionState === right.iceConnectionState;
@@ -1557,7 +1839,10 @@ function createCloudflareSFUHTTPTransport(options) {
   };
   return {
     addTracks: async (input) => {
-      const path = input.allowPartialRemoteTracks ? "tracks?allow_partial_remote_tracks=true" : "tracks";
+      const query = new URLSearchParams();
+      if (input.allowPartialRemoteTracks) query.set("allow_partial_remote_tracks", "true");
+      if (input.replacementCause) query.set("replacement_cause", input.replacementCause);
+      const path = query.size ? `tracks?${query}` : "tracks";
       const response = await request(path, {
         method: "POST",
         body: JSON.stringify({ connection_id: input.connectionId, session_description: input.sessionDescription, tracks: input.tracks })