@q9labsai/chalk-client 5.2.6 → 5.3.1

package/dist/generated/sync.d.ts

@@ -100,11 +100,20 @@ export declare const SyncProtocolMetadata: {
                 readonly pattern: "^[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256}(,[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256})*$";
             };
         };
+        readonly helloOnlyFields: {
+            readonly baggage: {
+                readonly kind: "string";
+                readonly minBytes: 47;
+                readonly maxBytes: 47;
+                readonly format: "w3c-baggage-session-id";
+                readonly pattern: "^session\\.id=[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$";
+            };
+        };
         readonly acceptedOn: {
             readonly hello: "client-to-server";
             readonly serverFrames: "server-to-client";
         };
-        readonly upgradeHeaders: readonly ["x-chalk-journey-id", "traceparent", "tracestate"];
+        readonly upgradeHeaders: readonly ["x-chalk-journey-id", "traceparent", "tracestate", "baggage"];
         readonly rule: "propagate_from_first_observed_layer_to_every_downstream_frame";
     };
     readonly externalIntents: readonly ["admit_participant", "deny_admission", "admission_request_expired", "mute_participant", "stop_participant_camera", "stop_participant_screen_share", "remove_participant", "start_recording", "stop_recording", "participant_leave", "start_episode", "extend_episode", "end_episode", "tenant_set_deadline", "tenant_end_episode", "maximum_duration_expired"];
@@ -353,6 +362,7 @@ export declare const UuidSchema: Schema.String;
 export declare const JourneyIdSchema: Schema.String;
 export declare const TraceparentSchema: Schema.String;
 export declare const TracestateSchema: Schema.String;
+export declare const BaggageSchema: Schema.String;
 export declare const SyncCorrelationFieldsSchema: Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
     readonly traceparent: Schema.optional<Schema.String>;
@@ -424,6 +434,7 @@ export declare const HelloFrameSchema: Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
     readonly traceparent: Schema.optional<Schema.String>;
     readonly tracestate: Schema.optional<Schema.String>;
+    readonly baggage: Schema.optional<Schema.String>;
     readonly type: Schema.Literal<"hello">;
     readonly protocol: Schema.Literal<1>;
     readonly token: Schema.String;
@@ -461,6 +472,7 @@ export declare const ExtendedHelloFrameSchema: Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
     readonly traceparent: Schema.optional<Schema.String>;
     readonly tracestate: Schema.optional<Schema.String>;
+    readonly baggage: Schema.optional<Schema.String>;
     readonly type: Schema.Literal<"hello">;
     readonly protocol: Schema.Literal<1>;
     readonly token: Schema.String;
@@ -1313,6 +1325,7 @@ export declare const WelcomeSnapshotFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1361,6 +1374,7 @@ export declare const WelcomeReplayFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1379,6 +1393,7 @@ export declare const WelcomeUpToDateFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1397,6 +1412,7 @@ export declare const WelcomeTerminalFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1416,6 +1432,7 @@ export declare const ExtendedWelcomeSnapshotFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1477,6 +1494,7 @@ export declare const ExtendedWelcomeReplayFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1508,6 +1526,7 @@ export declare const ExtendedWelcomeUpToDateFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1539,6 +1558,7 @@ export declare const ExtendedWelcomeTerminalFrameSchema: Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1571,6 +1591,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1631,6 +1652,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1661,6 +1683,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1691,6 +1714,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1722,6 +1746,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1769,6 +1794,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1786,6 +1812,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -1803,6 +1830,7 @@ export declare const WelcomeFrameSchema: Schema.Union<readonly [Schema.Struct<{
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -2176,6 +2204,9 @@ export declare const PresenceProjectionItemSchema: Schema.Struct<{
     readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
     readonly speaking: Schema.Boolean;
     readonly active_speaker: Schema.Boolean;
+    readonly identity_id: Schema.optional<Schema.String>;
+    readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+    readonly admission_revision: Schema.optional<Schema.Number>;
 }>;
 export declare const MediaProjectionSnapshotFrameSchema: Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
@@ -2205,6 +2236,9 @@ export declare const PresenceProjectionSnapshotFrameSchema: Schema.Struct<{
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>>;
 }>;
 export declare const MediaProjectionEventFrameSchema: Schema.Struct<{
@@ -2235,6 +2269,9 @@ export declare const PresenceProjectionEventFrameSchema: Schema.Struct<{
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>;
 }>;
 export declare const ProjectionFrameSchema: Schema.Union<readonly [Schema.Struct<{
@@ -2264,6 +2301,9 @@ export declare const ProjectionFrameSchema: Schema.Union<readonly [Schema.Struct
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>>;
 }>, Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
@@ -2292,6 +2332,9 @@ export declare const ProjectionFrameSchema: Schema.Union<readonly [Schema.Struct
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>;
 }>]>;
 export declare const LiveTargetOutcomeSchema: Schema.Union<readonly [Schema.Literal<"confirmed">, Schema.Literal<"satisfied">, Schema.Literal<"retryable_failure">, Schema.Literal<"terminal_failure">, Schema.Literal<"ambiguous">]>;
@@ -2762,6 +2805,7 @@ export declare const SyncV1ClientFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly journey_id: Schema.optional<Schema.String>;
     readonly traceparent: Schema.optional<Schema.String>;
     readonly tracestate: Schema.optional<Schema.String>;
+    readonly baggage: Schema.optional<Schema.String>;
     readonly type: Schema.Literal<"hello">;
     readonly protocol: Schema.Literal<1>;
     readonly token: Schema.String;
@@ -2794,6 +2838,7 @@ export declare const SyncV1ClientFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly journey_id: Schema.optional<Schema.String>;
     readonly traceparent: Schema.optional<Schema.String>;
     readonly tracestate: Schema.optional<Schema.String>;
+    readonly baggage: Schema.optional<Schema.String>;
     readonly type: Schema.Literal<"hello">;
     readonly protocol: Schema.Literal<1>;
     readonly token: Schema.String;
@@ -2984,6 +3029,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3044,6 +3090,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3074,6 +3121,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3104,6 +3152,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3135,6 +3184,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3182,6 +3232,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3199,6 +3250,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3216,6 +3268,7 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
     readonly protocol: Schema.Literal<1>;
     readonly participant_id: Schema.String;
     readonly participant_generation: Schema.Number;
+    readonly participant_identity_id: Schema.optionalKey<Schema.String>;
     readonly recovery_id: Schema.String;
     readonly head: Schema.Struct<{
         readonly revision: Schema.Number;
@@ -3882,6 +3935,9 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>>;
 }>, Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;
@@ -3910,6 +3966,9 @@ export declare const SyncV1ServerFrameSchema: Schema.decodeTo<Schema.Union<reado
         readonly state: Schema.Union<readonly [Schema.Literal<"connected">, Schema.Literal<"disconnected">]>;
         readonly speaking: Schema.Boolean;
         readonly active_speaker: Schema.Boolean;
+        readonly identity_id: Schema.optional<Schema.String>;
+        readonly device_type: Schema.optional<Schema.Literals<readonly ["phone", "tablet", "computer"]>>;
+        readonly admission_revision: Schema.optional<Schema.Number>;
     }>;
 }>]>, Schema.Struct<{
     readonly journey_id: Schema.optional<Schema.String>;

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from "./space-client";
 export * from "./sync";
 export * from "./whiteboard";
 export * from "./public-invites";
+export { currentSessionId, newSessionId, requestContextHeaders, SESSION_ID_KEY, sessionBaggage, setSessionSource, withRequestContext, type SessionSource } from "./session";
 export { formatSyncConnectDiagnostic } from "./sync/connect-diagnostics";
 export { getConnectionFailureDetail } from "./space-client/failure-detail";

package/dist/index.js

@@ -15,7 +15,19 @@ import {
   createSpaceClient,
   decodeWhiteboardV1ServerFrame,
   encodeWhiteboardV1ClientFrame
-} from "./chunk-I7Y4HR2P.js";
+} from "./chunk-2CEMOTZF.js";
+import {
+  createChalkPublicClient,
+  createChalkPublicInviteClient,
+  parseInviteCode
+} from "./chunk-VAJ6XNAA.js";
+import {
+  ArrivalInvalidHandleError,
+  ArrivalUnavailableError,
+  SpacePublicInviteUnavailableError,
+  parseParsedAccessGrant,
+  requireAccessGrant
+} from "./chunk-MHJ4UPM3.js";
 import {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -26,21 +38,10 @@ import {
   publicationKey,
   requireDescription,
   requireSFUDescription,
+  setVideoRenderSize,
   validatePublicationSnapshot,
   waitFor
-} from "./chunk-YIDKETOX.js";
-import {
-  createChalkPublicClient,
-  createChalkPublicInviteClient,
-  parseInviteCode
-} from "./chunk-WFRTUBN6.js";
-import {
-  ArrivalInvalidHandleError,
-  ArrivalUnavailableError,
-  SpacePublicInviteUnavailableError,
-  parseParsedAccessGrant,
-  requireAccessGrant
-} from "./chunk-CJVLTSIO.js";
+} from "./chunk-O5JB5XVX.js";
 import {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,
@@ -69,7 +70,16 @@ import {
   optimisticV1Control,
   reactionFromFrame,
   restoreV1Snapshot
-} from "./chunk-5YPQNMJE.js";
+} from "./chunk-FD7ZSDTM.js";
+import {
+  SESSION_ID_KEY,
+  currentSessionId,
+  newSessionId,
+  requestContextHeaders,
+  sessionBaggage,
+  setSessionSource,
+  withRequestContext
+} from "./chunk-N4IPKRS6.js";
 
 // src/space-client/reload-rejoin.ts
 import { Schema } from "effect";
@@ -149,6 +159,7 @@ export {
   InMemoryChalkWhiteboardV1PendingOperationStore,
   InMemoryV1PendingTargetStore,
   IndexedDbV1PendingTargetStore,
+  SESSION_ID_KEY,
   SpaceClientError,
   SpacePublicInviteUnavailableError,
   SyncBrowserCapabilityError,
@@ -176,6 +187,7 @@ export {
   createReactNativeWebSocketFactory,
   createSpaceClient,
   createV1SyncClient,
+  currentSessionId,
   decodeV1ClientFrame,
   decodeV1ServerFrame,
   decodeWhiteboardV1ServerFrame,
@@ -184,6 +196,7 @@ export {
   encodeWhiteboardV1ClientFrame,
   formatSyncConnectDiagnostic,
   getConnectionFailureDetail,
+  newSessionId,
   optimisticV1Control,
   parseCloudflareSFUPublicationID,
   parseInviteCode,
@@ -192,11 +205,16 @@ export {
   readReloadRejoin,
   reloadRejoinAccess,
   reloadRejoinStorageKey,
+  requestContextHeaders,
   requireDescription,
   requireSFUDescription,
   restoreV1Snapshot,
   resumeReloadRejoin,
+  sessionBaggage,
+  setSessionSource,
+  setVideoRenderSize,
   validatePublicationSnapshot,
   waitFor,
+  withRequestContext,
   writeReloadRejoin
 };

package/dist/media/call-stats.d.ts

@@ -0,0 +1,27 @@
+import type { components } from "../generated/openapi-types";
+export type CallStatsRequest = components["schemas"]["CallStatsRequest"];
+export type CallStatsSample = CallStatsRequest["samples"][number];
+/** One summary covers this long, so a call makes about six per minute. */
+export declare const CALL_STATS_WINDOW_MS = 10000;
+/** A batch uploads once it holds this many samples (about a minute of call). */
+export declare const CALL_STATS_UPLOAD_SAMPLES = 6;
+/** The API rejects larger batches. */
+export declare const CALL_STATS_MAX_BATCH = 30;
+/** The API rejects a window longer than this and drops the whole batch, so a longer gap (a stalled tab, a sleeping device) is skipped. */
+export declare const CALL_STATS_MAX_WINDOW_MS = 60000;
+/** Per-call cap: about an hour of samples. Later windows are dropped. */
+export declare const CALL_STATS_CALL_CAP = 360;
+export type CallStatsCollector = {
+    /** Feed one `getStats()` report. Cheap; summarises once a window has elapsed. */
+    readonly observe: (report: RTCStatsReport) => void;
+    /** Close the open window (if long enough) and upload what is buffered with `upload`, once any upload in flight ends. */
+    readonly flush: (upload: Upload) => Promise<void>;
+    /** A new peer connection starts new counters: drop the open window and its baseline, keep what is already buffered. */
+    readonly reset: () => void;
+};
+type Upload = (request: CallStatsRequest) => Promise<void>;
+export declare function createCallStatsCollector(options: {
+    readonly upload: Upload;
+    readonly now?: () => number;
+}): CallStatsCollector;
+export {};

package/dist/media/client.d.ts

@@ -7,12 +7,12 @@ export declare class CloudflareSFUClient implements ClientMediaPlane {
     subscribe(listener: () => void): () => void;
     remotePublicationResumed(publicationId: string): void;
     remoteParticipantsChanged(participantIds: readonly string[]): void;
-    remotePublicationsChanged(): void;
+    remotePublicationsChanged(publications?: readonly MediaPublication[], projectionState?: "available" | "unavailable"): void;
     prepareLocalTrack(source: MediaPublicationSource, track: MediaStreamTrack): void;
     clearPreparedLocalTrack(source: MediaPublicationSource, options?: {
         readonly stopTrack?: boolean;
     }): Promise<void>;
-    start(localMedia: MediaStream): Promise<void>;
+    start(localMedia: MediaStream, beforePublish?: () => Promise<MediaStream>): Promise<void>;
     refreshRemotePublications(): Promise<void>;
     setLocalPublicationTarget(target: MediaPlaneTarget): Promise<MediaPlaneResult>;
     pauseLocalCapture(source: "microphone" | "camera"): Promise<void>;

package/dist/media/ice-servers.d.ts

@@ -0,0 +1,3 @@
+import type { CloudflareSFUBootstrap } from "./types";
+/** The server sends TURN with its STUN entry; an older server sends only `stunServer`. */
+export declare function iceServersFor(bootstrap: CloudflareSFUBootstrap): RTCIceServer[];

package/dist/media/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./cloudflare-sfu";
 export type { ClientMediaPlane, ConnectionMediaLocalTrack, ConnectionMediaPhase, ConnectionMediaRemoteTrack, ConnectionMediaSnapshot, MediaPlaneOutcome, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaPublicationSource, MediaSource } from "./plane";
 export { describeMediaCaptureError } from "./capture-error";
+export { setVideoRenderSize } from "./video-render-size";
+export type { VideoRenderSize } from "./video-render-size";

package/dist/media/index.js

@@ -8,9 +8,11 @@ import {
   publicationKey,
   requireDescription,
   requireSFUDescription,
+  setVideoRenderSize,
   validatePublicationSnapshot,
   waitFor
-} from "../chunk-YIDKETOX.js";
+} from "../chunk-O5JB5XVX.js";
+import "../chunk-N4IPKRS6.js";
 export {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -21,6 +23,7 @@ export {
   publicationKey,
   requireDescription,
   requireSFUDescription,
+  setVideoRenderSize,
   validatePublicationSnapshot,
   waitFor
 };

package/dist/media/plane.d.ts

@@ -1,6 +1,6 @@
 import type { operations } from "../generated/openapi-types";
 export type MediaConnectionReplacementCause = NonNullable<NonNullable<operations["addCloudflareSFUTracks"]["parameters"]["query"]>["replacement_cause"]>;
-export type LocalPublicationRetirementCause = Exclude<MediaConnectionReplacementCause, "local_signaling_failure" | "remote_signaling_failure" | "dormant_connection" | "access_refresh">;
+export type LocalPublicationRetirementCause = Exclude<MediaConnectionReplacementCause, "local_signaling_failure" | "remote_signaling_failure" | "dormant_connection" | "access_refresh" | "receive_stalled">;
 export type ScreenShareSurface = "monitor" | "window" | "browser";
 export type ScreenShareOptions = {
     readonly surface?: ScreenShareSurface;
@@ -27,6 +27,7 @@ export type ConnectionMediaRemoteTrack = Pick<MediaPublication, "participantId"
     readonly track: MediaStreamTrack;
 };
 export type ConnectionMediaSnapshot = {
+    readonly receiveStalls?: readonly import("./receive-stall").ReceiveStallObservation[];
     readonly connection: {
         readonly phase: ConnectionMediaPhase;
         readonly peerConnectionState: RTCPeerConnectionState | null;
@@ -62,7 +63,8 @@ export type ClientMediaPlane = {
     readonly closeForcedLocalPublication?: (source: MediaSource, cause?: LocalPublicationRetirementCause) => Promise<void>;
     readonly observeLocalPublications: (listener: (publications: readonly MediaPublication[]) => void) => () => void;
     readonly observeRemotePublications: (listener: (publications: readonly MediaPublication[]) => void) => () => void;
-    readonly remotePublicationsChanged?: () => void;
+    /** Unavailable suspends receive eligibility without withdrawing publication identities. */
+    readonly remotePublicationsChanged?: (publications?: readonly MediaPublication[], projectionState?: "available" | "unavailable") => void;
     readonly remoteParticipantsChanged?: (participantIds: readonly string[]) => void;
     readonly remotePublicationResumed?: (publicationId: string) => void;
 };

package/dist/media/receive-stall.d.ts

@@ -0,0 +1,52 @@
+import type { MediaPublication } from "./plane";
+import type { CloudflareSFURemoteTrack } from "./types";
+export declare const RECEIVE_STALL_WINDOW_MS = 7000;
+export declare const RECEIVE_STARTUP_GRACE_MS = 20000;
+export type ReceivePacketSample = {
+    readonly publicationId: string;
+    readonly trackId: string;
+    readonly packets: number;
+};
+/** Only consecutive, timely observations of expected media establish a stall. */
+export declare class ReceiveStallDetector {
+    #private;
+    forget(publicationId: string): void;
+    clear(): void;
+    sample(now: number, tracks: readonly ReceivePacketSample[]): {
+        readonly stalled: readonly string[];
+        readonly advanced: readonly string[];
+        readonly resumed: readonly string[];
+    };
+}
+export type ReceiveStallObservation = {
+    readonly event: "receive_stalled";
+    readonly scope: "partial" | "all";
+    readonly observedAtMs: number;
+    readonly expectedTracks: number;
+    readonly stalledTracks: number;
+};
+/**
+ * Owns eligibility, pending stalls and the budget across replacement peers.
+ * Rebuild budgets belong to a remote participant's source, not to one publication id:
+ * a rebuild republishes every local track, and the peers' replacement publications must not renew them.
+ */
+export declare class ReceiveStallRecovery {
+    #private;
+    get observations(): readonly ReceiveStallObservation[];
+    expect(publications: readonly MediaPublication[], participantId: string): void;
+    suspend(): void;
+    isStalled(publicationId: string): boolean;
+    canRepull(id: string): boolean;
+    reserveRepull(id: string): boolean;
+    restarted(id: string): void;
+    canRebuild(id?: string): boolean;
+    reserveRebuild(): boolean;
+    /** The media connection was replaced: its receivers are gone, so nothing is awaiting a restore. */
+    replaced(): void;
+    clear(): void;
+    sample(now: number, connection: RTCPeerConnection, report: RTCStatsReport, tracks: Iterable<CloudflareSFURemoteTrack>): {
+        readonly stalled: readonly string[];
+        readonly advanced: readonly string[];
+        readonly newlyStalled: readonly string[];
+    };
+}

package/dist/media/types.d.ts

@@ -1,8 +1,15 @@
 import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
 import type { MediaConnectionReplacementCause, MediaPublication, MediaPublicationSource } from "./plane";
+export type CloudflareSFUIceServer = {
+    readonly urls: readonly string[];
+    readonly username?: string;
+    readonly credential?: string;
+};
 export type CloudflareSFUBootstrap = {
     readonly connectionId: string;
     readonly stunServer: string;
+    /** STUN and TURN servers from the API. Absent on older servers, which means STUN only. */
+    readonly iceServers?: readonly CloudflareSFUIceServer[];
 };
 export type CloudflareSFUSessionDescription = {
     readonly type: "offer" | "answer";
@@ -59,12 +66,24 @@ export type CloudflareSFUSignalingTransport = {
         readonly sessionDescription?: CloudflareSFUSessionDescription;
         readonly tracks: readonly CloudflareSFUCloseTrackRequest[];
         readonly force: boolean;
+        readonly receiveOnly?: boolean;
+    }) => Promise<CloudflareSFUTracksResponse>;
+    /** Changes the simulcast layer of tracks already pulled, without renegotiating. Transports without it keep the layer chosen at pull time. */
+    readonly updateTracks?: (input: {
+        readonly connectionId: string;
+        readonly tracks: readonly CloudflareSFUTrackRequest[];
     }) => Promise<CloudflareSFUTracksResponse>;
     readonly renegotiate: (input: {
         readonly connectionId: string;
         readonly sessionDescription: CloudflareSFUSessionDescription;
     }) => Promise<void>;
     readonly listPublications: () => Promise<CloudflareSFUPublicationSnapshot>;
+    /**
+     * Best-effort per-call stats upload; transports without it simply report nothing. The `closing`
+     * batch reuses the last token and never asks the credential provider, which could refresh access
+     * for a participant who just left or was evicted.
+     */
+    readonly uploadCallStats?: (stats: import("./call-stats").CallStatsRequest, closing: boolean) => Promise<void>;
 };
 export type CloudflareSFURemoteTrack = CloudflareSFUPublication & {
     readonly track: MediaStreamTrack;
@@ -77,6 +96,8 @@ export type CloudflareSFUFailureCode = CloudflareSFUErrorCode;
 export type CloudflareSFUConnectionPhase = "idle" | "connecting" | "live" | "recovering" | "failed" | "stopped";
 export type CloudflareSFUPhase = CloudflareSFUConnectionPhase;
 export type CloudflareSFUSnapshot = {
+    /** Omitted by media adapters without receive diagnostics; treat as empty. */
+    readonly receiveStalls?: readonly import("./receive-stall").ReceiveStallObservation[];
     readonly connection: {
         readonly phase: CloudflareSFUConnectionPhase;
         readonly peerConnectionState: RTCPeerConnectionState | null;

package/dist/media/video-render-size.d.ts

@@ -0,0 +1,7 @@
+export type VideoRenderSize = {
+    readonly width: number;
+    readonly height: number;
+};
+/** Tells the media client how large the UI draws a remote video, in device pixels. Pass null when the track leaves the screen. */
+export declare function setVideoRenderSize(track: MediaStreamTrack, size: VideoRenderSize | null): void;
+export declare function videoRenderSize(track: MediaStreamTrack): VideoRenderSize | undefined;