@jxsuite/collab 0.9.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/README.md

@@ -24,7 +24,7 @@ The CRDT granularity deliberately equals Studio's op-log granularity: mutators e
 - `applyDocOpsToY(doc, ops, origin)` replays Studio's recorded forward `JxDocOp`s onto the Y tree in one origin-tagged transaction (`LOCAL_ORIGIN` for user edits, `MIRROR_ORIGIN` for derived writes, `SEED_ORIGIN` for bootstraps).
 - `yEventsToDocOps(events)` converts a remote transaction's deep events back into `JxDocOp`s. Call it **inside** the `observeDeep` callback. It returns `null` for shapes it cannot convert safely; reconcile by diffing instead.
 - `diffDocs(a, b)` produces ops transforming `a` into `b` (invariant: `apply(clone(a), diff(a,b)) ≡ b`); returns `null` past `maxOps`, in which case `replaceYStructure()` hard-replaces and bumps `meta.canonicalRev` so stale mirror writes are discarded.
-- `applyDocOpToDoc` (in `./ops`, yjs-free) is the canonical plain-JSON applier shared with Studio's history replay and canvas shadow doc.
+- `applyDocOpToDoc`, `inverseOf` and `applyDocOpsWithInverse` (in `./ops`, yjs-free) re-export the canonical plain-JSON op vocabulary from `@jxsuite/schema/doc-ops`, shared with Studio's history replay and the canvas shadow doc, so a host without yjs can apply the same ops.
 
 ## The wire envelope (`./envelope`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.9.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": {
@@ -34,9 +35,9 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.2.0",
-    "lib0": "^0.2.117",
+    "@jxsuite/schema": "^2.3.0",
+    "lib0": "^0.2.119",
     "y-protocols": "^1.0.7",
-    "yjs": "13.6.32"
+    "yjs": "13.6.33"
   }
 }

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/ops.ts

@@ -1,128 +1,16 @@
 /**
- * The canonical Jx document-op vocabulary and its pure applier. A `JxDocOp` is a value-carrying,
- * replayable mutation of a plain-JSON Jx document tree, addressed by `JxPath` (alternating
- * "children" / index segments for structure, plus node keys). Studio's transaction pipeline records
- * forward/inverse pairs of these for history replay; the collab bridge mirrors them into a shared
- * Y.Doc.
+ * The Jx document-op vocabulary, re-exported from its home in `@jxsuite/schema/doc-ops`.
  *
- * This module is deliberately yjs-free and dependency-light: the slim canvas-iframe bundle imports
- * the applier for its non-reactive shadow doc, and it MUST stay byte-identical in behavior to the
- * parent's history replay — both sides import this one implementation.
+ * It moved so a host with no yjs (a Durable Object, a headless tool) can edit a document the way
+ * Studio does. This subpath stays so every existing `@jxsuite/collab/ops` import keeps working.
  */
 
-import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
-
-/** Value-carrying document mutation, replayable in either direction. */
-export type JxDocOp =
-  /** Set (or delete, when value is undefined) a key on the node at path. */
-  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
-  /** Insert a node at parentPath.children[index]. */
-  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Remove parentPath.children[index]. */
-  | { op: "remove-child"; parentPath: JxPath; index: number }
-  /** Replace parentPath.children[index] with node. */
-  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
-  | {
-      op: "move-child";
-      fromParentPath: JxPath;
-      fromIndex: number;
-      toParentPath: JxPath;
-      toIndex: number;
-    };
-
-export interface JxDocOpPair {
-  forward: JxDocOp;
-  inverse: JxDocOp;
-}
-
-/** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
-function jsonClone<T>(value: T): T {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-/** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
-export function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
-}
-
-/**
- * Walk a plain document tree by path. Paths address nodes by construction; missing segments and
- * non-node leaves surface as undefined (typed as node for caller ergonomics, matching Studio's
- * historical helper).
- */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode {
-  let node = doc;
-  for (const key of path) {
-    if (node == null) {
-      return undefined as unknown as JxMutableNode;
-    }
-    node = node[key] as JxMutableNode;
-  }
-  return node;
-}
-
-/** The node's children array, lazily created; throws if `node` is itself a children array or mapped. */
-export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
-  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
-  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
-  // Nothing renders. Callers must pass a node; fail loudly if they don't.
-  if (Array.isArray(node)) {
-    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
-  }
-  if (!node.children) {
-    node.children = [];
-  }
-  if (!Array.isArray(node.children)) {
-    throw new TypeError("Cannot insert into mapped-array children; edit the map template instead");
-  }
-  return node.children;
-}
-
-/**
- * Apply a replayable doc op to a bare document tree. Values/nodes are cloned in, so the tree never
- * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
- */
-export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
-  switch (op.op) {
-    case "set-key": {
-      const node = getNodeAtPath(doc, op.path);
-      if (!node) {
-        throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
-      }
-      const target = node as Record<string, unknown>;
-      if (op.value === undefined) {
-        delete target[op.key];
-      } else {
-        target[op.key] = cloneValue(op.value);
-      }
-      return;
-    }
-    case "insert-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "remove-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1);
-      return;
-    }
-    case "set-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "move-child": {
-      const fromParent = getNodeAtPath(doc, op.fromParentPath);
-      const toParent = getNodeAtPath(doc, op.toParentPath);
-      const [node] = childArray(fromParent).splice(op.fromIndex, 1);
-      childArray(toParent).splice(op.toIndex, 0, node!);
-      return;
-    }
-    default: {
-      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
-    }
-  }
-}
+export {
+  applyDocOpToDoc,
+  applyDocOpsWithInverse,
+  childArray,
+  cloneValue,
+  getNodeAtPath,
+  inverseOf,
+} from "@jxsuite/schema/doc-ops";
+export type { JxDocOp, JxDocOpPair } from "@jxsuite/schema/doc-ops";

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();