@q9labsai/chalk-client 4.1.16 → 4.1.17

package/README.md

@@ -21,14 +21,19 @@ Your backend mints an `AccessGrant` with the server SDK. See the [web quickstart
 client unchanged: it is an opaque signed envelope, so application code does
 not construct or inspect it. `getAccess` may resolve with the fetch `Response`
 that carries the grant or with its decoded JSON; the client validates it and
-fails the join on a non-OK response or a malformed body.
+classifies non-OK responses and rejects malformed bodies.
 
 ```ts
 import { createSpaceClient } from "@q9labsai/chalk-client";
 
 const client = createSpaceClient({
   space: "design-review",
-  getAccess: ({ space, reason }) => fetch(`/api/chalk/spaces/${space}/access?reason=${reason}`),
+  getAccess: (request) =>
+    fetch("/api/chalk/access", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(request),
+    }),
 });
 
 await client.join({
@@ -41,7 +46,13 @@ await client.join({
 `getAccess` receives `reason: "join" | "refresh" | "retry"`. `Connection`
 uses it for Entrance freshness, scheduled refresh, wake revalidation, and one
 refresh-and-retry after an access rejection. Keep the callback available for
-the full lifetime of the client.
+the full lifetime of the client. Forward the request unchanged to your backend,
+then pass it as the final `participants.issueAccess` argument alongside the
+server-only state from `getAccessRefreshState`. Chalk selects media replacement
+when recovery needs it and retains healthy media for ordinary refresh and Sync
+recovery. The quickstart shows the endpoint call; no conditional is needed.
+
+HTTP 408, 425, 429, and 5xx responses, network failures, and provider timeouts are `access.unavailable` (recoverable). Scheduled refresh retries these failures while retaining the current grant. Other non-OK responses (including 401 and 403) and malformed grants are `access.invalid`. Initial join does not automatically retry unavailable Access: show the failure and let the person check their network and try again. Return the `Response` unchanged so Chalk can classify its status; throwing a generic error for every non-OK response loses that distinction.
 
 ## Snapshot store
 
@@ -184,6 +195,36 @@ Events are `participantJoined`, `participantLeft`, `episodeEnded`,
 stable codes such as `access.invalid`, `episode.ended`, and
 `chat.payload_invalid`.
 
+### Join capture errors
+
+`join()` requests the microphone and camera by default. If both work, capture
+still uses one request. If a requested device fails, Chalk tries the requested
+devices separately and enters with the working devices; the unavailable device
+is off. This also applies to the React entrance, including a device that works
+in preview but fails at entry. A capture warning does not reject `join()`.
+
+Listen to `client.on("error", ({ error }) => ...)` (React: `onError`) for one
+recoverable warning, also available as `connection.lastError`. Its message names
+the failing device or devices. React displays a dismissible warning after entry.
+
+| Capture problem                     | Public error code                 |
+| ----------------------------------- | --------------------------------- |
+| Missing microphone, camera, or both | `media.device_not_found`          |
+| Busy microphone or camera           | `media.device_busy`               |
+| Denied microphone, camera, or both  | `media.permission_denied`         |
+| Unavailable device constraint       | `media.device_constraint_invalid` |
+| Other device capture failure        | `media.capture_failed`            |
+
+When both devices fail for different reasons, the warning uses the microphone's
+code and names both devices. Integrations must allow these codes and must not
+treat a recoverable capture warning as failed entry. Participants can enable a
+device later through `client.media` after resolving the problem.
+
+Only an unavailable capture API or an insecure browser context fails capture
+as nonrecoverable `environment.unsupported`. Joining with both devices explicitly
+off does not require capture. Access, Sync, or media transport failures can still
+reject `join()` independently of capture.
+
 ## Journey telemetry
 
 Client telemetry is opt-in. Start a `space.join` journey when a Participant

package/dist/access/grant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/access/grant.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grant.d.ts","sourceRoot":"","sources":["../../src/access/grant.ts"],"names":[],"mappings":"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"}

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

@@ -1,10 +1,10 @@
-import {
-  journeyHeaders
-} from "./chunk-HW5TTZL2.js";
 import {
   recordReconnect,
   traceReconnect
 } from "./chunk-RCDXIDCN.js";
+import {
+  journeyHeaders
+} from "./chunk-HW5TTZL2.js";
 
 // src/media/camera-uplink.ts
 var CameraUplinkPolicy = class {
@@ -230,6 +230,8 @@ var CloudflareSFUClient = class {
   #replacementAttemptedGeneration = null;
   #polling = false;
   #pollAfterCurrent = false;
+  #pollFailures = 0;
+  #pollFailedPull = false;
   #pollTimer;
   #sdpTail = Promise.resolve();
   #snapshot;
@@ -332,25 +334,29 @@ var CloudflareSFUClient = class {
     if (!this.#started || this.#stopped || this.#polling) return;
     this.#polling = true;
     const generation = this.#generation;
+    this.#pollFailedPull = false;
     try {
       const transport = this.#requireTransport();
       const authoritative = await traceReconnect(this.#recordReconnect, "list_publications", () => transport.listPublications());
       this.#requireGeneration(generation);
       await this.#reconcileRemotePublications(authoritative, generation);
+      this.#requireGeneration(generation);
+      if (!this.#remotePullIncomplete) this.#pollFailures = 0;
     } catch (error) {
       if (generation === this.#generation && !this.#stopped) this.#reportError(error);
       throw error;
     } finally {
-      if (generation === this.#generation) {
-        this.#polling = false;
-        if (this.#pollAfterCurrent) {
-          this.#pollAfterCurrent = false;
-          this.#clearPoll();
-          this.#schedulePoll(0);
-        }
-      }
+      this.#finishPublicationPoll(generation);
     }
   }
+  #finishPublicationPoll(generation) {
+    if (generation !== this.#generation) return;
+    this.#polling = false;
+    if (!this.#pollAfterCurrent) return;
+    this.#pollAfterCurrent = false;
+    this.#clearPoll();
+    this.#schedulePoll(0);
+  }
   async setLocalPublicationTarget(target) {
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result") return resolved.result;
@@ -478,14 +484,12 @@ var CloudflareSFUClient = class {
     if (options.bootstrap.connectionId !== this.#bootstrap.connectionId) this.#started = false;
     this.#bootstrap = options.bootstrap;
     if (options.transport) this.#transport = options.transport;
-    this.#connection = this.#createPeerConnection(options.bootstrap);
-    this.#observeConnection(this.#connection, generation, connectionEpoch);
+    this.#rebuildPeerConnection(options.bootstrap, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
       state.transceiver = null;
       state.enabled = false;
     }
     const enabled = [...this.#localTracks.values()].filter((state) => state.desiredEnabled && state.track.readyState !== "ended");
-    this.#setPhase("recovering", null);
     await this.#activatePreparedTracks(enabled, generation);
   }
   async #activatePreparedTracks(states, generation) {
@@ -740,6 +744,7 @@ var CloudflareSFUClient = class {
     if (ordering === "stale" || ordering === "same" && !this.#remotePullIncomplete) return;
     const desired = this.#desiredRemotePublications(authoritative, cursor);
     const toPull = this.#pendingRemotePulls(desired);
+    this.#pollFailedPull = true;
     const pulled = await this.#pullWithRecovery(toPull, cursor, generation);
     if (pulled === null) return;
     this.#requireGeneration(generation);
@@ -1120,16 +1125,14 @@ var CloudflareSFUClient = class {
     this.#clearRemoteTracks();
     this.#cursor = null;
     this.#bootstrap = bootstrap;
-    this.#connection = this.#createPeerConnection(bootstrap);
+    this.#rebuildPeerConnection(bootstrap, generation, connectionEpoch);
     this.#retiredLocalConnection = null;
     this.#negotiatedGeneration = null;
-    this.#observeConnection(this.#connection, generation, connectionEpoch);
     for (const state of this.#localTracks.values()) {
       state.transceiver = null;
       state.enabled = false;
       state.providerPublicationId = null;
     }
-    this.#setPhase("recovering", null);
     this.remotePublicationsChanged();
   }
   async #republishPreparedTracksAfterRecovery(generation) {
@@ -1152,7 +1155,17 @@ var CloudflareSFUClient = class {
     const create = this.#peerConnectionFactory ?? ((configuration) => new RTCPeerConnection(configuration));
     return create({ iceServers: [{ urls: bootstrap.stunServer }], bundlePolicy: "max-bundle" });
   }
+  #rebuildPeerConnection(bootstrap, generation, connectionEpoch) {
+    try {
+      this.#connection = this.#createPeerConnection(bootstrap);
+      this.#observeConnection(this.#connection, generation, connectionEpoch);
+    } catch (error) {
+      this.#setFailure(error, "media_failed");
+      throw error;
+    }
+  }
   #disposeConnection(stopSenders) {
+    if (!stopSenders) this.#setPhase("recovering", null);
     this.#disposeConnectionObservation?.();
     this.#disposeConnectionObservation = void 0;
     if (stopSenders) {
@@ -1198,15 +1211,27 @@ var CloudflareSFUClient = class {
         this.#schedulePoll();
         return;
       }
+      let nextDelay = this.#pollIntervalMs;
       try {
         await this.refreshRemotePublications();
+        if (this.#remotePullIncomplete) nextDelay = this.#incompletePullDelay();
       } catch {
+        if (this.#pollFailedPull && this.#remotePullIncomplete) nextDelay = this.#incompletePullDelay();
+        else {
+          this.#pollFailures = Math.min(this.#pollFailures + 1, 6);
+          nextDelay = Math.min(this.#pollIntervalMs, (500 + Math.random() * 500) * 2 ** (this.#pollFailures - 1));
+        }
       } finally {
-        this.#schedulePoll(this.#remotePullIncomplete ? 750 : this.#pollIntervalMs);
+        this.#schedulePoll(nextDelay);
       }
     }, delayMs);
   }
+  #incompletePullDelay() {
+    this.#pollFailures = Math.min(this.#pollFailures + 1, 6);
+    return Math.min(this.#pollIntervalMs, 750 * 2 ** (this.#pollFailures - 1));
+  }
   #clearPoll() {
+    this.#pollFailures = 0;
     if (this.#pollTimer !== void 0) globalThis.clearTimeout(this.#pollTimer);
     this.#pollTimer = void 0;
   }
@@ -1571,12 +1596,14 @@ var CloudflareRTKClient = class {
   #clientFactory;
   #snapshotListeners = /* @__PURE__ */ new Set();
   #sourceOperations = /* @__PURE__ */ new Map();
+  #generationInvalidators = /* @__PURE__ */ new Set();
   #connection = null;
   #localTracks = /* @__PURE__ */ new Map();
   #connectionUnsubscribers = [];
   #participantUnsubscribers = /* @__PURE__ */ new Map();
   #snapshot;
   #stopped = false;
+  #generation = 0;
   #screenDisableRequested = false;
   #initialAuthToken;
   constructor(options) {
@@ -1613,16 +1640,22 @@ var CloudflareRTKClient = class {
   async clearPreparedLocalTrack(source) {
     const state = this.#localTracks.get(source);
     if (!state) return;
-    if (state.enabled) {
-      await this.#setSourceEnabled(state, false);
-    }
+    const connection = this.#connection;
     if (state.endedListener) state.track.removeEventListener("ended", state.endedListener);
     this.#localTracks.delete(source);
+    const actions = connection ? this.#sourceActions(state, connection) : null;
+    const cleanup = actions?.enabled && state.enabled ? this.#queueSourceOperation(source, () => connection === this.#connection ? actions.disable() : Promise.resolve()) : Promise.resolve();
     this.#publishSnapshot();
+    try {
+      await cleanup;
+    } catch (error) {
+      if (!isStaleGeneration(error)) throw error;
+    }
   }
   async start(localMedia) {
     if (this.#snapshot.connection.phase === "live") return;
     this.#requireStartable();
+    const generation = this.#advanceGeneration();
     this.#setPhase("connecting", null);
     try {
       const tracks = localMedia.getTracks().filter((track) => track.kind === "audio" || track.kind === "video");
@@ -1630,38 +1663,60 @@ var CloudflareRTKClient = class {
         const source = track.kind === "audio" ? "microphone" : "camera";
         if (!this.#localTracks.has(source)) this.#localTracks.set(source, { source, track, enabled: false, endedListener: null });
       }
-      await this.#openConnection(this.#initialAuthToken);
-      for (const state of this.#localTracks.values()) {
-        if (state.source === "microphone" || state.source === "camera") await this.#setSourceEnabled(state, true);
-      }
-      this.#setPhase("live", null);
+      if (!await this.#openConnection(this.#initialAuthToken, generation)) return;
+      await this.#restoreLocalTracks(generation, true);
     } catch (error) {
-      this.#setFailure(error);
-      this.#reportError(error);
+      this.#failCurrentGeneration(generation, error);
       throw error;
     }
   }
   async setLocalPublicationTarget(target) {
     const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
     if (resolved.kind === "result") return resolved.result;
-    const state = resolved.value;
-    const previous = this.#sourceOperations.get(target.source) ?? Promise.resolve();
-    const operation = previous.catch(() => void 0).then(async () => {
-      if (state.enabled === target.enabled) return "satisfied";
-      try {
-        await this.#setSourceEnabled(state, target.enabled);
-        return "confirmed";
-      } catch (error) {
-        this.#reportError(error);
-        return "retryable_failure";
-      }
+    const generation = this.#generation;
+    try {
+      return await this.#queueSourceOperation(target.source, () => this.#applyLocalTarget(target, generation));
+    } catch (error) {
+      return { outcome: "retryable_failure", errorCode: error instanceof CloudflareRTKError ? error.code : "media_failed" };
+    }
+  }
+  async #queueSourceOperation(source, apply) {
+    const previous = this.#sourceOperations.get(source) ?? Promise.resolve();
+    const generation = this.#generation;
+    let invalidate = () => {
+    };
+    const retired = new Promise((_resolve, reject) => {
+      invalidate = () => reject(new CloudflareRTKError("The media operation belongs to a retired connection", "stale_generation"));
+      this.#generationInvalidators.add(invalidate);
     });
-    this.#sourceOperations.set(target.source, operation);
+    const operation = Promise.race([
+      previous.catch(() => void 0).then(() => {
+        if (!this.#isCurrentGeneration(generation)) throw new CloudflareRTKError("The queued media operation belongs to a retired connection", "stale_generation");
+        return apply();
+      }),
+      retired
+    ]);
+    this.#sourceOperations.set(source, operation);
     try {
-      const outcome = await operation;
-      return { outcome, errorCode: outcome === "retryable_failure" ? "media_failed" : null };
+      return await operation;
     } finally {
-      if (this.#sourceOperations.get(target.source) === operation) this.#sourceOperations.delete(target.source);
+      this.#generationInvalidators.delete(invalidate);
+      if (this.#sourceOperations.get(source) === operation) this.#sourceOperations.delete(source);
+    }
+  }
+  async #applyLocalTarget(target, generation) {
+    if (!this.#isCurrentGeneration(generation)) return { outcome: "retryable_failure", errorCode: "stale_generation" };
+    const resolved = resolveMediaTarget(this.#participantId, this.#stopped, this.#localTracks, target);
+    if (resolved.kind === "result") return resolved.result;
+    const state = resolved.value;
+    try {
+      if (!this.#connection) throw new CloudflareRTKError("The RealtimeKit connection is recovering", "stale_generation");
+      if (state.enabled === target.enabled) return { outcome: "satisfied", errorCode: null };
+      await this.#setSourceEnabled(state, target.enabled);
+      return { outcome: "confirmed", errorCode: null };
+    } catch (error) {
+      this.#reportError(error);
+      return { outcome: "retryable_failure", errorCode: error instanceof CloudflareRTKError ? error.code : "media_failed" };
     }
   }
   observeLocalPublications(listener) {
@@ -1673,31 +1728,74 @@ var CloudflareRTKClient = class {
   async restart(input) {
     if (!isRTKAccess(input)) throw new CloudflareRTKError("The RealtimeKit adapter requires a Cloudflare RealtimeKit access grant", "invalid_client");
     if (this.#stopped) throw new CloudflareRTKError("The RealtimeKit media client has stopped", "media_stopped");
+    const generation = this.#advanceGeneration();
     this.#setPhase("recovering", null);
     try {
       await this.#closeConnection();
-      await this.#openConnection(input.clientPayload.token);
-      for (const state of this.#localTracks.values()) if (state.enabled) await this.#setSourceEnabled(state, true);
-      this.#setPhase("live", null);
+      if (!this.#isCurrentGeneration(generation)) return;
+      if (!await this.#openConnection(input.clientPayload.token, generation)) return;
+      await this.#restoreLocalTracks(generation, false);
     } catch (error) {
-      this.#setFailure(error);
-      this.#reportError(error);
+      this.#failCurrentGeneration(generation, error);
       throw error;
     }
   }
   stop() {
     if (this.#stopped) return;
     this.#stopped = true;
+    this.#advanceGeneration();
     const leave = this.#closeConnection();
     void leave.catch((error) => this.#reportError(error));
     for (const state of this.#localTracks.values()) if (state.endedListener) state.track.removeEventListener("ended", state.endedListener);
     this.#localTracks.clear();
     this.#setPhase("stopped", null);
   }
-  async #openConnection(authToken) {
-    this.#connection = await this.#clientFactory({ authToken, onError: (error) => this.#reportError(error) });
-    this.#bindConnection(this.#connection);
-    await this.#connection.join();
+  #isCurrentGeneration(generation) {
+    return !this.#stopped && generation === this.#generation;
+  }
+  #advanceGeneration() {
+    const generation = ++this.#generation;
+    this.#sourceOperations.clear();
+    for (const invalidate of this.#generationInvalidators) invalidate();
+    this.#generationInvalidators.clear();
+    return generation;
+  }
+  async #restoreLocalTracks(generation, initial) {
+    for (const state of this.#localTracks.values()) {
+      if (!this.#isCurrentGeneration(generation)) return;
+      const enable = initial ? state.source !== "screen" : state.enabled;
+      if (enable) {
+        await this.#queueSourceOperation(state.source, async () => {
+          if (!this.#isCurrentGeneration(generation) || this.#localTracks.get(state.source) !== state || !initial && !state.enabled) return;
+          await this.#setSourceEnabled(state, true);
+        }).catch((error) => {
+          if (!this.#isCurrentGeneration(generation)) return;
+          if (isStaleGeneration(error) && this.#localTracks.get(state.source) !== state) return;
+          throw error;
+        });
+      }
+    }
+    if (this.#isCurrentGeneration(generation)) this.#setPhase("live", null);
+  }
+  #failCurrentGeneration(generation, error) {
+    if (!this.#isCurrentGeneration(generation)) return;
+    this.#setFailure(error);
+    this.#reportError(error);
+  }
+  async #openConnection(authToken, generation) {
+    const connection = await this.#clientFactory({ authToken, onError: (error) => this.#reportError(error) });
+    if (!this.#isCurrentGeneration(generation)) {
+      await connection.leave();
+      return false;
+    }
+    this.#connection = connection;
+    this.#bindConnection(connection);
+    await connection.join();
+    if (!this.#isCurrentGeneration(generation)) {
+      await connection.leave();
+      return false;
+    }
+    return true;
   }
   async #closeConnection() {
     const connection = this.#connection;
@@ -1749,22 +1847,44 @@ var CloudflareRTKClient = class {
   }
   async #setSourceEnabled(state, enabled) {
     const connection = this.#connection;
+    const generation = this.#generation;
     if (!connection) throw new CloudflareRTKError("The RealtimeKit connection is not active", "media_stopped");
-    if (state.source === "microphone") {
-      if (enabled) await connection.self.enableAudio(state.track);
-      else await connection.self.disableAudio();
-    } else if (state.source === "camera") {
-      if (enabled) await connection.self.enableVideo(state.track);
-      else await connection.self.disableVideo();
-    } else {
-      this.#screenDisableRequested = !enabled;
-      if (enabled) await connection.self.enableScreenShare();
-      else await connection.self.disableScreenShare();
+    const actions = this.#sourceActions(state, connection);
+    if (state.source === "screen") this.#screenDisableRequested = !enabled;
+    await actions[enabled ? "enable" : "disable"]();
+    try {
+      this.#requireCurrentSource(state, connection, generation);
+    } catch (error) {
+      if (enabled)
+        await actions.disable().catch((cause) => {
+          this.#failCurrentGeneration(generation, cause);
+          throw cause;
+        });
+      throw error;
     }
     state.enabled = enabled;
     state.track.enabled = enabled;
     this.#publishSnapshot();
   }
+  #sourceActions(state, connection) {
+    return {
+      microphone: { enabled: connection.self.audioEnabled, enable: () => connection.self.enableAudio(state.track), disable: () => connection.self.disableAudio() },
+      camera: { enabled: connection.self.videoEnabled, enable: () => connection.self.enableVideo(state.track), disable: () => connection.self.disableVideo() },
+      screen: {
+        enabled: connection.self.screenShareEnabled,
+        enable: () => connection.self.enableScreenShare(),
+        disable: () => {
+          if (connection === this.#connection) this.#screenDisableRequested = true;
+          return connection.self.disableScreenShare();
+        }
+      }
+    }[state.source];
+  }
+  #requireCurrentSource(state, connection, generation) {
+    if (!this.#isCurrentGeneration(generation) || connection !== this.#connection || this.#localTracks.get(state.source) !== state) {
+      throw new CloudflareRTKError("The local media target belongs to a replaced connection or source", "stale_generation");
+    }
+  }
   #syncLocalState(source) {
     const state = this.#localTracks.get(source);
     const connection = this.#connection;
@@ -1962,6 +2082,9 @@ function toParticipant(participant) {
     }
   };
 }
+function isStaleGeneration(error) {
+  return error instanceof CloudflareRTKError && error.code === "stale_generation";
+}
 
 // src/media/capture-error.ts
 function describeMediaCaptureError(cause) {
@@ -1988,6 +2111,7 @@ function describeMediaCaptureError(cause) {
 }
 
 export {
+  describeMediaCaptureError,
   CloudflareSFUError,
   parseCloudflareSFUPublicationID,
   requireDescription,
@@ -1999,6 +2123,5 @@ export {
   CloudflareSFUClient,
   createCloudflareSFUHTTPTransport,
   CloudflareRTKError,
-  CloudflareRTKClient,
-  describeMediaCaptureError
+  CloudflareRTKClient
 };

package/dist/{chunk-E4OK5K6N.js → chunk-A7BVZEFM.js}

@@ -1,7 +1,7 @@
 import {
   createChalkEffectClient,
   parseAccessGrant
-} from "./chunk-M3S7HNQF.js";
+} from "./chunk-ZRMGKMX4.js";
 
 // src/public-invites/client.ts
 import { Effect } from "effect";