Add public Replay start/stop API

[sentry-junior]

Replay needs a clearly public, documented API for manual lifecycle control.

• Today there are shipped controls for Replay lifecycle management, but they are not presented as a clear top-level SDK API and are easy to miss.
• Existing work such as Give better APIs to control start, stop, and sampling of replays sentry-javascript#7540 and Improve usability of Replay SDK public APIs (start/stop/flush) sentry-javascript#12810 focused on behavior and usability of the current controls, but this still leaves a gap in developer-facing API clarity and documentation.
• We should provide and document an explicit public API for starting, stopping, and querying Replay state, with ergonomic no-op semantics where possible.
• This should be documented in product docs, not just package-level implementation docs, and the recommended usage should not require users to discover or retain an integration instance ad hoc.

Action taken on behalf of David Cramer.

[linear-code]

JS-2348

DOCS-2646

[sentry-junior]

new info after re-checking docs: the gap is not that manual replay lifecycle control is undocumented.

• the public docs already cover this in platforms/javascript/session-replay/understanding-sessions/:
  • #manually-starting-replay
  • #manually-stopping-replay
  • examples using Sentry.getReplay().start(), startBuffering(), stop(), and flush()
• the docs explicitly state that when both replay sample rates are 0, replay is installed but inactive until manually started.
• the docs also clarify some ergonomics that earlier issues called out, including:
  • start() / startBuffering() are safe no-ops when a session is already running
  • flush() while stopped starts a new session recording

so the original issue body overstates the docs gap. i think the ticket is still directionally valid if we narrow it to one of these product gaps instead:

• make manual replay lifecycle control feel like an intentionally supported top-level API, not just "methods on the integration instance you happen to fetch"
• improve discoverability from the main replay setup/onboarding path, since the guidance exists but is buried in the deeper "understanding sessions" page
• clarify the recommended pattern and API contract around lifecycle/state inspection (getReplay(), nullability, state/query helpers, start/stop semantics)

i'd either:

• keep this issue open but retitle/re-scope it around discoverability + API ergonomics, or
• close it only if we believe the current API shape is good enough and this was purely a docs miss

action taken on behalf of David Cramer.

[sentry-junior]

additional context from follow-up review and user feedback:

• manual replay lifecycle control is documented in the public docs, including getReplay().start(), startBuffering(), stop(), and flush(): https://docs.sentry.io/platforms/javascript/session-replay/understanding-sessions/#manually-starting-replay
• there is also in-flight docs work around replay lifecycle hooks: feat: added replay lifecycle hooks docs #17598
• that shifts the issue away from “this is undocumented” and more toward discoverability / onboarding / product framing. junior itself initially missed the docs page, which is kind of the point.
• ryan also raised an API-shape concern: requiring users to retain or rediscover an ad hoc integration instance is not ideal, but moving everything onto the top-level Sentry object could create misleading no-op APIs when Replay is not installed. so “just add top-level methods” may not actually be the right fix.
• additional product feedback from the original user ask: they want to be able to automatically buffer/capture a replay when user feedback is captured. that suggests the real gap may be less about raw start() / stop() existence and more about a clearer onboarding story plus first-class lifecycle patterns for adjacent product flows like feedback capture.

so i think the issue is still valid, but should stay scoped around one or more of:

• improve Replay control discoverability from setup/onboarding docs
• document recommended lifecycle patterns more clearly
• evaluate whether feedback capture should have an opinionated Replay hook / recipe
• consider a more intentional public control surface only if it avoids misleading no-op behavior

Action taken on behalf of David Cramer.

[mydea]

moving this to docs repo, as there is nothing to do here IMHO.