@q9labsai/chalk-client 5.0.1 → 5.2.0

package/dist/{chunk-AVXJ4HQU.js → chunk-D2GXPX2P.js}

@@ -120,7 +120,7 @@ var BrowserSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -176,7 +176,7 @@ var ReactNativeSyncSocket = class {
     this.#socket = socket;
     this.#socket.onopen = () => this.onopen?.();
     this.#socket.onmessage = (event) => this.onmessage?.({ data: event.data });
-    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006 });
+    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006, reason: typeof event.reason === "string" ? event.reason : void 0 });
     this.#socket.onerror = () => this.onerror?.();
   }
   send(data) {
@@ -196,7 +196,7 @@ var BrowserFallbackSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -217,6 +217,81 @@ function unsubscribe(subscription) {
   }
 }
 
+// src/sync/connect-diagnostics.ts
+var SAFE_REASONS = /* @__PURE__ */ new Set([
+  "hello timeout",
+  "invalid token",
+  "policy violation",
+  "dependency unavailable",
+  "server draining",
+  "heartbeat timeout",
+  "normal",
+  "transport error",
+  "authentication failed",
+  "delivery recovery required",
+  "space action delivery recovery required",
+  "text frames only",
+  "unsupported protocol",
+  "invalid frame",
+  "WebSocket dial timeout",
+  "lifecycle transport deadline",
+  "lifecycle unavailable",
+  "invalid_frame",
+  "state_digest_mismatch",
+  "state_digest_recovery_failed",
+  "terminal event acknowledged",
+  "client stopped",
+  "participant inactive",
+  "terminal recovery"
+]);
+function safeSyncCloseReason(reason) {
+  return reason ? SAFE_REASONS.has(reason) ? reason : "redacted" : null;
+}
+function formatSyncConnectDiagnostic(diagnostic) {
+  return `[${diagnostic.stage}; open=${diagnostic.opened ? 1 : 0}; close=${diagnostic.closeCode ?? "none"}; reason=${safeSyncCloseReason(diagnostic.closeReason ?? void 0) ?? "none"}; ${Math.round(diagnostic.durationMs)}ms]`;
+}
+
+// src/sync/v1-health.ts
+var SYNC_HEALTH_BUDGET = {
+  probeIntervalMs: 500,
+  degradedAfterMs: 750,
+  recoveringAfterMs: 4e3,
+  stablePongsForMs: 2e3
+};
+var V1SyncHealth = class {
+  health = "healthy";
+  #lastPongAt;
+  #stableSince = null;
+  constructor(now) {
+    this.#lastPongAt = now;
+  }
+  observePong(now) {
+    this.check(now);
+    const gap = now - this.#lastPongAt;
+    this.#lastPongAt = now;
+    if (this.health === "healthy") return;
+    if (gap > SYNC_HEALTH_BUDGET.degradedAfterMs || this.#stableSince === null) this.#stableSince = now;
+    if (now - this.#stableSince >= SYNC_HEALTH_BUDGET.stablePongsForMs) {
+      this.health = "healthy";
+      this.#stableSince = null;
+    }
+  }
+  check(now) {
+    const silence = now - this.#lastPongAt;
+    if (silence >= SYNC_HEALTH_BUDGET.degradedAfterMs) this.#stableSince = null;
+    if (silence >= SYNC_HEALTH_BUDGET.recoveringAfterMs) this.health = "recovering";
+    else if (silence >= SYNC_HEALTH_BUDGET.degradedAfterMs && this.health === "healthy") this.health = "degraded";
+  }
+};
+
+// src/sync/dial-deadline.ts
+var SYNC_DIAL_TIMEOUT_MS = 1e4;
+function scheduleSyncDialDeadline(clock, onTimeout, timeoutMs = SYNC_DIAL_TIMEOUT_MS) {
+  const allowance = Number.isFinite(timeoutMs) ? Math.min(6e4, Math.max(SYNC_DIAL_TIMEOUT_MS, timeoutMs)) : SYNC_DIAL_TIMEOUT_MS;
+  const timer = clock.setTimeout(onTimeout, allowance);
+  return () => clock.clearTimeout(timer);
+}
+
 // src/generated/sync.ts
 import { Schema } from "effect";
 var SyncProtocolMetadata = {
@@ -225,7 +300,14 @@ var SyncProtocolMetadata = {
     field: "protocol",
     value: 1,
     transport: "websocket-json-text",
-    route: "/v1/sync"
+    route: "/v1/sync",
+    entryGeneration: {
+      queryParameter: "entry_generation",
+      newEntry: "new",
+      resume: "previous welcome entry_generation",
+      confirmation: "monotonic compare-and-set",
+      scope: "participant"
+    }
   },
   directions: {
     clientToServer: "client-to-server",
@@ -249,7 +331,7 @@ var SyncProtocolMetadata = {
     },
     {
       id: "live",
-      accepts: ["command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"],
+      accepts: ["entered", "command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"],
       heartbeat: {
         intervalMs: 2e4,
         missedDeadlinesBeforeClose: 2
@@ -529,7 +611,7 @@ var SyncProtocolMetadata = {
     {
       code: 1008,
       connection: "closed",
-      reasons: ["invalid token", "policy violation"]
+      reasons: ["invalid token", "policy violation", "entry timeout"]
     },
     {
       code: 1009,
@@ -701,6 +783,8 @@ function strictClientFrame(value) {
       return exactObject(value, ["type", "stream", "revision", "state_digest"]);
     case "recovery_ack":
       return exactObject(value, ["type", "recovery_id", "revision", "state_digest"]);
+    case "entered":
+      return exactObject(value, ["type"]);
     case "ping":
       return exactObject(value, ["type"]);
     default:
@@ -783,7 +867,8 @@ function strictWelcome(value) {
   const base = ["type", "protocol", "participant_id", "participant_generation", "recovery_id", "head", "mode"];
   const extension = Array.isArray(value.extensions) && value.extensions.length === 1 ? value.extensions[0] : void 0;
   const extensionValid = isObject(extension) && ["collaboration_v1", "collaboration_v2"].includes(String(extension.name)) && exactObject(extension, ["name", "capabilities", "participant_capabilities", "chat_head_sequence", "retained_floor_sequence", "read_receipts"]) && Array.isArray(extension.read_receipts);
-  const fields = extensionValid ? [...base, "extensions"] : base;
+  if (Object.hasOwn(value, "entry_confirmation") && value.entry_confirmation !== true) return false;
+  const fields = [...base, ...extensionValid ? ["extensions"] : [], ...Object.hasOwn(value, "entry_confirmation") ? ["entry_confirmation"] : [], ...Object.hasOwn(value, "entry_generation") ? ["entry_generation"] : []];
   if (!strictCursor(value.head)) return false;
   if (value.mode === "snapshot") return exactObjectWithCorrelation(value, [...fields, "snapshot"]) && strictSnapshot(value.snapshot);
   if (value.mode === "terminal") return exactObjectWithCorrelation(value, [...fields, "reason"]);
@@ -842,6 +927,8 @@ function strictServerFrame(value) {
       return exactObjectWithCorrelation(value, ["type", "command_id", "code"]);
     case "error":
       return exactObjectWithCorrelation(value, ["type", "code", "detail"]);
+    case "entered_ack":
+      return exactObjectWithCorrelation(value, ["type"]);
     case "pong":
       return exactObjectWithCorrelation(value, ["type"]);
     default:
@@ -1382,7 +1469,16 @@ var CollaborationWelcomeExtensionSchema = Schema.Struct({
   retained_floor_sequence: Schema.NullOr(UnsignedDecimalSchema),
   read_receipts: Schema.Array(ChatReadReceiptSchema).check(Schema.isMaxLength(500))
 }).check(exactKeys(["name", "capabilities", "participant_capabilities", "chat_head_sequence", "retained_floor_sequence", "read_receipts"]));
-var WelcomeBase = { type: Schema.Literal("welcome"), protocol: Schema.Literal(1), participant_id: UuidSchema, participant_generation: PositiveIntegerSchema, recovery_id: UuidSchema, head: ControlCursorSchema };
+var WelcomeBase = {
+  type: Schema.Literal("welcome"),
+  protocol: Schema.Literal(1),
+  participant_id: UuidSchema,
+  participant_generation: PositiveIntegerSchema,
+  recovery_id: UuidSchema,
+  head: ControlCursorSchema,
+  entry_confirmation: Schema.optionalKey(Schema.Literal(true)),
+  entry_generation: Schema.optionalKey(PositiveIntegerSchema.check(Schema.isLessThanOrEqualTo(9007199254740991)))
+};
 var ExtendedWelcomeBase = { ...WelcomeBase, extensions: Schema.Tuple([CollaborationWelcomeExtensionSchema]) };
 var WelcomeSnapshotFrameSchema = Schema.Struct({ ...WelcomeBase, mode: Schema.Literal("snapshot"), snapshot: SnapshotSchema, ...ServerCorrelationFields }).check(boundedServerFrame(SyncProtocolLimits.snapshotEncodedBytes));
 var WelcomeReplayFrameSchema = Schema.Struct({ ...WelcomeBase, mode: Schema.Literal("replay"), ...ServerCorrelationFields });
@@ -1558,6 +1654,8 @@ var RejectedChatReadResultFrameSchema = Schema.Struct({ type: Schema.Literal("ch
 var ChatReadResultFrameSchema = Schema.Union([AcceptedChatReadResultFrameSchema, RejectedChatReadResultFrameSchema]);
 var RetryableErrorFrameSchema = Schema.Struct({ type: Schema.Literal("retryable_error"), command_id: CommandIdSchema, code: RetryableErrorCodeSchema, ...ServerCorrelationFields });
 var ErrorFrameSchema = Schema.Struct({ type: Schema.Literal("error"), code: ProtocolErrorCodeSchema, detail: boundedUtf8String(1024), ...ServerCorrelationFields });
+var EnteredFrameSchema = Schema.Struct({ type: Schema.Literal("entered") });
+var EnteredAckFrameSchema = Schema.Struct({ type: Schema.Literal("entered_ack"), ...ServerCorrelationFields });
 var PingFrameSchema = Schema.Struct({ type: Schema.Literal("ping") });
 var PongFrameSchema = Schema.Struct({ type: Schema.Literal("pong"), ...ServerCorrelationFields });
 var SyncV1ClientFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) => strictClientFrame(frame) ? void 0 : { path: [], issue: "must not contain unknown or missing fields" })).pipe(
@@ -1591,6 +1689,7 @@ var SyncV1ClientFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) =>
       ChatReactionSetFrameSchema,
       DeliveryAckFrameSchema,
       RecoveryAckFrameSchema,
+      EnteredFrameSchema,
       PingFrameSchema
     ])
   )
@@ -1622,6 +1721,7 @@ var SyncV1ServerFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) =>
       ChatReactionResultFrameSchema,
       RetryableErrorFrameSchema,
       ErrorFrameSchema,
+      EnteredAckFrameSchema,
       PongFrameSchema
     ])
   )
@@ -1719,6 +1819,12 @@ var V1ReplicaError = class extends Error {
     this.name = "V1ReplicaError";
   }
 };
+var V1StateDigestMismatchError = class extends V1ReplicaError {
+  constructor() {
+    super("control state digest mismatch");
+    this.name = "V1StateDigestMismatchError";
+  }
+};
 async function restoreV1Snapshot(snapshot) {
   const state = snapshotToState(snapshot);
   assertV1ControlSemantics(state);
@@ -1832,7 +1938,7 @@ function durableProjection(state) {
   };
 }
 async function assertDigest(state) {
-  if (await computeV1StateDigest(state) !== state.stateDigest) throw new V1ReplicaError("control state digest mismatch");
+  if (await computeV1StateDigest(state) !== state.stateDigest) throw new V1StateDigestMismatchError();
 }
 function reduceEvent(state, event) {
   switch (event.name) {
@@ -1971,9 +2077,11 @@ function sameStrings2(left, right) {
 
 // src/sync/v1-collaboration-state.ts
 var MAX_COLLABORATION_REQUESTS_IN_FLIGHT = 64;
+var REACTION_ACK_TIMEOUT_MS = 5e3;
 var V1CollaborationState = class {
   #options;
   #listeners = /* @__PURE__ */ new Set();
+  #reactionTimers = /* @__PURE__ */ new Map();
   #reactions = /* @__PURE__ */ new Map();
   #chatSends = /* @__PURE__ */ new Map();
   #chatPages = /* @__PURE__ */ new Map();
@@ -2044,7 +2152,18 @@ var V1CollaborationState = class {
     this.#assertCapacity();
     const operationId = this.#nextRequestId();
     const frame = { type: "reaction_send", operation_id: operationId, reaction };
-    return this.#sendTrackedRequest(operationId, frame, this.#reactions);
+    const pending = this.#sendTrackedRequest(operationId, frame, this.#reactions);
+    this.#reactionTimers.set(
+      operationId,
+      this.#options.clock().setTimeout(() => {
+        this.#reactionTimers.delete(operationId);
+        const deferred = this.#reactions.get(operationId);
+        if (!deferred) return;
+        this.#reactions.delete(operationId);
+        rejectV1Deferred(deferred, new V1SyncError("Reaction acknowledgement timed out", "reaction_ack_timeout"));
+      }, REACTION_ACK_TIMEOUT_MS)
+    );
+    return pending;
   }
   sendChatMessage(input) {
     this.#assertReady("sendChat");
@@ -2108,6 +2227,8 @@ var V1CollaborationState = class {
     this.#requireNegotiated();
     const deferred = this.#reactions.get(frame.operation_id);
     if (!deferred) return;
+    this.#options.clock().clearTimeout(this.#reactionTimers.get(frame.operation_id));
+    this.#reactionTimers.delete(frame.operation_id);
     this.#reactions.delete(frame.operation_id);
     if (frame.outcome === "accepted") resolveV1Deferred(deferred, reactionFromFrame(frame.reaction));
     else rejectV1Deferred(deferred, new V1SyncError(frame.error_code, frame.error_code));
@@ -2178,6 +2299,8 @@ var V1CollaborationState = class {
     for (const deferred of this.#chatSends.values()) rejectV1Deferred(deferred, new V1SyncError(code, code));
     for (const deferred of this.#chatPages.values()) rejectV1Deferred(deferred, new V1SyncError(code, code));
     for (const deferred of this.#chatReads.values()) rejectV1Deferred(deferred, new V1SyncError(code, code));
+    for (const timer of this.#reactionTimers.values()) this.#options.clock().clearTimeout(timer);
+    this.#reactionTimers.clear();
     this.#reactions.clear();
     this.#chatSends.clear();
     this.#chatPages.clear();
@@ -2863,17 +2986,21 @@ var CLIENT_RESTART_CLOSE_CODE = 4e3;
 var DEFAULT_RECONNECT_DELAY_MS = 250;
 var MAX_RECONNECT_DELAY_MS = 5e3;
 var FAST_RECONNECT_ATTEMPTS = 8;
-var NOTICE_PROBE_INTERVAL_MS = 500;
-var NOTICE_SILENCE_MS = 750;
+var DIGEST_RECOVERY_COOLDOWN_MS = 6e4;
 var V1SyncClient = class {
   #options;
   #commandScheduler;
   #listeners = /* @__PURE__ */ new Set();
+  #mediaPauseListeners = /* @__PURE__ */ new Set();
   #requestListeners = /* @__PURE__ */ new Set();
   #collaborationState;
   #controlHeads = /* @__PURE__ */ new Map();
+  #snapshotRevision = null;
   #controlEvents = /* @__PURE__ */ new Map();
   #liveTargets;
+  #entryPending = false;
+  // Older Sync rejects new hello fields, so entry confirmation is requested on the URL and granted in welcome.
+  #entryNegotiated = false;
   #requests = /* @__PURE__ */ new Map();
   #mediaEventEvidence = /* @__PURE__ */ new Map();
   #presenceEventEvidence = /* @__PURE__ */ new Map();
@@ -2884,18 +3011,28 @@ var V1SyncClient = class {
   #presence = null;
   #participantId = null;
   #participantGeneration = null;
+  #entryGeneration = null;
   #recovery = null;
+  #snapshotRecoveryRequested = false;
+  #lastDigestRecoveryAt = null;
   #started = false;
   #startupGeneration = 0;
   #connectionGeneration = 0;
   #reconnectTimer;
+  #cancelDial;
+  #dialTimeoutCount = 0;
+  #connectStartedAt = null;
+  #opened = false;
+  #connectFailure;
+  #connectDiagnostic() {
+    return { stage: this.#opened ? "hello" : "upgrade", opened: this.#opened, closeCode: null, closeReason: null, durationMs: Math.max(0, this.#clock().now() - (this.#connectStartedAt ?? this.#clock().now())) };
+  }
   #reconnectAttempt = 0;
   #heartbeatTimer;
   #missedHeartbeats = 0;
   #noticeTimer;
   #noticeProbeTimer;
-  #noticeLastInboundAt = 0;
-  #noticeUnresponsive = false;
+  #health = new V1SyncHealth(0);
   #unsubscribeLifecycle;
   #inbound = Promise.resolve();
   #transportAvailable = true;
@@ -2935,6 +3072,7 @@ var V1SyncClient = class {
       stateChanged: () => this.#emit()
     });
     this.#collaborationState = new V1CollaborationState({
+      clock: () => this.#clock(),
       request: options.collaboration,
       requestIds: options.requestIds,
       maxPendingRequests: options.maxPendingCollaborationRequests,
@@ -2967,10 +3105,13 @@ var V1SyncClient = class {
   }
   stop() {
     this.#started = false;
+    this.#entryPending = false;
+    this.#entryGeneration = null;
     this.#startupGeneration += 1;
     this.#unsubscribeLifecycle?.();
     this.#unsubscribeLifecycle = void 0;
     this.#clearReconnect();
+    this.#clearDial();
     this.#clearHeartbeat();
     this.#clearNoticeProbe();
     this.#commandScheduler.stop("client_stopped");
@@ -2985,11 +3126,24 @@ var V1SyncClient = class {
     this.#liveTargets.resetLocalMedia();
     this.#emit();
   }
+  /** Announces completed startup; transport recovery resends until acknowledged. */
+  async confirmEntered() {
+    this.#requireLive();
+    this.#entryPending = true;
+    if (!this.#entryNegotiated) return;
+    this.#send({ type: "entered" });
+  }
   getSnapshot() {
     const pendingCommands = this.#commandScheduler.pendingCommands;
     const optimisticControl = this.#control && this.#participantId ? optimisticV1Control(this.#control, this.#participantId, pendingCommands) : this.#control;
     return {
-      connection: this.#phase.phase === "live" ? { ...this.#phase, noticeUnresponsive: this.#noticeUnresponsive } : { ...this.#phase },
+      connection: {
+        ...this.#phase,
+        ...this.#connectStartedAt !== null && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectAttempt: this.#connectDiagnostic() } : {},
+        ...this.#connectFailure && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectFailure: this.#connectFailure } : {},
+        ...this.#phase.phase === "live" ? { noticeUnresponsive: this.#health.health === "recovering", health: this.#health.health } : {},
+        ...this.#dialTimeoutCount ? { dialTimeoutCount: this.#dialTimeoutCount } : {}
+      },
       participantId: this.#participantId,
       participantGeneration: this.#participantGeneration,
       control: this.#control,
@@ -3006,6 +3160,16 @@ var V1SyncClient = class {
     listener(this.getSnapshot());
     return () => this.#listeners.delete(listener);
   }
+  onMediaPause(listener) {
+    this.#mediaPauseListeners.add(listener);
+    return () => this.#mediaPauseListeners.delete(listener);
+  }
+  #notifyMediaPause(event) {
+    const source = event.name === "participant_microphone_stopped" ? "microphone" : event.name === "participant_camera_stopped" ? "camera" : event.name === "participant_screen_share_stopped" ? "screen" : null;
+    if (source && "participant_id" in event.payload && event.payload.participant_id === this.#participantId) {
+      for (const listener of this.#mediaPauseListeners) listener({ source, revision: event.revision });
+    }
+  }
   onDirectedRequest(listener) {
     this.#requestListeners.add(listener);
     return () => this.#requestListeners.delete(listener);
@@ -3117,25 +3281,66 @@ var V1SyncClient = class {
     return promise;
   }
   #connect() {
-    if (!this.#started || !this.#transportAvailable || this.#socket) return;
+    if (!this.#started || !this.#transportAvailable || this.#socket || this.#phase.phase === "terminal") return;
     this.#phase = { phase: "connecting" };
+    this.#connectStartedAt = this.#clock().now();
+    this.#opened = false;
+    this.#connectFailure = void 0;
     this.#emit();
-    const socket = this.#options.webSocket.connect(this.#options.url);
+    this.#entryNegotiated = false;
+    let socket;
+    try {
+      socket = this.#options.webSocket.connect(entryUrl(this.#options.url, this.#entryGeneration, this.#options.entryConfirmation === true));
+    } catch {
+      this.#connectFailure = this.#connectDiagnostic();
+      this.#emit();
+      throw new V1SyncError("Sync WebSocket could not be created", "sync_hello_timeout");
+    }
     const connectionGeneration = ++this.#connectionGeneration;
     this.#socket = socket;
+    this.#cancelDial = scheduleSyncDialDeadline(
+      this.#clock(),
+      () => {
+        this.#cancelDial = void 0;
+        this.#dialTimeoutCount += 1;
+        this.#connectFailure = this.#connectDiagnostic();
+        this.#recover("WebSocket dial timeout");
+      },
+      this.#options.dialTimeoutMs
+    );
     socket.onopen = () => {
+      if (socket !== this.#socket) return;
+      this.#clearDial();
+      this.#opened = true;
+      this.#connectFailure = void 0;
       void this.#authenticate(socket);
     };
     socket.onmessage = (event) => {
       this.#inbound = this.#inbound.then(() => this.#receive(socket, event.data));
     };
-    socket.onclose = () => {
+    socket.onclose = (event) => {
+      if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
+        this.#connectFailure = { ...this.#connectDiagnostic(), closeCode: event.code, closeReason: safeSyncCloseReason(event.reason) };
+        this.#emit();
+      }
       this.#clock().setTimeout(() => {
         if (connectionGeneration !== this.#connectionGeneration) return;
-        this.#inbound = this.#inbound.then(() => this.#disconnected(socket));
+        this.#inbound = this.#inbound.then(() => {
+          if (socket === this.#socket && event.code === 1008 && (event.reason === "" || event.reason === "invalid token" || event.reason === "policy violation" || event.reason === "entry timeout")) {
+            this.#phase = { phase: "terminal", terminalReason: event.reason === "entry timeout" ? "entry_timeout" : "access_rejected" };
+            this.#emit();
+          }
+          this.#disconnected(socket);
+        });
       }, 0);
     };
-    socket.onerror = () => socket.close(CLIENT_RESTART_CLOSE_CODE, "transport error");
+    socket.onerror = () => {
+      if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
+        this.#connectFailure = this.#connectDiagnostic();
+        this.#emit();
+      }
+      socket.close(CLIENT_RESTART_CLOSE_CODE, "transport error");
+    };
   }
   async #authenticate(socket) {
     try {
@@ -3169,17 +3374,11 @@ var V1SyncClient = class {
     try {
       if (typeof data !== "string" || encoder3.encode(data).byteLength > SyncProtocolLimits.snapshotEncodedBytes) throw new V1ReplicaError("invalid inbound frame size");
       const frame = decodeV1ServerFrame(data);
-      if (this.#phase.phase === "live") {
-        this.#noticeLastInboundAt = this.#now();
-        this.#scheduleNoticeCheck();
-        if (this.#noticeUnresponsive) {
-          this.#noticeUnresponsive = false;
-          this.#emit();
-        }
-      }
       await this.#handleFrame(frame);
-    } catch {
-      this.#recover("invalid_frame");
+    } catch (error) {
+      if (this.#snapshotRecoveryRequested) this.#failDigestRecovery();
+      else if (error instanceof V1StateDigestMismatchError) this.#recoverDigestMismatch();
+      else this.#recover("invalid_frame");
     }
   }
   async #handleFrame(frame) {
@@ -3207,6 +3406,7 @@ var V1SyncClient = class {
           this.#control = await applyV1Event(this.#requireControl(), frame);
           this.#rememberControlHead(this.#control.revision, this.#control.stateDigest);
           this.#rememberControlEvent(frame);
+          this.#notifyMediaPause(frame);
         }
         await this.#commandScheduler.settleTerminalLifecycle(frame, this.#participantId);
         await this.#commandScheduler.settleProven();
@@ -3269,15 +3469,25 @@ var V1SyncClient = class {
         return;
       case "error":
         throw new V1ReplicaError(frame.code);
-      case "pong":
+      case "entered_ack":
+        this.#requireLive();
+        this.#entryPending = false;
+        return;
+      case "pong": {
         this.#requireLive();
         this.#missedHeartbeats = 0;
+        const previous = this.#health.health;
+        this.#health.observePong(this.#now());
+        if (previous !== this.#health.health) this.#emit();
         return;
+      }
     }
   }
   async #welcome(frame) {
     if (this.#phase.phase !== "recovering" || this.#recovery) throw new V1ReplicaError("unexpected welcome");
     this.#collaborationState.acceptWelcome(frame);
+    this.#entryNegotiated = frame.entry_confirmation === true;
+    this.#entryGeneration = frame.entry_generation ?? this.#entryGeneration;
     this.#participantId = frame.participant_id;
     this.#participantGeneration = frame.participant_generation;
     this.#updateLocalMediaStates();
@@ -3288,15 +3498,20 @@ var V1SyncClient = class {
       this.#emit();
       return;
     }
+    if (this.#snapshotRecoveryRequested && frame.mode !== "snapshot") throw new V1ReplicaError("digest recovery requires a full snapshot");
     if (frame.mode === "snapshot") {
-      this.#control = await restoreV1Snapshot(frame.snapshot);
+      const control = await restoreV1Snapshot(frame.snapshot);
+      if (!sameHead(control, frame.head)) throw new V1ReplicaError("snapshot head mismatch");
+      this.#control = control;
+      this.#snapshotRevision = control.revision;
+      this.#snapshotRecoveryRequested = false;
       this.#controlHeads.clear();
       this.#controlEvents.clear();
       this.#rememberControlHead(this.#control.revision, this.#control.stateDigest);
+      await this.#commandScheduler.settleProven();
     }
     if (frame.mode === "replay" && (!this.#control || this.#control.revision >= frame.head.revision)) throw new V1ReplicaError("invalid replay welcome");
     if (frame.mode === "up_to_date" && !sameHead(this.#control, frame.head)) throw new V1ReplicaError("up-to-date head mismatch");
-    if (frame.mode === "snapshot" && !sameHead(this.#control, frame.head)) throw new V1ReplicaError("snapshot head mismatch");
     this.#recovery = { id: frame.recovery_id, head: frame.head, replayEvents: 0, replayBytes: 0, controlComplete: false };
     if (frame.mode === "snapshot") this.#ackRecovery();
     this.#emit();
@@ -3311,6 +3526,7 @@ var V1SyncClient = class {
       this.#control = await applyV1Event(this.#requireControl(), event);
       this.#rememberControlHead(this.#control.revision, this.#control.stateDigest);
       this.#rememberControlEvent(event);
+      this.#notifyMediaPause(event);
     }
     this.#ackRecovery();
     this.#emit();
@@ -3390,8 +3606,11 @@ var V1SyncClient = class {
     if (!this.#recovery?.controlComplete || !this.#media || !this.#presence) return;
     this.#recovery = null;
     this.#phase = { phase: "live" };
+    this.#connectStartedAt = null;
+    this.#connectFailure = void 0;
     this.#reconnectAttempt = 0;
     this.#missedHeartbeats = 0;
+    if (this.#entryPending && this.#entryNegotiated) this.#send({ type: "entered" });
     this.#commandScheduler.enterLive();
     this.#liveTargets.enterLive();
     this.#startHeartbeat();
@@ -3404,7 +3623,7 @@ var V1SyncClient = class {
     this.#send({ type: "recovery_ack", recovery_id: recovery.id, revision: control.revision, state_digest: control.stateDigest });
   }
   #ackHeadIsProven(ack) {
-    return this.#controlHeads.get(ack.revision) === ack.state_digest;
+    return this.#snapshotRevision !== null && ack.revision < this.#snapshotRevision || this.#controlHeads.get(ack.revision) === ack.state_digest;
   }
   #rememberControlHead(revision, digest) {
     this.#controlHeads.set(revision, digest);
@@ -3423,6 +3642,7 @@ var V1SyncClient = class {
   #disconnected(socket) {
     if (socket !== this.#socket) return;
     this.#socket = null;
+    this.#clearDial();
     this.#recovery = null;
     this.#clearHeartbeat();
     this.#clearNoticeProbe();
@@ -3452,6 +3672,29 @@ var V1SyncClient = class {
     socket.close(CLIENT_RESTART_CLOSE_CODE, reason);
     this.#disconnected(socket);
   }
+  #recoverDigestMismatch() {
+    const now = this.#clock().now();
+    if (this.#lastDigestRecoveryAt !== null && now - this.#lastDigestRecoveryAt < DIGEST_RECOVERY_COOLDOWN_MS) {
+      this.#failDigestRecovery();
+      return;
+    }
+    this.#lastDigestRecoveryAt = now;
+    this.#snapshotRecoveryRequested = true;
+    this.#control = null;
+    this.#snapshotRevision = null;
+    this.#controlHeads.clear();
+    this.#controlEvents.clear();
+    this.#recover("state_digest_mismatch");
+  }
+  #failDigestRecovery() {
+    this.#phase = { phase: "terminal", terminalReason: "state_digest_recovery_failed" };
+    this.#clearReconnect();
+    this.#commandScheduler.stop("state_digest_recovery_failed");
+    const socket = this.#socket;
+    socket?.close(CLIENT_RESTART_CLOSE_CODE, "state_digest_recovery_failed");
+    if (socket) this.#disconnected(socket);
+    this.#emit();
+  }
   #handleLifecycle(event) {
     if (event === "online" || event === "offline") this.#online = event === "online";
     else this.#active = event === "active";
@@ -3500,6 +3743,10 @@ var V1SyncClient = class {
   #now() {
     return this.#clock().now();
   }
+  #clearDial() {
+    this.#cancelDial?.();
+    this.#cancelDial = void 0;
+  }
   #clearReconnect() {
     if (this.#reconnectTimer === void 0) return;
     this.#clock().clearTimeout(this.#reconnectTimer);
@@ -3557,33 +3804,29 @@ var V1SyncClient = class {
   }
   #startNoticeProbe() {
     this.#clearNoticeProbe();
-    this.#noticeLastInboundAt = this.#now();
-    this.#scheduleNoticeCheck();
+    this.#send({ type: "ping" });
+    this.#health = new V1SyncHealth(this.#now());
     const tick = () => {
       this.#noticeProbeTimer = void 0;
       if (this.#phase.phase !== "live") return;
+      const previous = this.#health.health;
+      this.#health.check(this.#now());
+      if (previous !== this.#health.health) this.#emit();
       this.#send({ type: "ping" });
-      this.#noticeProbeTimer = this.#clock().setTimeout(tick, NOTICE_PROBE_INTERVAL_MS);
+      this.#noticeProbeTimer = this.#clock().setTimeout(tick, SYNC_HEALTH_BUDGET.probeIntervalMs);
     };
-    this.#noticeProbeTimer = this.#clock().setTimeout(tick, NOTICE_PROBE_INTERVAL_MS);
-  }
-  #scheduleNoticeCheck() {
-    if (this.#noticeTimer !== void 0) this.#clock().clearTimeout(this.#noticeTimer);
-    const remaining = Math.max(0, NOTICE_SILENCE_MS - (this.#now() - this.#noticeLastInboundAt));
+    this.#noticeProbeTimer = this.#clock().setTimeout(tick, SYNC_HEALTH_BUDGET.probeIntervalMs);
     this.#noticeTimer = this.#clock().setTimeout(() => {
       this.#noticeTimer = void 0;
-      if (this.#phase.phase !== "live" || this.#noticeUnresponsive) return;
-      if (this.#now() - this.#noticeLastInboundAt < NOTICE_SILENCE_MS) return this.#scheduleNoticeCheck();
-      this.#noticeUnresponsive = true;
+      this.#health.check(this.#now());
       this.#emit();
-    }, remaining);
+    }, SYNC_HEALTH_BUDGET.degradedAfterMs);
   }
   #clearNoticeProbe() {
     if (this.#noticeTimer !== void 0) this.#clock().clearTimeout(this.#noticeTimer);
     if (this.#noticeProbeTimer !== void 0) this.#clock().clearTimeout(this.#noticeProbeTimer);
     this.#noticeTimer = void 0;
     this.#noticeProbeTimer = void 0;
-    this.#noticeUnresponsive = false;
   }
   #emit() {
     const snapshot = this.getSnapshot();
@@ -3626,6 +3869,12 @@ function copyPublication(publication) {
 function validMediaPublication(publication) {
   return typeof publication.participantId === "string" && publication.participantId.length > 0 && (publication.source === "microphone" || publication.source === "camera" || publication.source === "screen" || publication.source === "screen_audio") && typeof publication.enabled === "boolean" && (publication.publicationId === null || typeof publication.publicationId === "string") && (!publication.enabled || publication.publicationId !== null);
 }
+function entryUrl(value, generation, confirmation) {
+  const url = new URL(value);
+  url.searchParams.set("entry_generation", generation === null ? "new" : String(generation));
+  if (confirmation) url.searchParams.set("entry_confirmation", "1");
+  return url.toString();
+}
 function assertV1Url(value) {
   const url = new URL(value);
   if (url.pathname !== "/v1/sync") throw new V1SyncError("SyncEngine v1 websocket URL must use /v1/sync", "invalid_url");
@@ -3773,6 +4022,7 @@ function createV1SyncClient(options) {
 }
 
 export {
+  formatSyncConnectDiagnostic,
   UuidSchema,
   ReactionValues,
   ReactionSchema,
@@ -3786,6 +4036,7 @@ export {
   createBrowserSyncLifecycle,
   createReactNativeWebSocketFactory,
   createReactNativeSyncLifecycle,
+  scheduleSyncDialDeadline,
   encodeV1ClientFrame,
   decodeV1ServerFrame,
   decodeV1ClientFrame,