@craft-native/ios 0.0.449 → 0.0.464

package/templates/CraftNativeFiles.swift

@@ -6,6 +6,72 @@ import Network
 import PhotosUI
 import UIKit
 import UniformTypeIdentifiers
+import UserNotifications
+
+/// UserNotifications takes ownership of attachment files. Never give it a
+/// picker/download original: stage copies and retain them until `add` answers.
+final class CraftNotificationAttachments {
+    let attachments: [UNNotificationAttachment]
+    let directory: URL?
+
+    init(_ raw: Any?) throws {
+        guard let raw else { attachments = []; directory = nil; return }
+        func invalid(_ message: String) -> NSError {
+            NSError(domain: "CraftNotification", code: 1, userInfo: [NSLocalizedDescriptionKey: message])
+        }
+        guard let entries = raw as? [[String: Any]], entries.count <= 10 else {
+            throw invalid("attachments must be an array of at most ten { id, path } entries")
+        }
+        var identifiers = Set<String>()
+        let sources: [(String, URL)] = try entries.map { entry in
+            guard let id = entry["id"] as? String, !id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+                  identifiers.insert(id).inserted,
+                  let path = entry["path"] as? String, let url = CraftNativeFiles.owned(path) else {
+                throw invalid("Each attachment needs a unique nonempty id and an existing craft.files path")
+            }
+            let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
+            guard attributes[.type] as? FileAttributeType == .typeRegular,
+                  let size = attributes[.size] as? NSNumber, size.int64Value > 0, size.int64Value <= 50 * 1024 * 1024 else {
+                throw invalid("An attachment must be a nonempty regular file no larger than 50 MiB")
+            }
+            return (id, url)
+        }
+        guard !sources.isEmpty else { attachments = []; directory = nil; return }
+        let folder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("craft-notification-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        do {
+            attachments = try sources.map { id, source in
+                // Use generated names, keeping the extension for iOS type detection.
+                let copy = folder.appendingPathComponent(UUID().uuidString).appendingPathExtension(source.pathExtension)
+                try FileManager.default.copyItem(at: source, to: copy)
+                // iOS validates supported media, including the lower image/audio
+                // limits. A failure rejects the entire notification, never a subset.
+                return try UNNotificationAttachment(identifier: id, url: copy, options: nil)
+            }
+            directory = folder
+        } catch {
+            try? FileManager.default.removeItem(at: folder)
+            throw error
+        }
+    }
+
+    func cleanup() {
+        // Only our staging folder, never attachment.url (which iOS can move).
+        if let directory { try? FileManager.default.removeItem(at: directory) }
+    }
+
+    func schedule(_ request: UNNotificationRequest,
+                  submit: (UNNotificationRequest, @escaping (Error?) -> Void) -> Void = { UNUserNotificationCenter.current().add($0, withCompletionHandler: $1) },
+                  completion: @escaping (Error?) -> Void) {
+        submit(request) { error in
+            self.cleanup()
+            completion(error)
+        }
+    }
+
+    deinit { cleanup() }
+}
 
 // `craft.files` on a native screen: a photo picked from the library (or taken
 // with the camera), a file downloaded for the share sheet, and those files
@@ -847,6 +913,12 @@ enum CraftNativeFiles {
 // JavaScript. The screen decides what to keep (`keep`) and what to drop
 // (`prune`); nothing is evicted behind its back.
 enum CraftNativeMedia {
+    /// A caller-owned account + resource + version identity. Never used as a network URL.
+    static func identity(_ source: String, options: [String: Any]) -> String {
+        guard let key = options["cacheKey"] as? String, !key.isEmpty, key.utf8.count <= 1024 else { return source }
+        return "craft-media-key:" + key
+    }
+
     /// Foundation often wraps ENOSPC inside a URL or Cocoa file error.
     static func errorCode(_ error: Error, fallback: String) -> String {
         var cause: NSError? = error as NSError
@@ -1086,7 +1158,17 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         lock.lock()
         let task: URLSessionDownloadTask
         if let earlier = restored.removeValue(forKey: address), earlier.state == .running || earlier.state == .suspended {
-            task = earlier
+            if earlier.originalRequest?.url == request.url && earlier.originalRequest?.allHTTPHeaderFields == request.allHTTPHeaderFields {
+                task = earlier
+            }
+            else {
+                // A queued capability can expire while the app is suspended.
+                // Retain its cache identity, replace only its authorized source.
+                earlier.taskDescription = nil
+                earlier.cancel()
+                task = session.downloadTask(with: request)
+                task.taskDescription = address
+            }
         }
         else {
             task = session.downloadTask(with: request)

package/templates/CraftNativeScreen.swift

@@ -13,6 +13,92 @@ import Security
 import SwiftUI
 import UIKit
 
+/// A menu belongs to its native view, not to coordinates in a web page.
+final class CraftNativeContextMenu: NSObject, UIContextMenuInteractionDelegate {
+    private(set) var items: [[String: Any]] = []
+    private var dispatch: ((String) -> Void)?
+    private weak var view: UIView?
+    private(set) lazy var interaction = UIContextMenuInteraction(delegate: self)
+    private var revision = 0
+    private var handlerIdentity: String?
+
+    init(view: UIView) {
+        self.view = view
+        super.init()
+        view.addInteraction(interaction)
+    }
+
+    static func entries(_ raw: Any?) -> [[String: Any]] {
+        var seen = Set<String>()
+        return (raw as? [[String: Any]] ?? []).filter {
+            guard let id = $0["id"] as? String, !id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+                  let title = $0["title"] as? String, !title.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return false }
+            return seen.insert(id).inserted
+        }
+    }
+
+    func update(_ entries: [[String: Any]], handler: String? = nil, dispatch: @escaping (String) -> Void) {
+        if let handler, handler == handlerIdentity, NSArray(array: items).isEqual(to: entries) {
+            self.dispatch = dispatch
+            return
+        }
+        handlerIdentity = handler
+        revision += 1
+        interaction.dismissMenu()
+        items = entries
+        self.dispatch = dispatch
+    }
+
+    func detach() {
+        revision += 1
+        dispatch = nil
+        items = []
+        interaction.dismissMenu()
+        view?.removeInteraction(interaction)
+    }
+
+    /// Captured actions from an open menu cannot target a reconciled row.
+    func selection(_ id: String) -> () -> Void {
+        let expected = revision
+        return { [weak self] in
+            guard let self, self.revision == expected,
+                  let item = self.items.first(where: { $0["id"] as? String == id }),
+                  item["disabled"] as? Bool != true else { return }
+            self.dispatch?(id)
+        }
+    }
+
+    func menu() -> UIMenu {
+        UIMenu(children: items.map { item in
+            var attributes: UIMenuElement.Attributes = []
+            if item["disabled"] as? Bool == true { attributes.insert(.disabled) }
+            if item["destructive"] as? Bool == true { attributes.insert(.destructive) }
+            let chosen = selection(item["id"] as! String)
+            return UIAction(title: item["title"] as! String,
+                            image: (item["symbol"] as? String).flatMap { UIImage(systemName: $0) },
+                            attributes: attributes) { _ in chosen() }
+        })
+    }
+
+    func menuProvider() -> UIContextMenuActionProvider {
+        // UIKit asks for contents when presentation begins, after configuration
+        // was requested. A reconciled node must not supply a different menu to
+        // an interaction that started against its previous items or handler.
+        let expected = revision
+        return { [weak self] _ in
+            guard let self, self.revision == expected,
+                  self.dispatch != nil, !self.items.isEmpty else { return nil }
+            return self.menu()
+        }
+    }
+
+    func contextMenuInteraction(_ interaction: UIContextMenuInteraction,
+                                configurationForMenuAtLocation location: CGPoint) -> UIContextMenuConfiguration? {
+        guard dispatch != nil, !items.isEmpty else { return nil }
+        return UIContextMenuConfiguration(identifier: nil, previewProvider: nil, actionProvider: menuProvider())
+    }
+}
+
 private let craftNativeCapabilityTimeoutMilliseconds = 30_000
 
 /// A retained JavaScript context must lose storage and snapshot access when
@@ -4376,6 +4462,7 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
 
     private func configureSheet(_ controller: CraftNativeSheetController) {
         controller.isModalInPresentation = onRequestClose == nil
+        controller.view.accessibilityViewIsModal = true
         guard let sheet = controller.sheetPresentationController else { return }
         let choices = sheetDetents.filter { $0 == "medium" || $0 == "large" }
         let values = choices.isEmpty ? ["large"] : Array(Set(choices)).sorted { $0 == "medium" && $1 == "large" }
@@ -4432,6 +4519,7 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
         guard let controller = presentationController.presentedViewController as? CraftNativeSheetController else { return }
         restoreSheetContent(controller)
         renderedVisible = false
+        accessibilityViewIsModal = false
         onRequestClose?("swipe")
     }
 
@@ -4443,7 +4531,10 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
     /// screen-level overlay but lets hit testing fall through outside its
     /// interactive content.
     var blocksBackground = true {
-        didSet { blocker.isUserInteractionEnabled = blocksBackground }
+        didSet {
+            blocker.isUserInteractionEnabled = blocksBackground
+            accessibilityViewIsModal = blocksBackground && renderedVisible
+        }
     }
     /// An opt-in non-modal dismissal policy. The default popup remains
     /// pass-through; when enabled, an outside tap is consumed and routed to
@@ -4471,6 +4562,7 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
     /// press bookkeeping once turned that off for a view with no handler of
     /// its own, and a shown modal let every tap through to the screen behind.
     func setVisible(_ visible: Bool, opacity: CGFloat, animationType: String?) {
+        accessibilityViewIsModal = blocksBackground && visible
         if blocksBackground && (presentationStyle == "pageSheet" || presentationStyle == "formSheet") {
             setSheetVisible(visible, animated: animationType != "none")
             return
@@ -4528,6 +4620,7 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
 
     func resetForTeardown() {
         renderedVisible = false
+        accessibilityViewIsModal = false
         sheetPresenter = nil
         if let controller = sheetController {
             controller.dismiss(animated: false)
@@ -6404,7 +6497,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private var inputIdentities: [ObjectIdentifier: String] = [:]
     private var inputDrafts: [String: String] = [:]
     private var longPressHandlers: [ObjectIdentifier: String] = [:]
+    private var contextMenus: [ObjectIdentifier: CraftNativeContextMenu] = [:]
     private var accessibilityActionHandlers: [ObjectIdentifier: String] = [:]
+    private var accessibilityActionRevisions: [ObjectIdentifier: UUID] = [:]
     private var textMaxLengths: [ObjectIdentifier: Int] = [:]
     private var scrollHandlers: [ObjectIdentifier: String] = [:]
     private var scrollBeginHandlers: [ObjectIdentifier: String] = [:]
@@ -7420,6 +7515,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 // DOM fallback even though this screen can present UIKit.
                 function installNativeDialog() {
                     var craft = globalThis.craft = globalThis.craft || {};
+                    craft.accessibility = {
+                        announce: function(text, options) { return request('Accessibility', 'announce', [text, options == null ? {} : options]).then(function() {}); }
+                    };
                     if (Array.isArray(bridge.capabilities) && bridge.capabilities.indexOf('dialog') >= 0) {
                         craft.dialog = {
                             alert: function(options) { return request('Dialog', 'alert', [options || {}], true).then(function() {}); },
@@ -9626,7 +9724,15 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             configureStack(stack, style: style)
             reconcileChildren(children, in: stack, parent: current, path: path, style: style)
         }
-        updateLongPressHandler(props["disabled"] as? Bool == true ? nil : events["onLongPress"], for: result)
+        let menuDisabled = props["disabled"] as? Bool == true || (props["accessibilityState"] as? [String: Any])?["disabled"] as? Bool == true
+        // STX's HTML parser lowercases unknown bound props and maps
+        // @contextmenu to onLongPress. Keep that authored path usable too.
+        let menuEntries = menuDisabled ? [] : CraftNativeContextMenu.entries(props["contextMenu"] ?? props["contextmenu"])
+        let menuHandler = nonEmptyHandler(events["onContextMenuAction"]) ?? nonEmptyHandler(events["onLongPress"])
+        let hasMenu = !menuEntries.isEmpty && menuHandler != nil
+        // A menu owns the hold when both are authored; never open an action
+        // sheet from onLongPress underneath UIKit's menu.
+        updateLongPressHandler(menuDisabled || hasMenu ? nil : events["onLongPress"], for: result)
         if type != "Button" && type != "Link" && type != "Checkbox" && type != "TextInput" && type != "Picker" && type != "SegmentedControl" && type != "DatePicker" && type != "Modal" && type != "Switch" && type != "Slider" && type != "ActivityIndicator" && type != "StatusBar" && type != "RefreshControl" && type != "Map" {
             let disabled = props["disabled"] as? Bool == true
             updatePressHandler(disabled ? nil : nonEmptyHandler(events["onPress"]) ?? nonEmptyHandler(events["onClick"]), for: result)
@@ -9646,7 +9752,18 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         applyAccessibility(props, type: type, to: result)
         // After applyAccessibility: it settles whether the view is an element
         // at all, and an action on a non-element is unreachable.
-        updateAccessibilityActions(props["accessibilityActions"], handler: props["disabled"] as? Bool == true ? nil : events["onAccessibilityAction"], for: result)
+        updateAccessibilityActions(props["accessibilityActions"], handler: menuDisabled ? nil : events["onAccessibilityAction"], for: result)
+        let menuID = ObjectIdentifier(result)
+        if hasMenu, let menuHandler {
+            let menu = contextMenus[menuID] ?? CraftNativeContextMenu(view: result)
+            contextMenus[menuID] = menu
+            menu.update(menuEntries, handler: menuHandler) { [weak self] itemID in
+                self?.send(type: "EVENT", payload: ["handlerName": menuHandler, "nativeEvent": ["id": itemID]])
+            }
+            result.isUserInteractionEnabled = true
+        } else {
+            contextMenus.removeValue(forKey: menuID)?.detach()
+        }
         (result as? CraftNativeFlowView)?.configureCelebration(props["celebration"])
         return current
     }
@@ -10129,7 +10246,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         inputEventCounts.removeValue(forKey: id)
         if node.type == "TextInput" && !preservingInputDrafts { inputDrafts.removeValue(forKey: node.identity) }
         longPressHandlers.removeValue(forKey: id)
+        contextMenus.removeValue(forKey: id)?.detach()
         accessibilityActionHandlers.removeValue(forKey: id)
+        accessibilityActionRevisions.removeValue(forKey: id)
+        node.view.accessibilityCustomActions = nil
         textMaxLengths.removeValue(forKey: id)
         scrollHandlers.removeValue(forKey: id)
         scrollBeginHandlers.removeValue(forKey: id)
@@ -10367,15 +10487,19 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         }
         guard let handler, !handler.isEmpty, !entries.isEmpty else {
             accessibilityActionHandlers.removeValue(forKey: id)
+            accessibilityActionRevisions.removeValue(forKey: id)
             view.accessibilityCustomActions = nil
             return
         }
         accessibilityActionHandlers[id] = handler
+        let revision = UUID()
+        accessibilityActionRevisions[id] = revision
         view.accessibilityCustomActions = entries.map { entry in
             UIAccessibilityCustomAction(name: entry.label) { [weak self, weak view] _ in
                 // Read the handler at firing time: a reconcile can rename it
                 // while the rotor sits on the element.
-                guard let self, let view, let current = self.accessibilityActionHandlers[ObjectIdentifier(view)] else { return false }
+                guard let self, let view, self.accessibilityActionRevisions[ObjectIdentifier(view)] == revision,
+                      let current = self.accessibilityActionHandlers[ObjectIdentifier(view)] else { return false }
                 self.send(type: "EVENT", payload: ["handlerName": current, "nativeEvent": ["actionName": entry.name]])
                 return true
             }
@@ -11230,6 +11354,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         view.accessibilityLabel = (props["accessibilityLabel"] as? String)
             ?? ((type == "Image" || type == "ImageBackground") ? props["alt"] as? String : nil)
         view.accessibilityHint = props["accessibilityHint"] as? String
+        let language = (props["accessibilityLanguage"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        view.accessibilityLanguage = language?.isEmpty == false ? language : nil
         if let value = props["accessibilityValue"] {
             view.accessibilityValue = (value as? String) ?? (value as? NSNumber)?.stringValue
             authoredAccessibilityValues.insert(id)

package/templates/CraftNotificationService.swift

@@ -0,0 +1,199 @@
+import Foundation
+import ImageIO
+import UserNotifications
+
+/// A separate extension process: no app runtime, shared container or JS required.
+final class CraftNotificationService: UNNotificationServiceExtension {
+    private let lock = NSLock()
+    private var delivery: CraftRemoteNotificationDelivery?
+
+    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
+        let next = CraftRemoteNotificationDelivery()
+        lock.lock()
+        let previous = delivery
+        delivery = next
+        lock.unlock()
+        previous?.expire()
+        next.start(request.content, completion: contentHandler)
+    }
+
+    override func serviceExtensionTimeWillExpire() {
+        lock.lock()
+        let current = delivery
+        lock.unlock()
+        current?.expire()
+    }
+}
+
+/// Serial streaming downloads bound both disk use and the extension's lifetime.
+/// Any failure returns the original alert, without partially attached media.
+final class CraftRemoteNotificationDelivery: NSObject, URLSessionDataDelegate {
+    static let maximumBytes = 10 * 1024 * 1024
+    private let queue = DispatchQueue(label: "craft.notification-service")
+    private let configuration: URLSessionConfiguration
+    private let root: URL
+    private let timeout: TimeInterval
+    private var session: URLSession?
+    private var task: URLSessionDataTask?
+    private var deadline: DispatchWorkItem?
+    private var original: UNNotificationContent?
+    private var handler: ((UNNotificationContent) -> Void)?
+    private var expired = false
+    private var entries: [(String, URL)] = []
+    private var attachments: [UNNotificationAttachment] = []
+    private var folder: URL?
+    private var file: URL?
+    private var stream: FileHandle?
+    private var received = 0
+
+    init(configuration: URLSessionConfiguration = .ephemeral,
+         root: URL = FileManager.default.temporaryDirectory.appendingPathComponent("craft-remote-notifications", isDirectory: true),
+         timeout: TimeInterval = 25) {
+        self.configuration = configuration
+        self.root = root
+        self.timeout = timeout
+        super.init()
+    }
+
+    static func permitted(_ url: URL) -> Bool {
+        url.scheme?.lowercased() == "https" && url.host?.isEmpty == false && url.user == nil && url.password == nil
+    }
+
+    func start(_ content: UNNotificationContent, completion: @escaping (UNNotificationContent) -> Void) {
+        queue.async {
+            self.original = content
+            self.handler = completion
+            guard !self.expired, let raw = content.userInfo["craftAttachments"] as? [[String: Any]],
+                  !raw.isEmpty, raw.count <= 10 else { self.finish(false); return }
+            var ids = Set<String>()
+            for item in raw {
+                guard let id = item["id"] as? String, !id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
+                      id.utf8.count <= 128, ids.insert(id).inserted,
+                      let string = item["url"] as? String, let url = URL(string: string), Self.permitted(url) else {
+                    self.finish(false); return
+                }
+                self.entries.append((id, url))
+            }
+            do {
+                try FileManager.default.createDirectory(at: self.root, withIntermediateDirectories: true)
+                // Successful handoffs must outlive the handler: iOS validates and
+                // moves their files AFTER the extension finishes. Sweep only old
+                // UUID folders, never another delivery still in flight.
+                for url in try FileManager.default.contentsOfDirectory(at: self.root, includingPropertiesForKeys: [.creationDateKey]) {
+                    if UUID(uuidString: url.lastPathComponent) != nil,
+                       let created = try url.resourceValues(forKeys: [.creationDateKey]).creationDate,
+                       created < Date().addingTimeInterval(-86_400) {
+                        try? FileManager.default.removeItem(at: url)
+                    }
+                }
+                let folder = self.root.appendingPathComponent(UUID().uuidString, isDirectory: true)
+                try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+                self.folder = folder
+            } catch { self.finish(false); return }
+            self.configuration.httpCookieStorage = nil
+            self.configuration.httpShouldSetCookies = false
+            self.configuration.urlCredentialStorage = nil
+            self.configuration.urlCache = nil
+            self.configuration.requestCachePolicy = .reloadIgnoringLocalCacheData
+            self.configuration.timeoutIntervalForRequest = self.timeout
+            self.configuration.timeoutIntervalForResource = self.timeout
+            self.session = URLSession(configuration: self.configuration, delegate: self, delegateQueue: nil)
+            let deadline = DispatchWorkItem { [weak self] in self?.finish(false) }
+            self.deadline = deadline
+            self.queue.asyncAfter(deadline: .now() + self.timeout, execute: deadline)
+            self.downloadNext()
+        }
+    }
+
+    func expire() {
+        queue.async { self.expired = true; self.finish(false) }
+    }
+
+    private func downloadNext() {
+        guard attachments.count < entries.count else { finish(true); return }
+        file = nil
+        task = session?.dataTask(with: entries[attachments.count].1)
+        task?.resume()
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse,
+                    newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void) {
+        queue.async {
+            guard self.handler != nil, let url = request.url, Self.permitted(url) else {
+                completionHandler(nil); self.finish(false); return
+            }
+            completionHandler(request)
+        }
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive response: URLResponse,
+                    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void) {
+        queue.async {
+            let formats = ["image/jpeg": "jpg", "image/png": "png", "image/gif": "gif",
+                           "audio/mpeg": "mp3", "audio/mp4": "m4a", "audio/wav": "wav", "audio/x-wav": "wav",
+                           "audio/aiff": "aiff", "audio/x-aiff": "aiff", "video/mp4": "mp4", "video/mpeg": "mpeg", "video/x-msvideo": "avi"]
+            guard self.handler != nil, let http = response as? HTTPURLResponse, http.statusCode == 200,
+                  let url = response.url, Self.permitted(url),
+                  let suffix = formats[response.mimeType?.lowercased() ?? ""], let folder = self.folder,
+                  response.expectedContentLength <= Int64(Self.maximumBytes - self.received) else {
+                completionHandler(.cancel); self.finish(false); return
+            }
+            let file = folder.appendingPathComponent(UUID().uuidString).appendingPathExtension(suffix)
+            do {
+                guard FileManager.default.createFile(atPath: file.path, contents: nil) else { throw CocoaError(.fileWriteUnknown) }
+                self.file = file
+                self.stream = try FileHandle(forWritingTo: file)
+                completionHandler(.allow)
+            } catch { completionHandler(.cancel); self.finish(false) }
+        }
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        // Backpressure the delegate queue: do not retain an unbounded queue of
+        // Data chunks from a fast/chunked server while disk writes catch up.
+        queue.sync {
+            guard self.handler != nil else { return }
+            guard data.count <= Self.maximumBytes - self.received, let stream = self.stream else { self.finish(false); return }
+            do { try stream.write(contentsOf: data); self.received += data.count }
+            catch { self.finish(false) }
+        }
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        queue.async {
+            guard self.handler != nil else { return }
+            do {
+                try self.stream?.close()
+                self.stream = nil
+                guard error == nil, let file = self.file else { self.finish(false); return }
+                if ["jpg", "png", "gif"].contains(file.pathExtension) {
+                    guard let image = CGImageSourceCreateWithURL(file as CFURL, nil), CGImageSourceGetCount(image) > 0,
+                          CGImageSourceGetStatus(image) == .statusComplete else { self.finish(false); return }
+                }
+                let attachment = try UNNotificationAttachment(identifier: self.entries[self.attachments.count].0, url: file, options: nil)
+                self.attachments.append(attachment)
+                self.downloadNext()
+            } catch { self.finish(false) }
+        }
+    }
+
+    private func finish(_ success: Bool) {
+        guard let handler, let original else { return }
+        self.handler = nil
+        deadline?.cancel()
+        deadline = nil
+        task?.cancel()
+        session?.invalidateAndCancel()
+        session = nil
+        try? stream?.close()
+        stream = nil
+        if success, let content = original.mutableCopy() as? UNMutableNotificationContent {
+            content.attachments = original.attachments + attachments
+            handler(content)
+            // No acknowledgement exists here. Leave successful files for iOS.
+        } else {
+            if let folder { try? FileManager.default.removeItem(at: folder) }
+            handler(original)
+        }
+    }
+}

package/templates/CraftVoiceRecording.swift

@@ -105,11 +105,21 @@ final class CraftVoiceRecording {
     private var generation = 0
     private let startupTimeout: TimeInterval
     private let stopTimeout: TimeInterval
+    struct FileRemovalReceipt: Encodable {
+        let queueMilliseconds: Double
+        let removalMilliseconds: Double
+        let ownedBefore: Bool
+        let removed: Bool
+        let existsAfter: Bool
+    }
+    // Internal observation of the real deletion, not a replacement filesystem.
+    private let fileRemovalObserved: ((FileRemovalReceipt) -> Void)?
     private var backgroundObserver: NSObjectProtocol?
 
     init(audioQueue: DispatchQueue = DispatchQueue(label: "craft.voice-recording", qos: .userInitiated),
          startupTimeout: TimeInterval = 15,
          stopTimeout: TimeInterval = 10,
+         fileRemovalObserved: ((FileRemovalReceipt) -> Void)? = nil,
          permission: @escaping (@escaping (Bool) -> Void) -> Void = { answer in
              #if CRAFT_PERMISSION_MICROPHONE
              AVAudioSession.sharedInstance().requestRecordPermission(answer)
@@ -132,6 +142,7 @@ final class CraftVoiceRecording {
         self.audioQueue = audioQueue
         self.startupTimeout = startupTimeout
         self.stopTimeout = stopTimeout
+        self.fileRemovalObserved = fileRemovalObserved
         self.permission = permission
         self.makeRecorder = makeRecorder
         self.deactivate = deactivate
@@ -164,7 +175,24 @@ final class CraftVoiceRecording {
         session.finish(.failure(error))
         if let file = session.file {
             // A stalled encoder must not hold deletion behind its audio queue.
-            Self.fileQueue.async { CraftNativeFiles.remove(file.path) }
+            let queued = ProcessInfo.processInfo.systemUptime
+            let observed = fileRemovalObserved
+            Self.trace("cancel \(session.key.prefix(8)): file removal queued")
+            Self.fileQueue.async {
+                let began = ProcessInfo.processInfo.systemUptime
+                let owned = CraftNativeFiles.owned(file.path) != nil
+                let removed = CraftNativeFiles.remove(file.path)
+                let receipt = FileRemovalReceipt(
+                    queueMilliseconds: (began - queued) * 1000,
+                    removalMilliseconds: (ProcessInfo.processInfo.systemUptime - began) * 1000,
+                    ownedBefore: owned, removed: removed,
+                    existsAfter: FileManager.default.fileExists(atPath: file.path))
+                // No path or recording content is included in diagnostics.
+                if let json = try? JSONEncoder().encode(receipt), let text = String(data: json, encoding: .utf8) {
+                    Self.trace("cancel \(session.key.prefix(8)): file removal \(text)")
+                }
+                observed?(receipt)
+            }
         }
         audioQueue.async { self.erase(session) }
     }