@adonis-agora/collaboration 0.19.0 → 0.19.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @adonis-agora/collaboration
 
+## 0.19.2
+
+### Patch Changes
+
+- [#138](https://github.com/DavideCarvalho/adonis-agora-collaboration/pull/138) [`894997d`](https://github.com/DavideCarvalho/adonis-agora-collaboration/commit/894997d002cd20a9d9fd19107812005c77eb24a1) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Load heavy engine dependencies on first use instead of at import time. `@automerge/automerge` now loads when an automerge driver first opens a document, `@hocuspocus/transformer` (Tiptap + ProseMirror) when a document's text or a diff is first computed, and `@hocuspocus/server` when the yjs driver first attaches to the HTTP server. Importing the package root or its provider drops from ~10.5 MB to ~3.9 MB of heap (and ~100 ms of module evaluation) in every process that never opens a document — ace commands, queue workers, and web pods until the first collaboration request. No API change.
+
+## 0.19.1
+
+### Patch Changes
+
+- [#135](https://github.com/DavideCarvalho/adonis-agora-collaboration/pull/135) [`718d1cc`](https://github.com/DavideCarvalho/adonis-agora-collaboration/commit/718d1cce9bfd30f2c1f3bc77603a9bd6d230915e) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Automerge: clients and server exchange change chunks instead of whole documents. `useAutomergeDoc` asks for them with `?sync=changes`; the server acknowledges with a text frame and from then on both sides send only the changes the other lacks. Sockets that do not ask (older clients) keep sending and receiving whole documents, and a new client against an older server keeps sending whole documents, so mixed versions keep working in the same room. The server applies both shapes with `A.loadIncremental` and never forwards a payload that adds nothing.
+  
+  Automerge rooms are now saved and dropped from memory when their last client leaves, `close()` writes pending saves instead of cancelling them (and no longer hangs while sockets are open), and a document edited without pause is saved at least every 10 seconds.
+  
+  A socket whose presence join fails, or that closes while the join is in flight, is now taken out of its room (which can then be dropped) and its possibly half-written roster entry is removed, unless the user still has another tab on the document.
+
+- [#135](https://github.com/DavideCarvalho/adonis-agora-collaboration/pull/135) [`718d1cc`](https://github.com/DavideCarvalho/adonis-agora-collaboration/commit/718d1cce9bfd30f2c1f3bc77603a9bd6d230915e) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Presence: each roster entry now expires on its own 60-second TTL, and every live instance re-stamps the members it holds every 20 seconds, so the users of a crashed instance drop out even on a document other instances keep busy. The stored member format is unchanged. The Yjs driver no longer scans every open socket on each disconnect, and the Automerge driver no longer scans the room's sockets when one closes: both keep a socket count per user per document.
+
 ## 0.19.0
 
 ### Minor Changes

package/dist/src/drivers/automerge/automerge_driver.d.ts

@@ -1,12 +1,16 @@
 import type { CollaborationDriver, SelfHostedDriverOptions } from '../../driver.js';
 import type { CollabDiffSummary, CollabVersion, ListPageOptions } from '../../types.js';
+/** Text frame confirming that this socket exchanges change chunks. */
+export declare const CHANGES_ACK = "automerge-sync:changes";
 export declare class AutomergeDriver implements CollaborationDriver {
     readonly engine = "automerge";
     private rooms;
     private wss?;
     private readonly options;
     private readonly storage;
-    private persistTimers;
+    private pendingSaves;
+    /** Saves being written, by document name; a room is not dropped under one. */
+    private savesInFlight;
     /**
      * Rooms being opened, by document name.
      *
@@ -17,6 +21,14 @@ export declare class AutomergeDriver implements CollaborationDriver {
      * duplicated content, so the window has to close.
      */
     private roomLoads;
+    /**
+     * `@automerge/automerge`, loaded by the first call that opens a room or reads
+     * a version (see `lazy_deps.ts`). Every synchronous use runs on a room, and a
+     * room only exists after `openRoom` awaited the module, so it is set there.
+     */
+    private am;
+    /** Loads Automerge (once per process) and makes it available as `this.am`. */
+    private automerge;
     constructor(options: SelfHostedDriverOptions);
     private loadRoom;
     private openRoom;
@@ -32,10 +44,46 @@ export declare class AutomergeDriver implements CollaborationDriver {
      * than a document worth guessing at.
      */
     private seedDocument;
+    /**
+     * Sends everything the room gained since `since` to every client but the
+     * sender: the change chunk to sockets that speak chunks, a whole document
+     * (`wholeDoc`, else `A.save` of the room) to the rest. Each shape is
+     * encoded at most once per call.
+     */
     private broadcast;
+    /** Runs `fn` on the room, dropping it afterwards if nobody else uses it. */
+    private withRoom;
+    /**
+     * Writes the room's pending save and drops it from memory once nothing
+     * uses it: no client, no driver call, no save waiting or being written.
+     * A client that joins meanwhile finds the same room in the map.
+     */
+    private releaseRoom;
     attach(server: import('node:http').Server): Promise<void>;
+    /**
+     * Takes `ws` out of the room — and, when `userId` is given, out of that
+     * user's socket count, leaving the roster with their last one. Safe to call
+     * twice for one socket.
+     */
+    private removeSocket;
+    /** Removes `userId` from the roster unless another of their sockets is still in the room. */
+    private leaveIfLast;
+    /**
+     * Applies a client's whole document or change chunk and forwards only what
+     * was new to the room. A payload that adds nothing — a duplicate, or bytes
+     * that are not Automerge at all — is neither forwarded nor saved.
+     */
     private handleClientMessage;
-    private persistDebounced;
+    /**
+     * Debounced save: each edit postpones it by `debounce`, but never past
+     * {@link MAX_PERSIST_WAIT_MS} (or `debounce`, if longer) after the first
+     * unsaved edit, so a document edited without pause is still written.
+     */
+    private schedulePersist;
+    /** Writes the pending save of `docName` now, if there is one. */
+    private persistNow;
+    /** Saves `state`, tracked so the room is not dropped while it is written. */
+    private save;
     getDocumentState(docName: string): Promise<Uint8Array>;
     getDocumentText(docName: string): Promise<string>;
     /** Versions = markers over the native history (heads hash). */
@@ -48,6 +96,7 @@ export declare class AutomergeDriver implements CollaborationDriver {
      * that leaves no entry in it is a restore nobody can undo.
      */
     restoreVersion(docName: string, versionId: string, restoredBy: string | null): Promise<void>;
+    private restoreRoom;
     /** Binary state stored for a version (`A.save` of the doc at that point). */
     getVersionState(docName: string, versionId: string): Promise<Uint8Array>;
     diffVersions(docName: string, aId: string, bId: string): Promise<CollabDiffSummary>;

package/dist/src/drivers/automerge/automerge_driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automerge_driver.d.ts","sourceRoot":"","sources":["../../../../src/drivers/automerge/automerge_driver.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,OAAO,KAAK,EACV,iBAAiB,EAGjB,aAAa,EACb,eAAe,EAChB,MAAM,gBAAgB,CAAC;AA+BxB,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,QAAQ,CAAC,MAAM,eAAe;IAE9B,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,GAAG,CAAC,CAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAAoD;IACzE;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS,CAAoC;IAErD,YAAY,OAAO,EAAE,uBAAuB,EAG3C;IAED,OAAO,CAAC,QAAQ;YAYF,QAAQ;IAWtB;;;;;;;;;;OAUG;YAEW,YAAY;IA0C1B,OAAO,CAAC,SAAS;IAQX,MAAM,CAAC,MAAM,EAAE,OAAO,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2G9D;YAGa,mBAAmB;IAkBjC,OAAO,CAAC,gBAAgB;IAwBlB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAG3D;IAEK,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAItD;IAED,+DAA+D;IACzD,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,OAAO,CAAC,aAAa,CAAC,CAcxB;IAEK,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEpF;IAED;;;;;OAKG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,IAAI,CAAC,CAgCf;IAED,6EAA6E;IACvE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAI7E;IAEK,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAYxF;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAS3B;CACF"}
+{"version":3,"file":"automerge_driver.d.ts","sourceRoot":"","sources":["../../../../src/drivers/automerge/automerge_driver.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,OAAO,KAAK,EACV,iBAAiB,EAGjB,aAAa,EACb,eAAe,EAChB,MAAM,gBAAgB,CAAC;AA4BxB,sEAAsE;AACtE,eAAO,MAAM,WAAW,2BAA2B,CAAC;AAgCpD,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,QAAQ,CAAC,MAAM,eAAe;IAE9B,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,GAAG,CAAC,CAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAkC;IACtD,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAoC;IACzD;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS,CAAoC;IAErD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAmB;IAE7B,8EAA8E;YAChE,SAAS;IAKvB,YAAY,OAAO,EAAE,uBAAuB,EAG3C;IAED,OAAO,CAAC,QAAQ;YAYF,QAAQ;IAiBtB;;;;;;;;;;OAUG;YAEW,YAAY;IA0C1B;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAoBjB,4EAA4E;YAC9D,QAAQ;IAWtB;;;;OAIG;YACW,WAAW;IAQnB,MAAM,CAAC,MAAM,EAAE,OAAO,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsH9D;IAED;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAkBpB,6FAA6F;IAC7F,OAAO,CAAC,WAAW;IAOnB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAcvB,iEAAiE;YACnD,UAAU;IAQxB,6EAA6E;YAC/D,IAAI;IAmBZ,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAE3D;IAEK,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKtD;IAED,+DAA+D;IACzD,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,OAAO,CAAC,aAAa,CAAC,CAexB;IAEK,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEpF;IAED;;;;;OAKG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,IAAI,CAAC,CAOf;YAEa,WAAW;IA0CzB,6EAA6E;IACvE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAI7E;IAEK,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAaxF;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3B;CACF"}

package/dist/src/drivers/automerge/automerge_driver.js

@@ -1,9 +1,8 @@
-import * as A from '@automerge/automerge';
-import { next as ANext } from '@automerge/automerge';
 import { WebSocketServer } from 'ws';
 import { verifySelfHostedToken } from '../../auth/token.js';
 import { reportCollaborationError, reportCollaborationWarning } from '../../observability.js';
 import { createVersionMetadata, restoredFromLabel, seqVersions } from '../../versioning.js';
+import { loadAutomerge } from '../lazy_deps.js';
 import { lineDiff, resolveStorage } from '../shared.js';
 /**
  * Automerge driver.
@@ -14,22 +13,39 @@ import { lineDiff, resolveStorage } from '../shared.js';
  * between versions is already in the doc. `restoreVersion` brings the doc
  * back to the version's heads via a compensating change (non-destructive).
  *
- * Transport: clients speak Automerge's binary protocol
- * (@automerge/automerge-repo-network-websocket on the client). On the server
- * we use an in-memory DocHandle + simple per-room broadcast; for horizontal
- * scaling, updates are re-broadcast via Redis pub/sub (same philosophy as transmit).
+ * Transport: one in-memory doc per room and a per-room broadcast. Every
+ * client gets the whole `A.save(doc)` on connect. After that, a socket opened
+ * with `?sync=changes` is answered with the {@link CHANGES_ACK} text frame and
+ * from then on exchanges change chunks (`A.saveSince`) both ways; any other
+ * socket sends and receives whole saved documents. The server applies both
+ * shapes with `A.loadIncremental`, so one room can hold both kinds of client.
+ *
+ * A room lives while it has clients: when the last one leaves, its pending
+ * save is written and the room is dropped from memory.
  */
+/** Query parameter (and value) a client sets to ask for change chunks. */
+const CHANGES_PARAM = 'sync';
+const CHANGES_PARAM_VALUE = 'changes';
+/** Text frame confirming that this socket exchanges change chunks. */
+export const CHANGES_ACK = 'automerge-sync:changes';
+/** Longest a burst of edits can keep postponing its save. */
+const MAX_PERSIST_WAIT_MS = 10_000;
 /** Connections whose permission denied canWrite — their updates are dropped. */
 const readOnlyClients = new WeakSet();
-/** userId behind each open socket — feeds the presence roster on close. */
-const socketUsers = new WeakMap();
+/** Sockets that exchange change chunks instead of whole documents. */
+const changeClients = new WeakSet();
+function sameHeads(a, b) {
+    return a.length === b.length && a.every((hash, index) => hash === b[index]);
+}
 export class AutomergeDriver {
     engine = 'automerge';
     rooms = new Map();
     wss;
     options;
     storage;
-    persistTimers = new Map();
+    pendingSaves = new Map();
+    /** Saves being written, by document name; a room is not dropped under one. */
+    savesInFlight = new Map();
     /**
      * Rooms being opened, by document name.
      *
@@ -40,6 +56,17 @@ export class AutomergeDriver {
      * duplicated content, so the window has to close.
      */
     roomLoads = new Map();
+    /**
+     * `@automerge/automerge`, loaded by the first call that opens a room or reads
+     * a version (see `lazy_deps.ts`). Every synchronous use runs on a room, and a
+     * room only exists after `openRoom` awaited the module, so it is set there.
+     */
+    am;
+    /** Loads Automerge (once per process) and makes it available as `this.am`. */
+    async automerge() {
+        this.am ??= await loadAutomerge();
+        return this.am;
+    }
     constructor(options) {
         this.options = options;
         this.storage = resolveStorage(options.storage);
@@ -56,11 +83,17 @@ export class AutomergeDriver {
         return opening.finally(() => this.roomLoads.delete(docName));
     }
     async openRoom(docName) {
+        await this.automerge();
         const stored = await this.storage.loadDocument(docName);
         const doc = stored
-            ? A.load(stored.state)
+            ? this.am.load(stored.state)
             : await this.seedDocument(docName);
-        const room = { text: doc, clients: new Set() };
+        const room = {
+            text: doc,
+            clients: new Set(),
+            users: new Map(),
+            holds: 0,
+        };
         this.rooms.set(docName, room);
         return room;
     }
@@ -77,7 +110,7 @@ export class AutomergeDriver {
      */
     // biome-ignore lint/suspicious/noExplicitAny: automerge's typing is unstable between minors
     async seedDocument(docName) {
-        const empty = () => A.from({ content: '' });
+        const empty = () => this.am.from({ content: '' });
         if (!this.options.seedDocument)
             return empty();
         let seed;
@@ -99,7 +132,7 @@ export class AutomergeDriver {
         }
         let doc;
         try {
-            doc = A.load(seed);
+            doc = this.am.load(seed);
         }
         catch (error) {
             reportCollaborationError({ scope: 'storage', operation: 'loadDocument', docName, error });
@@ -115,12 +148,52 @@ export class AutomergeDriver {
         }
         return doc;
     }
-    broadcast(room, payload, sender) {
+    /**
+     * Sends everything the room gained since `since` to every client but the
+     * sender: the change chunk to sockets that speak chunks, a whole document
+     * (`wholeDoc`, else `A.save` of the room) to the rest. Each shape is
+     * encoded at most once per call.
+     */
+    broadcast(room, since, sender, wholeDoc) {
+        let changes;
+        let whole = wholeDoc;
         for (const client of room.clients) {
-            if (client !== sender && client.readyState === 1) {
-                client.send(payload);
+            if (client === sender || client.readyState !== 1)
+                continue;
+            if (changeClients.has(client)) {
+                changes ??= this.am.next.saveSince(room.text, since);
+                client.send(changes);
             }
+            else {
+                whole ??= this.am.save(room.text);
+                client.send(whole);
+            }
+        }
+    }
+    /** Runs `fn` on the room, dropping it afterwards if nobody else uses it. */
+    async withRoom(docName, fn) {
+        const room = await this.loadRoom(docName);
+        room.holds += 1;
+        try {
+            return await fn(room);
+        }
+        finally {
+            room.holds -= 1;
+            void this.releaseRoom(docName, room);
+        }
+    }
+    /**
+     * Writes the room's pending save and drops it from memory once nothing
+     * uses it: no client, no driver call, no save waiting or being written.
+     * A client that joins meanwhile finds the same room in the map.
+     */
+    async releaseRoom(docName, room) {
+        const idle = () => room.clients.size === 0 && room.holds === 0;
+        while (idle() && (this.pendingSaves.has(docName) || this.savesInFlight.has(docName))) {
+            await this.persistNow(docName);
         }
+        if (idle() && this.rooms.get(docName) === room)
+            this.rooms.delete(docName);
     }
     async attach(server) {
         const path = this.options.path ?? '/collaboration';
@@ -185,102 +258,176 @@ export class AutomergeDriver {
                     ws.close(4003, 'no access');
                     return;
                 }
+                let room;
                 try {
-                    const room = await this.loadRoom(docName);
+                    room = await this.loadRoom(docName);
+                    const joinedRoom = room;
                     room.clients.add(ws);
                     if (!permission.canWrite)
                         readOnlyClients.add(ws);
+                    const sendsChanges = url.searchParams.get(CHANGES_PARAM) === CHANGES_PARAM_VALUE;
+                    if (sendsChanges)
+                        changeClients.add(ws);
+                    // Registered before the join, so a socket that closes while the join
+                    // is in flight still leaves the room.
+                    let joined = false;
+                    ws.on('close', () => {
+                        this.removeSocket(docName, joinedRoom, ws, joined ? ctx.userId : undefined);
+                    });
                     await this.options.presence?.join(docName, {
                         userId: ctx.userId,
                         ...(ctx.user?.name ? { name: ctx.user.name } : {}),
                     });
-                    // Sends the full state to the new client.
-                    ws.send(A.save(room.text));
+                    if (ws.readyState !== ws.OPEN) {
+                        // Closed during the join: the entry it wrote is owed a leave.
+                        this.leaveIfLast(docName, joinedRoom, ctx.userId);
+                        return;
+                    }
+                    joined = true;
+                    room.users.set(ctx.userId, (room.users.get(ctx.userId) ?? 0) + 1);
+                    // The acknowledgement goes before the state, so the client knows
+                    // the shape of its first send before it makes it.
+                    if (sendsChanges)
+                        ws.send(CHANGES_ACK);
+                    ws.send(this.am.save(room.text));
                     ws.on('message', (data) => {
                         // A read-only connection still receives every update; its own are
                         // dropped. Enforced here because the client cannot be trusted to
                         // respect a permission it was merely told about.
                         if (readOnlyClients.has(ws))
                             return;
-                        void this.handleClientMessage(docName, data, ws);
-                    });
-                    ws.on('close', () => {
-                        room.clients.delete(ws);
-                        readOnlyClients.delete(ws);
-                        // Only the user's LAST socket on this document leaves the roster.
-                        const stillConnected = [...room.clients].some((client) => socketUsers.get(client) === ctx.userId);
-                        socketUsers.delete(ws);
-                        if (!stillConnected) {
-                            void this.options.presence?.leave(docName, ctx.userId);
-                        }
+                        this.handleClientMessage(docName, joinedRoom, data, ws);
                     });
-                    socketUsers.set(ws, ctx.userId);
                 }
                 catch (error) {
+                    if (room) {
+                        // A join that failed may still have written the entry.
+                        this.removeSocket(docName, room, ws, undefined);
+                        this.leaveIfLast(docName, room, ctx.userId);
+                    }
                     reportCollaborationError({ scope: 'storage', operation: 'loadDocument', docName, error });
                     ws.close(4500, 'could not open the document');
                 }
             });
         });
     }
-    // biome-ignore lint/suspicious/noExplicitAny: automerge's typing is unstable between minors
-    async handleClientMessage(docName, data, sender) {
-        const room = await this.loadRoom(docName);
+    /**
+     * Takes `ws` out of the room — and, when `userId` is given, out of that
+     * user's socket count, leaving the roster with their last one. Safe to call
+     * twice for one socket.
+     */
+    removeSocket(docName, room, ws, userId) {
+        if (!room.clients.delete(ws))
+            return;
+        readOnlyClients.delete(ws);
+        changeClients.delete(ws);
+        if (userId !== undefined) {
+            const count = (room.users.get(userId) ?? 1) - 1;
+            if (count > 0)
+                room.users.set(userId, count);
+            else
+                room.users.delete(userId);
+            this.leaveIfLast(docName, room, userId);
+        }
+        void this.releaseRoom(docName, room);
+    }
+    /** Removes `userId` from the roster unless another of their sockets is still in the room. */
+    leaveIfLast(docName, room, userId) {
+        if (room.users.has(userId))
+            return;
+        this.options.presence?.leave(docName, userId).catch((error) => {
+            reportCollaborationError({ scope: 'transport', operation: 'presence.leave', docName, error });
+        });
+    }
+    /**
+     * Applies a client's whole document or change chunk and forwards only what
+     * was new to the room. A payload that adds nothing — a duplicate, or bytes
+     * that are not Automerge at all — is neither forwarded nor saved.
+     */
+    handleClientMessage(docName, room, data, sender) {
         try {
-            // Client sends an incremental binary doc; merge into the server doc.
-            const incoming = A.load(data);
-            const merged = A.merge(room.text, incoming);
-            room.text = merged;
-            this.broadcast(room, data, sender);
-            // Persistence with simple per-room debounce.
-            await this.persistDebounced(docName, room);
+            const before = this.am.next.getHeads(room.text);
+            room.text = this.am.loadIncremental(room.text, data);
+            if (sameHeads(before, this.am.next.getHeads(room.text)))
+                return;
+            // A whole document from a whole-document client is forwarded as it came
+            // to the other whole-document clients: it is already the payload they need.
+            this.broadcast(room, before, sender, changeClients.has(sender) ? undefined : data);
+            this.schedulePersist(docName, room);
         }
         catch {
             // Invalid payload: ignore (a badly-behaved client doesn't take down the room).
         }
     }
-    persistDebounced(docName, room) {
-        return new Promise((resolve) => {
-            const existing = this.persistTimers.get(docName);
-            if (existing)
-                clearTimeout(existing);
-            this.persistTimers.set(docName, setTimeout(() => {
-                void this.storage
-                    .saveDocument(docName, A.save(room.text))
-                    .catch((error) => {
-                    reportCollaborationError({
-                        scope: 'storage',
-                        operation: 'saveDocument',
-                        docName,
-                        error,
-                    });
-                })
-                    .finally(() => resolve());
-            }, this.options.debounce ?? 2000));
-        });
+    /**
+     * Debounced save: each edit postpones it by `debounce`, but never past
+     * {@link MAX_PERSIST_WAIT_MS} (or `debounce`, if longer) after the first
+     * unsaved edit, so a document edited without pause is still written.
+     */
+    schedulePersist(docName, room) {
+        const debounce = this.options.debounce ?? 2000;
+        const now = Date.now();
+        const pending = this.pendingSaves.get(docName);
+        if (pending)
+            clearTimeout(pending.timer);
+        const deadline = pending?.deadline ?? now + Math.max(MAX_PERSIST_WAIT_MS, debounce);
+        const timer = setTimeout(() => void this.persistNow(docName), Math.max(0, Math.min(debounce, deadline - now)));
+        this.pendingSaves.set(docName, { timer, deadline, room });
+    }
+    /** Writes the pending save of `docName` now, if there is one. */
+    async persistNow(docName) {
+        const pending = this.pendingSaves.get(docName);
+        if (!pending)
+            return this.savesInFlight.get(docName);
+        clearTimeout(pending.timer);
+        this.pendingSaves.delete(docName);
+        await this.save(docName, this.am.save(pending.room.text));
+    }
+    /** Saves `state`, tracked so the room is not dropped while it is written. */
+    async save(docName, state) {
+        const previous = this.savesInFlight.get(docName);
+        const write = (async () => {
+            // Writes of one document stay in order, so an older state never lands last.
+            await previous;
+            try {
+                await this.storage.saveDocument(docName, state);
+            }
+            catch (error) {
+                reportCollaborationError({ scope: 'storage', operation: 'saveDocument', docName, error });
+            }
+        })();
+        this.savesInFlight.set(docName, write);
+        try {
+            await write;
+        }
+        finally {
+            if (this.savesInFlight.get(docName) === write)
+                this.savesInFlight.delete(docName);
+        }
     }
     async getDocumentState(docName) {
-        const room = await this.loadRoom(docName);
-        return A.save(room.text);
+        return this.withRoom(docName, (room) => this.am.save(room.text));
     }
     async getDocumentText(docName) {
-        const room = await this.loadRoom(docName);
-        const content = room.text.content;
-        return content ? content.toString() : '';
+        return this.withRoom(docName, (room) => {
+            const content = room.text.content;
+            return content ? content.toString() : '';
+        });
     }
     /** Versions = markers over the native history (heads hash). */
     async createVersion(docName, createdBy, label) {
-        const room = await this.loadRoom(docName);
-        const heads = ANext.getHeads(room.text);
-        const existing = await this.storage.listVersions(docName);
-        const version = {
-            ...createVersionMetadata(createdBy, label, seqVersions(existing)),
-            id: heads.join(','),
-        };
-        // Snapshot = binary save of the doc up to those heads (Automerge compresses
-        // well; storing the whole doc as the "snapshot" keeps restore O(1)).
-        await this.storage.saveVersion(docName, version, A.save(room.text));
-        return version;
+        return this.withRoom(docName, async (room) => {
+            const heads = this.am.next.getHeads(room.text);
+            const existing = await this.storage.listVersions(docName);
+            const version = {
+                ...createVersionMetadata(createdBy, label, seqVersions(existing)),
+                id: heads.join(','),
+            };
+            // Snapshot = binary save of the doc up to those heads (Automerge compresses
+            // well; storing the whole doc as the "snapshot" keeps restore O(1)).
+            await this.storage.saveVersion(docName, version, this.am.save(room.text));
+            return version;
+        });
     }
     async listVersions(docName, page) {
         return this.storage.listVersions(docName, page);
@@ -293,25 +440,36 @@ export class AutomergeDriver {
      */
     async restoreVersion(docName, versionId, restoredBy) {
         const bytes = await this.getVersionState(docName, versionId);
-        const snapshotDoc = A.load(bytes);
-        const room = await this.loadRoom(docName);
+        await this.automerge();
+        const snapshotDoc = this.am.load(bytes);
+        await this.withRoom(docName, (room) => this.restoreRoom(docName, room, versionId, snapshotDoc, restoredBy));
+    }
+    async restoreRoom(docName, room, versionId, 
+    // biome-ignore lint/suspicious/noExplicitAny: automerge's typing is unstable between minors
+    snapshotDoc, restoredBy) {
         const existing = await this.storage.listVersions(docName);
         const target = existing.find((version) => version.id === versionId);
         await this.storage.saveVersion(docName, {
             ...createVersionMetadata(restoredBy, restoredFromLabel(target, versionId), seqVersions(existing)),
-            id: ANext.getHeads(room.text).join(','),
-        }, A.save(room.text));
-        const merged = A.merge(room.text, snapshotDoc);
+            id: this.am.next.getHeads(room.text).join(','),
+        }, this.am.save(room.text));
+        const before = this.am.next.getHeads(room.text);
+        const merged = this.am.merge(room.text, snapshotDoc);
         // Automerge merge converges to the most recent state; to "restore",
         // we overwrite the content field with the value from the version.
         const restoredContent = snapshotDoc
             .content;
-        const finalDoc = A.change(merged, (doc) => {
+        const finalDoc = this.am.change(merged, (doc) => {
             doc.content = restoredContent?.toString() ?? '';
         });
         room.text = finalDoc;
-        this.broadcast(room, A.save(finalDoc));
-        await this.storage.saveDocument(docName, A.save(finalDoc));
+        this.broadcast(room, before);
+        // The restore supersedes any debounced save of the state it replaced.
+        const pending = this.pendingSaves.get(docName);
+        if (pending)
+            clearTimeout(pending.timer);
+        this.pendingSaves.delete(docName);
+        await this.save(docName, this.am.save(finalDoc));
     }
     /** Binary state stored for a version (`A.save` of the doc at that point). */
     async getVersionState(docName, versionId) {
@@ -325,20 +483,25 @@ export class AutomergeDriver {
             this.getVersionState(docName, aId),
             this.getVersionState(docName, bId),
         ]);
+        await this.automerge();
         const textOf = (bytes) => {
-            const doc = A.load(bytes);
+            const doc = this.am.load(bytes);
             return doc.content?.toString() ?? '';
         };
         return lineDiff(textOf(aBytes), textOf(bBytes));
     }
     async close() {
-        for (const timer of this.persistTimers.values())
-            clearTimeout(timer);
+        // Edits still inside their debounce are written, not dropped.
+        await Promise.all([...this.pendingSaves.keys()].map((docName) => this.persistNow(docName)));
+        await Promise.all(this.savesInFlight.values());
         // `this.wss?.close(cb)` never runs cb when there is no server, so this
         // promise used to hang forever on a driver that was never attached —
         // which is every driver outside the web process.
         if (!this.wss)
             return;
+        // `wss.close` only calls back once every client is gone.
+        for (const client of this.wss.clients)
+            client.terminate();
         return new Promise((resolve) => {
             this.wss?.close(() => resolve());
         });