Files
ghostgram/submodules/Display/Source/NavigationKeyframes.swift
T
ichmagmaus111andClaude Opus 5.5 534cabe35b bug fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 16:55:08 +01:00

310 lines
14 KiB
Swift
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import Foundation
import UIKit
/// When a bake's animations begin.
public enum NavigationKeyframeOrigin: Equatable {
/// At the commit that carries them: `beginTime` is left for Core Animation to resolve, on the same origin as every
/// other animation added in that turn.
case atCommit
/// At this media time (`CACurrentMediaTime()`'s clock).
case explicit(Double)
}
/// The samples one bake takes and how its animations are timed. Sample times are seconds of animation time from the
/// origin. Under Slow Animations each animation keeps that logical duration and runs at `speed = 1 / factor`, as
/// `CAAnimationUtils` does (and CoreList: CLAUDE.md, "Slow Animations reaches the emitted animation as speed").
public struct NavigationKeyframeTiming: Equatable {
public static let samplesPerSecond: Double = 120.0
public let origin: NavigationKeyframeOrigin
public let duration: Double
public let factor: Double
public let sampleTimes: [Double]
public init(origin: NavigationKeyframeOrigin, duration: Double, factor: Double) {
self.origin = origin
self.duration = max(0.0, duration)
self.factor = factor > 0.0 ? factor : 1.0
var sampleTimes: [Double] = []
let count = Int((self.duration * NavigationKeyframeTiming.samplesPerSecond).rounded(.up))
for i in 0 ..< count {
sampleTimes.append(Double(i) / NavigationKeyframeTiming.samplesPerSecond)
}
sampleTimes.append(self.duration)
self.sampleTimes = sampleTimes
}
public func withOrigin(_ origin: NavigationKeyframeOrigin) -> NavigationKeyframeTiming {
return NavigationKeyframeTiming(origin: origin, duration: self.duration, factor: self.factor)
}
/// The same origin and factor, cut (or extended) to `duration`.
public func withDuration(_ duration: Double) -> NavigationKeyframeTiming {
return NavigationKeyframeTiming(origin: self.origin, duration: duration, factor: self.factor)
}
}
/// One property's keyframes: `values[i]` at `timing.sampleTimes[i]`, linear between them.
public func makeNavigationKeyframeAnimation(keyPath: String, values: [Any], timing: NavigationKeyframeTiming, layer: CALayer) -> CAKeyframeAnimation {
let animation = CAKeyframeAnimation(keyPath: keyPath)
let duration = max(timing.duration, 1.0 / NavigationKeyframeTiming.samplesPerSecond)
animation.values = values
animation.keyTimes = timing.sampleTimes.map { NSNumber(value: min(1.0, $0 / duration)) }
animation.calculationMode = .linear
animation.duration = duration
animation.speed = Float(1.0 / timing.factor)
animation.fillMode = .both
animation.isRemovedOnCompletion = true
if case let .explicit(time) = timing.origin {
animation.beginTime = layer.convertTime(time, from: nil)
}
if #available(iOS 15.0, *), UIScreen.main.maximumFramesPerSecond > 61 {
// UIKit's push/pop runs at this range (screen RE notes §4); ProMotion caps app-driven refresh otherwise.
animation.preferredFrameRateRange = CAFrameRateRange(minimum: 80.0, maximum: 120.0, preferred: 0.0)
}
return animation
}
/// Adds `values` on `layer` under `key`. Core Animation never runs an animation whose values are all equal, so then
/// nothing is added and an old animation under `key` is removed. The model value is the caller's to set. `owner` stamps
/// the animation for `removeNavigationKeyframes(from:key:owner:)`.
public func addNavigationKeyframes(to layer: CALayer, key: String, keyPath: String, values: [Any], timing: NavigationKeyframeTiming, owner: Int? = nil) {
guard let first = values.first as AnyObject?, values.contains(where: { !($0 as AnyObject).isEqual(first) }) else {
layer.removeAnimation(forKey: key)
return
}
let animation = makeNavigationKeyframeAnimation(keyPath: keyPath, values: values, timing: timing, layer: layer)
if let owner {
animation.setValue(NSNumber(value: owner), forKey: navigationKeyframeOwnerKey)
}
layer.add(animation, forKey: key)
}
private let navigationKeyframeOwnerKey = "navigationKeyframeOwner"
/// Removes the animation under `key` only if `owner` added it: a layer can pass from one transition to the next, and the
/// next one's keyframes are not the old one's to remove.
public func removeNavigationKeyframes(from layer: CALayer, key: String, owner: Int) {
if let stamp = layer.animation(forKey: key)?.value(forKey: navigationKeyframeOwnerKey) as? NSNumber, stamp.intValue == owner {
layer.removeAnimation(forKey: key)
}
}
/// The clock of one group of keyframe animations (a transition's screens, the glass capsules), like UIKit's dummy view
/// in its fluid transition: one animation on a layer of its own records where the group's animation time starts.
///
/// - A group's first bake begins at the commit; the model's origin is the bake's now until the commit resolves one,
/// which the clock then adopts (read back off the layer). A layer outside the render tree never resolves one.
/// - A bake that continues motion already on screen (a retarget, a release) begins explicitly at now, unless the
/// group's first commit is still pending, in which case it joins that commit.
/// - The group ends when Core Animation completes the clock animation. It also completes it, unfinished and at once,
/// for a layer that is not on screen or leaves it (measured in the app, spec §6 results), so a stop the group did
/// not cause ends it at once. Tests replace this with `schedule` (no render server runs in their process); the
/// group then ends at its analytic deadline, re-armed once the origin is adopted.
public final class NavigationAnimationClock {
public static let animationKey = "navigationClock"
/// Tests install a manual clock on every clock made.
public static var configureForTesting: ((NavigationAnimationClock) -> Void)?
public var now: () -> Double = {
return CACurrentMediaTime()
}
public var durationFactor: () -> Double = {
return UIView.animationDurationFactor()
}
/// Nil: the group's end and its marks come from Core Animation's completions. Tests set a manual scheduler.
public var schedule: ((_ delay: Double, _ action: @escaping () -> Void) -> Void)?
/// Nil: the host is on screen while it is in a window, where a commit resolves the origin. Tests standing in for the
/// commit set it (no window can be made in their process).
public var isHostOnScreen: (() -> Bool)?
/// An empty 1×1 layer in the host view: it draws nothing, so its moving position shows nothing.
public let layer: CALayer
private weak var hostView: UIView?
/// Called once when a group's deadline has passed on both the model's clock and Core Animation's.
public var ended: (() -> Void)?
public private(set) var timing: NavigationKeyframeTiming?
/// Media time of animation time 0: the bake's now, then the commit's once it resolves.
public private(set) var originTime: Double = 0.0
private var isOriginResolved = false
private var generation = 0
private var markCount = 0
public init(hostView: UIView) {
self.layer = CALayer()
self.layer.frame = CGRect(x: 0.0, y: 0.0, width: 1.0, height: 1.0)
self.hostView = hostView
hostView.layer.addSublayer(self.layer)
NavigationAnimationClock.configureForTesting?(self)
}
deinit {
self.layer.removeFromSuperlayer()
}
public var isRunning: Bool {
return self.timing != nil
}
/// Starts a group lasting `duration` seconds of animation time; returns the timing to bake it with. `continuing`:
/// the bake continues motion already on screen, so it begins now rather than at the commit.
public func start(duration: Double, continuing: Bool) -> NavigationKeyframeTiming {
let now = self.now()
let origin: NavigationKeyframeOrigin = (continuing && !self.isAwaitingCommit) ? .explicit(now) : .atCommit
let timing = NavigationKeyframeTiming(origin: origin, duration: duration, factor: self.durationFactor())
self.generation += 1
self.timing = timing
self.originTime = now
self.isOriginResolved = origin != .atCommit
let animation = CABasicAnimation(keyPath: "position")
animation.fromValue = NSValue(cgPoint: CGPoint(x: 0.0, y: 0.0))
animation.toValue = NSValue(cgPoint: CGPoint(x: 1.0, y: 1.0))
animation.duration = max(timing.duration, 1.0 / NavigationKeyframeTiming.samplesPerSecond)
animation.speed = Float(1.0 / timing.factor)
animation.fillMode = .both
animation.isRemovedOnCompletion = false
if case let .explicit(time) = origin {
animation.beginTime = self.layer.convertTime(time, from: nil)
}
let generation = self.generation
if let schedule = self.schedule {
self.layer.add(animation, forKey: NavigationAnimationClock.animationKey)
schedule(timing.duration * timing.factor, { [weak self] in
self?.deadlineReached(generation)
})
} else {
animation.delegate = NavigationAnimationCompletion({ [weak self] _ in
self?.clockAnimationStopped(generation)
})
self.layer.add(animation, forKey: NavigationAnimationClock.animationKey)
}
return timing
}
/// Takes the origin Core Animation resolved at the commit, once there is one.
public func adoptResolvedOrigin() {
guard self.timing != nil, !self.isOriginResolved, let animation = self.layer.animation(forKey: NavigationAnimationClock.animationKey), animation.beginTime > 0.0 else {
return
}
self.originTime = self.layer.convertTime(animation.beginTime, to: nil)
self.isOriginResolved = true
}
/// The first bake's commit has not happened yet (and will: the host is on screen).
private var isAwaitingCommit: Bool {
self.adoptResolvedOrigin()
return self.timing != nil && !self.isOriginResolved && (self.isHostOnScreen?() ?? (self.hostView?.window != nil))
}
/// Seconds of animation time since the origin at media time `time` (now by default), after adopting a resolved
/// origin. 0 when no group runs, and while the first commit is pending: nothing the group times has begun on screen
/// then, and the origin the commit resolves is later than the bake's now by the rest of the turn (tens of ms in a
/// heavy one), so a time read from the bake's now would step back when it resolves.
public func animationTime(at time: Double? = nil) -> Double {
guard let timing = self.timing, !self.isAwaitingCommit else {
return 0.0
}
return max(0.0, ((time ?? self.now()) - self.originTime) / timing.factor)
}
/// The timing to re-install part of the running group with, on its phase: explicit at its origin, or at the commit
/// while the first commit is still pending.
public var reinstallTiming: NavigationKeyframeTiming? {
guard let timing = self.timing else {
return nil
}
if self.isAwaitingCommit {
return timing.withOrigin(.atCommit)
}
return timing.withOrigin(.explicit(self.originTime))
}
/// Runs `action` when the group's animation time reaches `time`, unless the group is stopped or restarted first: at
/// the completion of a marker animation on the group's own origin (at once if its layer is off screen).
public func schedule(atAnimationTime time: Double, _ action: @escaping () -> Void) {
guard let timing = self.timing, let reinstallTiming = self.reinstallTiming else {
return
}
let generation = self.generation
let guarded: () -> Void = { [weak self] in
guard let self, self.generation == generation else {
return
}
action()
}
if let schedule = self.schedule {
schedule(max(0.0, (time - self.animationTime()) * timing.factor), guarded)
return
}
let marker = CABasicAnimation(keyPath: "opacity")
marker.fromValue = 1.0 as NSNumber
marker.toValue = 0.5 as NSNumber
marker.duration = max(time, 1.0 / NavigationKeyframeTiming.samplesPerSecond)
marker.speed = Float(1.0 / timing.factor)
marker.isRemovedOnCompletion = true
if case let .explicit(origin) = reinstallTiming.origin {
marker.beginTime = self.layer.convertTime(origin, from: nil)
}
marker.delegate = NavigationAnimationCompletion({ _ in
guarded()
})
self.markCount += 1
self.layer.add(marker, forKey: "\(NavigationAnimationClock.animationKey).mark\(self.markCount)")
}
public func stop() {
self.generation += 1
self.finish()
}
private func clockAnimationStopped(_ generation: Int) {
// Finished, or stopped because the layer is off screen or left it; the group's own replacements and stops have
// moved the generation on.
guard generation == self.generation, self.timing != nil else {
return
}
self.finish()
self.ended?()
}
private func deadlineReached(_ generation: Int) {
guard generation == self.generation, let timing = self.timing else {
return
}
self.adoptResolvedOrigin()
let remaining = self.originTime + timing.duration * timing.factor - self.now()
if remaining > 0.0005, let schedule = self.schedule {
schedule(remaining, { [weak self] in
self?.deadlineReached(generation)
})
return
}
self.finish()
self.ended?()
}
private func finish() {
self.timing = nil
self.isOriginResolved = false
self.layer.removeAllAnimations()
}
}
/// A Core Animation completion as a closure (the delegate is retained by its animation).
private final class NavigationAnimationCompletion: NSObject, CAAnimationDelegate {
private var completion: ((Bool) -> Void)?
init(_ completion: @escaping (Bool) -> Void) {
self.completion = completion
super.init()
}
func animationDidStop(_ anim: CAAnimation, finished flag: Bool) {
let completion = self.completion
self.completion = nil
completion?(flag)
}
}