@liveblocks/core 3.24.1 → 3.24.3-livetextreplay

package/dist/index.d.cts

@@ -431,6 +431,11 @@ type UpdateTextOp = {
     readonly baseVersion: number;
     readonly version?: number;
     readonly ops: TextOperation[];
+    /** Server-only: accepted ops after the requested base version when reconciling. */
+    readonly history?: {
+        readonly version: number;
+        readonly ops: TextOperation[];
+    }[];
 };
 type DeleteCrdtOp = {
     readonly opId?: string;
@@ -970,6 +975,13 @@ type PrivateLiveTextApi = PrivateLiveNodeApi & {
  * the pending ops are re-expressed over the remote op in turn ("after"
  * order), keeping them in server coordinates at all times.
  *
+ * Reconnect replay: keep the pre-disconnect confirmed state and re-send only
+ * the in-flight op at that version. The server returns the intervening
+ * accepted operations with its acknowledgement, including the original op
+ * if it was already stored. Replaying that history through the normal OT
+ * paths rebases the pending edits exactly, without applying them twice to a
+ * snapshot. Queued edits stay queued until their predecessor is acknowledged.
+ *
  * @example
  * const text = new LiveText("Hello");
  * text.insert(5, " world");
@@ -1253,6 +1265,24 @@ type LiveNode = LiveStructure | LiveRegister<Json>;
  * value or a Live storage data structure (LiveMap, LiveList, etc.)
  */
 type LsonObject = Record<string, Lson | undefined>;
+/**
+ * The Json object an Lson object serializes to: every value converted with
+ * `ToJson`, optional keys staying optional.
+ */
+type JsonObjectOf<O extends LsonObject> = {
+    readonly [K in keyof O]: ToJson<Exclude<O[K], undefined>> | (undefined extends O[K] ? undefined : never);
+};
+/**
+ * The Json value a plain Lson object serializes to: an opaque record collapses
+ * to ReadonlyJsonObject, anything else is mapped key by key.
+ *
+ * Inferring V keeps this conditional resolvable, which ToJson's variance
+ * depends on. Deferring it makes unrelated assignments fail, such as
+ * LiveList<never> to Lson.
+ */
+type JsonOfLsonObject<L extends LsonObject> = string extends keyof L ? L extends Record<string, infer V> ? Record<string, V> extends L ? [
+    Json
+] extends [V] ? ReadonlyJsonObject : JsonObjectOf<L> : JsonObjectOf<L> : JsonObjectOf<L> : JsonObjectOf<L>;
 /**
  * Helper type to convert any valid Lson type to the equivalent Json type.
  *
@@ -1268,13 +1298,9 @@ type LsonObject = Record<string, Lson | undefined>;
  *   ToJson<LiveObject<{ a: number, b: LiveList<string>, c?: number }>>
  *                                      // { readonly a: null, readonly b: readonly string[], readonly c?: number }
  */
-type ToJson<L extends Lson | LsonObject> = L extends LiveList<infer I extends Lson> ? Lson extends I ? readonly ReadonlyJson[] : readonly ToJson<I>[] : L extends LiveObject<infer O extends LsonObject> ? LsonObject extends O ? ReadonlyJsonObject : {
-    readonly [K in keyof O]: ToJson<Exclude<O[K], undefined>> | (undefined extends O[K] ? undefined : never);
-} : L extends LiveMap<infer KS extends string, infer V extends Lson> ? Lson extends V ? ReadonlyJsonObject : {
+type ToJson<L extends Lson | LsonObject> = L extends LiveList<infer I extends Lson> ? Lson extends I ? readonly ReadonlyJson[] : readonly ToJson<I>[] : L extends LiveObject<infer O extends LsonObject> ? JsonOfLsonObject<O> : L extends LiveMap<infer KS extends string, infer V extends Lson> ? Lson extends V ? ReadonlyJsonObject : {
     readonly [K in KS]: ToJson<V>;
-} : L extends LiveText ? LiveTextData : L extends LiveFile ? LiveFileData : L extends LsonObject ? string extends keyof L ? ReadonlyJsonObject : {
-    readonly [K in keyof L]: ToJson<Exclude<L[K], undefined>> | (undefined extends L[K] ? undefined : never);
-} : L extends Json ? L : never;
+} : L extends LiveText ? LiveTextData : L extends LiveFile ? LiveFileData : L extends LsonObject ? JsonOfLsonObject<L> : L extends Json ? L : never;
 
 /**
  * Read-only query surface over {@link UnacknowledgedOps}, handed to CRDTs so
@@ -1890,7 +1916,7 @@ type NotificationChannelSettings = {
  * Base definition of notification settings.
  * Plain means it's a simple object coming from the remote backend.
  *
- * It's the raw settings object where somme channels cannot exists
+ * It's the raw settings object where some channels cannot exists
  * because there are no notification kinds enabled on the dashboard.
  * And this object isn't yet proxied by the creator factory `createNotificationSettings`.
  */
@@ -3175,6 +3201,8 @@ type UpdatePresenceClientMsg<P extends JsonObject> = {
 type UpdateStorageClientMsg = {
     readonly type: ClientMsgCode.UPDATE_STORAGE;
     readonly ops: ClientWireOp[];
+    /** Include authoritative history in text acknowledgements after a storage resync. */
+    readonly includeTextHistory?: true;
 };
 type FetchStorageClientMsg = {
     readonly type: ClientMsgCode.FETCH_STORAGE;

package/dist/index.d.ts

@@ -431,6 +431,11 @@ type UpdateTextOp = {
     readonly baseVersion: number;
     readonly version?: number;
     readonly ops: TextOperation[];
+    /** Server-only: accepted ops after the requested base version when reconciling. */
+    readonly history?: {
+        readonly version: number;
+        readonly ops: TextOperation[];
+    }[];
 };
 type DeleteCrdtOp = {
     readonly opId?: string;
@@ -970,6 +975,13 @@ type PrivateLiveTextApi = PrivateLiveNodeApi & {
  * the pending ops are re-expressed over the remote op in turn ("after"
  * order), keeping them in server coordinates at all times.
  *
+ * Reconnect replay: keep the pre-disconnect confirmed state and re-send only
+ * the in-flight op at that version. The server returns the intervening
+ * accepted operations with its acknowledgement, including the original op
+ * if it was already stored. Replaying that history through the normal OT
+ * paths rebases the pending edits exactly, without applying them twice to a
+ * snapshot. Queued edits stay queued until their predecessor is acknowledged.
+ *
  * @example
  * const text = new LiveText("Hello");
  * text.insert(5, " world");
@@ -1253,6 +1265,24 @@ type LiveNode = LiveStructure | LiveRegister<Json>;
  * value or a Live storage data structure (LiveMap, LiveList, etc.)
  */
 type LsonObject = Record<string, Lson | undefined>;
+/**
+ * The Json object an Lson object serializes to: every value converted with
+ * `ToJson`, optional keys staying optional.
+ */
+type JsonObjectOf<O extends LsonObject> = {
+    readonly [K in keyof O]: ToJson<Exclude<O[K], undefined>> | (undefined extends O[K] ? undefined : never);
+};
+/**
+ * The Json value a plain Lson object serializes to: an opaque record collapses
+ * to ReadonlyJsonObject, anything else is mapped key by key.
+ *
+ * Inferring V keeps this conditional resolvable, which ToJson's variance
+ * depends on. Deferring it makes unrelated assignments fail, such as
+ * LiveList<never> to Lson.
+ */
+type JsonOfLsonObject<L extends LsonObject> = string extends keyof L ? L extends Record<string, infer V> ? Record<string, V> extends L ? [
+    Json
+] extends [V] ? ReadonlyJsonObject : JsonObjectOf<L> : JsonObjectOf<L> : JsonObjectOf<L> : JsonObjectOf<L>;
 /**
  * Helper type to convert any valid Lson type to the equivalent Json type.
  *
@@ -1268,13 +1298,9 @@ type LsonObject = Record<string, Lson | undefined>;
  *   ToJson<LiveObject<{ a: number, b: LiveList<string>, c?: number }>>
  *                                      // { readonly a: null, readonly b: readonly string[], readonly c?: number }
  */
-type ToJson<L extends Lson | LsonObject> = L extends LiveList<infer I extends Lson> ? Lson extends I ? readonly ReadonlyJson[] : readonly ToJson<I>[] : L extends LiveObject<infer O extends LsonObject> ? LsonObject extends O ? ReadonlyJsonObject : {
-    readonly [K in keyof O]: ToJson<Exclude<O[K], undefined>> | (undefined extends O[K] ? undefined : never);
-} : L extends LiveMap<infer KS extends string, infer V extends Lson> ? Lson extends V ? ReadonlyJsonObject : {
+type ToJson<L extends Lson | LsonObject> = L extends LiveList<infer I extends Lson> ? Lson extends I ? readonly ReadonlyJson[] : readonly ToJson<I>[] : L extends LiveObject<infer O extends LsonObject> ? JsonOfLsonObject<O> : L extends LiveMap<infer KS extends string, infer V extends Lson> ? Lson extends V ? ReadonlyJsonObject : {
     readonly [K in KS]: ToJson<V>;
-} : L extends LiveText ? LiveTextData : L extends LiveFile ? LiveFileData : L extends LsonObject ? string extends keyof L ? ReadonlyJsonObject : {
-    readonly [K in keyof L]: ToJson<Exclude<L[K], undefined>> | (undefined extends L[K] ? undefined : never);
-} : L extends Json ? L : never;
+} : L extends LiveText ? LiveTextData : L extends LiveFile ? LiveFileData : L extends LsonObject ? JsonOfLsonObject<L> : L extends Json ? L : never;
 
 /**
  * Read-only query surface over {@link UnacknowledgedOps}, handed to CRDTs so
@@ -1890,7 +1916,7 @@ type NotificationChannelSettings = {
  * Base definition of notification settings.
  * Plain means it's a simple object coming from the remote backend.
  *
- * It's the raw settings object where somme channels cannot exists
+ * It's the raw settings object where some channels cannot exists
  * because there are no notification kinds enabled on the dashboard.
  * And this object isn't yet proxied by the creator factory `createNotificationSettings`.
  */
@@ -3175,6 +3201,8 @@ type UpdatePresenceClientMsg<P extends JsonObject> = {
 type UpdateStorageClientMsg = {
     readonly type: ClientMsgCode.UPDATE_STORAGE;
     readonly ops: ClientWireOp[];
+    /** Include authoritative history in text acknowledgements after a storage resync. */
+    readonly includeTextHistory?: true;
 };
 type FetchStorageClientMsg = {
     readonly type: ClientMsgCode.FETCH_STORAGE;

package/dist/index.js

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 
 // src/version.ts
 var PKG_NAME = "@liveblocks/core";
-var PKG_VERSION = "3.24.1";
+var PKG_VERSION = "3.24.3-livetextreplay";
 var PKG_FORMAT = "esm";
 
 // src/dupe-detection.ts
@@ -3628,11 +3628,11 @@ var HttpClient = class {
     const response = await this.#fetchPolyfill(url2, {
       ...options,
       headers: {
-        // These headers are default, but can be overriden by custom headers
+        // These headers are default, but can be overridden by custom headers
         "Content-Type": "application/json; charset=utf-8",
         // Possible header overrides
         ...options?.headers,
-        // Cannot be overriden by custom headers
+        // Cannot be overridden by custom headers
         Authorization: `Bearer ${getBearerTokenFromAuthValue(authValue)}`,
         "X-LB-Client": PKG_VERSION || "dev"
       }
@@ -3678,7 +3678,7 @@ var HttpClient = class {
   }
   /**
    * Makes a GET request and returns the raw response.
-   * Won't throw if the reponse is a non-2xx.
+   * Won't throw if the response is a non-2xx.
    * @deprecated Ideally, use .get() instead.
    */
   async rawGet(endpoint, authValue, params, options) {
@@ -3686,7 +3686,7 @@ var HttpClient = class {
   }
   /**
    * Makes a POST request and returns the raw response.
-   * Won't throw if the reponse is a non-2xx.
+   * Won't throw if the response is a non-2xx.
    * @deprecated Ideally, use .post() instead.
    */
   async rawPost(endpoint, authValue, body) {
@@ -3697,7 +3697,7 @@ var HttpClient = class {
   }
   /**
    * Makes a DELETE request and returns the raw response.
-   * Won't throw if the reponse is a non-2xx.
+   * Won't throw if the response is a non-2xx.
    * @deprecated Ideally, use .delete() instead.
    */
   async rawDelete(endpoint, authValue) {
@@ -3705,14 +3705,14 @@ var HttpClient = class {
   }
   /**
    * Makes a GET request, and return the JSON response.
-   * Will throw if the reponse is a non-2xx.
+   * Will throw if the response is a non-2xx.
    */
   async get(endpoint, authValue, params, options) {
     return await this.#fetch(endpoint, authValue, options, params);
   }
   /**
    * Makes a POST request, and return the JSON response.
-   * Will throw if the reponse is a non-2xx.
+   * Will throw if the response is a non-2xx.
    */
   async post(endpoint, authValue, body, options, params) {
     return await this.#fetch(
@@ -3728,14 +3728,14 @@ var HttpClient = class {
   }
   /**
    * Makes a DELETE request, and return the JSON response.
-   * Will throw if the reponse is a non-2xx.
+   * Will throw if the response is a non-2xx.
    */
   async delete(endpoint, authValue) {
     return await this.#fetch(endpoint, authValue, { method: "DELETE" });
   }
   /**
    * Makes a PUT request for a Blob body, and return the JSON response.
-   * Will throw if the reponse is a non-2xx.
+   * Will throw if the response is a non-2xx.
    */
   async putBlob(endpoint, authValue, blob, params, options) {
     return await this.#fetch(
@@ -9850,6 +9850,9 @@ var LiveText = class _LiveText extends AbstractCrdt {
   /** Local edits made while an op is in flight; sent after the ack. */
   #queuedOps = [];
   #acceptedOps = [];
+  /** Wait for replay history before applying post-snapshot remote ops. */
+  #reconnecting = false;
+  #bufferedRemoteOps = [];
   /**
    * Creates a new LiveText document.
    *
@@ -10152,8 +10155,6 @@ var LiveText = class _LiveText extends AbstractCrdt {
   #applyLocal(op, source) {
     const mutableOp = op;
     if (op.opId !== void 0 && op.opId === this.#inFlightOpId) {
-      this.#inFlightOps = [...this.#inFlightOps, ...this.#queuedOps];
-      this.#queuedOps = [];
       mutableOp.baseVersion = this.#version;
       mutableOp.ops = [...this.#inFlightOps];
       return { modified: false };
@@ -10192,6 +10193,9 @@ var LiveText = class _LiveText extends AbstractCrdt {
   }
   /** Server acknowledgement of our in-flight op. */
   #applyAck(op, source) {
+    if (this.#reconnecting) {
+      return this.#reconcileAck(op, source);
+    }
     const ackedVersion = op.version ?? Math.max(this.#version, op.baseVersion + 1);
     const predicted = this.#inFlightOps;
     const opId = this.#inFlightOpId;
@@ -10214,7 +10218,9 @@ var LiveText = class _LiveText extends AbstractCrdt {
             node: this,
             version: ackedVersion,
             updates: rebuilt.changes,
-            source
+            // A correction was not applied by the originating editor. It
+            // must not be filtered out as an echo of a local edit.
+            source: REMOTE
           }
         };
       }
@@ -10224,9 +10230,67 @@ var LiveText = class _LiveText extends AbstractCrdt {
     this.#flushQueued();
     return result;
   }
+  /** Recover the missing server timeline, preserving the normal OT invariants. */
+  #reconcileAck(op, source) {
+    const history = nn(
+      op.history,
+      "LiveText replay acknowledgement requires history"
+    );
+    this.#reconnecting = false;
+    const buffered = this.#bufferedRemoteOps;
+    this.#bufferedRemoteOps = [];
+    const changes = [];
+    const collect = (result) => {
+      if (result.modified && result.modified.type === "LiveText") {
+        changes.push(...result.modified.updates);
+      }
+    };
+    for (const entry of history) {
+      if (entry.version <= this.#version) continue;
+      if (entry.version === op.version) {
+        collect(this.#applyAck(op, source));
+      } else {
+        collect(
+          this.#applyRemote(
+            {
+              type: OpCode.UPDATE_TEXT,
+              id: op.id,
+              baseVersion: entry.version - 1,
+              version: entry.version,
+              ops: entry.ops
+            },
+            REMOTE
+          )
+        );
+      }
+    }
+    if (this.#inFlightOpId === op.opId) {
+      collect(this.#applyAck(op, source));
+    }
+    for (const remote of buffered) {
+      collect(this.#applyRemote(remote, REMOTE));
+    }
+    return changes.length === 0 ? { modified: false } : {
+      reverse: [],
+      modified: {
+        type: "LiveText",
+        node: this,
+        version: this.#version,
+        updates: changes,
+        source: REMOTE
+      }
+    };
+  }
   /** An accepted op from another client (or a server-fabricated fix op). */
   #applyRemote(op, source) {
     const version = op.version ?? this.#version + 1;
+    if (op.version !== void 0 && op.version <= this.#version) {
+      return { modified: false };
+    }
+    if (this.#reconnecting) {
+      this.#bufferedRemoteOps.push(op);
+      return { modified: false };
+    }
     this.#confirmed = applyTextOperationsToSegments(this.#confirmed, op.ops);
     const [overInFlight, inFlight] = transformTextOperationsX(
       op.ops,
@@ -10332,14 +10396,17 @@ var LiveText = class _LiveText extends AbstractCrdt {
     return { appliedOps, changes };
   }
   /**
-   * Reconcile this node against an authoritative storage snapshot (e.g.
-   * after a reconnect). The confirmed state and version are replaced by the
-   * snapshot's; pending (in-flight + queued) ops are preserved on top and
-   * will be re-sent by the offline-ops replay.
+   * Reconcile against an authoritative snapshot. With pending edits, retain
+   * the current document and confirmed version until replay history arrives:
+   * a snapshot alone cannot re-express the queue over unseen operations.
    *
    * @internal
    */
   _resyncText(data, version, source) {
+    if (this.#inFlightOpId !== void 0) {
+      this.#reconnecting = true;
+      return void 0;
+    }
     this.#confirmed = dataToSegments(data);
     this.#version = version;
     this.#acceptedOps = [];
@@ -10369,6 +10436,8 @@ var LiveText = class _LiveText extends AbstractCrdt {
     this.#inFlightOpId = void 0;
     this.#inFlightOps = [];
     this.#queuedOps = [];
+    this.#bufferedRemoteOps = [];
+    this.#reconnecting = false;
   }
   #recordAccepted(version, ops, opId) {
     if (this.#acceptedOps.some((entry) => entry.version === version)) {
@@ -12537,7 +12606,8 @@ function createRoom(options, config) {
     const result = applyLocalOps(unackedOps);
     messages.push({
       type: ClientMsgCode.UPDATE_STORAGE,
-      ops: result.opsToEmit
+      ops: result.opsToEmit,
+      includeTextHistory: true
     });
     notify(result.updates);
     sendMessages(messages);
@@ -13721,7 +13791,7 @@ ${dumpPool(
       updateSubscriptionSettings,
       markInboxNotificationAsRead
     },
-    // Explictly make the internal field non-enumerable, to avoid aggressive
+    // Explicitly make the internal field non-enumerable, to avoid aggressive
     // freezing when used with Immer
     kInternal,
     { enumerable: false }