Real-time collaboration: Add sync connection status handling

[shekharnwagh]

What?

Adds connection status tracking and error handling for real-time collaboration sync providers, including UI to inform users when synchronization is unavailable.

Why?

When using real-time collaboration, users need to know if their changes are being synced. Without connection status feedback, users may continue editing without realizing their work isn't being synced to other collaborators, leading to data loss.

This PR introduces a standardized system for sync providers to report their connection status and display appropriate UI when issues occur, ensuring users are always aware of their sync state.

Demo

GutenbergTrunkSyncConnectionHandling_20260206_1080.mp4

How?

Connection Status Tracking

Status reporting - Sync providers emit sync-connection-status events. The sync manager listens to these events and updates core-data state.

Three statuses - Providers report one of:

• connecting - Attempting to connect or reconnecting
• connected - Syncing normally
• disconnected - Cannot sync, with optional error details (code, message, description)

Core-data Store - New selectors and actions in @wordpress/core-data:

• Stores connection state for each synced entity (postType, postId)
• getSyncConnectionState() returns the aggregated current state (prioritizes disconnected, then connecting, then connected)

HTTP polling provider - The default provider reports status based on REST API availability, transitioning between statuses as REST API requests succeed or fail.

Disconnection Modal

Display behavior:

• On first page load: Waits 5 seconds before showing (prevents flash if connection establishes quickly)
• On subsequent disconnections: Shows immediately
• Remains visible until connection restores

Modal rendering - Uses BlockCanvasCover slot fill to display over the block editor canvas.

Error messages - Shows custom messages from SyncConnectionError when provided, or generic messages based on error code. Includes "Copy post content" button.

Context

Originally added to wpvip/rtc-plugin branch (PRs #74075, #74826, #74904).

Testing Instructions

Setup

1. Check out the PR branch and start your local development server.

2. Settings > Writing > Enable real-time collaboration

3. Enable debug here for logs:

   • gutenberg/packages/sync/src/providers/http-polling/http-polling-provider.ts

     Line 126 in 24f6331

     // debug: true,

4. Open a post in the editor and open your browser console. Filter console messages for "Status changed" to see connection status updates.

Test Disconnection

1. Open lib/compat/wordpress-7.0/collaboration.php and comment this line to disable the sync REST API:

   • https://github.com/Automattic/gutenberg/blob/166681bb454dcc395ceee88a69125ad534cc6216/lib/compat/wordpress-7.0/collaboration.php#L63

2. You should see a modal explaining the connection is lost with a "Copy post content" button

Test Reconnection

1. Uncomment this line in collaboration.php to re-enable the endpoint:
   • • https://github.com/Automattic/gutenberg/blob/166681bb454dcc395ceee88a69125ad534cc6216/lib/compat/wordpress-7.0/collaboration.php#L63
2. The modal should disappear within 30 seconds (depending on the backoff reached)
3. Check the console - status should transition from disconnected → connecting → connected

[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: shekharnwagh <shekharnwagh@git.wordpress.org>
Co-authored-by: alecgeatches <alecgeatches@git.wordpress.org>
Co-authored-by: ingeniumed <ingeniumed@git.wordpress.org>
Co-authored-by: chriszarate <czarate@git.wordpress.org>

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

[ingeniumed]

Should we be revealing this info, or make it a friendlier one like

The maximum number of collaborators have been reached.

That way it doesn't give away that the server is at max connection capacity, and make it a friendlier/understandable message for someone who may not be as technical.

[chriszarate]

It's a great point, but let's get a design or copywriter to review.

[ingeniumed]

@jarekmorawski or @jasmussen perhaps?

[ingeniumed]

Same thing. Don't think we should mention collaborative editing server.

[ingeniumed]

Same thing - don't think we should mention collaborative editing server.

[chriszarate]

@shekharnwagh I've made some updates to simplify the implementation and address some bugs:

• Remove actions and exports until they have a proven use case.
• Use the existing status event instead of introducing another synthetic event. This reduces the burden on provider implementors. For simple implementations, they can just rely on the default status events that are already emitted. If they want to vary the UI response by using our error codes, they can wrap the status event and embellish with an error (as we do in our plugin.
• Remove the ability to customize the copy in the error object. We don't yet have a use case, and it seems like filters might be a better approach.
• Update the term "sync connection state" to "connection status". Personal preference, but I've been thinking about this as fundamentally about connection status with an optional accompanying error.
• Prevent serialize from running too often.

[ingeniumed]

Need to get the connection messages reviewed by design, but I'm fine to do it in a follow up PR as well.

[shekharnwagh]

If they want to vary the UI response by using our error codes, they can wrap the status event and embellish with an error (as we do in our plugin.

@chriszarate We don't do that in RTC plugin, we use a new event - sync-connection-status. I tried the approach where the status event is intercepted and enriched, but it didn't feel the cleanest way to do it - mostly due to having to hack around type issues. Having a new event felt simpler, but open to giving that this approach a try.

[chriszarate]

Merging per our discussion and testing.