@q9labsai/chalk-client 5.2.1 → 5.2.3

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

@@ -18,8 +18,9 @@ import {
   createBrowserWebSocketFactory,
   createV1SyncClient,
   formatSyncConnectDiagnostic,
-  scheduleSyncDialDeadline
-} from "./chunk-TVNI2XUZ.js";
+  scheduleSyncDialDeadline,
+  syncConnectFailureCode
+} from "./chunk-IMMT22US.js";
 
 // src/access/manager.ts
 import { Clock, Context, Data, Effect, Layer, SynchronizedRef } from "effect";
@@ -332,7 +333,8 @@ var WhiteboardV1ProtocolMetadata = {
   extensions: {
     presentation: {
       name: "presentation_v1",
-      exactFields: ["name"]
+      exactFields: ["name"],
+      presenterExactFields: ["name", "presenter"]
     },
     view: {
       name: "view_v1",
@@ -654,7 +656,7 @@ function isExtensions(value) {
   const drawPolicyLast = value.length > 0 && isExtension(value[value.length - 1], drawPolicy);
   const base = drawPolicyLast ? value.slice(0, -1) : value;
   if (base.length === 0) return drawPolicyLast;
-  return (base.length === 1 || base.length === 2) && isExtension(base[0], presentation) && (base.length === 1 || isExtension(base[1], view) || hasExactKeys(base[1], view.ownerExactFields) && base[1].name === view.name && base[1].origins === true && base[1].owner === true || hasExactKeys(base[1], view.extendedExactFields) && base[1].name === view.name && base[1].origins === true);
+  return (base.length === 1 || base.length === 2) && (isExtension(base[0], presentation) || hasExactKeys(base[0], presentation.presenterExactFields) && base[0].name === presentation.name && base[0].presenter === true) && (base.length === 1 || isExtension(base[1], view) || hasExactKeys(base[1], view.ownerExactFields) && base[1].name === view.name && base[1].origins === true && base[1].owner === true || hasExactKeys(base[1], view.extendedExactFields) && base[1].name === view.name && base[1].origins === true);
 }
 function isDrawPolicy(value) {
   return typeof value === "string" && WhiteboardV1ProtocolMetadata.drawPolicies.some((policy) => policy === value);
@@ -663,6 +665,10 @@ function isDrawGrant(value) {
   return hasExactKeys(value, WhiteboardV1ProtocolMetadata.frames.drawAccess.grantExactFields) && isUuid(value.participant_id) && typeof value.can_draw === "boolean";
 }
 function isWelcome(value) {
+  if ("presenter_id" in value) {
+    const { presenter_id, ...welcome } = value;
+    return (presenter_id === null || isUuid(presenter_id)) && isWelcome(welcome);
+  }
   if ("view_owner_id" in value) {
     const { view_owner_id, ...welcome } = value;
     return isUuid(view_owner_id) && isWelcome(welcome);
@@ -670,6 +676,13 @@ function isWelcome(value) {
   const exact = hasExactRecordKeys(value, WhiteboardV1ProtocolMetadata.frames.welcome.exactFields) || hasExactRecordKeys(value, WhiteboardV1ProtocolMetadata.frames.welcome.extendedExactFields) && typeof value.presenting === "boolean";
   return exact && value.protocol === "whiteboard-v1" && isUuid(value.participant_id) && Number.isSafeInteger(value.participant_generation) && Number(value.participant_generation) > 0 && isCapabilities(value.capabilities) && isCapabilities(value.participant_capabilities) && isUuid(value.scene_id) && isUnsignedDecimal(value.revision) && typeof value.can_draw === "boolean";
 }
+function isPresentationUpdated(value) {
+  if ("presenter_id" in value) {
+    const { presenter_id, ...frame } = value;
+    return (presenter_id === null || isUuid(presenter_id)) && isPresentationUpdated(frame);
+  }
+  return hasExactRecordKeys(value, WhiteboardV1ProtocolMetadata.frames.presentationUpdated.exactFields) && isUuid(value.scene_id) && isUnsignedDecimal(value.revision) && typeof value.presenting === "boolean";
+}
 function isServerFrame(value) {
   if (!isRecord2(value)) return false;
   switch (value.type) {
@@ -692,7 +705,7 @@ function isServerFrame(value) {
     case "draw_access":
       return hasExactKeys(value, WhiteboardV1ProtocolMetadata.frames.drawAccess.exactFields) && isDrawPolicy(value.policy) && typeof value.can_draw === "boolean" && isCapabilities(value.capabilities) && Array.isArray(value.grants) && value.grants.length <= WhiteboardV1ProtocolLimits.drawAccessMaxGrants && value.grants.every(isDrawGrant);
     case "presentation_updated":
-      return hasExactKeys(value, WhiteboardV1ProtocolMetadata.frames.presentationUpdated.exactFields) && isUuid(value.scene_id) && isUnsignedDecimal(value.revision) && typeof value.presenting === "boolean";
+      return isPresentationUpdated(value);
     case "reset_required":
       return hasExactKeys(value, WhiteboardV1ProtocolMetadata.frames.resetRequired.exactFields) && isUuid(value.scene_id) && typeof value.reason === "string" && WhiteboardV1ProtocolMetadata.resetReasons.some((reason) => reason === value.reason);
     case "operation_error":
@@ -1065,7 +1078,8 @@ var ChalkWhiteboardV1Client = class {
   #presentationSupported = false;
   #viewsSupported = false;
   #presenting = false;
-  #hello = "owner-view";
+  #presenterId = null;
+  #hello = "presenter-view";
   #viewSequence = 0;
   #viewOwnerId = null;
   #viewVersions = new ChalkWhiteboardViewVersions();
@@ -1118,7 +1132,7 @@ var ChalkWhiteboardV1Client = class {
     if (this.#started && this.#startPromise) return this.#startPromise;
     this.#started = true;
     globalThis.document?.addEventListener("visibilitychange", this.#visibilityChanged);
-    this.#hello = "owner-view";
+    this.#hello = "presenter-view";
     this.#rejectedHelloRetries = 0;
     this.#viewsSupported = false;
     this.#phase = "connecting";
@@ -1172,6 +1186,7 @@ var ChalkWhiteboardV1Client = class {
     this.#drawPolicy = null;
     this.#drawPermissions = [];
     this.#presenting = false;
+    this.#presenterId = null;
     this.#publishSummary("unsubscribed", null);
   }
   subscribe(listener) {
@@ -1488,6 +1503,7 @@ var ChalkWhiteboardV1Client = class {
         this.#sceneId = frame.scene_id;
         this.#revision = frame.revision;
         this.#presenting = frame.presenting;
+        this.#presenterId = frame.presenter_id ?? null;
         this.#publishSummary("ready", null);
         return;
       case "reset_required":
@@ -1560,7 +1576,13 @@ var ChalkWhiteboardV1Client = class {
     this.#drawPolicy = null;
     this.#drawPermissions = [];
     this.#presentationSupported = "presenting" in frame;
-    this.#presenting = "presenting" in frame ? frame.presenting : false;
+    if ("presenting" in frame) {
+      this.#presenting = frame.presenting;
+      this.#presenterId = frame.presenter_id ?? null;
+    } else {
+      this.#presenting = false;
+      this.#presenterId = null;
+    }
     const refused = !drawPolicyNegotiated(this.#hello) && this.#dropPolicyChanges();
     this.#publishSummary("loading", refused ? policyUnavailable() : null);
     this.#clearHeartbeat();
@@ -1864,7 +1886,7 @@ var ChalkWhiteboardV1Client = class {
     if (step === "fail") return false;
     if (step === "step-down") return this.#stepDownHello();
     if (step === "retry-hello") return this.#retryHello();
-    if (phase === "live") this.#hello = "owner-view";
+    if (phase === "live") this.#hello = "presenter-view";
     return true;
   }
   #stepDownHello() {
@@ -1988,6 +2010,7 @@ var ChalkWhiteboardV1Client = class {
       drawPolicy: this.#drawPolicy,
       drawPermissions: this.#drawPermissions,
       presenting: this.#presenting,
+      presenterId: this.#presenterId,
       error: this.#summaryError
     };
   }
@@ -2192,19 +2215,20 @@ function operationName(frame) {
 function retryableOperationCode(code) {
   return code === "unavailable" || code === "overloaded" || code === "rate_limited" || code === "storage_unavailable";
 }
-var HELLO_LEVELS = ["owner-view", "draw-policy", "versioned-view", "view", "presentation", "legacy"];
+var HELLO_LEVELS = ["presenter-view", "owner-view", "draw-policy", "versioned-view", "view", "presentation", "legacy"];
 function viewsNegotiated(level) {
-  return level === "owner-view" || level === "draw-policy" || level === "versioned-view" || level === "view";
+  return level === "presenter-view" || level === "owner-view" || level === "draw-policy" || level === "versioned-view" || level === "view";
 }
 function viewOriginsNegotiated(level) {
-  return level === "owner-view" || level === "draw-policy" || level === "versioned-view";
+  return level === "presenter-view" || level === "owner-view" || level === "draw-policy" || level === "versioned-view";
 }
 function drawPolicyNegotiated(level) {
-  return level === "owner-view" || level === "draw-policy";
+  return level === "presenter-view" || level === "owner-view" || level === "draw-policy";
 }
 function helloFrame(level, token, cursor) {
   const hello = { type: "hello", protocol: "whiteboard-v1", token, cursor };
   if (level === "legacy") return hello;
+  if (level === "presenter-view") return { ...hello, extensions: [{ name: "presentation_v1", presenter: true }, { name: "view_v1", origins: true, owner: true }, { name: "draw_policy_v1" }] };
   if (level === "presentation") return { ...hello, extensions: [{ name: "presentation_v1" }] };
   if (level === "view") return { ...hello, extensions: [{ name: "presentation_v1" }, { name: "view_v1" }] };
   if (level === "versioned-view") return { ...hello, extensions: [{ name: "presentation_v1" }, { name: "view_v1", origins: true }] };
@@ -2517,6 +2541,22 @@ var ConnectionDiagnostics = class {
     } catch {
     }
   }
+  recordRecoveryExhausted(input) {
+    const { state, epoch, code, attempts, transport } = input;
+    this.record({
+      event: "recovery_exhausted",
+      state,
+      epoch,
+      code,
+      recovery: {
+        reference: `connection.${code}`,
+        attempts,
+        transport,
+        lastHeartbeatReplyAgoMs: transport?.lastHeartbeatReplyAt == null ? null : Math.max(0, this.#now() - transport.lastHeartbeatReplyAt),
+        visibilityState: typeof document === "undefined" ? null : document.visibilityState
+      }
+    });
+  }
   snapshot() {
     return Object.freeze([...this.#events]);
   }
@@ -2551,7 +2591,7 @@ var ConnectionDiagnostics = class {
 
 // src/connection/lifecycle.ts
 var MEDIA_RECOVERY_TIMEOUT_MS = 6e4;
-var START_TIMEOUT_MS = 1e4;
+var START_TIMEOUT_MS = 3e4;
 var LEAVE_TIMEOUT_MS = 5e3;
 var RECOVERY_BUDGET_MS = 1e4;
 var MAX_RECOVERY_ATTEMPTS = 3;
@@ -2768,7 +2808,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
         const failure2 = snapshot.connection.connectFailure;
         if (failure2 && failure2 !== observedConnectFailure) {
           observedConnectFailure = failure2;
-          diagnostics.record({ event: "sync_connect_failed", state: model.state, epoch: model.epoch, code: "sync_hello_timeout", sync: failure2 });
+          diagnostics.record({ event: "sync_connect_failed", state: model.state, epoch: model.epoch, code: syncConnectFailureCode(failure2), sync: failure2 });
         }
         const count = snapshot.connection.dialTimeoutCount ?? 0;
         if (count > observedDialTimeouts) {
@@ -2844,7 +2884,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
       const span = diagnostics.startSpan({ step, state: model.state, epoch: model.epoch });
       return effect.pipe(
         Effect2.tap(() => Effect2.sync(() => span.end({ state: model.state, epoch: model.epoch, outcome: "succeeded" }))),
-        Effect2.tapError(() => Effect2.sync(() => span.end({ state: model.state, epoch: model.epoch, outcome: "failed" })))
+        Effect2.tapError((cause) => Effect2.sync(() => span.end({ state: model.state, epoch: model.epoch, outcome: "failed", code: failureFromCause(cause, "internal_error", "Connection step failed").code })))
       );
     };
     const confirmSyncEntry = (sync) => {
@@ -2921,7 +2961,7 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
         Effect2.matchEffect({
           onFailure: (cause) => Effect2.gen(function* () {
             stopStream(stream);
-            const failure2 = failureFromCause(cause, "sync_start_failed", "The Connection could not start");
+            const failure2 = failureFromCause(cause, "internal_error", "The Connection could not start");
             model.failure = toFailure(failure2);
             if (model.joinCancelled) {
               span.end({ state: model.state, epoch: model.epoch, outcome: "cancelled", code: "invalid_state" });
@@ -3048,7 +3088,8 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
           const syncAttempt = { client: null, expiresAt: null, started: true };
           while (model.epoch === epoch && active(model)) {
             const plan = yield* recoveryPlan(model.recoveryQueued ?? kind);
-            const outcome = yield* attemptRecovery(plan, mediaAttempt, syncAttempt).pipe(
+            let attempts = 0;
+            const outcome = yield* attemptRecovery(plan, mediaAttempt, syncAttempt, () => attempts++).pipe(
               Effect2.match({
                 onSuccess: (attempt) => ({ attempt, failure: null }),
                 onFailure: (failure2) => ({ attempt: null, failure: failure2 })
@@ -3066,9 +3107,18 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
             yield* enqueue(
               Effect2.gen(function* () {
                 if (model.epoch !== epoch || !active(model)) return;
+                if (plan.kind === "sync" && model.sync?.getSnapshot().connection.phase === "live") {
+                  model.recoveryQueued = "media";
+                  return;
+                }
                 const code = plan.kind === "media" ? "media_recovery_exhausted" : "sync_recovery_exhausted";
+                const transport = model.sync?.getSnapshot().connection.recoveryDiagnostic ?? null;
+                diagnostics.recordRecoveryExhausted({ state: model.state, epoch, code, attempts, transport });
+                if (plan.kind === "sync") {
+                  yield* failForSnapshot(lifecycleFailure(code, true, "Connection lost. Rejoin to continue."));
+                  return;
+                }
                 model.failure = toFailure(lifecycleFailure(code, true, "Connection interrupted. Reconnecting in the background."));
-                diagnostics.record({ event: "recovery_exhausted", state: model.state, epoch, code });
                 yield* publish();
               })
             );
@@ -3089,14 +3139,14 @@ var makeConnectionLifecycleLayerFromServices = (options) => Layer3.effect(
         delays: options.recovery?.backoffMs?.length ? options.recovery.backoffMs : [100, 250, 500]
       }))
     );
-    const attemptRecovery = (plan, mediaAttempt2, syncAttempt) => Effect2.gen(function* () {
+    const attemptRecovery = (plan, mediaAttempt2, syncAttempt, onAttempt) => Effect2.gen(function* () {
       for (let attempt = 1; attempt <= plan.attempts; attempt += 1) {
         const remaining = plan.deadline - (yield* Clock2.currentTimeMillis);
         if (remaining <= 0) return null;
+        onAttempt();
         diagnostics.record({ event: "recovery_attempt", state: model.state, epoch: model.epoch, attempt });
         const failure2 = yield* recoveryOperation(mediaAttempt2, syncAttempt).pipe(
-          Effect2.timeout(remaining),
-          Effect2.catchTag("TimeoutError", () => Effect2.fail(lifecycleFailure("sync_start_failed", true, "Connection recovery is still waiting for the transport"))),
+          (effect) => withinForegroundBudget(effect, remaining, lifecycleFailure("sync_start_failed", true, "Connection recovery is still waiting for the transport")),
           Effect2.match({ onSuccess: () => null, onFailure: (cause) => cause })
         );
         if (failure2 === null) return attempt;
@@ -3584,9 +3634,11 @@ function syncTerminalFailure(snapshot) {
   return lifecycleFailure("sync_start_failed", true, "The Sync transport needs recovery");
 }
 function syncStartupFailure(snapshot) {
-  const sync = snapshot.connection.connectFailure ?? snapshot.connection.connectAttempt;
+  const evidence = snapshot.connection.connectFailure ?? snapshot.connection.connectAttempt;
+  const attempts = snapshot.connection.connectAttempt?.attempt;
+  const sync = evidence ? { ...evidence, ...attempts === void 0 ? {} : { attempts } } : void 0;
   const message = sync?.opened === false ? "Sync could not reach the call service" : "Sync could not connect";
-  return new ConnectionLifecycleFailure({ code: "sync_hello_timeout", recoverable: true, message: `${message}${sync ? ` ${formatSyncConnectDiagnostic(sync)}` : " before the startup deadline"}`, ...sync ? { sync: Object.freeze({ ...sync }) } : {} });
+  return new ConnectionLifecycleFailure({ code: syncConnectFailureCode(sync), recoverable: true, message: `${message}${sync ? ` ${formatSyncConnectDiagnostic(sync)}` : " before the startup deadline"}`, ...sync ? { sync: Object.freeze({ ...sync }) } : {} });
 }
 function syncAutoRecoverable(snapshot, failure2) {
   return failure2.recoverable && snapshot.connection.terminalReason !== "entry_timeout";
@@ -3631,6 +3683,7 @@ var INVALID_PAYLOAD_CODE_BY_ACTION = /* @__PURE__ */ new Map([
 ]);
 var MEDIA_TIMEOUT_FAILURE = { code: "media.timeout", recoverable: true, message: "Media did not respond in time. Try again." };
 var SYNC_FAILURES = /* @__PURE__ */ new Map([
+  ["sync_start_failed", { failure: { code: "connection.sync_start_failed", recoverable: true, message: "A connection to the call service could not be opened. Try again." } }],
   ["sync_hello_timeout", { failure: { code: "connection.sync_hello_timeout", recoverable: true, message: "Sync could not reach the call service. Try again." } }],
   ["not_live", { failure: { code: "connection.invalid_state", recoverable: true, message: "Wait for the call to connect, then try again." } }],
   ["signaling_timeout", { failure: MEDIA_TIMEOUT_FAILURE }],
@@ -6233,6 +6286,7 @@ var WhiteboardControllerRuntime = class {
       drawPolicy: summary.drawPolicy,
       drawPermissions: Object.freeze(summary.drawPermissions.map((permission) => Object.freeze({ ...permission }))),
       presenting: summary.presenting,
+      presenterId: summary.presenterId ?? null,
       error: summary.error ? Object.freeze({ ...summary.error }) : null
     });
     this.#publish();
@@ -6251,7 +6305,7 @@ var WhiteboardControllerRuntime = class {
   #publish() {
     const slice = Object.freeze({
       open: this.#summary.status !== "unsubscribed",
-      engine: Object.freeze({ status: this.#summary.status, sceneId: this.#summary.sceneId, revision: this.#summary.revision, presenting: this.#summary.presenting, error: this.#summary.error }),
+      engine: Object.freeze({ status: this.#summary.status, sceneId: this.#summary.sceneId, revision: this.#summary.revision, presenting: this.#summary.presenting, presenterId: this.#summary.presenterId ?? null, error: this.#summary.error }),
       access: Object.freeze({ canDraw: this.#summary.canDraw, policy: this.#summary.drawPolicy, permissions: this.#summary.drawPermissions })
     });
     const current = this.#store.getSnapshot().whiteboard;
@@ -6260,7 +6314,7 @@ var WhiteboardControllerRuntime = class {
   }
 };
 function sameWhiteboard(left, right) {
-  return left.open === right.open && left.engine.status === right.engine.status && left.engine.sceneId === right.engine.sceneId && left.engine.revision === right.engine.revision && left.engine.presenting === right.engine.presenting && sameError2(left.engine.error, right.engine.error) && sameAccess(left.access, right.access);
+  return left.open === right.open && left.engine.status === right.engine.status && left.engine.sceneId === right.engine.sceneId && left.engine.revision === right.engine.revision && left.engine.presenting === right.engine.presenting && left.engine.presenterId === right.engine.presenterId && sameError2(left.engine.error, right.engine.error) && sameAccess(left.access, right.access);
 }
 function sameAccess(left, right) {
   return left.canDraw === right.canDraw && left.policy === right.policy && left.permissions.length === right.permissions.length && left.permissions.every((permission, index) => permission.participantId === right.permissions[index]?.participantId && permission.canDraw === right.permissions[index]?.canDraw);
@@ -6355,7 +6409,9 @@ var makeSpaceClientCoreLayer = (options, platform = {}) => {
     diagnostics: {
       onEvent: (event) => {
         platform.onConnectionDiagnostic?.(event);
-        options.logger?.debug?.("SpaceClient connection event", { event: event.event, state: event.state, epoch: event.epoch, ...event.code ? { code: event.code } : {}, ...event.sync ? { sync: event.sync } : {} });
+        const attributes = { event: event.event, state: event.state, epoch: event.epoch, ...event.code ? { code: event.code } : {}, ...event.sync ? { sync: event.sync } : {}, ...event.recovery ? { recovery: event.recovery } : {} };
+        if (event.event === "recovery_exhausted") options.logger?.warn?.("SpaceClient connection event", attributes);
+        else options.logger?.debug?.("SpaceClient connection event", attributes);
       }
     }
   });

package/dist/{chunk-TVNI2XUZ.js → chunk-IMMT22US.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, reason: event.reason }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -178,7 +178,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, reason: typeof event.reason === "string" ? event.reason : void 0 });
+    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006, reason: typeof event.reason === "string" ? event.reason : void 0, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} });
     this.#socket.onerror = () => this.onerror?.();
   }
   send(data) {
@@ -198,7 +198,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, reason: event.reason }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -249,8 +249,11 @@ var SAFE_REASONS = /* @__PURE__ */ new Set([
 function safeSyncCloseReason(reason) {
   return reason ? SAFE_REASONS.has(reason) ? reason : "redacted" : null;
 }
+function syncConnectFailureCode(diagnostic) {
+  return diagnostic?.stage === "upgrade" ? "sync_start_failed" : "sync_hello_timeout";
+}
 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]`;
+  return `[${diagnostic.stage}; open=${diagnostic.opened ? 1 : 0}; close=${diagnostic.closeCode ?? "none"}; reason=${safeSyncCloseReason(diagnostic.closeReason ?? void 0) ?? "none"}; ${diagnostic.stage === "upgrade" && diagnostic.closeCode !== null ? "cause=closed_before_open; " : ""}${diagnostic.attempt === void 0 ? "" : `attempt=${diagnostic.attempt}; `}${diagnostic.attempts === void 0 ? "" : `attempts=${diagnostic.attempts}; `}${Math.round(diagnostic.durationMs)}ms]`;
 }
 
 // src/sync/v1-health.ts
@@ -336,7 +339,7 @@ var SyncProtocolMetadata = {
       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
+        missedDeadlinesBeforeClose: 5
       }
     },
     {
@@ -3024,10 +3027,14 @@ var V1SyncClient = class {
   #cancelDial;
   #dialTimeoutCount = 0;
   #connectStartedAt = null;
+  #connectAttemptCount = 0;
+  #socketCloses = [];
+  #omittedSocketCloses = 0;
+  #lastHeartbeatReplyAt = 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())) };
+    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())), attempt: this.#connectAttemptCount };
   }
   #reconnectAttempt = 0;
   #episodeEndTimer;
@@ -3090,6 +3097,11 @@ var V1SyncClient = class {
   async start() {
     if (this.#started) return;
     this.#started = true;
+    this.#connectAttemptCount = 0;
+    this.#socketCloses = [];
+    this.#omittedSocketCloses = 0;
+    this.#lastHeartbeatReplyAt = null;
+    this.#connectFailure = void 0;
     const startupGeneration = ++this.#startupGeneration;
     let stored;
     try {
@@ -3144,6 +3156,7 @@ var V1SyncClient = class {
     return {
       connection: {
         ...this.#phase,
+        recoveryDiagnostic: { socketAttempts: this.#connectAttemptCount, socketCloses: this.#socketCloses.slice(), omittedSocketCloses: this.#omittedSocketCloses, lastHeartbeatReplyAt: this.#lastHeartbeatReplyAt },
         ...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 } : {},
@@ -3288,9 +3301,10 @@ var V1SyncClient = class {
   #connect() {
     if (!this.#started || !this.#transportAvailable || this.#socket || this.#phase.phase === "terminal") return;
     this.#phase = { phase: "connecting" };
+    this.#connectAttemptCount += 1;
     this.#connectStartedAt = this.#clock().now();
     this.#opened = false;
-    this.#connectFailure = void 0;
+    if (this.#connectFailure?.opened) this.#connectFailure = void 0;
     this.#emit();
     this.#entryNegotiated = false;
     let socket;
@@ -3299,7 +3313,7 @@ var V1SyncClient = class {
     } catch {
       this.#connectFailure = this.#connectDiagnostic();
       this.#emit();
-      throw new V1SyncError("Sync WebSocket could not be created", "sync_hello_timeout");
+      throw new V1SyncError("Sync WebSocket could not be created", "sync_start_failed");
     }
     const connectionGeneration = ++this.#connectionGeneration;
     this.#socket = socket;
@@ -3324,6 +3338,13 @@ var V1SyncClient = class {
       this.#inbound = this.#inbound.then(() => this.#receive(socket, event.data));
     };
     socket.onclose = (event) => {
+      if (this.#started) {
+        this.#socketCloses.push({ code: event.code, wasClean: event.wasClean ?? null });
+        if (this.#socketCloses.length > 50) {
+          this.#socketCloses.shift();
+          this.#omittedSocketCloses += 1;
+        }
+      }
       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();
@@ -3341,7 +3362,7 @@ var V1SyncClient = class {
     };
     socket.onerror = () => {
       if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
-        this.#connectFailure = this.#connectDiagnostic();
+        this.#connectFailure ??= this.#connectDiagnostic();
         this.#emit();
       }
       socket.close(CLIENT_RESTART_CLOSE_CODE, "transport error");
@@ -3494,6 +3515,7 @@ var V1SyncClient = class {
       case "pong": {
         this.#requireLive();
         this.#missedHeartbeats = 0;
+        this.#lastHeartbeatReplyAt = this.#now();
         const previous = this.#health.health;
         this.#health.observePong(this.#now());
         if (previous !== this.#health.health) this.#emit();
@@ -4046,6 +4068,7 @@ function createV1SyncClient(options) {
 }
 
 export {
+  syncConnectFailureCode,
   formatSyncConnectDiagnostic,
   UuidSchema,
   ReactionValues,

package/dist/connection/diagnostics.d.ts

@@ -32,6 +32,13 @@ export type ConnectionDiagnostic = {
     readonly outcome?: ConnectionJoinTraceOutcome;
     readonly durationMs?: number;
     readonly sync?: import("../sync/connect-diagnostics").SyncConnectDiagnostic;
+    readonly recovery?: {
+        readonly reference: "connection.sync_recovery_exhausted" | "connection.media_recovery_exhausted";
+        readonly attempts: number;
+        readonly transport: import("../sync/connect-diagnostics").SyncRecoveryDiagnostic | null;
+        readonly lastHeartbeatReplyAgoMs: number | null;
+        readonly visibilityState: DocumentVisibilityState | null;
+    };
 };
 export declare class ConnectionDiagnostics {
     #private;
@@ -41,6 +48,13 @@ export declare class ConnectionDiagnostics {
         readonly onEvent?: (event: ConnectionDiagnostic) => void;
     });
     record(input: Omit<ConnectionDiagnostic, "timestamp">): void;
+    recordRecoveryExhausted(input: {
+        readonly state: ConnectionState;
+        readonly epoch: number;
+        readonly code: "sync_recovery_exhausted" | "media_recovery_exhausted";
+        readonly attempts: number;
+        readonly transport: import("../sync/connect-diagnostics").SyncRecoveryDiagnostic | null;
+    }): void;
     snapshot(): readonly ConnectionDiagnostic[];
     startSpan(input: {
         readonly step: ConnectionJoinTraceStep;

package/dist/effect.js

@@ -17,7 +17,7 @@ import {
   makeSpaceClientCoreLayer,
   makeSpaceClientCoreLayerFromServices,
   makeSpaceStoreLayer
-} from "./chunk-RVUN6LW4.js";
+} from "./chunk-4ZUN55Z2.js";
 import "./chunk-DWKTGBHR.js";
 import {
   APIKeyListSchema,
@@ -829,7 +829,7 @@ import {
   WhiteboardStorageUnavailableErrorWireSchema,
   createChalkEffectClient
 } from "./chunk-GA3JDPFI.js";
-import "./chunk-TVNI2XUZ.js";
+import "./chunk-IMMT22US.js";
 
 // src/space-client/effect.ts
 import { Context, Effect, Exit, Layer, Scope } from "effect";

package/dist/generated/sync.d.ts

@@ -37,7 +37,7 @@ export declare const SyncProtocolMetadata: {
         readonly accepts: readonly ["entered", "command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"];
         readonly heartbeat: {
             readonly intervalMs: 20000;
-            readonly missedDeadlinesBeforeClose: 2;
+            readonly missedDeadlinesBeforeClose: 5;
         };
     }, {
         readonly id: "terminal";

package/dist/generated/whiteboard-v1.d.ts

@@ -11,6 +11,7 @@ export declare const WhiteboardV1ProtocolMetadata: {
         readonly presentation: {
             readonly name: "presentation_v1";
             readonly exactFields: readonly ["name"];
+            readonly presenterExactFields: readonly ["name", "presenter"];
         };
         readonly view: {
             readonly name: "view_v1";
@@ -258,6 +259,7 @@ export type WhiteboardV1SharedAppState = {
 } | null;
 export type WhiteboardV1PresentationExtension = {
     readonly name: "presentation_v1";
+    readonly presenter?: true;
 };
 export type WhiteboardV1ViewExtension = {
     readonly name: "view_v1";
@@ -388,6 +390,7 @@ export type WhiteboardV1ServerFrame = {
     readonly revision: string;
     readonly can_draw: boolean;
     readonly presenting: boolean;
+    readonly presenter_id?: string | null;
     readonly view_owner_id?: string;
 } | {
     readonly type: "snapshot_page";
@@ -451,6 +454,7 @@ export type WhiteboardV1ServerFrame = {
     readonly scene_id: string;
     readonly revision: string;
     readonly presenting: boolean;
+    readonly presenter_id?: string | null;
 } | {
     readonly type: "reset_required";
     readonly scene_id: string;

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from "./sync";
 export * from "./whiteboard";
 export * from "./public-invites";
 export { formatSyncConnectDiagnostic } from "./sync/connect-diagnostics";
+export { getConnectionFailureDetail } from "./space-client/failure-detail";

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   createSpaceClient,
   decodeWhiteboardV1ServerFrame,
   encodeWhiteboardV1ClientFrame
-} from "./chunk-RVUN6LW4.js";
+} from "./chunk-4ZUN55Z2.js";
 import {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -69,7 +69,7 @@ import {
   optimisticV1Control,
   reactionFromFrame,
   restoreV1Snapshot
-} from "./chunk-TVNI2XUZ.js";
+} from "./chunk-IMMT22US.js";
 
 // src/space-client/reload-rejoin.ts
 import { Schema } from "effect";
@@ -115,6 +115,23 @@ function reloadRejoinAccess(access) {
   const parsed = parseParsedAccessGrant(access);
   return { tenantId: parsed.subject.tenantId, episodeId: parsed.subject.episodeId, participantId: parsed.subject.participantId, participantGeneration: parsed.subject.participantGeneration, mediaProof: parsed.media.token };
 }
+
+// src/space-client/failure-detail.ts
+var DEFAULT_FAILURE_DETAIL = "Something went wrong while joining. Try again.";
+var FAILURE_DETAILS = {
+  "access.invalid": "Access to this call was rejected. Refresh the page and try again.",
+  "access.unavailable": "Couldn\u2019t get access to the call. Try again.",
+  "connection.sync_start_failed": "Couldn\u2019t reach the call service. Try again.",
+  "connection.sync_hello_timeout": "The call service did not respond in time. Try again.",
+  "connection.sync_recovery_exhausted": "You\u2019re disconnected from the call. Rejoin to continue.",
+  "connection.media_start_failed": "Audio and video could not connect. Try again.",
+  "connection.media_recovery_exhausted": "Audio and video could not reconnect. Try again.",
+  "environment.unsupported": "This device cannot start the call. Use an up-to-date browser over HTTPS, or update the app."
+};
+function getConnectionFailureDetail({ code, sync }) {
+  if (sync?.stage === "upgrade") return sync.closeCode !== null ? "The connection closed before the call service could be reached. Try again." : "A connection to the call service could not be opened. Try again.";
+  return (code && FAILURE_DETAILS[code]) ?? DEFAULT_FAILURE_DETAIL;
+}
 export {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
@@ -166,6 +183,7 @@ export {
   encodeV1ClientFrame,
   encodeWhiteboardV1ClientFrame,
   formatSyncConnectDiagnostic,
+  getConnectionFailureDetail,
   optimisticV1Control,
   parseCloudflareSFUPublicationID,
   parseInviteCode,

package/dist/space-client/failure-detail.d.ts

@@ -0,0 +1,6 @@
+import type { ClientFailure, ErrorCode } from "./types";
+/** Safe, actionable failure copy shared by web and native call screens. */
+export declare function getConnectionFailureDetail({ code, sync }: {
+    readonly code?: ErrorCode;
+    readonly sync?: ClientFailure["sync"];
+}): string;

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

@@ -203,6 +203,7 @@ export type WhiteboardSlice = {
         readonly sceneId: string | null;
         readonly revision: string | null;
         readonly presenting: boolean;
+        readonly presenterId?: string | null;
         readonly error: ChalkWhiteboardV1Failure | null;
     };
     /** Who can draw, as Sync last told this person. `canDraw` is false until the board subscription is live. */

package/dist/sync/connect-diagnostics.d.ts

@@ -1,3 +1,13 @@
+/** Transport facts only. No URLs, close reasons, payloads, or identities. */
+export type SyncRecoveryDiagnostic = {
+    readonly socketAttempts: number;
+    readonly socketCloses: readonly {
+        readonly code: number;
+        readonly wasClean: boolean | null;
+    }[];
+    readonly omittedSocketCloses: number;
+    readonly lastHeartbeatReplyAt: number | null;
+};
 /** Browsers expose only upgrade/open and hello, never DNS/TCP/TLS progress. */
 export type SyncConnectDiagnostic = {
     readonly stage: "upgrade" | "hello";
@@ -5,6 +15,12 @@ export type SyncConnectDiagnostic = {
     readonly closeCode: number | null;
     readonly closeReason: string | null;
     readonly durationMs: number;
+    /** One-based socket attempt since Sync start; absent in older SDK evidence. */
+    readonly attempt?: number;
+    /** Total sockets started when the join failed, including a pending replacement. */
+    readonly attempts?: number;
 };
 export declare function safeSyncCloseReason(reason: string | undefined): string | null;
+/** Keep published error codes stable while separating upgrade from hello failures. */
+export declare function syncConnectFailureCode(diagnostic: SyncConnectDiagnostic | undefined): "sync_start_failed" | "sync_hello_timeout";
 export declare function formatSyncConnectDiagnostic(diagnostic: SyncConnectDiagnostic): string;

package/dist/sync/index.js

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

package/dist/sync/react-native.d.ts

@@ -7,6 +7,7 @@ export type ReactNativeAsyncStorage = {
 export type ReactNativeWebSocketCloseEvent = {
     readonly code?: unknown;
     readonly reason?: unknown;
+    readonly wasClean?: unknown;
 };
 export type ReactNativeWebSocket = {
     onopen: ((event: unknown) => void) | null;

package/dist/sync/types.d.ts

@@ -10,6 +10,7 @@ export type SyncSocket = {
     onclose: ((event: {
         readonly code: number;
         readonly reason?: string;
+        readonly wasClean?: boolean;
     }) => void) | null;
     onerror: (() => void) | null;
     send(data: string): void;

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

@@ -81,6 +81,7 @@ export type V1EpisodeSnapshot = {
         readonly dialTimeoutCount?: number;
         readonly connectAttempt?: import("./connect-diagnostics").SyncConnectDiagnostic;
         readonly connectFailure?: import("./connect-diagnostics").SyncConnectDiagnostic;
+        readonly recoveryDiagnostic?: import("./connect-diagnostics").SyncRecoveryDiagnostic;
     };
     readonly participantId: string | null;
     readonly participantGeneration: number | null;

package/dist/whiteboard/types.d.ts

@@ -179,6 +179,8 @@ export type ChalkWhiteboardSummary = {
     readonly drawPolicy: ChalkWhiteboardDrawPolicy | null;
     /** The host's per-person choices for people in the call. Empty unless this person is a host. */
     readonly drawPermissions: readonly ChalkWhiteboardDrawPermission[];
+    /** The person who opened the current presentation; absent on older servers. */
+    readonly presenterId?: string | null;
     readonly presenting: boolean;
     readonly error: ChalkWhiteboardV1Failure | null;
 };

package/package.json

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