@dabble/patches 0.8.8 → 0.8.10

package/dist/server/OTBranchManager.js

@@ -5,7 +5,7 @@ import { createChange } from "../data/change.js";
 import { createVersionMetadata } from "../data/version.js";
 import {
   assertBranchMetadata,
-  assertBranchOpenForMerge,
+  assertBranchExists,
   assertNotABranch,
   branchManagerApi,
   createBranchRecord,
@@ -22,49 +22,55 @@ class OTBranchManager {
   /**
    * 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.
    */
-  async listBranches(docId) {
-    return await this.store.listBranches(docId);
+  async listBranches(docId, options) {
+    return await this.store.listBranches(docId, options);
   }
   /**
    * 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 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, initialChanges) {
+  async createBranch(docId, rev, metadata) {
+    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;
+      }
+    }
     await assertNotABranch(this.store, docId);
-    const branchDocId = await generateBranchId(this.store, docId);
     const now = Date.now();
-    let initChanges;
-    if (initialChanges?.length) {
-      initChanges = initialChanges;
+    let contentStartRev;
+    if (metadata?.contentStartRev) {
+      contentStartRev = metadata.contentStartRev;
     } 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 initChanges = this.maxPayloadBytes ? breakChanges([rootReplace], this.maxPayloadBytes) : [rootReplace];
+      contentStartRev = initChanges[initChanges.length - 1].rev + 1;
+      await this.store.saveChanges(branchDocId, initChanges);
+      const initialVersionMetadata = createVersionMetadata({
+        origin: "main",
+        startedAt: now,
+        endedAt: now,
+        endRev: rev,
+        startRev: rev,
+        name: metadata?.name,
+        groupId: branchDocId,
+        branchName: metadata?.name
+      });
+      await this.store.createVersion(branchDocId, initialVersionMetadata, initChanges);
     }
-    const contentStartRev = initChanges[initChanges.length - 1].rev + 1;
-    await this.store.saveChanges(branchDocId, initChanges);
-    const initialVersionMetadata = createVersionMetadata({
-      origin: "main",
-      startedAt: now,
-      endedAt: now,
-      endRev: rev,
-      startRev: rev,
-      name: metadata?.name,
-      groupId: branchDocId,
-      branchName: metadata?.name
-    });
-    await this.store.createVersion(branchDocId, initialVersionMetadata, initChanges);
     const branch = createBranchRecord(branchDocId, docId, rev, contentStartRev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
@@ -76,79 +82,65 @@ class OTBranchManager {
    */
   async updateBranch(branchId, metadata) {
     assertBranchMetadata(metadata);
-    await this.store.updateBranch(branchId, metadata);
+    await this.store.updateBranch(branchId, { ...metadata, modifiedAt: Date.now() });
   }
   /**
-   * 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.
    */
-  async closeBranch(branchId, status) {
-    await this.store.updateBranch(branchId, { status: status ?? "closed" });
+  async deleteBranch(branchId) {
+    await this.store.deleteBranch(branchId);
   }
   /**
    * 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.
    */
   async mergeBranch(branchId) {
     const branch = await this.store.loadBranch(branchId);
-    assertBranchOpenForMerge(branch, branchId);
+    assertBranchExists(branch, branchId);
     const sourceDocId = branch.docId;
     const branchStartRevOnSource = branch.branchedAtRev;
-    const contentStartRev = branch.contentStartRev ?? 2;
-    const branchChanges = await this.store.listChanges(branchId, { startAfter: contentStartRev - 1 });
+    const startAfter = branch.lastMergedRev ?? (branch.contentStartRev ?? 2) - 1;
+    const branchChanges = await this.store.listChanges(branchId, { startAfter });
     if (branchChanges.length === 0) {
-      console.log(`Branch ${branchId} has no changes to merge.`);
-      await this.closeBranch(branchId, "merged");
       return [];
     }
-    const sourceChanges = await this.store.listChanges(sourceDocId, {
-      startAfter: branchStartRevOnSource
-    });
-    const canFastForward = sourceChanges.length === 0;
+    const lastBranchRev = branchChanges[branchChanges.length - 1].rev;
     const branchVersions = await this.store.listVersions(branchId, { origin: "main" });
-    const versionOrigin = canFastForward ? "main" : "branch";
     let lastVersionId;
     for (const v of branchVersions) {
       const newVersionMetadata = createVersionMetadata({
         ...v,
-        origin: versionOrigin,
+        origin: "branch",
         startRev: branchStartRevOnSource,
         groupId: branchId,
         branchName: branch.name,
-        // Keep branchName for traceability
         parentId: lastVersionId
       });
       const changes = await this.store.loadVersionChanges?.(branchId, v.id);
       await this.store.createVersion(sourceDocId, newVersionMetadata, changes);
       lastVersionId = newVersionMetadata.id;
     }
+    const changesToCommit = branchChanges.map((c, i) => ({
+      ...c,
+      baseRev: branchStartRevOnSource,
+      rev: branchStartRevOnSource + i + 1,
+      batchId: branchId
+    }));
     const committedMergeChanges = await wrapMergeCommit(branchId, sourceDocId, async () => {
-      if (canFastForward) {
-        const adjustedChanges = branchChanges.map((c) => ({
-          ...c,
-          baseRev: branchStartRevOnSource,
-          rev: void 0
-          // Let commitChanges assign sequential revs
-        }));
-        return (await this.patchesServer.commitChanges(sourceDocId, adjustedChanges)).changes;
-      } else {
-        const rev = branchStartRevOnSource + branchChanges.length;
-        const flattenedChange = createChange(
-          branchStartRevOnSource,
-          rev,
-          branchChanges.flatMap((c) => c.ops)
-        );
-        let changesToCommit = [flattenedChange];
-        if (this.maxPayloadBytes) {
-          changesToCommit = breakChanges(changesToCommit, this.maxPayloadBytes);
-        }
-        return (await this.patchesServer.commitChanges(sourceDocId, changesToCommit)).changes;
-      }
+      return (await this.patchesServer.commitChanges(sourceDocId, changesToCommit)).changes;
     });
-    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 committedMergeChanges;
   }
 }

package/dist/server/branchUtils.d.ts

@@ -1,5 +1,5 @@
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { EditableBranchMetadata, Branch, BranchStatus } from '../types.js';
+import { EditableBranchMetadata, Branch, CreateBranchMetadata } from '../types.js';
 import 'easy-signal';
 import '../net/websocket/AuthorizationProvider.js';
 import './types.js';
@@ -40,7 +40,7 @@ declare function generateBranchId(store: BranchIdGenerator, docId: string): Prom
  * @param metadata - Optional branch metadata (name, etc.).
  * @returns A new Branch object.
  */
-declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, contentStartRev: number, metadata?: EditableBranchMetadata): Branch;
+declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, contentStartRev: number, metadata?: CreateBranchMetadata | EditableBranchMetadata): Branch;
 /**
  * Store interface for branch loading.
  */
@@ -55,12 +55,12 @@ interface BranchLoader {
  */
 declare function assertNotABranch(store: BranchLoader, docId: string): Promise<void>;
 /**
- * Validates that a branch exists and is open for merging.
+ * Validates that a branch exists.
  * @param branch - The branch to validate (may be null).
  * @param branchId - The branch ID (for error messages).
- * @throws Error if branch not found or not open.
+ * @throws Error if branch not found.
  */
-declare function assertBranchOpenForMerge(branch: Branch | null, branchId: string): asserts branch is Branch;
+declare function assertBranchExists(branch: Branch | null, branchId: string): asserts branch is Branch;
 /**
  * Wraps a merge commit operation with standard error handling.
  * @param branchId - The branch being merged.
@@ -70,14 +70,5 @@ declare function assertBranchOpenForMerge(branch: Branch | null, branchId: strin
  * @throws Error with standardized message if commit fails.
  */
 declare function wrapMergeCommit<T>(branchId: string, sourceDocId: string, commitFn: () => Promise<T>): Promise<T>;
-/**
- * Standard close branch operation.
- * @param store - Store with updateBranch capability.
- * @param branchId - The branch to close.
- * @param status - The status to set (defaults to 'closed').
- */
-declare function closeBranch(store: {
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name'>>): Promise<void>;
-}, branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
 
-export { type BranchIdGenerator, type BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, closeBranch, createBranchRecord, generateBranchId, wrapMergeCommit };
+export { type BranchIdGenerator, type BranchLoader, assertBranchExists, assertBranchMetadata, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit };

package/dist/server/branchUtils.js

@@ -4,10 +4,19 @@ const branchManagerApi = {
   listBranches: "read",
   createBranch: "write",
   updateBranch: "write",
-  closeBranch: "write",
+  deleteBranch: "write",
   mergeBranch: "write"
 };
-const nonModifiableBranchFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status", "contentStartRev"]);
+const nonModifiableBranchFields = /* @__PURE__ */ new Set([
+  "id",
+  "docId",
+  "branchedAtRev",
+  "createdAt",
+  "modifiedAt",
+  "contentStartRev",
+  "pendingOp",
+  "deleted"
+]);
 function assertBranchMetadata(metadata) {
   if (!metadata) return;
   for (const key in metadata) {
@@ -20,14 +29,15 @@ async function generateBranchId(store, docId) {
   return store.createBranchId ? await Promise.resolve(store.createBranchId(docId)) : createId(22);
 }
 function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, contentStartRev, metadata) {
+  const now = Date.now();
   return {
     ...metadata,
     id: branchDocId,
     docId: sourceDocId,
     branchedAtRev,
     contentStartRev,
-    createdAt: Date.now(),
-    status: "open"
+    createdAt: now,
+    modifiedAt: now
   };
 }
 async function assertNotABranch(store, docId) {
@@ -36,13 +46,10 @@ async function assertNotABranch(store, docId) {
     throw new Error("Cannot create a branch from another branch.");
   }
 }
-function assertBranchOpenForMerge(branch, branchId) {
+function assertBranchExists(branch, branchId) {
   if (!branch) {
     throw new Error(`Branch with ID ${branchId} not found.`);
   }
-  if (branch.status !== "open") {
-    throw new Error(`Branch ${branchId} is not open (status: ${branch.status}). Cannot merge.`);
-  }
 }
 async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
   try {
@@ -52,15 +59,11 @@ async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
     throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
 }
-async function closeBranch(store, branchId, status) {
-  await store.updateBranch(branchId, { status: status ?? "closed" });
-}
 export {
+  assertBranchExists,
   assertBranchMetadata,
-  assertBranchOpenForMerge,
   assertNotABranch,
   branchManagerApi,
-  closeBranch,
   createBranchRecord,
   generateBranchId,
   wrapMergeCommit

package/dist/server/index.d.ts

@@ -9,7 +9,7 @@ export { buildVersionState, getBaseStateBeforeVersion } from '../algorithms/ot/s
 export { concatStreams, jsonReadable, parseVersionState, readStreamAsString } from './jsonReadable.js';
 export { blockable, blockableResponse, blocking, releaseConcurrency, singleInvocation } from '../utils/concurrency.js';
 export { RevConflictError } from './RevConflictError.js';
-export { BranchIdGenerator, BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit } from './branchUtils.js';
+export { BranchIdGenerator, BranchLoader, assertBranchExists, assertBranchMetadata, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit } from './branchUtils.js';
 export { CompressedStoreBackend } from './CompressedStoreBackend.js';
 export { createTombstoneIfSupported, isTombstoneStore, removeTombstoneIfExists } from './tombstone.js';
 export { assertVersionMetadata } from './utils.js';

package/dist/server/index.js

@@ -11,7 +11,7 @@ import { blockable, blockableResponse, blocking, releaseConcurrency, singleInvoc
 import { RevConflictError } from "./RevConflictError.js";
 import {
   assertBranchMetadata,
-  assertBranchOpenForMerge,
+  assertBranchExists,
   assertNotABranch,
   branchManagerApi,
   createBranchRecord,
@@ -30,8 +30,8 @@ export {
   OTServer,
   PatchesHistoryManager,
   RevConflictError,
+  assertBranchExists,
   assertBranchMetadata,
-  assertBranchOpenForMerge,
   assertNotABranch,
   assertVersionMetadata,
   blockable,

package/dist/server/types.d.ts

@@ -1,5 +1,5 @@
 import { JSONPatchOp } from '../json-patch/types.js';
-import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, Branch } from '../types.js';
+import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, ListBranchesOptions, Branch } from '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
@@ -150,13 +150,19 @@ interface BranchingStoreBackend {
      */
     createBranchId?(docId: string): Promise<string> | string;
     /** Lists metadata records for branches originating from a document. */
-    listBranches(docId: string): Promise<Branch[]>;
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
     /** Loads the metadata record for a specific branch ID. */
     loadBranch(branchId: string): Promise<Branch | null>;
     /** Creates or updates the metadata record for a branch. */
     createBranch(branch: Branch): 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>;
+    /**
+     * Replaces a branch record with a tombstone containing only `id`, `docId`, `modifiedAt`,
+     * and `deleted: true`. Tombstones are returned by `listBranches` when `since` is provided
+     * so that clients can clean up their local cache.
+     */
+    deleteBranch(branchId: string): Promise<void>;
 }
 
 export type { BranchingStoreBackend, LWWStoreBackend, ListFieldsOptions, OTStoreBackend, ServerStoreBackend, SnapshotResult, TombstoneStoreBackend, VersioningStoreBackend };

package/dist/solid/context.d.ts

@@ -10,6 +10,7 @@ import '../client/ClientAlgorithm.js';
 import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/dist/solid/index.d.ts

@@ -1,5 +1,5 @@
 export { PatchesContextValue, PatchesProvider, PatchesProviderProps, usePatchesContext } from './context.js';
-export { MaybeAccessor, PatchesDocProviderProps, UsePatchesDocLazyOptions, UsePatchesDocLazyReturn, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync } from './primitives.js';
+export { MaybeAccessor, PatchesDocProviderProps, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync } from './primitives.js';
 export { CreateManagedDocsOptions, CreateManagedDocsReturn, createManagedDocs } from './managed-docs.js';
 export { fillPath } from '../shared/utils.js';
 export { DocManager, getDocManager } from '../shared/doc-manager.js';
@@ -15,6 +15,7 @@ import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/dist/solid/primitives.d.ts

@@ -1,172 +1,78 @@
 import { Accessor } from 'solid-js';
 import { OpenDocOptions } from '../client/Patches.js';
 import { P as PatchesDoc } from '../BaseDoc-BT18xPxU.js';
-import { JSONPatch } from '../json-patch/JSONPatch.js';
 import { ChangeMutator } from '../types.js';
 import 'easy-signal';
 import '../json-patch/types.js';
 import '../client/ClientAlgorithm.js';
 import '../client/PatchesStore.js';
+import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
 /**
- * Options for usePatchesDoc primitive (eager mode with docId).
+ * Options for usePatchesDoc primitive.
  */
 interface UsePatchesDocOptions extends OpenDocOptions {
     /**
-     * Controls document lifecycle management on cleanup.
-     *
-     * - `false` (default): Explicit mode. Assumes doc is already open. Throws if not.
-     * - `true`: Opens doc on mount with ref counting, closes on cleanup (doc stays tracked).
-     * - `'untrack'`: Opens doc on mount, closes AND untracks on cleanup (removes from sync).
-     *
-     * @default false
+     * When true, the document is removed from sync tracking on close.
+     * By default documents stay tracked after closing.
      */
-    autoClose?: boolean | 'untrack';
+    untrack?: boolean;
 }
 /**
- * Options for usePatchesDoc primitive (lazy mode without docId).
- */
-interface UsePatchesDocLazyOptions {
-    /**
-     * Inject doc.id into state under this key on every state update.
-     * Useful when the document ID is derived from the path but needed in the data.
-     */
-    idProp?: string;
-}
-/**
- * Return type for usePatchesDoc primitive (eager mode).
+ * Return type for usePatchesDoc primitive.
  */
 interface UsePatchesDocReturn<T extends object> {
-    /**
-     * Accessor for the document state.
-     * Updated whenever the document changes (local or remote).
-     */
+    /** Accessor for the document state. */
     data: Accessor<T | undefined>;
-    /**
-     * Whether the document is currently loading/syncing.
-     * - `true` during initial load or updates
-     * - `false` when fully synced
-     */
+    /** Whether the document is currently loading. */
     loading: Accessor<boolean>;
-    /**
-     * Error that occurred during sync, if any.
-     */
+    /** Error that occurred during sync, if any. */
     error: Accessor<Error | undefined>;
-    /**
-     * The committed revision number.
-     * Increments each time the server confirms changes.
-     */
+    /** The committed revision number. */
     rev: Accessor<number>;
-    /**
-     * Whether there are pending local changes not yet committed by server.
-     */
+    /** Whether there are pending local changes not yet committed by server. */
     hasPending: Accessor<boolean>;
-    /**
-     * Make changes to the document.
-     *
-     * @example
-     * ```typescript
-     * change((patch, root) => {
-     *   patch.replace(root.title!, 'New Title')
-     * })
-     * ```
-     */
+    /** Make changes to the document. No-ops if the document is not loaded. */
     change: (mutator: ChangeMutator<T>) => void;
-    /**
-     * The underlying PatchesDoc instance.
-     * Useful for advanced operations.
-     */
+    /** Close the document and reset state. Useful for explicit cleanup. */
+    close: () => Promise<void>;
+    /** The underlying PatchesDoc instance. */
     doc: Accessor<PatchesDoc<T> | undefined>;
 }
 /**
- * Return type for usePatchesDoc primitive (lazy mode).
- * Extends the eager return type with lifecycle management methods.
+ * Type for document ID — can be a static string or accessor function.
  */
-interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<T> {
-    /**
-     * Current document path. `null` when no document is loaded.
-     */
-    path: Accessor<string | null>;
-    /**
-     * Open a document by path. Closes any previously loaded document first.
-     *
-     * @param docPath - The document path to open
-     * @param options - Optional algorithm and metadata overrides
-     */
-    load: (docPath: string, options?: OpenDocOptions) => Promise<void>;
-    /**
-     * Close the current document, unsubscribe, and reset all state.
-     * Calls `patches.closeDoc()` but does not untrack — tracking is managed separately.
-     */
-    close: () => Promise<void>;
-    /**
-     * Create a new document: open it, set initial state, then close it.
-     * A one-shot operation that doesn't bind the document to this handle.
-     *
-     * @param docPath - The document path to create
-     * @param initialState - Initial state object or JSONPatch to apply
-     * @param options - Optional algorithm and metadata overrides
-     */
-    create: (docPath: string, initialState: T | JSONPatch, options?: OpenDocOptions) => Promise<void>;
-}
+type MaybeAccessor<T> = T | Accessor<T>;
 /**
  * Solid primitive for reactive Patches document state.
  *
- * ## Eager Mode (with docId)
- *
- * Provides reactive access to an already-open Patches document.
+ * Opens the document automatically and closes it on cleanup (or when the
+ * accessor value changes). Accepts a static string or an accessor. When the
+ * value is falsy, no document is loaded.
  *
  * @example
  * ```tsx
- * // Explicit lifecycle — you control open/close
- * const { data, loading, change } = usePatchesDoc(() => props.docId)
+ * // Static
+ * const { data, change } = usePatchesDoc('doc-123')
  *
- * // Auto lifecycle — opens on mount, closes on cleanup
- * const { data, loading, change } = usePatchesDoc(() => props.docId, { autoClose: true })
- * ```
- *
- * ## Lazy Mode (without docId)
- *
- * Returns a deferred handle with `load()`, `close()`, and `create()` methods.
- * Does NOT register `onCleanup` — caller manages lifecycle.
- *
- * @example
- * ```tsx
- * const { data, load, close, change, create } = usePatchesDoc<Project>()
- *
- * // Later, when the user navigates:
- * await load('projects/abc/content')
- *
- * // When leaving:
- * await close()
+ * // Reactive — swaps automatically
+ * const [projectId, setProjectId] = createSignal<string | null>('abc')
+ * const { data, change } = usePatchesDoc(() => projectId() && `projects/${projectId()}`)
  * ```
  */
-declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
-declare function usePatchesDoc<T extends object>(options?: UsePatchesDocLazyOptions): UsePatchesDocLazyReturn<T>;
+declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string | null | undefined | false>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
 /**
  * Return type for usePatchesSync primitive.
  */
 interface UsePatchesSyncReturn {
-    /**
-     * Whether the WebSocket connection is established.
-     */
     connected: Accessor<boolean>;
-    /**
-     * Whether documents are currently syncing with the server.
-     */
     syncing: Accessor<boolean>;
-    /**
-     * Whether the client believes it has network connectivity.
-     */
     online: Accessor<boolean>;
 }
 /**
  * Solid primitive for reactive Patches sync state.
  *
- * Provides reactive access to PatchesSync connection and sync status.
- * Useful for showing "Offline" banners, global loading indicators, etc.
- *
  * @example
  * ```tsx
  * const { connected, syncing, online } = usePatchesSync();
@@ -177,68 +83,37 @@ interface UsePatchesSyncReturn {
  *   </Show>
  * );
  * ```
- *
- * @returns Reactive sync state
- * @throws Error if Patches context not provided
- * @throws Error if PatchesSync was not provided to context
  */
 declare function usePatchesSync(): UsePatchesSyncReturn;
-/**
- * Type for document ID - can be static string or accessor function.
- */
-type MaybeAccessor<T> = T | Accessor<T>;
 /**
  * Props for the Provider component returned by createPatchesDoc.
  */
 interface PatchesDocProviderProps extends OpenDocOptions {
     docId: MaybeAccessor<string>;
-    autoClose?: boolean | 'untrack';
+    untrack?: boolean;
     children: any;
 }
 /**
  * Creates a named document context that can be provided to child components.
  *
- * This enables child components to access the document using the returned `useDoc` hook
- * without needing to pass the docId down through props. Supports both static and
- * reactive docIds.
- *
- * ## Use Cases
- *
- * **Static document (user settings):**
+ * @example
  * ```tsx
  * const { Provider, useDoc } = createPatchesDoc<User>('user');
  *
  * <Provider docId="user-123">
  *   <UserProfile />
  * </Provider>
- * ```
  *
- * **Reactive document (multi-tab):**
- * ```tsx
- * const { Provider, useDoc } = createPatchesDoc<Whiteboard>('whiteboard');
+ * // Reactive
  * const [activeTabId, setActiveTabId] = createSignal('design-1');
- *
  * <Provider docId={activeTabId}>
  *   <WhiteboardCanvas />
  * </Provider>
  * ```
- *
- * **With autoClose:**
- * ```tsx
- * const { Provider, useDoc } = createPatchesDoc<Doc>('document');
- * const [currentDocId, setCurrentDocId] = createSignal('doc-1');
- *
- * <Provider docId={currentDocId} autoClose>
- *   <DocumentEditor />
- * </Provider>
- * ```
- *
- * @param name - Unique identifier for this document context (e.g., 'whiteboard', 'user')
- * @returns Object with Provider component and useDoc hook
  */
 declare function createPatchesDoc<T extends object>(name: string): {
     Provider: (props: PatchesDocProviderProps) => any;
     useDoc: () => UsePatchesDocReturn<T>;
 };
 
-export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocLazyOptions, type UsePatchesDocLazyReturn, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };
+export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };