feat (update JS): Clarified how session replay works

docs/platforms/javascript/common/session-replay/index.mdx

@@ -270,7 +270,24 @@ Sentry.init({
 
 ### How Sampling Works
 
-Sampling begins as soon as a session starts. <PlatformIdentifier name="replays-session-sample-rate" /> is evaluated first. If it's sampled, the replay recording will begin. Otherwise, <PlatformIdentifier name="replays-on-error-sample-rate" /> is evaluated and if it's sampled, the integration will begin buffering the replay and will only upload it to Sentry if an error occurs. The remainder of the replay will behave similarly to a whole-session replay. 
+Sampling begins as soon as a session starts. When someone visits your application, sampling decisions happen in this order:
+
+1. **<PlatformIdentifier name="replays-session-sample-rate" /> is checked first**
+   - If sampled: Full session recording starts and is sent to Sentry in real-time
+   - If not sampled: Recording is buffered in memory only (last 60 seconds kept)
+
+2. **If an error occurs** (and session wasn't selected for full recording):
+   - <PlatformIdentifier name="replays-on-error-sample-rate" /> is checked
+   - If sampled: Buffered 60 seconds + rest of session is sent to Sentry
+   - If not sampled: Buffer is discarded, nothing sent
+
+**When data leaves your browser:**
+
+| Scenario | Data Sent to Sentry |
+|----------|---------------------|
+| Selected for session sampling | Immediately (real-time chunks) |
+| Not selected, no error occurs | Never (buffer discarded) |
+| Not selected, error occurs & sampled | After error (60s before + everything after) |
 
 Read more about <PlatformLink to="/session-replay/understanding-sessions/">understanding sessions</PlatformLink>.
 

docs/platforms/javascript/common/session-replay/understanding-sessions.mdx

@@ -49,7 +49,13 @@ In `session` mode, Replay will continuously record and send data to Sentry. Afte
 
 ## Buffer Mode
 
-In `buffer` mode, Replay will continuously record data, but won't send any of it. It will instead keep up to the last 60 seconds in memory. When an error occurs, `replaysOnErrorSampleRate` will be checked and if it's sampled, the replay will be uploaded to Sentry and continue recording normally. After 15 minutes of user inactivity, or a maximum duration of 60 minutes, the session will end and the replay will stop.
+In `buffer` mode, Replay will continuously record data, but won't send any of it. It stores the last 60 seconds of event logs in a memory ring buffer (approximately 2-5MB).
+
+<Alert level="info">
+**What's stored:** Web Session Replay captures lightweight DOM event logs (clicks, scrolls, mutations), not video files. These logs are automatically converted to video-like replays by Sentry's servers.
+</Alert>
+
+When an error occurs, `replaysOnErrorSampleRate` will be checked and if it's sampled, the buffered 60 seconds _before_ the error plus everything _after_ is uploaded to Sentry and recording continues normally. After 15 minutes of user inactivity, or a maximum duration of 60 minutes, the session will end and the replay will stop.
 
 ## Manually Add Replay Integration