@dabble/patches 0.8.6 → 0.8.8

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

@@ -198,78 +198,37 @@ function splitLargeInsertText(text, maxChunkLength, attributes) {
   }
   return results;
 }
+function stripTextDeltas(value, basePath, textOps) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  if (Array.isArray(value.ops) && value.ops.some((op) => op.insert !== void 0)) {
+    textOps.push({ op: "@txt", path: basePath, value: value.ops });
+    const { ops: _ops, ...stub } = value;
+    return stub;
+  }
+  const result = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = stripTextDeltas(val, `${basePath}/${key}`, textOps);
+  }
+  return result;
+}
 function breakLargeValueOp(origChange, op, maxBytes, startRev, sizeCalculator) {
-  const results = [];
-  let rev = startRev;
-  const baseOpSize = getSizeForStorage({ ...op, value: "" }, sizeCalculator);
-  const baseChangeSize = getSizeForStorage({ ...origChange, ops: [{ ...op, value: "" }] }, sizeCalculator) - baseOpSize;
-  const valueBudget = maxBytes - baseChangeSize - 50;
-  if (typeof op.value === "string" && op.value.length > 100) {
-    const text = op.value;
-    const targetChunkSize = Math.max(1, valueBudget);
-    const numChunks = Math.ceil(text.length / targetChunkSize);
-    const chunkSize = Math.ceil(text.length / numChunks);
-    for (let i = 0; i < text.length; i += chunkSize) {
-      const chunk = text.slice(i, i + chunkSize);
-      const newOp = { op: "add" };
-      if (i === 0) {
-        newOp.op = op.op;
-        newOp.path = op.path;
-        newOp.value = chunk;
-      } else {
-        newOp.op = "patch";
-        newOp.path = op.path;
-        newOp.appendString = chunk;
-      }
-      results.push(deriveNewChange(origChange, rev++, [newOp]));
-    }
-    return results;
-  } else if (Array.isArray(op.value) && op.value.length > 1) {
-    const originalArray = op.value;
-    let currentChunk = [];
-    let chunkStartIndex = 0;
-    for (let i = 0; i < originalArray.length; i++) {
-      const item = originalArray[i];
-      const tentativeChunk = [...currentChunk, item];
-      const tentativeOp = { ...op, value: tentativeChunk };
-      const tentativeChangeSize = getSizeForStorage({ ...origChange, ops: [tentativeOp] }, sizeCalculator);
-      if (currentChunk.length > 0 && tentativeChangeSize > maxBytes) {
-        const chunkOp = {};
-        if (chunkStartIndex === 0) {
-          chunkOp.op = op.op;
-          chunkOp.path = op.path;
-          chunkOp.value = currentChunk;
-        } else {
-          chunkOp.op = "patch";
-          chunkOp.path = op.path;
-          chunkOp.appendArray = currentChunk;
-        }
-        results.push(deriveNewChange(origChange, rev++, [chunkOp]));
-        currentChunk = [item];
-        chunkStartIndex = i;
-      } else {
-        currentChunk.push(item);
-      }
-    }
-    if (currentChunk.length > 0) {
-      const chunkOp = {};
-      if (chunkStartIndex === 0) {
-        chunkOp.op = op.op;
-        chunkOp.path = op.path;
-        chunkOp.value = currentChunk;
-      } else {
-        chunkOp.op = "patch";
-        chunkOp.path = op.path;
-        chunkOp.appendArray = currentChunk;
-      }
-      results.push(deriveNewChange(origChange, rev, [chunkOp]));
-    }
-    return results;
+  const value = op.value;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    console.warn(`Oversized op ${op.op} at "${op.path}" is not an object; including as-is`);
+    return [deriveNewChange(origChange, startRev, [op])];
+  }
+  const textOps = [];
+  const strippedValue = stripTextDeltas(value, op.path, textOps);
+  if (textOps.length === 0) {
+    console.warn(`Oversized op ${op.op} at "${op.path}" has no text deltas; including as-is`);
+    return [deriveNewChange(origChange, startRev, [op])];
+  }
+  const allOps = [{ ...op, value: strippedValue }, ...textOps];
+  const combinedChange = deriveNewChange(origChange, startRev, allOps);
+  if (getSizeForStorage(combinedChange, sizeCalculator) <= maxBytes) {
+    return [combinedChange];
   }
-  console.warn(
-    `Warning: Single operation of type ${op.op} (path: ${op.path}) could not be split further by breakLargeValueOp despite exceeding maxBytes. Including as is.`
-  );
-  return [deriveNewChange(origChange, rev, [op])];
+  return breakSingleChange(combinedChange, maxBytes, sizeCalculator);
 }
 function deriveNewChange(origChange, rev, ops) {
   const { id: _id, ops: _o, rev: _r, baseRev: _br, created: _c, batchId: _bi, ...metadata } = origChange;

package/dist/client/LWWInMemoryStore.d.ts

@@ -31,7 +31,7 @@ declare class LWWInMemoryStore implements LWWClientStore {
     listDocs(includeDeleted?: boolean): Promise<TrackedDoc[]>;
     /**
      * Saves the current document state to storage.
-     * Clears all committed fields, pending ops, and sending change.
+     * Clears committed fields (subsumed by the snapshot) but preserves pending ops.
      */
     saveDoc(docId: string, docState: PatchesState): Promise<void>;
     /**
@@ -71,7 +71,13 @@ declare class LWWInMemoryStore implements LWWClientStore {
      */
     saveSendingChange(docId: string, change: Change): Promise<void>;
     /**
-     * Clear sendingChange after server ack, move ops to committed.
+     * Move sending ops to committed, then clear the sending slot.
+     * committedRev is NOT updated here — applyServerChanges owns that using the
+     * server's actual rev. Updating it here would bump the rev above the server's
+     * real value for noop changes (where the server doesn't create a new rev).
+     *
+     * Call this BEFORE applyServerChanges so that server corrections (which run
+     * after) overwrite any stale ops for fields the server won via LWW.
      */
     confirmSendingChange(docId: string): Promise<void>;
     /**

package/dist/client/LWWInMemoryStore.js

@@ -51,14 +51,15 @@ class LWWInMemoryStore {
   }
   /**
    * Saves the current document state to storage.
-   * Clears all committed fields, pending ops, and sending change.
+   * Clears committed fields (subsumed by the snapshot) but preserves pending ops.
    */
   async saveDoc(docId, docState) {
+    const existing = this.docs.get(docId);
     this.docs.set(docId, {
       snapshot: { state: docState.state, rev: docState.rev },
       committedFields: /* @__PURE__ */ new Map(),
-      pendingOps: /* @__PURE__ */ new Map(),
-      sendingChange: null,
+      pendingOps: existing?.pendingOps ?? /* @__PURE__ */ new Map(),
+      sendingChange: existing?.sendingChange ?? null,
       committedRev: docState.rev
     });
   }
@@ -150,7 +151,13 @@ class LWWInMemoryStore {
     buf.pendingOps.clear();
   }
   /**
-   * Clear sendingChange after server ack, move ops to committed.
+   * Move sending ops to committed, then clear the sending slot.
+   * committedRev is NOT updated here — applyServerChanges owns that using the
+   * server's actual rev. Updating it here would bump the rev above the server's
+   * real value for noop changes (where the server doesn't create a new rev).
+   *
+   * Call this BEFORE applyServerChanges so that server corrections (which run
+   * after) overwrite any stale ops for fields the server won via LWW.
    */
   async confirmSendingChange(docId) {
     const buf = this.docs.get(docId);
@@ -158,10 +165,6 @@ 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.d.ts

@@ -73,7 +73,7 @@ declare class LWWIndexedDBStore implements LWWClientStore {
     getDoc(docId: string): Promise<PatchesSnapshot | undefined>;
     /**
      * Saves the current document state to storage.
-     * Clears all committed fields and pending ops.
+     * Clears committed fields (subsumed by the snapshot) but preserves pending ops.
      */
     saveDoc(docId: string, docState: PatchesState): Promise<void>;
     /**
@@ -101,7 +101,13 @@ declare class LWWIndexedDBStore implements LWWClientStore {
      */
     saveSendingChange(docId: string, change: Change): Promise<void>;
     /**
-     * Clear sendingChange after server ack, move ops to committed.
+     * Move sending ops to committed, then clear the sending slot.
+     * committedRev is NOT updated here — applyServerChanges owns that using the
+     * server's actual rev. Updating it here would bump the rev above the server's
+     * real value for noop changes (where the server doesn't create a new rev).
+     *
+     * Call this BEFORE applyServerChanges so that server corrections (which run
+     * after) overwrite any stale ops for fields the server won via LWW.
      */
     confirmSendingChange(docId: string): Promise<void>;
     /**

package/dist/client/LWWIndexedDBStore.js

@@ -122,17 +122,15 @@ class LWWIndexedDBStore {
     };
   }
   async saveDoc(docId, docState) {
-    const [tx, snapshots, committedOps, pendingOps, sendingChanges, docsStore] = await this.db.transaction(
-      ["snapshots", "committedOps", "pendingOps", "sendingChanges", "docs"],
+    const [tx, snapshots, committedOps, docsStore] = await this.db.transaction(
+      ["snapshots", "committedOps", "docs"],
       "readwrite"
     );
     const { rev, state } = docState;
     await Promise.all([
       docsStore.put({ docId, committedRev: rev, algorithm: "lww" }),
       snapshots.put({ docId, state, rev }),
-      this.deleteFieldsForDoc(committedOps, docId),
-      this.deleteFieldsForDoc(pendingOps, docId),
-      sendingChanges.delete(docId)
+      this.deleteFieldsForDoc(committedOps, docId)
     ]);
     await tx.complete();
   }
@@ -233,8 +231,8 @@ class LWWIndexedDBStore {
     await tx.complete();
   }
   async confirmSendingChange(docId) {
-    const [tx, sendingChanges, committedOps, docsStore] = await this.db.transaction(
-      ["sendingChanges", "committedOps", "docs"],
+    const [tx, sendingChanges, committedOps] = await this.db.transaction(
+      ["sendingChanges", "committedOps"],
       "readwrite"
     );
     const sending = await sendingChanges.get(docId);
@@ -243,13 +241,6 @@ 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/OTInMemoryStore.js

@@ -31,10 +31,11 @@ class OTInMemoryStore {
   }
   // ─── Writes ────────────────────────────────────────────────────────────
   async saveDoc(docId, snapshot) {
+    const existing = this.docs.get(docId);
     this.docs.set(docId, {
       snapshot,
       committed: [],
-      pending: []
+      pending: existing?.pending ?? []
     });
   }
   async savePendingChanges(docId, changes) {

package/dist/client/OTIndexedDBStore.js

@@ -119,8 +119,7 @@ class OTIndexedDBStore {
     await Promise.all([
       docsStore.put({ docId, committedRev: rev, algorithm: "ot" }),
       snapshots.put({ docId, state, rev }),
-      committedChanges.delete([docId, 0], [docId, Infinity]),
-      pendingChanges.delete([docId, 0], [docId, Infinity])
+      committedChanges.delete([docId, 0], [docId, Infinity])
     ]);
     await tx.complete();
   }

package/dist/client/PatchesBranchClient.d.ts

@@ -0,0 +1,31 @@
+import { Store } from 'easy-signal';
+import { BranchAPI } from '../net/protocol/types.js';
+import { Branch, EditableBranchMetadata } from '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
+/**
+ * Client-side branch management interface for a document.
+ * Allows listing, creating, closing, and merging branches.
+ */
+declare class PatchesBranchClient {
+    private readonly api;
+    /** Document ID */
+    readonly id: string;
+    /** Store for the branches list */
+    readonly branches: Store<Branch[]>;
+    constructor(id: string, api: BranchAPI);
+    /** List all branches for this document */
+    listBranches(): Promise<Branch[]>;
+    /** Create a new branch from a specific revision */
+    createBranch(rev: number, metadata?: EditableBranchMetadata): Promise<string>;
+    /** Close a branch without merging its changes */
+    closeBranch(branchId: string): Promise<void>;
+    /** Merge a branch's changes back into this document */
+    mergeBranch(branchId: string): Promise<void>;
+    /** Clear state */
+    clear(): void;
+}
+
+export { PatchesBranchClient };

package/dist/client/PatchesBranchClient.js

@@ -0,0 +1,41 @@
+import "../chunk-IZ2YBCUP.js";
+import { store } from "easy-signal";
+class PatchesBranchClient {
+  constructor(id, api) {
+    this.api = api;
+    this.id = id;
+    this.branches = store([]);
+  }
+  /** Document ID */
+  id;
+  /** Store for the branches list */
+  branches;
+  /** List all branches for this document */
+  async listBranches() {
+    this.branches.state = await this.api.listBranches(this.id);
+    return this.branches.state;
+  }
+  /** Create a new branch from a specific revision */
+  async createBranch(rev, metadata) {
+    const branchId = await this.api.createBranch(this.id, rev, metadata);
+    await this.listBranches();
+    return branchId;
+  }
+  /** Close a branch without merging its changes */
+  async closeBranch(branchId) {
+    await this.api.closeBranch(branchId);
+    await this.listBranches();
+  }
+  /** Merge a branch's changes back into this document */
+  async mergeBranch(branchId) {
+    await this.api.mergeBranch(branchId);
+    await this.listBranches();
+  }
+  /** Clear state */
+  clear() {
+    this.branches.state = [];
+  }
+}
+export {
+  PatchesBranchClient
+};

package/dist/client/index.d.ts

@@ -10,6 +10,7 @@ export { LWWAlgorithm } from './LWWAlgorithm.js';
 export { LWWBatcher } from './LWWBatcher.js';
 export { OTAlgorithm } from './OTAlgorithm.js';
 export { OpenDocOptions, Patches, PatchesOptions } from './Patches.js';
+export { PatchesBranchClient } from './PatchesBranchClient.js';
 export { PatchesHistoryClient } from './PatchesHistoryClient.js';
 export { AlgorithmName, PatchesStore, TrackedDoc } from './PatchesStore.js';
 export { OTClientStore } from './OTClientStore.js';

package/dist/client/index.js

@@ -12,4 +12,5 @@ export * from "./OTDoc.js";
 export * from "./OTAlgorithm.js";
 export * from "./Patches.js";
 export * from "./PatchesDoc.js";
+export * from "./PatchesBranchClient.js";
 export * from "./PatchesHistoryClient.js";

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { LWWAlgorithm } from './client/LWWAlgorithm.js';
 export { LWWBatcher } from './client/LWWBatcher.js';
 export { OTAlgorithm } from './client/OTAlgorithm.js';
 export { OpenDocOptions, Patches, PatchesOptions } from './client/Patches.js';
+export { PatchesBranchClient } from './client/PatchesBranchClient.js';
 export { PatchesHistoryClient } from './client/PatchesHistoryClient.js';
 export { AlgorithmName, PatchesStore, TrackedDoc } from './client/PatchesStore.js';
 export { OTClientStore } from './client/OTClientStore.js';

package/dist/net/PatchesClient.d.ts

@@ -1,5 +1,5 @@
 import * as easy_signal from 'easy-signal';
-import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot, Branch } from '../types.js';
+import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot, Branch, EditableBranchMetadata } from '../types.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
 import { PatchesAPI, ClientTransport } from './protocol/types.js';
 import '../json-patch/JSONPatch.js';
@@ -117,7 +117,7 @@ declare class PatchesClient implements PatchesAPI {
      * @param metadata - Optional metadata for the new branch.
      * @returns A promise resolving with the unique ID of the newly created branch.
      */
-    createBranch(docId: string, rev: number, metadata?: EditableVersionMetadata): Promise<string>;
+    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata, initialChanges?: Change[]): Promise<string>;
     /**
      * Closes a branch on the server.
      * @param branchId - The ID of the branch to close.

package/dist/net/PatchesClient.js

@@ -143,8 +143,8 @@ class PatchesClient {
    * @param metadata - Optional metadata for the new branch.
    * @returns A promise resolving with the unique ID of the newly created branch.
    */
-  async createBranch(docId, rev, metadata) {
-    return this.rpc.call("createBranch", docId, rev, metadata);
+  async createBranch(docId, rev, metadata, initialChanges) {
+    return this.rpc.call("createBranch", docId, rev, metadata, initialChanges);
   }
   /**
    * Closes a branch on the server.

package/dist/net/PatchesSync.js

@@ -318,8 +318,8 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
             openDoc.import({ ...snapshot, changes: [] });
           }
         } else {
-          await this._applyServerChangesToDoc(docId, committed);
           await algorithm.confirmSent(docId, changeBatch);
+          await this._applyServerChangesToDoc(docId, committed);
         }
         pending = await algorithm.getPendingToSend(docId) ?? [];
       }

package/dist/net/index.d.ts

@@ -8,7 +8,7 @@ export { encodeDocId, normalizeIds } from './rest/utils.js';
 export { JSONRPCClient } from './protocol/JSONRPCClient.js';
 export { ApiDefinition, ConnectionSignalSubscriber, JSONRPCServer, JSONRPCServerOptions, MessageHandler } from './protocol/JSONRPCServer.js';
 export { getAuthContext, getClientId } from './serverContext.js';
-export { AwarenessUpdateNotificationParams, ClientTransport, ConnectionState, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, Message, PatchesAPI, PatchesNotificationParams, ServerTransport, SignalNotificationParams } from './protocol/types.js';
+export { AwarenessUpdateNotificationParams, BranchAPI, ClientTransport, ConnectionState, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, Message, PatchesAPI, PatchesNotificationParams, ServerTransport, SignalNotificationParams } from './protocol/types.js';
 export { rpcError, rpcNotification, rpcResponse } from './protocol/utils.js';
 export { Access, AuthContext, AuthorizationProvider, allowAll, assertNotDeleted, denyAll } from './websocket/AuthorizationProvider.js';
 export { onlineState } from './websocket/onlineState.js';

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

@@ -1,5 +1,5 @@
 import { Unsubscriber } from 'easy-signal';
-import { PatchesState, Change, ChangeInput, CommitChangesOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata } from '../../types.js';
+import { Branch, EditableBranchMetadata, Change, PatchesState, ChangeInput, CommitChangesOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata } from '../../types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../../json-patch/types.js';
@@ -131,6 +131,12 @@ interface PatchesAPI {
     /** Update the name and other metadata of a specific version. */
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
 }
+interface BranchAPI {
+    listBranches(docId: string): Promise<Branch[]>;
+    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata, initialChanges?: Change[]): Promise<string>;
+    closeBranch(branchId: string): Promise<void>;
+    mergeBranch(branchId: string): Promise<void>;
+}
 interface PatchesNotificationParams {
     docId: string;
     changes: Change[];
@@ -148,4 +154,4 @@ interface SignalNotificationParams {
     data: any;
 }
 
-export { type AwarenessUpdateNotificationParams, type ClientTransport, CommitChangesOptions, type ConnectionState, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type Message, type PatchesAPI, type PatchesNotificationParams, type ServerTransport, type SignalNotificationParams };
+export { type AwarenessUpdateNotificationParams, type BranchAPI, type ClientTransport, CommitChangesOptions, type ConnectionState, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type Message, type PatchesAPI, type PatchesNotificationParams, type ServerTransport, type SignalNotificationParams };

package/dist/net/rest/PatchesREST.d.ts

@@ -1,5 +1,5 @@
 import * as easy_signal from 'easy-signal';
-import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot, Branch } from '../../types.js';
+import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot, Branch, EditableBranchMetadata } from '../../types.js';
 import { PatchesConnection } from '../PatchesConnection.js';
 import { ConnectionState } from '../protocol/types.js';
 import '../../json-patch/JSONPatch.js';
@@ -62,7 +62,7 @@ declare class PatchesREST implements PatchesConnection {
     getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     listBranches(docId: string): Promise<Branch[]>;
-    createBranch(docId: string, rev: number, metadata?: EditableVersionMetadata): Promise<string>;
+    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata, initialChanges?: Change[]): Promise<string>;
     closeBranch(branchId: string): Promise<void>;
     mergeBranch(branchId: string): Promise<void>;
     private _setState;

package/dist/net/rest/PatchesREST.js

@@ -155,10 +155,10 @@ class PatchesREST {
   async listBranches(docId) {
     return this._fetch(`/docs/${encodeDocId(docId)}/_branches`);
   }
-  async createBranch(docId, rev, metadata) {
+  async createBranch(docId, rev, metadata, initialChanges) {
     return this._fetch(`/docs/${encodeDocId(docId)}/_branches`, {
       method: "POST",
-      body: { rev, ...metadata }
+      body: { rev, ...metadata, ...initialChanges ? { initialChanges } : {} }
     });
   }
   async closeBranch(branchId) {

package/dist/net/rest/SSEServer.js

@@ -52,7 +52,7 @@ class SSEServer {
     }
     const { readable, writable } = new TransformStream();
     client.writer = writable.getWriter();
-    client.writer.write(client.encoder.encode(": connected\n\n"));
+    client.writer.write(client.encoder.encode("retry: 5000\n\n"));
     if (lastEventId) {
       const lastId = parseInt(lastEventId, 10);
       if (isNaN(lastId)) {

package/dist/server/BranchManager.d.ts

@@ -1,4 +1,4 @@
-import { Branch, EditableBranchMetadata, BranchStatus, Change } from '../types.js';
+import { Branch, EditableBranchMetadata, Change, BranchStatus } from '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
@@ -23,9 +23,12 @@ interface BranchManager {
      * @param docId - The source document ID.
      * @param atPoint - Algorithm-specific branching point (revision for OT, typically current rev for LWW).
      * @param metadata - Optional branch metadata (name, custom fields).
+     * @param initialChanges - Optional pre-built initialization changes. If provided, stored directly
+     *   and contentStartRev is set to lastChange.rev + 1. If omitted, the implementation generates
+     *   initialization changes from the source state.
      * @returns The new branch document ID.
      */
-    createBranch(docId: string, atPoint: number, metadata?: EditableBranchMetadata): Promise<string>;
+    createBranch(docId: string, atPoint: number, metadata?: EditableBranchMetadata, initialChanges?: Change[]): Promise<string>;
     /**
      * Updates branch metadata.
      * @param branchId - The branch document ID.

package/dist/server/LWWBranchManager.d.ts

@@ -1,5 +1,5 @@
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { Branch, EditableBranchMetadata, BranchStatus, Change } from '../types.js';
+import { Branch, EditableBranchMetadata, Change, BranchStatus } from '../types.js';
 import { BranchManager } from './BranchManager.js';
 import { LWWServer } from './LWWServer.js';
 import { LWWStoreBackend, BranchingStoreBackend } from './types.js';
@@ -52,7 +52,7 @@ declare class LWWBranchManager implements BranchManager {
      * @param metadata - Optional branch metadata.
      * @returns The new branch document ID.
      */
-    createBranch(docId: string, atPoint: number, metadata?: EditableBranchMetadata): Promise<string>;
+    createBranch(docId: string, atPoint: number, metadata?: EditableBranchMetadata, _initialChanges?: Change[]): Promise<string>;
     /**
      * Updates branch metadata.
      * @param branchId - The branch document ID.

package/dist/server/LWWBranchManager.js

@@ -36,7 +36,7 @@ class LWWBranchManager {
    * @param metadata - Optional branch metadata.
    * @returns The new branch document ID.
    */
-  async createBranch(docId, atPoint, metadata) {
+  async createBranch(docId, atPoint, metadata, _initialChanges) {
     await assertNotABranch(this.store, docId);
     const snapshot = await this.store.getSnapshot(docId);
     const baseRev = snapshot?.rev ?? 0;
@@ -52,7 +52,7 @@ class LWWBranchManager {
     if (ops.length > 0) {
       await this.store.saveOps(branchDocId, ops);
     }
-    const branch = createBranchRecord(branchDocId, docId, atPoint, metadata);
+    const branch = createBranchRecord(branchDocId, docId, atPoint, rev + 1, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
   }

package/dist/server/OTBranchManager.d.ts

@@ -1,5 +1,5 @@
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { Branch, EditableBranchMetadata, BranchStatus, Change } from '../types.js';
+import { Branch, EditableBranchMetadata, Change, BranchStatus } from '../types.js';
 import { BranchManager } from './BranchManager.js';
 import { PatchesServer } from './PatchesServer.js';
 import { OTStoreBackend, BranchingStoreBackend } from './types.js';
@@ -44,11 +44,13 @@ declare class OTBranchManager implements BranchManager {
      * Creates a new branch for a document.
      * @param docId - The ID of the document to branch from.
      * @param rev - The revision of the document to branch from.
-     * @param branchName - Optional name for the branch.
      * @param metadata - Additional optional metadata to store with the branch.
+     * @param initialChanges - Optional pre-built initialization changes. If provided, stored
+     *   directly. If omitted, a root-replace change is generated from the source state at `rev`
+     *   and split via breakChanges when maxPayloadBytes is set.
      * @returns The ID of the new branch document.
      */
-    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata): Promise<string>;
+    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata, initialChanges?: Change[]): Promise<string>;
     /**
      * Updates a branch's metadata.
      * @param branchId - The ID of the branch to update.

package/dist/server/OTBranchManager.js

@@ -31,20 +31,29 @@ class OTBranchManager {
    * Creates a new branch for a document.
    * @param docId - The ID of the document to branch from.
    * @param rev - The revision of the document to branch from.
-   * @param branchName - Optional name for the branch.
    * @param metadata - Additional optional metadata to store with the branch.
+   * @param initialChanges - Optional pre-built initialization changes. If provided, stored
+   *   directly. If omitted, a root-replace change is generated from the source state at `rev`
+   *   and split via breakChanges when maxPayloadBytes is set.
    * @returns The ID of the new branch document.
    */
-  async createBranch(docId, rev, metadata) {
+  async createBranch(docId, rev, metadata, initialChanges) {
     await assertNotABranch(this.store, docId);
-    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]);
+    let initChanges;
+    if (initialChanges?.length) {
+      initChanges = initialChanges;
+    } else {
+      const { state: stateAtRev } = await getStateAtRevision(this.store, docId, rev);
+      const rootReplace = createChange(0, 1, [{ op: "replace", path: "", value: stateAtRev }], {
+        createdAt: now,
+        committedAt: now
+      });
+      initChanges = this.maxPayloadBytes ? breakChanges([rootReplace], this.maxPayloadBytes) : [rootReplace];
+    }
+    const contentStartRev = initChanges[initChanges.length - 1].rev + 1;
+    await this.store.saveChanges(branchDocId, initChanges);
     const initialVersionMetadata = createVersionMetadata({
       origin: "main",
       startedAt: now,
@@ -55,8 +64,8 @@ class OTBranchManager {
       groupId: branchDocId,
       branchName: metadata?.name
     });
-    await this.store.createVersion(branchDocId, initialVersionMetadata, [initialChange]);
-    const branch = createBranchRecord(branchDocId, docId, rev, metadata);
+    await this.store.createVersion(branchDocId, initialVersionMetadata, initChanges);
+    const branch = createBranchRecord(branchDocId, docId, rev, contentStartRev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
   }
@@ -88,7 +97,8 @@ class OTBranchManager {
     assertBranchOpenForMerge(branch, branchId);
     const sourceDocId = branch.docId;
     const branchStartRevOnSource = branch.branchedAtRev;
-    const branchChanges = await this.store.listChanges(branchId, {});
+    const contentStartRev = branch.contentStartRev ?? 2;
+    const branchChanges = await this.store.listChanges(branchId, { startAfter: contentStartRev - 1 });
     if (branchChanges.length === 0) {
       console.log(`Branch ${branchId} has no changes to merge.`);
       await this.closeBranch(branchId, "merged");

package/dist/server/branchUtils.d.ts

@@ -36,10 +36,11 @@ declare function generateBranchId(store: BranchIdGenerator, docId: string): Prom
  * @param branchDocId - The branch document ID.
  * @param sourceDocId - The source document being branched from.
  * @param branchedAtRev - The revision at which the branch was created.
+ * @param contentStartRev - The first revision of user content on the branch (after init changes).
  * @param metadata - Optional branch metadata (name, etc.).
  * @returns A new Branch object.
  */
-declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, metadata?: EditableBranchMetadata): Branch;
+declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, contentStartRev: number, metadata?: EditableBranchMetadata): Branch;
 /**
  * Store interface for branch loading.
  */

package/dist/server/branchUtils.js

@@ -7,7 +7,7 @@ const branchManagerApi = {
   closeBranch: "write",
   mergeBranch: "write"
 };
-const nonModifiableBranchFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status"]);
+const nonModifiableBranchFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status", "contentStartRev"]);
 function assertBranchMetadata(metadata) {
   if (!metadata) return;
   for (const key in metadata) {
@@ -19,12 +19,13 @@ function assertBranchMetadata(metadata) {
 async function generateBranchId(store, docId) {
   return store.createBranchId ? await Promise.resolve(store.createBranchId(docId)) : createId(22);
 }
-function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, metadata) {
+function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, contentStartRev, metadata) {
   return {
     ...metadata,
     id: branchDocId,
     docId: sourceDocId,
     branchedAtRev,
+    contentStartRev,
     createdAt: Date.now(),
     status: "open"
   };

package/dist/server/types.d.ts

@@ -155,8 +155,8 @@ interface BranchingStoreBackend {
     loadBranch(branchId: string): Promise<Branch | null>;
     /** Creates or updates the metadata record for a branch. */
     createBranch(branch: Branch): Promise<void>;
-    /** Updates specific fields (status, name, metadata) of an existing branch record. */
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name' | 'metadata'>>): Promise<void>;
+    /** Updates mutable fields of an existing branch record (excludes immutable identity fields). */
+    updateBranch(branchId: string, updates: Partial<Omit<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'contentStartRev'>>): Promise<void>;
 }
 
 export type { BranchingStoreBackend, LWWStoreBackend, ListFieldsOptions, OTStoreBackend, ServerStoreBackend, SnapshotResult, TombstoneStoreBackend, VersioningStoreBackend };

package/dist/types.d.ts

@@ -96,10 +96,18 @@ interface Branch {
     name?: string;
     /** Current status of the branch. */
     status: BranchStatus;
+    /**
+     * The first revision on the branch that contains user content (after initialization changes).
+     * Initialization changes (e.g. the root-replace that seeds the branch with source state)
+     * are at revisions < contentStartRev and are skipped during merge.
+     * Typically 2 for a single-change initialization; higher when the initial state is split
+     * across multiple changes due to size limits.
+     */
+    contentStartRev: number;
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
-type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'status'>;
+type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'status' | 'contentStartRev'>;
 /**
  * Represents a tombstone for a deleted document.
  * Tombstones persist after deletion to inform late-connecting clients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {