feat(editor): local-first persistence + robust refocus re-sync

Prevents a stale never-closed tab from clobbering a collaborator's
newer content (the core data-loss incident):

- Mesh y-indexeddb onto the shared Y.Doc so edits survive refresh /
offline, and a client can re-sync its durable local copy back up if
the server ever loses or resurrects a stale document.
- On tab refocus, force a sync round-trip and hold the editor
read-only until it completes, so the user can't type onto a
visibly-stale buffer. Detect dead sockets via websocket status,
readyState and last-message timestamp (incl. half-open sockets via
a post-forceSync probe). Always release after a 4s grace window so
offline editing is never trapped (local-first).

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/package-lock.json

@@ -38,6 +38,7 @@
         "remark-gfm": "^4.0.1",
         "shiki": "^4.0.2",
         "tippy.js": "^6.3.7",
+        "y-indexeddb": "^9.0.12",
         "yjs": "^13.6.0",
         "zod": "^4.3.6"
       },
@@ -1626,7 +1627,6 @@
       "resolved": "https://registry.npmjs.org/@tiptap/extension-code-block/-/extension-code-block-3.22.3.tgz",
       "integrity": "sha512-RiQtEjDAPrHpdo6sw6b7fOw/PijqgFIsozKKkGcSeBgWHQuFg7q9OxJTj+l0e60rVwSu/5gmKEEobzM9bX+t2Q==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/ueberdosis"
@@ -6348,6 +6348,26 @@
         "node": ">=8"
       }
     },
+    "node_modules/y-indexeddb": {
+      "version": "9.0.12",
+      "resolved": "https://registry.npmjs.org/y-indexeddb/-/y-indexeddb-9.0.12.tgz",
+      "integrity": "sha512-9oCFRSPPzBK7/w5vOkJBaVCQZKHXB/v6SIT+WYhnJxlEC61juqG0hBrAf+y3gmSMLFLwICNH9nQ53uscuse6Hg==",
+      "license": "MIT",
+      "dependencies": {
+        "lib0": "^0.2.74"
+      },
+      "engines": {
+        "node": ">=16.0.0",
+        "npm": ">=8.0.0"
+      },
+      "funding": {
+        "type": "GitHub Sponsors ❤",
+        "url": "https://github.com/sponsors/dmonad"
+      },
+      "peerDependencies": {
+        "yjs": "^13.0.0"
+      }
+    },
     "node_modules/y-protocols": {
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/y-protocols/-/y-protocols-1.0.7.tgz",

frontend/package.json

@@ -42,6 +42,7 @@
     "remark-gfm": "^4.0.1",
     "shiki": "^4.0.2",
     "tippy.js": "^6.3.7",
+    "y-indexeddb": "^9.0.12",
     "yjs": "^13.6.0",
     "zod": "^4.3.6"
   },

frontend/src/editor/Editor.tsx

@@ -11,6 +11,7 @@ import { CodeBlockShiki } from "./extensions/code-block-shiki";
 import * as Y from "yjs";
 import { UndoManager } from "yjs";
 import { HocuspocusProvider } from "@hocuspocus/provider";
+import { IndexeddbPersistence } from "y-indexeddb";
 import { useEffect, useMemo, useRef, useState, MutableRefObject } from "react";
 import { BubbleToolbar } from "./BubbleToolbar";
 import { BlockHandle } from "./BlockHandle";
@@ -77,6 +78,16 @@ export function Editor({
   const undoManagerCallbackRef = useRef(onUndoManagerReady);
   undoManagerCallbackRef.current = onUndoManagerReady;
 
+  // Local-first persistence layer. Mesh an IndexedDB provider onto the
+  // same Y.Doc as the network provider: edits survive a refresh / closed
+  // tab / offline window, and - critically - if the server ever loses or
+  // resurrects a stale document, this client re-syncs its locally-cached
+  // state back up. Yjs providers are meshable and dedupe automatically.
+  const idbRef = useRef<IndexeddbPersistence | null>(null);
+  if (!idbRef.current) {
+    idbRef.current = new IndexeddbPersistence(`collab-editor:${docName}`, ydoc);
+  }
+
   const providerRef = useRef<HocuspocusProvider | null>(null);
   if (!providerRef.current) {
     const wsUrl =
@@ -132,6 +143,8 @@ export function Editor({
     return () => {
       providerRef.current?.destroy();
       providerRef.current = null;
+      idbRef.current?.destroy();
+      idbRef.current = null;
       ydocRef.current?.destroy();
       ydocRef.current = null;
     };
@@ -351,6 +364,100 @@ export function Editor({
     onEditorReady(editor);
   }, [editor, editorRef, onEditorReady]);
 
+  // Re-sync on tab refocus, and hold the editor read-only until the
+  // round-trip completes. A long-stale never-closed tab must hear the
+  // latest server state BEFORE the user types on top of it, otherwise
+  // its old buffer can clobber a collaborator's newer content. Local-
+  // first safety net: if the sync can't complete (offline / Space
+  // asleep), we re-enable editing after a short grace period - the
+  // y-indexeddb copy is durable and merges on the next reconnect, so we
+  // never trap the user in a permanent read-only state.
+  useEffect(() => {
+    if (!editor) return;
+
+    let graceTimer: ReturnType<typeof setTimeout> | null = null;
+    let probeTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const clearTimers = () => {
+      if (graceTimer) clearTimeout(graceTimer);
+      if (probeTimer) clearTimeout(probeTimer);
+      graceTimer = null;
+      probeTimer = null;
+    };
+
+    const unlock = () => {
+      clearTimers();
+      if (!editor.isDestroyed && !editor.isEditable) editor.setEditable(true);
+    };
+
+    const lock = () => {
+      if (!editor.isDestroyed && editor.isEditable) editor.setEditable(false);
+      if (graceTimer) clearTimeout(graceTimer);
+      // Never trap the user: offline edits stay valid (y-indexeddb) and
+      // merge on the next reconnect, so always release after a grace window.
+      graceTimer = setTimeout(unlock, 4000);
+    };
+
+    const resync = () => {
+      provider.connect().catch(() => {});
+      provider.forceSync();
+    };
+
+    const onSynced = () => unlock();
+    provider.on("synced", onSynced);
+
+    // The underlying websocket carries the only trustworthy liveness
+    // signals: socket-level status, the raw readyState, and the
+    // timestamp of the last server message.
+    const socket = () =>
+      provider.configuration?.websocketProvider as
+        | { status?: string; webSocket?: { readyState?: number } | null; lastMessageReceived?: number }
+        | undefined;
+
+    // "Obviously dead" cases we can detect synchronously, without a probe.
+    const looksDead = () => {
+      const ws = socket();
+      if (!ws) return !provider.synced;
+      if (ws.status !== "connected") return true;
+      if (ws.webSocket && ws.webSocket.readyState !== WebSocket.OPEN) return true;
+      return false;
+    };
+
+    const onVisibility = () => {
+      if (document.visibilityState !== "visible") return;
+
+      const before = socket()?.lastMessageReceived ?? 0;
+      resync();
+
+      // Synchronously-detectable stale state -> lock immediately.
+      if (looksDead() || !provider.synced) {
+        lock();
+        return;
+      }
+
+      // Socket *claims* to be alive (connected + OPEN) but a backgrounded
+      // tab can hold a half-dead socket that never fired a close event.
+      // Our forceSync() must draw a reply; if no new message lands within
+      // the probe window, treat it as stale and force a hard reconnect.
+      if (probeTimer) clearTimeout(probeTimer);
+      probeTimer = setTimeout(() => {
+        const advanced = (socket()?.lastMessageReceived ?? 0) > before;
+        if (!advanced) {
+          resync();
+          lock();
+        }
+      }, 2000);
+    };
+
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibility);
+      provider.off("synced", onSynced);
+      clearTimers();
+      unlock();
+    };
+  }, [editor, provider]);
+
   const [containerEl, setContainerEl] = useState<HTMLElement | null>(null);
 
   if (!editor) return null;