@q9labsai/chalk-client 5.2.3 → 5.2.5

package/dist/{chunk-DWKTGBHR.js → chunk-FD25AMLG.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([]);
@@ -194,10 +249,10 @@ var CloudflareSFUClient = class {
   #replaceMediaConnection;
   #remoteListeners = /* @__PURE__ */ new Set();
   #snapshotListeners = /* @__PURE__ */ new Set();
+  #failureOwners = /* @__PURE__ */ new WeakMap();
   #locallyPausedSources = /* @__PURE__ */ new Set();
   #localTracks = /* @__PURE__ */ new Map();
-  #reusableLocalTransceivers = /* @__PURE__ */ new Map();
-  #reusableLocalPublicationIds = /* @__PURE__ */ new Map();
+  #ownedPublications = /* @__PURE__ */ new Set();
   #remoteTracks = /* @__PURE__ */ new Map();
   #bootstrap;
   #connection;
@@ -220,6 +275,7 @@ var CloudflareSFUClient = class {
   #pollFailedPull = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
+  #retirement = Promise.resolve();
   #snapshot;
   #started = false;
   #stopped = false;
@@ -273,20 +329,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 +363,10 @@ var CloudflareSFUClient = class {
   }
   async #clearPreparedTrack(state, stopTrack = true) {
     const source = state.source;
-    if (source === "screen_audio") {
+    if (source === "screen" || source === "screen_audio" || state.track.readyState === "ended") {
       try {
-        await this.#retireLocalPublication(source);
+        this.#pauseLocalSource(source);
+        await this.#retireOwnedPublications();
       } finally {
         this.#removeOwnedLocalTrack(state, stopTrack);
         if (this.#localTracks.get(source) === state) this.#localTracks.delete(source);
@@ -321,10 +375,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 +401,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 +422,54 @@ 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 #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";
+    this.#pauseLocalSource(target.source);
+    try {
+      await this.#retireOwnedPublications();
+      return { outcome, errorCode: null };
+    } catch (error) {
+      return mediaTargetFailure(error);
+    }
   }
-  async #setSinglePublicationTarget(target) {
+  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 };
+      await this.#enablePreparedTrack(state);
       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;
+    const sources = localSourceGroup(source);
+    for (const item of sources) {
+      if (enabled) this.#locallyPausedSources.delete(item);
+      else this.#locallyPausedSources.add(item);
     }
-    this.#locallyPausedSources.add(source);
-    const state = this.#localTracks.get(source);
-    if (!state) return;
-    state.desiredEnabled = false;
-    state.track.enabled = false;
+    if (!enabled) this.#pauseLocalSource(source);
+    return enabled ? Promise.resolve() : this.#retireOwnedPublications();
   }
   async closeForcedLocalPublication(source) {
-    this.setLocalSourceIntent(source, false);
-    await this.#retireLocalPublication(source);
-    if (source === "screen") await this.#retireLocalPublication("screen_audio");
-    if (!this.#replaceMediaConnection) return;
+    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 generation = this.#generation;
     await this.#serializeSDP(async () => {
       const existing = new Set([...this.#localTracks.values()].filter((state) => state.source !== source && state.providerPublicationId !== null));
@@ -423,54 +483,82 @@ 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);
+      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) {
+    const sources = localSourceGroup(source);
+    for (const publication of this.#ownedPublications) {
+      if (!sources.includes(publication.state.source)) continue;
+      this.#markPublicationRetiring(publication);
+      this.#retiredLocalConnection = this.#connection;
+    }
+    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() {
+    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) this.#reportError(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) {
+    const phase = publication.lifecycle;
+    if (phase.kind === "pending" || phase.kind === "confirmed") publication.lifecycle = { kind: "retiring", handle: phase.kind === "confirmed" ? phase.handle : null, detached: false };
+  }
+  async #closeOwnedPublication(publication) {
+    const phase = publication.lifecycle;
+    if (phase.kind !== "retiring" || !phase.handle) return;
+    const handle = phase.handle;
+    const { connection, connectionId, transceiver, state } = 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,6 +574,7 @@ 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();
     const generation = ++this.#generation;
     const connectionEpoch = ++this.#connectionEpoch;
     this.#polling = false;
@@ -493,12 +582,12 @@ var CloudflareSFUClient = class {
     this.#clearPoll();
     this.#remotePullRetryAfter.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,7 +613,10 @@ var CloudflareSFUClient = class {
     }
   }
   stop() {
-    if (this.#stopped) return;
+    if (this.#stopped) {
+      void this.#retireOwnedPublications();
+      return;
+    }
     this.#stopped = true;
     this.#subscribedPublicationIds.clear();
     this.#generation++;
@@ -534,12 +626,14 @@ var CloudflareSFUClient = class {
     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,43 +643,32 @@ 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}`;
-    }
+  async #enablePreparedTrack(state) {
+    const generation = this.#generation;
     state.desiredEnabled = true;
     state.track.enabled = true;
-    const generation = this.#generation;
     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.#publishPreparedTracks([state], generation);
       if (this.#remoteRecoveryGeneration !== generation) this.#replacementAttemptedGeneration = null;
     } catch (error) {
-      state.desiredEnabled = false;
-      state.enabled = false;
-      state.track.enabled = false;
+      if (generation === this.#generation) {
+        this.#pauseLocalSource(state.source);
+        await this.#retireOwnedPublications().catch(() => {
+        });
+      }
       throw error;
     }
   }
@@ -595,36 +678,39 @@ var CloudflareSFUClient = class {
     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);
+          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);
@@ -634,9 +720,9 @@ var CloudflareSFUClient = class {
     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);
     }
+    void this.#retireOwnedPublications();
   }
   async #publishPreparedTracksSerialized(states, generation, connection, connectionId) {
     this.#requireGeneration(generation);
@@ -646,28 +732,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, 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 +774,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 +788,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 +798,44 @@ var CloudflareSFUClient = class {
         source: state.source
       })
     );
-    const response = await (() => this.#requireTransport().addTracks({ connectionId, ...providerDescription(requireDescription(offer)), tracks }))();
+    const response = await this.#signal(() => this.#requireTransport().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);
+      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 {
@@ -913,7 +1000,7 @@ 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.#requireTransport().addTracks({ connectionId, tracks: requested, allowPartialRemoteTracks: true }), { generation, connectionId });
         this.#requireGeneration(generation);
         this.#recordRemotePullErrors(publications, response.trackErrors ?? []);
         const responseTracks = response.tracks ?? [];
@@ -958,13 +1045,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 +1064,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);
@@ -1115,10 +1202,9 @@ 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;
@@ -1190,8 +1276,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 +1355,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 +1374,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 +1485,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,22 +1524,36 @@ 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 response = await fetch(`${mediaPath}/${path}`, {
-        ...init,
-        signal,
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
-      });
-      if (!response.ok) {
-        throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
-          status: response.status,
-          retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600
+    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) => {
@@ -1533,7 +1646,6 @@ function describeMediaCaptureError(cause) {
 }
 
 export {
-  describeMediaCaptureError,
   CloudflareSFUError,
   parseCloudflareSFUPublicationID,
   requireDescription,
@@ -1542,6 +1654,10 @@ export {
   comparePublicationCursor,
   publicationKey,
   waitFor,
+  grantedMediaFromStream,
+  markMediaFailure,
+  classifyMediaFailure,
   CloudflareSFUClient,
-  createCloudflareSFUHTTPTransport
+  createCloudflareSFUHTTPTransport,
+  describeMediaCaptureError
 };