@swiftbrowser/native 0.17.6 → 0.17.7

package/src/runtime.ts

@@ -11,7 +11,8 @@
  * `atob`, `btoa`, `fetch` with `Headers`, `Request`, `Response`,
  * `AbortController` and `AbortSignal`, `URL`, `URLSearchParams`, `crypto`
  * (`getRandomValues`, `randomUUID`), `localStorage`, `structuredClone`,
- * `navigator`, `Image` (image.ts, on a bridge with `probeImage`) with the
+ * `navigator` (with `mediaSession` and `MediaMetadata` on a bridge with
+ * `mediaSession`, mediaSession.ts), `Image` (image.ts, on a bridge with `probeImage`) with the
  * bridge's `__sbImageProbed`, `Worker` (worker.ts) with the bridge's
  * `__sbWorkerMessage` and `__sbWorkerError`, `__sbOpenURL` (openURL.ts),
  * and the bridge's callbacks `__sbTimerFired` and `__sbFetchResult`. In a
@@ -28,6 +29,7 @@ import { createFetch } from './fetch';
 import { createImageGlobals } from './image';
 import { SimpleURL, SimpleURLSearchParams } from './url';
 import { installWorkerScope, NativeWorker } from './worker';
+import { createMediaSession, NativeMediaMetadata } from './mediaSession';
 import { receiveOpenURL } from './openURL';
 
 type AnyGlobal = Record<string, unknown>;
@@ -207,14 +209,22 @@ export function installRuntime(native: NativeBridge, target: AnyGlobal = globalT
 
   define('structuredClone', <T>(value: T): T => (value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T)));
 
-  define('navigator', {
+  const navigator: Record<string, unknown> = {
     userAgent: 'SwiftBrowserNative',
     language: native.locale().replace('_', '-'),
     languages: [native.locale().replace('_', '-')],
     onLine: true,
     platform: 'iOS',
     hardwareConcurrency: 1,
-  });
+  };
+  // What plays, for the lock screen and the media keys (mediaSession.ts); not in a worker.
+  const mediaSession = native.mediaSession && !native.workerPostMessage ? createMediaSession(native) : null;
+  if (mediaSession) navigator['mediaSession'] = mediaSession.session;
+  define('navigator', navigator);
+  if (mediaSession) {
+    define('MediaMetadata', NativeMediaMetadata);
+    define('__sbMediaSessionCommand', mediaSession.receive);
+  }
 
   if (native.workerPostMessage) {
     installed.push(...installWorkerScope(native, target));

package/swift/Sources/SwiftBrowserNative/Host/HostBridge.swift

@@ -28,6 +28,7 @@ import FoundationBridge // the shim's Foundation stand-ins (ShimAliases.swift)
 /// | `openURL(url)` | the system opener |
 /// | `locale()` | the viewer's locale identifier |
 /// | `launchArguments()` | the process's arguments (`-screen list` from a scheme or `simctl launch`) |
+/// | `mediaSession(update)` | `navigator.mediaSession`: the lock screen's now-playing info and the remote commands the app handles, on MediaPlayer (NowPlayingBridge.swift); a command the viewer gives comes to `__sbMediaSessionCommand(json)` |
 /// | `workerStart(id, name, engine)`, `workerPost(id, text)`, `workerTerminate(id)` | workers (JavaScriptCore only): a `JSContext` on a thread (`"context"`, WorkerHost.swift) or a hidden web view with WebKit's JIT (`"webview"`, WebViewWorkerHost.swift); their messages come to `__sbWorkerMessage(id, text)`, their errors to `__sbWorkerError(id, message)` |
 ///
 /// Everything JavaScript-facing runs on the main thread; work that is not
@@ -42,6 +43,9 @@ final class HostBridge {
     #endif
     private let logger = Logger(subsystem: "swiftbrowser", category: "js")
     private let session = URLSession(configuration: .default)
+    #if canImport(MediaPlayer)
+    private var nowPlaying: NowPlayingBridge?
+    #endif
     /// Keys of `localStorage` live under this prefix in `UserDefaults`.
     static let storagePrefix = "swiftbrowser.storage."
 
@@ -192,6 +196,16 @@ final class HostBridge {
 
         host.install("launchArguments") { _ in .array(ProcessInfo.processInfo.arguments.map(JSONValue.string)) }
 
+        #if canImport(MediaPlayer)
+        host.install("mediaSession") { [weak self] arguments in
+            guard let self, let update = arguments.first?.string else { return .string("mediaSession: expected a JSON string") }
+            if nowPlaying == nil {
+                nowPlaying = NowPlayingBridge { [weak self] command in self?.callIn("__sbMediaSessionCommand", [.string(command.json)]) }
+            }
+            return nowPlaying?.update(update).map(JSONValue.string)
+        }
+        #endif
+
         #if canImport(JavaScriptCore)
         host.install("workerStart") { [weak self] arguments in
             guard let self, let id = arguments[safe: 0]?.int, let name = arguments[safe: 1]?.string else {

package/swift/Sources/SwiftBrowserNative/Host/NowPlayingBridge.swift

@@ -0,0 +1,190 @@
+#if canImport(SwiftUI) && canImport(MediaPlayer)
+import Foundation
+import MediaPlayer
+import SwiftBrowserProtocol
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+#if os(iOS) && canImport(AVFoundation)
+import AVFoundation
+#endif
+#if canImport(FoundationBridge)
+import FoundationBridge
+#endif
+
+/// The app's `navigator.mediaSession` (packages/native/src/mediaSession.ts)
+/// on MediaPlayer: each `mediaSession(update)` sets `MPNowPlayingInfoCenter`
+/// (the lock screen's title, artist, album and artwork, the position the
+/// system extrapolates at the rate) and makes `MPRemoteCommandCenter`
+/// listen for exactly the commands the app handles; a command the viewer
+/// gives (a lock screen button, the media keys, the system's player
+/// controls) goes back as `__sbMediaSessionCommand(json)`. The update is
+/// the one the web renderer's `mediaSession` request carries
+/// (docs/ops-protocol.md, "Now playing"), so an app writes the same code
+/// for the page and the native app. Against the shim (the round trip) the
+/// MediaPlayer here is the shim's, which hands the same to the page.
+@MainActor
+final class NowPlayingBridge {
+    private let send: (JSONValue) -> Void
+    /// The target added to each command listened for, by the protocol's name.
+    private var targets: [String: Any] = [:]
+    private var artworkURL: String?
+    private var artwork: MPMediaItemArtwork?
+    private var artworkLoad: Task<Void, Never>?
+    private var info: [String: Any]?
+    #if os(iOS)
+    private var sessionReady = false
+    #endif
+
+    /// `send` hands a received command to the app.
+    init(send: @escaping (JSONValue) -> Void) {
+        self.send = send
+    }
+
+    /// Applies one update; the message of what was wrong with it, or nil.
+    func update(_ json: String) -> String? {
+        let parsed: JSONValue
+        do {
+            parsed = try JSONValue.parse(json)
+        } catch {
+            return "mediaSession: \(error)"
+        }
+        guard let fields = parsed.object else { return "mediaSession: expected an object" }
+        apply(fields)
+        return nil
+    }
+
+    private func apply(_ fields: JSONObject) {
+        let center = MPNowPlayingInfoCenter.default()
+        if let metadata = fields.object("metadata") {
+            var next: [String: Any] = [:]
+            if let title = metadata.string("title") { next[MPMediaItemPropertyTitle] = title }
+            if let artist = metadata.string("artist") { next[MPMediaItemPropertyArtist] = artist }
+            if let album = metadata.string("album") { next[MPMediaItemPropertyAlbumTitle] = album }
+            if let position = fields.object("position") {
+                if let duration = position.double("duration") { next[MPMediaItemPropertyPlaybackDuration] = duration }
+                if let elapsed = position.double("position") { next[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsed }
+                if let rate = position.double("rate") { next[MPNowPlayingInfoPropertyPlaybackRate] = rate }
+            }
+            if let state = fields.string("playbackState"), fields.object("position") == nil {
+                // No position: the state alone says whether it plays, through the rate.
+                next[MPNowPlayingInfoPropertyPlaybackRate] = state == "playing" ? 1.0 : 0.0
+            }
+            info = next
+            loadArtwork(metadata.string("artwork"))
+            publish()
+        } else if fields["metadata"] == .null {
+            info = nil
+            artwork = nil
+            artworkURL = nil
+            artworkLoad?.cancel()
+            center.nowPlayingInfo = nil
+        }
+        if let state = fields.string("playbackState") {
+            #if os(macOS) || canImport(FoundationBridge)
+            center.playbackState = state == "playing" ? .playing : state == "paused" ? .paused : .unknown
+            #endif
+            #if os(iOS)
+            // The lock screen shows the app that plays through an active playback session.
+            if state == "playing" { activateAudioSession() }
+            #endif
+        }
+        if let commands = fields.array("commands") {
+            listen(for: Set(commands.compactMap(\.string)))
+        }
+    }
+
+    /// The info with the artwork, as the center takes it whole.
+    private func publish() {
+        guard var next = info else { return }
+        if let artwork { next[MPMediaItemPropertyArtwork] = artwork }
+        MPNowPlayingInfoCenter.default().nowPlayingInfo = next
+    }
+
+    /// The artwork at `url` (a `data:` URL at once, a remote one through a fetch), once per URL.
+    private func loadArtwork(_ url: String?) {
+        guard url != artworkURL else { return }
+        artworkURL = url
+        artwork = nil
+        artworkLoad?.cancel()
+        guard let url else { return }
+        if url.hasPrefix("data:") {
+            if let comma = url.firstIndex(of: ","), let data = Data(base64Encoded: String(url[url.index(after: comma)...])) {
+                artwork = Self.artwork(from: data)
+            }
+            return
+        }
+        guard let remote = URL(string: url) else { return }
+        artworkLoad = Task { [weak self] in
+            guard let (data, _) = try? await URLSession.shared.data(from: remote), !Task.isCancelled else { return }
+            guard let self, self.artworkURL == url else { return }
+            self.artwork = Self.artwork(from: data)
+            self.publish()
+        }
+    }
+
+    private static func artwork(from data: Data) -> MPMediaItemArtwork? {
+        #if canImport(UIKit)
+        guard let image = UIImage(data: data) else { return nil }
+        #elseif canImport(AppKit)
+        guard let image = NSImage(data: data) else { return nil }
+        #endif
+        return MPMediaItemArtwork(boundsSize: image.size) { _ in image }
+    }
+
+    #if os(iOS)
+    private func activateAudioSession() {
+        guard !sessionReady else { return }
+        sessionReady = true
+        let session = AVAudioSession.sharedInstance()
+        try? session.setCategory(.playback, mode: .default)
+        try? session.setActive(true)
+    }
+    #endif
+
+    // MARK: Remote commands
+
+    /// The protocol's command names and the center's commands.
+    private var commands: [(name: String, command: MPRemoteCommand)] {
+        let center = MPRemoteCommandCenter.shared()
+        return [
+            ("play", center.playCommand),
+            ("pause", center.pauseCommand),
+            ("stop", center.stopCommand),
+            ("nextTrack", center.nextTrackCommand),
+            ("previousTrack", center.previousTrackCommand),
+            ("seekTo", center.changePlaybackPositionCommand),
+            ("skipForward", center.skipForwardCommand),
+            ("skipBackward", center.skipBackwardCommand),
+        ]
+    }
+
+    /// Listens for exactly `wanted`: a target for each new one, none for the
+    /// dropped ones, and every other command disabled (the system enables them
+    /// all to begin with; the protocol says the others get no button).
+    private func listen(for wanted: Set<String>) {
+        for (name, command) in commands {
+            let listening = targets[name] != nil
+            if wanted.contains(name), !listening {
+                if let skip = command as? MPSkipIntervalCommand, skip.preferredIntervals.isEmpty { skip.preferredIntervals = [15] }
+                targets[name] = command.addTarget { [weak self] event in
+                    var fields: JSONObject = ["command": .string(name)]
+                    if let seek = event as? MPChangePlaybackPositionCommandEvent { fields["position"] = .number(seek.positionTime) }
+                    if let skip = event as? MPSkipIntervalCommandEvent { fields["interval"] = .number(skip.interval) }
+                    // Called on the main thread; a hop keeps the app's handler out of the system's callback.
+                    DispatchQueue.main.async {
+                        MainActor.assumeIsolated { self?.send(.object(fields)) }
+                    }
+                    return .success
+                }
+            } else if !wanted.contains(name), listening {
+                command.removeTarget(targets.removeValue(forKey: name))
+            }
+            let enabled = wanted.contains(name)
+            if command.isEnabled != enabled { command.isEnabled = enabled }
+        }
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/ShimAliases.swift

@@ -24,4 +24,6 @@ public typealias HTTPURLResponse = FoundationBridge.HTTPURLResponse
 public typealias URLCache = FoundationBridge.URLCache
 public typealias CachedURLResponse = FoundationBridge.CachedURLResponse
 public typealias DispatchQueue = FoundationBridge.DispatchQueue
+// The shim's players post their notifications through the bridge's center.
+public typealias NotificationCenter = FoundationBridge.NotificationCenter
 #endif

package/swift/Sources/SwiftBrowserNative/Views/ElementView.swift

@@ -82,6 +82,8 @@ struct ElementView: View {
         case "toolbar", "searchfield":
             // Taken by the enclosing screen; in place they draw nothing.
             return AnyView(EmptyView())
+        // Media
+        case "video": return AnyView(VideoElement(node: node))
         // Shapes and colors
         case "color": return AnyView(ColorElement(node: node))
         case "shape": return ShapeElement(node: node).reportingSize(of: node)

package/swift/Sources/SwiftBrowserNative/Views/Kinds/Controls.swift

@@ -179,16 +179,18 @@ struct SliderElement: View {
             set: { app?.dispatch(.slide(node.id, $0)) }
         )
         let range = props.min...max(props.min, props.max)
+        // The drag's start and end, with the value then (`onEditingChanged`).
+        let editing = { (editing: Bool) -> Void in app?.dispatch(.slide(node.id, SliderProps(props: node.props).value, editing: editing)) }
         if node.children.isEmpty {
             if let step = props.step, step > 0 {
-                Slider(value: value, in: range, step: step)
+                Slider(value: value, in: range, step: step, onEditingChanged: editing)
             } else {
-                Slider(value: value, in: range)
+                Slider(value: value, in: range, onEditingChanged: editing)
             }
         } else if let step = props.step, step > 0 {
-            Slider(value: value, in: range, step: step) { ChildrenView(node: node) }
+            Slider(value: value, in: range, step: step, label: { ChildrenView(node: node) }, onEditingChanged: editing)
         } else {
-            Slider(value: value, in: range) { ChildrenView(node: node) }
+            Slider(value: value, in: range, label: { ChildrenView(node: node) }, onEditingChanged: editing)
         }
     }
 }

package/swift/Sources/SwiftBrowserNative/Views/Kinds/Navigation.swift

@@ -204,8 +204,11 @@ struct ScreenToolbar: ToolbarContent {
 }
 
 /// One `toolbar` element: a `ToolbarSpacer` for a `spacer` (iOS 26; a
-/// `Spacer` item before it), else an item with the element's children,
-/// without the bar's shared glass when `sharedBackground` is `hidden` (iOS 26).
+/// `Spacer` item before it), else the element's children as items of its
+/// placement (a `ToolbarItemGroup`: the protocol's `toolbar` holds the
+/// items of one run, as the page lays them out side by side; in one
+/// `ToolbarItem` iOS 26 shows only the first), without the bar's shared
+/// glass when `sharedBackground` is `hidden` (iOS 26).
 struct ToolbarElement: ToolbarContent {
     let node: ElementNode
 
@@ -220,12 +223,12 @@ struct ToolbarElement: ToolbarContent {
             }
         } else if props.sharedBackground == "hidden" {
             if #available(iOS 26, macOS 26, *) {
-                ToolbarItem(placement: placement) { ChildrenView(node: node) }.sharedBackgroundVisibility(.hidden)
+                ToolbarItemGroup(placement: placement) { ChildrenView(node: node) }.sharedBackgroundVisibility(.hidden)
             } else {
-                ToolbarItem(placement: placement) { ChildrenView(node: node) }
+                ToolbarItemGroup(placement: placement) { ChildrenView(node: node) }
             }
         } else {
-            ToolbarItem(placement: placement) { ChildrenView(node: node) }
+            ToolbarItemGroup(placement: placement) { ChildrenView(node: node) }
         }
     }
 }

package/swift/Sources/SwiftBrowserNative/Views/Kinds/Video.swift

@@ -0,0 +1,304 @@
+#if canImport(SwiftUI) && canImport(AVFoundation)
+import AVFoundation
+import AVKit
+import Foundation
+import SwiftBrowserProtocol
+import SwiftBrowserTree
+import SwiftUI
+#if canImport(FoundationBridge)
+import FoundationBridge
+#endif
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// `video` (docs/ops-protocol.md, "Video and audio"): an `AVPlayer` over the
+/// element's URL, drawn by AVKit's `VideoPlayer` with the system's controls
+/// (`controls`), else by a bare player layer at the element's `gravity`.
+/// The props drive the player (the item, mute, volume, rate, play and
+/// pause, each `seek` serial once) and the player reports back with the
+/// `video` events the page sends: `ready` with the duration and size,
+/// `time` while playing (every `report` seconds), `status`, `seeked`,
+/// `ended`, `error`, and `play` / `pause` when the viewer uses the
+/// controls. An element at no size plays its audio with nothing on
+/// screen, as the page's hidden element does for a player shown nowhere.
+///
+/// Built against the shim too (the round trip): the player there is the
+/// shim's, which plays in the page; what iOS alone has (watching the
+/// player's own state for the viewer's play and pause) is gated.
+struct VideoElement: View {
+    let node: ElementNode
+    @Environment(\.nativeApp) private var app
+    @State private var controller = VideoController()
+
+    var body: some View {
+        let props = VideoProps(props: node.props)
+        content(props)
+            .background(Color.black)
+            .onAppear {
+                controller.attach(id: node.id, app: app)
+                controller.apply(props)
+            }
+            .onChange(of: props) { _, now in controller.apply(now) }
+            .onDisappear { controller.detach() }
+    }
+
+    @ViewBuilder private func content(_ props: VideoProps) -> some View {
+        // A finite proposal is taken as is; an axis left open follows the
+        // video's aspect ratio (16:9 before the metadata), as on the page.
+        let ratio = (props.width ?? 0) > 0 && (props.height ?? 0) > 0 ? props.width! / props.height! : 16.0 / 9.0
+        if props.controls {
+            VideoPlayer(player: controller.player).aspectRatio(ratio, contentMode: .fit)
+        } else {
+            PlayerLayerView(player: controller.player, gravity: props.gravity).aspectRatio(ratio, contentMode: props.gravity == "resizeAspect" ? .fit : .fill)
+        }
+    }
+}
+
+/// A bare `AVPlayerLayer` (no controls) at the element's gravity.
+#if canImport(UIKit)
+private struct PlayerLayerView: UIViewRepresentable {
+    let player: AVPlayer
+    let gravity: String
+
+    final class LayerView: UIView {
+        override class var layerClass: AnyClass { AVPlayerLayer.self }
+        var playerLayer: AVPlayerLayer { layer as! AVPlayerLayer }
+    }
+
+    func makeUIView(context: Context) -> LayerView {
+        let view = LayerView()
+        view.playerLayer.player = player
+        view.playerLayer.videoGravity = videoGravity
+        return view
+    }
+
+    func updateUIView(_ view: LayerView, context: Context) {
+        if view.playerLayer.player !== player { view.playerLayer.player = player }
+        if view.playerLayer.videoGravity != videoGravity { view.playerLayer.videoGravity = videoGravity }
+    }
+
+    private var videoGravity: AVLayerVideoGravity {
+        switch gravity {
+        case "resizeAspectFill": .resizeAspectFill
+        case "resize": .resize
+        default: .resizeAspect
+        }
+    }
+}
+#else
+/// macOS: AVKit's player view, which has no controls option; the protocol's `controls` is for iOS and the page.
+private struct PlayerLayerView: View {
+    let player: AVPlayer
+    let gravity: String
+    var body: some View { VideoPlayer(player: player) }
+}
+#endif
+
+/// The player behind one `video` element, kept across the view's renders:
+/// applies each change of props and reports the player's events.
+@MainActor
+final class VideoController {
+    let player = AVPlayer()
+    private var id = 0
+    private weak var app: NativeApp?
+    private var applied: VideoProps?
+    private var url: String?
+    private var timeObserver: Any?
+    private var notifications: [Any] = []
+    private var loading: Task<Void, Never>?
+    private var ready = false
+    private var ended = false
+    #if !canImport(FoundationBridge)
+    private var stateObservation: NSKeyValueObservation?
+    #endif
+
+    func attach(id: Int, app: NativeApp?) {
+        self.id = id
+        self.app = app
+    }
+
+    /// Carries the props out, in the page's order: the item, mute and volume
+    /// (before any play), rate, a new seek, then play or pause.
+    func apply(_ props: VideoProps) {
+        if props.url != url { replace(props.url) }
+        if player.isMuted != props.muted { player.isMuted = props.muted }
+        let volume = Float(props.volume)
+        if player.volume != volume { player.volume = volume }
+        if props.report != applied?.report { observeTime(every: props.report ?? 0.25) }
+        if props.seekSerial != applied?.seekSerial {
+            seek(to: props.seekTime, serial: props.seekSerial)
+        }
+        let wasPlaying = applied?.playing ?? false
+        if props.playing, props.url != nil {
+            let rate = Float(props.rate > 0 ? props.rate : 1)
+            if player.rate != rate {
+                ended = false
+                player.rate = rate
+            }
+            if !wasPlaying { report("status", ["status": .string(ready ? "playing" : "waiting"), "time": .number(time)]) }
+        } else if player.rate != 0 {
+            player.pause()
+            if wasPlaying { report("status", ["status": .string("paused"), "time": .number(time)]) }
+        }
+        applied = props
+    }
+
+    func detach() {
+        loading?.cancel()
+        loading = nil
+        player.pause()
+        unobserve()
+        if let timeObserver {
+            player.removeTimeObserver(timeObserver)
+            self.timeObserver = nil
+        }
+        applied = nil
+    }
+
+    private var time: Double {
+        let seconds = player.currentTime().seconds
+        return seconds.isFinite ? seconds : 0
+    }
+
+    /// A new URL: a new item, watched for its end and its failure, probed for its metadata.
+    private func replace(_ url: String?) {
+        loading?.cancel()
+        unobserve()
+        self.url = url
+        ready = false
+        ended = false
+        guard let url, let parsed = URL(string: url) else {
+            player.replaceCurrentItem(with: nil)
+            if let url { report("error", ["url": .string(url), "code": .number(4), "message": .string("not a URL: \(url)")]) }
+            return
+        }
+        let item = AVPlayerItem(url: parsed)
+        player.replaceCurrentItem(with: item)
+        let center = NotificationCenter.default
+        notifications.append(center.addObserver(forName: .AVPlayerItemDidPlayToEndTime, object: item, queue: .main) { [weak self] _ in
+            Task { @MainActor in self?.playedToEnd(url) }
+        })
+        notifications.append(center.addObserver(forName: .AVPlayerItemFailedToPlayToEndTime, object: item, queue: .main) { [weak self] notification in
+            let message = (notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error)?.localizedDescription ?? "playback failed"
+            Task { @MainActor in self?.report("error", ["url": .string(url), "code": .number(2), "message": .string(message)]) }
+        })
+        notifications.append(center.addObserver(forName: .AVPlayerItemPlaybackStalled, object: item, queue: .main) { [weak self] _ in
+            Task { @MainActor in
+                guard let self else { return }
+                self.report("status", ["status": .string("waiting"), "time": .number(self.time)])
+            }
+        })
+        #if !canImport(FoundationBridge)
+        // The viewer's own play and pause (the system's controls), as changes the props did not ask for.
+        stateObservation = player.observe(\.timeControlStatus, options: [.new]) { [weak self] player, _ in
+            let status = player.timeControlStatus
+            Task { @MainActor in self?.playerChanged(to: status, url: url) }
+        }
+        #endif
+        loading = Task { [weak self] in
+            await self?.probe(item, url: url)
+        }
+    }
+
+    #if !canImport(FoundationBridge)
+    /// The player's state changed: the viewer's play or pause when the props
+    /// asked for the opposite (a pause at the item's end is the end, not the
+    /// viewer), else playback starting as asked.
+    private func playerChanged(to status: AVPlayer.TimeControlStatus, url: String) {
+        guard let applied, self.url == url else { return }
+        switch status {
+        case .playing where !applied.playing:
+            report("play", ["time": .number(time)])
+        case .paused where applied.playing && !ended && ready && !atEnd:
+            report("pause", ["time": .number(time)])
+        case .playing where applied.playing:
+            report("status", ["status": .string("playing"), "time": .number(time)])
+        default:
+            break
+        }
+    }
+
+    /// Whether the item is at (or within a frame of) its end.
+    private var atEnd: Bool {
+        guard let duration = player.currentItem?.duration, duration.isNumeric else { return false }
+        return time >= duration.seconds - 0.05
+    }
+    #endif
+
+    /// `ready`: the duration and the video's size, once the asset says; `error` when it cannot be read.
+    private func probe(_ item: AVPlayerItem, url: String) async {
+        let asset = item.asset
+        do {
+            let duration = try await asset.load(.duration)
+            var width = 0.0
+            var height = 0.0
+            if let track = try await asset.loadTracks(withMediaType: .video).first {
+                let size = try await track.load(.naturalSize)
+                width = size.width
+                height = size.height
+            }
+            guard !Task.isCancelled, self.url == url else { return }
+            ready = true
+            let seconds = duration.seconds
+            report("ready", [
+                "url": .string(url),
+                "duration": seconds.isFinite && duration.isNumeric ? .number(seconds) : .null,
+                "width": .number(width),
+                "height": .number(height),
+                "time": .number(time),
+            ])
+            if applied?.playing == true { report("status", ["status": .string("playing"), "time": .number(time)]) }
+        } catch {
+            guard !Task.isCancelled, self.url == url else { return }
+            report("error", ["url": .string(url), "code": .number(4), "message": .string(error.localizedDescription)])
+        }
+    }
+
+    private func seek(to seconds: Double, serial: Int) {
+        ended = false
+        player.seek(to: CMTime(seconds: seconds, preferredTimescale: 600)) { [weak self] finished in
+            guard finished else { return }
+            Task { @MainActor in
+                guard let self else { return }
+                self.report("seeked", ["serial": .number(Double(serial)), "time": .number(self.time)])
+            }
+        }
+    }
+
+    private func playedToEnd(_ url: String) {
+        if applied?.loop == true {
+            // The item plays again from its start, as a looper would.
+            player.seek(to: .zero)
+            if applied?.playing == true { player.rate = Float(applied?.rate ?? 1) }
+        } else {
+            ended = true
+        }
+        report("ended", ["url": .string(url), "time": .number(time)])
+    }
+
+    private func observeTime(every interval: Double) {
+        if let timeObserver { player.removeTimeObserver(timeObserver) }
+        let step = max(0.05, interval)
+        timeObserver = player.addPeriodicTimeObserver(forInterval: CMTime(seconds: step, preferredTimescale: 600), queue: .main) { [weak self] time in
+            Task { @MainActor in
+                guard let self, self.applied?.playing == true else { return }
+                let seconds = time.seconds
+                self.report("time", ["time": .number(seconds.isFinite ? seconds : 0)])
+            }
+        }
+    }
+
+    private func unobserve() {
+        for token in notifications { NotificationCenter.default.removeObserver(token) }
+        notifications = []
+        #if !canImport(FoundationBridge)
+        stateObservation = nil
+        #endif
+    }
+
+    private func report(_ event: String, _ fields: JSONObject) {
+        app?.dispatch(.video(id, event, fields))
+    }
+}
+#endif