@dabble/patches 0.7.21 → 0.7.23

package/dist/server/LWWServer.js

@@ -4,8 +4,8 @@ import { consolidateOps, convertDeltaOps } from "../algorithms/lww/consolidateOp
 import { createChange } from "../data/change.js";
 import { signal } from "easy-signal";
 import { createJSONPatch } from "../json-patch/createJSONPatch.js";
-import { JSONPatch } from "../json-patch/JSONPatch.js";
 import { getClientId } from "../net/serverContext.js";
+import { concatStreams } from "./jsonReadable.js";
 import { createTombstoneIfSupported, removeTombstoneIfExists } from "./tombstone.js";
 import { assertVersionMetadata } from "./utils.js";
 class LWWServer {
@@ -21,33 +21,35 @@ class LWWServer {
     undeleteDoc: "write"
   };
   store;
-  snapshotInterval;
   /** Notifies listeners whenever a batch of changes is successfully committed. */
   onChangesCommitted = signal();
   /** Notifies listeners when a document is deleted. */
   onDocDeleted = signal();
-  constructor(store, options = {}) {
+  constructor(store, _options = {}) {
     this.store = store;
-    this.snapshotInterval = options.snapshotInterval ?? 200;
   }
   /**
-   * Get the current state of a document.
-   * Reconstructs state from snapshot + ops changed since snapshot.
+   * Get the current state of a document as a ReadableStream of JSON.
+   * Streams `{"state":...,"rev":N,"changes":[...]}` with the snapshot state
+   * flowing through without parsing.
    *
    * @param docId - The document ID.
-   * @returns The document state and revision, or `{ state: {}, rev: 0 }` if not found.
+   * @returns A ReadableStream of JSON string chunks.
    */
   async getDoc(docId) {
     const snapshot = await this.store.getSnapshot(docId);
-    const baseState = snapshot?.state ?? {};
     const baseRev = snapshot?.rev ?? 0;
     const ops = await this.store.listOps(docId, { sinceRev: baseRev });
-    if (ops.length === 0) {
-      return { state: baseState, rev: baseRev };
+    let changes = [];
+    if (ops.length > 0) {
+      const sortedOps = [...ops].sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+      const maxRev = Math.max(baseRev, ...ops.map((op) => op.rev ?? 0));
+      const maxTs = Math.max(...ops.map((op) => op.ts ?? 0));
+      changes = [createChange(baseRev, maxRev, sortedOps, { committedAt: maxTs || Date.now() })];
     }
-    const state = new JSONPatch(ops).apply(baseState);
-    const rev = Math.max(baseRev, ...ops.map((op) => op.rev ?? 0));
-    return { state, rev };
+    const statePayload = snapshot?.state ?? "{}";
+    const rev = changes[changes.length - 1]?.rev || baseRev;
+    return concatStreams(`{"state":`, statePayload, `,"rev":${rev},"changes":`, JSON.stringify(changes), "}");
   }
   /**
    * Get changes that occurred after a specific revision.
@@ -55,7 +57,7 @@ class LWWServer {
    *
    * @param docId - The document ID.
    * @param rev - The revision number to get changes after.
-   * @returns Array containing 0 or 1 synthesized changes.
+   * @returns Array of synthesized changes (0 or 1 elements).
    */
   async getChangesSince(docId, rev) {
     const ops = await this.store.listOps(docId, { sinceRev: rev });
@@ -78,11 +80,11 @@ class LWWServer {
    * @param docId - The document ID.
    * @param changes - The changes to commit (always 1 for LWW).
    * @param options - Optional commit options (ignored for LWW).
-   * @returns Array containing 0-1 changes with catchup ops and new rev.
+   * @returns An object with the committed changes (0-1 elements).
    */
   async commitChanges(docId, changes, options) {
     if (changes.length === 0) {
-      return [];
+      return { changes: [] };
     }
     const change = changes[0];
     const serverNow = Date.now();
@@ -96,10 +98,6 @@ class LWWServer {
     if (opsToStore.length > 0 || pathsToDelete.length > 0) {
       newRev = await this.store.saveOps(docId, opsToStore, pathsToDelete);
     }
-    if (newRev > 0 && newRev % this.snapshotInterval === 0) {
-      const { state } = await this.getDoc(docId);
-      await this.store.saveSnapshot(docId, state, newRev);
-    }
     const responseOps = [...opsToReturn];
     if (clientRev !== void 0) {
       const opsSince = await this.store.listOps(docId, { sinceRev: clientRev });
@@ -122,7 +120,7 @@ class LWWServer {
         console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
       }
     }
-    return [responseChange];
+    return { changes: [responseChange] };
   }
   /**
    * Delete a document and emit deletion signal.
@@ -148,13 +146,14 @@ class LWWServer {
   }
   /**
    * Make a server-side change to a document.
+   * Stateless — uses getCurrentRev instead of loading document state.
    * @param docId - The document ID.
    * @param mutator - A function that receives a JSONPatch and PathProxy to define the changes.
    * @param metadata - Optional metadata for the change.
    * @returns The created change, or null if no operations were generated.
    */
   async change(docId, mutator, metadata) {
-    const { state, rev } = await this.getDoc(docId);
+    const rev = await this.store.getCurrentRev(docId);
     const patch = createJSONPatch(mutator);
     if (patch.ops.length === 0) {
       return null;
@@ -162,13 +161,14 @@ class LWWServer {
     const serverNow = Date.now();
     const opsWithTs = patch.ops.map((op) => ({ ...op, ts: serverNow }));
     const change = createChange(rev, rev + 1, opsWithTs, metadata);
-    patch.apply(state);
     await this.commitChanges(docId, [change]);
     return change;
   }
   /**
    * Captures the current state of a document as a new version.
    * Only works if store implements VersioningStoreBackend.
+   * Does NOT build state — creates version metadata, then emits `onVersionCreated`
+   * so subscribers can build and persist state out of band.
    *
    * @param docId - The document ID.
    * @param metadata - Optional metadata for the version.
@@ -179,19 +179,20 @@ class LWWServer {
     if (!this.isVersioningStore(this.store)) {
       throw new Error("LWW versioning requires a store that implements VersioningStoreBackend");
     }
-    const { state, rev } = await this.getDoc(docId);
+    const rev = await this.store.getCurrentRev(docId);
     if (rev === 0) {
       return null;
     }
+    const now = Date.now();
     const versionMetadata = createVersionMetadata({
       origin: "main",
-      startedAt: Date.now(),
-      endedAt: Date.now(),
+      startedAt: now,
+      endedAt: now,
       startRev: rev,
       endRev: rev,
       ...metadata
     });
-    await this.store.createVersion(docId, versionMetadata, state);
+    await this.store.createVersion(docId, versionMetadata);
     return versionMetadata.id;
   }
   /**

package/dist/server/OTBranchManager.js

@@ -40,9 +40,13 @@ class OTBranchManager {
     const { state: stateAtRev } = await getStateAtRevision(this.store, docId, rev);
     const branchDocId = await generateBranchId(this.store, docId);
     const now = Date.now();
+    const initialChange = createChange(0, 1, [{ op: "replace", path: "", value: stateAtRev }], {
+      createdAt: now,
+      committedAt: now
+    });
+    await this.store.saveChanges(branchDocId, [initialChange]);
     const initialVersionMetadata = createVersionMetadata({
       origin: "main",
-      // Branch doc versions are 'main' until merged
       startedAt: now,
       endedAt: now,
       endRev: rev,
@@ -51,7 +55,7 @@ class OTBranchManager {
       groupId: branchDocId,
       branchName: metadata?.name
     });
-    await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
+    await this.store.createVersion(branchDocId, initialVersionMetadata, [initialChange]);
     const branch = createBranchRecord(branchDocId, docId, rev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
@@ -107,9 +111,8 @@ class OTBranchManager {
         // Keep branchName for traceability
         parentId: lastVersionId
       });
-      const state = await this.store.loadVersionState(branchId, v.id);
       const changes = await this.store.loadVersionChanges?.(branchId, v.id);
-      await this.store.createVersion(sourceDocId, newVersionMetadata, state, changes);
+      await this.store.createVersion(sourceDocId, newVersionMetadata, changes);
       lastVersionId = newVersionMetadata.id;
     }
     const committedMergeChanges = await wrapMergeCommit(branchId, sourceDocId, async () => {
@@ -120,7 +123,7 @@ class OTBranchManager {
           rev: void 0
           // Let commitChanges assign sequential revs
         }));
-        return this.patchesServer.commitChanges(sourceDocId, adjustedChanges);
+        return (await this.patchesServer.commitChanges(sourceDocId, adjustedChanges)).changes;
       } else {
         const rev = branchStartRevOnSource + branchChanges.length;
         const flattenedChange = createChange(
@@ -132,7 +135,7 @@ class OTBranchManager {
         if (this.maxPayloadBytes) {
           changesToCommit = breakChanges(changesToCommit, this.maxPayloadBytes);
         }
-        return this.patchesServer.commitChanges(sourceDocId, changesToCommit);
+        return (await this.patchesServer.commitChanges(sourceDocId, changesToCommit)).changes;
       }
     });
     await this.closeBranch(branchId, "merged");

package/dist/server/OTServer.d.ts

@@ -1,7 +1,7 @@
 import * as easy_signal from 'easy-signal';
 import { PatchesServer } from './PatchesServer.js';
 import { OTStoreBackend } from './types.js';
-import { Change, CommitChangesOptions, DeleteDocOptions, PatchesState, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { Change, CommitChangesOptions, DeleteDocOptions, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -19,11 +19,6 @@ interface OTServerOptions {
      * Defaults to 30 minutes.
      */
     sessionTimeoutMinutes?: number;
-    /**
-     * Maximum size in bytes for a single change's storage representation.
-     * Useful for databases with row size limits.
-     */
-    maxStorageBytes?: number;
 }
 /**
  * Handles the server-side Operational Transformation (OT) logic,
@@ -45,7 +40,6 @@ declare class OTServer implements PatchesServer {
      */
     static api: ApiDefinition;
     private readonly sessionTimeoutMillis;
-    private readonly maxStorageBytes?;
     readonly store: OTStoreBackend;
     /** Notifies listeners whenever a batch of changes is *successfully* committed. */
     readonly onChangesCommitted: easy_signal.Signal<(docId: string, changes: Change[], options?: CommitChangesOptions, originClientId?: string) => void>;
@@ -53,39 +47,46 @@ declare class OTServer implements PatchesServer {
     readonly onDocDeleted: easy_signal.Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
     constructor(store: OTStoreBackend, options?: OTServerOptions);
     /**
-     * Get the current state of a document.
+     * Get the current state of a document as a ReadableStream of JSON.
+     * Streams `{"state":...,"rev":N,"changes":[...]}` with the version state
+     * flowing through without parsing.
      * @param docId - The ID of the document.
-     * @returns The current state of the document.
+     * @returns A ReadableStream of JSON string chunks.
      */
-    getDoc(docId: string): Promise<PatchesState>;
+    getDoc(docId: string): Promise<ReadableStream<string>>;
     /**
      * Get changes that occurred after a specific revision.
      * @param docId - The ID of the document.
      * @param rev - The revision number.
-     * @returns The changes that occurred after the specified revision.
+     * @returns Array of changes after the given revision.
      */
     getChangesSince(docId: string, rev: number): Promise<Change[]>;
     /**
      * Commits a set of changes to a document, applying operational transformation as needed.
      *
-     * Returns all changes the client needs to apply: both catchup changes (from other
-     * clients) and the client's own transformed changes. Only the new changes are
-     * broadcast to other clients.
+     * Returns all changes the client needs to apply (catchup changes from others, followed
+     * by the client's own transformed changes), plus an optional `docReloadRequired` flag.
+     *
+     * When `docReloadRequired` is true, the client must call `getDoc` to reload the full
+     * current state before continuing — its local state is stale.
      *
      * @param docId - The ID of the document.
      * @param changes - The changes to commit.
      * @param options - Optional commit settings (e.g., forceCommit for migrations).
-     * @returns Combined array of catchup changes followed by the client's committed changes.
+     * @returns An object with the committed changes and an optional reload flag.
      */
-    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<{
+        changes: Change[];
+        docReloadRequired?: true;
+    }>;
     /**
      * Make a server-side change to a document.
-     * @param mutator
-     * @returns
+     * Stateless — uses getCurrentRev instead of loading document state.
      */
     change<T = Record<string, any>>(docId: string, mutator: ChangeMutator<T>, metadata?: Record<string, any>): Promise<Change | null>;
     /**
      * Deletes a document.
+     * Stateless — uses getCurrentRev instead of loading document state.
      * @param docId The document ID.
      * @param options - Optional deletion settings (e.g., skipTombstone for testing).
      */
@@ -98,9 +99,12 @@ declare class OTServer implements PatchesServer {
     undeleteDoc(docId: string): Promise<boolean>;
     /**
      * Captures the current state of a document as a new version.
+     * Does NOT build state — creates version metadata + changes, then emits
+     * `onVersionCreated` so subscribers can build and persist state out of band.
+     *
      * @param docId The document ID.
      * @param metadata Optional metadata for the version.
-     * @returns The ID of the created version.
+     * @returns The ID of the created version, or null if no changes to capture.
      */
     captureCurrentVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string | null>;
 }

package/dist/server/OTServer.js

@@ -1,9 +1,7 @@
 import "../chunk-IZ2YBCUP.js";
 import { commitChanges } from "../algorithms/ot/server/commitChanges.js";
 import { createVersion } from "../algorithms/ot/server/createVersion.js";
-import { getSnapshotAtRevision } from "../algorithms/ot/server/getSnapshotAtRevision.js";
-import { getStateAtRevision } from "../algorithms/ot/server/getStateAtRevision.js";
-import { applyChanges } from "../algorithms/ot/shared/applyChanges.js";
+import { getSnapshotAtRevision, getSnapshotStream } from "../algorithms/ot/server/getSnapshotAtRevision.js";
 import { createChange } from "../data/change.js";
 import { signal } from "easy-signal";
 import { createJSONPatch } from "../json-patch/createJSONPatch.js";
@@ -23,7 +21,6 @@ class OTServer {
     undeleteDoc: "write"
   };
   sessionTimeoutMillis;
-  maxStorageBytes;
   store;
   /** Notifies listeners whenever a batch of changes is *successfully* committed. */
   onChangesCommitted = signal();
@@ -31,46 +28,48 @@ class OTServer {
   onDocDeleted = signal();
   constructor(store, options = {}) {
     this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1e3;
-    this.maxStorageBytes = options.maxStorageBytes;
     this.store = store;
   }
   /**
-   * Get the current state of a document.
+   * Get the current state of a document as a ReadableStream of JSON.
+   * Streams `{"state":...,"rev":N,"changes":[...]}` with the version state
+   * flowing through without parsing.
    * @param docId - The ID of the document.
-   * @returns The current state of the document.
+   * @returns A ReadableStream of JSON string chunks.
    */
   async getDoc(docId) {
-    return getStateAtRevision(this.store, docId);
+    return getSnapshotStream(this.store, docId);
   }
   /**
    * Get changes that occurred after a specific revision.
    * @param docId - The ID of the document.
    * @param rev - The revision number.
-   * @returns The changes that occurred after the specified revision.
+   * @returns Array of changes after the given revision.
    */
-  getChangesSince(docId, rev) {
+  async getChangesSince(docId, rev) {
     return this.store.listChanges(docId, { startAfter: rev });
   }
   /**
    * Commits a set of changes to a document, applying operational transformation as needed.
    *
-   * Returns all changes the client needs to apply: both catchup changes (from other
-   * clients) and the client's own transformed changes. Only the new changes are
-   * broadcast to other clients.
+   * Returns all changes the client needs to apply (catchup changes from others, followed
+   * by the client's own transformed changes), plus an optional `docReloadRequired` flag.
+   *
+   * When `docReloadRequired` is true, the client must call `getDoc` to reload the full
+   * current state before continuing — its local state is stale.
    *
    * @param docId - The ID of the document.
    * @param changes - The changes to commit.
    * @param options - Optional commit settings (e.g., forceCommit for migrations).
-   * @returns Combined array of catchup changes followed by the client's committed changes.
+   * @returns An object with the committed changes and an optional reload flag.
    */
   async commitChanges(docId, changes, options) {
-    const { catchupChanges, newChanges } = await commitChanges(
+    const { catchupChanges, newChanges, docReloadRequired } = await commitChanges(
       this.store,
       docId,
       changes,
       this.sessionTimeoutMillis,
-      options,
-      this.maxStorageBytes
+      options
     );
     if (newChanges.length > 0) {
       try {
@@ -79,32 +78,35 @@ class OTServer {
         console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
       }
     }
-    return [...catchupChanges, ...newChanges];
+    const result = {
+      changes: [...catchupChanges, ...newChanges]
+    };
+    if (docReloadRequired) result.docReloadRequired = true;
+    return result;
   }
   /**
    * Make a server-side change to a document.
-   * @param mutator
-   * @returns
+   * Stateless — uses getCurrentRev instead of loading document state.
    */
   async change(docId, mutator, metadata) {
-    const { state, rev } = await this.getDoc(docId);
+    const rev = await this.store.getCurrentRev(docId);
     const patch = createJSONPatch(mutator);
     if (patch.ops.length === 0) {
       return null;
     }
     const change = createChange(rev, rev + 1, patch.ops, metadata);
-    patch.apply(state);
     await this.commitChanges(docId, [change]);
     return change;
   }
   /**
    * Deletes a document.
+   * Stateless — uses getCurrentRev instead of loading document state.
    * @param docId The document ID.
    * @param options - Optional deletion settings (e.g., skipTombstone for testing).
    */
   async deleteDoc(docId, options) {
     const clientId = getClientId();
-    const { rev } = await this.getDoc(docId);
+    const rev = await this.store.getCurrentRev(docId);
     await createTombstoneIfSupported(this.store, docId, rev, clientId, options?.skipTombstone);
     await this.store.deleteDoc(docId);
     await this.onDocDeleted.emit(docId, options, clientId);
@@ -120,15 +122,17 @@ class OTServer {
   // === Version Operations ===
   /**
    * Captures the current state of a document as a new version.
+   * Does NOT build state — creates version metadata + changes, then emits
+   * `onVersionCreated` so subscribers can build and persist state out of band.
+   *
    * @param docId The document ID.
    * @param metadata Optional metadata for the version.
-   * @returns The ID of the created version.
+   * @returns The ID of the created version, or null if no changes to capture.
    */
   async captureCurrentVersion(docId, metadata) {
     assertVersionMetadata(metadata);
-    const { state: initialState, changes } = await getSnapshotAtRevision(this.store, docId);
-    const state = applyChanges(initialState, changes);
-    const version = await createVersion(this.store, docId, state, changes, metadata);
+    const { changes } = await getSnapshotAtRevision(this.store, docId);
+    const version = await createVersion(this.store, docId, changes, { metadata });
     if (!version) {
       return null;
     }

package/dist/server/PatchesHistoryManager.d.ts

@@ -44,12 +44,30 @@ declare class PatchesHistoryManager {
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     /**
      * Loads the full document state snapshot for a specific version by its ID.
+     * Returns a ReadableStream so the state can be streamed to clients via RPC.
      * @param docId - The ID of the document.
      * @param versionId - The unique ID of the version.
-     * @returns The document state at that version.
-     * @throws Error if the version ID is not found or state loading fails.
+     * @returns A ReadableStream of the JSON state, or a stream of 'null' if not found.
+     * @throws Error if state loading fails.
      */
-    getStateAtVersion(docId: string, versionId: string): Promise<any>;
+    getStateAtVersion(docId: string, versionId: string): Promise<ReadableStream<string>>;
+    /**
+     * Returns the document state immediately before a version's changes begin.
+     *
+     * Uses the version's `parentId` chain to find the correct baseline — so
+     * offline-branch session 2 returns the state after session 1, not after the
+     * last main-timeline version. Bridges any gap between the parent's `endRev`
+     * and the version's `startRev` by applying intermediate changes.
+     *
+     * Use this as the baseline when scrubbing through a version's individual changes.
+     *
+     * Only available for OT stores.
+     *
+     * @param docId - The document ID.
+     * @param versionId - The version whose pre-state to compute.
+     * @returns A ReadableStream of the JSON state at `version.startRev - 1`.
+     */
+    getStateBeforeVersion(docId: string, versionId: string): Promise<ReadableStream<string>>;
     /**
      * Loads the list of original client changes that were included in a specific version.
      * Useful for replaying/scrubbing through the operations within an offline or online session.
@@ -61,8 +79,9 @@ declare class PatchesHistoryManager {
     getChangesForVersion(docId: string, versionId: string): Promise<Change[]>;
     /**
      * Alias for getStateAtVersion for RPC API compatibility.
+     * Returns a ReadableStream for efficient JSON-RPC streaming.
      */
-    getVersionState(docId: string, versionId: string): Promise<any>;
+    getVersionState(docId: string, versionId: string): Promise<ReadableStream<string>>;
     /**
      * Alias for getChangesForVersion for RPC API compatibility.
      */

package/dist/server/PatchesHistoryManager.js

@@ -1,4 +1,6 @@
 import "../chunk-IZ2YBCUP.js";
+import { getStateBeforeVersionAsStream } from "../algorithms/ot/server/buildVersionState.js";
+import { jsonReadable } from "./jsonReadable.js";
 import { assertVersionMetadata } from "./utils.js";
 class PatchesHistoryManager {
   constructor(patches, store) {
@@ -10,7 +12,8 @@ class PatchesHistoryManager {
     createVersion: "write",
     updateVersion: "write",
     getVersionState: "read",
-    getVersionChanges: "read"
+    getVersionChanges: "read",
+    getStateBeforeVersion: "read"
   };
   store;
   /**
@@ -47,19 +50,51 @@ class PatchesHistoryManager {
   }
   /**
    * Loads the full document state snapshot for a specific version by its ID.
+   * Returns a ReadableStream so the state can be streamed to clients via RPC.
    * @param docId - The ID of the document.
    * @param versionId - The unique ID of the version.
-   * @returns The document state at that version.
-   * @throws Error if the version ID is not found or state loading fails.
+   * @returns A ReadableStream of the JSON state, or a stream of 'null' if not found.
+   * @throws Error if state loading fails.
    */
   async getStateAtVersion(docId, versionId) {
     try {
-      return await this.store.loadVersionState(docId, versionId);
+      const rawState = await this.store.loadVersionState(docId, versionId);
+      if (rawState === void 0) {
+        return jsonReadable("null");
+      }
+      return typeof rawState === "string" ? jsonReadable(rawState) : rawState;
     } catch (error) {
       console.error(`Failed to load state for version ${versionId} of doc ${docId}.`, error);
       throw new Error(`Could not load state for version ${versionId}.`);
     }
   }
+  /**
+   * Returns the document state immediately before a version's changes begin.
+   *
+   * Uses the version's `parentId` chain to find the correct baseline — so
+   * offline-branch session 2 returns the state after session 1, not after the
+   * last main-timeline version. Bridges any gap between the parent's `endRev`
+   * and the version's `startRev` by applying intermediate changes.
+   *
+   * Use this as the baseline when scrubbing through a version's individual changes.
+   *
+   * Only available for OT stores.
+   *
+   * @param docId - The document ID.
+   * @param versionId - The version whose pre-state to compute.
+   * @returns A ReadableStream of the JSON state at `version.startRev - 1`.
+   */
+  async getStateBeforeVersion(docId, versionId) {
+    if (!("listChanges" in this.store)) {
+      throw new Error("getStateBeforeVersion is only supported for OT stores.");
+    }
+    const otStore = this.store;
+    const version = await otStore.loadVersion(docId, versionId);
+    if (!version) {
+      throw new Error(`Version ${versionId} not found for doc ${docId}.`);
+    }
+    return getStateBeforeVersionAsStream(otStore, docId, version);
+  }
   /**
    * Loads the list of original client changes that were included in a specific version.
    * Useful for replaying/scrubbing through the operations within an offline or online session.
@@ -81,6 +116,7 @@ class PatchesHistoryManager {
   // ---------------------------------------------------------------------------
   /**
    * Alias for getStateAtVersion for RPC API compatibility.
+   * Returns a ReadableStream for efficient JSON-RPC streaming.
    */
   async getVersionState(docId, versionId) {
     return this.getStateAtVersion(docId, versionId);

package/dist/server/PatchesServer.d.ts

@@ -1,4 +1,4 @@
-import { PatchesState, Change, ChangeInput, CommitChangesOptions, DeleteDocOptions, EditableVersionMetadata, ChangeMutator } from '../types.js';
+import { Change, ChangeInput, CommitChangesOptions, DeleteDocOptions, EditableVersionMetadata, ChangeMutator } from '../types.js';
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -18,6 +18,14 @@ interface CommitResult {
     catchupChanges: Change[];
     /** The client's changes after transformation (will be broadcast to others). */
     newChanges: Change[];
+    /**
+     * When true, the client's local state is stale and it must call `getDoc` to
+     * reload the full current document before continuing. This happens when an
+     * offline-first client (baseRev: 0) commits changes to a document that already
+     * has server-side history — the server commits the changes but cannot send
+     * all the missed history inline.
+     */
+    docReloadRequired?: true;
 }
 /**
  * Interface that document servers must implement to work with the RPC layer.
@@ -28,31 +36,39 @@ interface CommitResult {
  */
 interface PatchesServer {
     /**
-     * Get the current state of a document.
+     * Get the current state of a document as a ReadableStream of JSON.
+     * The stream contains the full JSON envelope: `{"state":...,"rev":N,"changes":[...]}`.
      * @param docId - The document ID.
-     * @returns The document state and revision, or `{ state: {}, rev: 0 }` if not found.
+     * @returns A ReadableStream of JSON string chunks.
      */
-    getDoc(docId: string): Promise<PatchesState>;
+    getDoc(docId: string): Promise<ReadableStream<string>>;
     /**
      * Get changes that occurred after a specific revision.
      * @param docId - The document ID.
      * @param rev - The revision number to get changes after.
-     * @returns Array of changes after the specified revision, in revision order.
+     * @returns Array of changes after the given revision.
      */
     getChangesSince(docId: string, rev: number): Promise<Change[]>;
     /**
      * Commit changes to a document.
      *
      * Applies operational transformation as needed, assigns revision numbers,
-     * and persists the changes. Returns all changes the client needs to apply:
-     * both catchup changes (from other clients) and the client's own transformed changes.
+     * and persists the changes. Returns all changes the client needs to apply
+     * (catchup changes from others, followed by the client's own transformed changes),
+     * plus an optional `docReloadRequired` flag.
+     *
+     * When `docReloadRequired` is true, the client's changes were committed but its
+     * local state is stale. The client must call `getDoc` to reload before continuing.
      *
      * @param docId - The document ID.
      * @param changes - The changes to commit.
      * @param options - Optional commit options.
-     * @returns Combined array of catchup changes followed by the client's committed changes.
+     * @returns An object with the committed changes and an optional reload flag.
      */
-    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<{
+        changes: Change[];
+        docReloadRequired?: true;
+    }>;
     /**
      * Delete a document.
      * @param docId - The document ID.

package/dist/server/RevConflictError.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown by store implementations when `saveChanges` detects that a revision
+ * already exists. This signals a concurrent-write conflict so `commitChanges`
+ * can retry with fresh state.
+ *
+ * Store implementations should catch their native conflict errors (e.g.
+ * Firestore ALREADY_EXISTS) and re-throw as `RevConflictError`.
+ */
+declare class RevConflictError extends Error {
+    constructor(message?: string);
+}
+
+export { RevConflictError };