pause method

Implementation

SdkResult<GameSessionSnapshot> pause(GamePauseReason reason) {
  final current = snapshot.value;
  if (current.isTerminal) return _reject('Terminal session cannot pause');
  if (current.phase != GameSessionPhase.playing &&
      current.phase != GameSessionPhase.paused) {
    return _reject('Session is not playing');
  }
  final reasons = {...current.pauseReasons, reason};
  final wasPaused = current.phase == GameSessionPhase.paused;
  snapshot.value = current.copyWith(
    phase: GameSessionPhase.paused,
    pauseReasons: reasons,
  );
  // BUG-90: record the phase change in `events` (this session's history)
  // — only on the FIRST pause (playing -> paused), not every subsequent
  // overlapping pause reason (e.g. system pausing on top of an already
  // user-paused session), since the phase itself doesn't change again
  // until the session is fully resumed.
  if (!wasPaused) events.add(GameSessionPhase.paused);
  // ENH-96: the timeline records every pause-reason change (even one
  // that doesn't move the observable phase) — see `_recordPauseReasons`'
  // doc for why this differs from `events`' coarser phase-only history.
  _recordPauseReasons(reasons);
  return SdkSuccess(snapshot.value);
}