Collaborative editing: Make syncing a side-concern instead of a replacement for local state by chriszarate · Pull Request #72114 · WordPress/gutenberg

chriszarate · 2025-10-06T20:59:48Z

What?

Instead of effectively replacing the core-data store with a "database" Yjs provider (IndexedDB), this change makes syncing a side-effect of the core-data store, without changing how the entity records are represented and treated within it.

Note

This is the first of a series of modular PRs related to collaborative editing derived from the work in #72040. Not all PRs result in a fully functional editing experience.

Why?

The primary motivation for this change is that not all entity record properties should be synced. When all properties are not synced, the simplest path is to continue to represent the entity in the local store.
- Properties like guid, _links, and modified should not be synced because we want the local codebase to remain authoritative over their values.
- Properties like content should not be synced because we prefer to sync a derivative property (blocks) instead.
A secondary motivation is architectural simplicity. The core-data store continues to function as it does now, and the sync package interacts with it as a (privileged) client.
A database Yjs provider (IndexedDB) can be a vehicle for offline editing, but this is not easily implemented when a separate database (WordPress's relational database) is considered the source of truth.

How?

In editEntityRecord (core-data actions), do not skip dispatching edits and adding undo records for entities with syncing enabled.
- Kevin's PR [took the same approach](https://github.com/WordPress/gutenberg/pull/68483/files#diff
In getEntityRecord (core-data resolvers), do not conditionally load the entity record into the store, and invert the order so that the entity is loaded before "bootstrapping."
- This code change is minor (unwrapping an if/else), but produces a large diff due to the changed indentation.
  963b9796c15a1a44431b3386775e7fe05e5bfd1f96293a8e20f5debae3478bc8).
Make sure to call the "register" method on the sync provider.
In the entity sync config, introduce a set of synced properties. This set is currently limited to blocks to help navigate syncing errors, but it will be expanded in future PRs.

Testing Instructions

Check out this branch.
Enable the real-time collaboration experiment: Gutenberg > Experiments.
Open a post for editing in two different browser environments.
Use your browser's development tools to remove the post editor lock (see screencast in the next section).

Note: This provider uses requests to admin-ajax.php for signaling and the initial connection is delayed.

Testing Instructions for Keyboard

No UI changes in this pull request.

Screenshots or screencast

pr-1.mov

github-actions · 2025-10-06T20:59:59Z

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: chriszarate <czarate@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>

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

This reverts commit 7d8fdf0.

youknowriad · 2025-10-07T08:01:11Z

 			name
 		);
 		const namespace = postType?.rest_namespace ?? 'wp/v2';
+		const syncedProperties = new Set( [ 'blocks' ] );


I don't understand why we need this change here? It feels very ad-hoc?

Also what about post types that don't support "content" (so have no "blocks" property)

I don't understand why we need this change here? It feels very ad-hoc?

It is very ad hoc:

In the entity sync config, introduce a set of synced properties. This set is currently limited to blocks to help navigate syncing errors, but it will be expanded in future PRs.

"Syncing errors" is shorthand for all sorts of edge cases, but the most serious issues are:

Rich text attributes need to target the raw property.

The status field cannot be synced until it "matures" past "auto-draft", otherwise timing issues can result in the post getting stuck.

I didn't address these in this PR because we have more robust solutions available in other PRs, which I will open shortly. But I can create targeted fixes in this PR if that is desired.

I don't feel like this addresses my question though. I guess what I'm asking is that before making "blocks" a synced property for a given post type entity, we should first ensure the post type in question supports "content" (which we can do in the supports array no?)

Anyway, it's not a huge concern though but we should be thinking about post types that don't have "content" or "blocks".

Yes, also addressed in a future PR. You can see how we approached this in #72040 in this commit:

gutenberg/packages/core-data/src/utils/crdt.ts

Line 476 in 48c1ebe

case 'editor':

Apologies, I will have them all open today and can give you better pointers.

youknowriad · 2025-10-07T18:31:41Z

Thanks for splitting the work into small PRs, this one is good to go :)

youknowriad · 2025-10-07T18:35:16Z

Note that I sent you an invite to join the Gutenberg team, which means you should be able to use branches instead of a fork and also can merge approved PRs

youknowriad · 2025-10-07T18:36:34Z

I invite you to check the different PR practices (labels, merging props...)

…cement for local state (WordPress#72114) Co-authored-by: chriszarate <czarate@git.wordpress.org> Co-authored-by: youknowriad <youknowriad@git.wordpress.org>

chriszarate added 4 commits October 6, 2025 14:05

Make syncing a side-concern instead of a replacement for local state

754fa60

Update dependencies test case

7d8fdf0

Call the (previously ignored) register method

8d3818d

Introduce the synced properties set and limit to blocks

a0270f5

chriszarate requested a review from nerrad as a code owner October 6, 2025 20:59

Revert "Update dependencies test case"

c45f270

This reverts commit 7d8fdf0.

youknowriad reviewed Oct 7, 2025

View reviewed changes

youknowriad approved these changes Oct 7, 2025

View reviewed changes

youknowriad merged commit c214929 into WordPress:trunk Oct 7, 2025
78 of 80 checks passed

youknowriad deleted the improve/sync-as-side-concern branch October 7, 2025 18:32

github-actions Bot added this to the Gutenberg 21.9 milestone Oct 7, 2025

youknowriad added [Type] Enhancement A suggestion for improvement. [Type] Experimental Experimental feature or API. [Feature] Real-time Collaboration Phase 3 of the Gutenberg roadmap around real-time collaboration and removed [Type] Enhancement A suggestion for improvement. labels Oct 7, 2025

ingeniumed mentioned this pull request Oct 10, 2025

Fix api doc generation for module re-exports #72228

Merged

This was referenced Oct 10, 2025

Move Yjs providers into subfolder #72224

Merged

Improve collaborative editing in sync package #72040

Closed

chriszarate mentioned this pull request Oct 21, 2025

Sync Engine and Real-Time Collaboration #52593

Open

19 tasks

danluu mentioned this pull request May 14, 2026

RTC: fix stale delete propagation issue (symptom: delete causes temporary divergence between clients, which heals to incorrect result with deleted content getting re-added) #78320

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Collaborative editing: Make syncing a side-concern instead of a replacement for local state#72114

Collaborative editing: Make syncing a side-concern instead of a replacement for local state#72114
youknowriad merged 5 commits into
WordPress:trunkfrom
Automattic:improve/sync-as-side-concern

chriszarate commented Oct 6, 2025

Uh oh!

github-actions Bot commented Oct 6, 2025 •

edited

Loading

Uh oh!

youknowriad Oct 7, 2025

Uh oh!

youknowriad Oct 7, 2025

Uh oh!

chriszarate Oct 7, 2025

Uh oh!

youknowriad Oct 7, 2025

Uh oh!

youknowriad Oct 7, 2025

Uh oh!

chriszarate Oct 7, 2025

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

chriszarate commented Oct 6, 2025

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Uh oh!

github-actions Bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

youknowriad Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

youknowriad Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

chriszarate Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

youknowriad Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

youknowriad Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

chriszarate Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

youknowriad commented Oct 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 6, 2025 •

edited

Loading