Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: SPChat/Core/Streaming/ReplayCursor.swift3// Description: Pure state machine of the conversation Replay: position among the recorded events, play / pause, speed, and the delay before the next step derived from the real gap between two events.4import Foundation56/// Replay steps through the recorded events of a timeline, in the server's order. The cursor holds no event content:7/// only their timestamps, so that the pause between two steps is proportional to the real gap (clamped).8public struct ReplayCursor: Sendable, Equatable {9 public enum Speed: Int, Sendable, CaseIterable, Identifiable {10 case x1 = 1, x2 = 2, x4 = 411 public var id: Int { rawValue }12 public var label: String { "\(rawValue)×" }13 public var next: Speed { switch self { case .x1: .x2; case .x2: .x4; case .x4: .x1 } }14 }1516 /// Timestamps of the events (nil when the server sent none for an event).17 public private(set) var times: [Date?]18 /// Event under the cursor; nil = replay not started.19 public private(set) var index: Int?20 public private(set) var isPlaying = false21 public var speed: Speed = .x122 /// Seconds of replay per second of real time (a 10 s gap is replayed in 2.5 s at 1×).23 public var timeScale: Double = 0.2524 /// Bounds of the pause between two steps at 1×.25 public var minDelay: TimeInterval = 0.426 public var maxDelay: TimeInterval = 2.52728 public init(times: [Date?] = []) { self.times = times }2930 public var count: Int { times.count }31 public var isEmpty: Bool { times.isEmpty }32 public var isAtEnd: Bool { index.map { $0 >= count - 1 } ?? false }33 public var canStepBack: Bool { (index ?? 0) > 0 }34 public var canStepForward: Bool { !isEmpty && (index.map { $0 < count - 1 } ?? true) }35 /// 0…1 position for the scrubber (0 before the first step).36 public var progress: Double {37 guard let index, count > 1 else { return index == nil ? 0 : 1 }38 return Double(index) / Double(count - 1)39 }4041 /// The list was reloaded: the position is kept when it still exists, playback stops when nothing is left to play.42 public mutating func reload(times newTimes: [Date?]) {43 times = newTimes44 if let i = index, i >= newTimes.count { index = newTimes.isEmpty ? nil : newTimes.count - 1 }45 if isEmpty || isAtEnd { isPlaying = false }46 }4748 /// Moves to the next event. Returns false (and stops playing) at the end.49 @discardableResult50 public mutating func stepForward() -> Bool {51 guard canStepForward else { isPlaying = false; return false }52 index = index.map { $0 + 1 } ?? 053 if isAtEnd { isPlaying = false }54 return true55 }5657 @discardableResult58 public mutating func stepBack() -> Bool {59 guard let i = index, i > 0 else { return false }60 index = i - 1; return true61 }6263 public mutating func seek(to target: Int) {64 guard !isEmpty else { index = nil; return }65 index = min(max(target, 0), count - 1)66 if isAtEnd { isPlaying = false }67 }6869 /// Scrubber: 0…1 → nearest event.70 public mutating func seek(progress: Double) {71 guard !isEmpty else { return }72 seek(to: Int((min(max(progress, 0), 1) * Double(count - 1)).rounded()))73 }7475 /// Starts playing. From the end (or before the first step) it starts over at the first event.76 public mutating func play() {77 guard !isEmpty else { return }78 if index == nil || isAtEnd { index = 0 }79 isPlaying = count > 1 && !isAtEnd80 }81 public mutating func pause() { isPlaying = false }82 public mutating func toggle() { if isPlaying { pause() } else { play() } }83 public mutating func stop() { isPlaying = false; index = nil }84 public mutating func cycleSpeed() { speed = speed.next }8586 /// Real time elapsed between the event under the cursor and the next one (nil when a timestamp is missing).87 public var gapToNext: TimeInterval? {88 guard let i = index, i + 1 < count, let a = times[i], let b = times[i + 1] else { return nil }89 return max(0, b.timeIntervalSince(a))90 }9192 /// Pause before the next step while playing: the real gap × `timeScale`, clamped to `minDelay…maxDelay`, divided by the93 /// speed. nil when there is no next event. A missing timestamp gives the minimum pause.94 public var delayToNext: TimeInterval? {95 guard let i = index, i + 1 < count else { return nil }96 let base = gapToNext.map { min(max($0 * timeScale, minDelay), maxDelay) } ?? minDelay97 return base / Double(speed.rawValue)98 }99}100