@dabble/patches 0.7.21 → 0.7.23

package/dist/algorithms/ot/server/handleOfflineSessionsAndBatches.js

@@ -1,22 +1,17 @@
 import "../../../chunk-IZ2YBCUP.js";
-import { createVersionMetadata } from "../../../data/version.js";
-import { applyChanges } from "../shared/applyChanges.js";
-import { breakChanges } from "../shared/changeBatching.js";
-import { getStateAtRevision } from "./getStateAtRevision.js";
-async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId, origin = "offline-branch", maxStorageBytes) {
-  const [lastVersion] = await store.listVersions(docId, {
-    groupId: batchId,
-    reverse: true,
-    limit: 1
-  });
-  let offlineBaseState;
+import { createVersion } from "./createVersion.js";
+async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, origin = "offline-branch") {
   let parentId;
-  if (lastVersion) {
-    const vs = await store.loadVersionState(docId, lastVersion.id);
-    offlineBaseState = vs.state ?? vs;
-    parentId = lastVersion.id;
-  } else {
-    offlineBaseState = (await getStateAtRevision(store, docId, baseRev)).state;
+  if (origin === "offline-branch" && changes.length > 0) {
+    const firstRev = changes[0].rev;
+    const mainVersions = await store.listVersions(docId, {
+      limit: 1,
+      reverse: true,
+      startAfter: firstRev,
+      origin: "main",
+      orderBy: "endRev"
+    });
+    parentId = mainVersions[0]?.id;
   }
   let sessionStartIndex = 0;
   for (let i = 1; i <= changes.length; i++) {
@@ -25,45 +20,12 @@ async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docI
     if (timeDiff > sessionTimeoutMillis || isLastChange) {
       const sessionChanges = changes.slice(sessionStartIndex, i);
       if (sessionChanges.length > 0) {
-        const isContinuation = !!lastVersion && sessionChanges[0].createdAt - lastVersion.endedAt <= sessionTimeoutMillis;
-        if (isContinuation && store.appendVersionChanges) {
-          const mergedState = applyChanges(offlineBaseState, sessionChanges);
-          const newEndedAt = sessionChanges[sessionChanges.length - 1].createdAt;
-          const newRev = sessionChanges[sessionChanges.length - 1].rev;
-          await store.appendVersionChanges(docId, lastVersion.id, sessionChanges, newEndedAt, newRev, mergedState);
-          offlineBaseState = mergedState;
-          parentId = lastVersion.parentId;
-        } else {
-          offlineBaseState = applyChanges(offlineBaseState, sessionChanges);
-          const isOffline = sessionChanges[0].committedAt - sessionChanges[0].createdAt > sessionTimeoutMillis;
-          const sessionMetadata = createVersionMetadata({
-            parentId,
-            groupId: batchId,
-            origin,
-            ...isOffline ? { isOffline } : {},
-            startedAt: sessionChanges[0].createdAt,
-            endedAt: sessionChanges[sessionChanges.length - 1].createdAt,
-            endRev: sessionChanges[sessionChanges.length - 1].rev,
-            startRev: sessionChanges[0].rev
-          });
-          await store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
-          parentId = sessionMetadata.id;
-        }
+        const version = await createVersion(store, docId, sessionChanges, { origin, parentId });
+        parentId = version?.id;
         sessionStartIndex = i;
       }
     }
   }
-  if (origin === "offline-branch") {
-    const collapsed = changes.reduce((firstChange, nextChange) => {
-      firstChange.ops = [...firstChange.ops, ...nextChange.ops];
-      return firstChange;
-    });
-    if (maxStorageBytes) {
-      return breakChanges([collapsed], maxStorageBytes);
-    }
-    return [collapsed];
-  }
-  return changes;
 }
 export {
   handleOfflineSessionsAndBatches

package/dist/algorithms/ot/server/transformIncomingChanges.d.ts

@@ -5,14 +5,15 @@ import '../../../json-patch/types.js';
 
 /**
  * Transforms incoming changes against committed changes that happened *after* the client's baseRev.
- * The state used for transformation should be the server state *at the client's baseRev*.
+ * Stateless: passes null to transformPatch (no server state needed for transformation).
+ * Bad transformations produce empty ops and are filtered as noops.
+ *
  * @param changes The incoming changes.
- * @param stateAtBaseRev The server state *at the client's baseRev*.
  * @param committedChanges The committed changes that happened *after* the client's baseRev.
  * @param currentRev The current/latest revision number (these changes will have their `rev` set > `currentRev`).
  * @param forceCommit If true, skip filtering of no-op changes (useful for migrations).
  * @returns The transformed changes.
  */
-declare function transformIncomingChanges(changes: Change[], stateAtBaseRev: any, committedChanges: Change[], currentRev: number, forceCommit?: boolean): Change[];
+declare function transformIncomingChanges(changes: Change[], committedChanges: Change[], currentRev: number, forceCommit?: boolean): Change[];
 
 export { transformIncomingChanges };

package/dist/algorithms/ot/server/transformIncomingChanges.js

@@ -1,27 +1,13 @@
 import "../../../chunk-IZ2YBCUP.js";
-import { applyPatch } from "../../../json-patch/applyPatch.js";
 import { transformPatch } from "../../../json-patch/transformPatch.js";
-function transformIncomingChanges(changes, stateAtBaseRev, committedChanges, currentRev, forceCommit = false) {
+function transformIncomingChanges(changes, committedChanges, currentRev, forceCommit = false) {
   const committedOps = committedChanges.flatMap((c) => c.ops);
-  let state = stateAtBaseRev;
   let rev = currentRev + 1;
   return changes.map((change) => {
-    const transformedOps = transformPatch(stateAtBaseRev, committedOps, change.ops);
+    const transformedOps = transformPatch(null, committedOps, change.ops);
     if (transformedOps.length === 0 && !forceCommit) {
       return null;
     }
-    if (transformedOps.length > 0) {
-      try {
-        const previous = state;
-        state = applyPatch(state, transformedOps, { strict: true });
-        if (previous === state && !forceCommit) {
-          return null;
-        }
-      } catch (error) {
-        console.error(`Error applying change ${change.id} to state:`, error);
-        return null;
-      }
-    }
     return { ...change, rev: rev++, ops: transformedOps };
   }).filter(Boolean);
 }

package/dist/algorithms/ot/shared/applyChanges.js

@@ -3,7 +3,11 @@ import { applyPatch } from "../../../json-patch/applyPatch.js";
 function applyChanges(state, changes) {
   if (!changes.length) return state;
   for (const change of changes) {
-    state = applyPatch(state, change.ops, { strict: true });
+    try {
+      state = applyPatch(state, change.ops, { strict: true });
+    } catch (e) {
+      console.error(`applyChanges: skipping bad change ${change.id} (rev ${change.rev}):`, e);
+    }
   }
   return state;
 }

package/dist/client/LWWInMemoryStore.js

@@ -158,6 +158,10 @@ class LWWInMemoryStore {
     for (const op of buf.sendingChange.ops) {
       buf.committedFields.set(op.path, op.value);
     }
+    const changeRev = buf.sendingChange.rev;
+    if (changeRev !== void 0 && changeRev > buf.committedRev) {
+      buf.committedRev = changeRev;
+    }
     buf.sendingChange = null;
   }
   /**

package/dist/client/LWWIndexedDBStore.js

@@ -243,6 +243,13 @@ class LWWIndexedDBStore {
       return;
     }
     await Promise.all(sending.change.ops.map((op) => committedOps.put({ ...op, docId })));
+    const changeRev = sending.change.rev;
+    if (changeRev !== void 0) {
+      const docMeta = await docsStore.get(docId) ?? { docId, committedRev: 0, algorithm: "lww" };
+      if (changeRev > docMeta.committedRev) {
+        await docsStore.put({ ...docMeta, committedRev: changeRev });
+      }
+    }
     await sendingChanges.delete(docId);
     await tx.complete();
   }

package/dist/client/Patches.js

@@ -206,8 +206,11 @@ class Patches {
   _handleDocChange(docId, ops, doc, algorithm, metadata) {
     const prev = this._changeQueues.get(docId) ?? Promise.resolve();
     const current = prev.then(() => this._processDocChange(docId, ops, doc, algorithm, metadata));
-    this._changeQueues.set(docId, current.catch(() => {
-    }));
+    this._changeQueues.set(
+      docId,
+      current.catch(() => {
+      })
+    );
     return current;
   }
   async _processDocChange(docId, ops, doc, algorithm, metadata) {

package/dist/net/PatchesClient.d.ts

@@ -57,7 +57,10 @@ declare class PatchesClient implements PatchesAPI {
      * @param options - Optional commit settings (e.g., forceCommit for migrations).
      * @returns A promise resolving with the changes as committed by the server (potentially transformed).
      */
-    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<{
+        changes: Change[];
+        docReloadRequired?: true;
+    }>;
     /**
      * Deletes a document on the server.
      * @param docId - The ID of the document to delete.

package/dist/net/PatchesSync.js

@@ -286,9 +286,20 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [blockable],
         if (!this.state.connected) {
           throw new Error("Disconnected during flush");
         }
-        const committed = await this.ws.commitChanges(docId, changeBatch);
-        await this._applyServerChangesToDoc(docId, committed);
-        await algorithm.confirmSent(docId, changeBatch);
+        const { changes: committed, docReloadRequired } = await this.ws.commitChanges(docId, changeBatch);
+        if (docReloadRequired) {
+          await algorithm.confirmSent(docId, changeBatch);
+          const snapshot = await this.ws.getDoc(docId);
+          await algorithm.store.saveDoc(docId, snapshot);
+          this._updateDocSyncState(docId, { committedRev: snapshot.rev });
+          const openDoc = this.patches.getOpenDoc(docId);
+          if (openDoc) {
+            openDoc.import({ ...snapshot, changes: [] });
+          }
+        } else {
+          await this._applyServerChangesToDoc(docId, committed);
+          await algorithm.confirmSent(docId, changeBatch);
+        }
         pending = await algorithm.getPendingToSend(docId) ?? [];
       }
       const stillHasPending = await algorithm.hasPending(docId);

package/dist/net/protocol/JSONRPCServer.js

@@ -111,6 +111,21 @@ class JSONRPCServer {
     if ("id" in message && message.id !== void 0) {
       try {
         const result = await this._dispatch(message.method, message.params, ctx);
+        if (result && typeof result === "object" && typeof result.getReader === "function") {
+          const reader = result.getReader();
+          const chunks = [];
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            chunks.push(value);
+          }
+          const json = chunks.join("");
+          if (typeof raw === "string") {
+            return `{"jsonrpc":"2.0","id":${JSON.stringify(message.id)},"result":${json}}`;
+          } else {
+            return { jsonrpc: "2.0", id: message.id, result: JSON.parse(json) };
+          }
+        }
         const response = rpcResponse(result, message.id);
         return respond(response);
       } catch (err) {

package/dist/net/protocol/types.d.ts

@@ -122,8 +122,11 @@ interface PatchesAPI {
     getDoc(docId: string): Promise<PatchesState>;
     /** Get changes that occurred after a specific revision. */
     getChangesSince(docId: string, rev: number): Promise<Change[]>;
-    /** Apply a set of changes from the client to a document. Returns the committed changes. */
-    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    /** Apply a set of changes from the client to a document. Returns the committed changes and an optional reload flag. */
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<{
+        changes: Change[];
+        docReloadRequired?: true;
+    }>;
     /** Delete a document. */
     deleteDoc(docId: string): Promise<void>;
     /** Create a new named version snapshot of a document's current state. */

package/dist/server/CompressedStoreBackend.d.ts

@@ -34,12 +34,13 @@ declare class CompressedStoreBackend implements OTStoreBackend, Partial<Tombston
     private decompressChange;
     saveChanges(docId: string, changes: Change[]): Promise<void>;
     listChanges(docId: string, options: ListChangesOptions): Promise<Change[]>;
-    createVersion(docId: string, metadata: VersionMetadata, state: any, changes?: Change[]): Promise<void>;
-    appendVersionChanges(docId: string, versionId: string, changes: Change[], newEndedAt: number, newRev: number, newState: any): Promise<void>;
+    createVersion(docId: string, metadata: VersionMetadata, changes?: Change[]): Promise<void>;
     loadVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    getCurrentRev(docId: string): Promise<number>;
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
-    loadVersionState(docId: string, versionId: string): Promise<any | undefined>;
+    loadVersion(docId: string, versionId: string): Promise<VersionMetadata | undefined>;
+    loadVersionState(docId: string, versionId: string): Promise<string | ReadableStream<string> | undefined>;
     deleteDoc(docId: string): Promise<void>;
     createTombstone(tombstone: DocumentTombstone): Promise<void>;
     getTombstone(docId: string): Promise<DocumentTombstone | undefined>;

package/dist/server/CompressedStoreBackend.js

@@ -35,32 +35,27 @@ class CompressedStoreBackend {
     return stored.map((s) => this.decompressChange(s));
   }
   // === Version Operations (compress changes and state ops) ===
-  async createVersion(docId, metadata, state, changes) {
+  async createVersion(docId, metadata, changes) {
     const compressedChanges = changes?.map((c) => this.compressChange(c));
-    return this.store.createVersion(docId, metadata, state, compressedChanges);
-  }
-  async appendVersionChanges(docId, versionId, changes, newEndedAt, newRev, newState) {
-    const compressedChanges = changes.map((c) => this.compressChange(c));
-    return this.store.appendVersionChanges?.(
-      docId,
-      versionId,
-      compressedChanges,
-      newEndedAt,
-      newRev,
-      newState
-    );
+    return this.store.createVersion(docId, metadata, compressedChanges);
   }
   async loadVersionChanges(docId, versionId) {
     const stored = await this.store.loadVersionChanges?.(docId, versionId);
     return stored?.map((s) => this.decompressChange(s)) ?? [];
   }
   // === Pass-through Operations (no compression needed) ===
+  async getCurrentRev(docId) {
+    return this.store.getCurrentRev(docId);
+  }
   async updateVersion(docId, versionId, metadata) {
     return this.store.updateVersion(docId, versionId, metadata);
   }
   async listVersions(docId, options) {
     return this.store.listVersions(docId, options);
   }
+  async loadVersion(docId, versionId) {
+    return this.store.loadVersion(docId, versionId);
+  }
   async loadVersionState(docId, versionId) {
     return this.store.loadVersionState(docId, versionId);
   }

package/dist/server/LWWBranchManager.js

@@ -1,4 +1,5 @@
 import "../chunk-IZ2YBCUP.js";
+import { JSONPatch } from "../json-patch/JSONPatch.js";
 import {
   assertBranchMetadata,
   assertBranchOpenForMerge,
@@ -8,6 +9,7 @@ import {
   generateBranchId,
   wrapMergeCommit
 } from "./branchUtils.js";
+import { readStreamAsString } from "./jsonReadable.js";
 class LWWBranchManager {
   constructor(store, lwwServer) {
     this.store = store;
@@ -36,10 +38,17 @@ class LWWBranchManager {
    */
   async createBranch(docId, atPoint, metadata) {
     await assertNotABranch(this.store, docId);
-    const doc = await this.lwwServer.getDoc(docId);
+    const snapshot = await this.store.getSnapshot(docId);
+    const baseRev = snapshot?.rev ?? 0;
+    let state = snapshot ? JSON.parse(await readStreamAsString(snapshot.state)) : {};
     const ops = await this.store.listOps(docId);
+    const opsAfterSnapshot = ops.filter((op) => (op.rev ?? 0) > baseRev);
+    if (opsAfterSnapshot.length > 0) {
+      state = new JSONPatch(opsAfterSnapshot).apply(state);
+    }
+    const rev = ops.length > 0 ? Math.max(baseRev, ...ops.map((op) => op.rev ?? 0)) : baseRev;
     const branchDocId = await generateBranchId(this.store, docId);
-    await this.store.saveSnapshot(branchDocId, doc.state, doc.rev);
+    await this.store.saveSnapshot(branchDocId, state, rev);
     if (ops.length > 0) {
       await this.store.saveOps(branchDocId, ops);
     }
@@ -85,7 +94,7 @@ class LWWBranchManager {
       await this.closeBranch(branchId, "merged");
       return [];
     }
-    const committedChanges = await wrapMergeCommit(
+    const { changes: committedChanges } = await wrapMergeCommit(
       branchId,
       sourceDocId,
       () => this.lwwServer.commitChanges(sourceDocId, branchChanges)

package/dist/server/LWWMemoryStoreBackend.d.ts

@@ -1,6 +1,6 @@
 import { JSONPatchOp } from '../json-patch/types.js';
 import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, Branch } from '../types.js';
-import { LWWStoreBackend, VersioningStoreBackend, TombstoneStoreBackend, BranchingStoreBackend, ListFieldsOptions } from './types.js';
+import { LWWStoreBackend, VersioningStoreBackend, TombstoneStoreBackend, BranchingStoreBackend, SnapshotResult, ListFieldsOptions } from './types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
@@ -14,7 +14,6 @@ interface DocData {
 }
 interface VersionData {
     metadata: VersionMetadata;
-    state: any;
 }
 /**
  * In-memory implementation of LWWStoreBackend for testing.
@@ -37,10 +36,7 @@ declare class LWWMemoryStoreBackend implements LWWStoreBackend, VersioningStoreB
     private branches;
     private getOrCreateDoc;
     getCurrentRev(docId: string): Promise<number>;
-    getSnapshot(docId: string): Promise<{
-        state: any;
-        rev: number;
-    } | null>;
+    getSnapshot(docId: string): Promise<SnapshotResult | null>;
     saveSnapshot(docId: string, state: any, rev: number): Promise<void>;
     saveOps(docId: string, newOps: JSONPatchOp[], pathsToDelete?: string[]): Promise<number>;
     listOps(docId: string, options?: ListFieldsOptions): Promise<JSONPatchOp[]>;
@@ -48,9 +44,10 @@ declare class LWWMemoryStoreBackend implements LWWStoreBackend, VersioningStoreB
     createTombstone(tombstone: DocumentTombstone): Promise<void>;
     getTombstone(docId: string): Promise<DocumentTombstone | undefined>;
     removeTombstone(docId: string): Promise<void>;
-    createVersion(docId: string, metadata: VersionMetadata, state: any, _changes?: Change[]): Promise<void>;
+    createVersion(docId: string, metadata: VersionMetadata, _changes?: Change[]): Promise<void>;
     listVersions(docId: string, options?: ListVersionsOptions): Promise<VersionMetadata[]>;
-    loadVersionState(docId: string, versionId: string): Promise<any | undefined>;
+    loadVersion(docId: string, versionId: string): Promise<VersionMetadata | undefined>;
+    loadVersionState(_docId: string, _versionId: string): Promise<string | undefined>;
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     listBranches(docId: string): Promise<Branch[]>;
     loadBranch(branchId: string): Promise<Branch | null>;

package/dist/server/LWWMemoryStoreBackend.js

@@ -1,4 +1,5 @@
 import "../chunk-IZ2YBCUP.js";
+import { jsonReadable } from "./jsonReadable.js";
 class LWWMemoryStoreBackend {
   docs = /* @__PURE__ */ new Map();
   tombstones = /* @__PURE__ */ new Map();
@@ -18,7 +19,9 @@ class LWWMemoryStoreBackend {
   }
   // === Snapshot ===
   async getSnapshot(docId) {
-    return this.docs.get(docId)?.snapshot ?? null;
+    const snapshot = this.docs.get(docId)?.snapshot;
+    if (!snapshot) return null;
+    return { rev: snapshot.rev, state: jsonReadable(JSON.stringify(snapshot.state)) };
   }
   async saveSnapshot(docId, state, rev) {
     const doc = this.getOrCreateDoc(docId);
@@ -74,9 +77,9 @@ class LWWMemoryStoreBackend {
     this.tombstones.delete(docId);
   }
   // === Versioning ===
-  async createVersion(docId, metadata, state, _changes) {
+  async createVersion(docId, metadata, _changes) {
     const versions = this.versions.get(docId) || [];
-    versions.push({ metadata, state });
+    versions.push({ metadata });
     this.versions.set(docId, versions);
   }
   async listVersions(docId, options) {
@@ -111,10 +114,12 @@ class LWWMemoryStoreBackend {
     }
     return result;
   }
-  async loadVersionState(docId, versionId) {
+  async loadVersion(docId, versionId) {
     const versions = this.versions.get(docId) || [];
-    const version = versions.find((v) => v.metadata.id === versionId);
-    return version?.state;
+    return versions.find((v) => v.metadata.id === versionId)?.metadata;
+  }
+  async loadVersionState(_docId, _versionId) {
+    return void 0;
   }
   async updateVersion(docId, versionId, metadata) {
     const versions = this.versions.get(docId) || [];

package/dist/server/LWWServer.d.ts

@@ -1,6 +1,6 @@
 import * as easy_signal from 'easy-signal';
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { Change, CommitChangesOptions, DeleteDocOptions, PatchesState, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { Change, CommitChangesOptions, DeleteDocOptions, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
 import { PatchesServer } from './PatchesServer.js';
 import { LWWStoreBackend } from './types.js';
 import '../net/websocket/AuthorizationProvider.js';
@@ -13,11 +13,6 @@ import '../net/protocol/types.js';
  * Configuration options for LWWServer.
  */
 interface LWWServerOptions {
-    /**
-     * Number of revisions between automatic snapshots.
-     * Defaults to 200.
-     */
-    snapshotInterval?: number;
 }
 /**
  * Last-Write-Wins (LWW) server implementation.
@@ -53,27 +48,27 @@ declare class LWWServer implements PatchesServer {
      */
     static api: ApiDefinition;
     readonly store: LWWStoreBackend;
-    private readonly snapshotInterval;
     /** Notifies listeners whenever a batch of changes is successfully committed. */
     readonly onChangesCommitted: easy_signal.Signal<(docId: string, changes: Change[], options?: CommitChangesOptions, originClientId?: string) => void>;
     /** Notifies listeners when a document is deleted. */
     readonly onDocDeleted: easy_signal.Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
-    constructor(store: LWWStoreBackend, options?: LWWServerOptions);
+    constructor(store: LWWStoreBackend, _options?: LWWServerOptions);
     /**
-     * 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.
      */
-    getDoc(docId: string): Promise<PatchesState>;
+    getDoc(docId: string): Promise<ReadableStream<string>>;
     /**
      * Get changes that occurred after a specific revision.
      * LWW doesn't store changes, so this synthesizes a change from ops.
      *
      * @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).
      */
     getChangesSince(docId: string, rev: number): Promise<Change[]>;
     /**
@@ -87,9 +82,12 @@ declare class LWWServer implements PatchesServer {
      * @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).
      */
-    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<{
+        changes: Change[];
+        docReloadRequired?: true;
+    }>;
     /**
      * Delete a document and emit deletion signal.
      * Creates a tombstone if the store supports it.
@@ -106,6 +104,7 @@ declare class LWWServer implements PatchesServer {
     undeleteDoc(docId: string): Promise<boolean>;
     /**
      * 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.
@@ -115,6 +114,8 @@ declare class LWWServer implements PatchesServer {
     /**
      * 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.