@dabble/patches 0.8.8 → 0.8.10

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

@@ -231,7 +231,7 @@ function breakLargeValueOp(origChange, op, maxBytes, startRev, sizeCalculator) {
   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;
+  const { id: _id, ops: _o, rev: _r, baseRev: _br, created: _c, ...metadata } = origChange;
   return createChange(origChange.baseRev, rev, ops, metadata);
 }
 export {

package/dist/client/BranchClientStore.d.ts

@@ -0,0 +1,71 @@
+import { ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata } from '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
+/**
+ * Client-side branch storage interface that doubles as a BranchAPI-compatible layer.
+ *
+ * Implements the same method signatures as BranchAPI (listBranches, createBranch,
+ * deleteBranch, updateBranch) so PatchesBranchClient can call a single
+ * interface regardless of online/offline mode.
+ *
+ * All mutating methods set `pendingOp` on the branch record so PatchesSync knows
+ * which operations to push to the server.
+ *
+ * Also exposes sync-facing methods used by PatchesSync to reconcile local state
+ * with the server.
+ */
+interface BranchClientStore {
+    /**
+     * Returns locally cached branch metas for a document.
+     * Excludes deleted branches.
+     */
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
+    /**
+     * Creates a branch record locally with `pendingOp: 'create'`.
+     * Returns the branch document ID.
+     */
+    createBranch(docId: string, rev: number, metadata?: CreateBranchMetadata): Promise<string>;
+    /**
+     * Deletes a branch locally.
+     * If the branch has `pendingOp: 'create'` (never synced), physically removes it.
+     * Otherwise saves a tombstone with `pendingOp: 'delete'` and `deleted: true`.
+     */
+    deleteBranch(branchId: string): Promise<void>;
+    /**
+     * Updates branch metadata locally (e.g. name, lastMergedRev).
+     * If the branch has `pendingOp: 'create'` (never synced), keeps it as 'create'.
+     * Otherwise sets `pendingOp: 'update'`.
+     */
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
+    /**
+     * Loads a single branch by its branch document ID.
+     * Returns undefined if not found. Used to check if a document is a branch.
+     */
+    loadBranch(branchId: string): Promise<Branch | undefined>;
+    /**
+     * Saves branch metas from the server into the local store.
+     * Merges with existing data: updates existing branches and adds new ones.
+     * Branches not in the provided array are left untouched (incremental update friendly).
+     */
+    saveBranches(docId: string, branches: Branch[]): Promise<void>;
+    /**
+     * Physically removes branches from the local store.
+     * Called by PatchesSync after the server confirms deletion.
+     */
+    removeBranches(branchIds: string[]): Promise<void>;
+    /**
+     * Returns all branches with a `pendingOp` set, across all documents.
+     * Used by PatchesSync to efficiently find branches that need server sync.
+     */
+    listPendingBranches(): Promise<Branch[]>;
+    /**
+     * Returns the most recent `modifiedAt` timestamp across all committed branches
+     * for a given document. Used as the `since` parameter for incremental list fetches.
+     * Returns undefined if no committed branches exist locally.
+     */
+    getLastModifiedAt(docId: string): Promise<number | undefined>;
+}
+
+export type { BranchClientStore };

package/dist/client/ClientAlgorithm.d.ts

@@ -56,6 +56,18 @@ interface ClientAlgorithm {
      * @returns The changes created (for broadcast to other tabs)
      */
     handleDocChange<T extends object>(docId: string, ops: JSONPatchOp[], doc: PatchesDoc<T> | undefined, metadata: Record<string, any>): Promise<Change[]>;
+    /**
+     * Lists all changes (committed + pending) for a document.
+     * Used by PatchesBranchClient for client-side offline merge to read branch changes.
+     * Optional — only OT algorithms with IndexedDB stores support this.
+     *
+     * @param docId Document identifier
+     * @param options.startAfter Only return changes with rev > startAfter
+     * @returns Changes sorted by rev
+     */
+    listChanges?(docId: string, options?: {
+        startAfter?: number;
+    }): Promise<Change[]>;
     /**
      * Read-only check for whether a document has any pending local data.
      * - OT: Checks pendingChanges

package/dist/client/IndexedDBStore.d.ts

@@ -1,6 +1,7 @@
 import * as easy_signal from 'easy-signal';
-import { PatchesSnapshot, PatchesState } from '../types.js';
+import { PatchesSnapshot, PatchesState, ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata } from '../types.js';
 import { Deferred } from '../utils/deferred.js';
+import { BranchClientStore } from './BranchClientStore.js';
 import { PatchesStore, TrackedDoc } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -20,7 +21,7 @@ import '../json-patch/types.js';
  * - Revision tracking
  * - Extensibility via onUpgrade signal for algorithm-specific stores
  */
-declare class IndexedDBStore implements PatchesStore {
+declare class IndexedDBStore implements PatchesStore, BranchClientStore {
     private static readonly DB_VERSION;
     protected db: IDBDatabase | null;
     protected dbName?: string;
@@ -97,6 +98,16 @@ declare class IndexedDBStore implements PatchesStore {
      * @returns The last committed revision, or 0 if not found.
      */
     getCommittedRev(docId: string): Promise<number>;
+    listBranches(docId: string, _options?: ListBranchesOptions): Promise<Branch[]>;
+    createBranch(docId: string, rev: number, metadata?: CreateBranchMetadata): Promise<string>;
+    deleteBranch(branchId: string): Promise<void>;
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
+    loadBranch(branchId: string): Promise<Branch | undefined>;
+    saveBranches(docId: string, branches: Branch[]): Promise<void>;
+    removeBranches(branchIds: string[]): Promise<void>;
+    listPendingBranches(): Promise<Branch[]>;
+    getLastModifiedAt(docId: string): Promise<number | undefined>;
+    private _saveBranch;
 }
 declare class IDBTransactionWrapper {
     protected tx: IDBTransaction;

package/dist/client/IndexedDBStore.js

@@ -1,8 +1,9 @@
 import "../chunk-IZ2YBCUP.js";
+import { createId } from "crypto-id";
 import { deferred } from "../utils/deferred.js";
 import { signal } from "easy-signal";
 class IndexedDBStore {
-  static DB_VERSION = 1;
+  static DB_VERSION = 2;
   db = null;
   dbName;
   dbPromise;
@@ -32,6 +33,16 @@ class IndexedDBStore {
     if (!db.objectStoreNames.contains("snapshots")) {
       db.createObjectStore("snapshots", { keyPath: "docId" });
     }
+    if (!db.objectStoreNames.contains("branches")) {
+      const branchStore = db.createObjectStore("branches", { keyPath: "id" });
+      branchStore.createIndex("_docId", "_docId", { unique: false });
+      branchStore.createIndex("_pending", "_pending", { unique: false });
+    } else {
+      const branchStore = _transaction.objectStore("branches");
+      if (!branchStore.indexNames.contains("_pending")) {
+        branchStore.createIndex("_pending", "_pending", { unique: false });
+      }
+    }
   }
   async initDB() {
     if (!this.dbName) return;
@@ -191,6 +202,119 @@ class IndexedDBStore {
     await tx.complete();
     return docMeta?.committedRev ?? 0;
   }
+  // ─── Branch Methods (BranchClientStore) ─────────────────────────────────
+  // --- BranchAPI-compatible methods ---
+  async listBranches(docId, _options) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readonly");
+    const results = await branchStore.getAllByIndex("_docId", docId);
+    await tx.complete();
+    return results.filter((b) => !b.deleted).map(stripInternal);
+  }
+  async createBranch(docId, rev, metadata) {
+    const branchDocId = metadata?.id ?? createId(22);
+    const now = Date.now();
+    const branch = {
+      ...metadata,
+      id: branchDocId,
+      docId,
+      branchedAtRev: rev,
+      contentStartRev: metadata?.contentStartRev ?? 0,
+      createdAt: now,
+      modifiedAt: now,
+      pendingOp: "create"
+    };
+    await this._saveBranch(docId, branch);
+    return branchDocId;
+  }
+  async deleteBranch(branchId) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readwrite");
+    const existing = await branchStore.get(branchId);
+    if (!existing) throw new Error(`Branch ${branchId} not found`);
+    if (existing.pendingOp === "create") {
+      await branchStore.delete(branchId);
+    } else {
+      const tombstone = {
+        ...existing,
+        modifiedAt: Date.now(),
+        pendingOp: "delete",
+        deleted: true,
+        _pending: 1
+      };
+      await branchStore.put(tombstone);
+    }
+    await tx.complete();
+  }
+  async updateBranch(branchId, metadata) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readwrite");
+    const existing = await branchStore.get(branchId);
+    if (!existing) throw new Error(`Branch ${branchId} not found`);
+    Object.assign(existing, metadata);
+    existing.modifiedAt = Date.now();
+    if (existing.pendingOp !== "create") existing.pendingOp = "update";
+    existing._pending = 1;
+    await branchStore.put(existing);
+    await tx.complete();
+  }
+  // --- Internal methods ---
+  async loadBranch(branchId) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readonly");
+    const result = await branchStore.get(branchId);
+    await tx.complete();
+    return result ? stripInternal(result) : void 0;
+  }
+  // --- Sync-facing methods ---
+  async saveBranches(docId, branches) {
+    if (branches.length === 0) return;
+    const [tx, branchStore] = await this.transaction(["branches"], "readwrite");
+    await Promise.all(
+      branches.map(async (branch) => {
+        const existing = await branchStore.get(branch.id);
+        if (existing?.pendingOp && !branch.pendingOp) return;
+        const stored = { ...branch, _docId: docId };
+        if (existing?.lastMergedRev != null && (stored.lastMergedRev == null || existing.lastMergedRev > stored.lastMergedRev)) {
+          stored.lastMergedRev = existing.lastMergedRev;
+        }
+        if (branch.pendingOp) stored._pending = 1;
+        return branchStore.put(stored);
+      })
+    );
+    await tx.complete();
+  }
+  async removeBranches(branchIds) {
+    if (branchIds.length === 0) return;
+    const [tx, branchStore] = await this.transaction(["branches"], "readwrite");
+    await Promise.all(branchIds.map((id) => branchStore.delete(id)));
+    await tx.complete();
+  }
+  async listPendingBranches() {
+    const [tx, branchStore] = await this.transaction(["branches"], "readonly");
+    const results = await branchStore.getAllByIndex("_pending", 1);
+    await tx.complete();
+    return results.map(stripInternal);
+  }
+  async getLastModifiedAt(docId) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readonly");
+    const branches = await branchStore.getAllByIndex("_docId", docId);
+    await tx.complete();
+    if (branches.length === 0) return void 0;
+    let max = 0;
+    for (const b of branches) {
+      if (!b.pendingOp && !b.deleted && b.modifiedAt > max) max = b.modifiedAt;
+    }
+    return max || void 0;
+  }
+  // --- Private helpers ---
+  async _saveBranch(docId, branch) {
+    const [tx, branchStore] = await this.transaction(["branches"], "readwrite");
+    const stored = { ...branch, _docId: docId };
+    if (branch.pendingOp) stored._pending = 1;
+    await branchStore.put(stored);
+    await tx.complete();
+  }
+}
+function stripInternal(stored) {
+  const { _docId, _pending, ...branch } = stored;
+  return branch;
 }
 class IDBTransactionWrapper {
   tx;

package/dist/client/LWWInMemoryStore.js

@@ -54,12 +54,11 @@ class LWWInMemoryStore {
    * 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: existing?.pendingOps ?? /* @__PURE__ */ new Map(),
-      sendingChange: existing?.sendingChange ?? null,
+      pendingOps: /* @__PURE__ */ new Map(),
+      sendingChange: null,
       committedRev: docState.rev
     });
   }
@@ -165,6 +164,9 @@ class LWWInMemoryStore {
     for (const op of buf.sendingChange.ops) {
       buf.committedFields.set(op.path, op.value);
     }
+    if (buf.sendingChange.rev > buf.committedRev) {
+      buf.committedRev = buf.sendingChange.rev;
+    }
     buf.sendingChange = null;
   }
   /**

package/dist/client/LWWIndexedDBStore.d.ts

@@ -7,6 +7,7 @@ import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import 'easy-signal';
 import '../utils/deferred.js';
+import './BranchClientStore.js';
 
 /**
  * IndexedDB store implementation for Last-Writer-Wins (LWW) sync algorithm.

package/dist/client/LWWIndexedDBStore.js

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

package/dist/client/OTAlgorithm.d.ts

@@ -22,6 +22,9 @@ declare class OTAlgorithm implements ClientAlgorithm {
     constructor(store: OTClientStore, options?: PatchesDocOptions);
     createDoc<T extends object>(docId: string, snapshot?: PatchesSnapshot<T>): PatchesDoc<T>;
     loadDoc(docId: string): Promise<PatchesSnapshot | undefined>;
+    listChanges(docId: string, options?: {
+        startAfter?: number;
+    }): Promise<Change[]>;
     handleDocChange<T extends object>(docId: string, ops: JSONPatchOp[], doc: PatchesDoc<T> | undefined, metadata: Record<string, any>): Promise<Change[]>;
     hasPending(docId: string): Promise<boolean>;
     getPendingToSend(docId: string): Promise<Change[] | null>;

package/dist/client/OTAlgorithm.js

@@ -17,6 +17,10 @@ class OTAlgorithm {
   async loadDoc(docId) {
     return this.store.getDoc(docId);
   }
+  async listChanges(docId, options) {
+    if (!this.store.listChanges) throw new Error("Store does not support listChanges");
+    return this.store.listChanges(docId, options);
+  }
   async handleDocChange(docId, ops, doc, metadata) {
     if (ops.length === 0) return [];
     let committedRev;

package/dist/client/OTClientStore.d.ts

@@ -32,6 +32,17 @@ interface OTClientStore extends PatchesStore {
      * @param changes Array of new changes to append
      */
     savePendingChanges(docId: string, changes: Change[]): Promise<void>;
+    /**
+     * Lists all changes (committed + pending) for a document, sorted by rev.
+     * Used by PatchesBranchClient for client-side offline merge to read branch changes.
+     *
+     * @param docId Document identifier
+     * @param options.startAfter Only return changes with rev > startAfter
+     * @returns Changes sorted by rev
+     */
+    listChanges?(docId: string, options?: {
+        startAfter?: number;
+    }): Promise<Change[]>;
     /**
      * Atomically applies server-confirmed changes and updates pending changes.
      *

package/dist/client/OTIndexedDBStore.d.ts

@@ -7,6 +7,7 @@ import '@dabble/delta';
 import '../json-patch/types.js';
 import 'easy-signal';
 import '../utils/deferred.js';
+import './BranchClientStore.js';
 
 /**
  * IndexedDB store implementation for Operational Transformation (OT) sync algorithm.
@@ -94,6 +95,14 @@ declare class OTIndexedDBStore implements OTClientStore {
      * @returns The pending changes.
      */
     getPendingChanges(docId: string): Promise<Change[]>;
+    /**
+     * Lists all changes (committed + pending) for a document, sorted by rev.
+     * @param docId - The document ID.
+     * @param options.startAfter - Only return changes with rev > startAfter.
+     */
+    listChanges(docId: string, options?: {
+        startAfter?: number;
+    }): Promise<Change[]>;
     /**
      * Atomically applies server-confirmed changes and updates pending changes.
      * This is the core sync operation that must be atomic.

package/dist/client/OTIndexedDBStore.js

@@ -5,12 +5,12 @@ import {
   __publicField,
   __runInitializers
 } from "../chunk-IZ2YBCUP.js";
-var _applyServerChanges_dec, _getPendingChanges_dec, _savePendingChanges_dec, _saveDoc_dec, _deleteDoc_dec, _getDoc_dec, _init;
+var _applyServerChanges_dec, _listChanges_dec, _getPendingChanges_dec, _savePendingChanges_dec, _saveDoc_dec, _deleteDoc_dec, _getDoc_dec, _init;
 import { applyChanges } from "../algorithms/ot/shared/applyChanges.js";
 import { blockable } from "../utils/concurrency.js";
 import { IndexedDBStore } from "./IndexedDBStore.js";
 const SNAPSHOT_INTERVAL = 200;
-_getDoc_dec = [blockable], _deleteDoc_dec = [blockable], _saveDoc_dec = [blockable], _savePendingChanges_dec = [blockable], _getPendingChanges_dec = [blockable], _applyServerChanges_dec = [blockable];
+_getDoc_dec = [blockable], _deleteDoc_dec = [blockable], _saveDoc_dec = [blockable], _savePendingChanges_dec = [blockable], _getPendingChanges_dec = [blockable], _listChanges_dec = [blockable], _applyServerChanges_dec = [blockable];
 class OTIndexedDBStore {
   constructor(db) {
     __runInitializers(_init, 5, this);
@@ -111,7 +111,7 @@ class OTIndexedDBStore {
     await tx.complete();
   }
   async saveDoc(docId, docState) {
-    const [tx, snapshots, committedChanges, pendingChanges, docsStore] = await this.db.transaction(
+    const [tx, snapshots, committedChanges, , docsStore] = await this.db.transaction(
       ["snapshots", "committedChanges", "pendingChanges", "docs"],
       "readwrite"
     );
@@ -143,6 +143,17 @@ class OTIndexedDBStore {
     await tx.complete();
     return result;
   }
+  async listChanges(docId, options) {
+    const startRev = (options?.startAfter ?? -1) + 1;
+    const [tx, committedChanges, pendingChanges] = await this.db.transaction(
+      ["committedChanges", "pendingChanges"],
+      "readonly"
+    );
+    const committed = await committedChanges.getAll([docId, startRev], [docId, Infinity]);
+    const pending = await pendingChanges.getAll([docId, startRev], [docId, Infinity]);
+    await tx.complete();
+    return [...committed, ...pending].sort((a, b) => a.rev - b.rev);
+  }
   async applyServerChanges(docId, serverChanges, rebasedPendingChanges) {
     const [tx, committedChangesStore, pendingChangesStore, snapshots, docsStore] = await this.db.transaction(
       ["committedChanges", "pendingChanges", "snapshots", "docs"],
@@ -203,6 +214,7 @@ __decorateElement(_init, 1, "deleteDoc", _deleteDoc_dec, OTIndexedDBStore);
 __decorateElement(_init, 1, "saveDoc", _saveDoc_dec, OTIndexedDBStore);
 __decorateElement(_init, 1, "savePendingChanges", _savePendingChanges_dec, OTIndexedDBStore);
 __decorateElement(_init, 1, "getPendingChanges", _getPendingChanges_dec, OTIndexedDBStore);
+__decorateElement(_init, 1, "listChanges", _listChanges_dec, OTIndexedDBStore);
 __decorateElement(_init, 1, "applyServerChanges", _applyServerChanges_dec, OTIndexedDBStore);
 __decoratorMetadata(_init, OTIndexedDBStore);
 export {

package/dist/client/Patches.d.ts

@@ -123,6 +123,12 @@ declare class Patches {
      * Should be called when shutting down the client.
      */
     close(): Promise<void>;
+    /**
+     * Submits ops for a document through the serialized change queue.
+     * Used by PatchesBranchClient to merge branch changes without racing
+     * against concurrent user edits on the same document.
+     */
+    submitDocChange(docId: string, ops: JSONPatchOp[], metadata?: Record<string, any>): Promise<void>;
     /**
      * Internal handler for doc changes. Called when doc.onChange emits ops.
      * Serializes calls per docId to prevent concurrent handleDocChange from

package/dist/client/Patches.js

@@ -197,6 +197,17 @@ class Patches {
     this.onServerCommit.clear();
     this.onError.clear();
   }
+  /**
+   * Submits ops for a document through the serialized change queue.
+   * Used by PatchesBranchClient to merge branch changes without racing
+   * against concurrent user edits on the same document.
+   */
+  submitDocChange(docId, ops, metadata = {}) {
+    const managed = this.docs.get(docId);
+    const algorithm = this.getDocAlgorithm(docId) ?? this.algorithms[this.defaultAlgorithm];
+    if (!algorithm) throw new Error(`No algorithm found for document ${docId}`);
+    return this._handleDocChange(docId, ops, managed?.doc, algorithm, metadata);
+  }
   /**
    * Internal handler for doc changes. Called when doc.onChange emits ops.
    * Serializes calls per docId to prevent concurrent handleDocChange from

package/dist/client/PatchesBranchClient.d.ts

@@ -1,31 +1,92 @@
 import { Store } from 'easy-signal';
+import { SizeCalculator } from '../algorithms/ot/shared/changeBatching.js';
 import { BranchAPI } from '../net/protocol/types.js';
-import { Branch, EditableBranchMetadata } from '../types.js';
+import { Branch, ListBranchesOptions, CreateBranchMetadata } from '../types.js';
+import { BranchClientStore } from './BranchClientStore.js';
+import { Patches } from './Patches.js';
+import { AlgorithmName } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
+import './ClientAlgorithm.js';
+import '../BaseDoc-BT18xPxU.js';
 
+interface PatchesBranchClientOptions {
+    /** Maximum size in bytes for a single change in storage. Used to break large initial changes. */
+    maxStorageBytes?: number;
+    /** Custom size calculator for change size measurement. */
+    sizeCalculator?: SizeCalculator;
+    /** Algorithm to use for the branch document (defaults to the Patches instance default). */
+    algorithm?: AlgorithmName;
+}
 /**
- * Client-side branch management interface for a document.
- * Allows listing, creating, closing, and merging branches.
+ * Client-side branch management for a document.
+ *
+ * Accepts either a `BranchAPI` (online, server does the work) or a `BranchClientStore`
+ * (offline-first, local store handles caching/pending/tombstones). The API shape
+ * determines merge behavior:
+ *
+ * - `BranchAPI` has `mergeBranch` — server performs the merge
+ * - `BranchClientStore` has `updateBranch` — client merges locally, updates `lastMergedRev`
  */
 declare class PatchesBranchClient {
     private readonly api;
+    private readonly patches;
+    private readonly options?;
     /** 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 */
+    constructor(id: string, api: BranchAPI | BranchClientStore, patches: Patches, options?: PatchesBranchClientOptions | undefined);
+    /** Whether this client uses a local store (offline-first mode). */
+    private get isOffline();
+    /**
+     * Loads cached branches from the local store.
+     * Returns empty array when using online-only BranchAPI.
+     */
+    loadCached(): Promise<Branch[]>;
+    /**
+     * List all branches for this document.
+     * With a local store, returns cached data (server sync is handled by PatchesSync).
+     * With a BranchAPI, fetches directly from the server.
+     */
+    listBranches(options?: ListBranchesOptions): Promise<Branch[]>;
+    /**
+     * Create a new branch from a specific revision.
+     *
+     * When `initialState` is provided, the branch is created for offline-first sync:
+     * - Requires `metadata.id` to be set (used as the branch document ID)
+     * - Creates the initial root-replace change locally (broken into multiple if needed)
+     * - Saves the branch meta via the API (store marks it pending for later server sync)
+     * - Tracks the branch document and saves initial changes as pending through the algorithm
+     * - PatchesSync will create the branch on the server and flush the document changes
+     *
+     * When `initialState` is omitted, the branch is created directly via the API.
+     */
+    createBranch(rev: number, metadata?: CreateBranchMetadata, initialState?: any): Promise<string>;
+    /**
+     * Delete a branch.
+     * The API implementation handles tombstones (offline store) or direct deletion (online).
+     */
+    deleteBranch(branchId: string): Promise<void>;
+    /**
+     * Delete a branch and its document.
+     * Convenience method that deletes both the branch record and the branch document.
+     */
+    deleteBranchWithDoc(branchId: string): Promise<void>;
+    /**
+     * Merge a branch's changes back into this document.
+     *
+     * Online (BranchAPI with `mergeBranch`): server performs the merge.
+     * Offline (BranchClientStore with `updateBranch`): client reads branch changes,
+     * re-stamps them with `batchId: branchId`, submits via algorithm.handleDocChange
+     * on the source doc, then updates `lastMergedRev` locally.
+     */
     mergeBranch(branchId: string): Promise<void>;
     /** Clear state */
     clear(): void;
+    private _createBranchOffline;
+    private _mergeBranchLocally;
 }
 
-export { PatchesBranchClient };
+export { PatchesBranchClient, type PatchesBranchClientOptions };