Real-time collaboration: Remove ghost awareness state explicitly when refreshing

[alecgeatches]

What?

This PR explicitly disconnects users from awareness when the page is refreshed or otherwise navigated using the browser pagehide event.

Why?

When refreshing the page in real-time collaboration, the previous session's cursor stays around for a while. This can lead to confusion from ghost collaborators from the same user and have a negative visual impact:

Screen.Recording.2026-02-24.at.12.17.29.PM.mov

Clicking into a post and refreshing quickly creates several ghost users and cursors in trunk

How?

This PR explicitly sends a disconnect signal (null awareness update) on pagehide. From MDN:

If you're specifically trying to detect page unload events, the pagehide event is the best option.

The documentation above notes that this behavior works differently on mobile, but only in the way that it will NOT be explicitly fired if a user force-closes a browser in the background. This is fine, since awareness state will automatically be cleared out after a 30-second interval anyway.

---

We also apiFetch() with the keepalive: true option, which according to documentation:

This enables a fetch() request to, for example, send analytics at the end of a session even if the user navigates away from or closes the page.

The naming is a bit confusing but keepalive: true means the disconnect request can finish independent of the current page, so it's non-blocking to a refresh or navigation.

Testing Instructions

1. Check out this PR.
2. Ensure real-time collaboration is enabled via: WordPress Admin -> Settings -> Writing, and check the "Enable real-time collaboration" checkbox. Click the "Save Changes" button.
3. Open a post with two separate users in two tabs.
4. As user A, rapidly click into post content and refresh a few times.
5. You should observe that as user A you do not see ghost cursors persist from previous sessions. It's possible that if a disconnect signal takes a while you may see a prior cursor for up to 5 seconds, but much less than before.
6. As user B, you should see ghost cursors disappear after 5 seconds.

Screenshots

Here is the same demo as above but performed within this PR:

refresh-cursors-fixed.mov

I've also included a second user to see what this looks like to a third-party observer watching the same post.

Above we can see that user A (the left-hand side) never sees their cursor reappear, as their awareness data is removed during the refresh and no longer present after loading. User B has a short grace period for ghost cursors (5 seconds) before duplicate cursors are removed. This could be further improved but is relatively minor.

[chriszarate]

This feels related to #75829. @alecgeatches What do you think about using visibilitychange instead of pagehide? MDN notes:

The best event to use to signal the end of a user's session is the visibilitychange event. In browsers that don't support visibilitychange the pagehide event is the next-best alternative.

Do we want to hide presence indicators when the user is not actively "in" the session?

[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>
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.

[alecgeatches]

@alecgeatches What do you think about using visibilitychange instead of pagehide? MDN notes:

The best event to use to signal the end of a user's session is the visibilitychange event. In browsers that don't support visibilitychange the pagehide event is the next-best alternative.

Do we want to hide presence indicators when the user is not actively "in" the session?

@chriszarate I think this might be a step too far. As quoted above, pagehide is a better signal for "the page is done":

If you're specifically trying to detect page unload events, the pagehide event is the best option.

visibilitychange triggers for a ton of stuff:

This event fires with a visibilityState of hidden when a user navigates to a new page, switches tabs, closes the tab, minimizes or closes the browser, or, on mobile, switches from the browser to a different app.

This might make sense in a mobile-only context where switching tabs is more similar to exiting the session, but on a desktop I wouldn't expect switching tabs and minimizing to be a place where a user's session data is removed. This is also a bit simpler - we can fire and forget and don't need to worry about reinitializing a user if the tab is resumed.

[chriszarate]

Nitpick, but I'd rather see the parameters of these functions be consistent and accept SyncPayload[]. This mapping can be done in the calling code.

[alecgeatches]

Good idea! Removed sendDisconnect() in 7b1131b and added a non-blocking version of postSyncUpdate to call since it's essentially the same thing.

[alecgeatches]

I have created a backport PR for core here: WordPress/wordpress-develop#11049

[github-actions]

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