@q9labsai/chalk-client 5.2.4 → 5.2.6

package/dist/{chunk-3ASKGMD3.js → chunk-YIDKETOX.js}

@@ -176,6 +176,61 @@ function matchRemotePullTracks(publications, tracks) {
   });
 }
 
+// src/media/failure-diagnostics.ts
+var steps = /* @__PURE__ */ new WeakMap();
+var fetchFailures = /* @__PURE__ */ new WeakSet();
+var domErrorKinds = /* @__PURE__ */ new Map([
+  ["NotAllowedError", "NotAllowedError"],
+  ["NotReadableError", "NotReadableError"],
+  ["NotFoundError", "NotFoundError"],
+  ["OverconstrainedError", "OverconstrainedError"],
+  ["AbortError", "AbortError"],
+  ["SecurityError", "SecurityError"],
+  ["InvalidStateError", "InvalidStateError"],
+  ["OperationError", "OperationError"],
+  ["NotSupportedError", "NotSupportedError"],
+  ["TimeoutError", "timeout"],
+  ["NetworkError", "network"]
+]);
+function grantedMediaFromStream(stream) {
+  const liveTracks = stream.getTracks().filter((track) => track.readyState === "live");
+  return {
+    granted_audio: liveTracks.some((track) => track.kind === "audio") ? "granted" : "not_granted",
+    granted_video: liveTracks.some((track) => track.kind === "video") ? "granted" : "not_granted"
+  };
+}
+function markMediaFetchFailure(error) {
+  if (typeof error === "object" && error !== null) fetchFailures.add(error);
+}
+function markMediaFailure(error, step) {
+  if (typeof error === "object" && error !== null && !steps.has(error)) steps.set(error, step);
+}
+function unwrapMediaFailure(error, step) {
+  for (let depth = 0; depth < 8; depth++) {
+    if (typeof error !== "object" || error === null) break;
+    step = steps.get(error) ?? step;
+    if (fetchFailures.has(error)) break;
+    if (!("cause" in error) || error.cause === void 0) break;
+    error = error.cause;
+  }
+  return { error, step };
+}
+function classifyMediaFailure(cause, fallbackStep) {
+  const { error, step } = unwrapMediaFailure(cause, fallbackStep);
+  if (error instanceof CloudflareSFUError) {
+    const status = error.options.status;
+    return {
+      media_error_kind: error.code === "signaling_timeout" || error.code === "negotiation_timeout" ? "timeout" : "CloudflareSFUError",
+      media_error_step: step,
+      ...status !== void 0 && Number.isInteger(status) && status >= 400 && status <= 599 ? { http_status: status } : {}
+    };
+  }
+  if (typeof DOMException !== "undefined" && error instanceof DOMException) {
+    return { media_error_kind: domErrorKinds.get(error.name) ?? "unknown", media_error_step: step };
+  }
+  return { media_error_kind: error instanceof TypeError && fetchFailures.has(error) ? "network" : "unknown", media_error_step: step };
+}
+
 // src/media/client.ts
 var EMPTY_LOCAL = Object.freeze([]);
 var EMPTY_REMOTE = Object.freeze([]);
@@ -183,6 +238,7 @@ 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;
@@ -194,19 +250,21 @@ var CloudflareSFUClient = class {
   #replaceMediaConnection;
   #remoteListeners = /* @__PURE__ */ new Set();
   #snapshotListeners = /* @__PURE__ */ new Set();
-  #locallyPausedSources = /* @__PURE__ */ new Set();
+  #failureOwners = /* @__PURE__ */ new WeakMap();
+  #locallyPausedSources = /* @__PURE__ */ new Map();
   #localTracks = /* @__PURE__ */ new Map();
-  #reusableLocalTransceivers = /* @__PURE__ */ new Map();
-  #reusableLocalPublicationIds = /* @__PURE__ */ new Map();
+  #ownedPublications = /* @__PURE__ */ new Set();
   #remoteTracks = /* @__PURE__ */ new Map();
   #bootstrap;
   #connection;
   #disposeConnectionObservation;
   #connectionEpoch = 0;
   #retiredLocalConnection = null;
+  #retiredLocalCause = "forced_pause";
+  #replacementCause;
   #cursor = null;
   #remotePullIncomplete = false;
-  #remotePullRetryAfter = /* @__PURE__ */ new Map();
+  #remotePullRetries = /* @__PURE__ */ new Map();
   #remoteParticipantIds = null;
   #remoteParticipantRevision = 0;
   #subscribedPublicationIds = /* @__PURE__ */ new Set();
@@ -220,6 +278,7 @@ var CloudflareSFUClient = class {
   #pollFailedPull = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
+  #retirement = Promise.resolve();
   #snapshot;
   #started = false;
   #stopped = false;
@@ -252,7 +311,7 @@ var CloudflareSFUClient = class {
     return subscribeSnapshot(this.#snapshotListeners, listener);
   }
   remotePublicationResumed(publicationId) {
-    this.#remotePullRetryAfter.delete(publicationId);
+    this.#remotePullRetries.delete(publicationId);
     this.remotePublicationsChanged();
   }
   remoteParticipantsChanged(participantIds) {
@@ -273,20 +332,17 @@ var CloudflareSFUClient = class {
     this.#requireActive();
     validateTrackSource(source, track);
     if (this.#localTracks.has(source)) throw new CloudflareSFUError(`A ${source} track is already prepared`, "media_failed");
+    const reusable = [...this.#ownedPublications].find((item) => item.state.source === source && item.connection === this.#connection && item.lifecycle.kind === "confirmed");
     const state = {
       source,
       track,
-      transceiver: this.#reusableLocalTransceivers.get(source) ?? null,
-      providerPublicationId: this.#reusableLocalPublicationIds.get(source) ?? null,
-      pendingOperationId: null,
-      pendingTrackName: null,
+      transceiver: reusable?.transceiver ?? null,
+      providerPublicationId: reusable?.lifecycle.kind === "confirmed" ? reusable.lifecycle.handle.publicationId : null,
       desiredEnabled: false,
       enabled: false,
       endedListener: null,
       clearing: null
     };
-    this.#reusableLocalTransceivers.delete(source);
-    this.#reusableLocalPublicationIds.delete(source);
     if (source === "screen") {
       state.endedListener = () => {
         if (this.#localTracks.get("screen") === state) this.#invokeListener(() => this.#onScreenEnded?.());
@@ -310,9 +366,10 @@ var CloudflareSFUClient = class {
   }
   async #clearPreparedTrack(state, stopTrack = true) {
     const source = state.source;
-    if (source === "screen_audio") {
+    if (source === "screen" || source === "screen_audio") {
       try {
-        await this.#retireLocalPublication(source);
+        this.#pauseLocalSource(source, "capture_cleanup");
+        await this.#retireOwnedPublications();
       } finally {
         this.#removeOwnedLocalTrack(state, stopTrack);
         if (this.#localTracks.get(source) === state) this.#localTracks.delete(source);
@@ -321,10 +378,8 @@ var CloudflareSFUClient = class {
       }
       return;
     }
-    if (state.enabled) await this.#setPreparedTrackEnabled(state, false);
+    if (state.enabled) await this.#disablePreparedTrack(state);
     if (this.#localTracks.get(source) !== state) return;
-    if (state.transceiver) this.#reusableLocalTransceivers.set(source, state.transceiver);
-    if (state.providerPublicationId) this.#reusableLocalPublicationIds.set(source, state.providerPublicationId);
     this.#removeOwnedLocalTrack(state, stopTrack);
     this.#localTracks.delete(source);
     this.#publishSnapshot();
@@ -349,7 +404,7 @@ var CloudflareSFUClient = class {
     this.#pollFailedPull = false;
     try {
       const transport = this.#requireTransport();
-      const authoritative = await (() => transport.listPublications())();
+      const authoritative = await this.#signal(() => transport.listPublications());
       this.#requireGeneration(generation);
       await this.#reconcileRemotePublications(authoritative, generation);
       this.#requireGeneration(generation);
@@ -370,46 +425,63 @@ var CloudflareSFUClient = class {
     this.#schedulePoll(0);
   }
   async setLocalPublicationTarget(target) {
-    const result = await this.#setSinglePublicationTarget(target);
+    if (!target.enabled) return this.#pausePublicationTarget(target);
+    const result = await this.#enablePublicationTarget(target);
     if (target.source !== "screen" || !this.#localTracks.has("screen_audio") || result.outcome !== "confirmed" && result.outcome !== "satisfied") return result;
-    return this.#setSinglePublicationTarget({ ...target, source: "screen_audio" });
+    return this.#enablePublicationTarget({ ...target, source: "screen_audio" });
   }
-  async #setSinglePublicationTarget(target) {
+  async #pausePublicationTarget(target) {
+    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();
+      return { outcome, errorCode: null };
+    } catch (error) {
+      return mediaTargetFailure(error);
+    }
+  }
+  async #enablePublicationTarget(target) {
+    const generation = this.#generation;
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result") return resolved.result;
     const state = resolved.value;
-    if (this.#pausedTarget(target)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
+    if (this.#locallyPausedSources.has(target.source)) 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);
+      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 };
+      if (!await this.#enablePreparedTrack(state)) return { outcome: "terminal_failure", errorCode: "local_source_paused" };
       return { outcome: "confirmed", errorCode: null };
     } catch (error) {
-      if (!this.#stopped) this.#reportError(error);
+      if (generation === this.#generation && !this.#stopped) this.#reportError(error);
       return mediaTargetFailure(error);
     }
   }
-  #pausedTarget(target) {
-    return target.enabled && this.#locallyPausedSources.has(target.source);
-  }
-  setLocalSourceIntent(source, enabled) {
-    if (source === "screen") this.setLocalSourceIntent("screen_audio", enabled);
-    if (enabled) {
-      this.#locallyPausedSources.delete(source);
-      return;
-    }
-    this.#locallyPausedSources.add(source);
+  async pauseLocalCapture(source) {
+    this.#locallyPausedSources.set(source, "capture_cleanup");
     const state = this.#localTracks.get(source);
-    if (!state) return;
-    state.desiredEnabled = false;
-    state.track.enabled = false;
+    if (state) await this.#disablePreparedTrack(state);
   }
-  async closeForcedLocalPublication(source) {
-    this.setLocalSourceIntent(source, false);
-    await this.#retireLocalPublication(source);
-    if (source === "screen") await this.#retireLocalPublication("screen_audio");
-    if (!this.#replaceMediaConnection) return;
+  setLocalSourceIntent(source, enabled, cause = "forced_pause") {
+    const sources = localSourceGroup(source);
+    for (const item of sources) {
+      if (enabled) this.#locallyPausedSources.delete(item);
+      else this.#locallyPausedSources.set(item, cause);
+    }
+    if (!enabled) this.#pauseLocalSource(source, cause);
+    return enabled ? Promise.resolve() : this.#retireOwnedPublications();
+  }
+  async closeForcedLocalPublication(source, cause = "forced_pause") {
+    const sources = localSourceGroup(source);
+    const ownsPublication = [...this.#ownedPublications].some((item) => sources.includes(item.state.source));
+    await this.setLocalSourceIntent(source, false, cause);
+    if (!ownsPublication || !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));
@@ -423,54 +495,90 @@ var CloudflareSFUClient = class {
       this.#requireGeneration(generation);
       this.#setPhase("live", null);
     });
+    await this.#retirement;
   }
   async #retireUnavailableLocalPublication(state) {
     const publicationId = state.providerPublicationId;
     if (!publicationId) return;
-    const authoritative = await (() => this.#requireTransport().listPublications())();
+    const authoritative = await this.#signal(() => this.#requireTransport().listPublications());
     if (authoritative.publications.some((publication) => publication.publicationId === publicationId)) return;
-    if (state.providerPublicationId === publicationId) await this.#retireLocalPublication(state.source);
+    if (state.providerPublicationId === publicationId) {
+      this.#pauseLocalSource(state.source, "discovery_absent");
+      await this.#retireOwnedPublications();
+    }
   }
-  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;
+  #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, cause);
+    }
+    for (const state of this.#localTracks.values()) {
+      if (!sources.includes(state.source)) continue;
       state.desiredEnabled = false;
-      state.enabled = false;
-      state.providerPublicationId = null;
-      state.transceiver = null;
+      this.#clearLocalPublication(state);
     }
     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 (() => connection.createOffer())();
-      await (() => 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;
+  }
+  #retireOwnedPublications(reportFailure = this.#reportError.bind(this)) {
+    const publications = [...this.#ownedPublications].filter((item) => item.lifecycle.kind === "retiring" && item.lifecycle.handle);
+    const retirement = (async () => {
+      const errors = [];
+      for (const publication of publications) {
+        try {
+          await this.#serializeSDP(() => this.#closeOwnedPublication(publication), true);
+        } catch (error) {
+          errors.push(error);
+          if (!this.#stopped) reportFailure(error);
+        }
       }
+      if (this.#stopped && this.#ownedPublications.size === 0) this.#transport = void 0;
+      if (errors.length) throw new AggregateError(errors, "Media retirement failed");
+    })();
+    void retirement.catch(() => {
     });
+    return this.#retirement = retirement;
+  }
+  #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, 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) {
+        await this.#boundPeerOperation(transceiver.sender.replaceTrack(null));
+        closed = connection.connectionState === "closed";
+        if (!closed) transceiver.stop();
+      }
+      phase.detached = true;
+      const sessionDescription = closed ? void 0 : await createLocalOffer(connection);
+      const response = await this.#signal(() => this.#requireTransport().closeTracks({ connectionId, sessionDescription, tracks: [{ ...handle, source: state.source }], force: closed }), { generation: this.#generation, connectionId });
+      publication.lifecycle = { kind: "retired" };
+      this.#ownedPublications.delete(publication);
+      if (connection.connectionState !== "closed") await this.#applyProviderDescription(response, connection);
+    } catch (error) {
+      await this.#rollbackLocalOffer(connection);
+      throw error;
+    }
+  }
+  #fenceLocalPublications() {
+    for (const publication of this.#ownedPublications) publication.lifecycle = { kind: "retired" };
+    this.#ownedPublications.clear();
   }
   observeLocalPublications(listener) {
     this.#localListeners.add(listener);
@@ -486,19 +594,23 @@ 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();
+      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);
-    this.#reusableLocalTransceivers.clear();
-    this.#reusableLocalPublicationIds.clear();
+    for (const publication of this.#ownedPublications) this.#markPublicationRetiring(publication);
+    void this.#retireOwnedPublications();
     this.#clearRemoteTracks();
     this.#cursor = null;
     this.#negotiatedGeneration = null;
-    this.#replacementAttemptedGeneration = null;
+    this.#replacementAttemptedGeneration = options.bootstrap.connectionId !== this.#bootstrap.connectionId ? generation : null;
     if (options.bootstrap.connectionId !== this.#bootstrap.connectionId) this.#started = false;
     this.#bootstrap = options.bootstrap;
     if (options.transport) this.#transport = options.transport;
@@ -524,22 +636,27 @@ var CloudflareSFUClient = class {
     }
   }
   stop() {
-    if (this.#stopped) return;
+    if (this.#stopped) {
+      void this.#retireOwnedPublications();
+      return;
+    }
     this.#stopped = true;
     this.#subscribedPublicationIds.clear();
     this.#generation++;
     this.#connectionEpoch++;
     this.#clearPoll();
-    this.#remotePullRetryAfter.clear();
+    this.#remotePullRetries.clear();
     this.#polling = false;
     this.#pollAfterCurrent = false;
     this.#disposeConnection(true);
-    this.#reusableLocalTransceivers.clear();
-    this.#reusableLocalPublicationIds.clear();
+    for (const publication of this.#ownedPublications) this.#markPublicationRetiring(publication);
     this.#clearRemoteTracks();
-    for (const state of this.#localTracks.values()) this.#removeOwnedLocalTrack(state);
+    for (const state of this.#localTracks.values()) {
+      state.track.enabled = false;
+      this.#removeOwnedLocalTrack(state);
+    }
     this.#localTracks.clear();
-    this.#transport = void 0;
+    void this.#retireOwnedPublications();
     this.#started = false;
     this.#cursor = null;
     this.#publishSnapshot("stopped", null);
@@ -549,94 +666,115 @@ var CloudflareSFUClient = class {
     this.#remoteListeners.clear();
     this.#snapshotListeners.clear();
   }
-  async #setPreparedTrackEnabled(state, enabled, operationId) {
-    if (enabled) return this.#enablePreparedTrack(state, operationId);
-    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;
+  async #enablePreparedTrack(state) {
     const generation = this.#generation;
     try {
+      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) {
-      state.desiredEnabled = false;
-      state.enabled = false;
-      state.track.enabled = false;
+      if (generation === this.#generation) {
+        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();
     state.enabled = false;
-    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 () => {
-      const pending = await this.#prepareConnectionForPublication(states, generation);
-      try {
-        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.#publishPreparedTracksSerialized(
-          [...this.#localTracks.values()].filter((state) => (state.desiredEnabled || states.includes(state)) && state.track.readyState !== "ended"),
-          generation,
-          this.#connection,
-          this.#bootstrap.connectionId
-        );
-      }
-    });
+    try {
+      await this.#serializeSDP(async () => {
+        const pending = await this.#prepareConnectionForPublication(states, generation);
+        try {
+          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, "local_signaling_failure");
+          await this.#publishPreparedTracksSerialized(
+            [...this.#localTracks.values()].filter((state) => (state.desiredEnabled || states.includes(state)) && state.track.readyState !== "ended"),
+            generation,
+            this.#connection,
+            this.#bootstrap.connectionId
+          );
+        }
+      });
+    } finally {
+      await this.#retirement.catch(() => {
+      });
+    }
   }
   async #prepareConnectionForPublication(states, generation) {
     if (this.#retiredLocalConnection !== this.#connection || !this.#replaceMediaConnection) {
       await this.#replaceDormantConnectionBeforeNegotiation(generation);
       return states;
     }
-    const authoritative = await (() => this.#requireTransport().listPublications())();
+    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;
-      state.desiredEnabled = false;
-      state.track.enabled = false;
+      this.#pauseLocalSource(state.source, "discovery_absent");
     }
+    void this.#retireOwnedPublications();
   }
   async #publishPreparedTracksSerialized(states, generation, connection, connectionId) {
     this.#requireGeneration(generation);
@@ -646,28 +784,30 @@ var CloudflareSFUClient = class {
     const publications = [];
     try {
       for (const state of pendingStates) publications.push(await this.#prepareLocalPublication(connection, state, generation));
-      const response = await this.#negotiateLocalPublications(connection, connectionId, publications, generation);
+      await this.#negotiateLocalPublications(connection, connectionId, publications, generation);
       if (!wasLive) await this.#waitForConnection(connection, generation);
       this.#requireGeneration(generation);
       this.#negotiatedGeneration = generation;
-      this.#confirmLocalPublications(publications, response.tracks);
+      this.#settleLocalPublications(publications);
       this.#publishSnapshot();
       this.#emitLocal();
     } catch (error) {
-      if (generation === this.#generation) {
-        await this.#rollbackLocalOffer(connection);
-        await this.#discardLocalPublications(publications);
-      }
+      await this.#rollbackLocalOffer(connection);
+      for (const publication of publications) this.#markPublicationRetiring(publication);
+      this.#settleLocalPublications(publications);
       throw error;
+    } finally {
+      void this.#retireOwnedPublications();
     }
   }
   async #prepareLocalPublication(connection, state, generation) {
-    const reusedTransceiver = state.transceiver !== null;
     const transceiver = state.transceiver ?? this.#addLocalTransceiver(connection, state);
-    if (reusedTransceiver) await this.#boundPeerOperation(transceiver.sender.replaceTrack(state.track));
+    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);
     state.transceiver = transceiver;
-    return { state, transceiver, trackName: state.pendingTrackName ?? `${state.source}-${globalThis.crypto.randomUUID()}`, reusedTransceiver };
+    return publication;
   }
   #addLocalTransceiver(connection, state) {
     if (state.source !== "camera" || firefoxCameraSimulcastUnsupported()) return connection.addTransceiver(state.track, { direction: "sendonly" });
@@ -686,10 +826,9 @@ var CloudflareSFUClient = class {
     }
   }
   async #negotiateLocalPublications(connection, connectionId, publications, generation) {
-    let offer;
+    let sessionDescription;
     try {
-      offer = await (() => connection.createOffer())();
-      await (() => connection.setLocalDescription(offer))();
+      sessionDescription = await createLocalOffer(connection);
     } 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;
@@ -701,8 +840,7 @@ var CloudflareSFUClient = class {
         publication.transceiver = connection.addTransceiver(publication.state.track, { direction: "sendonly" });
         publication.state.transceiver = publication.transceiver;
       }
-      offer = await (() => connection.createOffer())();
-      await (() => connection.setLocalDescription(offer))();
+      sessionDescription = await createLocalOffer(connection);
     }
     const tracks = publications.map(
       ({ state, transceiver, trackName }) => ({
@@ -712,43 +850,44 @@ var CloudflareSFUClient = class {
         source: state.source
       })
     );
-    const response = await (() => this.#requireTransport().addTracks({ connectionId, ...providerDescription(requireDescription(offer)), tracks }))();
+    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);
-    return response;
   }
-  #confirmLocalPublications(publications, tracks) {
-    for (const { state, transceiver } of publications) {
+  #recordLocalPublicationHandles(publications, tracks) {
+    for (const publication of publications) {
+      const { state, transceiver, lifecycle } = publication;
+      if (lifecycle.kind === "retired") continue;
       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");
-      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;
+      if (!authoritative?.publicationId) throw new CloudflareSFUError("Missing publication ID", "invalid_publication");
+      const handle = { publicationId: authoritative.publicationId, mid: requireTransceiverMid(transceiver) };
+      publication.lifecycle = lifecycle.kind === "retiring" ? { ...lifecycle, handle } : { kind: "confirmed", handle };
     }
   }
-  async #discardLocalPublications(publications) {
-    for (const { state, transceiver, reusedTransceiver } of publications) {
-      if (reusedTransceiver) {
-        try {
-          await transceiver.sender.replaceTrack(null);
-        } catch (error) {
-          this.#reportError(error);
-        }
+  #settleLocalPublications(publications) {
+    for (const publication of publications) {
+      const { state, transceiver, lifecycle } = publication;
+      if (lifecycle.kind === "retired") continue;
+      if (lifecycle.kind === "confirmed" && state.transceiver === transceiver && !this.#locallyPausedSources.has(state.source)) {
+        state.enabled = true;
+        state.desiredEnabled = true;
+        state.track.enabled = true;
+        state.providerPublicationId = lifecycle.handle.publicationId;
         continue;
       }
-      try {
-        transceiver.stop();
-      } catch (error) {
-        this.#reportError(error);
+      this.#markPublicationRetiring(publication, this.#locallyPausedSources.get(state.source) ?? "publish_failure");
+      if (state.transceiver === transceiver) {
+        this.#clearLocalPublication(state);
       }
-      if (state.transceiver === transceiver) state.transceiver = null;
     }
   }
+  #clearLocalPublication(state) {
+    state.transceiver = null;
+    state.providerPublicationId = null;
+    state.enabled = false;
+    state.track.enabled = false;
+  }
   async #rollbackLocalOffer(connection) {
     if (connection.signalingState !== "have-local-offer") return;
     try {
@@ -784,8 +923,8 @@ 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);
@@ -793,7 +932,7 @@ var CloudflareSFUClient = class {
     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;
+      const remaining = (this.#remotePullRetries.get(publication.publicationId)?.retryAfter ?? 0) - now;
       return remaining <= 0;
     }).map(([, publication]) => publication);
   }
@@ -834,7 +973,8 @@ 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");
@@ -842,7 +982,7 @@ var CloudflareSFUClient = class {
   async #retryRemotePullOnReplacement(publications, cursor, generation) {
     this.#remoteRecoveryGeneration = generation;
     try {
-      await this.#replaceMediaConnectionForRecovery(generation);
+      await this.#replaceMediaConnectionForRecovery(generation, "remote_signaling_failure");
       await this.#republishPreparedTracksAfterRecovery(generation);
       return await this.#pull(publications, generation);
     } catch (error) {
@@ -887,7 +1027,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 });
+    }
   }
   async #pullBatch(publications, generation) {
     if (publications.length === 0) return [];
@@ -913,12 +1056,12 @@ var CloudflareSFUClient = class {
       connection.addEventListener("track", onTrack);
       try {
         this.#requireGeneration(generation);
-        const response = await (() => this.#requireTransport().addTracks({ connectionId, tracks: requested, allowPartialRemoteTracks: true }))();
+        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) this.#remotePullRetries.delete(publication.publicationId);
         await this.#completeRenegotiation(response, connection, connectionId, generation);
         if (matched.length === 0) return [];
         await this.#waitForConnection(connection, generation);
@@ -948,8 +1091,10 @@ 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);
+      const previous = this.#remotePullRetries.get(publication.publicationId) ?? { retryAfter: 0, failures: 0 };
+      const failureCount = Math.min(previous.failures + 1, 6);
+      const delay = Math.min(15e3, 750 * 2 ** (failureCount - 1));
+      this.#remotePullRetries.set(publication.publicationId, { retryAfter: Date.now() + delay, failures: failureCount });
       this.#reportError(new CloudflareSFUError(`Cloudflare SFU remote track failed: ${failure.code}`, "media_failed", { providerCode: failure.code }));
     }
   }
@@ -958,13 +1103,13 @@ var CloudflareSFUClient = class {
     await this.#applyProviderDescription(response, connection);
     const answer = await (() => connection.createAnswer())();
     await (() => connection.setLocalDescription(answer))();
-    await (() => this.#requireTransport().renegotiate({ connectionId, ...providerDescription(requireDescription(answer)) }))();
+    await this.#signal(() => this.#requireTransport().renegotiate({ connectionId, sessionDescription: requireDescription(answer) }), { generation, connectionId });
     this.#requireGeneration(generation);
   }
   async #applyProviderDescription(response, connection = this.#connection) {
     await (() => connection.setRemoteDescription(requireSFUDescription(response.sessionDescription)))();
   }
-  #serializeSDP(operation) {
+  #serializeSDP(operation, retirement = false) {
     const generation = this.#generation;
     let expired = false;
     let timer;
@@ -977,7 +1122,7 @@ var CloudflareSFUClient = class {
       }, NEGOTIATION_TIMEOUT_MS);
     });
     const run = () => {
-      if (expired || generation !== this.#generation) throw timeout;
+      if (expired || !retirement && generation !== this.#generation) throw timeout;
       return operation();
     };
     const pending = this.#sdpTail.then(run, run);
@@ -1100,9 +1245,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");
@@ -1115,14 +1265,14 @@ var CloudflareSFUClient = class {
     if (bootstrap.connectionId === this.#bootstrap.connectionId) {
       throw new CloudflareSFUError("Participant access did not replace the Cloudflare SFU connection", "signaling_failed");
     }
+    this.#fenceLocalPublications();
     const connectionEpoch = ++this.#connectionEpoch;
     this.#disposeConnection(false);
-    this.#reusableLocalTransceivers.clear();
-    this.#reusableLocalPublicationIds.clear();
     this.#clearRemoteTracks();
     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()) {
@@ -1190,8 +1340,6 @@ var CloudflareSFUClient = class {
     state.desiredEnabled = false;
     state.transceiver = null;
     state.providerPublicationId = null;
-    state.pendingOperationId = null;
-    state.pendingTrackName = null;
     state.endedListener = null;
   }
   #clearRemoteTracks() {
@@ -1271,7 +1419,7 @@ var CloudflareSFUClient = class {
   }
   #setFailure(error, fallback) {
     const code = error instanceof CloudflareSFUError ? error.code : fallback;
-    this.#publishSnapshot("failed", { code, recoverable: code !== "invalid_bootstrap" && code !== "invalid_target" && code !== "invalid_publication" });
+    this.#publishSnapshot("failed", { code, recoverable: code !== "invalid_bootstrap" && code !== "invalid_target" && code !== "invalid_publication", diagnostic: classifyMediaFailure(error, "peer_connection") });
     this.#reportError(error);
   }
   #emitLocal() {
@@ -1290,19 +1438,29 @@ var CloudflareSFUClient = class {
     }
   }
   #reportError(error) {
+    const owner = error instanceof Error ? this.#failureOwners.get(error) : void 0;
+    if (owner && (owner.generation !== this.#generation || owner.connectionId !== this.#bootstrap.connectionId)) return;
     try {
-      this.#onError?.(error);
+      this.#onError?.(error, owner?.connectionId ?? this.#bootstrap.connectionId);
     } catch {
     }
   }
+  async #signal(operation, owner = { generation: this.#generation, connectionId: this.#bootstrap.connectionId }) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (error instanceof Error) this.#failureOwners.set(error, owner);
+      throw error;
+    }
+  }
   #requireGeneration(generation) {
-    if (generation !== this.#generation || this.#stopped) throw new CloudflareSFUError("Cloudflare SFU operation belongs to a stale connection generation", "stale_generation");
+    if (generation !== this.#generation || this.#stopped) throw new CloudflareSFUError("Stale media connection", "stale_generation");
   }
   #requireActive() {
-    if (this.#stopped) throw new CloudflareSFUError("Cloudflare SFU client is stopped", "media_failed");
+    if (this.#stopped) throw new CloudflareSFUError("SFU client stopped", "media_failed");
   }
   #requireTransport() {
-    if (!this.#transport) throw new CloudflareSFUError("Cloudflare SFU signaling transport is unavailable", "signaling_failed");
+    if (!this.#transport) throw new CloudflareSFUError("SFU signaling unavailable", "signaling_failed");
     return this.#transport;
   }
 };
@@ -1391,8 +1549,13 @@ 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 };
+async function createLocalOffer(connection) {
+  const offer = await connection.createOffer();
+  await connection.setLocalDescription(offer);
+  return requireDescription(offer);
+}
+function localSourceGroup(source) {
+  return source === "screen" ? [source, "screen_audio"] : [source];
 }
 function isRateLimited(error) {
   return error instanceof CloudflareSFUError && error.options.status === 429;
@@ -1425,31 +1588,43 @@ function createCloudflareSFUHTTPTransport(options) {
   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 withDeadline(CREDENTIAL_TIMEOUT_MS, (signal) => credential(signal));
-    if (!token.trim()) throw new CloudflareSFUError("The media credential provider returned an empty token", "signaling_failed");
-    return withDeadline(timeoutMs, async (signal) => {
-      const startedAt = performance.now();
-      const response = await fetch(`${mediaPath}/${path}`, {
-        ...init,
-        signal,
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...options.traceparent ? { traceparent: options.traceparent } : {}, ...init?.headers }
-      });
-      if (!response.ok) {
-        try {
-          options.onDiagnostic?.({ event: "media_http_error", http_status: response.status, duration_ms: performance.now() - startedAt });
-        } catch {
-        }
-        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
+    try {
+      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");
+      return await withDeadline(timeoutMs, async (signal) => {
+        const startedAt = performance.now();
+        const response = await fetch(`${mediaPath}/${path}`, {
+          ...init,
+          signal,
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...options.traceparent ? { traceparent: options.traceparent } : {}, ...init?.headers }
+        }).catch((error) => {
+          markMediaFetchFailure(error);
+          throw error;
         });
-      }
-      return await response.json();
-    });
+        if (!response.ok) {
+          try {
+            options.onDiagnostic?.({ event: "media_http_error", http_status: response.status, duration_ms: performance.now() - startedAt });
+          } catch {
+          }
+          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();
+      });
+    } catch (error) {
+      const step = path === "publications" ? "sfu_publications" : path === "tracks/close" ? "sfu_close_tracks" : path === "renegotiate" ? "sfu_renegotiate" : "sfu_tracks";
+      markMediaFailure(error, step);
+      throw error;
+    }
   };
   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 })
@@ -1538,7 +1713,6 @@ function describeMediaCaptureError(cause) {
 }
 
 export {
-  describeMediaCaptureError,
   CloudflareSFUError,
   parseCloudflareSFUPublicationID,
   requireDescription,
@@ -1547,6 +1721,10 @@ export {
   comparePublicationCursor,
   publicationKey,
   waitFor,
+  grantedMediaFromStream,
+  markMediaFailure,
+  classifyMediaFailure,
   CloudflareSFUClient,
-  createCloudflareSFUHTTPTransport
+  createCloudflareSFUHTTPTransport,
+  describeMediaCaptureError
 };