docs(realtime): add note about sync event behavior in Presence (#42338)

## What kind of change does this PR introduce?

Documentation improvement for Realtime Presence.

## What is the current behavior?

The Presence documentation doesn't explain that during a `sync` event,
clients may receive `join` and `leave` events simultaneously even when
no users are actually joining or leaving. This can be confusing for
developers new to Presence.

## What is the new behavior?

Added an explanatory note clarifying that:
- During `sync`, you may receive `join` and `leave` events at the same
time
- This is normal and expected
- It reflects state reconciliation with the server, not real user
movement

This helps developers understand this behavior upfront rather than
having to discover it through debugging.

## Additional context

As mentioned in the issue, this behavior is discussed in [this community
discussion](https://github.com/orgs/supabase/discussions/26748) where
the solution had to be discovered by users.

Fixes #41175

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Clarified behavior during sync events in the Realtime Presence guide.
Added explanation that simultaneous join and leave events may occur due
to state reconciliation rather than actual user movement changes.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Jonathan Fulton authored and GitHub committed 2026-02-19 08:08:08 +00:00
1 parent 3f05963630
commit 25f9f7c5e3
1 file changed
+6
@@ -20,6 +20,12 @@ When any client subscribes, disconnects, or updates their presence payload, Supa
- **`join`** — a new client has started tracking presence
- **`leave`** — a client has stopped tracking presence
<Admonition type="note" title="Sync event behavior">
During a `sync` event, you may receive `join` and `leave` events simultaneously, even though no users are actually joining or leaving. This is expected behavior—Presence reconciles its local state with the server state, which can trigger these events as part of the synchronization process. This reflects state reconciliation, not real user movement.
</Admonition>
The complete presence state returned by `presenceState()` looks like this:
```json