@q9labsai/chalk-client 4.1.11 → 4.1.13

package/dist/{chunk-FJXN6BVS.js → chunk-DV433YIW.js}

@@ -2,21 +2,21 @@ import {
   CloudflareRTKClient,
   CloudflareSFUClient,
   createCloudflareSFUHTTPTransport
-} from "./chunk-C4BIONCP.js";
+} from "./chunk-S5OUHFGC.js";
 import {
   AccessGrantError,
   requireParsedAccessGrant,
   validEpisodeDiagnosticCredential
-} from "./chunk-JPNE4K2L.js";
+} from "./chunk-EBACU63B.js";
+import {
+  createTraceContext,
+  parseTraceparent
+} from "./chunk-NKOKY2AE.js";
 import {
   createBrowserSyncLifecycle,
   createBrowserWebSocketFactory,
   createV1SyncClient
 } from "./chunk-5VXGLI3T.js";
-import {
-  createTraceContext,
-  parseTraceparent
-} from "./chunk-QVHR3RMB.js";
 
 // src/access/manager.ts
 import { Clock, Context, Data, Effect, Layer, SynchronizedRef } from "effect";
@@ -885,6 +885,7 @@ var ChalkWhiteboardV1Client = class {
   #options;
   #store;
   #listeners = /* @__PURE__ */ new Set();
+  #summaryListeners = /* @__PURE__ */ new Set();
   #operations = /* @__PURE__ */ new Map();
   #reservedOperationIds = /* @__PURE__ */ new Set();
   #awaitingOperationIds = /* @__PURE__ */ new Set();
@@ -989,6 +990,11 @@ var ChalkWhiteboardV1Client = class {
     if (this.#snapshots.size === 0 && !this.#waitingForOperations) void this.#requestSnapshot().catch(() => void 0);
     return () => this.#listeners.delete(listener);
   }
+  subscribeSummary(listener) {
+    this.#summaryListeners.add(listener);
+    this.#notifySummaryListener(listener, this.#summary());
+    return () => this.#summaryListeners.delete(listener);
+  }
   submitUpdate(input) {
     this.#assertLive("submit_update");
     if (!this.#canDraw || !this.#capabilities.includes("drawWhiteboard")) {
@@ -1480,7 +1486,15 @@ var ChalkWhiteboardV1Client = class {
   #publishSummary(status, summaryError) {
     this.#summaryStatus = status;
     this.#summaryError = summaryError;
-    const summary = {
+    const summary = this.#summary();
+    try {
+      this.#options.onSummary?.(summary);
+    } catch {
+    }
+    for (const listener of this.#summaryListeners) this.#notifySummaryListener(listener, summary);
+  }
+  #summary() {
+    return {
       status: this.#summaryStatus,
       sceneId: this.#sceneId,
       revision: this.#revision,
@@ -1490,8 +1504,10 @@ var ChalkWhiteboardV1Client = class {
       presenting: this.#presenting,
       error: this.#summaryError
     };
+  }
+  #notifySummaryListener(listener, summary) {
     try {
-      this.#options.onSummary?.(summary);
+      listener(summary);
     } catch {
     }
   }
@@ -1739,9 +1755,15 @@ function createMediaClient(apiBaseURL, input) {
     );
   }
   const { subject } = input.access;
+  const replaceMediaConnection = input.replaceMediaConnection;
   const client = new CloudflareSFUClient({
     bootstrap: input.access.media.clientPayload,
     participantId: subject.participantId,
+    replaceMediaConnection: replaceMediaConnection ? async () => {
+      const replacement = await replaceMediaConnection();
+      if (replacement.provider !== "cloudflare_sfu") throw new TypeError("The Cloudflare SFU adapter requires a Cloudflare SFU access grant");
+      return replacement.clientPayload;
+    } : void 0,
     transport: createCloudflareSFUHTTPTransport({
       apiBaseURL,
       credential: input.credential,
@@ -1751,6 +1773,7 @@ function createMediaClient(apiBaseURL, input) {
       participantId: subject.participantId
     }),
     onError: input.onFailure,
+    ...input.recordRtcSummary ? { onRtcSummary: input.recordRtcSummary } : {},
     onScreenEnded: input.onScreenEnded
   });
   return createSFUConnectionMediaClient(client);
@@ -2135,6 +2158,8 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
             try: () => platform.createMediaClient({
               access: grant,
               credential: () => toPromise(access.getMediaToken()),
+              replaceMediaConnection: () => toPromise(access.refresh("media_recovery", true)).then((replacement) => replacement.media),
+              ...options.recordRtcSummary ? { recordRtcSummary: options.recordRtcSummary } : {},
               onFailure: () => enqueueBackground(handleMediaFailure()),
               onScreenEnded: () => enqueueBackground(notifyScreenEnded())
             }),
@@ -3480,7 +3505,8 @@ var MediaControllerRuntime = class {
     if (isAccessInvalid2(input.cause)) return Effect5.fail(input.cause);
     input.restoreIntent?.();
     const rollback = input.track ? this.#discardCaptured(input.source, input.track, input.media, input.prepared) : input.fallback;
-    const failure2 = isPermissionDenied(input.cause) ? captureError(input.cause, input.action, input.permissionMessage) : input.cause;
+    const captureWasUnavailable = input.action === "startScreenShare" && !input.prepared && input.track === null;
+    const failure2 = isPermissionDenied(input.cause) || captureWasUnavailable ? captureError(input.cause, input.action, input.permissionMessage) : input.cause;
     return rollback.pipe(Effect5.andThen(Effect5.sync(() => this.#publish())), Effect5.andThen(Effect5.fail(failure2)));
   }
   #assertActivePorts(ports, action) {
@@ -3663,7 +3689,7 @@ function sameDeviceList(left, right) {
 }
 function captureError(cause, action, permissionMessage) {
   if (isPermissionDenied(cause)) return new ConnectionError({ code: "permission_denied", action, recoverable: true, message: permissionMessage }, { cause });
-  return new ConnectionError({ code: "unsupported_environment", action, recoverable: false, message: "Media capture is unavailable" }, { cause });
+  return new ConnectionError({ code: "unsupported_environment", action, recoverable: false, message: action === "startScreenShare" ? "Screen sharing is unavailable in this browser." : "Media capture is unavailable" }, { cause });
 }
 function isPermissionDenied(cause) {
   return cause instanceof DOMException && (cause.name === "NotAllowedError" || cause.name === "SecurityError");
@@ -3893,16 +3919,24 @@ function participantPresence(participantId, presence) {
   return Object.freeze({ state: item.state, speaking: item.speaking, activeSpeaker: item.activeSpeaker });
 }
 function sameParticipants(left, right) {
-  return sameArray(
-    left.roster,
-    right.roster,
-    (current, next) => current.participantId === next.participantId && current.displayName === next.displayName && current.role === next.role && current.handRaised === next.handRaised && sameValues(current.eligibleRoles, next.eligibleRoles) && sameValues(current.capabilities, next.capabilities) && current.media.microphone === next.media.microphone && current.media.camera === next.media.camera && current.media.screenShare === next.media.screenShare && current.presence.state === next.presence.state && current.presence.speaking === next.presence.speaking && current.presence.activeSpeaker === next.presence.activeSpeaker
-  ) && sameArray(
+  return sameArray(left.roster, right.roster, sameParticipant) && sameArray(
     left.admissionQueue,
     right.admissionQueue,
     (current, next) => current.requestId === next.requestId && current.participantId === next.participantId && current.displayName === next.displayName && current.initialRole === next.initialRole && current.expiresAt === next.expiresAt && sameValues(current.eligibleRoles, next.eligibleRoles)
   );
 }
+function sameParticipant(left, right) {
+  return sameParticipantProfile(left, right) && sameParticipantMedia(left, right) && sameParticipantPresence(left, right);
+}
+function sameParticipantProfile(left, right) {
+  return left.participantId === right.participantId && left.displayName === right.displayName && left.role === right.role && left.handRaised === right.handRaised && sameValues(left.eligibleRoles, right.eligibleRoles) && sameValues(left.capabilities, right.capabilities);
+}
+function sameParticipantMedia(left, right) {
+  return left.media.microphone === right.media.microphone && left.media.camera === right.media.camera && left.media.screenShare === right.media.screenShare;
+}
+function sameParticipantPresence(left, right) {
+  return left.presence.state === right.presence.state && left.presence.speaking === right.presence.speaking && left.presence.activeSpeaker === right.presence.activeSpeaker;
+}
 function sameSelf(left, right) {
   return left.participantId === right.participantId && left.displayName === right.displayName && left.role === right.role && left.handRaised === right.handRaised && sameValues(left.capabilities, right.capabilities);
 }
@@ -4797,7 +4831,7 @@ var makeSpaceClientCoreLayer = (options, platform = {}) => {
     now: baseDependencies.clock.now,
     setTimeout: baseDependencies.clock.setTimeout,
     clearTimeout: baseDependencies.clock.clearTimeout,
-    release: { id: "chalk-client@4.1.11" }
+    release: { id: "chalk-client@4.1.13" }
   });
   const diagnosticSyncClients = /* @__PURE__ */ new Set();
   const dependencies = {
@@ -4818,6 +4852,7 @@ var makeSpaceClientCoreLayer = (options, platform = {}) => {
     initialMicrophoneEnabled: platform.initialMicrophoneEnabled,
     initialCameraEnabled: platform.initialCameraEnabled,
     telemetry: platform.telemetry,
+    recordRtcSummary: platform.recordRtcSummary,
     dependencies,
     diagnostics: {
       onEvent: (event) => {
@@ -4861,7 +4896,6 @@ var SpaceClientCore = class {
   #previous;
   #unsubscribeConnection = null;
   #unsubscribeStore = null;
-  #unsupportedReported = false;
   #leaveOperation;
   #participantJoinOperation;
   #syncConnectOperation;
@@ -4998,11 +5032,6 @@ var SpaceClientCore = class {
   #publishConnectionDiagnostics() {
     const snapshot = this.#connection.getSnapshot();
     if (!this.#episodeDiagnostics || snapshot.state !== "live") return;
-    if (!this.#unsupportedReported) {
-      this.#unsupportedReported = true;
-      const unsupported = this.#episodeDiagnostics.startOperation("whiteboard.unsupported");
-      unsupported?.succeed({ status: "unsupported" });
-    }
     if (!this.#participantJoinOperation) {
       this.#participantJoinOperation = this.#episodeDiagnostics.startOperation("participant.join");
       this.#participantJoinOperation?.succeed({ status: "live" });

package/dist/{chunk-JPNE4K2L.js → chunk-EBACU63B.js}

@@ -1,6 +1,6 @@
 import {
   journeyHeaders
-} from "./chunk-QVHR3RMB.js";
+} from "./chunk-NKOKY2AE.js";
 
 // src/generated/schemas.ts
 import { Schema, SchemaGetter } from "effect";
@@ -757,7 +757,8 @@ var RecordingReservationSchema = Schema.Struct({
   updated_at: DateTimeStringSchema
 });
 var RefreshSpacePublicInviteAccessRequestSchema = Schema.Struct({
-  media_proof: Schema.String.check(Schema.isMinLength(1))
+  media_proof: Schema.String.check(Schema.isMinLength(1)),
+  replace_media_connection: Schema.Boolean
 });
 var RegionsSchema = Schema.Struct({
   regions: Schema.Array(

package/dist/{chunk-DFLTEYWX.js → chunk-IYRVIFWN.js}

@@ -1,7 +1,7 @@
 import {
   createChalkEffectClient,
   parseAccessGrant
-} from "./chunk-JPNE4K2L.js";
+} from "./chunk-EBACU63B.js";
 
 // src/public-invites/client.ts
 import { Effect } from "effect";
@@ -59,7 +59,7 @@ function createChalkPublicClient(options) {
     const response = await Effect.runPromise(
       client.spaces.refreshSpacePublicInviteAccess({
         headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle },
-        payload: { media_proof: required(normalized.mediaProof, "mediaProof") }
+        payload: { media_proof: required(normalized.mediaProof, "mediaProof"), replace_media_connection: normalized.replaceMediaConnection ?? false }
       })
     );
     return parseAccessGrant(response);
@@ -109,7 +109,7 @@ function arrivalReference(reference) {
   return { arrivalHandle: required(reference.arrivalHandle, "arrivalHandle"), guestCredential: reference.guestCredential };
 }
 function refreshInput(input, arrival) {
-  const values = typeof input === "string" ? { arrivalHandle: arrival?.arrivalHandle, guestCredential: arrival?.guestCredential, mediaProof: input } : { arrivalHandle: input.arrivalHandle ?? arrival?.arrivalHandle, guestCredential: input.guestCredential ?? arrival?.guestCredential, mediaProof: input.mediaProof };
+  const values = typeof input === "string" ? { arrivalHandle: arrival?.arrivalHandle, guestCredential: arrival?.guestCredential, mediaProof: input } : { arrivalHandle: input.arrivalHandle ?? arrival?.arrivalHandle, guestCredential: input.guestCredential ?? arrival?.guestCredential, mediaProof: input.mediaProof, replaceMediaConnection: input.replaceMediaConnection };
   return {
     ...values,
     arrivalHandle: required(values.arrivalHandle ?? "", "arrivalHandle")

package/dist/{chunk-QVHR3RMB.js → chunk-NKOKY2AE.js}

@@ -22,6 +22,8 @@ var TELEMETRY_BUILT_IN_ATTRIBUTE_KEYS = [
   "connection_state",
   "ice_connection_state",
   "signaling_state",
+  "dtls_state",
+  "selected_candidate_pair_state",
   "bytes_received",
   "bytes_sent",
   "frames_dropped",
@@ -615,7 +617,9 @@ function summarizeRtcStats(stats) {
     packetsReceived: 0,
     packetsSent: 0,
     roundTripTimeSamples: [],
-    transportEntries: 0
+    transportEntries: 0,
+    dtlsStates: [],
+    selectedCandidatePairStates: []
   };
   for (const stat of stats) {
     statHandlers[stat.type ?? ""]?.(accumulator, stat);
@@ -634,6 +638,8 @@ function rtcSummaryAttributes(connection, stats) {
     packets_received: summary.packetsReceived,
     packets_sent: summary.packetsSent,
     transport_entries: summary.transportEntries,
+    ...summary.dtlsState !== void 0 ? { dtls_state: summary.dtlsState } : {},
+    ...summary.selectedCandidatePairState !== void 0 ? { selected_candidate_pair_state: summary.selectedCandidatePairState } : {},
     ...connection.connectionState !== void 0 ? { connection_state: connection.connectionState } : {},
     ...connection.iceConnectionState !== void 0 ? { ice_connection_state: connection.iceConnectionState } : {},
     ...summary.jitterMs !== void 0 ? { jitter_ms: summary.jitterMs } : {},
@@ -663,6 +669,13 @@ function accumulateOutbound(accumulator, stat) {
 function accumulateTransport(accumulator, stat) {
   accumulator.transportEntries += 1;
   appendFinite(accumulator.roundTripTimeSamples, stat.roundTripTime);
+  appendRtcState(accumulator.dtlsStates, stat.dtlsState, ["new", "connecting", "connected", "closed", "failed"]);
+  if (stat.type === "candidate-pair" && (stat.selected === true || stat.nominated === true)) {
+    appendRtcState(accumulator.selectedCandidatePairStates, stat.state, ["frozen", "waiting", "in-progress", "failed", "succeeded"]);
+  }
+}
+function appendRtcState(states, value, allowed) {
+  if (value !== void 0 && allowed.includes(value) && !states.includes(value)) states.push(value);
 }
 function appendFinite(samples, value) {
   if (isFiniteNumber(value)) samples.push(value);
@@ -670,6 +683,8 @@ function appendFinite(samples, value) {
 function finalizeAccumulator(accumulator) {
   const jitterMs = averageMilliseconds(accumulator.jitterSamples);
   const roundTripTimeMs = averageMilliseconds(accumulator.roundTripTimeSamples);
+  const dtlsState = lastValue(accumulator.dtlsStates);
+  const selectedCandidatePairState = lastValue(accumulator.selectedCandidatePairStates);
   return {
     bytesReceived: accumulator.bytesReceived,
     bytesSent: accumulator.bytesSent,
@@ -680,10 +695,15 @@ function finalizeAccumulator(accumulator) {
     packetsReceived: accumulator.packetsReceived,
     packetsSent: accumulator.packetsSent,
     transportEntries: accumulator.transportEntries,
+    ...dtlsState !== void 0 ? { dtlsState } : {},
+    ...selectedCandidatePairState !== void 0 ? { selectedCandidatePairState } : {},
     ...jitterMs !== void 0 ? { jitterMs } : {},
     ...roundTripTimeMs !== void 0 ? { roundTripTimeMs } : {}
   };
 }
+function lastValue(values) {
+  return values.at(-1);
+}
 function averageMilliseconds(samples) {
   if (samples.length === 0) return void 0;
   return Math.round(samples.reduce((total, sample) => total + sample, 0) / samples.length * 1e3);

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

@@ -25,12 +25,14 @@ function resolveMediaTarget(participantId, stopped, tracks, target) {
 
 // src/media/types.ts
 var CloudflareSFUError = class extends Error {
-  constructor(message, code) {
+  constructor(message, code, options = {}) {
     super(message);
     this.code = code;
+    this.options = options;
     this.name = "CloudflareSFUError";
   }
   code;
+  options;
 };
 
 // src/media/tracks.ts
@@ -138,10 +140,12 @@ var CloudflareSFUClient = class {
   #localListeners = /* @__PURE__ */ new Set();
   #onError;
   #onRemoteTrack;
+  #onRtcSummary;
   #onScreenEnded;
   #participantId;
   #peerConnectionFactory;
   #pollIntervalMs;
+  #replaceMediaConnection;
   #remoteListeners = /* @__PURE__ */ new Set();
   #snapshotListeners = /* @__PURE__ */ new Set();
   #localTracks = /* @__PURE__ */ new Map();
@@ -149,8 +153,11 @@ var CloudflareSFUClient = class {
   #remoteTracks = /* @__PURE__ */ new Map();
   #bootstrap;
   #connection;
+  #connectionEpoch = 0;
   #cursor = null;
   #generation = 0;
+  #negotiatedGeneration = null;
+  #replacementAttemptedGeneration = null;
   #polling = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
@@ -164,8 +171,10 @@ var CloudflareSFUClient = class {
     this.#bootstrap = options.bootstrap;
     this.#transport = options.transport;
     this.#pollIntervalMs = options.pollIntervalMs ?? 1e3;
+    this.#replaceMediaConnection = options.replaceMediaConnection;
     this.#onError = options.onError;
     this.#onRemoteTrack = options.onRemoteTrack;
+    this.#onRtcSummary = options.onRtcSummary;
     this.#onScreenEnded = options.onScreenEnded;
     this.#peerConnectionFactory = options.peerConnectionFactory;
     this.#connection = this.#createPeerConnection(options.bootstrap);
@@ -176,7 +185,7 @@ var CloudflareSFUClient = class {
       remoteTracks: EMPTY_REMOTE,
       failure: null
     });
-    this.#observeConnection(this.#connection, this.#generation);
+    this.#observeConnection(this.#connection, this.#generation, this.#connectionEpoch);
   }
   getSnapshot() {
     return this.#snapshot;
@@ -276,16 +285,19 @@ var CloudflareSFUClient = class {
     const options = "connectionId" in input ? { bootstrap: input } : input;
     validateBootstrap(options.bootstrap);
     const generation = ++this.#generation;
+    const connectionEpoch = ++this.#connectionEpoch;
     this.#polling = false;
     this.#clearPoll();
     this.#disposeConnection(false);
     this.#reusableLocalTransceivers.clear();
     this.#clearRemoteTracks();
     this.#cursor = null;
+    this.#negotiatedGeneration = null;
+    this.#replacementAttemptedGeneration = null;
     this.#bootstrap = options.bootstrap;
     if (options.transport) this.#transport = options.transport;
     this.#connection = this.#createPeerConnection(options.bootstrap);
-    this.#observeConnection(this.#connection, generation);
+    this.#observeConnection(this.#connection, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
       state.transceiver = null;
       state.enabled = false;
@@ -310,6 +322,7 @@ var CloudflareSFUClient = class {
     if (this.#stopped) return;
     this.#stopped = true;
     this.#generation++;
+    this.#connectionEpoch++;
     this.#clearPoll();
     this.#polling = false;
     this.#disposeConnection(true);
@@ -367,9 +380,21 @@ var CloudflareSFUClient = class {
   }
   async #publishPreparedTracks(states, generation) {
     if (states.length === 0) return;
-    const connection = this.#connection;
-    const bootstrap = this.#bootstrap;
-    await this.#serializeSDP(() => this.#publishPreparedTracksSerialized(states, generation, connection, bootstrap.connectionId));
+    await this.#serializeSDP(async () => {
+      await this.#replaceDormantConnectionBeforeNegotiation(generation);
+      try {
+        await this.#publishPreparedTracksSerialized(states, 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
+        );
+      }
+    });
   }
   async #publishPreparedTracksSerialized(states, generation, connection, connectionId) {
     this.#requireGeneration(generation);
@@ -382,6 +407,7 @@ var CloudflareSFUClient = class {
       const response = 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.#publishSnapshot();
       this.#emitLocal();
@@ -458,6 +484,7 @@ var CloudflareSFUClient = class {
     const desired = desiredRemotePublications(authoritative.publications, this.#participantId);
     const toPull = [...desired].filter(([key, publication]) => this.#remoteTracks.get(key)?.publicationId !== publication.publicationId).map(([, publication]) => publication);
     const pulled = await this.#pull(toPull, generation);
+    if (pulled === null) return;
     this.#requireGeneration(generation);
     const next = reconcileRemoteTracks(desired, pulled, this.#remoteTracks);
     stopReplacedRemoteTracks(this.#remoteTracks, next, this.#reportError.bind(this));
@@ -470,9 +497,9 @@ var CloudflareSFUClient = class {
   }
   async #pull(publications, generation) {
     if (publications.length === 0) return [];
-    const connection = this.#connection;
-    const connectionId = this.#bootstrap.connectionId;
     return this.#serializeSDP(async () => {
+      const connection = this.#connection;
+      const connectionId = this.#bootstrap.connectionId;
       const requested = publications.map((publication) => {
         const reference = parseCloudflareSFUPublicationID(publication.publicationId);
         return { location: "remote", sessionId: reference.connectionId, trackName: reference.trackName };
@@ -489,6 +516,7 @@ var CloudflareSFUClient = class {
         const responseTracks = response.tracks ?? [];
         await this.#completeRenegotiation(response, connection, connectionId, generation);
         await this.#waitForConnection(connection, generation);
+        this.#negotiatedGeneration = generation;
         await waitFor(() => responseTracks.every((track) => track.mid !== void 0 && received.has(track.mid)), 5e3);
         this.#requireGeneration(generation);
         return publications.map((publication, index) => {
@@ -532,15 +560,78 @@ var CloudflareSFUClient = class {
       "Timed out waiting for the Cloudflare SFU peer connection"
     );
   }
-  #observeConnection(connection, generation) {
+  #observeConnection(connection, generation, connectionEpoch) {
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+      connection.removeEventListener("connectionstatechange", capture);
+      connection.removeEventListener("iceconnectionstatechange", capture);
+      connection.removeEventListener("signalingstatechange", capture);
+    };
     const observe = () => {
-      if (generation !== this.#generation || this.#stopped) return;
+      if (disposed || generation !== this.#generation || connectionEpoch !== this.#connectionEpoch || this.#stopped) return;
       const observation = observeConnectionState(connection.connectionState, connection.iceConnectionState, this.#started);
       if (observation) this.#publishSnapshot(observation.phase, observation.failure);
       else this.#publishSnapshot();
     };
-    connection.addEventListener("connectionstatechange", observe);
-    connection.addEventListener("iceconnectionstatechange", observe);
+    const capture = () => {
+      if (disposed || generation !== this.#generation || connectionEpoch !== this.#connectionEpoch || this.#stopped) return;
+      observe();
+      const recorder = this.#onRtcSummary;
+      if (recorder) {
+        let stats;
+        try {
+          stats = Promise.resolve(connection.getStats());
+        } catch {
+          stats = Promise.reject(new Error("RTC stats are unavailable"));
+        }
+        void stats.then((report) => {
+          if (disposed || generation !== this.#generation || connectionEpoch !== this.#connectionEpoch || this.#stopped) return;
+          recorder(rtcConnectionState(connection), rtcStats(report));
+        }).catch(() => void 0);
+      }
+      if (connection.connectionState === "closed") dispose();
+    };
+    connection.addEventListener("connectionstatechange", capture);
+    connection.addEventListener("iceconnectionstatechange", capture);
+    connection.addEventListener("signalingstatechange", capture);
+    capture();
+  }
+  async #replaceDormantConnectionBeforeNegotiation(generation) {
+    if (!this.#started || this.#negotiatedGeneration === generation || this.#replacementAttemptedGeneration === generation || !this.#replaceMediaConnection) return;
+    await this.#replaceMediaConnectionForRecovery(generation);
+  }
+  async #replaceMediaConnectionForRecovery(generation) {
+    this.#requireGeneration(generation);
+    if (!this.#replaceMediaConnection || this.#replacementAttemptedGeneration === generation) {
+      throw new CloudflareSFUError("A fresh Cloudflare SFU connection is unavailable", "signaling_failed");
+    }
+    this.#replacementAttemptedGeneration = generation;
+    const bootstrap = await this.#replaceMediaConnection();
+    this.#requireGeneration(generation);
+    validateBootstrap(bootstrap);
+    if (bootstrap.connectionId === this.#bootstrap.connectionId) {
+      throw new CloudflareSFUError("Participant access did not replace the Cloudflare SFU connection", "signaling_failed");
+    }
+    const connectionEpoch = ++this.#connectionEpoch;
+    this.#disposeConnection(false);
+    this.#reusableLocalTransceivers.clear();
+    this.#clearRemoteTracks();
+    this.#cursor = null;
+    this.#bootstrap = bootstrap;
+    this.#connection = this.#createPeerConnection(bootstrap);
+    this.#negotiatedGeneration = null;
+    this.#observeConnection(this.#connection, generation, connectionEpoch);
+    for (const state of this.#localTracks.values()) {
+      state.transceiver = null;
+      state.enabled = false;
+      state.providerPublicationId = null;
+    }
+    this.#setPhase("recovering", null);
+  }
+  #isRetryableConnectionFailure(error) {
+    return error instanceof CloudflareSFUError && error.code === "signaling_failed" && error.options.retryableConnection === true;
   }
   #createPeerConnection(bootstrap) {
     const create = this.#peerConnectionFactory ?? ((configuration) => new RTCPeerConnection(configuration));
@@ -679,6 +770,71 @@ function validateClientOptions(options) {
     throw new CloudflareSFUError("Cloudflare SFU polling interval is invalid", "invalid_bootstrap");
   }
 }
+function rtcConnectionState(connection) {
+  return {
+    connectionState: connection.connectionState,
+    iceConnectionState: connection.iceConnectionState,
+    signalingState: connection.signalingState
+  };
+}
+function rtcStats(report) {
+  const entries = [];
+  report.forEach((entry) => {
+    if (typeof entry.type !== "string") return;
+    entries.push({ type: entry.type, ...rtcTrafficStats(entry), ...rtcQualityStats(entry), ...rtcTransportStats(entry) });
+  });
+  return entries;
+}
+function rtcTrafficStats(entry) {
+  const bytesReceived = rtcNumber(entry, "bytesReceived");
+  const bytesSent = rtcNumber(entry, "bytesSent");
+  const packetsReceived = rtcNumber(entry, "packetsReceived");
+  const packetsSent = rtcNumber(entry, "packetsSent");
+  return {
+    ...bytesReceived !== void 0 ? { bytesReceived } : {},
+    ...bytesSent !== void 0 ? { bytesSent } : {},
+    ...packetsReceived !== void 0 ? { packetsReceived } : {},
+    ...packetsSent !== void 0 ? { packetsSent } : {}
+  };
+}
+function rtcQualityStats(entry) {
+  const kind = rtcString(entry, "kind");
+  const framesDropped = rtcNumber(entry, "framesDropped");
+  const jitter = rtcNumber(entry, "jitter");
+  const packetsLost = rtcNumber(entry, "packetsLost");
+  const roundTripTime = rtcNumber(entry, "roundTripTime");
+  return {
+    ...kind !== void 0 ? { kind } : {},
+    ...framesDropped !== void 0 ? { framesDropped } : {},
+    ...jitter !== void 0 ? { jitter } : {},
+    ...packetsLost !== void 0 ? { packetsLost } : {},
+    ...roundTripTime !== void 0 ? { roundTripTime } : {}
+  };
+}
+function rtcTransportStats(entry) {
+  const state = rtcString(entry, "state");
+  const selected = rtcBoolean(entry, "selected");
+  const nominated = rtcBoolean(entry, "nominated");
+  const dtlsState = rtcString(entry, "dtlsState");
+  return {
+    ...state !== void 0 ? { state } : {},
+    ...selected !== void 0 ? { selected } : {},
+    ...nominated !== void 0 ? { nominated } : {},
+    ...dtlsState !== void 0 ? { dtlsState } : {}
+  };
+}
+function rtcString(value, property) {
+  const candidate = Reflect.get(value, property);
+  return typeof candidate === "string" ? candidate : void 0;
+}
+function rtcNumber(value, property) {
+  const candidate = Reflect.get(value, property);
+  return typeof candidate === "number" ? candidate : void 0;
+}
+function rtcBoolean(value, property) {
+  const candidate = Reflect.get(value, property);
+  return typeof candidate === "boolean" ? candidate : void 0;
+}
 function validateBootstrap(bootstrap) {
   if (!bootstrap.connectionId.trim() || !bootstrap.stunServer.trim()) throw new CloudflareSFUError("Cloudflare SFU bootstrap is incomplete", "invalid_bootstrap");
 }
@@ -771,7 +927,12 @@ function createCloudflareSFUHTTPTransport(options) {
       ...init,
       headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
     });
-    if (!response.ok) throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed");
+    if (!response.ok) {
+      throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
+        status: response.status,
+        retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600
+      });
+    }
     return await response.json();
   };
   return {

package/dist/client.d.ts

@@ -6560,6 +6560,7 @@ export declare const createChalkEffectClient: (options: ChalkEffectClientOptions
         }>, never, never>>, never, never>, never, never>;
         readonly refreshSpacePublicInviteAccess: HttpApiClient.Client.Method<import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"refreshSpacePublicInviteAccess", "POST", "/v1/public/space-invite-arrival/access-grants", never, never, import("effect/Schema").toCodecJson<import("effect/Schema").Struct<{
             readonly media_proof: import("effect/Schema").String;
+            readonly replace_media_connection: import("effect/Schema").Boolean;
         }>>, import("effect/Schema").toCodecStringTree<import("effect/Schema").Struct<{
             readonly "X-Chalk-Arrival-Handle": import("effect/Schema").String;
         }>>, import("effect/Schema").toCodecJson<import("effect/Schema").Struct<{