feat(versioning): resolve version authors reactively via the user store

Version snapshots now carry raw author user-ids on a new `by` field
instead of a pre-resolved `secondaryLabel` string, and resolving those
ids to usernames becomes a view concern:

- `VersioningExtension` accepts `resolveUsers` and exposes the
  normalized `userStore` on its instance (mirroring CommentsExtension);
  `CollaborationExtension` passes its shared store in.
- The YHub endpoints just split the activity `by` field into ids — no
  more reaching into the attribution extension's user store. `create`
  stamps the optimistic snapshot with the cursor user's id.
- New `useVersionUsers`/`useSnapshotLabel` React hooks (mirroring
  `useCommentUsers`) resolve `by` ids reactively, so author labels
  update as user info loads into the store — no re-list needed.
- `UserStore` gains `setUser` and resolvers now receive the store, so a
  resolver can return partial info synchronously and fill in the rest
  later.

Author: nperez0111

examples/07-collaboration/13-versioning-yjs14/src/userdata.ts

@@ -1,4 +1,4 @@
-import type { User } from "@blocknote/core";
+import type { User, UserStore } from "@blocknote/core";
 
 // Integer-like ids make it obvious if username resolution ever breaks: the
 // version sidebar / diff tooltips would show a bare number (e.g. "1") instead
@@ -18,6 +18,15 @@ export const USERS: User[] = [
  * diff tooltips) by name instead of id. Mirrors the `resolveUsers` you'd
  * normally back with your own user database.
  */
-export async function resolveUsers(userIds: string[]): Promise<User[]> {
-  return USERS.filter((u) => userIds.includes(u.id));
+export async function resolveUsers(
+  userIds: string[],
+  store: UserStore<any>,
+): Promise<User[]> {
+  setTimeout(
+    () => {
+      store.setUser(USERS.filter((u) => userIds.includes(u.id)));
+    },
+    Math.random() * 200 + 300,
+  );
+  return [USERS[0]];
 }

packages/core/src/extensions/Versioning/Versioning.test.ts

@@ -11,6 +11,7 @@ import {
 } from "vite-plus/test";
 
 import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
+import type { UserStoreOrResolver } from "../../user/index.js";
 import { sortSnapshotsNewestFirst, VersioningExtension } from "./Versioning.js";
 import type { VersionSnapshot } from "./Versioning.js";
 import {
@@ -56,6 +57,7 @@ function setup(opts?: {
   initialText?: string;
   withoutRestore?: boolean;
   withoutUpdateName?: boolean;
+  resolveUsers?: UserStoreOrResolver;
 }) {
   const editor = createEditor();
   setEditorText(editor, opts?.initialText ?? "initial doc");
@@ -74,6 +76,7 @@ function setup(opts?: {
     endpoints,
     preview,
     getCurrentDocument: () => editor.document,
+    resolveUsers: opts?.resolveUsers,
   })({ editor });
 
   /** Seed a snapshot into the backend by capturing the current editor doc. */
@@ -347,6 +350,57 @@ describe("VersioningExtension", () => {
     });
   });
 
+  // -------------------------------------------------------------------------
+  // User store (author resolution for `VersionSnapshot.by`)
+  // -------------------------------------------------------------------------
+
+  describe("user store", () => {
+    it("exposes an empty user store when no resolveUsers is provided", async () => {
+      expect(ctx.ext.userStore).toBeDefined();
+      await ctx.ext.userStore.loadUsers(["u1"]);
+      expect(ctx.ext.userStore.getUser("u1")).toBeUndefined();
+    });
+
+    it("builds a de-duped user store from a resolveUsers callback", async () => {
+      const resolveUsers = vi.fn(async (ids: string[]) =>
+        ids.map((id) => ({ id, username: `name-${id}`, avatarUrl: "" })),
+      );
+      const withUsers = setup({ resolveUsers });
+
+      await withUsers.ext.userStore.loadUsers(["u1", "u2"]);
+      expect(withUsers.ext.userStore.getUser("u1")?.username).toBe("name-u1");
+      expect(withUsers.ext.userStore.getUser("u2")?.username).toBe("name-u2");
+
+      // Already-cached ids are not re-fetched.
+      await withUsers.ext.userStore.loadUsers(["u1"]);
+      expect(resolveUsers).toHaveBeenCalledTimes(1);
+
+      withUsers.editor.unmount();
+    });
+
+    it("passes `by` author ids through list() untouched", async () => {
+      const editor = createEditor();
+      const ext = VersioningExtension({
+        endpoints: {
+          list: async () => [snap("1", 100, { by: ["u1", "u2"] })],
+          getContent: async () => [],
+        },
+        preview: createInMemoryPreviewController(editor),
+        getCurrentDocument: () => editor.document,
+      })({ editor });
+
+      const result = await ext.list();
+
+      // Raw ids are preserved — resolving them to user info is the view
+      // layer's job (via `ext.userStore`), never the extension's.
+      expect(result[0]!.by).toEqual(["u1", "u2"]);
+      expect(result[0]!.secondaryLabel).toBeUndefined();
+      expect(ext.store.state.snapshots).toEqual(result);
+
+      editor.unmount();
+    });
+  });
+
   // -------------------------------------------------------------------------
   // End-to-end workflow
   // -------------------------------------------------------------------------

packages/core/src/extensions/Versioning/Versioning.ts

@@ -4,6 +4,11 @@ import {
   createStore,
   type ExtensionOptions,
 } from "../../editor/BlockNoteExtension.js";
+import {
+  normalizeToUserStore,
+  type User,
+  type UserStoreOrResolver,
+} from "../../user/index.js";
 
 /**
  * Represents a single snapshot of a document's history, including metadata and content information.
@@ -34,11 +39,24 @@ export interface VersionSnapshot {
   updatedAt: number;
 
   /**
-   * An optional secondary label for the snapshot, which can display additional information such as the author or a custom description.
+   * An optional secondary label for the snapshot, which can display additional information such as a custom description.
    * This is for display purposes only and is not used for any logic in the versioning system.
+   *
+   * For author attribution, prefer {@link by}: it holds raw user ids that the
+   * view layer resolves to user info (and keeps up to date as users load).
+   * When both are set, `secondaryLabel` wins.
    */
   secondaryLabel?: string;
 
+  /**
+   * The id(s) of the user(s) that authored this version, as raw user ids —
+   * never pre-resolved to display names. The view layer resolves them via the
+   * {@link VersioningExtension}'s user store (see
+   * {@link VersioningExtensionOptions.resolveUsers}), reactively updating as
+   * user info loads. Only used when {@link secondaryLabel} is unset.
+   */
+  by?: User["id"] | User["id"][];
+
   /**
    * The ID of the previous snapshot that this snapshot was restored from.
    */
@@ -274,6 +292,19 @@ export type VersioningExtensionOptions<
    * extension's `canPreviewCurrent` flag.
    */
   serializeCurrentContent?: () => Output | Promise<Output>;
+  /**
+   * Resolve user information for the author ids in {@link VersionSnapshot.by},
+   * used by the view layer to render version-author labels.
+   *
+   * Either a resolver function (called with the ids of users that are not yet
+   * cached, returning their information — a user store is built from it
+   * internally) or a pre-built user store (see `createUserStore`). Pass the
+   * same store you give the comments/collaboration extensions so a single
+   * de-duped user cache is shared across features.
+   *
+   * @note omit and author ids are displayed as-is.
+   */
+  resolveUsers?: UserStoreOrResolver;
 };
 
 function snapshotNotFoundError(
@@ -296,12 +327,16 @@ export const VersioningExtension = createExtension(
       preview,
       getCurrentDocument,
       serializeCurrentContent,
+      resolveUsers,
     } = typeof optionsOrFactory === "function"
       ? optionsOrFactory(editor)
       : optionsOrFactory;
 
     const endpoints =
       typeof endpointsRaw === "function" ? endpointsRaw(editor) : endpointsRaw;
+    // With no resolver this is an empty store: `getUser` always misses, so the
+    // view layer falls back to showing the raw ids from `VersionSnapshot.by`.
+    const userStore = normalizeToUserStore(resolveUsers);
     const store = createStore<{
       snapshots: VersionSnapshot[];
       /**
@@ -463,6 +498,7 @@ export const VersioningExtension = createExtension(
     return {
       key: "versioning",
       store,
+      userStore,
       list: async (): Promise<VersionSnapshot[]> => {
         return await updateSnapshots();
       },

packages/core/src/user/UserStore.ts

@@ -58,8 +58,35 @@ export type UserStore<U extends User = User> = {
    * The user has to be loaded via `loadUsers` first.
    */
   getUser: (userId: User["id"]) => U | undefined;
+  /**
+   * Manually set information about a user. This is useful if you have a
+   * resolver that returns partial information (e.g. just the username) and you
+   * want to fill in the rest later (e.g. avatarUrl).
+   */
+  setUser: (user: U | U[]) => void;
 };
 
+export type UserStoreResolver<U extends User = User> = (
+  /**
+   * The user ids to resolve. The resolver should return information for all of
+   * these users, or an empty array if none could be resolved.
+   */
+  userIds: User["id"][],
+  /**
+   * The {@link UserStore} that is calling this resolver. This allows you to return a user synchronously, and update the store later if you need to fetch additional information asynchronously.
+   */
+  store: UserStore<any>,
+) => Promise<U[]>;
+
+/**
+ * A resolver callback or an already-built {@link UserStore} — the shape that
+ * user-facing options (comments, collaboration) accept so callers can either let
+ * the extension build a store or pass a shared one.
+ */
+export type UserStoreOrResolver<U extends User = User> =
+  | ((userIds: User["id"][], store: UserStore<any>) => Promise<U[]>)
+  | UserStore<any>;
+
 /**
  * Creates a {@link UserStore} that retrieves and caches information about users.
  *
@@ -76,7 +103,7 @@ export type UserStore<U extends User = User> = {
  * See [Comments](https://www.blocknotejs.org/docs/features/collaboration/comments) for more info.
  */
 export function createUserStore<U extends User = User>(
-  resolveUsers: (userIds: User["id"][]) => Promise<U[]>,
+  resolveUsers: (userIds: User["id"][], store: UserStore<any>) => Promise<U[]>,
 ): UserStore<U> {
   if (!resolveUsers) {
     throw new Error("resolveUsers is required to create a user store");
@@ -89,6 +116,33 @@ export function createUserStore<U extends User = User>(
   // not state that consumers need to subscribe to.
   const loadingUsers = new Set<User["id"]>();
 
+  const userStore: UserStore<U> = {
+    store,
+    async loadUsers(userIds) {
+      const missingUsers = userIds.filter(
+        (id) => !store.state.has(id) && !loadingUsers.has(id),
+      );
+      await fetchUsers(missingUsers);
+    },
+    async refetchUsers(userIds) {
+      const usersToFetch = userIds.filter((id) => !loadingUsers.has(id));
+      await fetchUsers(usersToFetch);
+    },
+    getUser(userId) {
+      return store.state.get(userId);
+    },
+    setUser(users) {
+      const usersArray = Array.isArray(users) ? users : [users];
+      store.setState((prevState) => {
+        const nextState = new Map(prevState);
+        for (const user of usersArray) {
+          nextState.set(user.id, user);
+        }
+        return nextState;
+      });
+    },
+  };
+
   async function fetchUsers(userIds: User["id"][]) {
     if (userIds.length === 0) {
       return;
@@ -99,7 +153,7 @@ export function createUserStore<U extends User = User>(
     }
 
     try {
-      const users = await resolveUsers(userIds);
+      const users = await resolveUsers(userIds, userStore);
       // Only update the store if any users were actually resolved. Emitting
       // an update when nothing changed (e.g. when the resolver can't find a
       // user) would needlessly notify subscribers and, combined with a
@@ -124,33 +178,9 @@ export function createUserStore<U extends User = User>(
     }
   }
 
-  return {
-    store,
-    async loadUsers(userIds: User["id"][]) {
-      const missingUsers = userIds.filter(
-        (id) => !store.state.has(id) && !loadingUsers.has(id),
-      );
-      await fetchUsers(missingUsers);
-    },
-    async refetchUsers(userIds: User["id"][]) {
-      const usersToFetch = userIds.filter((id) => !loadingUsers.has(id));
-      await fetchUsers(usersToFetch);
-    },
-    getUser(userId: User["id"]): U | undefined {
-      return store.state.get(userId);
-    },
-  };
+  return userStore;
 }
 
-/**
- * A resolver callback or an already-built {@link UserStore} — the shape that
- * user-facing options (comments, collaboration) accept so callers can either let
- * the extension build a store or pass a shared one.
- */
-export type UserStoreOrResolver<U extends User = User> =
-  | ((userIds: User["id"][]) => Promise<U[]>)
-  | UserStore<any>;
-
 /**
  * Normalize a {@link UserStoreOrResolver} to a {@link UserStore}:
  * - an existing store is returned as-is (so a single de-duped cache can be

packages/core/src/y/extensions/index.ts

@@ -104,6 +104,7 @@ export const CollaborationExtension = createExtension(
           ? VersioningExtension({
               ...createYjsVersioningAdapter(editor, options.fragment),
               endpoints: options.versioningEndpoints,
+              resolveUsers: userStore,
             })
           : null,
         AttributionExtension({