@dabble/patches 0.8.7 → 0.8.9

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 { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata, PatchesState, Change, ChangeInput, CommitChangesOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata } from '../../types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../../json-patch/types.js';
@@ -131,6 +131,13 @@ 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, options?: ListBranchesOptions): Promise<Branch[]>;
+    createBranch(docId: string, rev: number, metadata?: CreateBranchMetadata): Promise<string>;
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
+    deleteBranch(branchId: string): Promise<void>;
+    mergeBranch(branchId: string): Promise<void>;
+}
 interface PatchesNotificationParams {
     docId: string;
     changes: Change[];
@@ -148,4 +155,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, CreateBranchMetadata, EditableBranchMetadata } from '../../types.js';
 import { PatchesConnection } from '../PatchesConnection.js';
 import { ConnectionState } from '../protocol/types.js';
 import '../../json-patch/JSONPatch.js';
@@ -61,10 +61,13 @@ declare class PatchesREST implements PatchesConnection {
     getVersionState(docId: string, versionId: string): Promise<PatchesSnapshot>;
     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>;
-    closeBranch(branchId: string): Promise<void>;
-    mergeBranch(branchId: string): Promise<void>;
+    listBranches(docId: string, options?: {
+        since?: number;
+    }): Promise<Branch[]>;
+    createBranch(docId: string, rev: number, metadata?: CreateBranchMetadata): Promise<string>;
+    updateBranch(docId: string, branchId: string, metadata: EditableBranchMetadata): Promise<void>;
+    deleteBranch(docId: string, branchId: string): Promise<void>;
+    mergeBranch(docId: string, branchId: string): Promise<void>;
     private _setState;
     private _getHeaders;
     private _fetch;

package/dist/net/rest/PatchesREST.js

@@ -2,7 +2,7 @@ import "../../chunk-IZ2YBCUP.js";
 import { signal } from "easy-signal";
 import { StatusError } from "../error.js";
 import { onlineState } from "../websocket/onlineState.js";
-import { encodeDocId, normalizeIds } from "./utils.js";
+import { normalizeIds } from "./utils.js";
 const SESSION_STORAGE_KEY = "patches-clientId";
 class PatchesREST {
   /** The client ID used for SSE connection and subscription management. */
@@ -114,58 +114,68 @@ class PatchesREST {
   }
   // --- PatchesAPI: Documents ---
   async getDoc(docId) {
-    return this._fetch(`/docs/${encodeDocId(docId)}`);
+    return this._fetch(`/docs/${docId}`);
   }
   async getChangesSince(docId, rev) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_changes?since=${rev}`);
+    return this._fetch(`/docs/${docId}/_changes?since=${rev}`);
   }
   async commitChanges(docId, changes, options) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_changes`, {
+    return this._fetch(`/docs/${docId}/_changes`, {
       method: "POST",
       body: { changes, options }
     });
   }
   async deleteDoc(docId, _options) {
-    await this._fetch(`/docs/${encodeDocId(docId)}`, { method: "DELETE" });
+    await this._fetch(`/docs/${docId}`, { method: "DELETE" });
   }
   // --- PatchesAPI: Versions ---
   async createVersion(docId, metadata) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_versions`, {
+    return this._fetch(`/docs/${docId}/_versions`, {
       method: "POST",
       body: metadata
     });
   }
   async listVersions(docId, options) {
     const params = options ? `?${new URLSearchParams(options)}` : "";
-    return this._fetch(`/docs/${encodeDocId(docId)}/_versions${params}`);
+    return this._fetch(`/docs/${docId}/_versions${params}`);
   }
   async getVersionState(docId, versionId) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_versions/${encodeURIComponent(versionId)}`);
+    return this._fetch(`/docs/${docId}/_versions/${encodeURIComponent(versionId)}`);
   }
   async getVersionChanges(docId, versionId) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_versions/${encodeURIComponent(versionId)}/_changes`);
+    return this._fetch(`/docs/${docId}/_versions/${encodeURIComponent(versionId)}/_changes`);
   }
   async updateVersion(docId, versionId, metadata) {
-    await this._fetch(`/docs/${encodeDocId(docId)}/_versions/${encodeURIComponent(versionId)}`, {
+    await this._fetch(`/docs/${docId}/_versions/${encodeURIComponent(versionId)}`, {
       method: "PUT",
       body: metadata
     });
   }
-  // --- Branch Operations (not in PatchesAPI but matches PatchesClient feature parity) ---
-  async listBranches(docId) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_branches`);
+  // --- Branch Operations ---
+  // Note: updateBranch, deleteBranch, and mergeBranch take (docId, branchId) rather than
+  // matching BranchAPI signatures, because the REST URL pattern is /docs/:docId/_branches/:branchId.
+  // Apps using PatchesREST as a branchApi need a thin adapter to bridge the difference.
+  async listBranches(docId, options) {
+    const params = options?.since ? `?since=${encodeURIComponent(String(options.since))}` : "";
+    return this._fetch(`/docs/${docId}/_branches${params}`);
   }
   async createBranch(docId, rev, metadata) {
-    return this._fetch(`/docs/${encodeDocId(docId)}/_branches`, {
+    return this._fetch(`/docs/${docId}/_branches`, {
       method: "POST",
-      body: { rev, ...metadata }
+      body: { branchedAtRev: rev, ...metadata }
     });
   }
-  async closeBranch(branchId) {
-    await this._fetch(`/docs/${encodeDocId(branchId)}`, { method: "DELETE" });
+  async updateBranch(docId, branchId, metadata) {
+    await this._fetch(`/docs/${docId}/_branches/${encodeURIComponent(branchId)}`, {
+      method: "PUT",
+      body: metadata
+    });
+  }
+  async deleteBranch(docId, branchId) {
+    await this._fetch(`/docs/${docId}/_branches/${encodeURIComponent(branchId)}`, { method: "DELETE" });
   }
-  async mergeBranch(branchId) {
-    await this._fetch(`/docs/${encodeDocId(branchId)}/_merge`, { method: "POST" });
+  async mergeBranch(docId, branchId) {
+    await this._fetch(`/docs/${docId}/_branches/${encodeURIComponent(branchId)}/_merge`, { method: "POST" });
   }
   // --- Private Helpers ---
   _setState(state) {

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/net/rest/index.d.ts

@@ -1,6 +1,6 @@
 export { PatchesREST, PatchesRESTOptions } from './PatchesREST.js';
 export { BufferedEvent, SSEServer, SSEServerOptions } from './SSEServer.js';
-export { encodeDocId, normalizeIds } from './utils.js';
+export { normalizeIds } from './utils.js';
 import 'easy-signal';
 import '../../types.js';
 import '../../json-patch/JSONPatch.js';

package/dist/net/rest/index.js

@@ -1,8 +1,7 @@
 import "../../chunk-IZ2YBCUP.js";
 export * from "./PatchesREST.js";
 export * from "./SSEServer.js";
-import { encodeDocId, normalizeIds } from "./utils.js";
+import { normalizeIds } from "./utils.js";
 export {
-  encodeDocId,
   normalizeIds
 };

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

@@ -1,14 +1,6 @@
-/**
- * Encode a hierarchical doc ID for use in URL path segments.
- * Each segment is individually encoded so slashes are preserved as path separators.
- *
- * @example encodeDocId('users/abc/stats/2026-01') => 'users/abc/stats/2026-01'
- * @example encodeDocId('docs/hello world') => 'docs/hello%20world'
- */
-declare function encodeDocId(docId: string): string;
 /**
  * Normalize a string or string array to a string array.
  */
 declare function normalizeIds(ids: string | string[]): string[];
 
-export { encodeDocId, normalizeIds };
+export { normalizeIds };

package/dist/net/rest/utils.js

@@ -1,11 +1,7 @@
 import "../../chunk-IZ2YBCUP.js";
-function encodeDocId(docId) {
-  return docId.split("/").map(encodeURIComponent).join("/");
-}
 function normalizeIds(ids) {
   return Array.isArray(ids) ? ids : [ids];
 }
 export {
-  encodeDocId,
   normalizeIds
 };

package/dist/server/BranchManager.d.ts

@@ -1,4 +1,4 @@
-import { Branch, EditableBranchMetadata, BranchStatus, Change } from '../types.js';
+import { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata, Change } from '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
@@ -15,17 +15,20 @@ interface BranchManager {
     /**
      * Lists all branches for a document.
      * @param docId - The source document ID.
+     * @param options - Optional filtering options (e.g. `since` for incremental sync).
      * @returns Array of branch metadata.
      */
-    listBranches(docId: string): Promise<Branch[]>;
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
     /**
      * Creates a new branch from a document.
      * @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).
+     *   When `contentStartRev` is set, the server skips generating initial changes
+     *   (the client has already created them and will sync them as regular document changes).
      * @returns The new branch document ID.
      */
-    createBranch(docId: string, atPoint: number, metadata?: EditableBranchMetadata): Promise<string>;
+    createBranch(docId: string, atPoint: number, metadata?: CreateBranchMetadata): Promise<string>;
     /**
      * Updates branch metadata.
      * @param branchId - The branch document ID.
@@ -33,11 +36,12 @@ interface BranchManager {
      */
     updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
     /**
-     * Closes a branch with the specified status.
-     * @param branchId - The branch document ID.
-     * @param status - The status to set (defaults to 'closed').
+     * Deletes a branch, replacing it with a tombstone record.
+     * The tombstone preserves `id`, `docId`, `modifiedAt`, and `deleted: true`
+     * so that clients using incremental sync (`since`) can clean up their local cache.
+     * @param branchId - The branch document ID to delete.
      */
-    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+    deleteBranch(branchId: string): Promise<void>;
     /**
      * Merges a branch back into its source document.
      * Algorithm-specific: OT uses fast-forward or flattened merge, LWW uses timestamp resolution.

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 { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata, Change } from '../types.js';
 import { BranchManager } from './BranchManager.js';
 import { LWWServer } from './LWWServer.js';
 import { LWWStoreBackend, BranchingStoreBackend } from './types.js';
@@ -37,9 +37,10 @@ declare class LWWBranchManager implements BranchManager {
     /**
      * Lists all branches for a document.
      * @param docId - The source document ID.
+     * @param options - Optional filtering options (e.g. `since` for incremental sync).
      * @returns Array of branch metadata.
      */
-    listBranches(docId: string): Promise<Branch[]>;
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
     /**
      * Creates a new branch from a document's current state.
      *
@@ -49,10 +50,9 @@ declare class LWWBranchManager implements BranchManager {
      *
      * @param docId - The source document ID.
      * @param atPoint - The revision number (recorded for tracking).
-     * @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?: CreateBranchMetadata): Promise<string>;
     /**
      * Updates branch metadata.
      * @param branchId - The branch document ID.
@@ -60,16 +60,17 @@ declare class LWWBranchManager implements BranchManager {
      */
     updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
     /**
-     * Closes a branch with the specified status.
-     * @param branchId - The branch document ID.
-     * @param status - The status to set (defaults to 'closed').
+     * Deletes a branch, replacing the record with a tombstone.
      */
-    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
+    deleteBranch(branchId: string): Promise<void>;
     /**
      * Merges a branch back into its source document.
      *
+     * Supports multiple merges — the branch stays open and `lastMergedRev` tracks
+     * which branch revision was last merged. Subsequent merges only pick up new changes.
+     *
      * LWW merge algorithm:
-     * 1. Get all ops changes made on the branch since it was created
+     * 1. Get ops changes made on the branch since last merge (or since creation)
      * 2. Apply those changes to the source document
      * 3. Timestamps automatically resolve any conflicts (later wins)
      *

package/dist/server/LWWBranchManager.js

@@ -2,7 +2,7 @@ import "../chunk-IZ2YBCUP.js";
 import { JSONPatch } from "../json-patch/JSONPatch.js";
 import {
   assertBranchMetadata,
-  assertBranchOpenForMerge,
+  assertBranchExists,
   assertNotABranch,
   branchManagerApi,
   createBranchRecord,
@@ -19,10 +19,11 @@ class LWWBranchManager {
   /**
    * Lists all branches for a document.
    * @param docId - The source document ID.
+   * @param options - Optional filtering options (e.g. `since` for incremental sync).
    * @returns Array of branch metadata.
    */
-  async listBranches(docId) {
-    return await this.store.listBranches(docId);
+  async listBranches(docId, options) {
+    return await this.store.listBranches(docId, options);
   }
   /**
    * Creates a new branch from a document's current state.
@@ -33,26 +34,39 @@ class LWWBranchManager {
    *
    * @param docId - The source document ID.
    * @param atPoint - The revision number (recorded for tracking).
-   * @param metadata - Optional branch metadata.
    * @returns The new branch document ID.
    */
   async createBranch(docId, atPoint, metadata) {
-    await assertNotABranch(this.store, 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 branchDocId = metadata?.id ?? await generateBranchId(this.store, docId);
+    if (metadata?.id) {
+      const existing = await this.store.loadBranch(branchDocId);
+      if (existing) {
+        if (existing.docId !== docId) {
+          throw new Error(`Branch ${branchDocId} already exists for a different document`);
+        }
+        return branchDocId;
+      }
     }
-    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, state, rev);
-    if (ops.length > 0) {
-      await this.store.saveOps(branchDocId, ops);
+    await assertNotABranch(this.store, docId);
+    if (!metadata?.contentStartRev) {
+      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;
+      await this.store.saveSnapshot(branchDocId, state, rev);
+      if (ops.length > 0) {
+        await this.store.saveOps(branchDocId, ops);
+      }
+      const branch2 = createBranchRecord(branchDocId, docId, atPoint, rev + 1, metadata);
+      await this.store.createBranch(branch2);
+      return branchDocId;
     }
-    const branch = createBranchRecord(branchDocId, docId, atPoint, metadata);
+    const branch = createBranchRecord(branchDocId, docId, atPoint, metadata.contentStartRev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
   }
@@ -63,21 +77,22 @@ class LWWBranchManager {
    */
   async updateBranch(branchId, metadata) {
     assertBranchMetadata(metadata);
-    await this.store.updateBranch(branchId, metadata);
+    await this.store.updateBranch(branchId, { ...metadata, modifiedAt: Date.now() });
   }
   /**
-   * Closes a branch with the specified status.
-   * @param branchId - The branch document ID.
-   * @param status - The status to set (defaults to 'closed').
+   * Deletes a branch, replacing the record with a tombstone.
    */
-  async closeBranch(branchId, status) {
-    await this.store.updateBranch(branchId, { status: status ?? "closed" });
+  async deleteBranch(branchId) {
+    await this.store.deleteBranch(branchId);
   }
   /**
    * Merges a branch back into its source document.
    *
+   * Supports multiple merges — the branch stays open and `lastMergedRev` tracks
+   * which branch revision was last merged. Subsequent merges only pick up new changes.
+   *
    * LWW merge algorithm:
-   * 1. Get all ops changes made on the branch since it was created
+   * 1. Get ops changes made on the branch since last merge (or since creation)
    * 2. Apply those changes to the source document
    * 3. Timestamps automatically resolve any conflicts (later wins)
    *
@@ -86,20 +101,22 @@ class LWWBranchManager {
    */
   async mergeBranch(branchId) {
     const branch = await this.store.loadBranch(branchId);
-    assertBranchOpenForMerge(branch, branchId);
+    assertBranchExists(branch, branchId);
     const sourceDocId = branch.docId;
-    const branchChanges = await this.lwwServer.getChangesSince(branchId, branch.branchedAtRev);
+    const sinceRev = branch.lastMergedRev ?? (branch.contentStartRev ?? 1) - 1;
+    const branchChanges = await this.lwwServer.getChangesSince(branchId, sinceRev);
     if (branchChanges.length === 0) {
-      console.log(`Branch ${branchId} has no changes to merge.`);
-      await this.closeBranch(branchId, "merged");
       return [];
     }
+    const lastBranchRev = branchChanges[branchChanges.length - 1].rev;
     const { changes: committedChanges } = await wrapMergeCommit(
       branchId,
       sourceDocId,
       () => this.lwwServer.commitChanges(sourceDocId, branchChanges)
     );
-    await this.closeBranch(branchId, "merged");
+    const currentBranch = await this.store.loadBranch(branchId);
+    const effectiveLastMergedRev = Math.max(lastBranchRev, currentBranch?.lastMergedRev ?? 0);
+    await this.store.updateBranch(branchId, { lastMergedRev: effectiveLastMergedRev, modifiedAt: Date.now() });
     return committedChanges;
   }
 }

package/dist/server/LWWMemoryStoreBackend.d.ts

@@ -49,10 +49,13 @@ declare class LWWMemoryStoreBackend implements LWWStoreBackend, VersioningStoreB
     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[]>;
+    listBranches(docId: string, options?: {
+        since?: number;
+    }): Promise<Branch[]>;
     loadBranch(branchId: string): Promise<Branch | null>;
     createBranch(branch: Branch): Promise<void>;
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name' | 'metadata'>>): Promise<void>;
+    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'name' | 'metadata'>>): Promise<void>;
+    deleteBranch(branchId: string): Promise<void>;
     /**
      * Clears all data from the store. Useful for test cleanup.
      */

package/dist/server/LWWMemoryStoreBackend.js

@@ -129,11 +129,15 @@ class LWWMemoryStoreBackend {
     }
   }
   // === Branching ===
-  async listBranches(docId) {
+  async listBranches(docId, options) {
     const result = [];
+    const since = options?.since ?? 0;
     for (const branch of this.branches.values()) {
-      if (branch.docId === docId) {
-        result.push(branch);
+      if (branch.docId !== docId) continue;
+      if (since) {
+        if (branch.modifiedAt > since) result.push(branch);
+      } else {
+        if (!branch.deleted) result.push(branch);
       }
     }
     return result;
@@ -150,6 +154,20 @@ class LWWMemoryStoreBackend {
       Object.assign(branch, updates);
     }
   }
+  async deleteBranch(branchId) {
+    const branch = this.branches.get(branchId);
+    if (branch) {
+      this.branches.set(branchId, {
+        id: branch.id,
+        docId: branch.docId,
+        branchedAtRev: branch.branchedAtRev,
+        createdAt: branch.createdAt,
+        modifiedAt: Date.now(),
+        contentStartRev: branch.contentStartRev,
+        deleted: true
+      });
+    }
+  }
   // === Testing utilities ===
   /**
    * Clears all data from the store. Useful for test cleanup.

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 { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata, Change } from '../types.js';
 import { BranchManager } from './BranchManager.js';
 import { PatchesServer } from './PatchesServer.js';
 import { OTStoreBackend, BranchingStoreBackend } from './types.js';
@@ -22,7 +22,7 @@ type OTBranchStore = OTStoreBackend & BranchingStoreBackend;
  * Manages branches for documents using Operational Transformation semantics:
  * - Creates branches at specific revision points
  * - Uses fast-forward merge when possible (no concurrent changes on source)
- * - Falls back to flattened merge for divergent histories
+ * - Transforms individual branch changes against concurrent source changes for divergent histories
  *
  * A branch is a document that originates from another document at a specific revision.
  * Its first version represents the source document's state at that revision.
@@ -37,18 +37,17 @@ declare class OTBranchManager implements BranchManager {
     /**
      * Lists all open branches for a document.
      * @param docId - The ID of the document.
+     * @param options - Optional filtering options (e.g. `since` for incremental sync).
      * @returns The branches.
      */
-    listBranches(docId: string): Promise<Branch[]>;
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
     /**
      * 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.
      * @returns The ID of the new branch document.
      */
-    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata): Promise<string>;
+    createBranch(docId: string, rev: number, metadata?: CreateBranchMetadata): Promise<string>;
     /**
      * Updates a branch's metadata.
      * @param branchId - The ID of the branch to update.
@@ -56,13 +55,18 @@ declare class OTBranchManager implements BranchManager {
      */
     updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
     /**
-     * Closes a branch, marking it as merged or deleted.
-     * @param branchId - The ID of the branch to close.
-     * @param status - The status to set for the branch.
+     * Deletes a branch, replacing the record with a tombstone.
      */
-    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+    deleteBranch(branchId: string): Promise<void>;
     /**
      * Merges changes from a branch back into its source document.
+     *
+     * Supports multiple merges — the branch stays open and `lastMergedRev` tracks
+     * which branch revision was last merged. Subsequent merges only pick up new changes.
+     *
+     * All merge changes use `batchId: branchId` so that `commitChanges` never transforms
+     * branch changes against each other (they share the same causal context).
+     *
      * @param branchId - The ID of the branch document to merge.
      * @returns The server commit change(s) applied to the source document.
      * @throws Error if branch not found, already closed/merged, or merge fails.