[WIP][lexical-yjs][lexical-react] Feature: initial implementation of collab v2 #7616

james-atticus · 2025-06-11T02:03:19Z

Description

Introduces a new useYjsCollaborationV2__EXPERIMENTAL hook and CollaborationPluginV2__EXPERIMENTAL plugin. Implementation of binding is heavily based off y-prosemirror. Tree shaking should mean that consumers who only use one version won't have a noticeable increase in bundle size.

The first commit is mostly refactoring, splitting out some shared logic from the original hook into useYjsCollaborationInternal (open to naming suggestions).

The second commit adds v2 implementations of syncLexicalUpdateToYjs and syncYjsChangesToLexical. Notably missing is all logic related to keeping selection updated and syncing cursors. That will come in a later PR.

Test plan

Unit tests have been updated to run with both v1 and v2 collab code. Despite the large diff (Github seems to be struggling even with whitespace hidden), the only change was to add the wrapping in describe.each and passing useCollabV2 down into the relevant functions (createTestConnection and expectCorrectInitialContent).

I have E2E tests running with v2 locally, however most of them fail because the selection in the right viewer isn't updated, so assertions about things like toolbar state fail. I'll look at enabling collab v2 in tests in a later PR.

vercel · 2025-06-11T02:03:24Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
lexical	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 13, 2025 5:11am
lexical-playground	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 13, 2025 5:11am

james-atticus · 2025-06-11T02:09:06Z

packages/lexical-react/src/shared/useYjsCollaboration.tsx

+  );
+}
+
+export function useYjsCollaborationV2__EXPERIMENTAL(


I've removed shouldBootstrap from v2 because it's a big foot-gun in v1. The consistent recommendation in Discord is to set it to false, so figured may as well use this opportunity to remove it entirely.

syncCursorPositionsFn is tied specifically to Binding. I haven't looked into cursor syncing for the rewrite yet, when I get to that, I'll try and make the function generic.

…nternal with shared v1/v2 logic

…b v2

james-atticus · 2025-06-12T23:46:45Z

packages/lexical-playground/__tests__/e2e/Collaboration.spec.mjs

@@ -38,7 +37,7 @@ test.describe('Collaboration', () => {
    isCollab,
    browserName,
  }) => {
-    test.skip(!isCollab || IS_MAC);
+    test.skip(!isCollab);


Drive-by: this test works fine on mac

james-atticus · 2025-06-13T00:05:45Z

packages/lexical-react/src/__tests__/unit/Collaboration.test.ts

+    if (useCollabV2) {
+      // Manually bootstrap editor state.
+      await waitForReact(() => {
+        client1.update(() => $getRoot().append($createParagraphNode()));


Needed because v2 doesn't support shouldBootstrap

james-atticus · 2025-06-13T01:28:14Z

packages/lexical-yjs/src/Bindings.ts

+export type LexicalMapping = Map<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  YAbstractType<any>,
+  // Either a node if type is YXmlElement or an Array of text nodes if YXmlText
+  LexicalNode | Array<TextNode>
+>;


Equivalent of the type in y-prosemirror.

james-atticus · 2025-06-13T01:36:52Z

packages/lexical-yjs/src/SyncEditorStates.ts

+  const dirtyElements = new Set<NodeKey>();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const collectDirty = (_value: any, type: YAbstractType<any>) => {
+    if (binding.mapping.has(type)) {
+      const node = binding.mapping.get(type)!;
+      if (!(node instanceof Array)) {
+        dirtyElements.add(node.getKey());
+      }
+    }
+  };


In y-prosemirror, for any YType that's been modified, the corresponding entry is deleted from the mapping. This then causes the sync code to recreate the code in createNodeIfNotExists. In Lexical however, we don't want to do this - we want to update the existing node if possible (i.e. keep the same nodeKey).

james-atticus · 2025-06-13T01:50:07Z

packages/lexical-yjs/src/SyncV2.ts

+/**
+ * @return Returns node if node could be created. Otherwise it deletes the yjs type and returns null
+ */
+export const $createOrUpdateNodeFromYElement = (


Per above, this is basically the same as createNodeFromYElement, except that it takes dirtyElements and updates existing nodes.

james-atticus · 2025-06-13T04:35:44Z

packages/lexical-yjs/src/SyncV2.ts

+): Y.XmlText => {
+  const type = new Y.XmlText();
+  const delta = nodes.map((node) => ({
+    attributes: {__properties: propertiesToAttributes(node, meta)},


y-prosemirror has marks (marksToAttributes(node.marks, meta)) for text nodes and attributes (node.attrs) for element nodes. Lexical does have this same delineation - just got the one propertiesToAttributes helper function.

james-atticus · 2025-06-13T04:52:39Z

packages/lexical-yjs/src/SyncV2.ts

+    const rightY = yChildren[yChildCnt - right - 1];
+    const rightP = pChildren[pChildCnt - right - 1];
+    if (mappedIdentity(meta.mapping.get(rightY), rightP)) {
+      if (rightP instanceof ElementNode && dirtyElements.has(rightP.getKey())) {


This is where dirtyElements is used to update YFragments without removing them from the mapping.

james-atticus · 2025-06-13T05:21:02Z

packages/lexical-playground/src/appSettings.ts

@@ -33,6 +33,7 @@ export const DEFAULT_SETTINGS = {
  tableCellBackgroundColor: true,
  tableCellMerge: true,
  tableHorizontalScroll: true,
+  useCollabV2: false,


Adding as a setting but not exposing it through the settings menu yet, given how early days this still is.

etrepum

I haven't been able to do invest the time to do a very thorough review, but the things that caught my eye were mostly just the sections where this is handling exceptions indiscriminately

etrepum · 2025-06-29T23:13:23Z

packages/lexical-yjs/src/Bindings.ts

+  return {
+    ...createBaseBinding(editor, id, doc, docMap, excludedProperties),
+    mapping: new Map(),
+    root: doc.get('root-v2', XmlElement) as XmlElement,


I like that this has a different default to avoid bad behavior when different versions of collab are used with the same doc, although maybe it should be parameterized further in some way to also solve the use case from #6483?

etrepum · 2025-06-29T23:29:47Z

packages/lexical-yjs/src/SyncV2.ts

+  } catch (e) {
+    // an error occured while creating the node. This is probably a result of a concurrent action.
+    // TODO(collab-v2): also delete the mapped node from editor state.
+    el.doc!.transact((transaction) => {
+      el._item!.delete(transaction);
+    }, meta);
+    meta.mapping.delete(el);
+    return null;
+  }


Would be nice to narrow this down to specific exceptions we'd expect to see and/or to a smaller portion of that code. A whole lot is happening in that block and this would make it quite hard to debug.

I'd been meaning to come back to this. Given it's in the functions for going from Yjs->Lexical, I'd rather just throw all errors and let the Lexical error boundary handle it. Just deleting data from Yjs seems needlessly dangerous. (It's only like this now because that's how y-prosemirror works.)

etrepum · 2025-06-29T23:31:09Z

packages/lexical-yjs/src/SyncV2.ts

+  } catch (e) {
+    // an error occured while creating the node. This is probably a result of a concurrent action.
+    // TODO(collab-v2): also delete the mapped text nodes from editor state.
+    text.doc!.transact((transaction) => {
+      text._item!.delete(transaction);
+    });
+    return null;
+  }


Same as above, I think this will make debugging very difficult

facebook-github-bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Jun 11, 2025

vercel bot deployed to Preview – lexical June 11, 2025 02:04 View deployment

vercel bot deployed to Preview – lexical-playground June 11, 2025 02:06 View deployment

james-atticus commented Jun 11, 2025

View reviewed changes

james-atticus force-pushed the yjs-v2-boilerplate branch from fbfd4f5 to 70e1f5a Compare June 11, 2025 02:10

james-atticus marked this pull request as ready for review June 11, 2025 02:11

james-atticus requested review from zurfyx, fantactuka, acywatson, Fetz, ivailop7, Sahejkm, potatowagon, lilshady and takuyakanbr as code owners June 11, 2025 02:11

vercel bot deployed to Preview – lexical June 11, 2025 02:12 View deployment

vercel bot deployed to Preview – lexical-playground June 11, 2025 02:13 View deployment

james-atticus changed the title ~~[lexical-yjs][lexical-react] Refactor: split out useYjsCollaborationInternal with shared v1/v2 logic~~ [lexical-yjs][lexical-react] Feature: initial implementation of collab v2 Jun 12, 2025

vercel bot deployed to Preview – lexical June 12, 2025 23:44 View deployment

vercel bot deployed to Preview – lexical-playground June 12, 2025 23:45 View deployment

james-atticus changed the title ~~[lexical-yjs][lexical-react] Feature: initial implementation of collab v2~~ [WIP][lexical-yjs][lexical-react] Feature: initial implementation of collab v2 Jun 12, 2025

james-atticus marked this pull request as draft June 12, 2025 23:46

james-atticus added 2 commits June 13, 2025 11:22

[lexical-yjs][lexical-react] Refactor: split out useYjsCollaborationI…

f0a01f0

…nternal with shared v1/v2 logic

[lexical-yjs][lexical-react] Feature: initial implementation of colla…

8d91369

…b v2

james-atticus force-pushed the yjs-v2-boilerplate branch from 486f58e to 8d91369 Compare June 13, 2025 05:09

james-atticus commented Jun 13, 2025

View reviewed changes

vercel bot deployed to Preview – lexical June 13, 2025 05:10 View deployment

vercel bot deployed to Preview – lexical-playground June 13, 2025 05:11 View deployment

james-atticus commented Jun 13, 2025

View reviewed changes

Mati20041 mentioned this pull request Jun 29, 2025

[lexical-yjs][lexical-react] Feature: Allow custom Yjs XmlText #6483

Open

etrepum reviewed Jun 29, 2025

View reviewed changes

[WIP][lexical-yjs][lexical-react] Feature: initial implementation of collab v2 #7616

Are you sure you want to change the base?

[WIP][lexical-yjs][lexical-react] Feature: initial implementation of collab v2 #7616

Uh oh!

Conversation

james-atticus commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Test plan

Uh oh!

vercel bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

etrepum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

james-atticus commented Jun 11, 2025 •

edited

Loading

vercel bot commented Jun 11, 2025 •

edited

Loading