@webspatial/platform-visionos 1.6.1 → 2.0.0

package/web-spatial/model/element-motion/SpatializedElementAnimationManager.swift

@@ -0,0 +1,263 @@
+import Foundation
+import QuartzCore
+import simd
+import Spatial
+
+enum SpatializedElementAnimationManagerError: Error {
+    case animationNotFound(String)
+    case invalidTarget(String)
+    case invalidTimeline(String)
+}
+
+final class SpatializedElementAnimationManager: NSObject {
+    private var animations: [String: SpatializedElementAnimationObject] = [:]
+    private var displayLink: CADisplayLink?
+    private let sendWebMsg: ((String, Encodable) -> Void)?
+
+    init(sendWebMsg: ((String, Encodable) -> Void)? = nil) {
+        self.sendWebMsg = sendWebMsg
+        super.init()
+    }
+
+    func getAnimation(_ animationId: String) -> SpatializedElementAnimationObject? {
+        animations[animationId]
+    }
+
+    var hasActiveFrameDriver: Bool {
+        displayLink != nil
+    }
+
+    func createAnimation(
+        command: CreateSpatializedElementAnimationCommand,
+        target: SpatializedElement,
+        explicitAnimationId: String? = nil
+    ) throws -> SpatializedElementAnimationObject {
+        try Self.validateTimeline(command.timeline)
+        let targetKind = try Self.resolveTargetKind(for: target)
+        let writeAdapter = SpatializedElementAnimationWriteAdapter()
+        let sampler = SpatializedElementMotionTimelineSampler(
+            timeline: command.timeline,
+            baselineTransform: Self.decomposeTransform(from: writeAdapter.currentAffineTransform(for: target)),
+            baselineOpacity: writeAdapter.baselineOpacity(for: target)
+        )
+
+        let animation = SpatializedElementAnimationObject(
+            id: explicitAnimationId,
+            targetElement: target,
+            targetKind: targetKind,
+            timelineSampler: sampler,
+            duration: command.timeline.duration,
+            timingFunction: "linear",
+            delay: command.timeline.delay ?? 0,
+            speed: command.timeline.playbackRate ?? 1.0,
+            loopConfig: command.timeline.loop ?? .none,
+            sendWebMsg: sendWebMsg
+        )
+        register(animation)
+        return animation
+    }
+
+    /// Validates native timeline fields that affect frame-driver lifetime.
+    private static func validateTimeline(_ timeline: SpatializedMotionTimelinePayload) throws {
+        if let playbackRate = timeline.playbackRate,
+           !playbackRate.isFinite || playbackRate <= 0
+        {
+            throw SpatializedElementAnimationManagerError.invalidTimeline("playbackRate must be > 0 and finite")
+        }
+    }
+
+    /// Resolves the native animation target kind from the concrete element subtype.
+    private static func resolveTargetKind(for target: SpatializedElement) throws -> SpatializedElementAnimationTargetKind {
+        if target is SpatializedStatic3DElement {
+            return .static3d
+        }
+        if target is SpatializedDynamic3DElement {
+            return .dynamic3d
+        }
+        if target is Spatialized2DElement {
+            return .spatialized2d
+        }
+        throw SpatializedElementAnimationManagerError.invalidTarget("unsupported element type \(String(describing: type(of: target)))")
+    }
+
+    func controlAnimation(_ command: ControlSpatializedElementAnimationCommand) throws {
+        guard let animation = animations[command.animationId] else {
+            throw SpatializedElementAnimationManagerError.animationNotFound(command.animationId)
+        }
+
+        let timestamp = CACurrentMediaTime()
+        switch command.type {
+        case "play":
+            animation.play(at: timestamp)
+        case "pause":
+            animation.pause(at: timestamp)
+        case "resume":
+            animation.resume(at: timestamp)
+        case "stop":
+            animation.stop(at: timestamp)
+        case "reset":
+            animation.reset(at: timestamp)
+        case "finish":
+            animation.finish(at: timestamp)
+        case "destroy":
+            animation.destroy()
+        default:
+            throw SpatializedElementAnimationManagerError.invalidTarget("unknown control type \(command.type)")
+        }
+
+        refreshDisplayLink()
+    }
+
+    func destroyAnimation(_ animationId: String) {
+        animations[animationId]?.destroy()
+        refreshDisplayLink()
+    }
+
+    func destroyAnimationsForElement(_ elementId: String) {
+        let ids = animations.values.filter { $0.targetElementId == elementId }.map { $0.uuid }
+        for id in ids {
+            animations[id]?.destroy()
+        }
+        refreshDisplayLink()
+    }
+
+    func removeAll() {
+        let current = Array(animations.values)
+        for animation in current {
+            animation.destroy()
+        }
+        animations.removeAll()
+        stopDisplayLink()
+    }
+
+    func tickAll(timestamp: CFTimeInterval) {
+        let current = Array(animations.values)
+        for animation in current {
+            animation.tick(at: timestamp)
+        }
+        refreshDisplayLink()
+    }
+
+    private func register(_ animation: SpatializedElementAnimationObject) {
+        var animation = animation
+        animations[animation.uuid] = animation
+        animation.on(event: SpatialObject.Events.BeforeDestroyed.rawValue) { [weak self] object, _ in
+            guard let self = self, let animation = object as? SpatializedElementAnimationObject else { return }
+            self.animations.removeValue(forKey: animation.uuid)
+            self.refreshDisplayLink()
+        }
+        refreshDisplayLink()
+    }
+
+    private func refreshDisplayLink() {
+        if animations.values.contains(where: { $0.isAnimating }) {
+            ensureDisplayLinkRunning()
+        } else {
+            stopDisplayLink()
+        }
+    }
+
+    private func ensureDisplayLinkRunning() {
+        guard displayLink == nil else { return }
+        let link = CADisplayLink(target: self, selector: #selector(onFrame(_:)))
+        link.preferredFrameRateRange = CAFrameRateRange(minimum: 60, maximum: 90, preferred: 90)
+        link.add(to: .main, forMode: .common)
+        displayLink = link
+    }
+
+    private func stopDisplayLink() {
+        displayLink?.invalidate()
+        displayLink = nil
+    }
+
+    @objc private func onFrame(_ link: CADisplayLink) {
+        tickAll(timestamp: CACurrentMediaTime())
+    }
+
+    static func decomposeTransform(from transform: AffineTransform3D) -> SpatializedMotionTransformComponents {
+        if transform == .identity {
+            return .identity
+        }
+
+        let m = transform.matrix
+        let tx = m.columns.3.x
+        let ty = m.columns.3.y
+        let tz = m.columns.3.z
+
+        let col0 = SIMD3<Double>(m.columns.0.x, m.columns.0.y, m.columns.0.z)
+        let col1 = SIMD3<Double>(m.columns.1.x, m.columns.1.y, m.columns.1.z)
+        let col2 = SIMD3<Double>(m.columns.2.x, m.columns.2.y, m.columns.2.z)
+
+        var sx = simd_length(col0)
+        let sy = simd_length(col1)
+        let sz = simd_length(col2)
+
+        guard sx > 1e-10, sy > 1e-10, sz > 1e-10 else {
+            return SpatializedMotionTransformComponents(
+                translateX: tx, translateY: ty, translateZ: tz,
+                rotateX: 0, rotateY: 0, rotateZ: 0,
+                scaleX: sx, scaleY: sy, scaleZ: sz
+            )
+        }
+
+        // Preserve an odd reflection on the X scale so the normalized rotation remains proper.
+        let determinant = simd_determinant(simd_double3x3(columns: (col0, col1, col2)))
+        if determinant < 0 {
+            sx = -sx
+        }
+
+        let r00 = col0.x / sx; let r10 = col0.y / sx; let r20 = col0.z / sx
+        let r11 = col1.y / sy; let r21 = col1.z / sy
+        let r12 = col2.y / sz; let r22 = col2.z / sz
+
+        let cosY = sqrt(r00 * r00 + r10 * r10)
+        let rotY = atan2(-r20, cosY)
+        let rotX: Double
+        let rotZ: Double
+
+        if cosY > 1e-6 {
+            rotX = atan2(r21, r22)
+            rotZ = atan2(r10, r00)
+        } else {
+            rotX = atan2(-r12, r11)
+            rotZ = 0
+        }
+
+        let rad2deg = 180.0 / Double.pi
+        return SpatializedMotionTransformComponents(
+            translateX: tx, translateY: ty, translateZ: tz,
+            rotateX: rotX * rad2deg,
+            rotateY: rotY * rad2deg,
+            rotateZ: rotZ * rad2deg,
+            scaleX: sx, scaleY: sy, scaleZ: sz
+        )
+    }
+
+    static func composeTransform(_ transform: SpatializedMotionTransformComponents) -> AffineTransform3D {
+        let deg2rad = Double.pi / 180.0
+
+        let cosX = cos(transform.rotateX * deg2rad)
+        let sinX = sin(transform.rotateX * deg2rad)
+        let cosY = cos(transform.rotateY * deg2rad)
+        let sinY = sin(transform.rotateY * deg2rad)
+        let cosZ = cos(transform.rotateZ * deg2rad)
+        let sinZ = sin(transform.rotateZ * deg2rad)
+
+        let r00 = cosY * cosZ
+        let r01 = sinX * sinY * cosZ - cosX * sinZ
+        let r02 = cosX * sinY * cosZ + sinX * sinZ
+        let r10 = cosY * sinZ
+        let r11 = sinX * sinY * sinZ + cosX * cosZ
+        let r12 = cosX * sinY * sinZ - sinX * cosZ
+        let r20 = -sinY
+        let r21 = sinX * cosY
+        let r22 = cosX * cosY
+
+        let col0 = simd_double4(r00 * transform.scaleX, r10 * transform.scaleX, r20 * transform.scaleX, 0)
+        let col1 = simd_double4(r01 * transform.scaleY, r11 * transform.scaleY, r21 * transform.scaleY, 0)
+        let col2 = simd_double4(r02 * transform.scaleZ, r12 * transform.scaleZ, r22 * transform.scaleZ, 0)
+        let col3 = simd_double4(transform.translateX, transform.translateY, transform.translateZ, 1)
+
+        return AffineTransform3D(truncating: simd_double4x4(columns: (col0, col1, col2, col3)))
+    }
+}

package/web-spatial/model/element-motion/SpatializedElementAnimationObject.swift

@@ -0,0 +1,399 @@
+import Foundation
+import QuartzCore
+import Spatial
+
+final class SpatializedElementAnimationObject: SpatialObject {
+    let targetElementId: String
+    weak var targetElement: SpatializedElement?
+    let targetKind: SpatializedElementAnimationTargetKind
+    let timelineSampler: SpatializedElementMotionTimelineSampler
+    let writeAdapter: SpatializedElementAnimationWriteAdapter
+    private let sendWebMsg: ((String, Encodable) -> Void)?
+
+    private let duration: TimeInterval
+    private let delay: TimeInterval
+    private let timingFunction: SpatializedMotionTimingFunction
+    private let speed: Double
+    private let loopConfig: SpatializedMotionLoopConfig
+
+    private(set) var animatesTransform: Bool
+    private(set) var animatesOpacity: Bool
+
+    private var isReversed = false
+
+    private(set) var playState: SpatializedElementAnimationPlayState = .idle
+    private(set) var finished = false
+
+    private var startTime: CFTimeInterval = 0
+    private var pausedDuration: CFTimeInterval = 0
+    private var pauseStartTime: CFTimeInterval = 0
+    private var delayCompleted = false
+    private var createdTime: CFTimeInterval = 0
+    /// Tracks whether the current playback session has emitted its first-frame lifecycle event.
+    private var hasEmittedStartEvent = false
+
+    var isAnimating: Bool {
+        playState == .running
+    }
+
+    var isPaused: Bool {
+        playState == .paused
+    }
+
+    var uuid: String {
+        spatialId
+    }
+
+    init(
+        id: String? = nil,
+        targetElement: SpatializedElement,
+        targetKind: SpatializedElementAnimationTargetKind,
+        timelineSampler: SpatializedElementMotionTimelineSampler,
+        duration: Double,
+        timingFunction: String,
+        delay: Double,
+        speed: Double = 1.0,
+        loopConfig: SpatializedMotionLoopConfig = .none,
+        sendWebMsg: ((String, Encodable) -> Void)? = nil
+    ) {
+        targetElementId = targetElement.spatialId
+        self.targetElement = targetElement
+        self.targetKind = targetKind
+        self.timelineSampler = timelineSampler
+        writeAdapter = SpatializedElementAnimationWriteAdapter()
+        self.duration = duration
+        self.delay = delay
+        self.timingFunction = SpatializedMotionTimingFunction.from(name: timingFunction)
+        self.speed = speed
+        self.loopConfig = loopConfig
+        self.sendWebMsg = sendWebMsg
+        animatesTransform = timelineSampler.animatesTransform
+        animatesOpacity = timelineSampler.animatesOpacity
+
+        if let id {
+            super.init(id)
+        } else {
+            super.init()
+        }
+    }
+
+    func play(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        if isPaused {
+            resume(at: timestamp)
+            return
+        }
+
+        // Preserve session semantics: play() while already running is a no-op.
+        guard playState != .running else {
+            return
+        }
+
+        startFreshPlayback(at: timestamp)
+    }
+
+    func pause(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        guard playState == .running else {
+            return
+        }
+
+        let values = currentValues(at: timestamp)
+        applySample(values)
+        playState = .paused
+        pauseStartTime = timestamp
+        emitStateChanged(action: "pause", playState: .paused, values: values)
+    }
+
+    func resume(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        guard playState == .paused else {
+            return
+        }
+
+        playState = .running
+        pausedDuration += timestamp - pauseStartTime
+        emitStateChanged(action: "resume", playState: .running, values: currentValues(at: timestamp))
+    }
+
+    func stop(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        guard playState == .running || playState == .paused else {
+            return
+        }
+
+        let values = currentValues(at: timestamp)
+        playState = .idle
+        finished = false
+        applySample(values)
+        releaseMask()
+        emitStateChanged(action: "stop", playState: .idle, values: values)
+    }
+
+    func reset(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        let values = sampleValues(at: 0)
+        resetTimingState()
+        playState = .idle
+        finished = false
+        applySample(values)
+        releaseMask()
+        emitStateChanged(action: "reset", playState: .idle, values: values)
+    }
+
+    func finish(at timestamp: CFTimeInterval = CACurrentMediaTime()) {
+        // A finished session has already emitted its terminal event.
+        guard playState != .finished else {
+            return
+        }
+
+        let values = sampleValues(at: duration)
+        resetTimingState()
+        playState = .finished
+        finished = true
+        applySample(values)
+        releaseMask()
+        emitStateChanged(action: "finish", playState: .finished, values: values)
+    }
+
+    func tick(at timestamp: CFTimeInterval) {
+        guard playState == .running else {
+            return
+        }
+
+        guard shouldStartAnimation(at: timestamp) else {
+            return
+        }
+
+        if !hasEmittedStartEvent {
+            let values = currentValues(at: timestamp)
+            applySample(values)
+            emitStartEventIfNeeded(values: values)
+            if isIterationComplete(at: timestamp) {
+                let completedValues = sampleValues(at: duration)
+                applySample(completedValues)
+                playState = .finished
+                finished = true
+                releaseMask()
+                emitStateChanged(action: "complete", playState: .finished, values: completedValues)
+            }
+            return
+        }
+
+        if isIterationComplete(at: timestamp) {
+            switch loopConfig {
+            case .none:
+                let values = sampleValues(at: duration)
+                applySample(values)
+                playState = .finished
+                finished = true
+                releaseMask()
+                emitStateChanged(action: "complete", playState: .finished, values: values)
+            case .resetLoop:
+                applySample(sampleValues(at: 0))
+                resetForNextIteration(at: timestamp)
+            case .reverseLoop:
+                isReversed.toggle()
+                resetForNextIteration(at: timestamp)
+            }
+            return
+        }
+
+        applySample(currentValues(at: timestamp))
+    }
+
+    override func onDestroy() {
+        playState = .idle
+        finished = false
+        releaseMask()
+        emitStateChanged(action: "destroy", playState: .idle)
+    }
+
+    private func startFreshPlayback(at timestamp: CFTimeInterval) {
+        createdTime = timestamp
+        startTime = timestamp
+        pausedDuration = 0
+        pauseStartTime = 0
+        delayCompleted = delay <= 0
+        isReversed = false
+        finished = false
+        hasEmittedStartEvent = false
+        guard lockMask() else {
+            playState = .idle
+            emitStateChanged(
+                action: "error",
+                playState: .idle,
+                values: currentValues(at: timestamp),
+                error: SpatializedElementAnimationErrorPayload(
+                    code: "mask-conflict",
+                    message: "Another animation is already writing this target"
+                )
+            )
+            return
+        }
+        playState = .running
+        let startValues = sampleValues(at: 0)
+        applySample(startValues)
+        emitStateChanged(action: "play", playState: .running, values: startValues)
+        if delay <= 0 {
+            emitStartEventIfNeeded(values: startValues)
+        }
+    }
+
+    private func lockMask() -> Bool {
+        guard let element = targetElement else { return false }
+        return writeAdapter.acquireMask(
+            on: element,
+            animationId: uuid,
+            animatesTransform: animatesTransform,
+            animatesOpacity: animatesOpacity
+        )
+    }
+
+    private func releaseMask() {
+        guard let element = targetElement else { return }
+        writeAdapter.releaseMaskAndApplyPending(on: element, animationId: uuid)
+    }
+
+    private func currentValues(at timestamp: CFTimeInterval) -> SpatializedMotionValuesPayload {
+        let progress = currentProgress(at: timestamp)
+        return sampleValues(at: progress * duration)
+    }
+
+    private func sampleValues(at timeSec: Double) -> SpatializedMotionValuesPayload {
+        let sample = timelineSampler.sampleTransformAndOpacity(at: timeSec)
+        return buildValuesPayload(
+            transform: sample.transform,
+            opacity: sample.opacity,
+            animatesTransform: animatesTransform,
+            animatesOpacity: animatesOpacity
+        )
+    }
+
+    private func applySample(_ values: SpatializedMotionValuesPayload) {
+        guard let element = targetElement else { return }
+
+        if let transform = values.transform,
+           writeAdapter.shouldAllowTransformWrite(on: element, animationId: uuid)
+        {
+            let components = SpatializedMotionTransformComponents(
+                translateX: transform.translate?.x ?? 0,
+                translateY: transform.translate?.y ?? 0,
+                translateZ: transform.translate?.z ?? 0,
+                rotateX: transform.rotate?.x ?? 0,
+                rotateY: transform.rotate?.y ?? 0,
+                rotateZ: transform.rotate?.z ?? 0,
+                scaleX: transform.scale?.x ?? 1,
+                scaleY: transform.scale?.y ?? 1,
+                scaleZ: transform.scale?.z ?? 1
+            )
+            writeAdapter.applyAffine(SpatializedElementAnimationManager.composeTransform(components), to: element)
+        }
+
+        if let opacity = values.opacity,
+           writeAdapter.shouldAllowOpacityWrite(on: element, animationId: uuid)
+        {
+            writeAdapter.applyOpacity(opacity, to: element)
+        }
+    }
+
+    private func buildValuesPayload(
+        transform: SpatializedMotionTransformComponents,
+        opacity: Double,
+        animatesTransform: Bool,
+        animatesOpacity: Bool
+    ) -> SpatializedMotionValuesPayload {
+        var transformPayload: SpatializedMotionTransformPayload? = nil
+        var opacityPayload: Double? = nil
+
+        if animatesTransform {
+            transformPayload = SpatializedMotionTransformPayload(
+                translate: Vec3Payload(x: transform.translateX, y: transform.translateY, z: transform.translateZ),
+                rotate: Vec3Payload(x: transform.rotateX, y: transform.rotateY, z: transform.rotateZ),
+                scale: Vec3Payload(x: transform.scaleX, y: transform.scaleY, z: transform.scaleZ)
+            )
+        }
+
+        if animatesOpacity {
+            opacityPayload = opacity
+        }
+
+        return SpatializedMotionValuesPayload(
+            transform: transformPayload,
+            opacity: opacityPayload
+        )
+    }
+
+    private func emitStateChanged(
+        action: String,
+        playState: SpatializedElementAnimationPlayState,
+        values: SpatializedMotionValuesPayload? = nil,
+        error: SpatializedElementAnimationErrorPayload? = nil
+    ) {
+        guard let sendWebMsg else { return }
+        sendWebMsg(uuid, SpatialAnimationStateChanged(
+            animationId: uuid,
+            action: action,
+            playState: playState,
+            finished: finished,
+            values: values,
+            error: error
+        ))
+    }
+
+    private func shouldStartAnimation(at timestamp: CFTimeInterval) -> Bool {
+        if delayCompleted {
+            return true
+        }
+        let elapsed = timestamp - createdTime - pausedDuration
+        if elapsed >= delay {
+            delayCompleted = true
+            startTime = timestamp
+            // Delay-window pauses are already accounted for above; active playback starts with a fresh pause clock.
+            pausedDuration = 0
+            pauseStartTime = 0
+            return true
+        }
+        return false
+    }
+
+    /// Emits a one-time start lifecycle event when playback reaches its first sampled frame.
+    private func emitStartEventIfNeeded(values: SpatializedMotionValuesPayload) {
+        guard !hasEmittedStartEvent else {
+            return
+        }
+        hasEmittedStartEvent = true
+        emitStateChanged(action: "start", playState: .running, values: values)
+    }
+
+    private func currentProgress(at timestamp: CFTimeInterval) -> Double {
+        let raw = rawProgress(at: timestamp)
+        let eased = timingFunction.evaluate(raw)
+        return isReversed ? (1.0 - eased) : eased
+    }
+
+    private func rawProgress(at timestamp: CFTimeInterval) -> Double {
+        guard delayCompleted else { return 0 }
+        let elapsed = (samplingTimestamp(for: timestamp) - startTime - pausedDuration) * speed
+        return min(max(elapsed / duration, 0.0), 1.0)
+    }
+
+    private func isIterationComplete(at timestamp: CFTimeInterval) -> Bool {
+        guard delayCompleted else { return false }
+        let elapsed = (timestamp - startTime - pausedDuration) * speed
+        return elapsed >= duration
+    }
+
+    private func resetForNextIteration(at timestamp: CFTimeInterval) {
+        startTime = timestamp
+        pausedDuration = 0
+    }
+
+    private func resetTimingState() {
+        startTime = 0
+        pausedDuration = 0
+        pauseStartTime = 0
+        createdTime = 0
+        delayCompleted = false
+        isReversed = false
+    }
+
+    private func samplingTimestamp(for timestamp: CFTimeInterval) -> CFTimeInterval {
+        isPaused ? pauseStartTime : timestamp
+    }
+}

package/web-spatial/model/element-motion/SpatializedElementAnimationTypes.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+enum SpatializedElementAnimationTargetKind: String, Codable {
+    case spatialized2d
+    case static3d
+    case dynamic3d
+}
+
+enum SpatializedElementAnimationPlayState: String, Codable {
+    case idle
+    case running
+    case paused
+    case finished
+}
+
+struct SpatializedElementAnimationErrorPayload: Codable {
+    let code: String
+    let message: String
+}
+
+struct SpatialAnimationStateChanged: Encodable {
+    let type: SpatialWebMsgType = .animationstatechange
+    let animationId: String
+    let action: String
+    let playState: SpatializedElementAnimationPlayState
+    let finished: Bool
+    let values: SpatializedMotionValuesPayload?
+    let error: SpatializedElementAnimationErrorPayload?
+
+    init(
+        animationId: String,
+        action: String,
+        playState: SpatializedElementAnimationPlayState,
+        finished: Bool,
+        values: SpatializedMotionValuesPayload? = nil,
+        error: SpatializedElementAnimationErrorPayload? = nil
+    ) {
+        self.animationId = animationId
+        self.action = action
+        self.playState = playState
+        self.finished = finished
+        self.values = values
+        self.error = error
+    }
+}