@craft-native/ios 0.0.451 → 0.0.467

package/dist/internal/typescript/src/native-notifications.d.ts

@@ -0,0 +1,17 @@
+/** Registered before notification delivery; payloads reference category ids. */
+export interface NativeNotificationCategory {
+    id: string;
+    actions: {
+        id: string;
+        title: string;
+        destructive?: boolean;
+        /** Open the app. Otherwise nativeApp handles the action in the background. */
+        foreground?: boolean;
+        authenticationRequired?: boolean;
+        textInput?: {
+            buttonTitle: string;
+            placeholder?: string;
+        };
+    }[];
+}
+export declare function nativeNotificationProblems(categories: unknown, nativeApp?: string, renderer?: string): string[];

package/dist/internal/typescript/src/native-routing.d.ts

@@ -0,0 +1,26 @@
+/** Constraints on decoded named path parameters; query items cannot override them. */
+export interface NativeParameterConstraint {
+    /** A case-sensitive regular expression for the complete normalized value. */
+    pattern?: string;
+    exclude?: readonly string[];
+    /** Normalize decoded values and exclusions before case-sensitive grammar validation. */
+    normalize?: 'lowercase';
+}
+export type NativeRouteConstraints = Record<string, Record<string, NativeParameterConstraint>>;
+/** Validate and normalize the decoded parameter map before query binding. */
+export declare function applyNativeParameterConstraints(params: Record<string, string>, rules?: Record<string, NativeParameterConstraint>): boolean;
+export declare function nativeRouteConstraintProblems(screens?: Record<string, string>, constraints?: NativeRouteConstraints): string[];
+/** `/a//b/?q#h` → `/a/b`, the way the shell and the page compare paths. Null for a relative path. */
+export declare function normalizeNativePath(raw: string): string | null;
+export interface NativePathMatch {
+    path: string;
+    screen: string;
+    params: Record<string, string>;
+}
+export declare function routeSegments(path: string): string[];
+/**
+ * The native screen for a path, by the rules the shell (`CraftHybridRoutes`)
+ * and the page script apply: static segments win over `:params`, which win
+ * over a trailing `*`; query items become params under the path's own.
+ */
+export declare function matchNativePath(nativeScreens: Record<string, string> | undefined, raw: string, constraints?: NativeRouteConstraints): NativePathMatch | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.451",
+  "version": "0.0.467",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/templates/CraftApp.swift

@@ -284,6 +284,18 @@ struct CraftRecoveryBudget {
     }
 }
 
+/// Capture the scene's launch intent before activation and before SwiftUI's
+/// onOpenURL callback. Activation alone cannot say that a cold launch had no URL.
+final class CraftSceneDelegate: NSObject, UIWindowSceneDelegate {
+    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
+        let urls = options.urlContexts.map { $0.url }
+            + options.userActivities.filter { $0.activityType == NSUserActivityTypeBrowsingWeb }.compactMap { $0.webpageURL }
+        if let url = urls.sorted(by: { $0.absoluteString < $1.absoluteString }).first {
+            DeepLinkManager.shared.captureLaunchURL(url)
+        }
+    }
+}
+
 final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
         let config = CraftConfig.bundled()
@@ -292,6 +304,7 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         // First, so a crash anywhere in the rest of launch is reported too.
         CraftCrashReporter.shared.start(config)
         UNUserNotificationCenter.current().delegate = self
+        UNUserNotificationCenter.current().setNotificationCategories(CraftNotificationCategory.registered(config.notificationCategories ?? []))
         // Before launch finishes, which is the only time iOS accepts it.
         CraftBackgroundWork.shared.registerRefresh(config)
         // The shell, the app script and an all-native app's services now,
@@ -323,6 +336,13 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         return true
     }
 
+    func application(_ application: UIApplication, configurationForConnecting session: UISceneSession,
+                     options: UIScene.ConnectionOptions) -> UISceneConfiguration {
+        let configuration = UISceneConfiguration(name: nil, sessionRole: session.role)
+        if session.role == .windowApplication { configuration.delegateClass = CraftSceneDelegate.self }
+        return configuration
+    }
+
     func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
         CraftEventManager.shared.handleShortcut(shortcutItem)
         completionHandler(true)
@@ -382,8 +402,19 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         // rather than where the notification pointed. The manager exists from
         // process start and holds the tap until the page is ready, the way it
         // already does for a home-screen shortcut.
-        CraftEventManager.shared.handleNotificationResponse(response.notification.request.content.userInfo)
-        completionHandler()
+        DispatchQueue.main.async {
+            if response.actionIdentifier == UNNotificationDefaultActionIdentifier {
+                CraftEventManager.shared.handleNotificationResponse(response.notification.request.content.userInfo)
+                completionHandler()
+            } else if response.actionIdentifier == UNNotificationDismissActionIdentifier {
+                completionHandler()
+            } else {
+                CraftEventManager.shared.handleNotificationAction(
+                    request: response.notification.request, action: response.actionIdentifier,
+                    userText: (response as? UNTextInputNotificationResponse)?.userText,
+                    completion: completionHandler)
+            }
+        }
     }
 
     func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
@@ -481,6 +512,18 @@ class CraftEventManager {
         sendToWeb("craftNotificationResponse", data: Self.pageData(userInfo))
     }
 
+    /// Keep the response alive while the app script handles a background action.
+    /// The existing readiness queue also covers a cold launch; app code answers
+    /// craft.background.complete(ok, detail.id) and the normal deadline bounds it.
+    func handleNotificationAction(request: UNNotificationRequest, action: String, userText: String?, completion: @escaping () -> Void) {
+        let id = CraftBackgroundWork.shared.hold { _ in completion() }
+        var detail: [String: Any] = ["id": id, "actionId": action,
+            "notificationId": request.identifier, "categoryId": request.content.categoryIdentifier,
+            "data": Self.pageData(request.content.userInfo)]
+        if let userText { detail["userText"] = userText }
+        sendToWeb("craftNotificationAction", data: detail)
+    }
+
     /// A notification that arrived while the app was in front, in the same
     /// shape as a tap so one handler can read both.
     func handleNotificationReceived(_ userInfo: [AnyHashable: Any]) {
@@ -1551,9 +1594,9 @@ class DeepLinkManager {
     private var replayingNativeLinks = false
     private weak var webView: WKWebView?
     private var isReady = false
-    // Replay bookkeeping only. A native screen can become ready before UIKit
-    // delivers the launch URL; listener readiness cannot classify that URL.
-    private var hasBeenReady = false
+    // Startup classification is independent of listener readiness. The same
+    // URL opened again later is a warm link, even if it matches the launch URL.
+    private var initialURLDispatched = false
     private var nativeListeners: [UUID: (canReceive: () -> Bool, receive: (URL, Bool) -> Void)] = [:]
 
     private init() {
@@ -1578,7 +1621,6 @@ class DeepLinkManager {
 
     func setReady() {
         isReady = true
-        hasBeenReady = true
         let urls = pendingURLs
         pendingURLs.removeAll()
         for link in urls {
@@ -1586,31 +1628,37 @@ class DeepLinkManager {
         }
     }
 
+    func captureLaunchURL(_ url: URL) {
+        launch.receive(url)
+    }
+
     func handleURL(_ url: URL) {
         launch.receive(url)
+        let initial = !initialURLDispatched && url == initialURL
+        if initial { initialURLDispatched = true }
 
         // A hybrid app opens a native path's screen itself, and tells the
         // native screens that listen; every other link is the page's. An
         // all-native app has no page: its native screens hear every link.
         if CraftHybrid.shared.isEnabled {
             if CraftHybrid.shared.handleDeepLink(url) {
-                dispatchNative(url, initial: false)
+                dispatchNative(url, initial: initial)
             } else if !CraftHybrid.shared.hasWeb {
-                enqueueNative(url)
+                enqueueNative(url, initial: initial)
             } else if isReady && webView != nil {
-                dispatchDeepLink(url, initial: false)
+                dispatchDeepLink(url, initial: initial)
             } else {
-                pendingURLs.append((url, !hasBeenReady && url == initialURL))
+                pendingURLs.append((url, initial))
             }
             return
         }
 
         if !nativeListeners.isEmpty {
-            enqueueNative(url)
+            enqueueNative(url, initial: initial)
         } else if isReady && webView != nil {
-            dispatchDeepLink(url, initial: false)
+            dispatchDeepLink(url, initial: initial)
         } else {
-            pendingURLs.append((url, !hasBeenReady && url == initialURL))
+            pendingURLs.append((url, initial))
         }
     }
 
@@ -1645,8 +1693,8 @@ class DeepLinkManager {
         nativeListeners.removeValue(forKey: token)
     }
 
-    private func enqueueNative(_ url: URL) {
-        pendingURLs.append((url, !hasBeenReady && url == initialURL))
+    private func enqueueNative(_ url: URL, initial: Bool) {
+        pendingURLs.append((url, initial))
         replayNativeLinks()
     }
 
@@ -1660,7 +1708,6 @@ class DeepLinkManager {
             let receivers = nativeListeners.values.filter { $0.canReceive() }
             guard !receivers.isEmpty else { return }
             pendingURLs.removeFirst()
-            hasBeenReady = true
             for receiver in receivers { receiver.receive(link.url, link.initial) }
         }
     }
@@ -1788,7 +1835,59 @@ struct CraftConfiguredShortcut: Codable {
     var phrases: [String]
 }
 
+struct CraftNotificationCategory: Codable {
+    struct Action: Codable {
+        struct TextInput: Codable {
+            var buttonTitle: String
+            var placeholder: String?
+        }
+        var id: String
+        var title: String
+        var destructive: Bool?
+        var foreground: Bool?
+        var authenticationRequired: Bool?
+        var textInput: TextInput?
+
+        func native() -> UNNotificationAction {
+            var options: UNNotificationActionOptions = []
+            if destructive == true { options.insert(.destructive) }
+            if foreground == true { options.insert(.foreground) }
+            if authenticationRequired == true { options.insert(.authenticationRequired) }
+            if let textInput {
+                return UNTextInputNotificationAction(identifier: id, title: title, options: options,
+                    textInputButtonTitle: textInput.buttonTitle, textInputPlaceholder: textInput.placeholder ?? "")
+            }
+            return UNNotificationAction(identifier: id, title: title, options: options)
+        }
+    }
+    var id: String
+    var actions: [Action]
+
+    static func registered(_ categories: [Self]) -> Set<UNNotificationCategory> {
+        Set(categories.map { UNNotificationCategory(identifier: $0.id, actions: $0.actions.map { $0.native() }, intentIdentifiers: [], options: []) })
+    }
+
+    static func apply(_ value: [String: Any], to content: UNMutableNotificationContent) throws {
+        for key in ["categoryId", "threadIdentifier"] {
+            if let raw = value[key], !(raw is String) {
+                throw NSError(domain: "CraftNotification", code: 1, userInfo: [NSLocalizedDescriptionKey: "\(key) must be a string"])
+            }
+        }
+        content.categoryIdentifier = value["categoryId"] as? String ?? ""
+        content.threadIdentifier = value["threadIdentifier"] as? String ?? ""
+        if let raw = value["interruptionLevel"] {
+            switch raw as? String {
+            case "passive": content.interruptionLevel = .passive
+            case "active": content.interruptionLevel = .active
+            case "timeSensitive": content.interruptionLevel = .timeSensitive
+            default: throw NSError(domain: "CraftNotification", code: 1, userInfo: [NSLocalizedDescriptionKey: "interruptionLevel must be passive, active or timeSensitive"])
+            }
+        }
+    }
+}
+
 struct CraftConfig: Codable {
+    var notificationCategories: [CraftNotificationCategory]? = nil
     var appShortcuts: [CraftConfiguredShortcut]? = nil
     var appName: String = "Craft App"
     var bundleId: String = "com.craft.app"
@@ -1895,6 +1994,7 @@ struct CraftConfig: Codable {
     /// Hybrid: app paths drawn natively, to the screen in `dist/native-screen.js`
     /// that draws each (`{"/m": "today"}`). Everything else is the web page.
     var nativeScreens: [String: String]? = nil
+    var nativeScreenConstraints: [String: [String: CraftHybridRoutes.ParameterConstraint]]? = nil
     /// The tab bar to show before the page describes its own.
     var tabs: [Tab]? = nil
     /// Static styling for the selected tab indicator; the page may still
@@ -7942,6 +8042,8 @@ struct CraftWebView: UIViewRepresentable {
                 }
 
                 let content = UNMutableNotificationContent()
+                do { try CraftNotificationCategory.apply(data, to: content) }
+                catch { self?.rejectCallback(callbackId, error: error.localizedDescription); return }
                 content.title = data["title"] as? String ?? ""
                 content.body = data["body"] as? String ?? ""
                 if let subtitle = data["subtitle"] as? String { content.subtitle = subtitle }

package/templates/CraftHybrid.swift

@@ -45,6 +45,48 @@ import Combine
 /// page script and the typescript API (`matchNativePath`) implement the same
 /// rules, and the tests hold all three to one set of cases.
 struct CraftHybridRoutes {
+    struct ParameterConstraint: Codable {
+        var pattern: String? = nil
+        var exclude: [String]? = nil
+        var normalize: String? = nil
+
+        private enum CodingKeys: String, CodingKey { case pattern, exclude, normalize }
+        private struct Field: CodingKey {
+            let stringValue: String
+            let intValue: Int? = nil
+            init(stringValue: String) { self.stringValue = stringValue }
+            init?(intValue: Int) { return nil }
+        }
+
+        init(from decoder: Decoder) throws {
+            let fields = try decoder.container(keyedBy: Field.self)
+            guard fields.allKeys.allSatisfy({ ["pattern", "exclude", "normalize"].contains($0.stringValue) }) else {
+                throw DecodingError.dataCorrupted(.init(codingPath: decoder.codingPath, debugDescription: "Unknown native path parameter constraint"))
+            }
+            let values = try decoder.container(keyedBy: CodingKeys.self)
+            pattern = values.contains(.pattern) ? try values.decode(String.self, forKey: .pattern) : nil
+            exclude = values.contains(.exclude) ? try values.decode([String].self, forKey: .exclude) : nil
+            normalize = values.contains(.normalize) ? try values.decode(String.self, forKey: .normalize) : nil
+            guard normalize == nil || normalize == "lowercase" else {
+                throw DecodingError.dataCorrupted(.init(codingPath: decoder.codingPath, debugDescription: "Unknown native path parameter normalization"))
+            }
+        }
+
+        func normalized(_ value: String) -> String { normalize == "lowercase" ? value.lowercased() : value }
+
+        func accepts(_ raw: String) -> Bool {
+            guard normalize == nil || normalize == "lowercase" else { return false }
+            let value = normalized(raw)
+            if (exclude ?? []).contains(where: { normalized($0) == value }) { return false }
+            if let pattern {
+                let range = NSRange(value.startIndex..<value.endIndex, in: value)
+                guard let expression = try? NSRegularExpression(pattern: "^(?:\(pattern))$"),
+                      expression.firstMatch(in: value, range: range)?.range == range else { return false }
+            }
+            return true
+        }
+    }
+
     struct Match: Equatable {
         let path: String
         let screen: String
@@ -55,14 +97,15 @@ struct CraftHybridRoutes {
         let pattern: String
         let segments: [String]
         let screen: String
+        let constraints: [String: ParameterConstraint]
     }
 
     private let routes: [Route]
 
-    init(_ table: [String: String]) {
+    init(_ table: [String: String], constraints: [String: [String: ParameterConstraint]] = [:]) {
         routes = table.compactMap { pattern, screen -> Route? in
             guard let normalized = CraftHybridRoutes.normalize(pattern), !screen.isEmpty else { return nil }
-            return Route(pattern: normalized, segments: CraftHybridRoutes.segments(normalized), screen: screen)
+            return Route(pattern: normalized, segments: CraftHybridRoutes.segments(normalized), screen: screen, constraints: constraints[pattern] ?? [:])
         }.sorted(by: CraftHybridRoutes.precedes)
     }
 
@@ -100,6 +143,8 @@ struct CraftHybridRoutes {
         let parts = Self.segments(path)
         for route in routes {
             guard var params = Self.bind(route.segments, to: parts) else { continue }
+            guard route.constraints.allSatisfy({ name, rule in params[name].map(rule.accepts) ?? false }) else { continue }
+            for (name, rule) in route.constraints { params[name] = params[name].map(rule.normalized) }
             if let query = raw.firstIndex(of: "?") {
                 let rest = raw[raw.index(after: query)...].split(separator: "#", maxSplits: 1).first.map(String.init) ?? ""
                 for item in rest.split(separator: "&") {
@@ -370,7 +415,7 @@ final class CraftHybrid: NSObject {
         siteURL = config.devServerURL.flatMap(URL.init(string:)).flatMap { url in
             ["http", "https"].contains((url.scheme ?? "").lowercased()) ? url : nil
         }
-        routes = CraftHybridRoutes(config.nativeScreens ?? [:])
+        routes = CraftHybridRoutes(config.nativeScreens ?? [:], constraints: config.nativeScreenConstraints ?? [:])
         startPath = config.devServerURL.flatMap(URL.init(string:)).map(CraftHybridRoutes.appPath(of:)) ?? "/"
         if startPath.isEmpty { startPath = "/" }
         let wanted = !routes.isEmpty
@@ -498,7 +543,11 @@ final class CraftHybrid: NSObject {
     /// The document-start script the hybrid page runs, with the route table
     /// and the shared storage keys filled in.
     func pageScript() -> String {
-        let routeList = (config.nativeScreens ?? [:]).map { ["pattern": $0.key, "screen": $0.value] }
+        let routeList: [[String: Any]] = (config.nativeScreens ?? [:]).map { pattern, screen in
+            let encoded = try? JSONEncoder().encode(config.nativeScreenConstraints?[pattern] ?? [:])
+            let constraints = encoded.flatMap { try? JSONSerialization.jsonObject(with: $0) } ?? [:]
+            return ["pattern": pattern, "screen": screen, "constraints": constraints]
+        }
         let share = Array((config.shareStorage ?? [:]).keys).sorted()
         // The page's key for the sign-in token, when it shares one.
         let tokenKey = CraftSession.tokenKey(config)
@@ -537,7 +586,7 @@ final class CraftHybrid: NSObject {
       var table = [];
       for (var i = 0; i < ROUTES.length; i++) {
         var pattern = normalize(ROUTES[i].pattern);
-        if (pattern && ROUTES[i].screen) table.push({ pattern: pattern, segments: segments(pattern), screen: ROUTES[i].screen });
+        if (pattern && ROUTES[i].screen) table.push({ pattern: pattern, segments: segments(pattern), screen: ROUTES[i].screen, constraints: ROUTES[i].constraints === undefined ? {} : ROUTES[i].constraints });
       }
       function wild(r) { return r.segments[r.segments.length - 1] === '*' ? 1 : 0; }
       function fixed(r) { return r.segments.filter(function (s) { return s !== '*' && s.charAt(0) !== ':'; }).length; }
@@ -562,6 +611,27 @@ final class CraftHybrid: NSObject {
         for (var i = 0; i < table.length; i++) {
           var params = bind(table[i].segments, parts);
           if (!params) continue;
+          var rules = table[i].constraints;
+          if (!rules || typeof rules !== 'object' || Array.isArray(rules)) continue;
+          var accepted = Object.keys(rules).every(function (name) {
+            var rule = table[i].constraints[name], value = params[name];
+            if (!rule || typeof rule !== 'object' || Array.isArray(rule) || typeof value !== 'string') return false;
+            if (Object.keys(rule).some(function (key) { return ['pattern', 'exclude', 'normalize'].indexOf(key) < 0; })) return false;
+            if (rule.normalize !== undefined && rule.normalize !== 'lowercase') return false;
+            if (rule.normalize === 'lowercase') value = value.toLowerCase();
+            if (rule.exclude !== undefined) {
+              if (!Array.isArray(rule.exclude) || rule.exclude.some(function (item) { return typeof item !== 'string'; })) return false;
+              if (rule.exclude.some(function (item) { return (rule.normalize === 'lowercase' ? item.toLowerCase() : item) === value; })) return false;
+            }
+            if (rule.pattern !== undefined) {
+              if (typeof rule.pattern !== 'string') return false;
+              try { var found = new RegExp('^(?:' + rule.pattern + ')$').exec(value); if (!found || found[0] !== value) return false; }
+              catch (e) { return false; }
+            }
+            params[name] = value;
+            return true;
+          });
+          if (!accepted) continue;
           var query = raw.indexOf('?');
           if (query >= 0) {
             raw.slice(query + 1).split('#')[0].split('&').forEach(function (item) {

package/templates/CraftNativeActions.swift

@@ -57,6 +57,7 @@ enum CraftNativeActions {
         values.append("viewScroll")
         values.append("crypto")
         values.append("shortcuts")
+        values.append("accessibility")
         if config.enableBiometric { values.append("biometric") }
         if config.enableSecureStorage { values.append("secureStorage") }
         if config.enableLocalDatabase { values.append("database") }
@@ -91,7 +92,7 @@ enum CraftNativeActions {
         if config.enableAppleMusic { values.append("music") }
         // `craft.background.complete(ok, id)`: the answer to a silent push or
         // a background refresh, which the app script (`nativeApp`) hears.
-        if config.backgroundRefresh?.enabled == true || config.enablePushNotifications { values.append("background") }
+        if config.backgroundRefresh?.enabled == true || config.enablePushNotifications || !(config.notificationCategories ?? []).isEmpty { values.append("background") }
         // A heart-rate strap is the app's own service (CraftHeartRate.swift),
         // so it needs no web view.
         if config.enableHeartRate { values.append(contentsOf: ["heartRate", "heartRateRecordingOwnership", "heartRateRecordingIntentIdentity"]) }
@@ -107,6 +108,8 @@ enum CraftNativeActions {
         // Video and audio kept on the phone for offline (CraftNativeMedia),
         // which the native Video element plays in place of the address.
         values.append("media")
+        values.append("media-cache-key")
+        values.append("media-remove")
         if config.enableCamera { values.append("camera") }
         if config.enableAudioRecording { values.append("audioRecording") }
         // craft.crashReporter: the app's crash and error reporter (bughq).
@@ -189,6 +192,23 @@ enum CraftNativeActions {
 
         let sync: Result<Any, CraftNativeActionError>?
         switch (module, method) {
+        case ("Accessibility", "announce"):
+            guard let text = args.first as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                sync = failure("INVALID_ARGUMENT", "Accessibility.announce needs nonempty text")
+                break
+            }
+            let options = args.count > 1 ? args[1] : NSNull()
+            guard options is NSNull || options is [String: Any] else {
+                sync = failure("INVALID_ARGUMENT", "Accessibility.announce options must be an object")
+                break
+            }
+            let polite = (options as? [String: Any])?["polite"]
+            guard polite == nil || (polite as? NSNumber).map({ CFGetTypeID($0) == CFBooleanGetTypeID() }) == true else {
+                sync = failure("INVALID_ARGUMENT", "Accessibility.announce polite must be a Boolean")
+                break
+            }
+            announce(text, polite: polite as? Bool ?? true)
+            sync = .success(true)
         case ("Crypto", "randomUUID"):
             sync = .success(UUID().uuidString.lowercased())
         case ("Device", "getInfo"):
@@ -313,9 +333,31 @@ enum CraftNativeActions {
             keepMedia(requestToken: requestToken, args: args, completion: completion)
             return
         case ("Media", "path"):
-            sync = .success(CraftNativeMedia.local(args.first as? String ?? "")?.path ?? NSNull())
+            sync = .success(CraftNativeMedia.local(CraftNativeMedia.identity(args.first as? String ?? "", options: args.count > 1 ? args[1] as? [String: Any] ?? [:] : [:]))?.path ?? NSNull())
+        case ("Media", "remove"):
+            let options = args.count > 1 ? args[1] as? [String: Any] ?? [:] : [:]
+            if let value = options["cacheKey"], !(value is NSNull) {
+                guard let key = value as? String, !key.isEmpty, key.utf8.count <= 1024 else {
+                    sync = failure("INVALID_ARGUMENT", "media.remove cacheKey must be a nonempty string of at most 1024 bytes")
+                    break
+                }
+            }
+            let address = CraftNativeMedia.identity(args.first as? String ?? "", options: options)
+            guard !address.isEmpty else {
+                sync = failure("INVALID_ARGUMENT", "media.remove needs a source or cache key")
+                break
+            }
+            DispatchQueue.global(qos: .utility).async {
+                do { complete(requestToken, .success(try CraftNativeMedia.remove(address)), completion) }
+                catch { complete(requestToken, failure("IO_ERROR", "The media copy could not be removed"), completion) }
+            }
+            return
         case ("Media", "prune"):
-            let keep = (args.first as? [Any] ?? []).compactMap { $0 as? String }
+            let keep = (args.first as? [Any] ?? []).compactMap { value -> String? in
+                if let url = value as? String { return url }
+                guard let source = value as? [String: Any], let url = source["url"] as? String else { return nil }
+                return CraftNativeMedia.identity(url, options: source)
+            }
             DispatchQueue.global(qos: .utility).async {
                 complete(requestToken, .success(CraftNativeMedia.prune(keep: keep)), completion)
             }
@@ -661,7 +703,7 @@ enum CraftNativeActions {
             // The app script's answer to `craftSilentPush` or
             // `craftBackgroundRefresh`: args `[ok, id?]`, with no id for
             // everything still pending, as a page's `craft.background.complete`.
-            guard config.backgroundRefresh?.enabled == true || config.enablePushNotifications else {
+            guard config.backgroundRefresh?.enabled == true || config.enablePushNotifications || !(config.notificationCategories ?? []).isEmpty else {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Background work is disabled"), completion)
                 return
             }
@@ -690,7 +732,15 @@ enum CraftNativeActions {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Local notifications are disabled"), completion)
                 return
             }
-            notifications(requestToken: requestToken, method: method, args: args, completion: completion)
+            // Staging notification media can copy large files; keep it off the
+            // renderer/JavaScript thread. UserNotifications is thread-safe.
+            if method == "schedule" {
+                DispatchQueue.global(qos: .utility).async {
+                    notifications(requestToken: requestToken, method: method, args: args, completion: completion)
+                }
+            } else {
+                notifications(requestToken: requestToken, method: method, args: args, completion: completion)
+            }
             return
         default:
             sync = failure("UNKNOWN_ACTION", "Unsupported native API")
@@ -924,18 +974,19 @@ enum CraftNativeActions {
         args: [Any],
         completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
     ) {
-        guard let address = args.first as? String,
-              let url = URL(string: address),
+        guard let source = args.first as? String,
+              let url = URL(string: source),
               let scheme = url.scheme?.lowercased(), scheme == "https" || scheme == "http",
               url.host?.isEmpty == false else {
             complete(requestToken, failure("INVALID_ARGUMENT", "media.keep needs an absolute http or https URL"), completion)
             return
         }
+        let options = args.count > 1 ? args[1] as? [String: Any] ?? [:] : [:]
+        let address = CraftNativeMedia.identity(source, options: options)
         if let kept = CraftNativeMedia.local(address) {
             complete(requestToken, .success(CraftNativeMedia.describe(address, kept)), completion)
             return
         }
-        let options = args.count > 1 ? args[1] as? [String: Any] ?? [:] : [:]
         var request = URLRequest(url: url, timeoutInterval: craftNativeFetchTimeoutSeconds)
         request.httpMethod = "GET"
         if let headers = options["headers"] as? [String: Any] {
@@ -969,7 +1020,8 @@ enum CraftNativeActions {
         // 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)
+        guard let ownership = CraftNativeMedia.ownershipStamp(address, flight: flight) else { return }
+        let task = CraftNativeMediaTransfers.shared.start(request, address: address, flight: flight, ownership: ownership, wifiOnly: wifiOnly)
         cancellationLock.lock()
         // Unless it answered already (a queued transfer, or an instant failure).
         if CraftNativeMedia.isWaiting(address, flight: flight) { fetchTasks[requestToken] = task }
@@ -1305,11 +1357,17 @@ enum CraftNativeActions {
         return failure("DATABASE_ERROR", message)
     }
 
-    private static func notifications(
+    static func notifications(
         requestToken: String,
         method: String,
         args: [Any],
-        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void,
+        authorize: (@escaping (Bool, Error?) -> Void) -> Void = {
+            UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge], completionHandler: $0)
+        },
+        submit: @escaping (UNNotificationRequest, @escaping (Error?) -> Void) -> Void = {
+            UNUserNotificationCenter.current().add($0, withCompletionHandler: $1)
+        }
     ) {
         let center = UNUserNotificationCenter.current()
         switch method {
@@ -1330,16 +1388,35 @@ enum CraftNativeActions {
                 }), completion)
             }
         case "schedule":
+            guard !isCancelled(requestToken) else {
+                complete(requestToken, failure("CANCELLED", "Notification request cancelled"), completion)
+                return
+            }
             guard let value = args.first as? [String: Any], let title = value["title"] as? String, !title.isEmpty else {
                 complete(requestToken, failure("INVALID_ARGUMENT", "Notifications.schedule needs a title"), completion)
                 return
             }
-            center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, authorizationError in
+            let content = UNMutableNotificationContent()
+            let files: CraftNotificationAttachments
+            do {
+                try CraftNotificationCategory.apply(value, to: content)
+                files = try CraftNotificationAttachments(value["attachments"])
+                content.attachments = files.attachments
+            } catch {
+                complete(requestToken, failure("INVALID_ARGUMENT", error.localizedDescription), completion)
+                return
+            }
+            authorize { granted, authorizationError in
+                guard !isCancelled(requestToken) else {
+                    files.cleanup()
+                    complete(requestToken, failure("CANCELLED", "Notification request cancelled"), completion)
+                    return
+                }
                 guard authorizationError == nil, granted else {
+                    files.cleanup()
                     complete(requestToken, failure("PERMISSION_DENIED", authorizationError?.localizedDescription ?? "Notification permission denied"), completion)
                     return
                 }
-                let content = UNMutableNotificationContent()
                 content.title = title
                 content.body = value["body"] as? String ?? ""
                 content.sound = .default
@@ -1353,7 +1430,7 @@ enum CraftNativeActions {
                 let id = (value["id"] as? String).flatMap { validKey($0) } ?? UUID().uuidString
                 let delay = craftNativeNumber(value["delay"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil }
                 let trigger = delay.map { UNTimeIntervalNotificationTrigger(timeInterval: max($0 / 1_000, 1), repeats: false) }
-                center.add(UNNotificationRequest(identifier: id, content: content, trigger: trigger)) { addError in
+                files.schedule(UNNotificationRequest(identifier: id, content: content, trigger: trigger), submit: submit) { addError in
                     if let addError = addError {
                         complete(requestToken, failure("NOTIFICATION_ERROR", addError.localizedDescription), completion)
                     } else {
@@ -1424,6 +1501,20 @@ enum CraftNativeActions {
         CraftNativeActionError(code: code, message: message)
     }
 
+    /// Announcements report a status without moving VoiceOver's current focus.
+    static func announce(_ text: String, polite: Bool,
+                         post: (UIAccessibility.Notification, Any?) -> Void = { UIAccessibility.post(notification: $0, argument: $1) }) {
+        let spoken: NSAttributedString
+        if #available(iOS 17.0, *) {
+            spoken = NSAttributedString(string: text, attributes: [
+                .accessibilitySpeechAnnouncementPriority: polite ? UIAccessibilityPriority.low : UIAccessibilityPriority.default,
+            ])
+        } else {
+            spoken = NSAttributedString(string: text, attributes: [.accessibilitySpeechQueueAnnouncement: polite])
+        }
+        post(.announcement, spoken)
+    }
+
     private static func failure(_ code: String, _ message: String) -> Result<Any, CraftNativeActionError> {
         .failure(error(code, message))
     }