@dabble/patches 0.8.7 → 0.8.9

package/dist/client/PatchesBranchClient.d.ts

@@ -0,0 +1,92 @@
+import { Store } from 'easy-signal';
+import { SizeCalculator } from '../algorithms/ot/shared/changeBatching.js';
+import { BranchAPI } from '../net/protocol/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 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 | 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, type PatchesBranchClientOptions };

package/dist/client/PatchesBranchClient.js

@@ -0,0 +1,170 @@
+import "../chunk-IZ2YBCUP.js";
+import { store } from "easy-signal";
+import { breakChanges } from "../algorithms/ot/shared/changeBatching.js";
+import { createChange } from "../data/change.js";
+class PatchesBranchClient {
+  constructor(id, api, patches, options) {
+    this.api = api;
+    this.patches = patches;
+    this.options = options;
+    this.id = id;
+    this.branches = store([]);
+  }
+  /** Document ID */
+  id;
+  /** Store for the branches list */
+  branches;
+  /** Whether this client uses a local store (offline-first mode). */
+  get isOffline() {
+    return "loadBranch" in this.api;
+  }
+  /**
+   * Loads cached branches from the local store.
+   * Returns empty array when using online-only BranchAPI.
+   */
+  async loadCached() {
+    if (!this.isOffline) return [];
+    const cached = await this.api.listBranches(this.id);
+    this.branches.state = cached;
+    return cached;
+  }
+  /**
+   * 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.
+   */
+  async listBranches(options) {
+    const branches = await this.api.listBranches(this.id, options);
+    this.branches.state = branches;
+    return branches;
+  }
+  /**
+   * 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.
+   */
+  async createBranch(rev, metadata, initialState) {
+    if (initialState !== void 0) {
+      if (!metadata) {
+        throw new Error("metadata is required when creating a branch with initialState");
+      }
+      return this._createBranchOffline(rev, metadata, initialState);
+    }
+    const branchId = await this.api.createBranch(this.id, rev, metadata);
+    await this.listBranches();
+    return branchId;
+  }
+  /**
+   * Delete a branch.
+   * The API implementation handles tombstones (offline store) or direct deletion (online).
+   */
+  async deleteBranch(branchId) {
+    await this.api.deleteBranch(branchId);
+    this.branches.state = this.branches.state.filter((b) => b.id !== branchId);
+  }
+  /**
+   * Delete a branch and its document.
+   * Convenience method that deletes both the branch record and the branch document.
+   */
+  async deleteBranchWithDoc(branchId) {
+    await this.deleteBranch(branchId);
+    await this.patches.deleteDoc(branchId);
+  }
+  /**
+   * 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.
+   */
+  async mergeBranch(branchId) {
+    if (!this.isOffline) {
+      await this.api.mergeBranch(branchId);
+      await this.listBranches();
+      return;
+    }
+    await this._mergeBranchLocally(branchId);
+  }
+  /** Clear state */
+  clear() {
+    this.branches.state = [];
+  }
+  // --- Private ---
+  async _createBranchOffline(rev, metadata, initialState) {
+    const branchDocId = metadata.id;
+    if (!branchDocId) {
+      throw new Error("metadata.id is required when creating a branch with initialState");
+    }
+    if ("loadBranch" in this.api) {
+      const maybeBranch = await this.api.loadBranch(this.id);
+      if (maybeBranch) {
+        throw new Error("Cannot create a branch from another branch.");
+      }
+    }
+    const now = Date.now();
+    const rootReplace = createChange(0, 1, [{ op: "replace", path: "", value: initialState }], {
+      createdAt: now,
+      committedAt: 0
+    });
+    let initChanges = [rootReplace];
+    if (this.options?.maxStorageBytes) {
+      initChanges = breakChanges(initChanges, this.options.maxStorageBytes, this.options.sizeCalculator);
+    }
+    const contentStartRev = initChanges[initChanges.length - 1].rev + 1;
+    const algorithmName = this.options?.algorithm ?? this.patches.defaultAlgorithm;
+    const algorithm = this.patches.algorithms[algorithmName];
+    if (!algorithm) {
+      throw new Error(`Algorithm '${algorithmName}' not found`);
+    }
+    await this.api.createBranch(this.id, rev, { ...metadata, contentStartRev });
+    try {
+      await this.patches.trackDocs([branchDocId], algorithmName);
+      for (const change of initChanges) {
+        await algorithm.handleDocChange(branchDocId, change.ops, void 0, {});
+      }
+    } catch (err) {
+      if (this.isOffline) {
+        await this.api.removeBranches([branchDocId]);
+      }
+      await this.patches.untrackDocs([branchDocId]);
+      throw err;
+    }
+    await this.listBranches();
+    this.patches.onChange.emit(branchDocId);
+    return branchDocId;
+  }
+  async _mergeBranchLocally(branchId) {
+    const offlineApi = this.api;
+    const branch = this.branches.state.find((b) => b.id === branchId);
+    if (!branch) throw new Error(`Branch ${branchId} not found`);
+    const sourceDocId = branch.docId;
+    const algorithmName = this.options?.algorithm ?? this.patches.defaultAlgorithm;
+    const algorithm = this.patches.algorithms[algorithmName];
+    if (!algorithm?.listChanges) {
+      throw new Error("Offline merge requires an algorithm with listChanges support");
+    }
+    const startAfter = branch.lastMergedRev ?? (branch.contentStartRev ?? 2) - 1;
+    const branchChanges = await algorithm.listChanges(branchId, { startAfter });
+    if (branchChanges.length === 0) return;
+    const lastBranchRev = branchChanges[branchChanges.length - 1].rev;
+    for (const change of branchChanges) {
+      await this.patches.submitDocChange(sourceDocId, change.ops, { batchId: branchId });
+    }
+    await offlineApi.updateBranch(branchId, { lastMergedRev: lastBranchRev });
+    this.patches.onChange.emit(sourceDocId);
+    this.branches.state = this.branches.state.map(
+      (b) => b.id === branchId ? { ...b, lastMergedRev: lastBranchRev } : b
+    );
+  }
+}
+export {
+  PatchesBranchClient
+};

package/dist/client/index.d.ts

@@ -10,7 +10,9 @@ export { LWWAlgorithm } from './LWWAlgorithm.js';
 export { LWWBatcher } from './LWWBatcher.js';
 export { OTAlgorithm } from './OTAlgorithm.js';
 export { OpenDocOptions, Patches, PatchesOptions } from './Patches.js';
+export { PatchesBranchClient, PatchesBranchClientOptions } from './PatchesBranchClient.js';
 export { PatchesHistoryClient } from './PatchesHistoryClient.js';
+export { BranchClientStore } from './BranchClientStore.js';
 export { AlgorithmName, PatchesStore, TrackedDoc } from './PatchesStore.js';
 export { OTClientStore } from './OTClientStore.js';
 export { LWWClientStore } from './LWWClientStore.js';
@@ -21,4 +23,5 @@ import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../utils/deferred.js';
+import '../algorithms/ot/shared/changeBatching.js';
 import '../net/protocol/types.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/compression/index.d.ts

@@ -10,11 +10,11 @@ import { JSONPatchOp } from '../json-patch/types.js';
  *
  * @example Client: Size calculator for change splitting
  * ```typescript
- * import { compressedSizeBase64 } from '@dabble/patches/compression';
+ * import { compressedSizeUint8 } from '@dabble/patches/compression';
  *
  * new OTDoc(state, {}, {
- *   sizeCalculator: compressedSizeBase64,
- *   maxStorageBytes: 1_000_000
+ *   sizeCalculator: compressedSizeUint8,
+ *   maxStorageBytes: 1_000_000,
  * });
  * ```
  *
@@ -32,13 +32,21 @@ import { JSONPatchOp } from '../json-patch/types.js';
  */
 type SizeCalculator = (data: unknown) => number;
 /**
- * Calculate size after base64 LZ compression.
- * Use this when your server uses base64 compression format.
+ * Estimate the stored size of a change after base64 LZ compression.
+ *
+ * When passed a Change object (has an `ops` array), only the `ops` field is
+ * compressed — mirroring what `CompressedStoreBackend` does — so the estimate
+ * reflects the actual stored size rather than compressing everything together.
+ * For other data it falls back to compressing the whole value.
  */
 declare const compressedSizeBase64: SizeCalculator;
 /**
- * Calculate size after uint8array LZ compression.
- * Use this when your server uses binary compression format.
+ * Estimate the stored size of a change after uint8array LZ compression.
+ *
+ * When passed a Change object (has an `ops` array), only the `ops` field is
+ * compressed — mirroring what `CompressedStoreBackend` does — so the estimate
+ * reflects the actual stored size rather than compressing everything together.
+ * For other data it falls back to compressing the whole value.
  */
 declare const compressedSizeUint8: SizeCalculator;
 /**

package/dist/compression/index.js

@@ -1,8 +1,13 @@
 import "../chunk-IZ2YBCUP.js";
 import { compressToBase64, compressToUint8Array, decompressFromBase64, decompressFromUint8Array } from "./lz.js";
 const compressedSizeBase64 = (data) => {
-  if (data === void 0) return 0;
+  if (data === void 0 || data === null) return 0;
   try {
+    if (typeof data === "object" && "ops" in data && Array.isArray(data.ops)) {
+      const { ops, ...rest } = data;
+      const compressedOps = compressToBase64(JSON.stringify(ops));
+      return new TextEncoder().encode(JSON.stringify({ ...rest, ops: compressedOps })).length;
+    }
     const json = JSON.stringify(data);
     if (!json) return 0;
     return compressToBase64(json).length;
@@ -11,8 +16,14 @@ const compressedSizeBase64 = (data) => {
   }
 };
 const compressedSizeUint8 = (data) => {
-  if (data === void 0) return 0;
+  if (data === void 0 || data === null) return 0;
   try {
+    if (typeof data === "object" && "ops" in data && Array.isArray(data.ops)) {
+      const { ops, ...rest } = data;
+      const compressedOps = compressToUint8Array(JSON.stringify(ops));
+      const nonOpsSize = new TextEncoder().encode(JSON.stringify(rest)).length;
+      return nonOpsSize + compressedOps.length;
+    }
     const json = JSON.stringify(data);
     if (!json) return 0;
     return compressToUint8Array(json).length;

package/dist/index.d.ts

@@ -11,7 +11,9 @@ 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, PatchesBranchClientOptions } from './client/PatchesBranchClient.js';
 export { PatchesHistoryClient } from './client/PatchesHistoryClient.js';
+export { BranchClientStore } from './client/BranchClientStore.js';
 export { AlgorithmName, PatchesStore, TrackedDoc } from './client/PatchesStore.js';
 export { OTClientStore } from './client/OTClientStore.js';
 export { LWWClientStore } from './client/LWWClientStore.js';
@@ -29,8 +31,9 @@ export { createPathProxy, pathProxy } from './json-patch/pathProxy.js';
 export { transformPatch } from './json-patch/transformPatch.js';
 export { JSONPatch, PathLike, WriteOptions } from './json-patch/JSONPatch.js';
 export { ApplyJSONPatchOptions, JSONPatchOp, JSONPatchOpHandlerMap } from './json-patch/types.js';
-export { Branch, BranchStatus, Change, ChangeInput, ChangeMutator, CommitChangesOptions, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata } from './types.js';
+export { Branch, Change, ChangeInput, ChangeMutator, CommitChangesOptions, CreateBranchMetadata, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListBranchesOptions, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata } from './types.js';
 import './utils/deferred.js';
+import './algorithms/ot/shared/changeBatching.js';
 import './net/protocol/types.js';
 import './json-patch/ops/add.js';
 import './json-patch/ops/copy.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, ListBranchesOptions, Branch, CreateBranchMetadata, EditableBranchMetadata } from '../types.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
 import { PatchesAPI, ClientTransport } from './protocol/types.js';
 import '../json-patch/JSONPatch.js';
@@ -109,21 +109,26 @@ declare class PatchesClient implements PatchesAPI {
      * @param docId - The ID of the document.
      * @returns A promise resolving with an array of branch metadata objects.
      */
-    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.
      * @param rev - The revision number to base the new branch on.
-     * @param metadata - Optional metadata for the new branch.
+     * @param options - Optional branch creation options.
      * @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?: CreateBranchMetadata): Promise<string>;
     /**
-     * Closes a branch on the server.
-     * @param branchId - The ID of the branch to close.
-     * @returns A promise resolving when the branch is closed.
+     * Updates a branch's metadata on the server.
+     * @param branchId - The ID of the branch to update.
+     * @param metadata - The metadata to update.
      */
-    closeBranch(branchId: string): Promise<void>;
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
+    /**
+     * Deletes a branch on the server, replacing it with a tombstone.
+     * @param branchId - The ID of the branch to delete.
+     */
+    deleteBranch(branchId: string): Promise<void>;
     /**
      * Merges a branch on the server.
      * @param branchId - The ID of the branch to merge.

package/dist/net/PatchesClient.js

@@ -133,26 +133,33 @@ class PatchesClient {
    * @param docId - The ID of the document.
    * @returns A promise resolving with an array of branch metadata objects.
    */
-  async listBranches(docId) {
-    return this.rpc.call("listBranches", docId);
+  async listBranches(docId, options) {
+    return this.rpc.call("listBranches", docId, options);
   }
   /**
    * Creates a new branch for a document.
    * @param docId - The ID of the document.
    * @param rev - The revision number to base the new branch on.
-   * @param metadata - Optional metadata for the new branch.
+   * @param options - Optional branch creation options.
    * @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);
   }
   /**
-   * Closes a branch on the server.
-   * @param branchId - The ID of the branch to close.
-   * @returns A promise resolving when the branch is closed.
+   * Updates a branch's metadata on the server.
+   * @param branchId - The ID of the branch to update.
+   * @param metadata - The metadata to update.
    */
-  async closeBranch(branchId) {
-    return this.rpc.call("closeBranch", branchId);
+  async updateBranch(branchId, metadata) {
+    return this.rpc.call("updateBranch", branchId, metadata);
+  }
+  /**
+   * Deletes a branch on the server, replacing it with a tombstone.
+   * @param branchId - The ID of the branch to delete.
+   */
+  async deleteBranch(branchId) {
+    return this.rpc.call("deleteBranch", branchId);
   }
   /**
    * Merges a branch on the server.

package/dist/net/PatchesSync.d.ts

@@ -1,18 +1,19 @@
 import * as easy_signal from 'easy-signal';
 import { ReadonlyStoreClass, Store } from 'easy-signal';
 import { SizeCalculator } from '../algorithms/ot/shared/changeBatching.js';
+import { BranchClientStore } from '../client/BranchClientStore.js';
 import { ClientAlgorithm } from '../client/ClientAlgorithm.js';
 import { Patches } from '../client/Patches.js';
 import { AlgorithmName } from '../client/PatchesStore.js';
 import { DocSyncStatus, DocSyncState, Change } from '../types.js';
 import { PatchesConnection } from './PatchesConnection.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
-import { ConnectionState } from './protocol/types.js';
+import { BranchAPI, ConnectionState } from './protocol/types.js';
 import { WebSocketOptions } from './websocket/WebSocketTransport.js';
-import '../json-patch/types.js';
-import '../BaseDoc-BT18xPxU.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
+import '../json-patch/types.js';
+import '../BaseDoc-BT18xPxU.js';
 import '../utils/deferred.js';
 
 interface PatchesSyncState {
@@ -31,6 +32,20 @@ interface PatchesSyncOptions {
     maxStorageBytes?: number;
     /** Custom size calculator for storage limit. Falls back to patches.docOptions.sizeCalculator. */
     sizeCalculator?: SizeCalculator;
+    /**
+     * Local store for branch metadata.
+     * When provided, enables offline branch support:
+     * - Branch metas are cached locally
+     * - Branches with `pendingOp` are synced to the server during sync
+     * - Branch document content flows through the standard doc sync pipeline
+     */
+    branchStore?: BranchClientStore;
+    /**
+     * Server-side Branch API for syncing pending branch operations.
+     * Required when branchStore is provided. Typically the same RPC client
+     * used by PatchesBranchClient instances in online mode.
+     */
+    branchApi?: BranchAPI;
 }
 /**
  * Handles server connection, document subscriptions, and syncing logic between
@@ -69,6 +84,12 @@ declare class PatchesSync extends ReadonlyStoreClass<PatchesSyncState> {
      * Provides the pending changes that were discarded so the application can handle them.
      */
     readonly onRemoteDocDeleted: easy_signal.Signal<(docId: string, pendingChanges: Change[]) => void>;
+    /**
+     * Signal emitted after pending branch metas have been synced to the server.
+     * Consumers should use this to refresh in-memory branch state (e.g. call `loadCached()`
+     * on their PatchesBranchClient instances).
+     */
+    readonly onBranchMetasSynced: easy_signal.Signal<easy_signal.SignalSubscriber>;
     constructor(patches: Patches, url: string, options?: PatchesSyncOptions);
     constructor(patches: Patches, connection: PatchesConnection, options?: PatchesSyncOptions);
     private _unsubs;
@@ -109,6 +130,18 @@ declare class PatchesSync extends ReadonlyStoreClass<PatchesSyncState> {
      * After calling destroy(), this instance should not be reused.
      */
     destroy(): void;
+    /**
+     * Syncs pending branch metas to the server.
+     *
+     * Pending branches come in two flavors:
+     * - **Created offline** (`pending: true`, no `deleted`): created on the server via `createBranch`.
+     * - **Deleted offline** (`pending: true`, `deleted: true`): deleted on the server via `deleteBranch`,
+     *   then physically removed from the local store.
+     *
+     * The server skips initial change creation when `contentStartRev` is set in the metadata,
+     * so their document content flows through the standard doc sync pipeline.
+     */
+    protected syncPendingBranchMetas(): Promise<void>;
     /**
      * Syncs all known docs when initially connected.
      */

package/dist/net/PatchesSync.js

@@ -52,8 +52,17 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
      * Provides the pending changes that were discarded so the application can handle them.
      */
     __publicField(this, "onRemoteDocDeleted", signal());
+    /**
+     * Signal emitted after pending branch metas have been synced to the server.
+     * Consumers should use this to refresh in-memory branch state (e.g. call `loadCached()`
+     * on their PatchesBranchClient instances).
+     */
+    __publicField(this, "onBranchMetasSynced", signal());
     __publicField(this, "_unsubs", []);
     this.patches = patches;
+    if (options?.branchStore && !options?.branchApi) {
+      throw new Error("branchApi is required when branchStore is provided");
+    }
     this.maxPayloadBytes = options?.maxPayloadBytes;
     this.maxStorageBytes = options?.maxStorageBytes ?? patches.docOptions?.maxStorageBytes;
     this.sizeCalculator = options?.sizeCalculator ?? patches.docOptions?.sizeCalculator;
@@ -160,6 +169,68 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
     for (const unsub of this._unsubs) unsub();
     this._unsubs.length = 0;
   }
+  /**
+   * Syncs pending branch metas to the server.
+   *
+   * Pending branches come in two flavors:
+   * - **Created offline** (`pending: true`, no `deleted`): created on the server via `createBranch`.
+   * - **Deleted offline** (`pending: true`, `deleted: true`): deleted on the server via `deleteBranch`,
+   *   then physically removed from the local store.
+   *
+   * The server skips initial change creation when `contentStartRev` is set in the metadata,
+   * so their document content flows through the standard doc sync pipeline.
+   */
+  async syncPendingBranchMetas() {
+    const branchStore = this.options?.branchStore;
+    const branchApi = this.options?.branchApi;
+    if (!branchStore || !branchApi) return;
+    const pendingBranches = await branchStore.listPendingBranches();
+    const creates = pendingBranches.filter((b) => b.pendingOp === "create");
+    const updates = pendingBranches.filter((b) => b.pendingOp === "update");
+    const deletes = pendingBranches.filter((b) => b.pendingOp === "delete");
+    for (const branch of creates) {
+      if (!this.state.connected) break;
+      try {
+        const { docId: sourceDocId, branchedAtRev, createdAt: _1, modifiedAt: _2, pendingOp: _3, deleted: _4, ...metadata } = branch;
+        await branchApi.createBranch(sourceDocId, branchedAtRev, metadata);
+        const synced = { ...branch, pendingOp: void 0 };
+        delete synced.pendingOp;
+        await branchStore.saveBranches(sourceDocId, [synced]);
+      } catch (err) {
+        console.error("Failed to sync pending branch create:", branch.id, err);
+        this.onError.emit(err instanceof Error ? err : new Error(String(err)));
+        break;
+      }
+    }
+    for (const branch of updates) {
+      if (!this.state.connected) break;
+      try {
+        const { id: _id, docId: _did, branchedAtRev: _bar, createdAt: _ca, modifiedAt: _ma, contentStartRev: _csr, pendingOp: _po, deleted: _del, ...metadata } = branch;
+        await branchApi.updateBranch(branch.id, metadata);
+        const synced = { ...branch, pendingOp: void 0 };
+        delete synced.pendingOp;
+        await branchStore.saveBranches(branch.docId, [synced]);
+      } catch (err) {
+        console.error("Failed to sync pending branch update:", branch.id, err);
+        this.onError.emit(err instanceof Error ? err : new Error(String(err)));
+        break;
+      }
+    }
+    for (const branch of deletes) {
+      if (!this.state.connected) break;
+      try {
+        await branchApi.deleteBranch(branch.id);
+        await branchStore.removeBranches([branch.id]);
+      } catch (err) {
+        console.error("Failed to sync pending branch deletion:", branch.id, err);
+        this.onError.emit(err instanceof Error ? err : new Error(String(err)));
+        break;
+      }
+    }
+    if (pendingBranches.length > 0) {
+      this.onBranchMetasSynced.emit();
+    }
+  }
   /**
    * Syncs all known docs when initially connected.
    */
@@ -167,6 +238,7 @@ class PatchesSync extends (_a = ReadonlyStoreClass, _syncDoc_dec = [serialGate],
     if (!this.state.connected) return;
     this.updateState({ syncStatus: "syncing" });
     try {
+      await this.syncPendingBranchMetas();
       const allTracked = [];
       for (const algorithm of Object.values(this.patches.algorithms)) {
         if (!algorithm) continue;

package/dist/net/index.d.ts

@@ -4,11 +4,11 @@ export { PatchesConnection } from './PatchesConnection.js';
 export { PatchesSync, PatchesSyncOptions, PatchesSyncState } from './PatchesSync.js';
 export { PatchesREST, PatchesRESTOptions } from './rest/PatchesREST.js';
 export { BufferedEvent, SSEServer, SSEServerOptions } from './rest/SSEServer.js';
-export { encodeDocId, normalizeIds } from './rest/utils.js';
+export { 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';
@@ -19,6 +19,7 @@ export { WebSocketOptions, WebSocketTransport } from './websocket/WebSocketTrans
 export { CommitChangesOptions } from '../types.js';
 import 'easy-signal';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../client/ClientAlgorithm.js';
 import '../json-patch/types.js';
 import '../BaseDoc-BT18xPxU.js';