craft-native 0.0.377 → 0.0.380

package/README.md

@@ -658,7 +658,15 @@ This lets browser simulations checkpoint on backgrounding with the same contract
 as a native shell. Storage failures must still be handled by the caller.
 
 Await `platform.call('Storage', 'set', [key, value], signal)` before reporting
-a saved checkpoint. `craft.storage.setSync` updates the immediate UI cache and
+a saved checkpoint. The browser captures the key and JSON value when the call
+starts, before waiting for a Web Lock. Later mutations of your simulation state
+or argument array cannot retarget or change that pending save. `setIfAbsent`
+captures its value too; `compareAndSet` captures both the expected and next JSON
+values (including their `toJSON` representation). Invalid JSON input rejects
+without changing the previous checkpoint. Cancellation and account-scope checks
+still run before committing the captured value.
+
+`craft.storage.setSync` updates the immediate UI cache and
 queues its write when Web Locks are available; it cannot acknowledge durability
 or propagate a later quota failure. Background events are an opportunity to
 checkpoint, but browsers can terminate a page before queued work finishes, so

package/dist/browser.js

@@ -242,8 +242,18 @@ async function createBrowserStorage(options) {
       signal?.throwIfAborted();
       const captured = capture();
       const wasAvailable = available();
-      await waitForAccount(accountChanged(), signal);
       const name = String(args[0] ?? "");
+      let json;
+      let expected;
+      if (wasAvailable && module === "Storage") {
+        if (method === "set" || method === "setIfAbsent" && lock)
+          json = encode(args[1]);
+        if (method === "compareAndSet" && lock) {
+          expected = parse(encode(args[1]));
+          json = encode(args[2]);
+        }
+      }
+      await waitForAccount(accountChanged(), signal);
       if (module === "Storage") {
         if (!wasAvailable)
           throw scopeChanged();
@@ -253,7 +263,7 @@ async function createBrowserStorage(options) {
           if (method === "get")
             return parse(storage.getItem(address));
           if (method === "set") {
-            storage.setItem(address, encode(args[1]));
+            storage.setItem(address, json);
             return true;
           }
           if (method === "remove") {
@@ -274,12 +284,12 @@ async function createBrowserStorage(options) {
             if (method === "setIfAbsent") {
               if (raw !== null)
                 return false;
-              storage.setItem(address, encode(args[1]));
+              storage.setItem(address, json);
               return true;
             }
-            if (raw === null || !jsonEqual(parse(raw), args[1]))
+            if (raw === null || !jsonEqual(parse(raw), expected))
               return false;
-            storage.setItem(address, encode(args[2]));
+            storage.setItem(address, json);
             return true;
           }
           throw Object.assign(new Error(`Unsupported browser storage operation ${method}`), { code: "UNSUPPORTED" });

package/dist/cli.js

@@ -3047,7 +3047,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.377";
+var version = "0.0.380";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -375,7 +375,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.377";
+var version = "0.0.380";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.377";
+var version = "0.0.380";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/src/index.d.ts

@@ -44,6 +44,8 @@ export interface CraftConfig {
     /** Runs from the generated project root after `craft ios build` writes it. */
     postGenerate?: CraftPostGenerateHook;
     backgroundColor?: string;
+    /** Default tint for native controls and selected tabs, as #RRGGBB. */
+    tintColor?: string;
     /** The launch and webview background while the phone is in Dark Mode. */
     backgroundColorDark?: string;
     /** Edge-swipe back and forward through the page's history, pushState entries included. */

package/dist/ios/src/index.js

@@ -1421,6 +1421,8 @@ async function init(options) {
   if (config.renderer !== "web" && config.renderer !== "native") {
     throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
   }
+  if (config.tintColor !== undefined && !/^#[0-9a-f]{6}$/i.test(config.tintColor))
+    throw new Error("iOS tintColor must be a #RRGGBB color");
   const selection = config.tabBar?.selection;
   if (selection?.cornerRadius !== undefined && (!Number.isFinite(selection.cornerRadius) || selection.cornerRadius < 0))
     throw new Error("iOS tabBar.selection.cornerRadius must be a finite non-negative number");

package/dist/ios/templates/CraftApp.swift

@@ -700,6 +700,7 @@ struct CraftApp: App {
                     .ignoresSafeArea(.keyboard, edges: .bottom)
                 }
             }
+                .tint(appState.config.tintColor.flatMap { UIColor(hex: $0) }.map { Color($0) })
                 .preferredColorScheme(appState.appearanceScheme)
                 .environmentObject(appState)
                 .onOpenURL { url in
@@ -1788,6 +1789,8 @@ struct CraftConfig: Codable {
     /// which keep what `darkMode` pinned.
     var appearance: String? = nil
     var backgroundColor: String = "#1a1a2e"
+    /// Default native control and selected-tab tint, independent of page chrome.
+    var tintColor: String? = nil
     /// The background while the phone is in Dark Mode; the light one if unset.
     var backgroundColorDark: String? = nil
     /// Edge-swipe back and forward through the page's history.

package/dist/ios/templates/CraftHybrid.swift

@@ -1192,6 +1192,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
             }
         }
         view.backgroundColor = config.resolvedBackgroundColor
+        if let tint = config.tintColor.flatMap({ UIColor(hex: $0) }) { view.tintColor = tint }
         parking.frame = view.bounds
         parking.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         view.insertSubview(parking, at: 0)
@@ -1265,7 +1266,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 view.layoutIfNeeded()
             }
         }
-        tabBar.tintColor = chrome.tint ?? view.tintColor
+        tabBar.tintColor = chrome.tint ?? config.tintColor.flatMap { UIColor(hex: $0) } ?? view.tintColor
         let hidden = !chrome.tabBarVisible || chrome.tabs.isEmpty
         if #available(iOS 18.0, *) { setTabBarHidden(hidden, animated: false) }
         else { tabBar.isHidden = hidden }
@@ -1411,7 +1412,10 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         accessoryGlass.frame = accessoryButton.frame
         let badgeWidth = max(18, accessoryBadge.intrinsicContentSize.width + 8)
         accessoryBadge.frame = CGRect(x: accessoryButton.frame.maxX - badgeWidth + 4, y: accessoryButton.frame.minY - 3, width: badgeWidth, height: 18)
-        CraftChrome.shared.layoutChanged(tabBar.isHidden ? 0 : max(0, view.bounds.maxY - tabBar.frame.minY) + (accessoryModel == nil ? 0 : (iconOnly ? 56 : 44)))
+        // A compact action floats over the page, not across its whole width.
+        // Only the older-system full-width shelf reserves space in web layout.
+        let accessoryInset: CGFloat = accessoryModel != nil && !iconOnly ? 44 : 0
+        CraftChrome.shared.layoutChanged(tabBar.isHidden ? 0 : max(0, view.bounds.maxY - tabBar.frame.minY) + accessoryInset)
     }
 
     private var webAttached = false
@@ -2273,10 +2277,11 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
     }
 
     private func safeAreaForTabBar() -> CGFloat {
-        // UIKit supplies the bar (and on iOS 26, its accessory) inset. Only
-        // the older-system accessory above that bar needs an extra inset.
+        // UIKit supplies the bar (and on iOS 26, its standard accessory) inset.
+        // Compact actions overlay content; only the older full-width shelf
+        // needs an extra inset.
         let chrome = CraftChrome.shared
-        if chrome.tabBarVisible && !chrome.tabs.isEmpty && chrome.tabAccessory?.iconOnly == true { return 56 }
+        if chrome.tabAccessory?.iconOnly == true { return 0 }
 #if compiler(>=6.2)
         if #available(iOS 26.0, *) { return 0 }
 #endif

package/dist/ios/templates/CraftNativeActions.swift

@@ -278,13 +278,13 @@ enum CraftNativeActions {
         case ("Files", "pickVideo"):
             let options = args.first as? [String: Any] ?? [:]
             DispatchQueue.main.async {
-                CraftNativeFiles.pickVideo(options) { completeFile(requestToken, $0, completion) }
+                CraftNativeFiles.pickVideo(options, isCancelled: { isCancelled(requestToken) }) { completeFile(requestToken, $0, completion) }
             }
             return
         case ("Files", "pickFile"):
             let options = args.first as? [String: Any] ?? [:]
             DispatchQueue.main.async {
-                CraftNativeFiles.pickFile(options) { completeFile(requestToken, $0, completion) }
+                CraftNativeFiles.pickFile(options, isCancelled: { isCancelled(requestToken) }) { completeFile(requestToken, $0, completion) }
             }
             return
         case ("Files", "download"):
@@ -700,6 +700,13 @@ enum CraftNativeActions {
         }
     }
 
+    /// Read without consuming the token: final delivery owns its removal.
+    static func isCancelled(_ requestToken: String) -> Bool {
+        cancellationLock.lock()
+        defer { cancellationLock.unlock() }
+        return cancelledRequests.contains(requestToken)
+    }
+
     static func cancel(requestToken: String) {
         cancellationLock.lock()
         cancelledRequests.insert(requestToken)
@@ -1836,7 +1843,9 @@ enum CraftSnapshots {
         revisions[name] = mine
         pending[name] = .some(json)
         cache.removeObject(forKey: name as NSString)
-        lock.unlock()
+        // Admission and queue submission are one ordering boundary. Unlocking
+        // before enqueue lets an older caller overtake a newer revision on disk
+        // while the cache still retains the newer value.
         queue.async {
             var ok = true
             do {
@@ -1863,6 +1872,7 @@ enum CraftSnapshots {
                 completion?(ok)
             }
         }
+        lock.unlock()
     }
 
     /// Every snapshot there is: on disk, and written but not on disk yet.

package/dist/ios/templates/CraftNativeFiles.swift

@@ -1,4 +1,5 @@
 import CryptoKit
+import Darwin
 import Foundation
 import ImageIO
 import Network
@@ -74,11 +75,21 @@ enum CraftNativeFiles {
         return info
     }
 
-    /// Forget a file made here. True when there was one.
+    /// Forget only the requested owned file. True only when it was removed;
+    /// pruning its now-empty directory is best effort, not recursive deletion.
     @discardableResult
     static func remove(_ path: String) -> Bool {
         guard let url = owned(path) else { return false }
-        try? FileManager.default.removeItem(at: url.deletingLastPathComponent())
+        // unlink cannot recursively remove a directory if the entry changes
+        // after ownership validation. A denied or already-gone file is false.
+        guard url.path.withCString({ unlink($0) }) == 0 else { return false }
+        let parent = url.deletingLastPathComponent()
+        let base = root.standardizedFileURL.resolvingSymlinksInPath()
+        if parent.path != base.path {
+            // rmdir refuses nonempty directories, even if a sibling appears
+            // concurrently. Never recursively delete an imported file's peers.
+            _ = parent.path.withCString { rmdir($0) }
+        }
         return true
     }
 
@@ -298,7 +309,8 @@ enum CraftNativeFiles {
 
     /// System pickers grant access to just the selected video. Copy it while
     /// the provider's URL is valid; no movie bytes cross JavaScriptCore.
-    static func pickVideo(_ options: [String: Any], done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+    static func pickVideo(_ options: [String: Any], isCancelled: @escaping () -> Bool = { false }, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        guard !isCancelled() else { done(.failure(importCancelled())); return }
         guard activePicker == nil else {
             done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
             return
@@ -313,7 +325,7 @@ enum CraftNativeFiles {
             DispatchQueue.main.async { activePicker = nil; done(result) }
         }
         if options["source"] as? String == "files" {
-            let delegate = VideoDocumentDelegate(limit: limit, done: finish)
+            let delegate = VideoDocumentDelegate(limit: limit, isCancelled: isCancelled, done: finish)
             var types: [UTType] = [.movie]
             if let webm = UTType(filenameExtension: "webm") { types.append(webm) }
             let picker = UIDocumentPickerViewController(forOpeningContentTypes: types, asCopy: true)
@@ -329,7 +341,7 @@ enum CraftNativeFiles {
             configuration.filter = .videos
             configuration.selectionLimit = 1
             configuration.preferredAssetRepresentationMode = .current
-            let delegate = VideoLibraryDelegate(limit: limit, done: finish)
+            let delegate = VideoLibraryDelegate(limit: limit, isCancelled: isCancelled, done: finish)
             let picker = PHPickerViewController(configuration: configuration)
             picker.delegate = delegate
             activePicker = delegate
@@ -345,7 +357,8 @@ enum CraftNativeFiles {
     /// Pick one or more documents and copy them into app-owned storage while
     /// the security-scoped URLs are valid. `contentTypes` accepts MIME types,
     /// UTIs, or filename extensions; an empty list means any document.
-    static func pickFile(_ options: [String: Any], done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+    static func pickFile(_ options: [String: Any], isCancelled: @escaping () -> Bool = { false }, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        guard !isCancelled() else { done(.failure(importCancelled())); return }
         guard activePicker == nil else {
             done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
             return
@@ -372,7 +385,7 @@ enum CraftNativeFiles {
         let finish: (Result<Any, CraftNativeActionError>) -> Void = { result in
             DispatchQueue.main.async { activePicker = nil; done(result) }
         }
-        let delegate = FileDocumentDelegate(limit: limit, done: finish)
+        let delegate = FileDocumentDelegate(limit: limit, isCancelled: isCancelled, done: finish)
         let picker = UIDocumentPickerViewController(forOpeningContentTypes: types, asCopy: true)
         picker.allowsMultipleSelection = selectionLimit > 1
         picker.delegate = delegate
@@ -409,28 +422,98 @@ enum CraftNativeFiles {
 
     /// Copy an arbitrary selected document into Craft's private file area and
     /// return the same descriptor used by downloads, writes, and uploads.
-    static func copyFile(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
+    static func copyFile(_ source: URL, limit: Int, isCancelled: () -> Bool = { false }) -> Result<Any, CraftNativeActionError> {
+        let contentType = (try? source.resourceValues(forKeys: [.contentTypeKey]))?.contentType
+        return copyImport(source, limit: limit, type: mimeType(for: source, contentType: contentType), isCancelled: isCancelled)
+    }
+
+    private static func importCancelled() -> CraftNativeActionError {
+        CraftNativeActionError(code: "CANCELLED", message: "The file import was cancelled")
+    }
+
+    /// Validate the opened file, not just its path metadata. Nonblocking open
+    /// avoids hanging on a FIFO; no-follow refuses symlinks. Metadata is only
+    /// an early rejection: enforce the limit on bytes actually read as well.
+    private static func copyImport(_ source: URL, limit: Int, type: String, isCancelled: () -> Bool) -> Result<Any, CraftNativeActionError> {
+        var destination: URL?
+        var succeeded = false
+        defer {
+            if !succeeded, let destination {
+                _ = destination.path.withCString { unlink($0) }
+                _ = destination.deletingLastPathComponent().path.withCString { rmdir($0) }
+            }
+        }
         do {
-            let values = try source.resourceValues(forKeys: [.fileSizeKey, .contentTypeKey])
-            let size: Int
-            if let fileSize = values.fileSize {
-                size = fileSize
-            } else {
-                size = ((try? FileManager.default.attributesOfItem(atPath: source.path))?[.size] as? NSNumber)?.intValue ?? 0
-            }
-            guard size > 0, size <= limit else {
-                return .failure(CraftNativeActionError(code: "FILE_TOO_LARGE", message: "Choose a nonempty file under \(limit / 1024 / 1024)MB."))
-            }
-            let destination = try newFile(named: source.lastPathComponent)
-            do { try FileManager.default.copyItem(at: source, to: destination) }
-            catch { try? FileManager.default.removeItem(at: destination.deletingLastPathComponent()); throw error }
-            let type = mimeType(for: source, contentType: values.contentType)
-            return .success(describe(destination, type: type))
+            guard !isCancelled() else { throw importCancelled() }
+            guard source.isFileURL else {
+                throw CraftNativeActionError(code: "INVALID_FILE", message: "Choose a regular local file")
+            }
+            let descriptor = source.path.withCString { open($0, O_RDONLY | O_NONBLOCK | O_NOFOLLOW | O_CLOEXEC) }
+            guard descriptor >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+            let input = FileHandle(fileDescriptor: descriptor, closeOnDealloc: true)
+            defer { try? input.close() }
+            var metadata = stat()
+            guard fstat(descriptor, &metadata) == 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+            guard metadata.st_mode & S_IFMT == S_IFREG else {
+                throw CraftNativeActionError(code: "INVALID_FILE", message: "Choose a regular file, not a directory or special file")
+            }
+            let oversized = CraftNativeActionError(code: "FILE_TOO_LARGE", message: "Choose a nonempty file no larger than \(limit) bytes.")
+            guard limit > 0, metadata.st_size > 0, metadata.st_size <= limit else { throw oversized }
+            let target = try newFile(named: source.lastPathComponent)
+            destination = target
+            guard FileManager.default.createFile(atPath: target.path, contents: nil) else {
+                throw CraftNativeActionError(code: "WRITE_ERROR", message: "The imported file could not be created")
+            }
+            let output = try FileHandle(forWritingTo: target)
+            defer { try? output.close() }
+            var total = 0
+            while true {
+                guard !isCancelled() else { throw importCancelled() }
+                // At the limit, probe one more byte without writing it. This
+                // also avoids overflowing limit + 1 for an Int.max caller.
+                let chunk = try input.read(upToCount: max(1, min(64 * 1024, limit - total))) ?? Data()
+                guard !isCancelled() else { throw importCancelled() }
+                if chunk.isEmpty { break }
+                guard chunk.count <= limit - total else { throw oversized }
+                try output.write(contentsOf: chunk)
+                total += chunk.count
+            }
+            guard total > 0 else { throw oversized }
+            try output.close()
+            guard !isCancelled() else { throw importCancelled() }
+            succeeded = true
+            return .success(describe(target, type: type))
         } catch {
-            return .failure(CraftNativeActionError(code: "READ_ERROR", message: error.localizedDescription))
+            return .failure((error as? CraftNativeActionError) ?? CraftNativeActionError(code: "READ_ERROR", message: error.localizedDescription))
         }
     }
 
+    /// All-or-nothing ownership for a multi-document selection. Security scope
+    /// lasts through each copy; cancellation also rolls back earlier results.
+    static func copyFiles(_ sources: [URL], limit: Int, isCancelled: () -> Bool = { false }) -> Result<Any, CraftNativeActionError> {
+        var results: [[String: Any]] = []
+        var succeeded = false
+        defer {
+            if !succeeded { results.compactMap { $0["path"] as? String }.forEach { remove($0) } }
+        }
+        for source in sources {
+            guard !isCancelled() else { return .failure(importCancelled()) }
+            let granted = source.startAccessingSecurityScopedResource()
+            defer { if granted { source.stopAccessingSecurityScopedResource() } }
+            switch copyFile(source, limit: limit, isCancelled: isCancelled) {
+            case .success(let value):
+                guard let info = value as? [String: Any] else {
+                    return .failure(CraftNativeActionError(code: "READ_ERROR", message: "The selected file could not be described"))
+                }
+                results.append(info)
+            case .failure(let error): return .failure(error)
+            }
+        }
+        guard !isCancelled() else { return .failure(importCancelled()) }
+        succeeded = true
+        return .success(results)
+    }
+
     private static func mimeType(for source: URL, contentType: UTType?) -> String {
         let generic = "application/octet-stream"
         if let preferred = contentType?.preferredMIMEType, preferred != generic { return preferred }
@@ -450,82 +533,60 @@ enum CraftNativeFiles {
 
     private final class FileDocumentDelegate: NSObject, UIDocumentPickerDelegate {
         let limit: Int
+        let isCancelled: () -> Bool
         let done: (Result<Any, CraftNativeActionError>) -> Void
-        init(limit: Int, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.done = done }
+        init(limit: Int, isCancelled: @escaping () -> Bool, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.isCancelled = isCancelled; self.done = done }
         func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) { done(.success([])) }
         func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
             guard !urls.isEmpty else { done(.success([])); return }
-            let (limit, done) = (self.limit, self.done)
+            let (limit, isCancelled, done) = (self.limit, self.isCancelled, self.done)
             DispatchQueue.global(qos: .userInitiated).async {
-                var results: [[String: Any]] = []
-                for url in urls {
-                    let granted = url.startAccessingSecurityScopedResource()
-                    defer { if granted { url.stopAccessingSecurityScopedResource() } }
-                    switch CraftNativeFiles.copyFile(url, limit: limit) {
-                    case .success(let value):
-                        guard let info = value as? [String: Any] else { done(.failure(CraftNativeActionError(code: "READ_ERROR", message: "The selected file could not be described"))); return }
-                        results.append(info)
-                    case .failure(let error):
-                        results.compactMap { $0["path"] as? String }.forEach { CraftNativeFiles.remove($0) }
-                        done(.failure(error))
-                        return
-                    }
-                }
-                done(.success(results))
+                done(CraftNativeFiles.copyFiles(urls, limit: limit, isCancelled: isCancelled))
             }
         }
     }
 
-    static func copyVideo(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
+    static func copyVideo(_ source: URL, limit: Int, isCancelled: () -> Bool = { false }) -> Result<Any, CraftNativeActionError> {
         let ext = source.pathExtension.lowercased()
         let types = ["mp4": "video/mp4", "m4v": "video/x-m4v", "mov": "video/quicktime", "webm": "video/webm"]
         guard let type = types[ext] else {
             return .failure(CraftNativeActionError(code: "INVALID_VIDEO", message: "Choose an MP4, MOV or WebM video."))
         }
-        do {
-            let size = ((try FileManager.default.attributesOfItem(atPath: source.path))[.size] as? NSNumber)?.intValue ?? 0
-            guard size > 0, size <= limit else {
-                return .failure(CraftNativeActionError(code: "FILE_TOO_LARGE", message: "Choose a nonempty video under \(limit / 1024 / 1024)MB."))
-            }
-            let destination = try newFile(named: source.lastPathComponent)
-            do { try FileManager.default.copyItem(at: source, to: destination) }
-            catch { try? FileManager.default.removeItem(at: destination.deletingLastPathComponent()); throw error }
-            return .success(describe(destination, type: type))
-        } catch {
-            return .failure(CraftNativeActionError(code: "READ_ERROR", message: error.localizedDescription))
-        }
+        return copyImport(source, limit: limit, type: type, isCancelled: isCancelled)
     }
 
     private final class VideoLibraryDelegate: NSObject, PHPickerViewControllerDelegate {
         let limit: Int
+        let isCancelled: () -> Bool
         let done: (Result<Any, CraftNativeActionError>) -> Void
-        init(limit: Int, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.done = done }
+        init(limit: Int, isCancelled: @escaping () -> Bool, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.isCancelled = isCancelled; self.done = done }
         func picker(_ picker: PHPickerViewController, didFinishPicking results: [PHPickerResult]) {
             picker.dismiss(animated: true)
             guard let provider = results.first?.itemProvider else { done(.success(NSNull())); return }
-            let (limit, done) = (self.limit, self.done)
+            let (limit, isCancelled, done) = (self.limit, self.isCancelled, self.done)
             provider.loadFileRepresentation(forTypeIdentifier: UTType.movie.identifier) { url, error in
                 guard let url else {
                     done(.failure(CraftNativeActionError(code: "READ_ERROR", message: error?.localizedDescription ?? "The video could not be read")))
                     return
                 }
-                done(CraftNativeFiles.copyVideo(url, limit: limit))
+                done(CraftNativeFiles.copyVideo(url, limit: limit, isCancelled: isCancelled))
             }
         }
     }
 
     private final class VideoDocumentDelegate: NSObject, UIDocumentPickerDelegate {
         let limit: Int
+        let isCancelled: () -> Bool
         let done: (Result<Any, CraftNativeActionError>) -> Void
-        init(limit: Int, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.done = done }
+        init(limit: Int, isCancelled: @escaping () -> Bool, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.isCancelled = isCancelled; self.done = done }
         func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) { done(.success(NSNull())) }
         func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
             guard let url = urls.first else { done(.success(NSNull())); return }
-            let (limit, done) = (self.limit, self.done)
+            let (limit, isCancelled, done) = (self.limit, self.isCancelled, self.done)
             DispatchQueue.global(qos: .userInitiated).async {
                 let granted = url.startAccessingSecurityScopedResource()
                 defer { if granted { url.stopAccessingSecurityScopedResource() } }
-                done(CraftNativeFiles.copyVideo(url, limit: limit))
+                done(CraftNativeFiles.copyVideo(url, limit: limit, isCancelled: isCancelled))
             }
         }
     }

package/dist/ios/templates/CraftNativeScreen.swift

@@ -15,7 +15,7 @@ import UIKit
 
 private let craftNativeCapabilityTimeoutMilliseconds = 30_000
 
-/// A retained JavaScript context must lose synchronous storage access when
+/// A retained JavaScript context must lose storage and snapshot access when
 /// its screen closes. Only the actual synchronous unmount callback may finish
 /// its cleanup; queued script work runs after that allowance ends.
 private final class CraftNativeStorageLifetime {
@@ -4929,7 +4929,7 @@ final class CraftNativeSvgView: UIView {
     private func updateFrames() {
         if isAnimating {
             if animationStart == nil { animationStart = CACurrentMediaTime() }
-            CraftNativeFrameClock.shared.request(self) { [weak self] in self?.nextFrame() }
+            CraftNativeFrameClock.shared.request(self) { [weak self] _ in self?.nextFrame() }
         } else {
             animationStart = nil
             CraftNativeFrameClock.shared.cancel(self)
@@ -4941,7 +4941,7 @@ final class CraftNativeSvgView: UIView {
         // Drawn only while some of it is on screen; a row scrolled away keeps
         // its time and is right when it comes back.
         if let window, window.bounds.intersects(convert(bounds, to: window)) { setNeedsDisplay() }
-        CraftNativeFrameClock.shared.request(self) { [weak self] in self?.nextFrame() }
+        CraftNativeFrameClock.shared.request(self) { [weak self] _ in self?.nextFrame() }
     }
 
     private static func hasAnimation(_ children: [Any]) -> Bool {
@@ -5713,8 +5713,10 @@ extension CAAnimation {
 final class CraftNativeFrameClock: NSObject {
     static let shared = CraftNativeFrameClock()
 
-    private var waiting: [ObjectIdentifier: () -> Void] = [:]
+    private var waiting: [ObjectIdentifier: (CFTimeInterval) -> Void] = [:]
     private var link: CADisplayLink?
+    /// The display's monotonic timestamp, captured before handing off scripts.
+    private var lastTimestamp: CFTimeInterval = 0
 
     /// How many screens wait for the next frame.
     var waitingCount: Int { waiting.count }
@@ -5722,7 +5724,7 @@ final class CraftNativeFrameClock: NSObject {
     var isRunning: Bool { link.map { !$0.isPaused } ?? false }
 
     /// `deliver` on the next frame, once. Asking again before it comes keeps one.
-    func request(_ owner: AnyObject, _ deliver: @escaping () -> Void) {
+    func request(_ owner: AnyObject, _ deliver: @escaping (CFTimeInterval) -> Void) {
         waiting[ObjectIdentifier(owner)] = deliver
         if link == nil {
             let link = CADisplayLink(target: self, selector: #selector(frame(_:)))
@@ -5742,10 +5744,15 @@ final class CraftNativeFrameClock: NSObject {
     }
 
     @objc private func frame(_ link: CADisplayLink) {
+        let timestamp = link.timestamp
+        // Keep waiting for a new vsync rather than delivering a duplicate or
+        // stale display timestamp after the link is paused and requested again.
+        guard timestamp.isFinite, timestamp > lastTimestamp else { return }
+        lastTimestamp = timestamp
         let due = waiting
         waiting.removeAll()
         if waiting.isEmpty { link.isPaused = true }
-        due.values.forEach { $0() }
+        due.values.forEach { $0(timestamp) }
     }
 }
 
@@ -6015,6 +6022,18 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// The script asked for an animation frame it has not had yet
     /// (`requestAnimationFrame`, CraftNativeFrameClock). Main thread only.
     private var frameWanted = false
+    private let frameTimeOrigin = CACurrentMediaTime()
+    private var lastFrameTimestamp = -Double.infinity
+    /// Vsync is delivered on main but may wait on the script queue. Closing
+    /// on main invalidates queued delivery without retaining the controller
+    /// or holding a lock while JavaScript calls synchronous UIKit APIs.
+    private final class FrameDelivery {
+        private let lock = NSLock()
+        private var open = true
+        var isOpen: Bool { lock.withLock { open } }
+        func close() { lock.withLock { open = false } }
+    }
+    private let frameDelivery = FrameDelivery()
     private var lifecycleObservers: [NSObjectProtocol] = []
     private var deepLinkListener: UUID?
     private var keyboardSafeAreaInset: CGFloat = 0
@@ -6070,6 +6089,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         CraftInterfaceStyleController.apply(to: self, config: config)
         navigationItem.title = routeName ?? config.appName
         view.backgroundColor = config.resolvedBackgroundColor
+        if let tint = config.tintColor.flatMap({ UIColor(hex: $0) }) { view.tintColor = tint }
         rootStack.axis = .vertical
         rootStack.alignItems = "stretch"
         rootStack.translatesAutoresizingMaskIntoConstraints = false
@@ -6214,15 +6234,34 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         guard !runtimeDisposed, !frameWanted else { return }
         frameWanted = true
         guard isAppScript || reportedVisible != false else { return }
-        CraftNativeFrameClock.shared.request(self) { [weak self] in self?.fireFrame() }
+        CraftNativeFrameClock.shared.request(self) { [weak self] timestamp in self?.fireFrame(timestamp: timestamp) }
     }
 
-    private func fireFrame() {
+    // Native display-delivery boundary; internal so the native fixture can
+    // exercise stale startup ticks without depending on simulator timing.
+    func fireFrame(timestamp displayTimestamp: CFTimeInterval) {
         guard frameWanted, !runtimeDisposed else { return }
+        // Another screen's callback can hide this screen after the clock has
+        // captured its batch. Keep the request pending until it is shown.
+        guard isAppScript || reportedVisible != false else { return }
+        let timestamp = (displayTimestamp - frameTimeOrigin) * 1000
+        // A display tick may predate a newly created controller. Clamping
+        // those ticks to zero delivers multiple frames at the same time.
+        // Wait for a valid tick instead, keeping the JS batch cancellable.
+        guard displayTimestamp.isFinite, timestamp.isFinite, timestamp >= 0,
+              timestamp > lastFrameTimestamp else {
+            CraftNativeFrameClock.shared.request(self) { [weak self] timestamp in self?.fireFrame(timestamp: timestamp) }
+            return
+        }
+        lastFrameTimestamp = timestamp
         frameWanted = false
         let context = jsContext
         let route = routeName ?? "screen"
-        CraftNativeScriptThread.run(label: "frame \(route)") { context.objectForKeyedSubscript("__craftNativeFireFrame")?.call(withArguments: []) }
+        let delivery = frameDelivery
+        CraftNativeScriptThread.run(label: "frame \(route)") {
+            guard delivery.isOpen else { return }
+            context.objectForKeyedSubscript("__craftNativeFireFrame")?.call(withArguments: [timestamp])
+        }
     }
 
     /// The screen came on screen or went off it: a screen pushed over it was
@@ -6247,7 +6286,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 self.hasAppeared = true
             }
         }
-        if visible, frameWanted { CraftNativeFrameClock.shared.request(self) { [weak self] in self?.fireFrame() } }
+        if visible, frameWanted { CraftNativeFrameClock.shared.request(self) { [weak self] timestamp in self?.fireFrame(timestamp: timestamp) } }
         if !visible { CraftNativeFrameClock.shared.cancel(self) }
         guard visible != reportedVisible else { return }
         let first = reportedVisible == nil
@@ -6276,6 +6315,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func disposeRuntime() {
         guard !runtimeDisposed else { return }
         runtimeDisposed = true
+        frameDelivery.close()
         storageLifetime.close()
         pendingCapabilityDeadlines.values.forEach { $0.cancel() }
         pendingCapabilityDeadlines.removeAll()
@@ -6343,6 +6383,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     override func viewDidLayoutSubviews() {
         super.viewDidLayoutSubviews()
+        // Containment, bar visibility and accessory insets can change after
+        // rendering. Recheck once the scroll viewport has its actual frame.
+        trackContentScrollView()
         positionModals()
         emitLayoutEvents()
         sendViewportIfChanged()
@@ -6588,28 +6631,28 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if (typeof globalThis.requestAnimationFrame !== 'function') {
                 (function() {
                     var frames = [];
-                    var cancelled = new Set();
+                    var callbacks = new Map();
                     var nextFrame = 0;
                     globalThis.requestAnimationFrame = function(callback) {
                         if (typeof callback !== 'function') return 0;
                         var id = ++nextFrame;
-                        frames.push({ id: id, callback: callback });
+                        callbacks.set(id, callback);
+                        frames.push(id);
                         if (frames.length === 1) craftNativeRequestFrame();
                         return id;
                     };
                     globalThis.cancelAnimationFrame = function(id) {
-                        if (frames.some(function(frame) { return frame.id === id; })) cancelled.add(id);
+                        callbacks.delete(id);
                     };
-                    globalThis.__craftNativeFireFrame = function() {
+                    globalThis.__craftNativeFireFrame = function(now) {
                         var due = frames;
-                        var skip = cancelled;
                         frames = [];
-                        cancelled = new Set();
-                        var now = globalThis.performance && typeof globalThis.performance.now === 'function' ? globalThis.performance.now() : Date.now();
                         var failures = [];
                         for (var i = 0; i < due.length; i++) {
-                            if (skip.has(due[i].id)) continue;
-                            try { due[i].callback(now); } catch (error) { failures.push(error); }
+                            var callback = callbacks.get(due[i]);
+                            callbacks.delete(due[i]);
+                            if (!callback) continue;
+                            try { callback(now); } catch (error) { failures.push(error); }
                         }
                         failures.forEach(function(error) { globalThis.setTimeout(function() { throw error; }, 0); });
                     };
@@ -6773,26 +6816,33 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             }
         }
         let snapshotGet: @convention(block) (String) -> String? = { name in
-            CraftSnapshots.read(name)
+            storageLifetime.access(closedValue: nil) { CraftSnapshots.read(name) }
         }
         // JavaScriptCore retains these outer host blocks. A weak capture only
         // on the nested completion still makes the host block retain self,
         // forming controller -> JSContext -> host block -> controller.
         let snapshotSet: @convention(block) (String, JSValue, JSValue) -> Void = { [weak self] name, value, done in
-            CraftSnapshots.write(name, json: value.isNull || value.isUndefined ? nil : value.toString()) { [weak self] ok in
-                CraftNativeScriptThread.run {
-                    // A writer can finish after UIKit has disposed this
-                    // screen. Resolve the pending promise as a cancellation,
-                    // never as a successful write into a dead runtime.
-                    done.call(withArguments: [self?.runtimeDisposed != false ? false : ok])
+            let json = value.isNull || value.isUndefined ? nil : value.toString()
+            // Refuse before queueing disk work. Rejecting only its completion
+            // still lets a closed screen overwrite another screen's checkpoint.
+            storageLifetime.access(closedValue: ()) {
+                CraftSnapshots.write(name, json: json) { [weak self] ok in
+                    CraftNativeScriptThread.run {
+                        // A writer can finish after UIKit has disposed this
+                        // screen. Resolve the pending promise as a cancellation,
+                        // never as a successful write into a dead runtime.
+                        done.call(withArguments: [self?.runtimeDisposed != false ? false : ok])
+                    }
                 }
             }
         }
         let snapshotClear: @convention(block) (JSValue, JSValue) -> Void = { [weak self] keep, done in
             let names = (keep.isUndefined || keep.isNull ? [] : (keep.toArray() ?? [])).compactMap { $0 as? String }
-            CraftSnapshots.clear(keeping: Set(names)) { [weak self] ok in
-                CraftNativeScriptThread.run {
-                    done.call(withArguments: [self?.runtimeDisposed != false ? false : ok])
+            storageLifetime.access(closedValue: ()) {
+                CraftSnapshots.clear(keeping: Set(names)) { [weak self] ok in
+                    CraftNativeScriptThread.run {
+                        done.call(withArguments: [self?.runtimeDisposed != false ? false : ok])
+                    }
                 }
             }
         }
@@ -7576,10 +7626,29 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let edgeToEdge = scroll != nil && (prefersLargeTitle == true || scroll === leadingScroll?.view)
         let fullEdgeToEdge = rootIsSafeAreaView
         let topEdgeToEdge = fullEdgeToEdge || edgeToEdge
+        // Only a leading vertical scroller that reaches the root's bottom
+        // can paint beneath a visible tab bar. A bounded list, fixed footer,
+        // plain screen or presented sheet must retain its safe-area bottom.
+        // Use UIKit's automatic inset for tab/accessory clearance, rather
+        // than adding a second explicit inset (also owned by keyboard code).
+        var tabbedScroll = false
+        if let scroll, scroll === leadingScroll?.view, scroll.bounds.height > 0,
+           let tabBar = tabBarController?.tabBar, !tabBar.isHidden, tabBar.alpha > 0,
+           let window = view.window, tabBar.window === window,
+           tabBar.convert(tabBar.bounds, to: view).intersects(view.bounds) {
+            let viewport = scroll.convert(scroll.bounds, to: rootStack)
+            tabbedScroll = abs(viewport.maxY - rootStack.bounds.maxY) < 0.5
+        }
+        let bottomEdgeToEdge = fullEdgeToEdge || tabbedScroll
         rootTopToSafeArea?.isActive = !topEdgeToEdge
         rootTopToView?.isActive = topEdgeToEdge
-        rootBottomToSafeArea?.isActive = !fullEdgeToEdge
-        rootBottomToView?.isActive = fullEdgeToEdge
+        if bottomEdgeToEdge {
+            rootBottomToSafeArea?.isActive = false
+            rootBottomToView?.isActive = true
+        } else {
+            rootBottomToView?.isActive = false
+            rootBottomToSafeArea?.isActive = true
+        }
         rootLeadingToSafeArea?.isActive = !fullEdgeToEdge
         rootLeadingToView?.isActive = fullEdgeToEdge
         rootTrailingToSafeArea?.isActive = !fullEdgeToEdge
@@ -7769,6 +7838,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if let keyboard = keyboardScreenFrame, let window = scroll.window {
                 let frame = scroll.convert(scroll.bounds, to: window)
                 overlap = max(0, frame.maxY - window.convert(keyboard, from: nil).minY)
+                // An edge-to-edge scroller already receives the keyboard's
+                // safe-area share through UIKit. Add only uncovered overlap.
+                let automaticBottom = max(0, scroll.adjustedContentInset.bottom - scroll.contentInset.bottom)
+                overlap = max(0, overlap - automaticBottom)
             }
             if abs(scroll.contentInset.bottom - overlap) > 0.5 { scroll.contentInset.bottom = overlap }
             if abs(scroll.verticalScrollIndicatorInsets.bottom - overlap) > 0.5 { scroll.verticalScrollIndicatorInsets.bottom = overlap }

package/dist/ios/templates/CraftNativeServices.swift

@@ -314,30 +314,44 @@ final class CraftNativeSounds {
     private static var category: AVAudioSession.Category = .ambient
 
     private var sounds: [String: Sound] = [:]
-    private var interruptionObserver: NSObjectProtocol?
+    /// AVAudioSession belongs to the app, not to a screen. Observe for the
+    /// process lifetime once sounds are used, including gaps between screens.
+    /// Weak membership must not keep a disposed screen's service alive.
+    private static let services = NSHashTable<CraftNativeSounds>.weakObjects()
+    private static var sessionInterrupted = false
+    private static let interruptionObserver = NotificationCenter.default.addObserver(
+        forName: AVAudioSession.interruptionNotification,
+        object: nil,
+        queue: .main,
+    ) { note in CraftNativeSounds.handleInterruption(note) }
     /// `{ id, event: "ended" | "error", message? }` to the screen's script.
     var emit: (([String: Any]) -> Void)?
 
     init() {
-        interruptionObserver = NotificationCenter.default.addObserver(
-            forName: AVAudioSession.interruptionNotification,
-            object: nil,
-            queue: .main,
-        ) { [weak self] note in
-            guard let self else { return }
-            let type = (note.userInfo?[AVAudioSessionInterruptionTypeKey] as? NSNumber)?.uintValue
-            if type == AVAudioSession.InterruptionType.began.rawValue {
-                self.sounds.values.forEach { sound in
+        _ = Self.interruptionObserver
+        Self.services.add(self)
+    }
+
+    /// Sound services and their playback controls are used on main.
+    private static func handleInterruption(_ note: Notification) {
+        let type = (note.userInfo?[AVAudioSessionInterruptionTypeKey] as? NSNumber)?.uintValue
+        if type == AVAudioSession.InterruptionType.began.rawValue {
+            sessionInterrupted = true
+            services.allObjects.forEach { service in
+                service.sounds.values.forEach { sound in
                     guard !sound.paused else { return }
                     sound.interrupted = true
                     sound.player.pause()
                 }
-                return
             }
-            guard type == AVAudioSession.InterruptionType.ended.rawValue else { return }
-            let options = (note.userInfo?[AVAudioSessionInterruptionOptionKey] as? NSNumber)?.uintValue ?? 0
-            let shouldResume = options & AVAudioSession.InterruptionOptions.shouldResume.rawValue != 0
-            self.sounds.values.forEach { sound in
+            return
+        }
+        guard type == AVAudioSession.InterruptionType.ended.rawValue else { return }
+        sessionInterrupted = false
+        let options = (note.userInfo?[AVAudioSessionInterruptionOptionKey] as? NSNumber)?.uintValue ?? 0
+        let shouldResume = options & AVAudioSession.InterruptionOptions.shouldResume.rawValue != 0
+        services.allObjects.forEach { service in
+            service.sounds.values.forEach { sound in
                 guard sound.interrupted else { return }
                 sound.interrupted = false
                 // Without permission to auto-resume, keep a resumable paused
@@ -348,10 +362,6 @@ final class CraftNativeSounds {
         }
     }
 
-    deinit {
-        if let interruptionObserver { NotificationCenter.default.removeObserver(interruptionObserver) }
-    }
-
     /// Starts `url`. `answer` hears once it plays (or could not be loaded).
     func play(id: String, url: URL, options: [String: Any], answer: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
         stop(id: id, fadeOut: 0)
@@ -364,6 +374,7 @@ final class CraftNativeSounds {
         let item = AVPlayerItem(url: url)
         let player = AVQueuePlayer()
         let sound = Sound(player: player, volume: volume)
+        sound.interrupted = Self.sessionInterrupted
         sound.pending = answer
         sounds[id] = sound
         let failed: (String) -> Void = { [weak self, weak sound] message in
@@ -397,7 +408,7 @@ final class CraftNativeSounds {
             }
         }
         player.volume = fadeIn > 0 ? 0 : volume
-        player.play()
+        if !Self.sessionInterrupted { player.play() }
         if fadeIn > 0 { ramp(sound, to: volume, over: fadeIn) }
     }
 
@@ -413,7 +424,7 @@ final class CraftNativeSounds {
 
     @discardableResult
     func resume(id: String) -> Bool {
-        guard let sound = sounds[id], sound.paused else { return false }
+        guard !Self.sessionInterrupted, let sound = sounds[id], sound.paused else { return false }
         sound.paused = false
         sound.interrupted = false
         sound.player.volume = sound.volume

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.377",
+  "version": "0.0.380",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",