@jxsuite/collab 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.0.0",
+    "@jxsuite/schema": "^1.1.0",
     "lib0": "^0.2.99",
     "y-protocols": "^1.0.6",
     "yjs": "13.6.27"

package/src/envelope.ts

@@ -47,6 +47,13 @@ export type ControlMessage =
   | { type: "flush"; path: string }
   /** Server → client: the flush landed. */
   | { type: "flush-ack"; path: string }
+  /**
+   * Server → client: the room's unsaved-since-last-persist state changed (drives the Save
+   * affordance). Room-level and authoritative: any peer's edit dirties the room for everyone; a
+   * persist clears it for everyone. Sent to a newly-subscribing connection during the open
+   * handshake so it learns the current state.
+   */
+  | { type: "doc-dirty"; path: string; dirty: boolean }
   /**
    * Server → client: a request was refused (codes: read-only, content-not-loaded, too-large,
    * rate-limited, binary-file, unknown-frame).

package/src/provider.ts

@@ -39,6 +39,12 @@ export interface CollabHandle {
    * is dead: destroy it and re-acquire a fresh one via platform.collab.
    */
   onReset: (cb: () => void) => () => void;
+  /**
+   * Room-level unsaved state changed: any peer edited since the last persist, or a persist cleared
+   * it. Fires immediately with the current value on subscribe (the server sends it during the open
+   * handshake, so the callback must run synchronously to win that race). Returns an unsubscribe.
+   */
+  onDirty: (cb: (dirty: boolean) => void) => () => void;
   destroy: () => void;
 }
 

package/src/ws-client.ts

@@ -67,6 +67,9 @@ interface DocEntry {
   resetCbs: Set<() => void>;
   pendingFlush: Set<() => void>;
   handleDestroyed: boolean;
+  /** Latest room-level dirty state from the server (survives reconnect on the same entry). */
+  dirty: boolean;
+  dirtyCbs: Set<(dirty: boolean) => void>;
 }
 
 export function createWsCollabConnection(options: WsCollabConnectionOptions): WsCollabConnection {
@@ -180,6 +183,16 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
         }
         return;
       }
+      case "doc-dirty": {
+        const entry = docs.get(message.path);
+        if (entry) {
+          entry.dirty = message.dirty;
+          for (const cb of entry.dirtyCbs) {
+            cb(message.dirty);
+          }
+        }
+        return;
+      }
       case "error": {
         if (!message.path) {
           return;
@@ -349,6 +362,8 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
         resolveSynced = resolve;
       });
       const entry: DocEntry = {
+        dirty: false,
+        dirtyCbs: new Set(),
         doc: new Y.Doc(),
         epoch: 0,
         handleDestroyed: false,
@@ -418,6 +433,13 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
             sendFrame({ message: { path, type: "flush" }, type: "control" });
           }),
         identity: () => identity,
+        onDirty: (cb) => {
+          entry.dirtyCbs.add(cb);
+          // Deliver current state synchronously: the server's open-handshake `doc-dirty` may have
+          // Already landed before the caller subscribes, and it must not miss the initial value.
+          cb(entry.dirty);
+          return () => entry.dirtyCbs.delete(cb);
+        },
         onReset: (cb) => {
           entry.resetCbs.add(cb);
           return () => entry.resetCbs.delete(cb);

package/src/ws-room.ts

@@ -44,6 +44,10 @@ interface Room {
   epoch: number;
   subscribers: Set<HostConnection>;
   ready: Promise<void>;
+  /** The source text as of the last persist (seed or markPersisted) — the room-dirty baseline. */
+  baseline: string;
+  /** True while the live source differs from `baseline`; mirrored to peers via `doc-dirty`. */
+  dirty: boolean;
 }
 
 export interface HostConnection {
@@ -64,6 +68,12 @@ export interface CollabHost {
   subscriberCount: (path: string) => number;
   /** Destroy an empty room (embedder teardown after its grace period). */
   destroyRoomIfEmpty: (path: string) => void;
+  /**
+   * The embedder folded the room's source to durable storage: reset the dirty baseline to the
+   * current source and broadcast `doc-dirty{false}` to every subscriber. Called from `onFlush`
+   * after a successful write.
+   */
+  markPersisted: (path: string) => void;
   destroy: () => void;
 }
 
@@ -114,27 +124,32 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
   };
 
   const ensureRoom = (path: string): Room => {
-    let room = rooms.get(path);
-    if (room) {
-      return room;
+    const existing = rooms.get(path);
+    if (existing) {
+      return existing;
     }
     const doc = new Y.Doc();
     const epoch = epochs.get(path) ?? 0;
     epochs.set(path, epoch);
-    room = {
+    const room: Room = {
+      baseline: "",
+      dirty: false,
       doc,
       epoch,
-      ready: (async () => {
-        const source = await options.loadSource(path);
-        if (source === null) {
-          throw new Error("content-not-loaded");
-        }
-        doc.transact(() => {
-          sourceText(doc).insert(0, source);
-        }, "seed");
-      })(),
+      ready: Promise.resolve(),
       subscribers: new Set(),
     };
+    room.ready = (async () => {
+      const source = await options.loadSource(path);
+      if (source === null) {
+        throw new Error("content-not-loaded");
+      }
+      // The seeded text IS the on-disk state — the initial clean baseline.
+      room.baseline = source;
+      doc.transact(() => {
+        sourceText(doc).insert(0, source);
+      }, "seed");
+    })();
     doc.on("update", (update: Uint8Array, origin: unknown) => {
       const current = rooms.get(path);
       if (!current || current.doc !== doc) {
@@ -148,6 +163,15 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
         origin instanceof Object && "socket" in origin ? (origin as InternalConnection) : undefined,
       );
       options.onSourceChange?.(path);
+      // Room-level dirty: broadcast on transition so every peer's Save affordance stays in sync.
+      const nowDirty = sourceText(current.doc).toString() !== current.baseline;
+      if (nowDirty !== current.dirty) {
+        current.dirty = nowDirty;
+        broadcastToRoom(current, {
+          message: { dirty: nowDirty, path, type: "doc-dirty" },
+          type: "control",
+        });
+      }
     });
     rooms.set(path, room);
     return room;
@@ -178,6 +202,8 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
     room.subscribers.add(conn);
     conn.subscribed.add(path);
     sendControl(conn, { epoch: room.epoch, path, type: "opened" });
+    // The joiner learns the room's current unsaved state (it may join a room others have dirtied).
+    sendControl(conn, { dirty: room.dirty, path, type: "doc-dirty" });
     // Server-initiated step1: learn the client's state (it replies step2 + its own step1).
     const body = encoding.createEncoder();
     syncProtocol.writeSyncStep1(body, room.doc);
@@ -394,6 +420,21 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
       }
     },
 
+    markPersisted(path) {
+      const room = rooms.get(path);
+      if (!room) {
+        return;
+      }
+      room.baseline = sourceText(room.doc).toString();
+      if (room.dirty) {
+        room.dirty = false;
+        broadcastToRoom(room, {
+          message: { dirty: false, path, type: "doc-dirty" },
+          type: "control",
+        });
+      }
+    },
+
     resetDoc(path) {
       const nextEpoch = (epochs.get(path) ?? 0) + 1;
       epochs.set(path, nextEpoch);