@q9labsai/chalk-client 5.2.4 → 5.2.6

package/dist/generated/schemas.d.ts

@@ -226,15 +226,22 @@ export declare const ConnectionReportRequestSchema: Schema.Struct<{
         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 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", "media_projection_mismatch"]>;
+        readonly granted_audio: Schema.optional<Schema.Literals<readonly ["granted", "not_granted", "unknown"]>>;
+        readonly granted_video: Schema.optional<Schema.Literals<readonly ["granted", "not_granted", "unknown"]>>;
         readonly heartbeat_gap_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
         readonly http_status: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly media_error_kind: Schema.optional<Schema.Literals<readonly ["NotAllowedError", "NotReadableError", "NotFoundError", "OverconstrainedError", "AbortError", "SecurityError", "InvalidStateError", "OperationError", "NotSupportedError", "CloudflareSFUError", "network", "timeout", "unknown"]>>;
+        readonly media_error_step: Schema.optional<Schema.Literals<readonly ["local_capture", "peer_connection", "access_refresh", "sfu_tracks", "sfu_close_tracks", "sfu_renegotiate", "sfu_publications"]>>;
         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 projection_state: Schema.optional<Schema.Literals<readonly ["on", "off"]>>;
+        readonly publication_state: Schema.optional<Schema.Literals<readonly ["on", "off"]>>;
+        readonly source: Schema.optional<Schema.Literals<readonly ["microphone", "camera"]>>;
         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 trigger: Schema.Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted", "media_projection_mismatch"]>;
     readonly version: Schema.Literal<1>;
 }>;
 export type ConnectionReportRequest = typeof ConnectionReportRequestSchema.Type;
@@ -443,6 +450,7 @@ export declare const IntegrationServiceIdSchema: Schema.brand<Schema.String, "In
 export type IntegrationServiceId = typeof IntegrationServiceIdSchema.Type;
 export declare const IssueAccessGrantRequestSchema: Schema.Struct<{
     readonly current_media_token: Schema.optional<Schema.String>;
+    readonly expected_media_connection_id: Schema.optional<Schema.NullOr<Schema.String>>;
     readonly participant_generation: Schema.Number;
     readonly replace_media_connection: Schema.Boolean;
 }>;
@@ -478,6 +486,10 @@ export declare const MembershipListSchema: Schema.Struct<{
     }>;
 }>;
 export type MembershipList = typeof MembershipListSchema.Type;
+export declare const ParticipantEpisodeStatusSchema: Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["active", "ending", "ended"]>;
+}>;
+export type ParticipantEpisodeStatus = typeof ParticipantEpisodeStatusSchema.Type;
 export declare const ParticipantJoinCancellationSchema: Schema.Struct<{
     readonly cancelled: Schema.Boolean;
 }>;
@@ -1346,6 +1358,7 @@ export declare const AddCloudflareSFUTracksPathParamsSchema: Schema.Struct<{
 export type AddCloudflareSFUTracksPathParams = typeof AddCloudflareSFUTracksPathParamsSchema.Type;
 export declare const AddCloudflareSFUTracksQueryParamsSchema: Schema.Struct<{
     readonly allow_partial_remote_tracks: Schema.optional<Schema.Boolean>;
+    readonly replacement_cause: Schema.optional<Schema.Literals<readonly ["user_pause", "moderation_pause", "sync_recovery_loss", "discovery_absent", "capture_cleanup", "consent_revoked", "publish_failure", "enable_failure", "projection_mismatch", "forced_pause", "local_signaling_failure", "remote_signaling_failure", "dormant_connection", "access_refresh"]>>;
 }>;
 export type AddCloudflareSFUTracksQueryParams = typeof AddCloudflareSFUTracksQueryParamsSchema.Type;
 export declare const AddCloudflareSFUTracksRequestBodySchema: Schema.Struct<{
@@ -2235,6 +2248,23 @@ export declare const GetEpisodeAttendance429ResponseHeadersSchema: Schema.Struct
     readonly "X-RateLimit-Remaining": Schema.NumberFromString;
 }>;
 export type GetEpisodeAttendance429ResponseHeaders = typeof GetEpisodeAttendance429ResponseHeadersSchema.Type;
+export declare const GetParticipantEpisodeStatusPathParamsSchema: Schema.Struct<{
+    readonly episode_id: Schema.brand<Schema.String, "EpisodeId">;
+    readonly participant_id: Schema.brand<Schema.String, "ParticipantId">;
+    readonly space_id: Schema.brand<Schema.String, "SpaceId">;
+    readonly tenant_id: Schema.brand<Schema.String, "TenantId">;
+}>;
+export type GetParticipantEpisodeStatusPathParams = typeof GetParticipantEpisodeStatusPathParamsSchema.Type;
+export declare const GetParticipantEpisodeStatusResponseSchema: Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["active", "ending", "ended"]>;
+}>;
+export type GetParticipantEpisodeStatusResponse = typeof GetParticipantEpisodeStatusResponseSchema.Type;
+export declare const GetParticipantEpisodeStatus429ResponseHeadersSchema: Schema.Struct<{
+    readonly "Retry-After": Schema.NumberFromString;
+    readonly "X-RateLimit-Limit": Schema.NumberFromString;
+    readonly "X-RateLimit-Remaining": Schema.NumberFromString;
+}>;
+export type GetParticipantEpisodeStatus429ResponseHeaders = typeof GetParticipantEpisodeStatus429ResponseHeadersSchema.Type;
 export declare const GetProblemReportAvailabilityPathParamsSchema: Schema.Struct<{
     readonly tenant_id: Schema.brand<Schema.String, "TenantId">;
 }>;
@@ -2599,6 +2629,7 @@ export declare const IssueAccessGrantPathParamsSchema: Schema.Struct<{
 export type IssueAccessGrantPathParams = typeof IssueAccessGrantPathParamsSchema.Type;
 export declare const IssueAccessGrantRequestBodySchema: Schema.Struct<{
     readonly current_media_token: Schema.optional<Schema.String>;
+    readonly expected_media_connection_id: Schema.optional<Schema.NullOr<Schema.String>>;
     readonly participant_generation: Schema.Number;
     readonly replace_media_connection: Schema.Boolean;
 }>;
@@ -3314,15 +3345,22 @@ export declare const ReportConnectionFailureRequestBodySchema: Schema.Struct<{
         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 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", "media_projection_mismatch"]>;
+        readonly granted_audio: Schema.optional<Schema.Literals<readonly ["granted", "not_granted", "unknown"]>>;
+        readonly granted_video: Schema.optional<Schema.Literals<readonly ["granted", "not_granted", "unknown"]>>;
         readonly heartbeat_gap_ms: Schema.optional<Schema.NullOr<Schema.Number>>;
         readonly http_status: Schema.optional<Schema.NullOr<Schema.Number>>;
+        readonly media_error_kind: Schema.optional<Schema.Literals<readonly ["NotAllowedError", "NotReadableError", "NotFoundError", "OverconstrainedError", "AbortError", "SecurityError", "InvalidStateError", "OperationError", "NotSupportedError", "CloudflareSFUError", "network", "timeout", "unknown"]>>;
+        readonly media_error_step: Schema.optional<Schema.Literals<readonly ["local_capture", "peer_connection", "access_refresh", "sfu_tracks", "sfu_close_tracks", "sfu_renegotiate", "sfu_publications"]>>;
         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 projection_state: Schema.optional<Schema.Literals<readonly ["on", "off"]>>;
+        readonly publication_state: Schema.optional<Schema.Literals<readonly ["on", "off"]>>;
+        readonly source: Schema.optional<Schema.Literals<readonly ["microphone", "camera"]>>;
         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 trigger: Schema.Literals<readonly ["join_failed", "connection_lost", "recovery_exhausted", "media_projection_mismatch"]>;
     readonly version: Schema.Literal<1>;
 }>;
 export type ReportConnectionFailureRequestBody = typeof ReportConnectionFailureRequestBodySchema.Type;
@@ -4862,6 +4900,26 @@ export declare const ParticipantInvalidIdErrorSchema: Schema.decodeTo<typeof Par
         readonly message: Schema.String;
     }>;
 }>, never, never>;
+declare const ParticipantMediaReplacementPendingError_base: Schema.Class<ParticipantMediaReplacementPendingError, Schema.TaggedStruct<"ParticipantMediaReplacementPendingError", {
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"participant.media_replacement_pending">;
+        readonly message: Schema.String;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ParticipantMediaReplacementPendingError extends ParticipantMediaReplacementPendingError_base {
+}
+export declare const ParticipantMediaReplacementPendingErrorWireSchema: Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"participant.media_replacement_pending">;
+        readonly message: Schema.String;
+    }>;
+}>;
+export declare const ParticipantMediaReplacementPendingErrorSchema: Schema.decodeTo<typeof ParticipantMediaReplacementPendingError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"participant.media_replacement_pending">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>;
 declare const ParticipantNotActiveError_base: Schema.Class<ParticipantNotActiveError, Schema.TaggedStruct<"ParticipantNotActiveError", {
     readonly error: Schema.Struct<{
         readonly code: Schema.Literal<"participant.not_active">;
@@ -7869,6 +7927,58 @@ export declare const GetEpisodeErrorSchema: Schema.Union<readonly [Schema.decode
     }>;
 }>, never, never>]>;
 export type GetEpisodeError = typeof GetEpisodeErrorSchema.Type;
+export declare const GetParticipantEpisodeStatusErrorSchema: 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 EpisodeInvalidIdError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"episode.invalid_id">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof EpisodeNotFoundError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"episode.not_found">;
+        readonly message: Schema.String;
+    }>;
+}>, never, never>, Schema.decodeTo<typeof ParticipantInvalidIdError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"participant.invalid_id">;
+        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 SpaceInvalidIdError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"space.invalid_id">;
+        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 GetParticipantEpisodeStatusError = typeof GetParticipantEpisodeStatusErrorSchema.Type;
 export declare const GetProblemReportAvailabilityErrorSchema: Schema.decodeTo<typeof TenantInvalidIdError, Schema.Struct<{
     readonly error: Schema.Struct<{
         readonly code: Schema.Literal<"tenant.invalid_id">;
@@ -8585,6 +8695,11 @@ export declare const IssueAccessGrantErrorSchema: Schema.Union<readonly [Schema.
         readonly code: Schema.Literal<"participant.invalid_id">;
         readonly message: Schema.String;
     }>;
+}>, never, never>, Schema.decodeTo<typeof ParticipantMediaReplacementPendingError, Schema.Struct<{
+    readonly error: Schema.Struct<{
+        readonly code: Schema.Literal<"participant.media_replacement_pending">;
+        readonly message: Schema.String;
+    }>;
 }>, never, never>, Schema.decodeTo<typeof ParticipantNotFoundError, Schema.Struct<{
     readonly error: Schema.Struct<{
         readonly code: Schema.Literal<"participant.not_found">;
@@ -11268,6 +11383,13 @@ export declare const ChalkOperationPolicies: {
             readonly windowSeconds: 60;
         };
     };
+    readonly getParticipantEpisodeStatus: {
+        readonly rateLimit: {
+            readonly limit: 300;
+            readonly policy: "v1.authenticated.read";
+            readonly windowSeconds: 60;
+        };
+    };
     readonly getSpacePublicInvite: {
         readonly rateLimit: {
             readonly limit: 300;

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   createSpaceClient,
   decodeWhiteboardV1ServerFrame,
   encodeWhiteboardV1ClientFrame
-} from "./chunk-LDPC2JZB.js";
+} from "./chunk-I7Y4HR2P.js";
 import {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -28,19 +28,19 @@ import {
   requireSFUDescription,
   validatePublicationSnapshot,
   waitFor
-} from "./chunk-3ASKGMD3.js";
+} from "./chunk-YIDKETOX.js";
 import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "./chunk-SYUGRHZ5.js";
+} from "./chunk-WFRTUBN6.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError,
   parseParsedAccessGrant,
   requireAccessGrant
-} from "./chunk-AZONR3Q3.js";
+} from "./chunk-CJVLTSIO.js";
 import {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,

package/dist/media/client.d.ts

@@ -1,4 +1,4 @@
-import type { ClientMediaPlane, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaPublicationSource } from "./plane";
+import type { ClientMediaPlane, LocalPublicationRetirementCause, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaPublicationSource } from "./plane";
 import type { CloudflareSFUBootstrap, CloudflareSFUClientOptions, CloudflareSFURestartOptions, CloudflareSFUSnapshot } from "./types";
 export declare class CloudflareSFUClient implements ClientMediaPlane {
     #private;
@@ -15,8 +15,9 @@ export declare class CloudflareSFUClient implements ClientMediaPlane {
     start(localMedia: MediaStream): Promise<void>;
     refreshRemotePublications(): Promise<void>;
     setLocalPublicationTarget(target: MediaPlaneTarget): Promise<MediaPlaneResult>;
-    setLocalSourceIntent(source: MediaPublicationSource, enabled: boolean): void;
-    closeForcedLocalPublication(source: MediaPublicationSource): Promise<void>;
+    pauseLocalCapture(source: "microphone" | "camera"): Promise<void>;
+    setLocalSourceIntent(source: MediaPublicationSource, enabled: boolean, cause?: LocalPublicationRetirementCause): Promise<void>;
+    closeForcedLocalPublication(source: MediaPublicationSource, cause?: LocalPublicationRetirementCause): Promise<void>;
     observeLocalPublications(listener: (publications: readonly MediaPublication[]) => void): () => void;
     observeRemotePublications(listener: (publications: readonly MediaPublication[]) => void): () => void;
     restart(input: CloudflareSFUBootstrap | CloudflareSFURestartOptions): Promise<void>;

package/dist/media/failure-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectionReport } from "../transport-diagnostics";
+type ReportEvent = ConnectionReport["events"][number];
+export type MediaFailureDiagnostic = Required<Pick<ReportEvent, "media_error_kind" | "media_error_step">> & Pick<ReportEvent, "http_status">;
+export type GrantedMedia = Required<Pick<ReportEvent, "granted_audio" | "granted_video">>;
+type MediaFailureStep = NonNullable<ReportEvent["media_error_step"]>;
+export declare function grantedMediaFromStream(stream: MediaStream): GrantedMedia;
+export declare function markMediaFetchFailure(error: unknown): void;
+export declare function markMediaFailure(error: unknown, step: MediaFailureStep): void;
+export declare function classifyMediaFailure(cause: unknown, fallbackStep: MediaFailureStep): MediaFailureDiagnostic;
+export {};

package/dist/media/index.js

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

package/dist/media/plane.d.ts

@@ -1,3 +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 ScreenShareSurface = "monitor" | "window" | "browser";
 export type ScreenShareOptions = {
     readonly surface?: ScreenShareSurface;
@@ -38,6 +41,7 @@ export type ConnectionMediaSnapshot = {
     readonly failure: {
         readonly code: string;
         readonly recoverable: boolean;
+        readonly diagnostic?: import("./failure-diagnostics").MediaFailureDiagnostic;
     } | null;
 };
 export type MediaPlaneOutcome = "confirmed" | "satisfied" | "retryable_failure" | "terminal_failure" | "ambiguous";
@@ -53,8 +57,9 @@ export type MediaPlaneResult = {
 };
 export type ClientMediaPlane = {
     readonly setLocalPublicationTarget: (target: MediaPlaneTarget) => Promise<MediaPlaneResult>;
-    readonly setLocalSourceIntent?: (source: MediaSource, enabled: boolean) => void;
-    readonly closeForcedLocalPublication?: (source: MediaSource) => Promise<void>;
+    readonly pauseLocalCapture?: (source: "microphone" | "camera") => Promise<void>;
+    readonly setLocalSourceIntent?: (source: MediaSource, enabled: boolean, cause?: LocalPublicationRetirementCause) => void;
+    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;

package/dist/media/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
-import type { MediaPublication, MediaPublicationSource } from "./plane";
+import type { MediaConnectionReplacementCause, MediaPublication, MediaPublicationSource } from "./plane";
 export type CloudflareSFUBootstrap = {
     readonly connectionId: string;
     readonly stunServer: string;
@@ -52,6 +52,7 @@ export type CloudflareSFUSignalingTransport = {
         readonly sessionDescription?: CloudflareSFUSessionDescription;
         readonly tracks: readonly CloudflareSFUTrackRequest[];
         readonly allowPartialRemoteTracks?: boolean;
+        readonly replacementCause?: MediaConnectionReplacementCause;
     }) => Promise<CloudflareSFUTracksResponse>;
     readonly closeTracks: (input: {
         readonly connectionId: string;
@@ -90,6 +91,7 @@ export type CloudflareSFUSnapshot = {
     readonly failure: {
         readonly code: CloudflareSFUFailureCode;
         readonly recoverable: boolean;
+        readonly diagnostic?: import("./failure-diagnostics").MediaFailureDiagnostic;
     } | null;
 };
 export type CloudflareSFUClientOptions = {
@@ -98,7 +100,7 @@ export type CloudflareSFUClientOptions = {
     readonly transport: CloudflareSFUSignalingTransport;
     readonly replaceMediaConnection?: () => Promise<CloudflareSFUBootstrap>;
     readonly pollIntervalMs?: number;
-    readonly onError?: (error: unknown) => void;
+    readonly onError?: (error: unknown, mediaConnectionId: string) => void;
     readonly onRemoteTrack?: (publication: CloudflareSFURemoteTrack) => void;
     readonly onScreenEnded?: () => void;
     readonly peerConnectionFactory?: (configuration: RTCConfiguration) => RTCPeerConnection;

package/dist/public-invites/index.js

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

package/dist/server/access-refresh.d.cts

@@ -2,7 +2,7 @@ import type { AccessContext } from "../space-client/types.cjs";
 import type { IssueAccessGrantInput } from "./types.cjs";
 import { type AccessGrant, type ParticipantMediaCredential } from "../access/grant.cjs";
 /** Forward the browser request unchanged; only Chalk decides whether media needs replacing. */
-export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection">;
+export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection" | "expectedMediaConnectionId" | "currentMediaToken">;
 /** Keep this on your backend, scoped to the authenticated Participant. Never send it to a browser or log it. */
 export type AccessRefreshState = {
     readonly participantGeneration: number;

package/dist/server/access-refresh.d.ts

@@ -2,7 +2,7 @@ import type { AccessContext } from "../space-client/types.js";
 import type { IssueAccessGrantInput } from "./types.js";
 import { type AccessGrant, type ParticipantMediaCredential } from "../access/grant.js";
 /** Forward the browser request unchanged; only Chalk decides whether media needs replacing. */
-export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection">;
+export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection" | "expectedMediaConnectionId" | "currentMediaToken">;
 /** Keep this on your backend, scoped to the authenticated Participant. Never send it to a browser or log it. */
 export type AccessRefreshState = {
     readonly participantGeneration: number;

package/dist/server/index.cjs

@@ -38,11 +38,13 @@ function decodeBase64Url(value) {
 // src/access/grant.ts
 var accessGrantBrand = /* @__PURE__ */ Symbol("AccessGrant");
 var AccessGrantError = class extends TypeError {
-  code = "access.invalid";
-  constructor(message = "Access grant is invalid") {
+  constructor(message = "Access grant is invalid", reason) {
     super(message);
+    this.reason = reason;
     this.name = "AccessGrantError";
   }
+  reason;
+  code = "access.invalid";
 };
 function parseParsedAccessGrant(value) {
   if (!isRecord(value)) throw new AccessGrantError();
@@ -165,7 +167,12 @@ function getAccessRefreshState(access) {
   });
 }
 function accessRefreshInput(state, request) {
-  if (request?.replaceMediaConnection === true) return { participantGeneration: state.participantGeneration, replaceMediaConnection: true };
+  if (request?.replaceMediaConnection === true)
+    return {
+      participantGeneration: state.participantGeneration,
+      replaceMediaConnection: true,
+      ...request.expectedMediaConnectionId === void 0 ? {} : { expectedMediaConnectionId: request.expectedMediaConnectionId, ...request.currentMediaToken === void 0 ? {} : { currentMediaToken: request.currentMediaToken } }
+    };
   return state;
 }
 
@@ -326,7 +333,9 @@ function setOptionalHeader(headers, name, value) {
   if (value !== void 0) headers.set(name, value);
 }
 async function responseError(response, retryable) {
-  return new ChalkAPIError({ code: errorCode(await errorBody(response)), requestId: requestId(response.headers), retryable: retryable && retryableStatuses.has(response.status), status: response.status });
+  const code = errorCode(await errorBody(response));
+  const pendingReplacement = response.status === 409 && code === "participant.media_replacement_pending";
+  return new ChalkAPIError({ code, requestId: requestId(response.headers), retryable: pendingReplacement || retryable && retryableStatuses.has(response.status), status: response.status });
 }
 async function errorBody(response) {
   try {
@@ -601,7 +610,8 @@ function accessGrantRequest(input) {
   return {
     participant_generation: input.participantGeneration,
     replace_media_connection: input.replaceMediaConnection ?? false,
-    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {}
+    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {},
+    ...input.replaceMediaConnection && input.expectedMediaConnectionId !== void 0 ? { expected_media_connection_id: input.expectedMediaConnectionId } : {}
   };
 }
 function participantRemovalRequest(input) {

package/dist/server/index.js

@@ -16,11 +16,13 @@ function decodeBase64Url(value) {
 // src/access/grant.ts
 var accessGrantBrand = /* @__PURE__ */ Symbol("AccessGrant");
 var AccessGrantError = class extends TypeError {
-  code = "access.invalid";
-  constructor(message = "Access grant is invalid") {
+  constructor(message = "Access grant is invalid", reason) {
     super(message);
+    this.reason = reason;
     this.name = "AccessGrantError";
   }
+  reason;
+  code = "access.invalid";
 };
 function parseParsedAccessGrant(value) {
   if (!isRecord(value)) throw new AccessGrantError();
@@ -143,7 +145,12 @@ function getAccessRefreshState(access) {
   });
 }
 function accessRefreshInput(state, request) {
-  if (request?.replaceMediaConnection === true) return { participantGeneration: state.participantGeneration, replaceMediaConnection: true };
+  if (request?.replaceMediaConnection === true)
+    return {
+      participantGeneration: state.participantGeneration,
+      replaceMediaConnection: true,
+      ...request.expectedMediaConnectionId === void 0 ? {} : { expectedMediaConnectionId: request.expectedMediaConnectionId, ...request.currentMediaToken === void 0 ? {} : { currentMediaToken: request.currentMediaToken } }
+    };
   return state;
 }
 
@@ -228,7 +235,9 @@ function setOptionalHeader(headers, name, value) {
   if (value !== void 0) headers.set(name, value);
 }
 async function responseError(response, retryable) {
-  return new ChalkAPIError({ code: errorCode(await errorBody(response)), requestId: requestId(response.headers), retryable: retryable && retryableStatuses.has(response.status), status: response.status });
+  const code = errorCode(await errorBody(response));
+  const pendingReplacement = response.status === 409 && code === "participant.media_replacement_pending";
+  return new ChalkAPIError({ code, requestId: requestId(response.headers), retryable: pendingReplacement || retryable && retryableStatuses.has(response.status), status: response.status });
 }
 async function errorBody(response) {
   try {
@@ -503,7 +512,8 @@ function accessGrantRequest(input) {
   return {
     participant_generation: input.participantGeneration,
     replace_media_connection: input.replaceMediaConnection ?? false,
-    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {}
+    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {},
+    ...input.replaceMediaConnection && input.expectedMediaConnectionId !== void 0 ? { expected_media_connection_id: input.expectedMediaConnectionId } : {}
   };
 }
 function participantRemovalRequest(input) {

package/dist/server/types.d.cts

@@ -158,8 +158,9 @@ export type IssueAccessGrantInput = {
     readonly replaceMediaConnection?: false;
 } | {
     readonly participantGeneration: number;
-    readonly currentMediaToken?: never;
+    readonly currentMediaToken?: string;
     readonly replaceMediaConnection: true;
+    readonly expectedMediaConnectionId?: string;
 };
 export type APIKey = {
     readonly created_at: string;

package/dist/server/types.d.ts

@@ -158,8 +158,9 @@ export type IssueAccessGrantInput = {
     readonly replaceMediaConnection?: false;
 } | {
     readonly participantGeneration: number;
-    readonly currentMediaToken?: never;
+    readonly currentMediaToken?: string;
     readonly replaceMediaConnection: true;
+    readonly expectedMediaConnectionId?: string;
 };
 export type APIKey = {
     readonly created_at: string;

package/dist/space-client/media-projection-monitor.d.ts

@@ -0,0 +1,26 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
+type Source = "microphone" | "camera";
+type Observation = {
+    readonly revision: number;
+    readonly publicationId: string | null;
+    readonly enabled: boolean;
+    readonly projectedEnabled: boolean;
+    readonly projectedPublicationId: string | null;
+};
+type Options = {
+    readonly now: () => number;
+    readonly schedule: (callback: () => void, milliseconds: number) => unknown;
+    readonly cancel: (timer: unknown) => void;
+    readonly report: (event: ConnectionReportTransportEvent) => void;
+    readonly pause: (source: Source, revision: number) => void;
+    readonly changed: () => void;
+};
+/** Observes authority without sending targets that could affect another client. */
+export declare class MediaProjectionMonitor {
+    #private;
+    constructor(options: Options);
+    observe(source: Source, observation: Observation): void;
+    state(source: Source): "requesting" | "failed" | null;
+    reset(): void;
+}
+export {};

package/dist/space-client/promise-facade.d.ts

@@ -1,11 +1,11 @@
 import { Effect } from "effect";
-type ControllerCommand = (...args: any[]) => unknown;
-type PromiseRuntime = {
-    readonly runPromise: (effect: Effect.Effect<any, any, any>) => Promise<any>;
+type ControllerCommand = (...args: never[]) => unknown;
+type PromiseRuntime<Services> = {
+    readonly runPromise: (effect: Effect.Effect<unknown, unknown, Services>) => Promise<unknown>;
 };
-export type PromiseCommand<Command> = Command extends (...args: infer Arguments) => infer Result ? (Result extends Effect.Effect<infer Success, any, any> ? (...args: Arguments) => Promise<Success> : (...args: Arguments) => Result) : never;
+export type PromiseCommand<Command> = Command extends (...args: infer Arguments) => infer Result ? (Result extends Effect.Effect<infer Success, unknown, unknown> ? (...args: Arguments) => Promise<Success> : (...args: Arguments) => Result) : never;
 export type PromiseController<Controller extends Record<string, ControllerCommand>> = {
     readonly [Key in keyof Controller]: PromiseCommand<Controller[Key]>;
 };
-export declare function toPromiseController<Controller extends Record<string, ControllerCommand>>(runtime: PromiseRuntime, controller: Controller): PromiseController<Omit<Controller, "configure" | "dispose">>;
+export declare function toPromiseController<Services, Controller extends Record<string, ControllerCommand>>(runtime: PromiseRuntime<Services>, controller: Controller): PromiseController<Omit<Controller, "configure" | "dispose">>;
 export {};

package/dist/space-client/types.d.ts

@@ -17,6 +17,10 @@ export type AccessContext = {
     readonly reason: AccessReason;
     /** Forward to the access endpoint so media recovery can obtain a fresh connection. */
     readonly replaceMediaConnection: boolean;
+    /** Automatic replacement succeeds only while this media binding is current. Omit for explicit takeover. */
+    readonly expectedMediaConnectionId?: string;
+    /** Forward unchanged for replay-safe recovery. Never log credentials. */
+    readonly currentMediaToken?: string;
     readonly signal?: AbortSignal;
 };
 /**

package/dist/transport-diagnostics.d.ts

@@ -1,3 +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">;
+export type ConnectionReportTransportEvent = Pick<ConnectionReport["events"][number], "event" | "phase" | "attempt" | "duration_ms" | "heartbeat_gap_ms" | "close_code" | "http_status" | "source" | "publication_state" | "projection_state" | "outcome">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.2.4",
+  "version": "5.2.6",
   "license": "MIT",
   "repository": {
     "type": "git",