@jxsuite/collab 0.10.0 → 0.11.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kevin Shenk
+Copyright (c) 2026 Avunu LLC and Jx Suite contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
     "./awareness-types": "./src/awareness-types.ts",
     "./provider": "./src/provider.ts",
     "./client": "./src/ws-client.ts",
+    "./reconnect": "./src/reconnect.ts",
     "./room": "./src/ws-room.ts"
   },
   "publishConfig": {

package/src/negotiate.ts

@@ -55,9 +55,12 @@ export function negotiateCollab(probe: unknown): CollabNegotiation {
     // A 200 that is not a JSON object: pre-negotiation server. Connect as before, offering nothing.
     return { offer: [], refused: null };
   }
-  const body = probe as { collab?: unknown; protocols?: unknown };
+  const body = probe as { collab?: unknown; detail?: unknown; protocols?: unknown };
   if (body.collab === false) {
-    return { offer: [], refused: "This server has collaboration disabled." };
+    /* The server's own sentence wins when it sends one. "Disabled" is true of a flag that is off,
+       and false of a room an action would open: that server knows which it is and says so. */
+    const detail = typeof body.detail === "string" ? body.detail.trim() : "";
+    return { offer: [], refused: detail || "This server has collaboration disabled." };
   }
   const { protocols } = body;
   if (!Array.isArray(protocols) || protocols.length === 0) {

package/src/reconnect.ts

@@ -0,0 +1,164 @@
+/// <reference lib="dom" />
+/**
+ * Reconnect timing shared by every long-lived socket Studio holds: the collab socket
+ * (`ws-client.ts`) and the cloud session's `/events` stream
+ * (`packages/studio/src/platforms/cloud.ts`).
+ *
+ * **Jitter, because every client loses the socket at the same instant.** A gateway deploy or a
+ * relay restart drops every connected Studio together, and a plain doubling backoff brings them all
+ * back together too — at 1s, 2s, 4s, … in lockstep, so each retry wave lands on the server as one
+ * spike. Equal jitter ({@link backoffDelay}) keeps the doubling but spreads each wave across the
+ * upper half of its window, which keeps a floor under the delay (a retry never fires immediately on
+ * a server that is still down) while decorrelating the herd.
+ *
+ * **Wake triggers, because a timer is the wrong clock for a laptop.** A socket that dropped while
+ * the machine slept or the network was gone can be sitting in a 30-second wait when the network
+ * returns. The browser says so — `online`, a `pageshow` restored from the back/forward cache, a tab
+ * becoming visible — and {@link ReconnectScheduler.wake} turns any of them into a retry now. It
+ * only ever SHORTENS a pending wait: a socket that is open or mid-handshake is left alone, so a tab
+ * switch never tears down a healthy connection.
+ *
+ * This module imports nothing, deliberately: the cloud adapter reads it eagerly, before the dynamic
+ * import that pulls in Yjs, so it must not drag the CRDT into the initial bundle (the same
+ * constraint, and the same reason, as `negotiate.ts`).
+ */
+
+/** Backoff tuning. Every field is optional; the defaults are what production uses. */
+export interface ReconnectPolicy {
+  /** The first retry's window, in ms. Doubles per failed attempt. Default 1000. */
+  baseMs?: number;
+  /** The ceiling on any one window, in ms. Default 30 000. */
+  maxMs?: number;
+  /** Source of jitter in [0, 1]. Default `Math.random`; tests pin it. */
+  random?: () => number;
+}
+
+const DEFAULT_BASE_MS = 1000;
+const DEFAULT_MAX_MS = 30_000;
+
+/**
+ * The delay before retry number `attempt` (0-based), with **equal jitter**: half the capped window
+ * is fixed and the other half is random, so the result lies in `[cap / 2, cap]` where `cap =
+ * min(maxMs, baseMs × 2^attempt)`.
+ *
+ * Full jitter (`random × cap`) spreads the herd wider but can retry at ~0ms, which against a server
+ * that is still restarting is a wasted handshake per client; equal jitter keeps the floor.
+ */
+export function backoffDelay(attempt: number, policy: ReconnectPolicy = {}): number {
+  const base = policy.baseMs ?? DEFAULT_BASE_MS;
+  const max = policy.maxMs ?? DEFAULT_MAX_MS;
+  const random = policy.random ?? Math.random;
+  // `2 ** attempt` reaches Infinity long before an attempt counter overflows; `min` absorbs it.
+  const cap = Math.min(max, base * 2 ** Math.max(0, attempt));
+  return cap / 2 + (random() * cap) / 2;
+}
+
+/** The DOM surfaces the scheduler listens on (injectable for tests and non-browser runtimes). */
+export interface ReconnectWakeSources {
+  win?: Pick<Window, "addEventListener" | "removeEventListener">;
+  doc?: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener">;
+}
+
+export interface ReconnectScheduler {
+  /**
+   * The socket closed: arm one retry after the next backoff delay. A second call while a retry is
+   * already pending is a no-op, so a close that arrives twice cannot double the attempt count.
+   */
+  scheduleRetry: () => void;
+  /** The socket opened: the next failure starts the backoff from the first window again. */
+  opened: () => void;
+  /**
+   * Conditions changed (network back, page shown): if a retry is pending, run it NOW. A no-op when
+   * nothing is pending — the socket is open or a handshake is already in flight, and either way
+   * there is nothing to hurry.
+   */
+  wake: () => void;
+  /** Cancel any pending retry and remove every wake listener. Idempotent. */
+  dispose: () => void;
+}
+
+/**
+ * Drive `connect` through jittered backoff and the browser's wake signals.
+ *
+ * The caller owns the socket; this owns only WHEN `connect` runs again. The caller reports the two
+ * edges it sees — {@link ReconnectScheduler.opened} on `open`,
+ * {@link ReconnectScheduler.scheduleRetry} on `close` — and calls {@link ReconnectScheduler.dispose}
+ * when it is done with the socket for good.
+ */
+export function createReconnectScheduler(
+  connect: () => void,
+  opts: ReconnectPolicy & ReconnectWakeSources = {},
+): ReconnectScheduler {
+  const win =
+    opts.win ??
+    (typeof window === "undefined"
+      ? undefined
+      : (window as Pick<Window, "addEventListener" | "removeEventListener">));
+  const doc = opts.doc ?? (typeof document === "undefined" ? undefined : document);
+  let attempt = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let disposed = false;
+
+  const fire = () => {
+    timer = null;
+    if (!disposed) {
+      connect();
+    }
+  };
+
+  const wake = () => {
+    if (disposed || timer === null) {
+      return;
+    }
+    clearTimeout(timer);
+    /* The backoff that accumulated was measured against the conditions that just ended — an
+       offline laptop fails every attempt for as long as it is offline. Carrying it forward would
+       make the first failure after the network returns wait a full 30 seconds. */
+    attempt = 0;
+    fire();
+  };
+
+  const onPageShow = (event: Event) => {
+    // A fresh load is not a wake: only a page restored from the back/forward cache was frozen.
+    if ((event as PageTransitionEvent).persisted) {
+      wake();
+    }
+  };
+  const onVisibility = () => {
+    if (doc?.visibilityState === "visible") {
+      wake();
+    }
+  };
+
+  win?.addEventListener("online", wake);
+  win?.addEventListener("pageshow", onPageShow);
+  doc?.addEventListener("visibilitychange", onVisibility);
+
+  return {
+    dispose() {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      win?.removeEventListener("online", wake);
+      win?.removeEventListener("pageshow", onPageShow);
+      doc?.removeEventListener("visibilitychange", onVisibility);
+    },
+    opened() {
+      attempt = 0;
+    },
+    scheduleRetry() {
+      if (disposed || timer !== null) {
+        return;
+      }
+      const delay = backoffDelay(attempt, opts);
+      attempt += 1;
+      timer = setTimeout(fire, delay);
+    },
+    wake,
+  };
+}

package/src/ws-client.ts

@@ -1,8 +1,9 @@
 /**
  * The browser half of the wire envelope: one WebSocket per project, multiplexing every open
- * document. `createWsCollabConnection` owns the socket (exponential-backoff reconnect, re-open of
- * live docs on reconnect), the shared project-level Awareness, and per-doc sync state;
- * `openDoc(path)` hands out {@link CollabHandle}s for `StudioPlatform.collab`.
+ * document. `createWsCollabConnection` owns the socket (jittered-backoff reconnect with wake
+ * triggers, `reconnect.ts`; re-open of live docs on reconnect), the shared project-level Awareness,
+ * and per-doc sync state; `openDoc(path)` hands out {@link CollabHandle}s for
+ * `StudioPlatform.collab`.
  */
 
 import * as Y from "yjs";
@@ -16,6 +17,7 @@ import {
 } from "y-protocols/awareness";
 import * as syncProtocol from "y-protocols/sync";
 import { decodeFrame, encodeFrame } from "./envelope.ts";
+import { createReconnectScheduler } from "./reconnect.ts";
 import type { CollabFrame, ControlMessage } from "./envelope.ts";
 import type { CollabHandle, CollabIdentity, CollabStatus } from "./provider.ts";
 
@@ -52,8 +54,13 @@ export interface WsCollabConnectionOptions {
   hydratePath?: (path: string) => Promise<void>;
   /** Give up on an openDoc after this long (falls back to solo editing). */
   openTimeoutMs?: number;
-  /** Initial reconnect backoff (doubles to 30s). */
+  /** Initial reconnect backoff window (`ReconnectPolicy.baseMs`: doubles to 30s, equal jitter). */
   reconnectDelayMs?: number;
+  /**
+   * Jitter source for the reconnect backoff (`ReconnectPolicy.random`). Tests pin it so a retry's
+   * delay is exact; production leaves it to `Math.random`.
+   */
+  reconnectRandom?: () => number;
 }
 
 export interface WsCollabConnection {
@@ -99,8 +106,6 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
   let identity: CollabIdentity | null = null;
   let status: CollabStatus = "connecting";
   let destroyed = false;
-  let retryMs = options.reconnectDelayMs ?? 1000;
-  let retryTimer: ReturnType<typeof setTimeout> | null = null;
 
   const setStatus = (next: CollabStatus) => {
     if (status === next) {
@@ -262,10 +267,9 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
     entry.doc.destroy();
   };
 
+  /* No `destroyed` guard here: the only callers are the first connect below and the scheduler, and
+     `destroy()` disposes the scheduler, whose timer re-checks that before it calls back. */
   const connect = () => {
-    if (destroyed) {
-      return;
-    }
     setStatus("connecting");
     /* Re-offered on every reconnect: a socket that comes back after the server was restarted must
        negotiate again, and the offer is a property of this client's envelope, not of one socket. */
@@ -280,7 +284,7 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
        the injectable WsLike test surface minimal). */
     // oxlint-disable-next-line unicorn/prefer-add-event-listener
     ws.onopen = () => {
-      retryMs = options.reconnectDelayMs ?? 1000;
+      reconnect.opened();
       setStatus("connected");
       // Re-open every live doc and re-publish our awareness state.
       for (const path of docs.keys()) {
@@ -335,14 +339,17 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
       for (const entry of docs.values()) {
         entry.opened = false;
       }
-      retryTimer = setTimeout(connect, retryMs);
-      retryMs = Math.min(retryMs * 2, 30_000);
+      reconnect.scheduleRetry();
     };
     // oxlint-disable-next-line unicorn/prefer-add-event-listener
     ws.onerror = () => {
       // The close handler follows and owns retry.
     };
   };
+  const reconnect = createReconnectScheduler(connect, {
+    ...(options.reconnectDelayMs === undefined ? {} : { baseMs: options.reconnectDelayMs }),
+    ...(options.reconnectRandom === undefined ? {} : { random: options.reconnectRandom }),
+  });
   connect();
 
   return {
@@ -351,9 +358,7 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
         return;
       }
       destroyed = true;
-      if (retryTimer) {
-        clearTimeout(retryTimer);
-      }
+      reconnect.dispose();
       removeAwarenessStates(awareness, [awareness.clientID], "destroy");
       awareness.destroy();
       awarenessDoc.destroy();