@craft-native/ios 0.0.238 → 0.0.242

package/templates/CraftHybrid.swift

@@ -342,10 +342,9 @@ final class CraftHybrid: NSObject {
         webView.evaluateJavaScript("window.__craftHybrid && window.__craftHybrid.adopt && window.__craftHybrid.adopt(\(json))")
     }
 
-    static var bundleURL: URL? {
-        Bundle.main.url(forResource: "native-screen", withExtension: "js", subdirectory: "dist")
-            ?? Bundle.main.url(forResource: "native-screen", withExtension: "js")
-    }
+    /// Whether the app carries native screens: the one-file bundle, or a
+    /// file per route (`CraftNativeBundle`).
+    static var hasBundle: Bool { CraftNativeBundle.isAvailable }
 
     /// From the bundled config, at launch: whether the shell routes paths,
     /// whether there is a web view, where it starts, the tab bar it starts
@@ -363,12 +362,12 @@ final class CraftHybrid: NSObject {
         startPath = config.devServerURL.flatMap(URL.init(string:)).map(CraftHybridRoutes.appPath(of:)) ?? "/"
         if startPath.isEmpty { startPath = "/" }
         let wanted = !routes.isEmpty
-        if wanted && Self.bundleURL == nil {
+        if wanted && !Self.hasBundle {
             NSLog(hasWeb
                 ? "[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; every path opens in the web view"
                 : "[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; the app has no screens to show")
         }
-        isEnabled = wanted && Self.bundleURL != nil
+        isEnabled = wanted && Self.hasBundle
         if isEnabled, !hasWeb, routes.match(startPath) == nil {
             // No web view to show it in: the first tab a screen draws.
             let fallback = (config.tabs ?? []).map(\.id).first { routes.match($0) != nil }
@@ -380,7 +379,7 @@ final class CraftHybrid: NSObject {
         CraftChrome.shared.configure(tabs: config.tabs ?? [], selected: tabIds(from: config.tabs ?? []).isEmpty ? nil : CraftHybridRoutes.tab(owning: startPath, among: tabIds(from: config.tabs ?? [])), splash: hasWeb && !startsNative)
 
         let script = config.nativeApp.flatMap { $0.isEmpty ? nil : $0 }
-        appScriptRoute = script != nil && Self.bundleURL != nil && (isEnabled || !hasWeb) ? script : nil
+        appScriptRoute = script != nil && Self.hasBundle && (isEnabled || !hasWeb) ? script : nil
         if let script, appScriptRoute == nil {
             NSLog("[craft hybrid] nativeApp %@ does not run: it needs dist/native-screen.js, and nativeScreens or renderer \"native\"", script)
         }
@@ -1158,6 +1157,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             let complete = recognizer.state == .ended && speed > -700
                 && (progress >= max(32, view.bounds.width * 0.28) || speed > 700)
             finishInteractiveTabSwipe(completed: complete, velocity: velocity) { [weak self] in
+                CraftFramePacing.shared.end("tab swipe")
                 self?.activeTabSwipeTarget = nil
                 self?.tabSwipeSettling = false
                 self?.prepareAdjacentNativeTabs()
@@ -1187,7 +1187,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             // create a second web root here: the shared WebView cannot draw
             // both pages during the same gesture.
             guard hybrid.routes.match(id) != nil else { return false }
-            target = makeStack(tab: id, rootPath: id)
+            target = CraftFramePacing.shared.measure("tab swipe mount \(id)") { makeStack(tab: id, rootPath: id) }
             (target.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
         }
         guard current.view !== target.view,
@@ -1216,6 +1216,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         target.view.frame = view.bounds.offsetBy(dx: tabSwipeFrom, dy: 0)
         view.bringSubviewToFront(target.view)
         CraftChrome.shared.beginTabSwipe(to: id, from: currentTab)
+        lastNavigation = CACurrentMediaTime()
+        CraftFramePacing.shared.begin("tab swipe")
         return true
     }
 
@@ -1245,12 +1247,11 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         CraftChrome.shared.settleTabSwipe(completed: completed, duration: duration)
         let remaining = end - target.view.frame.minX
         let initialVelocity = abs(remaining) > 1 ? max(0, min(12, velocity / remaining)) : 0
-        UIView.animate(withDuration: duration, delay: 0, usingSpringWithDamping: 1,
-                       initialSpringVelocity: initialVelocity,
-                       options: [.beginFromCurrentState, .allowUserInteraction], animations: {
+        let move = {
             target.view.frame.origin.x = end
             current.view.frame.origin.x = completed ? -direction * width : 0
-        }, completion: { _ in
+        }
+        let settled: (Bool) -> Void = { _ in
             guard self.tabSwipeGeneration == generation,
                   self.activeTabSwipeTarget == targetId else { return }
             if completed {
@@ -1268,7 +1269,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
                 }
             }
             completion()
-        })
+        }
+        UIView.animate(withDuration: duration, delay: 0, usingSpringWithDamping: 1,
+                       initialSpringVelocity: initialVelocity,
+                       options: [.beginFromCurrentState, .allowUserInteraction], animations: move, completion: settled)
     }
 
     /// A newer navigation action wins immediately, including a tap back on
@@ -1448,9 +1452,15 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     private func show(tab id: String, rootPath: String? = nil) {
+        lastNavigation = CACurrentMediaTime()
         interruptTabSwipe(restoringSelection: false)
         cancelPendingTab()
-        let nav = stacks[id] ?? makeStack(tab: id, rootPath: rootPath ?? (id.isEmpty ? hybrid.startPath : id))
+        let pacing = CraftFramePacing.shared
+        if pacing.enabled, id != currentTab, !currentTab.isEmpty {
+            pacing.begin("tab \(id)")
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { pacing.end("tab \(id)") }
+        }
+        let nav = stacks[id] ?? pacing.measure("tab \(id) mount") { makeStack(tab: id, rootPath: rootPath ?? (id.isEmpty ? hybrid.startPath : id)) }
         // A stack is hidden and shown rather than moved, so UIKit tells its
         // screens nothing: the shell says which went away and which is back.
         if id != currentTab {
@@ -1469,31 +1479,69 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         }
     }
 
-    /// Prepare one neighbour after the first frame, never inside the finger's
-    /// tracking run-loop mode. A first swipe then uses a laid-out native root
-    /// rather than compiling, measuring and fetching at gesture start.
+    /// Prepare the other tabs' first screens after the first frame, nearest
+    /// first, one per idle moment and never inside the finger's tracking
+    /// run-loop mode. A swipe or a tap then lands on a laid-out native root
+    /// rather than compiling, measuring and fetching while it animates. Only
+    /// the neighbours used to be prepared, so arriving on a tab mounted the
+    /// next one 150ms later, which was just when the next swipe began.
+    ///
+    /// Idle means idle: not while a push, a pop or a tab swipe animates, and
+    /// not right after one (a link opened at launch must not wait behind
+    /// tabs nobody asked for). The neighbours come first and soon; the tabs
+    /// further away only once the screen has been still for a while.
     private func prepareAdjacentNativeTabs() {
         let owner = currentTab
-        let timer = Timer(timeInterval: 0.15, repeats: false) { [weak self] _ in
-            guard let self, self.currentTab == owner, self.activeTabSwipeTarget == nil,
-                  self.view.window != nil,
-                  let index = self.hybrid.tabIds.firstIndex(of: owner) else { return }
-            let tabs = self.hybrid.tabIds
-            for neighbour in [index + 1, index - 1] where tabs.indices.contains(neighbour) {
-                let id = tabs[neighbour]
-                guard self.stacks[id] == nil, self.hybrid.routes.match(id) != nil else { continue }
+        guard let index = hybrid.tabIds.firstIndex(of: owner) else { return }
+        let tabs = hybrid.tabIds
+        let waiting = tabs.indices.filter { $0 != index && stacks[tabs[$0]] == nil && hybrid.routes.match(tabs[$0]) != nil }
+            .sorted { abs($0 - index) < abs($1 - index) || (abs($0 - index) == abs($1 - index) && $0 > $1) }
+        // One preparation pending at a time, for the tab on screen now.
+        preparation?.invalidate()
+        preparation = nil
+        guard let next = waiting.first else { return }
+        let neighbour = abs(next - index) == 1
+        let timer = Timer(timeInterval: neighbour ? 0.15 : 0.6, repeats: false) { [weak self] _ in
+            guard let self else { return }
+            self.preparation = nil
+            guard self.currentTab == owner, self.view.window != nil else { return }
+            let quietFor = neighbour ? 0.3 : 1.0
+            guard self.activeTabSwipeTarget == nil, !self.tabSwipeSettling,
+                  !self.stacks.values.contains(where: { $0.transitionCoordinator != nil }),
+                  CACurrentMediaTime() - self.lastNavigation >= quietFor else {
+                self.prepareAdjacentNativeTabs()
+                return
+            }
+            let id = tabs[next]
+            guard self.stacks[id] == nil else { self.prepareAdjacentNativeTabs(); return }
+            let nav = CraftFramePacing.shared.measure("prepare \(id)") { () -> UINavigationController in
                 let nav = self.makeStack(tab: id, rootPath: id)
                 nav.view.isHidden = true
                 nav.view.layoutIfNeeded()
-                (nav.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
-                (self.visibleStack?.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
-                self.prepareAdjacentNativeTabs()
-                break
+                // Draw its text and pictures now. A hidden layer is not
+                // drawn at commit, so the first swipe to this tab drew
+                // every label of the screen in the gesture's first frame.
+                Self.drawContents(of: nav.view.layer)
+                return nav
             }
+            (nav.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
+            (self.visibleStack?.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
+            self.prepareAdjacentNativeTabs()
         }
+        preparation = timer
         RunLoop.main.add(timer, forMode: .default)
     }
 
+    private var preparation: Timer?
+
+    /// When the shell last moved between screens: a tab, a push or a pop.
+    private var lastNavigation: CFTimeInterval = 0
+
+    private static func drawContents(of layer: CALayer) {
+        layer.displayIfNeeded()
+        layer.sublayers?.forEach(drawContents(of:))
+    }
+
     private func cancelPendingTab() {
         pendingTab?.deadline.cancel()
         pendingTab = nil
@@ -1759,6 +1807,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     // MARK: UINavigationControllerDelegate
 
     func navigationController(_ navigationController: UINavigationController, willShow viewController: UIViewController, animated: Bool) {
+        lastNavigation = CACurrentMediaTime()
+        if animated { CraftFramePacing.shared.begin("navigation") }
         // The page draws its own header, and a tab's root screen its own
         // title unless it asked for the bar; a pushed native screen gets the
         // bar and its Back.
@@ -1773,6 +1823,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     func navigationController(_ navigationController: UINavigationController, didShow viewController: UIViewController, animated: Bool) {
+        lastNavigation = CACurrentMediaTime()
+        CraftFramePacing.shared.end("navigation")
         let key = ObjectIdentifier(navigationController)
         let before = shownStacks[key] ?? []
         let now = navigationController.viewControllers
@@ -1959,3 +2011,115 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         #endif
     }
 }
+
+// MARK: - Frame pacing
+
+/// How smoothly the app's own motion runs, measured the way Instruments'
+/// Animation Hitches template counts it: a frame that reaches the screen
+/// later than the display expected it is a hitch, and the time it was late
+/// is hitch time. Apple's bar is a hitch time ratio under 5 ms per second of
+/// motion; above 10 the motion reads as broken.
+///
+/// Off unless the app is launched with `-CraftFramePacing YES` (or
+/// `CRAFT_FRAME_PACING=1`), so a shipped app never runs a display link for
+/// it. Each span (a scroll, a tab swipe, a push, a screen mount) logs one
+/// `[craft frames]` line, which simulator and device runs read back with
+/// `log show`. The Animation Hitches instrument does not run in the
+/// simulator; this does.
+final class CraftFramePacing: NSObject {
+    static let shared = CraftFramePacing()
+
+    let enabled: Bool = {
+        let info = ProcessInfo.processInfo
+        return UserDefaults.standard.bool(forKey: "CraftFramePacing") || info.environment["CRAFT_FRAME_PACING"] == "1"
+    }()
+
+    private struct Span {
+        var started: CFTimeInterval
+        var frames = 0
+        var hitches = 0
+        var hitchTime: CFTimeInterval = 0
+        var worst: CFTimeInterval = 0
+    }
+
+    private var spans: [String: Span] = [:]
+    private var link: CADisplayLink?
+    private var lastTimestamp: CFTimeInterval = 0
+    private var lastTarget: CFTimeInterval = 0
+
+    /// Start counting frames for `name`; a span already open keeps counting.
+    func begin(_ name: String) {
+        guard enabled, spans[name] == nil else { return }
+        spans[name] = Span(started: CACurrentMediaTime())
+        guard link == nil else { return }
+        let link = CADisplayLink(target: self, selector: #selector(frame(_:)))
+        // ProMotion runs scrolling at up to 120Hz; measure against what the
+        // display actually asked for, not a fixed 60.
+        if #available(iOS 15.0, *) { link.preferredFrameRateRange = CAFrameRateRange(minimum: 80, maximum: 120, preferred: 120) }
+        link.add(to: .main, forMode: .common)
+        self.link = link
+        lastTimestamp = 0
+    }
+
+    /// Close `name` and log its frames.
+    func end(_ name: String) {
+        guard enabled, let span = spans.removeValue(forKey: name) else { return }
+        let duration = max(0.001, CACurrentMediaTime() - span.started)
+        write(String(format: "%@ frames=%d duration=%.0fms hitches=%d hitchTime=%.1fms worst=%.1fms ratio=%.1fms/s",
+                     name, span.frames, duration * 1000, span.hitches, span.hitchTime * 1000, span.worst * 1000,
+                     span.hitchTime * 1000 / duration))
+        if spans.isEmpty {
+            link?.invalidate()
+            link = nil
+        }
+    }
+
+    /// One main-thread block, timed: a screen mount, a bundle evaluation.
+    @discardableResult
+    func measure<T>(_ name: String, _ work: () -> T) -> T {
+        guard enabled else { return work() }
+        let started = CACurrentMediaTime()
+        let result = work()
+        write(String(format: "%@ main=%.1fms", name, (CACurrentMediaTime() - started) * 1000))
+        return result
+    }
+
+    /// Each line to the log and to `Library/Caches/craft-frame-pacing.log`
+    /// in the app's container, which a test run reads back whole (a
+    /// simulator's unified log can drop an app's lines under load). Written
+    /// off the main thread, so the measuring costs no frames itself.
+    private let output = DispatchQueue(label: "craft.frame-pacing", qos: .utility)
+    private lazy var file: FileHandle? = {
+        guard let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else { return nil }
+        let url = caches.appendingPathComponent("craft-frame-pacing.log")
+        if !FileManager.default.fileExists(atPath: url.path) { FileManager.default.createFile(atPath: url.path, contents: nil) }
+        let handle = try? FileHandle(forWritingTo: url)
+        _ = try? handle?.seekToEnd()
+        return handle
+    }()
+
+    private func write(_ line: String) {
+        NSLog("[craft frames] %@", line)
+        let stamped = "\(Date().timeIntervalSince1970) \(line)\n"
+        output.async { [weak self] in try? self?.file?.write(contentsOf: Data(stamped.utf8)) }
+    }
+
+    @objc private func frame(_ link: CADisplayLink) {
+        defer {
+            lastTimestamp = link.timestamp
+            lastTarget = link.targetTimestamp
+        }
+        guard lastTimestamp > 0 else { return }
+        // The frame was due at the last target; anything later than that,
+        // beyond a millisecond of scheduling noise, is hitch time.
+        let late = link.timestamp - lastTarget
+        for key in spans.keys {
+            spans[key]!.frames += 1
+            if late > 0.001 {
+                spans[key]!.hitches += 1
+                spans[key]!.hitchTime += late
+                spans[key]!.worst = max(spans[key]!.worst, late)
+            }
+        }
+    }
+}

package/templates/CraftNativeActions.swift

@@ -764,11 +764,15 @@ enum CraftNativeActions {
     /// screens asking at the same time share one download). A refused answer
     /// (not 2xx) keeps nothing and says its status. Cancelled like fetch.
     ///
-    /// `cellular: false` keeps it off a metered connection: iOS refuses the
-    /// download on cellular, a personal hotspot and Low Data Mode, and the
-    /// answer is `{ ok: false, reason: "cellular" }` straight away, so the
-    /// screen can say it is waiting for Wi-Fi instead of failing. A copy
-    /// already kept still answers, whatever the connection.
+    /// `cellular: false` keeps it off a metered connection (cellular, a
+    /// personal hotspot, Low Data Mode). The download runs on a background
+    /// session (CraftNativeMediaTransfers), so it carries on while the app is
+    /// suspended or closed. When the phone cannot fetch it now (no
+    /// connection, or only a metered one for a Wi-Fi-only keep) the answer is
+    /// `{ ok: false, reason: "offline" | "cellular", queued: true }` straight
+    /// away, so the screen can say it is waiting rather than failing, and the
+    /// transfer finishes with iOS when it can. A copy already kept still
+    /// answers, whatever the connection.
     private static func keepMedia(
         requestToken: String,
         args: [Any],
@@ -797,38 +801,33 @@ enum CraftNativeActions {
                 request.setValue(value, forHTTPHeaderField: name)
             }
         }
-        if options["cellular"] as? Bool == false {
+        let wifiOnly = options["cellular"] as? Bool == false
+        if wifiOnly {
             request.allowsExpensiveNetworkAccess = false
             request.allowsConstrainedNetworkAccess = false
         }
-        guard let flight = CraftNativeMedia.begin(address, { complete(requestToken, $0, completion) }) else { return }
-        let task = fetchSession.downloadTask(with: request) { location, response, error in
+        let answer: (Result<Any, CraftNativeActionError>) -> Void = { result in
             cancellationLock.lock()
             fetchTasks.removeValue(forKey: requestToken)
             cancellationLock.unlock()
-            if let error = error {
-                // Refused only because the connection is metered: not a failure, a wait.
-                if let reason = (error as? URLError)?.networkUnavailableReason, reason == .expensive || reason == .constrained {
-                    CraftNativeMedia.finish(address, flight: flight, .success(["ok": false, "url": address, "reason": "cellular"]))
-                    return
-                }
-                let code = (error as? URLError)?.code == .timedOut ? "TIMEOUT" : "NETWORK_ERROR"
-                CraftNativeMedia.finish(address, flight: flight, failure(CraftNativeMedia.errorCode(error, fallback: code), error.localizedDescription))
-                return
-            }
-            guard let http = response as? HTTPURLResponse, let location else {
-                CraftNativeMedia.finish(address, flight: flight, failure("NETWORK_ERROR", "media.keep received a response that is not HTTP"))
-                return
-            }
-            // The system deletes `location` once this returns: move it now.
-            CraftNativeMedia.finish(address, flight: flight, CraftNativeMedia.store(address, at: location, response: http, flight: flight))
+            complete(requestToken, result, completion)
         }
+        guard let flight = CraftNativeMedia.begin(address, answer) else { return }
         cancellationLock.lock()
         let alreadyCancelled = cancelledRequests.contains(requestToken)
-        if !alreadyCancelled { fetchTasks[requestToken] = task }
         cancellationLock.unlock()
-        if alreadyCancelled { CraftNativeMedia.finish(address, flight: flight, failure("CANCELLED", "media.keep was cancelled")) }
-        else { task.resume() }
+        if alreadyCancelled {
+            CraftNativeMedia.finish(address, flight: flight, failure("CANCELLED", "media.keep was cancelled"))
+            return
+        }
+        // On the app's background session (CraftNativeMediaTransfers): it
+        // carries on while the app is suspended, and a keep the phone cannot
+        // fetch now is answered at once while its transfer waits with iOS.
+        let task = CraftNativeMediaTransfers.shared.start(request, address: address, flight: flight, wifiOnly: wifiOnly)
+        cancellationLock.lock()
+        // Unless it answered already (a queued transfer, or an instant failure).
+        if CraftNativeMedia.isWaiting(address, flight: flight) { fetchTasks[requestToken] = task }
+        cancellationLock.unlock()
     }
 
     private static func claimInitialDeepLink(_ url: URL?) -> URL? {

package/templates/CraftNativeFiles.swift

@@ -1,6 +1,7 @@
 import CryptoKit
 import Foundation
 import ImageIO
+import Network
 import PhotosUI
 import UIKit
 import UniformTypeIdentifiers
@@ -554,6 +555,13 @@ enum CraftNativeMedia {
         return id
     }
 
+    /// Whether `flight` is still the download `address`'s keeps wait for.
+    static func isWaiting(_ address: String, flight: UUID) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return inFlight[address]?.id == flight
+    }
+
     static func finish(_ address: String, flight: UUID, _ result: Result<Any, CraftNativeActionError>) {
         lock.lock()
         let waiting = inFlight[address]?.id == flight ? inFlight.removeValue(forKey: address)?.waiting ?? [] : []
@@ -563,7 +571,7 @@ enum CraftNativeMedia {
 
     /// A finished download moved into place (atomically, so a half-written
     /// file is never played), or a refusal with the server's status.
-    static func store(_ address: String, at location: URL, response: HTTPURLResponse, flight: UUID? = nil) -> Result<Any, CraftNativeActionError> {
+    static func store(_ address: String, at location: URL, response: HTTPURLResponse, flight: UUID? = nil, stillWanted: (() -> Bool)? = nil) -> Result<Any, CraftNativeActionError> {
         guard response.statusCode == 200 else {
             return .success(["ok": false, "url": address, "status": response.statusCode])
         }
@@ -574,6 +582,10 @@ enum CraftNativeMedia {
         if let flight, inFlight[address]?.id != flight {
             return .failure(CraftNativeActionError(code: "CANCELLED", message: "The video cache was cleared"))
         }
+        // A background transfer from before the cache was cleared (sign-out).
+        if let stillWanted, !stillWanted() {
+            return .failure(CraftNativeActionError(code: "CANCELLED", message: "The video cache was cleared"))
+        }
         let staging = root.appendingPathComponent(UUID().uuidString + ".part")
         defer { try? fm.removeItem(at: staging) }
         do {
@@ -609,6 +621,9 @@ enum CraftNativeMedia {
         lock.lock()
         let waiting = inFlight.values.flatMap { $0.waiting }
         inFlight.removeAll()
+        // Under the same lock a background transfer commits under: none
+        // started before this lands after it.
+        CraftNativeMediaTransfers.shared.cancelAll()
         let fm = FileManager.default
         let files = (try? fm.contentsOfDirectory(at: root, includingPropertiesForKeys: nil)) ?? []
         var removed = 0
@@ -625,6 +640,7 @@ enum CraftNativeMedia {
 
     /// Removes every copy whose address is not in `keep`; answers how many.
     static func prune(keep: [String]) -> Int {
+        CraftNativeMediaTransfers.shared.cancel(except: keep + Array(inFlightAddresses()))
         lock.lock()
         defer { lock.unlock() }
         let wanted = Set(keep.map { file(for: $0).lastPathComponent })
@@ -637,6 +653,12 @@ enum CraftNativeMedia {
         return removed
     }
 
+    private static func inFlightAddresses() -> Set<String> {
+        lock.lock()
+        defer { lock.unlock() }
+        return Set(inFlight.keys)
+    }
+
     /// What the kept copies come to, in bytes, and how many there are.
     static func usage() -> [String: Any] {
         let files = (try? FileManager.default.contentsOfDirectory(at: root, includingPropertiesForKeys: [.fileSizeKey])) ?? []
@@ -645,3 +667,185 @@ enum CraftNativeMedia {
         return ["files": kept.count, "bytes": bytes]
     }
 }
+
+/// The downloads `media.keep` starts, on a background URLSession: a transfer
+/// carries on while the app is suspended or closed, waits for Wi-Fi when it
+/// was asked to, and lands in CraftNativeMedia when it finishes, whether or
+/// not anyone is still waiting for it (the address travels with the task as
+/// its description, so a transfer outlives the launch that started it).
+///
+/// A request answers as soon as its file is kept, or at once with
+/// `{ ok: false, reason: "cellular" | "offline", queued: true }` when the
+/// phone cannot fetch it now: the transfer stays with iOS and finishes on
+/// its own, and the next `keep` of that address answers from the copy.
+final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
+    static let shared = CraftNativeMediaTransfers()
+    static var identifier: String { "\(Bundle.main.bundleIdentifier ?? "dev.craft.app").craft-media" }
+
+    /// iOS's handler from relaunching the app for this session's events.
+    var backgroundCompletion: (() -> Void)?
+
+    private struct Transfer {
+        let address: String
+        /// The keep still waiting for this transfer; nil once answered early.
+        var flight: UUID?
+        let wifiOnly: Bool
+        /// Transfers from before the last `clear` must not land.
+        let generation: Int
+    }
+
+    private let lock = NSLock()
+    private var transfers: [Int: Transfer] = [:]
+    /// What each finished download came to, until its task completes.
+    private var finished: [Int: Result<Any, CraftNativeActionError>] = [:]
+    /// Transfers left running by an earlier launch, by address.
+    private var restored: [String: URLSessionDownloadTask] = [:]
+    private var generation = 0
+    private let monitor = NWPathMonitor()
+
+    /// Made once, at first use: iOS hands this identifier's finished
+    /// transfers to whichever session object the app makes with it.
+    private(set) var session: URLSession!
+
+    override init() {
+        super.init()
+        let configuration = URLSessionConfiguration.background(withIdentifier: Self.identifier)
+        configuration.sessionSendsLaunchEvents = true
+        configuration.isDiscretionary = false
+        session = URLSession(configuration: configuration, delegate: self, delegateQueue: nil)
+        session.getAllTasks { [weak self] tasks in
+            guard let self else { return }
+            self.lock.lock()
+            for case let task as URLSessionDownloadTask in tasks where task.state == .running || task.state == .suspended {
+                if let address = task.taskDescription, self.transfers[task.taskIdentifier] == nil { self.restored[address] = task }
+            }
+            self.lock.unlock()
+        }
+        // A connection lost (or only a metered one left for a Wi-Fi-only
+        // keep) answers the waiting keeps; their transfers carry on later.
+        monitor.pathUpdateHandler = { [weak self] path in self?.release(on: path) }
+        monitor.start(queue: DispatchQueue(label: "dev.craft.native.media.path"))
+    }
+
+    /// Fetches `request` into the copy for `address`, finishing `flight`.
+    func start(_ request: URLRequest, address: String, flight: UUID, wifiOnly: Bool) -> URLSessionTask {
+        lock.lock()
+        let task: URLSessionDownloadTask
+        if let earlier = restored.removeValue(forKey: address), earlier.state == .running || earlier.state == .suspended {
+            task = earlier
+        }
+        else {
+            task = session.downloadTask(with: request)
+            task.taskDescription = address
+        }
+        transfers[task.taskIdentifier] = Transfer(address: address, flight: flight, wifiOnly: wifiOnly, generation: generation)
+        lock.unlock()
+        task.resume()
+        release(on: monitor.currentPath)
+        return task
+    }
+
+    /// Answers the keeps that cannot be fetched on `path`; their transfers stay queued with iOS.
+    private func release(on path: NWPath) {
+        let offline = path.status != .satisfied
+        let metered = path.isExpensive || path.isConstrained
+        lock.lock()
+        var answered: [(String, UUID, String)] = []
+        for (id, transfer) in transfers {
+            guard let flight = transfer.flight, offline || (transfer.wifiOnly && metered) else { continue }
+            transfers[id]?.flight = nil
+            answered.append((transfer.address, flight, offline ? "offline" : "cellular"))
+        }
+        lock.unlock()
+        for (address, flight, reason) in answered {
+            CraftNativeMedia.finish(address, flight: flight, .success(["ok": false, "url": address, "reason": reason, "queued": true]))
+        }
+    }
+
+    /// Stops every transfer: an account's copies are being cleared, and none of its videos may land after.
+    func cancelAll() {
+        lock.lock()
+        generation += 1
+        restored.removeAll()
+        lock.unlock()
+        session.getAllTasks { tasks in tasks.forEach { $0.cancel() } }
+    }
+
+    /// Stops the transfers for addresses no longer wanted.
+    func cancel(except keep: [String]) {
+        let wanted = Set(keep)
+        lock.lock()
+        restored = restored.filter { wanted.contains($0.key) }
+        lock.unlock()
+        session.getAllTasks { tasks in
+            for task in tasks where !wanted.contains(task.taskDescription ?? "") { task.cancel() }
+        }
+    }
+
+    func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {
+        lock.lock()
+        let transfer = transfers[downloadTask.taskIdentifier]
+        lock.unlock()
+        // One left by an earlier launch belongs to the generation this launch began with.
+        let started = transfer?.generation ?? 0
+        guard let address = transfer?.address ?? downloadTask.taskDescription else { return }
+        guard let http = downloadTask.response as? HTTPURLResponse else {
+            record(downloadTask, .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "media.keep received a response that is not HTTP")))
+            return
+        }
+        // The system deletes `location` once this returns: move it now. It
+        // lands whether its keep is still waiting or was answered early; only
+        // a clear since it started (sign-out) keeps it out.
+        record(downloadTask, CraftNativeMedia.store(address, at: location, response: http, stillWanted: { [weak self] in self?.isCurrent(started) ?? false }))
+    }
+
+    /// How many times the cache was cleared in this launch; a transfer started before the last clear does not land.
+    var currentGeneration: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return generation
+    }
+
+    func isCurrent(_ started: Int) -> Bool {
+        currentGeneration == started
+    }
+
+    private func record(_ task: URLSessionTask, _ result: Result<Any, CraftNativeActionError>) {
+        lock.lock()
+        finished[task.taskIdentifier] = result
+        lock.unlock()
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        lock.lock()
+        let transfer = transfers.removeValue(forKey: task.taskIdentifier)
+        let result = finished.removeValue(forKey: task.taskIdentifier)
+        if let address = task.taskDescription, restored[address] === task { restored.removeValue(forKey: address) }
+        lock.unlock()
+        guard let transfer, let flight = transfer.flight else { return }
+        if let error {
+            let urlError = error as? URLError
+            if urlError?.code == .cancelled {
+                CraftNativeMedia.finish(transfer.address, flight: flight, .failure(CraftNativeActionError(code: "CANCELLED", message: "media.keep was cancelled")))
+                return
+            }
+            // Refused only because the connection is metered: not a failure, a wait.
+            if let reason = urlError?.networkUnavailableReason, reason == .expensive || reason == .constrained {
+                CraftNativeMedia.finish(transfer.address, flight: flight, .success(["ok": false, "url": transfer.address, "reason": "cellular"]))
+                return
+            }
+            let code = urlError?.code == .timedOut ? "TIMEOUT" : "NETWORK_ERROR"
+            CraftNativeMedia.finish(transfer.address, flight: flight, .failure(CraftNativeActionError(code: CraftNativeMedia.errorCode(error, fallback: code), message: error.localizedDescription)))
+            return
+        }
+        CraftNativeMedia.finish(transfer.address, flight: flight, result ?? .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "media.keep finished without a file")))
+    }
+
+    func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
+        DispatchQueue.main.async { [weak self] in
+            let done = self?.backgroundCompletion
+            self?.backgroundCompletion = nil
+            done?()
+        }
+    }
+}