feat: attribution endpoints for version diffing

Author: nperez0111

examples/07-collaboration/11-yhub/src/App.tsx

@@ -12,7 +12,7 @@ const provider = {
   awareness: new Awareness(doc),
 };
 provider.awareness.setLocalStateField("user", {
-  name: "Client A",
+  name: "Alice",
   color: "#30bced",
 });
 
@@ -21,18 +21,88 @@ const provider2 = {
   awareness: new Awareness(doc2),
 };
 provider2.awareness.setLocalStateField("user", {
-  name: "Client B",
+  name: "Bob",
   color: "#6eeb83",
 });
 
 const attrs = new Y.Attributions();
 
+// Batch timestamps: reuse the same timestamp for edits from the same user
+// within a 10-second window of inactivity.
+const BATCH_INTERVAL_MS = 10_000;
+const batchTimestamps = new Map<string, number>();
+const batchTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+function getBatchedTimestamp(userName: string): number {
+  const existing = batchTimestamps.get(userName);
+  const now = Date.now();
+
+  // Clear any pending reset timer
+  const timer = batchTimers.get(userName);
+  if (timer) clearTimeout(timer);
+
+  // Start a new batch if none exists or the previous one expired
+  if (existing == null) {
+    batchTimestamps.set(userName, now);
+  }
+
+  // Reset the batch after 10s of inactivity
+  batchTimers.set(
+    userName,
+    setTimeout(() => {
+      batchTimestamps.delete(userName);
+      batchTimers.delete(userName);
+    }, BATCH_INTERVAL_MS),
+  );
+
+  return batchTimestamps.get(userName)!;
+}
+
+// Track attributions per user for each doc
+function trackAttributions(
+  trackedDoc: Y.Doc,
+  userName: string,
+  attributions: Y.Attributions,
+) {
+  trackedDoc.on(
+    "update",
+    (
+      update: Uint8Array,
+      _origin: unknown,
+      _ydoc: Y.Doc,
+      tr: { local: boolean },
+    ) => {
+      if (!tr.local) return;
+      const contentIds = Y.createContentIdsFromUpdate(update);
+      const timestamp = getBatchedTimestamp(userName);
+      Y.insertIntoIdMap(
+        attributions.inserts,
+        Y.createIdMapFromIdSet(contentIds.inserts, [
+          Y.createContentAttribute("insert", userName),
+          Y.createContentAttribute("insertAt", timestamp),
+        ]),
+      );
+      Y.insertIntoIdMap(
+        attributions.deletes,
+        Y.createIdMapFromIdSet(contentIds.deletes, [
+          Y.createContentAttribute("delete", userName),
+          Y.createContentAttribute("deleteAt", timestamp),
+        ]),
+      );
+    },
+  );
+}
+
+// Track local changes on each doc with a distinct user name
+trackAttributions(doc, "Alice", attrs);
+trackAttributions(doc2, "Bob", attrs);
+
 const suggestingDoc = new Y.Doc({ isSuggestionDoc: true });
 const suggestingProvider = {
   awareness: new Awareness(suggestingDoc),
 };
 suggestingProvider.awareness.setLocalStateField("user", {
-  name: "View Suggestions",
+  name: "Charlie",
   color: "#ffbc42",
 });
 const suggestingAttributionManager = Y.createAttributionManagerFromDiff(
@@ -47,7 +117,7 @@ const suggestionModeProvider = {
   awareness: new Awareness(suggestionModeDoc),
 };
 suggestionModeProvider.awareness.setLocalStateField("user", {
-  name: "Suggestion Mode",
+  name: "Debbie",
   color: "#ee6352",
 });
 const suggestionModeAttributionManager = Y.createAttributionManagerFromDiff(
@@ -57,6 +127,10 @@ const suggestionModeAttributionManager = Y.createAttributionManagerFromDiff(
 );
 suggestionModeAttributionManager.suggestionMode = true;
 
+// Track local changes on suggestion docs with distinct user names
+trackAttributions(suggestingDoc, "Charlie", attrs);
+trackAttributions(suggestionModeDoc, "Debbie", attrs);
+
 // Function to sync two documents
 function syncDocs(sourceDoc: Y.Doc, targetDoc: Y.Doc) {
   const update = Y.encodeStateAsUpdate(sourceDoc);
@@ -84,18 +158,22 @@ function Editor({
   fragment,
   provider,
   attributionManager,
+  userName,
+  userColor,
 }: {
   fragment: Y.Type;
   provider: { awareness?: Awareness };
   attributionManager?: Y.DiffAttributionManager;
+  userName: string;
+  userColor: string;
 }) {
   const editor = useCreateBlockNote(
     withCollaboration({
       collaboration: {
         fragment,
         provider,
         attributionManager,
-        user: { name: "Client A", color: "#30bced" },
+        user: { name: userName, color: userColor },
       },
     }),
   );
@@ -116,12 +194,22 @@ export default function App() {
         }}
       >
         <div style={{ flex: 1 }}>
-          Client A
-          <Editor fragment={doc.get("doc")} provider={provider} />
+          Client A (Alice)
+          <Editor
+            fragment={doc.get("doc")}
+            provider={provider}
+            userName="Alice"
+            userColor="#30bced"
+          />
         </div>
         <div style={{ flex: 1 }}>
-          Client B
-          <Editor fragment={doc2.get("doc")} provider={provider2} />
+          Client B (Bob)
+          <Editor
+            fragment={doc2.get("doc")}
+            provider={provider2}
+            userName="Bob"
+            userColor="#6eeb83"
+          />
         </div>
       </div>
       <div
@@ -133,19 +221,23 @@ export default function App() {
         }}
       >
         <div style={{ flex: 1 }}>
-          View Suggestions Mode
+          View Suggestions (Charlie)
           <Editor
             fragment={suggestingDoc.get("doc")}
             provider={suggestingProvider}
             attributionManager={suggestingAttributionManager}
+            userName="Charlie"
+            userColor="#ffbc42"
           />
         </div>
         <div style={{ flex: 1 }}>
-          Suggestion Mode
+          Suggestion Mode (Debbie)
           <Editor
             fragment={suggestionModeDoc.get("doc")}
             provider={suggestionModeProvider}
             attributionManager={suggestionModeAttributionManager}
+            userName="Debbie"
+            userColor="#ee6352"
           />
         </div>
       </div>

examples/07-collaboration/11-yhub/src/style.css

@@ -1,67 +0,0 @@
-ins {
-  background-color: hsl(120 100 90);
-  color: hsl(120 100 30);
-  position: relative;
-}
-
-ins:hover::after {
-  content: attr(data-description);
-  position: absolute;
-  top: 100%;
-  left: 50%;
-  transform: translateX(-50%);
-  margin-top: 4px;
-  padding: 4px 8px;
-  background-color: rgba(0, 0, 0, 0.9);
-  color: white;
-  border-radius: 4px;
-  font-size: 12px;
-  white-space: nowrap;
-  pointer-events: none;
-  z-index: 1000;
-}
-
-.dark ins {
-  background-color: hsl(120 100 10);
-  color: hsl(120 80 70);
-}
-
-.dark ins:hover::after {
-  background-color: rgba(30, 30, 30, 0.95);
-  color: hsl(120 80 70);
-  border: 1px solid rgba(255, 255, 255, 0.1);
-}
-
-del {
-  background-color: hsl(0 100 90);
-  color: hsl(0 100 30);
-  position: relative;
-}
-
-del:hover::after {
-  content: attr(data-description);
-  position: absolute;
-  top: 100%;
-  left: 50%;
-  transform: translateX(-50%);
-  margin-top: 4px;
-  padding: 4px 8px;
-  background-color: rgba(0, 0, 0, 0.9);
-  color: white;
-  border-radius: 4px;
-  font-size: 12px;
-  white-space: nowrap;
-  pointer-events: none;
-  z-index: 1000;
-}
-
-.dark del {
-  background-color: hsl(0 100 10);
-  color: hsl(0 80 70);
-}
-
-.dark del:hover::after {
-  background-color: rgba(30, 30, 30, 0.95);
-  color: hsl(0 80 70);
-  border: 1px solid rgba(255, 255, 255, 0.1);
-}

examples/07-collaboration/13-versioning-yjs14/src/App.tsx

@@ -24,7 +24,7 @@ import "./style.css";
 // HTTP) for the same document, so the backend URL, org, and docId are shared.
 const yhubHost = "yhub-standalone-x9kss.ondigitalocean.app";
 const org = "blocknote-versioning-yjs14";
-const docId = "blocknote-versioning-y-example-4";
+const docId = "blocknote-versioning-y-example-5";
 
 const doc = new Y.Doc();
 // YHub expects clients to connect to `/ws/{org}/{docId}`. WebsocketProvider

examples/07-collaboration/14-multi-doc-versioning/src/DocumentEditor.tsx

@@ -1,6 +1,13 @@
 import "@blocknote/core/fonts/inter.css";
-import { withCollaboration, SuggestionsExtension } from "@blocknote/core/y";
-import { VersioningExtension } from "@blocknote/core/extensions";
+import {
+  withCollaboration,
+  SuggestionsExtension,
+  createYHubVersioningEndpoints,
+} from "@blocknote/core/y";
+import {
+  VersioningExtension,
+  type VersioningEndpoints,
+} from "@blocknote/core/extensions";
 import {
   BlockNoteViewEditor,
   useCreateBlockNote,
@@ -15,7 +22,7 @@ import { fromBase64 } from "lib0/buffer";
 import { WebsocketProvider } from "@y/websocket";
 
 import type { DemoUser } from "./userdata.js";
-import { createLocalStorageVersioningEndpoints } from "./localStorageEndpoints.js";
+
 import { HistorySidebar } from "./HistorySidebar.js";
 
 /**
@@ -35,7 +42,7 @@ export function DocumentEditor({
   docTitle: string;
   onTouch: () => void;
 }) {
-  const roomName = `bn-multi-doc-${workspaceId}-${docId}`;
+  const roomName = `${workspaceId}/${docId}`;
 
   // Stable refs for Y.js resources that persist for this mount
   const resourcesRef = useRef<{
@@ -44,9 +51,7 @@ export function DocumentEditor({
     provider: WebsocketProvider;
     suggestionProvider: WebsocketProvider;
     attributionManager: ReturnType<typeof Y.createAttributionManagerFromDiff>;
-    versioningEndpoints: ReturnType<
-      typeof createLocalStorageVersioningEndpoints
-    >;
+    versioningEndpoints: VersioningEndpoints;
   } | null>(null);
 
   if (!resourcesRef.current) {
@@ -61,29 +66,28 @@ export function DocumentEditor({
     }
 
     const suggestionDoc = new Y.Doc({ isSuggestionDoc: true });
+    const yhubHost = "yhub-standalone-x9kss.ondigitalocean.app";
+
     const provider = new WebsocketProvider(
-      "wss://demos.yjs.dev/ws",
+      `wss://${yhubHost}/ws`,
       roomName,
       doc,
-      { connect: false },
     );
     const suggestionProvider = new WebsocketProvider(
-      "wss://demos.yjs.dev/ws",
+      `wss://${yhubHost}/ws`,
       roomName + "-suggestions",
       suggestionDoc,
-      { connect: false },
     );
     const attributionManager = Y.createAttributionManagerFromDiff(
       doc,
       suggestionDoc,
     );
 
-    provider.connectBc();
-    suggestionProvider.connectBc();
-
-    const versioningEndpoints = createLocalStorageVersioningEndpoints(
-      `bn-versioning-${docId}`,
-    );
+    const versioningEndpoints = createYHubVersioningEndpoints({
+      baseUrl: `https://${yhubHost}`,
+      org: workspaceId,
+      docId,
+    });
 
     resourcesRef.current = {
       doc,

examples/07-collaboration/14-multi-doc-versioning/src/style.css

@@ -64,31 +64,6 @@
   --mod-border: rgba(166, 190, 255, 0.85);
 }
 
-/* ===== Base ===== */
-
-* {
-  box-sizing: border-box;
-}
-
-html,
-body,
-#root {
-  height: 100%;
-  margin: 0;
-}
-
-body {
-  background: var(--bg);
-  color: var(--text);
-  font-family:
-    -apple-system, BlinkMacSystemFont, "Segoe UI", "Inter", system-ui,
-    sans-serif;
-  font-size: 14px;
-  line-height: 1.5;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
 button {
   font: inherit;
   color: inherit;