Real-time collaboration: Improve collaboration within the same rich text

[alecgeatches]

What?

Allow two users to type at the same time within a block.

Fixes #74563, which demonstrates the behavior before this PR:

When two users have selections with the same Y.Text (e.g. core/paragraph text), other users' editors do not update selection position when it has changed.

Here are some examples of that behavior:

1. Stationary cursor "moves backward"

Above, my user has a cursor set at the beginning of "second". When another user types earlierin the paragraph, my selection stays in the same location. Because the text is being added before my selection position, my cursor "travels backwards" within the paragraph.

2. Selection range moves

Similarly, if a range is selected, this also stays stationary during text changes:

This is the same problem as above. Because the selectionStart/selectionEnd properties don't adjust to the changes in the underlying text, the selection can move backwords within the logical text.

3. Unexpected selection changes in rich text with line breaks

This problem persists when there are line breaks in a shared rich text object:

This PR addresses these issues and allows fluid selection updates with CRDT changes.

Why?

Users expect editing within the same block to work, and cursors to adjust to real-time changes in the same text.

How?

The cursor drift issue happens because the editor stores cursor positions as absolute offsets (e.g. "index 5 in the paragraph"), but when a remote peer inserts or deletes text before that position, the offset becomes stale. The cursor stays at index 5 even though the text it was anchored to has shifted.

The fix utilizes existing stored relative position data and updates selection to match when text changes occur.

When a user interacts with the editor, their cursor position is saved to a selection history as a Y.RelativePosition. These relative positions automatically account for text mutations and the relative position converted back to absolute will return the corrected offset. The main change is in getPostChangesFromCRDTDoc(), which extracts changes from the CRDT document when remote updates arrive. After extracting content changes, it now also recalculates the local user's cursor by converting their stored relative position back to an absolute offset, and includes this recalculated selection in the returned changes.

Because the recalculated selection is bundled into the same EDIT_ENTITY_RECORD dispatch as the content changes, both arrive in the store atomically.

Limitations

This strategy of recalculating absolute position doesn't work in two scenarios:

Limitation 1: Current block is split before the cursor

Screen.Recording.2026-02-23.at.1.13.22.PM.mov

User 1 has their cursor near the front of the block, and user 2 is typing later in the block. When user 1 hits enter and the block breaks into two, user 2's cursor stays within the same block. Ideally, the cursor should stay with the same logical text and move into the second paragraph.

This is tricky to solve. When the block is broken, a new Y.Text object is created for the new block's content which is now a separate data structure from the block the user was typing in. The anchor text is gone, so the absolute position just resolves to the end of the first block.

Limitation 2: Current block is merged into another block

Screen.Recording.2026-02-23.at.1.14.55.PM.mov

User 1 has their cursor at the beginning of the block and user 2 is typing later in the block. When user 1 hits backspace and the block is merged into the previous block, user 2's cursor disappears. Ideally, the cursor should stay in the same logical text and move into the previous block with the rest of the content.

Similar to above, this is difficult because the second block's structure is destroyed when the block is merged and the Y.Text in the prior block is changed. Making this work would require understanding where text content has been merged into other blocks and recalculating position.

---

Both of these are real issues, but will require more intensive tree-watching, changing our mergeCrdtBlocks logic to be more intelligent about block additions/deletions, or listening for specific Gutenberg signals that a block split or merge has occurred. In any case, I think this PR represents a huge improvement over current behavior and can be merged without addressing these cases yet.

Testing Instructions

1. Check out this PR. Ensure real-time collaboration is enabled via: WordPress Admin -> Settings -> Writing, and check the "Enable real-time collaboration" checkbox. Click the "Save Changes" button.
2. Open a post in two separate tabs. Ideally, this can be done on a shared site so that another real human can test at the same time.
3. Within the same block, have one user at the beginning of the block start typing.
4. Have a second user start typing later in the block.
5. Verify that both user's text appears in the block, and that the cursor position moves intuitively with the content.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: alecgeatches <alecgeatches@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[maxschmeling]

I thought this might be an issue, but you can't select half of a paragraph and then a block after that. Extending you selection down to a block at the end causes the entire paragraph to be selected. So it seems you can't half end.type be BlockSelection and start.type not be BlockSelection

[alecgeatches]

Block-level selections overall are funky, so thank you for checking.

[github-actions]

I just cherry-picked this PR to the wp/7.0 branch to get it included in the next release: 3b5bca0