Add lifecycle event hooks (on('start') / on('stop')) to notify when replay state changes

[behnammodi]

Problem Statement

When using replayIntegration in manual mode, there is no way for external code to know when the replay has stopped due to internal reasons such as maxReplayDuration expiry.

This makes it impossible to keep external state in sync with the actual replay state. For example, a wrapper library that tracks active replay sessions via an activeSession array has no way to know when Sentry has internally stopped the replay — leading to stale state where the wrapper believes recording is still active when it is not.

The problem is not limited to maxReplayDuration. Any internal stop (error budget, rate limiting, idle timeout) has the same issue.

Solution Brainstorm

Add lifecycle event hooks to the Replay integration following the same client.on(event, callback) pattern already established in @sentry/core:

const replay = getReplay(); 
 
replay.on('start', () => { 
 console.log('Replay started');
}); 
 
replay.on('stop', ({ reason }) => { 
 // reason: 'maxDuration' | 'manual' | 'error' | 'inactivity' | ...
 console.log('Replay stopped, reason:', reason); 
});

The reason field on the stop event would be particularly valuable — it lets consumers distinguish between an intentional manual stop and an internally triggered one, so they can decide whether to restart recording or just update their state.

Additional Context

No response

Priority

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it.}

[linear-code]

JS-2160

[logaretm]

Thanks for the suggestion, I will raise this with the team this week to figure out next steps since it is a public facing API.

Your suggestion seems reasonable so I will use it as basis. I will post updated here as they come.