@q9labsai/chalk-client 5.2.3 → 5.2.4

package/README.md

@@ -311,7 +311,7 @@ SpaceClient negotiates `collaboration_v2` for the 24-emoji set and per-message r
 
 `await client.media.setScreenShareEnabled(true, { surface: "browser", audio: true })` requests tab audio. The browser picker remains authoritative: selecting a window or declining audio still shares video normally. Audio is published separately as `screen_audio`; it starts, stops, and is revoked with the share, never with the microphone. `media.screenShare.hasAudio` reports local live audio; `participants.roster[].media.screenShareHasAudio` reports the remote publication. `media.remote` contains the received track.
 
-The sharer keeps local playback (`suppressLocalAudioPlayback: false`). Display audio disables echo cancellation, noise suppression and automatic gain control to preserve music; microphone capture and its processing are unchanged. System audio is excluded to avoid sending the call back to itself. Headphones avoid acoustic doubling through the microphone; local playback cannot be preserved while guaranteeing that loudspeakers never leak into it. Chrome documents [local playback control](https://developer.chrome.com/blog/screen-sharing-improvements-in-chrome-109) and [system-audio feedback](https://developer.chrome.com/docs/web-platform/screen-sharing-controls). [Meet documents the same “Also share tab audio” picker control](https://support.google.com/meet/answer/9308856?hl=en). No public X documentation establishing its echo default was found.
+The sharer keeps local playback (`suppressLocalAudioPlayback: false`). Display audio disables echo cancellation, noise suppression and automatic gain control to preserve music; microphone capture and its processing are unchanged. System audio is excluded to avoid sending the call back to itself. Headphones avoid acoustic doubling through the microphone; local playback cannot be preserved while guaranteeing that loudspeakers never leak into it. Chrome documents [local playback control](https://developer.chrome.com/blog/screen-sharing-improvements-in-chrome-109) and [system-audio feedback](https://developer.chrome.com/docs/web-platform/screen-sharing-controls). [Meet documents the same “Also share tab audio” picker control](https://support.google.com/meet/answer/9308856?hl=en).
 
 Shared tab audio is excluded from recordings until the recording format supports it. React Native display capture behavior is unchanged.
 

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

@@ -1428,12 +1428,17 @@ function createCloudflareSFUHTTPTransport(options) {
     const token = await withDeadline(CREDENTIAL_TIMEOUT_MS, (signal) => credential(signal));
     if (!token.trim()) throw new CloudflareSFUError("The media credential provider returned an empty token", "signaling_failed");
     return withDeadline(timeoutMs, async (signal) => {
+      const startedAt = performance.now();
       const response = await fetch(`${mediaPath}/${path}`, {
         ...init,
         signal,
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...options.traceparent ? { traceparent: options.traceparent } : {}, ...init?.headers }
       });
       if (!response.ok) {
+        try {
+          options.onDiagnostic?.({ event: "media_http_error", http_status: response.status, duration_ms: performance.now() - startedAt });
+        } catch {
+        }
         throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
           status: response.status,
           retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600

package/dist/{chunk-IMMT22US.js → chunk-5YPQNMJE.js}

@@ -3303,6 +3303,7 @@ var V1SyncClient = class {
     this.#phase = { phase: "connecting" };
     this.#connectAttemptCount += 1;
     this.#connectStartedAt = this.#clock().now();
+    const socketStartedAt = this.#connectStartedAt;
     this.#opened = false;
     if (this.#connectFailure?.opened) this.#connectFailure = void 0;
     this.#emit();
@@ -3331,6 +3332,7 @@ var V1SyncClient = class {
       if (socket !== this.#socket) return;
       this.#clearDial();
       this.#opened = true;
+      this.#diagnostic({ event: "sync_socket_open", attempt: this.#connectAttemptCount, duration_ms: this.#clock().now() - socketStartedAt });
       this.#connectFailure = void 0;
       void this.#authenticate(socket);
     };
@@ -3338,6 +3340,7 @@ var V1SyncClient = class {
       this.#inbound = this.#inbound.then(() => this.#receive(socket, event.data));
     };
     socket.onclose = (event) => {
+      this.#diagnostic({ event: "sync_socket_close", close_code: event.code, duration_ms: this.#clock().now() - socketStartedAt, ...this.#lastHeartbeatReplyAt === null ? {} : { heartbeat_gap_ms: this.#now() - this.#lastHeartbeatReplyAt } });
       if (this.#started) {
         this.#socketCloses.push({ code: event.code, wasClean: event.wasClean ?? null });
         if (this.#socketCloses.length > 50) {
@@ -3376,6 +3379,7 @@ var V1SyncClient = class {
       const hello = {
         type: "hello",
         protocol: 1,
+        ...this.#options.traceparent ? { traceparent: this.#options.traceparent } : {},
         token,
         streams: {
           control: { cursor: this.#control && { revision: this.#control.revision, state_schema_version: this.#control.stateSchemaVersion, state_digest: this.#control.stateDigest } },
@@ -3829,12 +3833,19 @@ var V1SyncClient = class {
   #updateLocalMediaStates() {
     this.#liveTargets.updateFromPublications(this.#localPublications);
   }
+  #diagnostic(event) {
+    try {
+      this.#options.onDiagnostic?.(event);
+    } catch {
+    }
+  }
   #startHeartbeat() {
     this.#clearHeartbeat();
     this.#heartbeatTimer = this.#clock().setTimeout(() => {
       this.#heartbeatTimer = void 0;
       if (this.#phase.phase !== "live") return;
       this.#missedHeartbeats += 1;
+      if (this.#missedHeartbeats > 1) this.#diagnostic({ event: "sync_heartbeat_gap", duration_ms: this.#missedHeartbeats * 2e4, ...this.#lastHeartbeatReplyAt === null ? {} : { heartbeat_gap_ms: this.#now() - this.#lastHeartbeatReplyAt } });
       if (this.#missedHeartbeats > 2) {
         this.#socket?.close(CLIENT_RESTART_CLOSE_CODE, "heartbeat timeout");
         return;

package/dist/{chunk-GA3JDPFI.js → chunk-AZONR3Q3.js}

@@ -243,6 +243,71 @@ var CloudflareSFUTracksRequestSchema = Schema.Struct({
     })
   )
 });
+var ConnectionReportRequestSchema = Schema.Struct({
+  events: Schema.Array(
+    Schema.Struct({
+      attempt: Schema.optional(Schema.NullOr(Schema.Number)),
+      close_code: Schema.optional(Schema.NullOr(Schema.Number)),
+      code: Schema.optional(
+        Schema.Literals([
+          "invalid_state",
+          "invalid_access",
+          "access_unavailable",
+          "permission_denied",
+          "device_not_found",
+          "device_busy",
+          "device_constraint_invalid",
+          "media_capture_failed",
+          "sync_start_failed",
+          "state_digest_recovery_failed",
+          "sync_hello_timeout",
+          "media_start_failed",
+          "join_cleanup_unconfirmed",
+          "sync_recovery_exhausted",
+          "media_recovery_exhausted",
+          "command_rejected",
+          "leave_unconfirmed",
+          "episode_ended",
+          "unsupported_environment",
+          "internal_error",
+          "collaboration_unavailable",
+          "chat_cursor_reset_required",
+          "rate_limited",
+          "invalid_payload"
+        ])
+      ),
+      duration_ms: Schema.optional(Schema.NullOr(Schema.Number)),
+      elapsed_ms: Schema.Number,
+      event: Schema.Literals([
+        "space_join_span",
+        "state_changed",
+        "connection_failed",
+        "sync_connect_failed",
+        "sync_dial_timeout",
+        "access_refreshed",
+        "access_refresh_failed",
+        "recovery_attempt",
+        "recovery_succeeded",
+        "recovery_exhausted",
+        "cleanup_completed",
+        "cleanup_unconfirmed",
+        "sync_socket_open",
+        "sync_socket_close",
+        "sync_heartbeat_gap",
+        "media_state",
+        "media_http_error"
+      ]),
+      heartbeat_gap_ms: Schema.optional(Schema.NullOr(Schema.Number)),
+      http_status: Schema.optional(Schema.NullOr(Schema.Number)),
+      outcome: Schema.optional(Schema.Literals(["started", "succeeded", "failed", "cancelled"])),
+      phase: Schema.optional(Schema.Literals(["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"])),
+      state: Schema.optional(Schema.Literals(["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"])),
+      step: Schema.optional(Schema.Literals(["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]))
+    })
+  ).check(Schema.isMinLength(1), Schema.isMaxLength(64)),
+  trigger: Schema.Literals(["join_failed", "connection_lost", "recovery_exhausted"]),
+  version: Schema.Literal(1)
+});
 var CreateAPIKeyRequestSchema = Schema.Struct({
   expires_at: DateTimeStringSchema,
   name: Schema.String.check(Schema.isMinLength(1)),
@@ -1687,6 +1752,15 @@ var RenegotiateCloudflareSFU429ResponseHeadersSchema = Schema.Struct({
   "X-RateLimit-Limit": RateLimitLimitHeaderSchema,
   "X-RateLimit-Remaining": RateLimitRemainingHeaderSchema
 });
+var ReportConnectionFailurePathParamsSchema = Schema.Struct({
+  tenant_id: TenantIdSchema
+});
+var ReportConnectionFailureRequestBodySchema = ConnectionReportRequestSchema;
+var ReportConnectionFailure429ResponseHeadersSchema = Schema.Struct({
+  "Retry-After": RetryAfterHeaderSchema,
+  "X-RateLimit-Limit": RateLimitLimitHeaderSchema,
+  "X-RateLimit-Remaining": RateLimitRemainingHeaderSchema
+});
 var RequestRecordingExportPathParamsSchema = Schema.Struct({
   recording_id: RecordingIdSchema,
   tenant_id: TenantIdSchema
@@ -4794,6 +4868,16 @@ var RenegotiateCloudflareSFUErrorSchema = Schema.Union([
   SpaceInvalidIdErrorSchema,
   TenantInvalidIdErrorSchema
 ]);
+var ReportConnectionFailureErrorSchema = Schema.Union([
+  AccessForbiddenErrorSchema,
+  AccessUnauthenticatedErrorSchema,
+  RequestInvalidErrorSchema,
+  RequestPayloadTooLargeErrorSchema,
+  RequestRateLimitedErrorSchema,
+  ServiceInternalErrorSchema,
+  ServiceUnavailableErrorSchema,
+  TenantInvalidIdErrorSchema
+]);
 var RequestRecordingExportErrorSchema = Schema.Union([
   AccessForbiddenErrorSchema,
   AccessUnauthenticatedErrorSchema,
@@ -5087,6 +5171,7 @@ var ChalkOperationPolicies = {
   refreshSpacePublicInviteAccess: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   removeEpisodeParticipant: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   renegotiateCloudflareSFU: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
+  reportConnectionFailure: { maxBodyBytes: 32768, rateLimit: { limit: 6, policy: "connection_reports.participant", windowSeconds: 600 } },
   requestRecordingExport: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   requestTranscript: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   restoreSpace: { rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
@@ -5528,6 +5613,22 @@ var defaultGroup = HttpApiGroup.make("default").add(
       ServiceUnavailableErrorSchema.pipe(HttpApiSchema.status(503))
     ]
   })
+).add(
+  HttpApiEndpoint.post("reportConnectionFailure", "/v1/tenants/:tenant_id/connection-reports", {
+    params: ReportConnectionFailurePathParamsSchema,
+    payload: ReportConnectionFailureRequestBodySchema,
+    success: HttpApiSchema.Empty(204).pipe(HttpApiSchema.status(204)),
+    error: [
+      RequestInvalidErrorSchema.pipe(HttpApiSchema.status(400)),
+      TenantInvalidIdErrorSchema.pipe(HttpApiSchema.status(400)),
+      AccessUnauthenticatedErrorSchema.pipe(HttpApiSchema.status(401)),
+      AccessForbiddenErrorSchema.pipe(HttpApiSchema.status(403)),
+      RequestPayloadTooLargeErrorSchema.pipe(HttpApiSchema.status(413)),
+      RequestRateLimitedErrorSchema.pipe(HttpApiSchema.status(429)),
+      ServiceInternalErrorSchema.pipe(HttpApiSchema.status(500)),
+      ServiceUnavailableErrorSchema.pipe(HttpApiSchema.status(503))
+    ]
+  })
 ).add(
   HttpApiEndpoint.delete("revokeAPIKey", "/v1/tenants/:tenant_id/api-keys/:api_key_id", {
     params: RevokeAPIKeyPathParamsSchema,
@@ -6877,6 +6978,7 @@ export {
   CloudflareSFURenegotiateResponseSchema,
   CloudflareSFUTracksAPIResponseSchema,
   CloudflareSFUTracksRequestSchema,
+  ConnectionReportRequestSchema,
   CreateAPIKeyRequestSchema,
   CreateEpisodeRequestSchema,
   CreateMembershipRequestSchema,
@@ -7174,6 +7276,9 @@ export {
   RenegotiateCloudflareSFURequestBodySchema,
   RenegotiateCloudflareSFUResponseSchema,
   RenegotiateCloudflareSFU429ResponseHeadersSchema,
+  ReportConnectionFailurePathParamsSchema,
+  ReportConnectionFailureRequestBodySchema,
+  ReportConnectionFailure429ResponseHeadersSchema,
   RequestRecordingExportPathParamsSchema,
   RequestRecordingExportRequestBodySchema,
   RequestRecordingExportResponseSchema,
@@ -7642,6 +7747,7 @@ export {
   RefreshSpacePublicInviteAccessErrorSchema,
   RemoveEpisodeParticipantErrorSchema,
   RenegotiateCloudflareSFUErrorSchema,
+  ReportConnectionFailureErrorSchema,
   RequestRecordingExportErrorSchema,
   RequestTranscriptErrorSchema,
   RestoreSpaceErrorSchema,

package/dist/{chunk-4ZUN55Z2.js → chunk-LDPC2JZB.js}

@@ -2,11 +2,11 @@ import {
   CloudflareSFUClient,
   createCloudflareSFUHTTPTransport,
   describeMediaCaptureError
-} from "./chunk-DWKTGBHR.js";
+} from "./chunk-3ASKGMD3.js";
 import {
   AccessGrantError,
   requireParsedAccessGrant
-} from "./chunk-GA3JDPFI.js";
+} from "./chunk-AZONR3Q3.js";
 import {
   ChatAttachmentMimeTypeSchema,
   ChatReactionSetFrameSchema,
@@ -20,7 +20,7 @@ import {
   formatSyncConnectDiagnostic,
   scheduleSyncDialDeadline,
   syncConnectFailureCode
-} from "./chunk-IMMT22US.js";
+} from "./chunk-5YPQNMJE.js";
 
 // src/access/manager.ts
 import { Clock, Context, Data, Effect, Layer, SynchronizedRef } from "effect";
@@ -59,7 +59,7 @@ var makeConnectionAccessLayer = (provider, refreshWindowMs = DEFAULT_REFRESH_WIN
         automaticMediaReplacementListeners.add(listener);
         return () => automaticMediaReplacementListeners.delete(listener);
       }),
-      requiresRefresh: millisecondsUntilRefresh.pipe(Effect.map((milliseconds) => milliseconds === null || milliseconds === 0)),
+      requiresRefresh: millisecondsUntilRefresh.pipe(Effect.map((milliseconds2) => milliseconds2 === null || milliseconds2 === 0)),
       millisecondsUntilRefresh,
       clear: SynchronizedRef.set(state, { access: null })
     };
@@ -2156,7 +2156,7 @@ var ChalkWhiteboardV1Client = class {
     return this.#options.clock ?? {
       now: Date.now,
       monotonicNow: () => globalThis.performance.now(),
-      setTimeout: (callback, milliseconds) => globalThis.setTimeout(callback, milliseconds),
+      setTimeout: (callback, milliseconds2) => globalThis.setTimeout(callback, milliseconds2),
       clearTimeout: (handle) => globalThis.clearTimeout(handle)
     };
   }
@@ -2288,6 +2288,124 @@ function createChalkWhiteboardV1Client(options) {
   });
 }
 
+// src/connection/report.ts
+var MAX_EVENTS = 64;
+var MAX_BYTES = 32768;
+var MAX_MS = 2147483647;
+var COOLDOWN_MS = 6e4;
+var participantCooldowns = /* @__PURE__ */ new Map();
+var milliseconds = (value) => Math.max(0, Math.min(MAX_MS, Math.round(Number.isFinite(value) ? value : 0)));
+var optionalMilliseconds = (value) => value == null ? void 0 : milliseconds(value);
+function reserveParticipantReport(access, now) {
+  const key = `${access.subject.tenantId}:${access.subject.participantId}`;
+  for (const [participant, until] of participantCooldowns) if (until <= now) participantCooldowns.delete(participant);
+  if (participantCooldowns.has(key)) return false;
+  if (participantCooldowns.size >= 128) participantCooldowns.delete(participantCooldowns.keys().next().value ?? "");
+  participantCooldowns.set(key, now + COOLDOWN_MS);
+  return true;
+}
+var ConnectionReporter = class {
+  #events = [];
+  #startedAt;
+  #options;
+  #pending = null;
+  #unsubscribe;
+  #controller = null;
+  #retryOnReconnect = false;
+  #disposed = false;
+  constructor(options) {
+    this.#options = options;
+    this.#startedAt = options.now();
+  }
+  recordDiagnostic(diagnostic) {
+    this.#record({
+      event: diagnostic.event,
+      elapsed_ms: this.#elapsed(),
+      state: diagnostic.state,
+      step: diagnostic.step,
+      outcome: diagnostic.outcome,
+      code: diagnostic.code,
+      attempt: optionalMilliseconds(diagnostic.attempt),
+      duration_ms: optionalMilliseconds(diagnostic.sync?.durationMs ?? diagnostic.durationMs),
+      close_code: diagnostic.sync?.closeCode ?? void 0,
+      heartbeat_gap_ms: optionalMilliseconds(diagnostic.recovery?.lastHeartbeatReplyAgoMs)
+    });
+    if (diagnostic.event === "recovery_exhausted") this.#report("recovery_exhausted");
+    else if (diagnostic.event === "connection_failed") this.#report(diagnostic.state === "joining" ? "join_failed" : "connection_lost");
+  }
+  recordTransport(event) {
+    this.#record({
+      event: event.event,
+      elapsed_ms: this.#elapsed(),
+      ...event.phase ? { phase: event.phase } : {},
+      ...event.attempt == null ? {} : { attempt: milliseconds(event.attempt) },
+      ...event.duration_ms == null ? {} : { duration_ms: milliseconds(event.duration_ms) },
+      ...event.heartbeat_gap_ms == null ? {} : { heartbeat_gap_ms: milliseconds(event.heartbeat_gap_ms) },
+      ...event.close_code == null ? {} : { close_code: event.close_code },
+      ...event.http_status == null ? {} : { http_status: event.http_status }
+    });
+  }
+  dispose() {
+    this.#disposed = true;
+    this.#controller?.abort();
+    this.#stopListening();
+    this.#pending = null;
+    this.#events.length = 0;
+  }
+  get traceparent() {
+    return this.#options.traceparent;
+  }
+  #elapsed() {
+    return milliseconds(this.#options.now() - this.#startedAt);
+  }
+  #record(event) {
+    if (this.#disposed) return;
+    this.#events.push(event);
+    if (this.#events.length > MAX_EVENTS) this.#events.shift();
+  }
+  #report(trigger) {
+    if (this.#disposed || this.#pending) return;
+    const access = this.#options.access();
+    if (!access) return;
+    if (!reserveParticipantReport(access, this.#options.now())) return;
+    const events = this.#events.slice();
+    const report = { version: 1, trigger, events };
+    while (events.length && new TextEncoder().encode(JSON.stringify(report)).byteLength > MAX_BYTES) events.shift();
+    if (!events.length) return;
+    this.#pending = { access, report, attempts: 0 };
+    this.#unsubscribe = this.#options.subscribeOnline(() => {
+      this.#retryOnReconnect = true;
+      void this.#flush();
+    });
+    void this.#flush();
+  }
+  async #flush() {
+    const pending = this.#pending;
+    if (!pending || this.#controller || this.#disposed || !this.#options.online()) return;
+    this.#retryOnReconnect = false;
+    const controller = new AbortController();
+    this.#controller = controller;
+    pending.attempts += 1;
+    const timer = globalThis.setTimeout(() => controller.abort(), 5e3);
+    try {
+      await this.#options.send(pending.access, pending.report, controller.signal, this.traceparent);
+      this.#pending = null;
+    } catch {
+      if (pending.attempts >= 2) this.#pending = null;
+    } finally {
+      globalThis.clearTimeout(timer);
+      this.#controller = null;
+      if (!this.#pending) this.#stopListening();
+      if (this.#retryOnReconnect) void this.#flush();
+    }
+  }
+  #stopListening() {
+    this.#unsubscribe?.();
+    this.#unsubscribe = void 0;
+    this.#retryOnReconnect = false;
+  }
+};
+
 // src/connection/types.ts
 var ConnectionError = class extends Error {
   code;
@@ -2359,9 +2477,34 @@ function createDefaultConnectionDependencies(options) {
   return {
     clock: {
       now: () => Date.now(),
-      setTimeout: (callback, milliseconds) => globalThis.setTimeout(callback, milliseconds),
+      setTimeout: (callback, milliseconds2) => globalThis.setTimeout(callback, milliseconds2),
       clearTimeout: (handle) => globalThis.clearTimeout(handle)
     },
+    createConnectionReporter: (access) => {
+      const random = globalThis.crypto;
+      if (!random?.randomUUID) return void 0;
+      return new ConnectionReporter({
+        traceparent: `00-${random.randomUUID().replaceAll("-", "")}-${random.randomUUID().replaceAll("-", "").slice(0, 16)}-01`,
+        now: () => performance.now(),
+        access,
+        online: () => globalThis.navigator?.onLine !== false,
+        subscribeOnline: (listener) => {
+          globalThis.window?.addEventListener("online", listener);
+          return () => globalThis.window?.removeEventListener("online", listener);
+        },
+        send: async (grant, report, signal, traceparent) => {
+          const response = await fetch(`${options.apiBaseURL.replace(/\/$/, "")}/v1/tenants/${encodeURIComponent(grant.subject.tenantId)}/connection-reports`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${grant.media.token}`, "Content-Type": "application/json", traceparent },
+            body: JSON.stringify(report),
+            signal,
+            keepalive: true,
+            credentials: "omit"
+          });
+          await response.body?.cancel();
+        }
+      });
+    },
     mediaDevices: createBrowserMediaDevices(),
     cancelPendingAdmission: async (access, signal) => {
       const { tenantId, spaceId, episodeId, participantId } = access.subject;
@@ -2426,6 +2569,8 @@ function createMediaClient(apiBaseURL, input) {
     transport: createCloudflareSFUHTTPTransport({
       apiBaseURL,
       credential: input.credential,
+      onDiagnostic: input.onTransportDiagnostic,
+      traceparent: input.traceparent,
       tenantId: subject.tenantId,
       spaceId: subject.spaceId,
       episodeId: subject.episodeId,
@@ -2467,6 +2612,8 @@ function bindConnectionMediaClient(client, restart) {
 function createSyncClient(syncURL, input) {
   return createV1SyncClient({
     url: syncURL,
+    onDiagnostic: input.onTransportDiagnostic,
+    traceparent: input.traceparent,
     token: input.token,
     mediaPlane: input.media,
     collaboration: { name: "collaboration_v2", chatCursor: { afterSequence: null, retainedFloorSequence: null } },
@@ -2498,7 +2645,7 @@ function whiteboardURL(syncURL) {
 }
 
 // src/foreground-deadline.ts
-function scheduleForegroundDeadline(clock, milliseconds, expired) {
+function scheduleForegroundDeadline(clock, milliseconds2, expired) {
   let timer;
   let cancelled = false;
   const arm = () => {
@@ -2506,9 +2653,9 @@ function scheduleForegroundDeadline(clock, milliseconds, expired) {
     timer = clock.setTimeout(() => {
       if (cancelled) return;
       const elapsed = clock.now() - started;
-      if (typeof document !== "undefined" && document.visibilityState === "hidden" || elapsed > milliseconds + 2e3 || elapsed < 0) arm();
+      if (typeof document !== "undefined" && document.visibilityState === "hidden" || elapsed > milliseconds2 + 2e3 || elapsed < 0) arm();
       else expired();
-    }, milliseconds);
+    }, milliseconds2);
   };
   arm();
   return () => {
@@ -2594,6 +2741,7 @@ var MEDIA_RECOVERY_TIMEOUT_MS = 6e4;
 var START_TIMEOUT_MS = 3e4;
 var LEAVE_TIMEOUT_MS = 5e3;
 var RECOVERY_BUDGET_MS = 1e4;
+var SYNC_RECOVERY_BUDGET_MS = MEDIA_RECOVERY_TIMEOUT_MS;
 var MAX_RECOVERY_ATTEMPTS = 3;
 var REFRESH_RETRY_MS = 5e3;
 var RECONNECT_GRACE_MS = 250;
@@ -2634,7 +2782,16 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     const clock = yield* Clock2.Clock;
     const context = yield* Effect2.context();
     const serviceScope = yield* Effect2.scope;
-    const diagnostics = new ConnectionDiagnostics({ now: () => clock.currentTimeMillisUnsafe(), ...options.diagnostics });
+    const reporter = platform.createConnectionReporter?.(access.currentUnsafe);
+    const diagnostics = new ConnectionDiagnostics({
+      now: () => clock.currentTimeMillisUnsafe(),
+      ...options.diagnostics,
+      onEvent: (event) => {
+        reporter?.recordDiagnostic(event);
+        options.diagnostics?.onEvent?.(event);
+      }
+    });
+    const onTransportDiagnostic = (event) => reporter?.recordTransport(event);
     const snapshotRef = yield* SubscriptionRef.make(idleSnapshot());
     const queue = yield* Queue.unbounded();
     const listeners = /* @__PURE__ */ new Set();
@@ -2677,10 +2834,10 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     };
     const mediaAttempt = { expiresAt: null };
     const foreign7 = (operation, code = "internal_error", message = "A browser transport operation failed") => Effect2.tryPromise({ try: operation, catch: (cause) => accessRejected(cause) ? lifecycleFailure("invalid_access", false, "Access was rejected", cause) : lifecycleFailure(code, true, message, cause) });
-    const withinForegroundBudget = (effect, milliseconds, failure2) => Effect2.raceFirst(
+    const withinForegroundBudget = (effect, milliseconds2, failure2) => Effect2.raceFirst(
       effect,
       Effect2.callback((resume) => {
-        const cancel = scheduleForegroundDeadline(platform.clock, milliseconds, () => resume(Effect2.fail(typeof failure2 === "function" ? failure2() : failure2)));
+        const cancel = scheduleForegroundDeadline(platform.clock, milliseconds2, () => resume(Effect2.fail(typeof failure2 === "function" ? failure2() : failure2)));
         return Effect2.sync(cancel);
       })
     );
@@ -2741,10 +2898,10 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     const scheduleRefresh = (delay) => Effect2.gen(function* () {
       yield* stopRefresh();
       if (!active(model)) return;
-      const milliseconds = delay ?? (yield* access.millisecondsUntilRefresh) ?? 0;
+      const milliseconds2 = delay ?? (yield* access.millisecondsUntilRefresh) ?? 0;
       const scope = model.activeScope;
       if (!scope) return;
-      model.refreshFiber = yield* Effect2.forkIn(Effect2.sleep(Math.max(0, milliseconds)).pipe(Effect2.andThen(enqueue(refreshAccess())), Effect2.ignore), scope);
+      model.refreshFiber = yield* Effect2.forkIn(Effect2.sleep(Math.max(0, milliseconds2)).pipe(Effect2.andThen(enqueue(refreshAccess())), Effect2.ignore), scope);
     });
     const refreshAccess = () => Effect2.gen(function* () {
       const scope = model.activeScope;
@@ -2923,6 +3080,8 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
                 if (media === model.media) mediaAttempt.expiresAt = platform.clock.now() + MEDIA_RECOVERY_TIMEOUT_MS;
                 return replacement.media;
               }),
+              onTransportDiagnostic,
+              traceparent: reporter?.traceparent,
               onFailure: () => enqueueBackground(handleMediaFailure()),
               onScreenEnded: () => enqueueBackground(notifyScreenEnded())
             }),
@@ -2933,7 +3092,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
         const sync = yield* trace(
           "create_sync_client",
           Effect2.try({
-            try: () => platform.createSyncClient({ access: grant, token: () => toPromise(access.getSyncToken()), media }),
+            try: () => platform.createSyncClient({ access: grant, token: () => toPromise(access.getSyncToken()), media, onTransportDiagnostic, traceparent: reporter?.traceparent }),
             catch: (cause) => accessRejected(cause) ? lifecycleFailure("invalid_access", false, "Access was rejected", cause) : lifecycleFailure("sync_start_failed", true, "The sync layer could not start", cause)
           })
         );
@@ -3134,7 +3293,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     const recoveryPlan = (kind) => Clock2.currentTimeMillis.pipe(
       Effect2.map((now) => ({
         kind,
-        deadline: now + boundedInteger(options.recovery?.budgetMs, RECOVERY_BUDGET_MS, 1, 6e4),
+        deadline: now + boundedInteger(options.recovery?.budgetMs, kind === "sync" ? SYNC_RECOVERY_BUDGET_MS : RECOVERY_BUDGET_MS, 1, 6e4),
         attempts: boundedInteger(options.recovery?.maxAttempts, MAX_RECOVERY_ATTEMPTS, 1, 10),
         delays: options.recovery?.backoffMs?.length ? options.recovery.backoffMs : [100, 250, 500]
       }))
@@ -3259,7 +3418,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
         attempt.expiresAt = now + MEDIA_RECOVERY_TIMEOUT_MS;
       }
       if ((attempt.started || snapshot.connection.phase !== "idle") && (yield* syncNeedsReplacement(snapshot))) return yield* restartSync(attempt);
-      yield* waitForSyncLive(sync, boundedInteger(options.recovery?.budgetMs, RECOVERY_BUDGET_MS, 1, 6e4));
+      yield* waitForSyncLive(sync, boundedInteger(options.recovery?.budgetMs, SYNC_RECOVERY_BUDGET_MS, 1, 6e4));
     });
     const restartSync = (attempt) => Effect2.gen(function* () {
       const epoch = model.epoch;
@@ -3273,7 +3432,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
           model.syncBindingCleanup?.();
           model.sync = null;
           const sync2 = yield* Effect2.try({
-            try: () => platform.createSyncClient({ access: grant, token: () => toPromise(access.getSyncToken()), media }),
+            try: () => platform.createSyncClient({ access: grant, token: () => toPromise(access.getSyncToken()), media, onTransportDiagnostic, traceparent: reporter?.traceparent }),
             catch: (cause) => lifecycleFailure("sync_start_failed", true, "The sync layer could not start", cause)
           });
           model.sync = sync2;
@@ -3290,7 +3449,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
           else if (attempt.client === sync) attempt.started = true;
         })
       ).pipe(
-        Effect2.andThen(waitForSyncLive(sync, boundedInteger(options.recovery?.budgetMs, RECOVERY_BUDGET_MS, 1, 6e4))),
+        Effect2.andThen(waitForSyncLive(sync, boundedInteger(options.recovery?.budgetMs, SYNC_RECOVERY_BUDGET_MS, 1, 6e4))),
         Effect2.andThen(Effect2.suspend(() => sync === model.sync && model.epoch === epoch && active(model) ? confirmSyncEntry(sync) : Effect2.fail(lifecycleFailure("invalid_state", false, "Sync recovery was superseded")))),
         Effect2.tapError(
           () => enqueue(
@@ -3341,6 +3500,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
       yield* transition("left");
     });
     const syncNeedsRecovery = (snapshot) => active(model) && (snapshot.connection.phase === "connecting" || snapshot.connection.phase === "recovering" || snapshot.connection.phase === "terminal");
+    const mediaNeedsRecovery = (snapshot) => active(model) && (snapshot.connection.phase === "recovering" || snapshot.connection.phase === "failed" && snapshot.failure?.recoverable === true);
     const recordFailure = (failure2) => Effect2.sync(() => {
       diagnostics.record({ event: "connection_failed", state: model.state, epoch: model.epoch, code: failure2.code, ...failure2.sync ? { sync: failure2.sync } : {} });
     });
@@ -3353,8 +3513,10 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     const handleMediaSnapshot = (media, snapshot) => Effect2.gen(function* () {
       if (media !== model.media || media.getSnapshot() !== snapshot) return;
       if (snapshot === model.mediaSnapshot) return;
+      const phase = mediaDiagnosticPhase(snapshot);
+      if (phase !== mediaDiagnosticPhase(model.mediaSnapshot)) onTransportDiagnostic({ event: "media_state", phase });
       model.mediaSnapshot = snapshot;
-      if (active(model) && (snapshot.connection.phase === "recovering" || snapshot.connection.phase === "failed" && snapshot.failure?.recoverable)) yield* recover("media");
+      if (mediaNeedsRecovery(snapshot)) yield* recover("media");
       yield* publish();
     });
     const handleMediaFailure = () => model.media ? handleMediaSnapshot(model.media, model.media.getSnapshot()) : Effect2.void;
@@ -3418,6 +3580,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
     yield* Effect2.addFinalizer(
       () => Effect2.gen(function* () {
         model.closed = true;
+        reporter?.dispose();
         accessReplacementUnsubscribe();
         foregroundUnsubscribe?.();
         if (activeJoin) yield* Fiber.interrupt(activeJoin);
@@ -3491,7 +3654,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
       ),
       runPortCommand: (operation) => withFreshAccess(operation),
       nowUnsafe: () => clock.currentTimeMillisUnsafe(),
-      scheduleUnsafe: (callback, milliseconds) => platform.clock.setTimeout(callback, milliseconds),
+      scheduleUnsafe: (callback, milliseconds2) => platform.clock.setTimeout(callback, milliseconds2),
       cancelScheduleUnsafe: (handle) => platform.clock.clearTimeout(handle),
       createId: () => platform.createId?.() ?? `local-${++fallbackIdentifier}`
     };
@@ -3617,6 +3780,9 @@ function syncPhase(phase) {
   if (phase === "connecting") return "connecting";
   return "idle";
 }
+function mediaDiagnosticPhase(snapshot) {
+  return snapshot?.connection.peerConnectionState ?? snapshot?.connection.phase;
+}
 function mediaPhase(phase) {
   if (phase === "live") return "healthy";
   if (phase === "recovering") return "recovering";

package/dist/{chunk-6LNRDKJF.js → chunk-SYUGRHZ5.js}

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

package/dist/client.d.ts

@@ -1761,6 +1761,66 @@ export declare const createChalkEffectClient: (options: ChalkEffectClientOptions
                 readonly message: import("effect/Schema").String;
             }>;
         }>, never, never>>, never, never>, never, never>;
+        readonly reportConnectionFailure: HttpApiClient.Client.Method<import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"reportConnectionFailure", "POST", "/v1/tenants/:tenant_id/connection-reports", import("effect/Schema").toCodecStringTree<import("effect/Schema").Struct<{
+            readonly tenant_id: import("effect/Schema").brand<import("effect/Schema").String, "TenantId">;
+        }>>, never, import("effect/Schema").toCodecJson<import("effect/Schema").Struct<{
+            readonly events: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly attempt: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+                readonly close_code: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+                readonly code: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["invalid_state", "invalid_access", "access_unavailable", "permission_denied", "device_not_found", "device_busy", "device_constraint_invalid", "media_capture_failed", "sync_start_failed", "state_digest_recovery_failed", "sync_hello_timeout", "media_start_failed", "join_cleanup_unconfirmed", "sync_recovery_exhausted", "media_recovery_exhausted", "command_rejected", "leave_unconfirmed", "episode_ended", "unsupported_environment", "internal_error", "collaboration_unavailable", "chat_cursor_reset_required", "rate_limited", "invalid_payload"]>>;
+                readonly duration_ms: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+                readonly elapsed_ms: import("effect/Schema").Number;
+                readonly event: import("effect/Schema").Literals<readonly ["space_join_span", "state_changed", "connection_failed", "sync_connect_failed", "sync_dial_timeout", "access_refreshed", "access_refresh_failed", "recovery_attempt", "recovery_succeeded", "recovery_exhausted", "cleanup_completed", "cleanup_unconfirmed", "sync_socket_open", "sync_socket_close", "sync_heartbeat_gap", "media_state", "media_http_error"]>;
+                readonly heartbeat_gap_ms: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+                readonly http_status: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+                readonly outcome: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["started", "succeeded", "failed", "cancelled"]>>;
+                readonly phase: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"]>>;
+                readonly state: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"]>>;
+                readonly step: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]>>;
+            }>>;
+            readonly trigger: import("effect/Schema").Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted"]>;
+            readonly version: import("effect/Schema").Literal<1>;
+        }>>, never, import("effect/Schema").toCodecJson<import("effect/Schema").Void>, import("effect/Schema").toCodecJson<import("effect/Schema").decodeTo<typeof import("./effect").AccessForbiddenError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"access.forbidden">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").AccessUnauthenticatedError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"access.unauthenticated">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").RequestInvalidError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"request.invalid">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").RequestPayloadTooLargeError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"request.payload_too_large">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").RequestRateLimitedError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"request.rate_limited">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").ServiceInternalError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"service.internal_error">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").ServiceUnavailableError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"service.unavailable">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never> | import("effect/Schema").decodeTo<typeof import("./effect").TenantInvalidIdError, import("effect/Schema").Struct<{
+            readonly error: import("effect/Schema").Struct<{
+                readonly code: import("effect/Schema").Literal<"tenant.invalid_id">;
+                readonly message: import("effect/Schema").String;
+            }>;
+        }>, never, never>>, never, never>, never, never>;
         readonly revokeAPIKey: HttpApiClient.Client.Method<import("effect/unstable/httpapi/HttpApiEndpoint").HttpApiEndpoint<"revokeAPIKey", "DELETE", "/v1/tenants/:tenant_id/api-keys/:api_key_id", import("effect/Schema").toCodecStringTree<import("effect/Schema").Struct<{
             readonly api_key_id: import("effect/Schema").brand<import("effect/Schema").String, "UUID">;
             readonly tenant_id: import("effect/Schema").brand<import("effect/Schema").String, "TenantId">;

package/dist/connection/dependencies.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectionReporter, ConnectionReportTransportEvent } from "./report";
 import type { ClientMediaPlane, CloudflareSFUBootstrap, ConnectionMediaSnapshot } from "../media";
 import type { ChalkChatFileTransport } from "../chat-files";
 import type { V1AdmissionTarget, V1AssignableRole, V1CommandResult, V1EpisodeSnapshot, V1SelfMediaTargetResult } from "../sync";
@@ -79,6 +80,8 @@ export type ConnectionMediaFactoryInput = {
     readonly access: ParsedAccessGrant;
     readonly credential: () => Promise<string>;
     readonly replaceMediaConnection?: () => Promise<ParticipantMediaAccess>;
+    readonly traceparent?: string;
+    readonly onTransportDiagnostic?: (event: ConnectionReportTransportEvent) => void;
     readonly onFailure: (error: unknown) => void;
     readonly onScreenEnded: () => void;
 };
@@ -86,6 +89,8 @@ export type ConnectionSyncFactoryInput = {
     readonly access: ParsedAccessGrant;
     readonly token: () => Promise<string>;
     readonly media: ConnectionMediaClient;
+    readonly traceparent?: string;
+    readonly onTransportDiagnostic?: (event: ConnectionReportTransportEvent) => void;
 };
 export type ConnectionWhiteboardFactoryInput = {
     readonly onWatchdogReplacement?: ChalkWhiteboardV1ClientOptions["onWatchdogReplacement"];
@@ -97,6 +102,7 @@ export type ConnectionChatFileFactoryInput = {
 };
 export type ConnectionDependencies = {
     readonly clock: ConnectionClock;
+    readonly createConnectionReporter?: (access: () => ParsedAccessGrant | null) => ConnectionReporter | undefined;
     readonly cancelPendingAdmission?: (access: ParsedAccessGrant, signal: AbortSignal) => Promise<boolean>;
     readonly mediaDevices: ConnectionMediaDevices;
     readonly createMediaClient: (input: ConnectionMediaFactoryInput) => ConnectionMediaClient;

package/dist/connection/report.d.ts

@@ -0,0 +1,21 @@
+import type { ParsedAccessGrant } from "../access/grant";
+import type { ConnectionDiagnostic } from "./diagnostics";
+import type { ConnectionReport, ConnectionReportTransportEvent } from "../transport-diagnostics";
+export type { ConnectionReport, ConnectionReportTransportEvent } from "../transport-diagnostics";
+type ReporterOptions = {
+    readonly traceparent: string;
+    readonly now: () => number;
+    readonly access: () => ParsedAccessGrant | null;
+    readonly send: (access: ParsedAccessGrant, report: ConnectionReport, signal: AbortSignal, traceparent: string) => Promise<void>;
+    readonly online: () => boolean;
+    readonly subscribeOnline: (listener: () => void) => () => void;
+};
+/** Only SDK-owned enums and numeric facts enter this buffer. No generic logging. */
+export declare class ConnectionReporter {
+    #private;
+    constructor(options: ReporterOptions);
+    recordDiagnostic(diagnostic: ConnectionDiagnostic): void;
+    recordTransport(event: ConnectionReportTransportEvent): void;
+    dispose(): void;
+    get traceparent(): string;
+}

package/dist/effect.js

@@ -17,8 +17,8 @@ import {
   makeSpaceClientCoreLayer,
   makeSpaceClientCoreLayerFromServices,
   makeSpaceStoreLayer
-} from "./chunk-4ZUN55Z2.js";
-import "./chunk-DWKTGBHR.js";
+} from "./chunk-LDPC2JZB.js";
+import "./chunk-3ASKGMD3.js";
 import {
   APIKeyListSchema,
   APIKeyWithSecretSchema,
@@ -139,6 +139,7 @@ import {
   CloudflareSFURenegotiateResponseSchema,
   CloudflareSFUTracksAPIResponseSchema,
   CloudflareSFUTracksRequestSchema,
+  ConnectionReportRequestSchema,
   CreateAPIKey429ResponseHeadersSchema,
   CreateAPIKeyErrorSchema,
   CreateAPIKeyPathParamsSchema,
@@ -548,6 +549,10 @@ import {
   RenegotiateCloudflareSFUPathParamsSchema,
   RenegotiateCloudflareSFURequestBodySchema,
   RenegotiateCloudflareSFUResponseSchema,
+  ReportConnectionFailure429ResponseHeadersSchema,
+  ReportConnectionFailureErrorSchema,
+  ReportConnectionFailurePathParamsSchema,
+  ReportConnectionFailureRequestBodySchema,
   ReportsDeliveryFailedError,
   ReportsDeliveryFailedErrorSchema,
   ReportsDeliveryFailedErrorWireSchema,
@@ -828,8 +833,8 @@ import {
   WhiteboardStorageUnavailableErrorSchema,
   WhiteboardStorageUnavailableErrorWireSchema,
   createChalkEffectClient
-} from "./chunk-GA3JDPFI.js";
-import "./chunk-IMMT22US.js";
+} from "./chunk-AZONR3Q3.js";
+import "./chunk-5YPQNMJE.js";
 
 // src/space-client/effect.ts
 import { Context, Effect, Exit, Layer, Scope } from "effect";
@@ -990,6 +995,7 @@ export {
   ConnectionAccessService,
   ConnectionLifecycleService,
   ConnectionPlatformService,
+  ConnectionReportRequestSchema,
   CreateAPIKey429ResponseHeadersSchema,
   CreateAPIKeyErrorSchema,
   CreateAPIKeyPathParamsSchema,
@@ -1399,6 +1405,10 @@ export {
   RenegotiateCloudflareSFUPathParamsSchema,
   RenegotiateCloudflareSFURequestBodySchema,
   RenegotiateCloudflareSFUResponseSchema,
+  ReportConnectionFailure429ResponseHeadersSchema,
+  ReportConnectionFailureErrorSchema,
+  ReportConnectionFailurePathParamsSchema,
+  ReportConnectionFailureRequestBodySchema,
   ReportsDeliveryFailedError,
   ReportsDeliveryFailedErrorSchema,
   ReportsDeliveryFailedErrorWireSchema,

package/dist/generated/http-api.d.ts

@@ -1726,6 +1726,65 @@ declare const ChalkApi_base: HttpApi.HttpApi<"ChalkApi", HttpApiGroup.HttpApiGro
         readonly code: import("effect/Schema").Literal<"tenant.invalid_id">;
         readonly message: import("effect/Schema").String;
     }>;
+}>, never, never>>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"reportConnectionFailure", "POST", "/v1/tenants/:tenant_id/connection-reports", import("effect/Schema").toCodecStringTree<import("effect/Schema").Struct<{
+    readonly tenant_id: import("effect/Schema").brand<import("effect/Schema").String, "TenantId">;
+}>>, never, import("effect/Schema").toCodecJson<import("effect/Schema").Struct<{
+    readonly events: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly attempt: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+        readonly close_code: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+        readonly code: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["invalid_state", "invalid_access", "access_unavailable", "permission_denied", "device_not_found", "device_busy", "device_constraint_invalid", "media_capture_failed", "sync_start_failed", "state_digest_recovery_failed", "sync_hello_timeout", "media_start_failed", "join_cleanup_unconfirmed", "sync_recovery_exhausted", "media_recovery_exhausted", "command_rejected", "leave_unconfirmed", "episode_ended", "unsupported_environment", "internal_error", "collaboration_unavailable", "chat_cursor_reset_required", "rate_limited", "invalid_payload"]>>;
+        readonly duration_ms: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+        readonly elapsed_ms: import("effect/Schema").Number;
+        readonly event: import("effect/Schema").Literals<readonly ["space_join_span", "state_changed", "connection_failed", "sync_connect_failed", "sync_dial_timeout", "access_refreshed", "access_refresh_failed", "recovery_attempt", "recovery_succeeded", "recovery_exhausted", "cleanup_completed", "cleanup_unconfirmed", "sync_socket_open", "sync_socket_close", "sync_heartbeat_gap", "media_state", "media_http_error"]>;
+        readonly heartbeat_gap_ms: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+        readonly http_status: import("effect/Schema").optional<import("effect/Schema").NullOr<import("effect/Schema").Number>>;
+        readonly outcome: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["started", "succeeded", "failed", "cancelled"]>>;
+        readonly phase: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"]>>;
+        readonly state: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"]>>;
+        readonly step: import("effect/Schema").optional<import("effect/Schema").Literals<readonly ["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]>>;
+    }>>;
+    readonly trigger: import("effect/Schema").Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted"]>;
+    readonly version: import("effect/Schema").Literal<1>;
+}>>, never, import("effect/Schema").toCodecJson<import("effect/Schema").Void>, import("effect/Schema").toCodecJson<import("effect/Schema").decodeTo<typeof S.AccessForbiddenError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"access.forbidden">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.AccessUnauthenticatedError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"access.unauthenticated">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.RequestInvalidError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"request.invalid">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.RequestPayloadTooLargeError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"request.payload_too_large">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.RequestRateLimitedError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"request.rate_limited">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.ServiceInternalError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"service.internal_error">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.ServiceUnavailableError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"service.unavailable">;
+        readonly message: import("effect/Schema").String;
+    }>;
+}>, never, never> | import("effect/Schema").decodeTo<typeof S.TenantInvalidIdError, import("effect/Schema").Struct<{
+    readonly error: import("effect/Schema").Struct<{
+        readonly code: import("effect/Schema").Literal<"tenant.invalid_id">;
+        readonly message: import("effect/Schema").String;
+    }>;
 }>, never, never>>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"revokeAPIKey", "DELETE", "/v1/tenants/:tenant_id/api-keys/:api_key_id", import("effect/Schema").toCodecStringTree<import("effect/Schema").Struct<{
     readonly api_key_id: import("effect/Schema").brand<import("effect/Schema").String, "UUID">;
     readonly tenant_id: import("effect/Schema").brand<import("effect/Schema").String, "TenantId">;

package/dist/generated/schemas.d.ts

@@ -219,6 +219,25 @@ export declare const CloudflareSFUTracksRequestSchema: Schema.Struct<{
     }>>;
 }>;
 export type CloudflareSFUTracksRequest = typeof CloudflareSFUTracksRequestSchema.Type;
+export declare const ConnectionReportRequestSchema: Schema.Struct<{
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly attempt: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly close_code: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly code: Schema.optional<Schema.Literals<readonly ["invalid_state", "invalid_access", "access_unavailable", "permission_denied", "device_not_found", "device_busy", "device_constraint_invalid", "media_capture_failed", "sync_start_failed", "state_digest_recovery_failed", "sync_hello_timeout", "media_start_failed", "join_cleanup_unconfirmed", "sync_recovery_exhausted", "media_recovery_exhausted", "command_rejected", "leave_unconfirmed", "episode_ended", "unsupported_environment", "internal_error", "collaboration_unavailable", "chat_cursor_reset_required", "rate_limited", "invalid_payload"]>>;
+        readonly duration_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly elapsed_ms: Schema.Number;
+        readonly event: Schema.Literals<readonly ["space_join_span", "state_changed", "connection_failed", "sync_connect_failed", "sync_dial_timeout", "access_refreshed", "access_refresh_failed", "recovery_attempt", "recovery_succeeded", "recovery_exhausted", "cleanup_completed", "cleanup_unconfirmed", "sync_socket_open", "sync_socket_close", "sync_heartbeat_gap", "media_state", "media_http_error"]>;
+        readonly heartbeat_gap_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly http_status: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly outcome: Schema.optional<Schema.Literals<readonly ["started", "succeeded", "failed", "cancelled"]>>;
+        readonly phase: Schema.optional<Schema.Literals<readonly ["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"]>>;
+        readonly state: Schema.optional<Schema.Literals<readonly ["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"]>>;
+        readonly step: Schema.optional<Schema.Literals<readonly ["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]>>;
+    }>>;
+    readonly trigger: Schema.Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted"]>;
+    readonly version: Schema.Literal<1>;
+}>;
+export type ConnectionReportRequest = typeof ConnectionReportRequestSchema.Type;
 export declare const CreateAPIKeyRequestSchema: Schema.Struct<{
     readonly expires_at: Schema.brand<Schema.String, "DateTimeString">;
     readonly name: Schema.String;
@@ -3284,6 +3303,35 @@ export declare const RenegotiateCloudflareSFU429ResponseHeadersSchema: Schema.St
     readonly "X-RateLimit-Remaining": Schema.NumberFromString;
 }>;
 export type RenegotiateCloudflareSFU429ResponseHeaders = typeof RenegotiateCloudflareSFU429ResponseHeadersSchema.Type;
+export declare const ReportConnectionFailurePathParamsSchema: Schema.Struct<{
+    readonly tenant_id: Schema.brand<Schema.String, "TenantId">;
+}>;
+export type ReportConnectionFailurePathParams = typeof ReportConnectionFailurePathParamsSchema.Type;
+export declare const ReportConnectionFailureRequestBodySchema: Schema.Struct<{
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly attempt: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly close_code: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly code: Schema.optional<Schema.Literals<readonly ["invalid_state", "invalid_access", "access_unavailable", "permission_denied", "device_not_found", "device_busy", "device_constraint_invalid", "media_capture_failed", "sync_start_failed", "state_digest_recovery_failed", "sync_hello_timeout", "media_start_failed", "join_cleanup_unconfirmed", "sync_recovery_exhausted", "media_recovery_exhausted", "command_rejected", "leave_unconfirmed", "episode_ended", "unsupported_environment", "internal_error", "collaboration_unavailable", "chat_cursor_reset_required", "rate_limited", "invalid_payload"]>>;
+        readonly duration_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly elapsed_ms: Schema.Number;
+        readonly event: Schema.Literals<readonly ["space_join_span", "state_changed", "connection_failed", "sync_connect_failed", "sync_dial_timeout", "access_refreshed", "access_refresh_failed", "recovery_attempt", "recovery_succeeded", "recovery_exhausted", "cleanup_completed", "cleanup_unconfirmed", "sync_socket_open", "sync_socket_close", "sync_heartbeat_gap", "media_state", "media_http_error"]>;
+        readonly heartbeat_gap_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly http_status: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly outcome: Schema.optional<Schema.Literals<readonly ["started", "succeeded", "failed", "cancelled"]>>;
+        readonly phase: Schema.optional<Schema.Literals<readonly ["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"]>>;
+        readonly state: Schema.optional<Schema.Literals<readonly ["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"]>>;
+        readonly step: Schema.optional<Schema.Literals<readonly ["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]>>;
+    }>>;
+    readonly trigger: Schema.Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted"]>;
+    readonly version: Schema.Literal<1>;
+}>;
+export type ReportConnectionFailureRequestBody = typeof ReportConnectionFailureRequestBodySchema.Type;
+export declare const ReportConnectionFailure429ResponseHeadersSchema: Schema.Struct<{
+    readonly "Retry-After": Schema.NumberFromString;
+    readonly "X-RateLimit-Limit": Schema.NumberFromString;
+    readonly "X-RateLimit-Remaining": Schema.NumberFromString;
+}>;
+export type ReportConnectionFailure429ResponseHeaders = typeof ReportConnectionFailure429ResponseHeadersSchema.Type;
 export declare const RequestRecordingExportPathParamsSchema: Schema.Struct<{
     readonly recording_id: Schema.brand<Schema.String, "RecordingId">;
     readonly tenant_id: Schema.brand<Schema.String, "TenantId">;
@@ -9843,6 +9891,48 @@ export declare const RenegotiateCloudflareSFUErrorSchema: Schema.Union<readonly
     }>;
 }>, never, never>]>;
 export type RenegotiateCloudflareSFUError = typeof RenegotiateCloudflareSFUErrorSchema.Type;
+export declare const ReportConnectionFailureErrorSchema: Schema.Union<readonly [Schema.decodeTo<typeof AccessForbiddenError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"access.forbidden">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof AccessUnauthenticatedError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"access.unauthenticated">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof RequestInvalidError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"request.invalid">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof RequestPayloadTooLargeError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"request.payload_too_large">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof RequestRateLimitedError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"request.rate_limited">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof ServiceInternalError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"service.internal_error">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof ServiceUnavailableError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"service.unavailable">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof TenantInvalidIdError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"tenant.invalid_id">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>]>;
+export type ReportConnectionFailureError = typeof ReportConnectionFailureErrorSchema.Type;
 export declare const RequestRecordingExportErrorSchema: Schema.Union<readonly [Schema.decodeTo<typeof AccessForbiddenError, Schema.Struct<{
     readonly error: Schema.Struct<{
         readonly code: Schema.Literal<"access.forbidden">;
@@ -11346,6 +11436,14 @@ export declare const ChalkOperationPolicies: {
             readonly windowSeconds: 60;
         };
     };
+    readonly reportConnectionFailure: {
+        readonly maxBodyBytes: 32768;
+        readonly rateLimit: {
+            readonly limit: 6;
+            readonly policy: "connection_reports.participant";
+            readonly windowSeconds: 600;
+        };
+    };
     readonly requestRecordingExport: {
         readonly maxBodyBytes: 1048576;
         readonly rateLimit: {

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   createSpaceClient,
   decodeWhiteboardV1ServerFrame,
   encodeWhiteboardV1ClientFrame
-} from "./chunk-4ZUN55Z2.js";
+} from "./chunk-LDPC2JZB.js";
 import {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -28,19 +28,19 @@ import {
   requireSFUDescription,
   validatePublicationSnapshot,
   waitFor
-} from "./chunk-DWKTGBHR.js";
+} from "./chunk-3ASKGMD3.js";
 import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "./chunk-6LNRDKJF.js";
+} from "./chunk-SYUGRHZ5.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError,
   parseParsedAccessGrant,
   requireAccessGrant
-} from "./chunk-GA3JDPFI.js";
+} from "./chunk-AZONR3Q3.js";
 import {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,
@@ -69,7 +69,7 @@ import {
   optimisticV1Control,
   reactionFromFrame,
   restoreV1Snapshot
-} from "./chunk-IMMT22US.js";
+} from "./chunk-5YPQNMJE.js";
 
 // src/space-client/reload-rejoin.ts
 import { Schema } from "effect";

package/dist/media/index.js

@@ -10,7 +10,7 @@ import {
   requireSFUDescription,
   validatePublicationSnapshot,
   waitFor
-} from "../chunk-DWKTGBHR.js";
+} from "../chunk-3ASKGMD3.js";
 export {
   CloudflareSFUClient,
   CloudflareSFUError,

package/dist/media/types.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
 import type { MediaPublication, MediaPublicationSource } from "./plane";
 export type CloudflareSFUBootstrap = {
     readonly connectionId: string;
@@ -108,6 +109,8 @@ export type CloudflareSFURestartOptions = {
 };
 export type CloudflareSFUCredentialProvider = (signal?: AbortSignal) => string | Promise<string>;
 export type CloudflareSFUHTTPTransportOptions = {
+    readonly traceparent?: string;
+    readonly onDiagnostic?: (event: ConnectionReportTransportEvent) => void;
     readonly apiBaseURL: string;
     readonly credential?: CloudflareSFUCredentialProvider;
     /** @deprecated Use credential so refreshed media access is read before every request. */

package/dist/public-invites/index.js

@@ -2,12 +2,12 @@ import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "../chunk-6LNRDKJF.js";
+} from "../chunk-SYUGRHZ5.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError
-} from "../chunk-GA3JDPFI.js";
+} from "../chunk-AZONR3Q3.js";
 export {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,

package/dist/sync/index.js

@@ -22,7 +22,7 @@ import {
   encodeV1ClientFrame,
   optimisticV1Control,
   restoreV1Snapshot
-} from "../chunk-IMMT22US.js";
+} from "../chunk-5YPQNMJE.js";
 export {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,

package/dist/sync/v1-types.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
 import type { SetAdmissionPolicyCommandFrame, SyncV1ServerFrame } from "../generated/sync";
 import type { ClientMediaPlane, MediaPlaneOutcome, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaSource } from "../media/plane";
 import type { ChalkChatReactionInput, ChalkChatReactions, ChalkChatMessage, ChalkChatPageResult, ChalkChatReadReceipt, ChalkReaction, ChalkReactionEvent, ChalkSendChatMessageInput, ChalkSyncV1CollaborationCapability } from "../collaboration/types";
@@ -189,6 +190,8 @@ export type V1CollaborationClient = {
     }) => Promise<ChalkChatPageResult>;
 };
 export type V1SyncClientOptions = {
+    readonly traceparent?: string;
+    readonly onDiagnostic?: (event: ConnectionReportTransportEvent) => void;
     readonly url: string;
     readonly token: () => Promise<string>;
     readonly webSocket: SyncWebSocketFactory;

package/dist/transport-diagnostics.d.ts

@@ -0,0 +1,3 @@
+import type { components } from "./generated/openapi-types";
+export type ConnectionReport = components["schemas"]["ConnectionReportRequest"];
+export type ConnectionReportTransportEvent = Pick<ConnectionReport["events"][number], "event" | "phase" | "attempt" | "duration_ms" | "heartbeat_gap_ms" | "close_code" | "http_status">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.2.3",
+  "version": "5.2.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -218,7 +218,7 @@
     "dev": "tsup ./src/index.ts ./src/effect.ts ./src/media/index.ts ./src/sync/index.ts --format esm --out-dir ./dist --platform browser --external effect --watch",
     "generate:webhooks": "node ./scripts/generate-webhook-contract.mjs",
     "check:webhooks-generated": "node ./scripts/generate-webhook-contract.mjs --check",
-    "test": "pnpm exec vitest run",
+    "test": "node ../../../scripts/test/run.mjs pnpm exec vitest run",
     "test:webhooks-package": "pnpm run build && node ./scripts/check-webhook-package.mjs",
     "test:server-package": "pnpm run build && node ./scripts/check-server-package.mjs",
     "test:sync-browser": "pnpm run build && node ./scripts/real-browser-sync.mjs",