docs(realtime): document presence and auto-reconnect

Add Presence and Auto-reconnect subsections to the README Realtime
section. Presence documents onPresenceSync/onPresenceJoin/onPresenceLeave,
track(), untrack(), and presenceState(). Auto-reconnect documents the
ClientOptions flags (realtimeAutoReconnect, realtimeReconnectBaseDelay,
realtimeReconnectMaxDelay) and the behaviour of run() vs poll().
Remove presence and automatic reconnection from the "out of scope" note.

Extend ReadmeRealtimeTest with assertions for onPresenceSync and
realtimeAutoReconnect. Add Unreleased CHANGELOG entries for both features.

Author: Victor Hernández

CHANGELOG.md

@@ -9,6 +9,21 @@ backward-compatible features and patch releases contain fixes.
 
 ## [Unreleased]
 
+### Added
+- **Realtime — Presence**: `Channel` now supports `onPresenceSync(callable)`,
+  `onPresenceJoin(callable)`, `onPresenceLeave(callable)`, `track(array $payload)`,
+  `untrack()`, and `presenceState(): array<string, list<array<string, mixed>>>`.
+  The server sends `presence_state` (full sync) and `presence_diff` (join/leave
+  deltas) Phoenix frames; the `Presence` class merges them and fires the registered
+  callbacks. Presence is opt-in: passing `presence_key` in channel params or
+  registering any presence callback enables it in the `phx_join` config.
+- **Realtime — Auto-reconnect**: opt-in via
+  `ClientOptions(realtimeAutoReconnect: true, realtimeReconnectBaseDelay: 1.0,
+  realtimeReconnectMaxDelay: 30.0)`. When enabled, `run()` detects connection
+  drops, waits with exponential backoff (capped at `realtimeReconnectMaxDelay`),
+  reconnects, and re-subscribes all channels that were `joined` or `joining`.
+  `poll()` users remain responsible for their own reconnection.
+
 ## [0.5.2] - 2026-06-28
 
 ### Added

README.md

@@ -168,6 +168,60 @@ $realtime->disconnect();
 Prefer your own loop? Call `poll(float $timeout)` repeatedly instead of `run()`,
 and `stop()` to break out of `run()` from inside a callback.
 
+### Presence
+
+Track which clients are online and get notified when they join or leave. Register
+callbacks with `onPresenceSync`, `onPresenceJoin`, and `onPresenceLeave` before
+calling `subscribe()`, then call `track()` to broadcast your own state:
+
+```php
+$channel = $realtime->channel('room-1')
+    ->onPresenceSync(function (): void {
+        // Fired every time the full presence state is (re)synced — on join and
+        // after every diff. Read the current snapshot with presenceState().
+    })
+    ->onPresenceJoin(function (string $key, array $currentPresences, array $newPresences): void {
+        // A client started tracking; $newPresences lists their state payloads.
+    })
+    ->onPresenceLeave(function (string $key, array $currentPresences, array $leftPresences): void {
+        // A client stopped tracking.
+    })
+    ->subscribe();
+
+// Announce your own state (any serialisable array):
+$channel->track(['user_id' => 42, 'online_at' => time()]);
+
+// Read the current snapshot:
+// array<string, list<array<string, mixed>>>  (keyed by presence_ref)
+$state = $channel->presenceState();
+
+// Stop broadcasting (leaves the channel's presence):
+$channel->untrack();
+```
+
+### Auto-reconnect
+
+By default the client does not reconnect after a dropped connection. Pass
+`realtimeAutoReconnect: true` to make `run()` reconnect with exponential backoff
+and automatically re-subscribe all active channels:
+
+```php
+$client = new Client('https://YOUR-PROJECT.supabase.co', 'YOUR-ANON-KEY', new ClientOptions(
+    webSocketFactory: new MyWebSocketConnectionFactory(),
+    realtimeAutoReconnect: true,
+    realtimeReconnectBaseDelay: 1.0,  // initial retry delay in seconds (default)
+    realtimeReconnectMaxDelay: 30.0,  // cap on retry delay in seconds (default)
+));
+
+$realtime = $client->realtime();
+$realtime->connect();
+// ... subscribe channels ...
+$realtime->run(); // loops forever; reconnects + re-subscribes if the socket drops
+```
+
+When driving the loop yourself with `poll()`, reconnection is not automatic.
+After a receive error, call `connect()` again and re-subscribe your channels.
+
 ### Implementing `WebSocketConnection`
 
 `WebSocketConnection` is a small contract you back with any WebSocket client.
@@ -246,8 +300,7 @@ handshake, adds headers, applies a read timeout on every `receive()` call, and
 auto-responds to WebSocket-level ping frames via phrity's `PingResponder`
 middleware.
 
-> Out of scope for this release: presence, automatic reconnection, and automatic
-> access-token refresh. Recreate the connection on disconnect to reconnect.
+> Out of scope for this release: automatic access-token refresh.
 
 ## Auth (GoTrue)
 

tests/Realtime/ReadmeRealtimeTest.php

@@ -13,5 +13,7 @@
         ->and($readme)->toContain('webSocketFactory')
         ->and($readme)->toContain('onPostgresChanges')
         ->and($readme)->not->toContain('**Planned:**')
-        ->and($readme)->toContain('Realtime (postgres changes & broadcast)');
+        ->and($readme)->toContain('Realtime (postgres changes & broadcast)')
+        ->and($readme)->toContain('onPresenceSync')
+        ->and($readme)->toContain('realtimeAutoReconnect');
 });