@dabble/patches 0.2.13 → 0.2.15

package/README.md

@@ -1,12 +1,26 @@
 # Patches
 
-A friendly realtime library based on operational transformations.
+**Hello, friend!** Meet your new favorite realtime library. It's based on operational transformations, but don't let that scare you!
 
 <img src="./patches.png" alt="Patches the Dog" style="width: 300px;">
 
-Patches is a TypeScript library designed for building real-time collaborative applications. It leverages Operational Transformation (OT) with a centralized server model to ensure document consistency across multiple clients. It supports versioning, offline work, branching, and can handle very large and very long-lived documents.
+## What Is This Thing?
 
-When working with a document in Patches, you are working with regular JavaScript data types. If it is supported by JSON, you can have it in your document. The `state` in your `doc.state` is your immutable data. When you modify your document with `doc.change(state => state.prop = 'new value')` the doc will get a new immutable `state` object with those changes applied.
+Patches is a TypeScript library that makes building collaborative apps _delightfully_ straightforward. You know, the kind where multiple people can edit the same document at once without everything exploding? Yeah, those!
+
+It uses something called Operational Transformation (fancy, I know) with a centralized server model. Translation: Your users can collaborate without weird conflicts, even when their internet connection gets flaky.
+
+The BEST part? It handles massive documents with loooong histories. We're talking documents with 480,000+ operations that load in 1-2ms. Not a typo!
+
+## Why You'll Love It
+
+When working with Patches, you're just using normal JavaScript data. If JSON supports it, Patches supports it. Your document's `state` is immutable (fancy word for "won't change unexpectedly"). When you want to change something, you just do:
+
+```js
+doc.change(state => (state.prop = 'new value'));
+```
+
+And bam! You get a fresh new state with your changes applied.
 
 ## Table of Contents
 
@@ -17,56 +31,49 @@ When working with a document in Patches, you are working with regular JavaScript
   - [Client Example](#client-example)
   - [Server Example](#server-example)
 - [Core Components](#core-components)
-  - [Patches](#patches-main-client)
-  - [PatchesDoc](#patchesdoc-document-instance)
-  - [PatchesServer](#patchesserver)
-  - [PatchesHistoryManager](#patcheshistorymanager)
-  - [PatchesBranchManager](#patchesbranchmanager)
-  - [Backend Store](#backend-store)
-  - [Transport & Networking](#transport--networking)
-  - [Awareness (Presence, Cursors, etc.)](#awareness-presence-cursors-etc)
 - [Basic Workflow](#basic-workflow)
-  - [Client-Side](#client-side)
-  - [Server-Side](#server-side)
 - [Examples](#examples)
-  - [Simple Client Setup](#simple-client-setup)
-  - [Simple Server Setup](#simple-server-setup)
 - [Advanced Topics](#advanced-topics)
-  - [Offline Support & Versioning](#offline-support--versioning)
-  - [Branching and Merging](#branching-and-merging)
-  - [Custom OT Types](#custom-ot-types)
 - [JSON Patch (Legacy)](#json-patch-legacy)
 - [Contributing](#contributing)
 - [License](#license)
 
 ## Why Operational Transformations?
 
-**OT vs CRDT**
-[Conflict-Free Replicated Datatypes](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) are the newest and improved algorithm for collaborative editing, so why use [Operational Transformation](https://en.wikipedia.org/wiki/Operational_transformation)? There [are](https://thom.ee/blog/crdt-vs-operational-transformation/) [various](https://www.tiny.cloud/blog/real-time-collaboration-ot-vs-crdt/) [opinions](https://fiberplane.com/blog/why-we-at-fiberplane-use-operational-transformation-instead-of-crdt/) about which to use. We found that at [Dabble Writer](https://www.dabblewriter.com/), the performance of CRDTs was not good enough for some of the extremely large or long-lived documents for our customers. Even the highly optimized [Y.js](https://yjs.dev/) which we really hoped would work for us didn't cut it. And since our service requires a central server anyway, we decided to double-down on our OT library, spruce it up, deck it out, improve the [DX](https://en.wikipedia.org/wiki/User_experience#Developer_experience) for ourselves, but hopefully it is useful for you too.
+**"Wait, shouldn't I be using CRDTs instead?"**
+
+Look, there are [lots](https://thom.ee/blog/crdt-vs-operational-transformation/) of [opinions](https://www.tiny.cloud/blog/real-time-collaboration-ot-vs-crdt/) about [this](https://fiberplane.com/blog/why-we-at-fiberplane-use-operational-transformation-instead-of-crdt/). Here's the deal: at [Dabble Writer](https://www.dabblewriter.com/), we tried CRDTs. We REALLY wanted them to work. Even the super-optimized [Y.js](https://yjs.dev/) couldn't handle our power users' documents.
 
-**What about Y.js?**
-For those who may want to let us know that Y.js can handle large documents, we did run tests ourselves. We were impressed with what Y.js offers and were hopeful it would work for us. We prefer to focus on the user experience than on our syncing library. However, it was not to be.
+Some of our users have projects with 480k+ operations. 😱 These monsters took hours to re-create in Y.js, ~4 seconds to load in optimized Y.js, and ~20ms to add a change. With our OT library? 1-2ms to load and 0.2ms to apply a change.
 
-Our longest project contains over 480k operations in it. 😳 And considering we save written text in 30-second chunks, not character-by-character, you can start to understand how _extra_ some of our customers are in their writing. That project took a few hours to re-create in Y.js from our OT patches, ~4 seconds to load in an optimized, GCed Y.js doc on a fast Mac Studio, and ~20ms to add a new change to it. Compare that to our (this) OT library which takes 1-2ms to load the doc and 0.2ms to apply a new change to it. As projects grow larger or longer, OT's performance remains constant and CRDT's diminish. For _most_ use-cases CRDTs may be better, but if you have very large—or more importantly long-lived (many changes over time)—documents, you may find OT a better choice.
+As projects grow larger or longer-lived, OT performance stays zippy while CRDTs slow down. For most use cases, CRDTs might be perfect! But if you have very large or long-lived documents (especially ones that accumulate tons of changes over time), OT could save your bacon.
 
 ## Key Concepts
 
-- **Centralized OT:** Uses a central authority (the server) to definitively order operations, simplifying conflict resolution compared to fully distributed OT systems. ([Learn more about centralized vs. distributed OT](https://marijnhaverbeke.nl/blog/collaborative-editing.html#centralization)).
-- **Rebasing:** Client changes are "rebased" on top of changes they receive from the server, ensuring local edits are adjusted correctly based on the server's history.
-- **Linear History:** The server maintains a single, linear history of document revisions.
-- **Client-Server Communication:** Clients send batches of changes (`Change` objects) tagged with the server revision they were based on (`baseRev`). The server transforms these changes, applies them, assigns a new revision number, and broadcasts the committed change back to clients.
+- **Centralized OT:** Using a server as the authority makes everything WAY simpler. No complicated peer-to-peer conflict resolution!
+- **Rebasing:** Client changes get "rebased" on top of server changes. Like git rebase, but for your real-time edits!
+- **Linear History:** The server keeps one straight timeline of revisions. No timeline branches = no headaches.
+- **Client-Server Dance:** Clients send batches of changes tagged with the server revision they're based on. The server transforms them, applies them, gives them a new revision number, and broadcasts them back.
 
 **Why Centralized?**
-There are many papers and algorithms for OT. There are problems—edge-cases—with those that don't rely on a central authority. To simplify, we use an algorithm that only transforms operations in one direction, rather than in 2. It is more like a git _rebase_. This method was inspired by [Marijn Haverbeke's article](https://marijnhaverbeke.nl/blog/collaborative-editing.html) about the topic, and we originally had the server reject changes if new ones came in before them and require the client to transform (rebase) them and resubmit. This comes with a theoretical downside, however. Slow connections and quickly changing documents may keep slower clients resubmitting over and over and never committing. For example, if you had an OT document that tracked all the mouse movements of every client connected to a document, a slow client might have severe jitter while it tries to commit its mouse position. I wouldn't suggest using OT for this use-case, but as I said, it is a theoretical downside. So we have modified our approach to make the server do the transform and commit, sending back any new changes _and_ the transformed submitted ones for the client to apply. This ensures all clients "get equal time with the server", even with slow connections.
 
-**Snapshots**
-OT documents are essentially an array of changes. To create the in-memory state of the document, the `doc.state` that you view, you must replay each change from the first to the last. You may recognize a problem here. For long documents (like ones with 480k changes), this could take some time. For this reason, OT will snapshot the data every X number of changes (200, 500, etc). This allows you to grab the latest snapshot and then any changes after it was created and replay those change on top of the snapshot to get the latest state. This is what allows OT to have consistent performance over time.
+We use an algorithm that only transforms operations in one direction (like git rebase), inspired by [Marijn Haverbeke's article](https://marijnhaverbeke.nl/blog/collaborative-editing.html). Originally, we made the server reject changes if new ones came in before them, forcing clients to transform and resubmit. BUT! This could theoretically make slow clients keep resubmitting forever and never committing.
 
-**Versioning as Snapshots**
-Most realtime collaborative documents are accessed and changed in bursts—user sessions—where a person sits down to write, design, edit, whiteboard, etc. Most of these use-cases benefit from "versioning" features where the user can go back in time to see old versions of their project. Patches combines the concept of snapshots and versions. Instead of using X number of changes to decide when to create a snapshot, Patches creates a new versions/snapshots after there is more than 30 minutes between any 2 changes. Some versions or snapshots may only reflect 1 change. Others may reflect 100s. As long as your document isn't being constantly updated, the requirement of snapshots turns into a feature you can provide your users. _If you have an [IoT](https://en.wikipedia.org/wiki/Internet_of_things) use-case or something similar where there is no break to create versions, we'd be happy for a pull request that allows Patches to support both. But we didn't want to make the code more complex for something that may not be used._
+So we leveled up! Now the server does the transform and commit, sending back both new changes AND the transformed submitted ones. Everyone gets equal time with the server, even the slowpokes!
+
+**Snapshots = Performance Magic**
+
+OT documents are just arrays of changes. To create the current document state, you replay each change from first to last. For looooong documents (like our 480k changes monster), this would be painfully slow.
+
+That's why we snapshot the data every so often. Grab the latest snapshot, add recent changes, and you're good to go! This is how OT maintains consistent performance over time.
+
+**Versions as Snapshots**
+
+Most collaborative work happens in bursts. We combine snapshots with versions by creating new snapshots when there's a 30+ minute gap between changes. This clever trick turns a technical requirement into a user-facing feature – versioning!
 
 **Immutable State**
-Patches uses immutable data. That is, it uses gentleman's (and lady's) immutability, meaning, you _shouldn't_ change the structure, but for performance the objects aren't frozen. Each change creates a new object in memory, keeping the old objects that didn't change and replacing only those that did. There are [articles](https://www.freecodecamp.org/news/immutable-javascript-improve-application-performance/) [about](http://www.cowtowncoder.com/blog/archives/2010/08/entry_409.html) the [benefits](https://medium.com/@mohitgadhavi1/the-power-of-immutability-improving-javascript-performance-and-code-quality-96d82134d8da) of using immutable data, but suffice it to say, Patches assumes you won't be changing the state data outside of the `doc.change(stateProxy => {...})` method (which uses a proxy, BTW, and does not operate on the state directly).
+
+Patches uses gentleman's immutability – each change creates a new object, keeping unchanged objects as-is and only replacing what changed. This brings tons of [benefits](https://www.freecodecamp.org/news/immutable-javascript-improve-application-performance/) for [performance](http://www.cowtowncoder.com/blog/archives/2010/08/entry_409.html) and [code quality](https://medium.com/@mohitgadhavi1/the-power-of-immutability-improving-javascript-performance-and-code-quality-96d82134d8da).
 
 ## Installation
 
@@ -78,64 +85,61 @@ yarn add @dabble/patches
 
 ## Getting Started
 
-Here's a quick overview of how to set up a basic client and server using Patches. These examples assume you have a way to communicate changes between the client and server (e.g., WebSockets, HTTP polling).
-
-_(Note: These are simplified examples. Real-world implementations require proper error handling, network communication, authentication, and a persistent backend store.)_
+Let's set up a basic client and server. (These examples are simplified – real-world apps need error handling, proper network communication, auth, and persistence.)
 
 ### Client Example
 
-This shows how to initialize `Patches` (the main client interface) with an in-memory store and set up real-time sync with `PatchesSync`.
+Here's how to get rolling with Patches on the client:
 
 ```typescript
 import { Patches } from '@dabble/patches';
-import { InMemoryStore } from '@dabble/patches/persist/InMemoryStore';
-import { PatchesSync } from '@dabble/patches/net/PatchesSync';
+import { InMemoryStore } from '@dabble/patches/persist';
+import { PatchesSync } from '@dabble/patches/net';
 
 interface MyDoc {
   text: string;
   count: number;
 }
 
-// 1. Create a store (in-memory for demo; use IndexedDB or your own for production)
+// 1. Create a store (just using in-memory for this demo)
 const store = new InMemoryStore();
 
-// 2. Create the main Patches client instance
+// 2. Create the main Patches client
 const patches = new Patches({ store });
 
 // 3. Set up real-time sync with your server
 const sync = new PatchesSync('wss://your-server-url', patches);
-await sync.connect(); // Connect to the server (returns a promise)
+await sync.connect(); // Connect to the server!
 
 // 4. Open or create a document by ID
 const doc = await patches.openDoc<MyDoc>('my-doc-1');
 
-// 5. React to updates (e.g., update UI)
+// 5. React to updates (update your UI here)
 doc.onUpdate(newState => {
   console.log('Document updated:', newState);
   // Update your UI here
 });
 
 // 6. Make local changes
-// (Changes are applied optimistically and will be synced to the server)
+// (Changes apply immediately locally and sync to the server automatically)
 doc.change(draft => {
   draft.text = 'Hello World!';
   draft.count = (draft.count || 0) + 1;
 });
 
-// 7. Changes are automatically synced using PatchesSync.
-//    If not using PatchesSync, you can manually flush changes to your backend as needed.
+// 7. That's it! Changes sync automatically with PatchesSync
 ```
 
 ### Server Example
 
-This outlines a basic Express server using `PatchesServer` with an in-memory store.
+Here's a basic Express server using `PatchesServer`:
 
 ```typescript
 import express from 'express';
-import { PatchesServer, PatchesStoreBackend, Change } from '@dabble/patches';
+import { PatchesServer, PatchesStoreBackend, Change } from '@dabble/patches/server';
 
 // Server Setup
-const store = new InMemoryStore(); // Fictional in-memory backend, use a database
+const store = new InMemoryStore(); // Use a real database in production!
 const server = new PatchesServer(store);
 const app = express();
 app.use(express.json());
@@ -143,7 +147,7 @@ app.use(express.json());
 // Endpoint to receive changes
 app.post('/docs/:docId/changes', async (req, res) => {
   const docId = req.params.docId;
-  const clientChanges: Change[] = req.body.changes;
+  const clientChanges = req.body.changes;
 
   if (!Array.isArray(clientChanges)) {
     return res.status(400).json({ error: 'Invalid request' });
@@ -156,7 +160,7 @@ app.post('/docs/:docId/changes', async (req, res) => {
     res.json(committedChanges);
     // Broadcast committed changes to other connected clients (via WebSockets, etc.)
     // broadcastChanges(docId, committedChanges, req.headers['x-client-id']);
-  } catch (error: any) {
+  } catch (error) {
     console.error(`Error processing changes for ${docId}:`, error);
     const statusCode = error.message.includes('out of sync') ? 409 : 500;
     res.status(statusCode).json({ error: error.message });
@@ -179,139 +183,119 @@ const PORT = 3000;
 app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
 ```
 
-For more detailed explanations and advanced features, dive into the [Core Components](#core-components) and [Examples](#examples) sections.
+For more details and advanced features, check out the rest of the docs!
 
 ## Core Components
 
-Centralized OT has two different areas of focus, the server and the client. They both have very different jobs and interaction patterns.
-
-These are the main classes you'll interact with when building a collaborative application with Patches.
+Centralized OT has two very different areas: server and client. They do completely different jobs!
 
 ### Patches (Main Client)
 
-(`Patches` Documentation: [`docs/Patches.md`](./docs/Patches.md))
+([`docs/Patches.md`](./docs/Patches.md))
 
-This is the main entry point you'll use on the client in your app. It manages document instances (`PatchesDoc`) and persistence (`PatchesStore`). You obtain a `PatchesDoc` by calling `patches.openDoc(docId)`.
+This is your main entry point on the client. It manages document instances and persistence. You get a `PatchesDoc` by calling `patches.openDoc(docId)`.
 
-- **Document Management:** Handles opening, tracking, and closing collaborative documents.
-- **Persistence:** Integrates with a pluggable store (e.g., in-memory, IndexedDB, custom backend).
-- **Sync Integration:** Works with `PatchesSync` for real-time server sync.
-- **Event Emitters:** Provides hooks (`onError`, `onServerCommit`, etc.) to react to system-level events.
-
-See [`docs/PatchesDoc.md`](./docs/PatchesDoc.md) for detailed usage and examples.
+- **Document Management:** Opens, tracks, and closes collaborative documents
+- **Persistence:** Works with pluggable storage (in-memory, IndexedDB, custom)
+- **Sync Integration:** Pairs with `PatchesSync` for real-time server communication
+- **Event Emitters:** Hooks like `onError` and `onServerCommit` for reacting to events
 
 ### PatchesDoc (Document Instance)
 
-(`PatchesDoc` Documentation: [`docs/PatchesDoc.md`](./docs/PatchesDoc.md))
-
-A `PatchesDoc` represents a single collaborative document. You do not instantiate this directly in most apps; instead, use `patches.openDoc(docId)`.
+([`docs/PatchesDoc.md`](./docs/PatchesDoc.md))
 
-- **Local State Management:** Maintains the _committed_ state (last known server state), sending changes (awaiting server confirmation), and pending changes (local edits not yet sent).
-- **Optimistic Updates:** Applies local changes immediately for a responsive UI.
-- **Synchronization:** Implements the client-side OT logic:
-  - Sends pending changes to the server (`getUpdatesForServer`).
-  - Applies server confirmations (`applyServerConfirmation`).
-  - Applies external server updates from other clients (`applyExternalServerUpdate`), rebasing local changes as needed.
-- **Event Emitters:** Provides hooks (`onUpdate`, `onChange`, etc.) to react to state changes.
+This represents a single collaborative document. You don't create this directly; use `patches.openDoc(docId)` instead.
 
-See [`docs/PatchesDoc.md`](./docs/PatchesDoc.md) for detailed usage and examples.
+- **Local State Management:** Tracks committed state, sending changes, and pending changes
+- **Optimistic Updates:** Applies local changes immediately for snappy UIs
+- **Synchronization:** Handles client-side OT magic:
+  - Sends pending changes to server
+  - Applies server confirmations
+  - Applies external updates, rebasing local changes as needed
+- **Event Emitters:** Hooks like `onUpdate` and `onChange` to react to state changes
 
 ### PatchesServer
 
-(`PatchesServer` Documentation: [`docs/PatchesServer.md`](./docs/PatchesServer.md))
+([`docs/PatchesServer.md`](./docs/PatchesServer.md))
 
-The heart of the server-side logic. See [`docs/operational-transformation.md#patchserver`](./docs/operational-transformation.md#patchserver) for its role in the OT flow.
+The heart of server-side logic!
 
-- **Receives Changes:** Handles incoming `Change` objects from clients.
-- **Transformation:** Transforms client changes against concurrent server changes using the OT algorithm.
-- **Applies Changes:** Applies the final transformed changes to the authoritative document state.
-- **Versioning:** Creates version snapshots based on time-based sessions or explicit triggers (useful for history and offline support).
-- **Persistence:** Uses a `PatchesStoreBackend` implementation to save/load document state, changes, and versions.
-
-See [`docs/PatchesServer.md`](./docs/PatchesServer.md) for detailed usage and examples.
+- **Receives Changes:** Handles incoming `Change` objects from clients
+- **Transformation:** Transforms client changes against concurrent server changes
+- **Applies Changes:** Applies transformed changes to the authoritative document state
+- **Versioning:** Creates version snapshots based on user sessions
+- **Persistence:** Uses `PatchesStoreBackend` to save/load document state and history
 
 ### PatchesHistoryManager
 
-(`PatchesHistoryManager` Documentation: [`docs/PatchesHistoryManager.md`](./docs/PatchesHistoryManager.md))
-
-Provides an API for querying the history ([`VersionMetadata`](./docs/types.ts)) of a document.
+([`docs/PatchesHistoryManager.md`](./docs/PatchesHistoryManager.md))
 
-- **List Versions:** Retrieve metadata about saved document versions (snapshots).
-- **Get Version State/Changes:** Load the full state or the specific changes associated with a past version.
-- **List Server Changes:** Query the raw sequence of committed server changes based on revision numbers.
+Helps you query document history.
 
-See [`docs/PatchesHistoryManager.md`](./docs/PatchesHistoryManager.md) for detailed usage and examples.
+- **List Versions:** Get metadata about saved document versions
+- **Get Version State/Changes:** Load the full state or specific changes for a version
+- **List Server Changes:** Query raw server changes by revision numbers
 
 ### PatchesBranchManager
 
-(`PatchesBranchManager` Documentation: [`docs/PatchesBranchManager.md`](./docs/PatchesBranchManager.md))
+([`docs/PatchesBranchManager.md`](./docs/PatchesBranchManager.md))
 
-Manages branching ([`Branch`](./docs/types.ts)) and merging workflows.
+Manages branching and merging workflows.
 
-- **Create Branch:** Creates a new document branching off from a source document at a specific revision.
-- **List Branches:** Retrieves information about existing branches.
-- **Merge Branch:** Merges the changes made on a branch back into its source document (requires OT on the server to handle conflicts).
-- **Close Branch:** Marks a branch as closed, merged, or abandoned.
-
-See [`docs/PatchesBranchManager.md`](./docs/PatchesBranchManager.md) for detailed usage and examples.
+- **Create Branch:** Makes a new document branching off from a source doc
+- **List Branches:** Shows info about existing branches
+- **Merge Branch:** Merges changes back into the source document
+- **Close Branch:** Marks a branch as closed, merged, or abandoned
 
 ### Backend Store
 
-([`PatchesStoreBackend` / `BranchingStoreBackend`](./docs/operational-transformation.md#backend-store-interface) Documentation: [`docs/operational-transformation.md#backend-store-interface`](./docs/operational-transformation.md#backend-store-interface))
-
-This isn't a specific class provided by the library, but rather an _interface_ (`PatchesStoreBackend` and `BranchingStoreBackend`) that you need to implement. This interface defines how the `PatchesServer`, `PatchesHistoryManager`, and `PatchesBranchManager` interact with your chosen persistence layer (e.g., a database, file system, in-memory store).
+([`docs/operational-transformation.md#backend-store-interface`](./docs/operational-transformation.md#backend-store-interface))
 
-You are responsible for providing an implementation that fulfills the methods defined in the interface (e.g., `getLatestRevision`, `saveChange`, `listVersions`, `createBranch`).
+This is an interface you implement, not a specific class. It defines how the server components interact with your chosen storage (database, file system, memory).
 
-See [`docs/operational-transformation.md#backend-store-interface`](./docs/operational-transformation.md#backend-store-interface) for the interface definition.
+You're responsible for making it work with your backend!
 
-## Transport & Networking
+### Transport & Networking
 
-Patches provides flexible networking options for real-time collaboration:
+Patches gives you flexible networking options:
 
-- **WebSocket Transport:** For most applications, use the high-level [`PatchesWebSocket`](./docs/websocket.md) class to connect to a central Patches server. This handles document updates, awareness, and versioning over a persistent WebSocket connection.
-- **WebRTC Transport:** For peer-to-peer scenarios, use [`WebRTCTransport`](./docs/operational-transformation.md#webrtc) and [`WebRTCAwareness`](./docs/awareness.md) for direct client-to-client communication and awareness.
-
-See [WebSocket Transport](./docs/websocket.md) and [Awareness](./docs/awareness.md) for detailed usage and examples.
+- **WebSocket Transport:** For most apps, use [`PatchesWebSocket`](./docs/websocket.md) to connect to a central server
+- **WebRTC Transport:** For peer-to-peer, use [`WebRTCTransport`](./docs/operational-transformation.md#webrtc) and [`WebRTCAwareness`](./docs/awareness.md)
 
 **When to use which?**
 
-- Use WebSocket for most collaborative apps with a central server.
-- Use WebRTC for peer-to-peer or hybrid topologies, or to reduce server load for awareness/presence.
-
----
+- WebSocket for most collaborative apps with a central server
+- WebRTC for peer-to-peer or to reduce server load for awareness/presence
 
-## Awareness (Presence, Cursors, etc.)
+### Awareness (Presence, Cursors, etc.)
 
-"Awareness" lets you show who is online, where their cursor is, and more. Patches supports awareness over both WebSocket (server-mediated) and WebRTC (peer-to-peer). You can use awareness to build collaborative cursors, user lists, and more.
+"Awareness" lets you show who's online, where their cursor is, and more. Patches supports awareness over both WebSocket and WebRTC.
 
-See [Awareness documentation](./docs/awareness.md) for how to use awareness features in your app.
+Check the [Awareness documentation](./docs/awareness.md) for how to build collaborative cursors, user lists, and other cool features.
 
 ## Basic Workflow
 
-### Client-Side (`Patches` and `PatchesDoc`)
+### Client-Side
 
-1.  **Initialize `Patches`:** Create an instance with a store (e.g., `InMemoryStore`).
-2.  **Track and Open a Document:** Use `patches.trackDocs([docId])` and `patches.openDoc(docId)` to get a `PatchesDoc` instance.
-3.  **Subscribe to Updates:** Use `doc.onUpdate`.
-4.  **Make Local Changes:** Use `doc.change()`.
-5.  **Sync Changes:** If using `PatchesSync`, changes are synced automatically. Otherwise, use the store or your own sync logic.
+1. **Initialize `Patches`** with a store
+2. **Track and Open a Document** with `patches.trackDocs([docId])` and `patches.openDoc(docId)`
+3. **Subscribe to Updates** with `doc.onUpdate`
+4. **Make Local Changes** with `doc.change()`
+5. **Sync Changes** automatically with `PatchesSync` or manually with your own logic
 
-### Server-Side (`PatchesServer`)
+### Server-Side
 
-1.  **Initialize `PatchesServer`:** Create an instance. See [`docs/PatchesServer.md#initialization`](./docs/PatchesServer.md#initialization).
-2.  **Receive Client Changes:** Use [`server.receiveChanges()`](./docs/PatchesServer.md#core-method-receivechanges).
-3.  **Handle History/Branching:** Use [`PatchesHistoryManager`](./docs/PatchesHistoryManager.md) and [`PatchesBranchManager`](./docs/PatchesBranchManager.md).
+1. **Initialize `PatchesServer`** with your backend store
+2. **Receive Client Changes** with `server.receiveChanges()`
+3. **Handle History/Branching** with `PatchesHistoryManager` and `PatchesBranchManager`
 
 ## Examples
 
-_(Note: These are simplified examples. Real-world implementations require proper error handling, network communication, authentication, and backend setup.)_
-
 ### Simple Client Setup
 
 ```typescript
 import { Patches } from '@dabble/patches';
-import { InMemoryStore } from '@dabble/patches/persist/InMemoryStore';
+import { InMemoryStore } from '@dabble/patches/persist';
 
 interface MyDoc {
   text: string;
@@ -332,7 +316,7 @@ doc.change(draft => {
   draft.text = 'Hello';
   draft.count = 0;
 });
-// If using PatchesSync, changes are synced automatically.
+// With PatchesSync, changes sync automatically
 ```
 
 ### Simple Server Setup
@@ -344,118 +328,13 @@ import {
   PatchesStoreBackend,
   Change,
   VersionMetadata, //... other types
-} from '@dabble/patches';
+} from '@dabble/patches/server';
 
-// --- Basic In-Memory Store (Replace with a real backend!) ---
+// --- Basic In-Memory Store (Use a real database!) ---
 class InMemoryStore implements PatchesStoreBackend {
-  private docs: Map<string, { state: any; rev: number; changes: Change[]; versions: VersionMetadata[] }> = new Map();
+  private docs = new Map<string, { state: any; rev: number; changes: Change[]; versions: VersionMetadata[] }>();
 
-  async getLatestRevision(docId: string): Promise<number> {
-    return this.docs.get(docId)?.rev ?? 0;
-  }
-  async getLatestState(docId: string): Promise<any | undefined> {
-    const doc = this.docs.get(docId);
-    // Return a deep copy to prevent accidental mutation
-    return doc ? JSON.parse(JSON.stringify(doc.state)) : undefined;
-  }
-  async getStateAtRevision(docId: string, rev: number): Promise<any | undefined> {
-    // IMPORTANT: In-memory store cannot easily reconstruct past states without snapshots.
-    // A real implementation would replay changes or load version snapshots.
-    // This basic version only returns the latest state if rev matches.
-    const doc = this.docs.get(docId);
-    if (doc && doc.rev === rev) {
-      return JSON.parse(JSON.stringify(doc.state)); // Return copy
-    }
-    // Try finding a version snapshot matching the revision
-    const version = doc?.versions.find(v => v.endDate === rev); // Approximation!
-    if (version) {
-      return JSON.parse(JSON.stringify(version.state));
-    }
-    // Fallback: Cannot reconstruct this revision
-    if (rev === 0 && !doc) return {}; // Initial empty state at rev 0
-    console.warn(
-      `In-Memory Store: Cannot get state at revision ${rev} for doc ${docId}. Returning latest or undefined.`
-    );
-    return doc ? JSON.parse(JSON.stringify(doc.state)) : undefined; // Or throw error
-  }
-  async saveChange(docId: string, change: Change): Promise<void> {
-    let doc = this.docs.get(docId);
-    if (!doc) {
-      doc = { state: {}, rev: 0, changes: [], versions: [] };
-      this.docs.set(docId, doc);
-    }
-    // Apply change to get new state (use library's apply function)
-    const { applyChanges } = await import('@dabble/patches'); // Assuming exported
-    doc.state = applyChanges(doc.state, [change]);
-    doc.rev = change.rev;
-    doc.changes.push(change); // Store history of changes
-    console.log(`[Store] Saved change rev ${change.rev} for doc ${docId}. New state:`, doc.state);
-  }
-  async listChanges(docId: string, options: any): Promise<Change[]> {
-    const doc = this.docs.get(docId);
-    if (!doc) return [];
-    let changes = doc.changes;
-    if (options.startAfterRev !== undefined) {
-      changes = changes.filter(c => c.rev > options.startAfterRev!);
-    }
-    // Add other filter/limit/sort logic here based on options
-    changes.sort((a, b) => a.rev - b.rev); // Ensure ascending order
-    if (options.limit) {
-      changes = changes.slice(0, options.limit);
-    }
-    return changes;
-  }
-  async saveVersion(docId: string, version: VersionMetadata): Promise<void> {
-    const doc = this.docs.get(docId);
-    if (!doc) {
-      // This case is less likely if saveChange created the doc, but handle defensively
-      console.warn(`[Store] Cannot save version for non-existent doc ${docId}`);
-      return;
-    }
-    // Simple: just add to list. A real store might index/optimize.
-    doc.versions.push(version);
-    console.log(`[Store] Saved version ${version.id} (${version.origin}) for doc ${docId}.`);
-  }
-  async listVersions(docId: string, options: any): Promise<VersionMetadata[]> {
-    const doc = this.docs.get(docId);
-    if (!doc) return [];
-    let versions = doc.versions;
-    // Apply filtering/sorting based on options (simplified)
-    if (options.origin) {
-      versions = versions.filter(v => v.origin === options.origin);
-    }
-    if (options.groupId) {
-      versions = versions.filter(v => v.groupId === options.groupId);
-    }
-    // ... other filters ...
-    versions.sort((a, b) => (options.reverse ? b.startDate - a.startDate : a.startDate - b.startDate));
-    if (options.limit) {
-      versions = versions.slice(0, options.limit);
-    }
-    return versions;
-  }
-  async loadVersionMetadata(docId: string, versionId: string): Promise<VersionMetadata | null> {
-    const doc = this.docs.get(docId);
-    return doc?.versions.find(v => v.id === versionId) ?? null;
-  }
-  async loadVersionState(docId: string, versionId: string): Promise<any | undefined> {
-    const meta = await this.loadVersionMetadata(docId, versionId);
-    return meta ? JSON.parse(JSON.stringify(meta.state)) : undefined; // Return copy
-  }
-  async loadVersionChanges(docId: string, versionId: string): Promise<Change[]> {
-    const meta = await this.loadVersionMetadata(docId, versionId);
-    return meta ? meta.changes : [];
-  }
-  async getLatestVersionMetadata(docId: string): Promise<VersionMetadata | null> {
-    const doc = this.docs.get(docId);
-    if (!doc || doc.versions.length === 0) return null;
-    // Find version with the latest endDate
-    return doc.versions.reduce(
-      (latest, current) => (!latest || current.endDate > latest.endDate ? current : latest),
-      null as VersionMetadata | null
-    );
-  }
-  // Implement BranchingStoreBackend methods if needed...
+  // Implementation details omitted for brevity...
 }
 
 // --- Server Setup ---
@@ -464,59 +343,8 @@ const server = new PatchesServer(store);
 const app = express();
 app.use(express.json());
 
-// --- Mock Broadcast (Replace with WebSocket/SSE etc.) ---
-const clients = new Map<string, Set<any>>(); // docId -> Set<client connections>
-function broadcastChanges(docId: string, changes: Change[], senderClientId: string | null) {
-  console.log(`Broadcasting changes for ${docId} to other clients:`, changes);
-  // Implement actual broadcast logic here (e.g., WebSockets)
-  // clients.get(docId)?.forEach(client => {
-  //     if (client.id !== senderClientId) { // Don't send back to sender
-  //         client.send(JSON.stringify({ type: 'changes', docId, changes }));
-  //     }
-  // });
-}
-
-// --- API Endpoint ---
-app.post('/docs/:docId/changes', async (req, res) => {
-  const docId = req.params.docId;
-  const clientChanges: Change[] = req.body.changes;
-  const clientId = req.headers['x-client-id'] as string | null; // Example client ID header
-
-  // Basic validation
-  if (!Array.isArray(clientChanges)) {
-    return res.status(400).json({ error: 'Invalid request: expected changes array.' });
-  }
-
-  console.log(`Received ${clientChanges.length} changes for doc ${docId} from client ${clientId || 'unknown'}`);
-
-  try {
-    const committedChanges = await server.receiveChanges(docId, clientChanges);
-    console.log(`Committed ${committedChanges.length} changes for doc ${docId}, rev: ${committedChanges[0]?.rev}`);
-    res.json(committedChanges); // Send confirmation back to sender
-
-    // Broadcast to others if changes were made
-    if (committedChanges.length > 0) {
-      broadcastChanges(docId, committedChanges, clientId);
-    }
-  } catch (error: any) {
-    console.error(`Error processing changes for doc ${docId}:`, error);
-    // Use 409 Conflict for revision mismatches, 500 for others
-    const statusCode = error.message.includes('out of sync') ? 409 : 500;
-    res.status(statusCode).json({ error: error.message });
-  }
-});
-
-// Endpoint to get latest state (for new clients)
-app.get('/docs/:docId', async (req, res) => {
-  const docId = req.params.docId;
-  try {
-    const { state, rev } = await server.getLatestDocumentStateAndRev(docId);
-    res.json({ state: state ?? {}, rev }); // Provide empty object if state is undefined
-  } catch (error: any) {
-    console.error(`Error fetching state for doc ${docId}:`, error);
-    res.status(500).json({ error: 'Failed to fetch document state.' });
-  }
-});
+// API endpoints for changes and state...
+// (see full example in code)
 
 const PORT = 3000;
 app.listen(PORT, () => {
@@ -540,7 +368,7 @@ See [`Operational Transformation > Operation Handlers`](./docs/operational-trans
 
 ## JSON Patch (Legacy)
 
-See [`docs/json-patch.md`](./docs/json-patch.md) for documentation on the JSON Patch features, including [`JSONPatch`](./docs/json-patch.md#jsonpatch-class) and [`createJSONPatch`](./docs/json-patch.md#createjsonpatch-helper).
+For legacy JSON Patch features, see [`docs/json-patch.md`](./docs/json-patch.md).
 
 ## Contributing
 

package/dist/server/PatchesBranchManager.d.ts

@@ -1,5 +1,6 @@
-import type { Branch, BranchingStoreBackend, BranchStatus, Change } from '../types.js';
+import type { Branch, BranchStatus, Change } from '../types.js';
 import type { PatchesServer } from './PatchesServer.js';
+import type { BranchingStoreBackend } from './types.js';
 /**
  * Helps manage branches for a document. A branch is a document that is branched from another document. Its first
  * version will be the point-in-time of the original document at the time of the branch. Branches allow for parallel

package/dist/server/PatchesHistoryManager.d.ts

@@ -1,40 +1,44 @@
-import type { Change, ListVersionsOptions, PatchesStoreBackend, VersionMetadata } from '../types.js';
+import type { Change, ListVersionsOptions, VersionMetadata } from '../types.js';
+import type { PatchesStoreBackend } from './types.js';
 /**
  * Helps retrieve historical information (versions, changes) for a document
  * using the new versioning model based on IDs and metadata.
  */
 export declare class PatchesHistoryManager {
-    private readonly docId;
     private readonly store;
-    constructor(docId: string, store: PatchesStoreBackend);
+    constructor(store: PatchesStoreBackend);
     /**
      * Lists version metadata for the document, supporting various filters.
+     * @param docId - The ID of the document.
      * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
      * @returns A list of version metadata objects.
      */
-    listVersions(options?: ListVersionsOptions): Promise<VersionMetadata[]>;
+    listVersions(docId: string, options?: ListVersionsOptions): Promise<VersionMetadata[]>;
     /**
      * Loads the full document state snapshot for a specific version by its ID.
+     * @param docId - The ID of the document.
      * @param versionId - The unique ID of the version.
      * @returns The document state at that version.
      * @throws Error if the version ID is not found or state loading fails.
      */
-    getStateAtVersion(versionId: string): Promise<any>;
+    getStateAtVersion(docId: string, versionId: string): Promise<any>;
     /**
      * Loads the list of original client changes that were included in a specific version.
      * Useful for replaying/scrubbing through the operations within an offline or online session.
+     * @param docId - The ID of the document.
      * @param versionId - The unique ID of the version.
      * @returns An array of Change objects.
      * @throws Error if the version ID is not found or change loading fails.
      */
-    getChangesForVersion(versionId: string): Promise<Change[]>;
+    getChangesForVersion(docId: string, versionId: string): Promise<Change[]>;
     /**
      * Lists committed server changes for the document, typically used for server-side processing
      * or deep history analysis based on raw revisions.
+     * @param docId - The ID of the document.
      * @param options - Options like start/end revision, limit.
      * @returns The list of committed Change objects.
      */
-    listServerChanges(options?: {
+    listServerChanges(docId: string, options?: {
         limit?: number;
         startAfterRev?: number;
         endBeforeRev?: number;

package/dist/server/PatchesHistoryManager.js

@@ -3,57 +3,60 @@
  * using the new versioning model based on IDs and metadata.
  */
 export class PatchesHistoryManager {
-    constructor(docId, store) {
-        this.docId = docId;
+    constructor(store) {
         this.store = store;
     }
     /**
      * Lists version metadata for the document, supporting various filters.
+     * @param docId - The ID of the document.
      * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
      * @returns A list of version metadata objects.
      */
-    async listVersions(options = {}) {
-        return await this.store.listVersions(this.docId, options);
+    async listVersions(docId, options = {}) {
+        return await this.store.listVersions(docId, options);
     }
     /**
      * Loads the full document state snapshot for a specific version by its ID.
+     * @param docId - The ID of the document.
      * @param versionId - The unique ID of the version.
      * @returns The document state at that version.
      * @throws Error if the version ID is not found or state loading fails.
      */
-    async getStateAtVersion(versionId) {
+    async getStateAtVersion(docId, versionId) {
         try {
-            return await this.store.loadVersionState(this.docId, versionId);
+            return await this.store.loadVersionState(docId, versionId);
         }
         catch (error) {
-            console.error(`Failed to load state for version ${versionId} of doc ${this.docId}.`, error);
+            console.error(`Failed to load state for version ${versionId} of doc ${docId}.`, error);
             throw new Error(`Could not load state for version ${versionId}.`);
         }
     }
     /**
      * Loads the list of original client changes that were included in a specific version.
      * Useful for replaying/scrubbing through the operations within an offline or online session.
+     * @param docId - The ID of the document.
      * @param versionId - The unique ID of the version.
      * @returns An array of Change objects.
      * @throws Error if the version ID is not found or change loading fails.
      */
-    async getChangesForVersion(versionId) {
+    async getChangesForVersion(docId, versionId) {
         try {
-            return await this.store.loadVersionChanges(this.docId, versionId);
+            return await this.store.loadVersionChanges(docId, versionId);
         }
         catch (error) {
-            console.error(`Failed to load changes for version ${versionId} of doc ${this.docId}.`, error);
+            console.error(`Failed to load changes for version ${versionId} of doc ${docId}.`, error);
             throw new Error(`Could not load changes for version ${versionId}.`);
         }
     }
     /**
      * Lists committed server changes for the document, typically used for server-side processing
      * or deep history analysis based on raw revisions.
+     * @param docId - The ID of the document.
      * @param options - Options like start/end revision, limit.
      * @returns The list of committed Change objects.
      */
-    async listServerChanges(options = {}) {
+    async listServerChanges(docId, options = {}) {
         // Added return type
-        return await this.store.listChanges(this.docId, options);
+        return await this.store.listChanges(docId, options);
     }
 }

package/dist/server/PatchesServer.d.ts

@@ -1,4 +1,5 @@
-import type { Change, ListVersionsOptions, PatchesSnapshot, PatchesState, PatchesStoreBackend, VersionMetadata } from '../types.js';
+import type { Change, ListVersionsOptions, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
+import type { PatchesStoreBackend } from './types.js';
 /**
  * Configuration options for the PatchesServer.
  */

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
 export { PatchesBranchManager } from './PatchesBranchManager';
 export { PatchesHistoryManager } from './PatchesHistoryManager';
 export { PatchesServer } from './PatchesServer';
+export type { BranchingStoreBackend, PatchesStoreBackend } from './types';

package/dist/server/types.d.ts

@@ -0,0 +1,48 @@
+import type { Branch, Change, ListChangesOptions, ListVersionsOptions, VersionMetadata } from '../types';
+/**
+ * Interface for a backend storage system for patch synchronization.
+ * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
+ */
+export interface PatchesStoreBackend {
+    /** Adds a subscription for a client to one or more documents. */
+    addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
+    /** Removes a subscription for a client from one or more documents. */
+    removeSubscription(clientId: string, docIds: string[]): Promise<string[]>;
+    /** Saves a batch of committed server changes. */
+    saveChanges(docId: string, changes: Change[]): Promise<void>;
+    /** Lists committed server changes based on revision numbers. */
+    listChanges(docId: string, options: ListChangesOptions): Promise<Change[]>;
+    /**
+     * Saves version metadata, its state snapshot, and the original changes that constitute it.
+     * State and changes are stored separately from the core metadata.
+     */
+    createVersion(docId: string, metadata: VersionMetadata, state: any, changes: Change[]): Promise<void>;
+    /** Update a version's metadata. */
+    updateVersion(docId: string, versionId: string, metadata: Partial<VersionMetadata>): Promise<void>;
+    /** Lists version metadata based on filtering/sorting options. */
+    listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
+    /** Loads the state snapshot for a specific version ID. */
+    loadVersionState(docId: string, versionId: string): Promise<any | undefined>;
+    /** Loads the original Change objects associated with a specific version ID. */
+    loadVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    /** Deletes a document. */
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Extends PatchesStoreBackend with methods specifically for managing branches.
+ */
+export interface BranchingStoreBackend extends PatchesStoreBackend {
+    /** Lists metadata records for branches originating from a document. */
+    listBranches(docId: string): 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 specific fields (status, name, metadata) of an existing branch record. */
+    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name' | 'metadata'>>): Promise<void>;
+    /**
+     * @deprecated Use updateBranch with status instead.
+     * Marks a branch as closed. Implementations might handle this via updateBranch.
+     */
+    closeBranch(branchId: string): Promise<void>;
+}

package/dist/server/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -111,53 +111,6 @@ export interface ListVersionsOptions {
     /** Filter by the group ID (branch ID or offline batch ID). */
     groupId?: string;
 }
-/**
- * Interface for a backend storage system for patch synchronization.
- * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
- */
-export interface PatchesStoreBackend {
-    /** Adds a subscription for a client to one or more documents. */
-    addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
-    /** Removes a subscription for a client from one or more documents. */
-    removeSubscription(clientId: string, docIds: string[]): Promise<string[]>;
-    /** Saves a batch of committed server changes. */
-    saveChanges(docId: string, changes: Change[]): Promise<void>;
-    /** Lists committed server changes based on revision numbers. */
-    listChanges(docId: string, options: ListChangesOptions): Promise<Change[]>;
-    /**
-     * Saves version metadata, its state snapshot, and the original changes that constitute it.
-     * State and changes are stored separately from the core metadata.
-     */
-    createVersion(docId: string, metadata: VersionMetadata, state: any, changes: Change[]): Promise<void>;
-    /** Update a version's metadata. */
-    updateVersion(docId: string, versionId: string, metadata: Partial<VersionMetadata>): Promise<void>;
-    /** Lists version metadata based on filtering/sorting options. */
-    listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
-    /** Loads the state snapshot for a specific version ID. */
-    loadVersionState(docId: string, versionId: string): Promise<any | undefined>;
-    /** Loads the original Change objects associated with a specific version ID. */
-    loadVersionChanges(docId: string, versionId: string): Promise<Change[]>;
-    /** Deletes a document. */
-    deleteDoc(docId: string): Promise<void>;
-}
-/**
- * Extends PatchesStoreBackend with methods specifically for managing branches.
- */
-export interface BranchingStoreBackend extends PatchesStoreBackend {
-    /** Lists metadata records for branches originating from a document. */
-    listBranches(docId: string): 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 specific fields (status, name, metadata) of an existing branch record. */
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name' | 'metadata'>>): Promise<void>;
-    /**
-     * @deprecated Use updateBranch with status instead.
-     * Marks a branch as closed. Implementations might handle this via updateBranch.
-     */
-    closeBranch(branchId: string): Promise<void>;
-}
 export interface Deferred<T = void> {
     promise: Promise<T>;
     resolve: (value: T) => void;

package/package.json

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