@craft-native/ios 0.0.464 → 0.0.471

package/dist/cli.js

@@ -1397,9 +1397,11 @@ function writeShell(output, config) {
   writeSource(join4(output, "Sources", "CraftNativeUI.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeUI.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeServices.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeServices.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeFiles.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeFiles.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeMediaOwnership.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeMediaOwnership.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftVoiceRecording.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftVoiceRecording.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftWebAudio.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftWebAudio.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftHybrid.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftHybrid.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftFramePacingLog.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftFramePacingLog.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftCrashReporter.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftCrashReporter.swift"), "utf-8").replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION));
   writeSource(join4(output, "Sources", "CraftLiveActivities.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftLiveActivities.swift"), "utf8"));
   writeSource(join4(output, "Shared", "CraftActivityAttributes.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftActivityAttributes.swift"), "utf8"));

package/dist/index.js

@@ -1611,9 +1611,11 @@ function writeShell(output, config) {
   writeSource(join4(output, "Sources", "CraftNativeUI.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeUI.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeServices.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeServices.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftNativeFiles.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeFiles.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeMediaOwnership.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftNativeMediaOwnership.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftVoiceRecording.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftVoiceRecording.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftWebAudio.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftWebAudio.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftHybrid.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftHybrid.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftFramePacingLog.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftFramePacingLog.swift"), "utf8"));
   writeSource(join4(output, "Sources", "CraftCrashReporter.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftCrashReporter.swift"), "utf-8").replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION));
   writeSource(join4(output, "Sources", "CraftLiveActivities.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftLiveActivities.swift"), "utf8"));
   writeSource(join4(output, "Shared", "CraftActivityAttributes.swift"), readFileSync3(join4(TEMPLATES_DIR, "CraftActivityAttributes.swift"), "utf8"));

package/package.json

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

package/templates/CraftFramePacingLog.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+/// The opt-in frame trace shares one append-only file for this app process.
+enum CraftFramePacingLog {
+    static func open(in directory: URL) throws -> FileHandle {
+        let manager = FileManager.default
+        try manager.createDirectory(at: directory, withIntermediateDirectories: true)
+        let url = directory.appendingPathComponent("craft-frame-pacing.log")
+        if !manager.fileExists(atPath: url.path),
+           !manager.createFile(atPath: url.path, contents: nil) {
+            throw NSError(domain: NSCocoaErrorDomain, code: NSFileWriteUnknownError,
+                          userInfo: [NSFilePathErrorKey: url.path])
+        }
+        let handle = try FileHandle(forWritingTo: url)
+        _ = try handle.seekToEnd()
+        return handle
+    }
+}

package/templates/CraftHybrid.swift

@@ -2703,11 +2703,11 @@ final class CraftFramePacing: NSObject {
     private let output = DispatchQueue(label: "craft.frame-pacing", qos: .utility)
     private lazy var file: FileHandle? = {
         guard let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else { return nil }
-        let url = caches.appendingPathComponent("craft-frame-pacing.log")
-        if !FileManager.default.fileExists(atPath: url.path) { FileManager.default.createFile(atPath: url.path, contents: nil) }
-        let handle = try? FileHandle(forWritingTo: url)
-        _ = try? handle?.seekToEnd()
-        return handle
+        do { return try CraftFramePacingLog.open(in: caches) }
+        catch {
+            NSLog("[craft frames] trace file unavailable: %@", String(describing: error))
+            return nil
+        }
     }()
 
     private func write(_ line: String) {

package/templates/CraftNativeActions.swift

@@ -109,6 +109,7 @@ enum CraftNativeActions {
         // 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).
@@ -333,6 +334,24 @@ enum CraftNativeActions {
             return
         case ("Media", "path"):
             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 { value -> String? in
                 if let url = value as? String { return url }
@@ -1001,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 }

package/templates/CraftNativeFiles.swift

@@ -943,9 +943,40 @@ enum CraftNativeMedia {
     /// Addresses being fetched now, so a second `keep` waits for the first.
     private struct Flight {
         let id: UUID
+        let ownership: CraftNativeMediaOwnership.Stamp
         var waiting: [(Result<Any, CraftNativeActionError>) -> Void]
     }
     private static var inFlight: [String: Flight] = [:]
+    private static var owner: CraftNativeMediaOwnership?
+
+    /// Called under the same lock as cache commits. Keep the journal outside
+    /// the cache directory so clear/prune cannot erase revocation history.
+    private static func ownership() throws -> CraftNativeMediaOwnership {
+        if let owner { return owner }
+        let value = try CraftNativeMediaOwnership(url: root.deletingLastPathComponent().appendingPathComponent("craft-media-ownership.json"))
+        owner = value
+        return value
+    }
+
+    private static func ownerKey(_ address: String) -> String {
+        String(file(for: address).lastPathComponent.prefix(64))
+    }
+
+    /// Remove only this identity's complete and staging files. A failed
+    /// unlink remains observable; its durable tombstone still hides the copy.
+    private static func removeFiles(_ address: String) throws -> Int {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: root.path) else { return 0 }
+        let prefix = ownerKey(address) + "."
+        var removed = 0
+        var failure: Error?
+        for url in try fm.contentsOfDirectory(at: root, includingPropertiesForKeys: nil) where url.lastPathComponent.hasPrefix(prefix) {
+            do { try fm.removeItem(at: url); removed += 1 }
+            catch { failure = error }
+        }
+        if let failure { throw failure }
+        return removed
+    }
 
     /// Where `address`'s copy lives (whether or not it is there yet). The
     /// extension is the address's, because AVPlayer reads the type from it.
@@ -959,8 +990,12 @@ enum CraftNativeMedia {
     /// The copy of `address` on this phone, or nil.
     static func local(_ address: String) -> URL? {
         guard !address.isEmpty else { return nil }
+        lock.lock()
+        defer { lock.unlock() }
+        guard (try? ownership().permitsLocal(ownerKey(address))) == true else { return nil }
         let url = file(for: address)
-        return ((try? url.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? 0) > 0 ? url : nil
+        let values = try? url.resourceValues(forKeys: [.fileSizeKey, .isRegularFileKey])
+        return values?.isRegularFile == true && (values?.fileSize ?? 0) > 0 ? url : nil
     }
 
     static func describe(_ address: String, _ url: URL) -> [String: Any] {
@@ -971,14 +1006,35 @@ enum CraftNativeMedia {
     /// A new download's identity, or nil after joining an existing download.
     static func begin(_ address: String, _ done: @escaping (Result<Any, CraftNativeActionError>) -> Void) -> UUID? {
         lock.lock()
-        defer { lock.unlock() }
         if inFlight[address] != nil {
             inFlight[address]!.waiting.append(done)
+            lock.unlock()
+            return nil
+        }
+        do {
+            let stamp = try ownership().activate(ownerKey(address)) { _ = try removeFiles(address) }
+            let id = UUID()
+            inFlight[address] = Flight(id: id, ownership: stamp, waiting: [done])
+            lock.unlock()
+            return id
+        } catch {
+            lock.unlock()
+            done(.failure(CraftNativeActionError(code: errorCode(error, fallback: "IO_ERROR"), message: "Media ownership could not be persisted")))
             return nil
         }
-        let id = UUID()
-        inFlight[address] = Flight(id: id, waiting: [done])
-        return id
+    }
+
+    static func ownershipStamp(_ address: String, flight: UUID) -> CraftNativeMediaOwnership.Stamp? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let current = inFlight[address], current.id == flight else { return nil }
+        return current.ownership
+    }
+
+    static func acceptsTransfer(_ address: String, stamp: CraftNativeMediaOwnership.Stamp) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return (try? ownership().accepts(ownerKey(address), stamp: stamp)) == true
     }
 
     /// Whether `flight` is still the download `address`'s keeps wait for.
@@ -997,7 +1053,7 @@ enum CraftNativeMedia {
 
     /// A finished download moved into place (atomically, so a half-written
     /// file is never played), or a refusal with the server's status.
-    static func store(_ address: String, at location: URL, response: HTTPURLResponse, flight: UUID? = nil, stillWanted: (() -> Bool)? = nil) -> Result<Any, CraftNativeActionError> {
+    static func store(_ address: String, at location: URL, response: HTTPURLResponse, flight: UUID? = nil, stamp: CraftNativeMediaOwnership.Stamp? = nil, stillWanted: (() -> Bool)? = nil) -> Result<Any, CraftNativeActionError> {
         guard response.statusCode == 200 else {
             return .success(["ok": false, "url": address, "status": response.statusCode])
         }
@@ -1008,11 +1064,15 @@ enum CraftNativeMedia {
         if let flight, inFlight[address]?.id != flight {
             return .failure(CraftNativeActionError(code: "CANCELLED", message: "The media cache was cleared"))
         }
+        let captured = stamp ?? flight.flatMap { inFlight[address]?.id == $0 ? inFlight[address]?.ownership : nil }
+        guard let captured, (try? ownership().accepts(ownerKey(address), stamp: captured)) == true else {
+            return .failure(CraftNativeActionError(code: "CANCELLED", message: "Media ownership was retired"))
+        }
         // A background transfer from before the cache was cleared (sign-out).
         if let stillWanted, !stillWanted() {
             return .failure(CraftNativeActionError(code: "CANCELLED", message: "The media cache was cleared"))
         }
-        let staging = root.appendingPathComponent(UUID().uuidString + ".part")
+        let staging = root.appendingPathComponent(ownerKey(address) + "." + UUID().uuidString + ".part")
         defer { try? fm.removeItem(at: staging) }
         do {
             // URL resource values can retain a previous size when a retry
@@ -1045,15 +1105,20 @@ enum CraftNativeMedia {
     /// End an account's cache lifetime.
     static func clear() throws -> Int {
         lock.lock()
+        var failure: Error?
+        do { try ownership().clear() }
+        catch { failure = error }
         let waiting = inFlight.values.flatMap { $0.waiting }
         inFlight.removeAll()
         // Under the same lock a background transfer commits under: none
         // started before this lands after it.
         CraftNativeMediaTransfers.shared.cancelAll()
         let fm = FileManager.default
-        let files = (try? fm.contentsOfDirectory(at: root, includingPropertiesForKeys: nil)) ?? []
+        var files: [URL] = []
+        do {
+            if fm.fileExists(atPath: root.path) { files = try fm.contentsOfDirectory(at: root, includingPropertiesForKeys: nil) }
+        } catch { failure = error }
         var removed = 0
-        var failure: Error?
         for url in files {
             do { try fm.removeItem(at: url); removed += 1 }
             catch { failure = error }
@@ -1064,6 +1129,24 @@ enum CraftNativeMedia {
         return removed
     }
 
+    /// Revoke one cache identity without removing other authorized media.
+    static func remove(_ address: String) throws -> Int {
+        guard !address.isEmpty else { throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "media.remove needs a source or cache key") }
+        lock.lock()
+        var failure: Error?
+        do { try ownership().retire(ownerKey(address)) }
+        catch { failure = error }
+        let waiting = inFlight.removeValue(forKey: address)?.waiting ?? []
+        CraftNativeMediaTransfers.shared.cancelRetired(address: address)
+        var removed = 0
+        do { removed = try removeFiles(address) }
+        catch { failure = error }
+        lock.unlock()
+        for done in waiting { done(.failure(CraftNativeActionError(code: "CANCELLED", message: "Media ownership was retired"))) }
+        if let failure { throw failure }
+        return removed
+    }
+
     /// Removes every copy whose address is not in `keep`; answers how many.
     static func prune(keep: [String]) -> Int {
         CraftNativeMediaTransfers.shared.cancel(except: keep + Array(inFlightAddresses()))
@@ -1120,6 +1203,24 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         let generation: Int
     }
 
+    private struct Description: Codable {
+        let address: String
+        let ownership: CraftNativeMediaOwnership.Stamp
+    }
+
+    private static func describe(_ address: String, ownership: CraftNativeMediaOwnership.Stamp) -> String {
+        // No network capability is added to the journal: only the task that
+        // already owns the authorized request carries its cache identity.
+        let data = try! JSONEncoder().encode(Description(address: address, ownership: ownership))
+        return "craft-media-v2:" + data.base64EncodedString()
+    }
+
+    private static func description(_ task: URLSessionTask) -> Description? {
+        guard let text = task.taskDescription, text.hasPrefix("craft-media-v2:"),
+              let data = Data(base64Encoded: String(text.dropFirst("craft-media-v2:".count))) else { return nil }
+        return try? JSONDecoder().decode(Description.self, from: data)
+    }
+
     private let lock = NSLock()
     private var transfers: [Int: Transfer] = [:]
     /// What each finished download came to, until its task completes.
@@ -1143,7 +1244,10 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
             guard let self else { return }
             self.lock.lock()
             for case let task as URLSessionDownloadTask in tasks where task.state == .running || task.state == .suspended {
-                if let address = task.taskDescription, self.transfers[task.taskIdentifier] == nil { self.restored[address] = task }
+                // A pre-upgrade address-only description cannot establish
+                // durable ownership. A new authorized keep can replace it.
+                guard let description = Self.description(task) else { task.cancel(); continue }
+                if self.transfers[task.taskIdentifier] == nil { self.restored[description.address] = task }
             }
             self.lock.unlock()
         }
@@ -1154,11 +1258,12 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
     }
 
     /// Fetches `request` into the copy for `address`, finishing `flight`.
-    func start(_ request: URLRequest, address: String, flight: UUID, wifiOnly: Bool) -> URLSessionTask {
+    func start(_ request: URLRequest, address: String, flight: UUID, ownership: CraftNativeMediaOwnership.Stamp, wifiOnly: Bool) -> URLSessionTask {
         lock.lock()
         let task: URLSessionDownloadTask
         if let earlier = restored.removeValue(forKey: address), earlier.state == .running || earlier.state == .suspended {
-            if earlier.originalRequest?.url == request.url && earlier.originalRequest?.allHTTPHeaderFields == request.allHTTPHeaderFields {
+            if Self.description(earlier)?.ownership == ownership,
+               earlier.originalRequest?.url == request.url && earlier.originalRequest?.allHTTPHeaderFields == request.allHTTPHeaderFields {
                 task = earlier
             }
             else {
@@ -1167,12 +1272,12 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
                 earlier.taskDescription = nil
                 earlier.cancel()
                 task = session.downloadTask(with: request)
-                task.taskDescription = address
+                task.taskDescription = Self.describe(address, ownership: ownership)
             }
         }
         else {
             task = session.downloadTask(with: request)
-            task.taskDescription = address
+            task.taskDescription = Self.describe(address, ownership: ownership)
         }
         transfers[task.taskIdentifier] = Transfer(address: address, flight: flight, wifiOnly: wifiOnly, generation: generation)
         lock.unlock()
@@ -1204,7 +1309,28 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         generation += 1
         restored.removeAll()
         lock.unlock()
-        session.getAllTasks { tasks in tasks.forEach { $0.cancel() } }
+        // The asynchronous enumeration may run after a new authorized keep.
+        // Retire only obsolete stamps, never that new generation's task.
+        session.getAllTasks { tasks in
+            for task in tasks {
+                guard let description = Self.description(task), CraftNativeMedia.acceptsTransfer(description.address, stamp: description.ownership) else {
+                    task.cancel()
+                    continue
+                }
+            }
+        }
+    }
+
+    func cancelRetired(address: String) {
+        lock.lock()
+        restored.removeValue(forKey: address)
+        lock.unlock()
+        session.getAllTasks { tasks in
+            for task in tasks {
+                guard let description = Self.description(task) else { task.cancel(); continue }
+                if description.address == address && !CraftNativeMedia.acceptsTransfer(address, stamp: description.ownership) { task.cancel() }
+            }
+        }
     }
 
     /// Stops the transfers for addresses no longer wanted.
@@ -1214,7 +1340,7 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         restored = restored.filter { wanted.contains($0.key) }
         lock.unlock()
         session.getAllTasks { tasks in
-            for task in tasks where !wanted.contains(task.taskDescription ?? "") { task.cancel() }
+            for task in tasks where !wanted.contains(Self.description(task)?.address ?? "") { task.cancel() }
         }
     }
 
@@ -1224,7 +1350,11 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         lock.unlock()
         // One left by an earlier launch belongs to the generation this launch began with.
         let started = transfer?.generation ?? 0
-        guard let address = transfer?.address ?? downloadTask.taskDescription else { return }
+        guard let description = Self.description(downloadTask) else {
+            record(downloadTask, .failure(CraftNativeActionError(code: "CANCELLED", message: "The media transfer has no durable ownership")))
+            return
+        }
+        let address = description.address
         guard let http = downloadTask.response as? HTTPURLResponse else {
             record(downloadTask, .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "media.keep received a response that is not HTTP")))
             return
@@ -1232,7 +1362,7 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         // The system deletes `location` once this returns: move it now. It
         // lands whether its keep is still waiting or was answered early; only
         // a clear since it started (sign-out) keeps it out.
-        record(downloadTask, CraftNativeMedia.store(address, at: location, response: http, stillWanted: { [weak self] in self?.isCurrent(started) ?? false }))
+        record(downloadTask, CraftNativeMedia.store(address, at: location, response: http, stamp: description.ownership, stillWanted: { [weak self] in self?.isCurrent(started) ?? false }))
     }
 
     /// How many times the cache was cleared in this launch; a transfer started before the last clear does not land.
@@ -1256,7 +1386,7 @@ final class CraftNativeMediaTransfers: NSObject, URLSessionDownloadDelegate {
         lock.lock()
         let transfer = transfers.removeValue(forKey: task.taskIdentifier)
         let result = finished.removeValue(forKey: task.taskIdentifier)
-        if let address = task.taskDescription, restored[address] === task { restored.removeValue(forKey: address) }
+        if let address = Self.description(task)?.address, restored[address] === task { restored.removeValue(forKey: address) }
         lock.unlock()
         guard let transfer, let flight = transfer.flight else { return }
         if let error {

package/templates/CraftNativeMediaOwnership.swift

@@ -0,0 +1,92 @@
+import Foundation
+
+/// Durable ownership of cached media and background transfers. The media
+/// store serializes access to this journal with its file-commit lock.
+final class CraftNativeMediaOwnership {
+    struct Stamp: Codable, Equatable {
+        let epoch: String
+        let revision: String
+    }
+
+    private struct Journal: Codable {
+        var version = 1
+        var epoch = UUID().uuidString
+        var legacyCopiesAllowed = true
+        var revisions: [String: String] = [:]
+        var revoked: Set<String> = []
+        var authorized: Set<String> = []
+    }
+
+    private let url: URL
+    private var journal: Journal
+    private var persistenceFailure: Error?
+
+    init(url: URL) throws {
+        self.url = url
+        if FileManager.default.fileExists(atPath: url.path) {
+            journal = try JSONDecoder().decode(Journal.self, from: Data(contentsOf: url))
+            guard journal.version == 1 else { throw CocoaError(.fileReadCorruptFile) }
+        } else {
+            journal = Journal()
+            try persist(journal)
+        }
+    }
+
+    func permitsLocal(_ identity: String) -> Bool {
+        persistenceFailure == nil && !journal.revoked.contains(identity)
+            && (journal.legacyCopiesAllowed || journal.authorized.contains(identity))
+    }
+
+    func accepts(_ identity: String, stamp: Stamp) -> Bool {
+        permitsLocal(identity) && stamp.epoch == journal.epoch
+            && stamp.revision == (journal.revisions[identity] ?? "")
+    }
+
+    /// A new explicit authorized keep may use this identity again. Old bytes
+    /// must be removed before lifting a tombstone, including after a failed
+    /// unlink. Its old transfer stamp never becomes current again.
+    func activate(_ identity: String, removeRetiredFiles: () throws -> Void) throws -> Stamp {
+        if persistenceFailure != nil { try persist(journal) }
+        if !permitsLocal(identity) {
+            try removeRetiredFiles()
+            var next = journal
+            next.revoked.remove(identity)
+            next.authorized.insert(identity)
+            try persist(next)
+        }
+        return Stamp(epoch: journal.epoch, revision: journal.revisions[identity] ?? "")
+    }
+
+    /// Persist before cancelling or unlinking: a task that outlives this
+    /// process cannot regain ownership on the next launch.
+    func retire(_ identity: String) throws {
+        var next = journal
+        next.revisions[identity] = UUID().uuidString
+        next.revoked.insert(identity)
+        try persist(next)
+    }
+
+    /// Sign-out invalidates all existing stamps and all copies, even if a
+    /// filesystem error prevents unlinking one of them.
+    func clear() throws {
+        var next = Journal()
+        next.legacyCopiesAllowed = false
+        try persist(next)
+    }
+
+    private func persist(_ next: Journal) throws {
+        // A failed journal write is observable and fails closed in this
+        // process. A later retire/clear can retry once storage is writable.
+        journal = next
+        do {
+            try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.sortedKeys]
+            try encoder.encode(next).write(to: url, options: .atomic)
+            persistenceFailure = nil
+        } catch {
+            persistenceFailure = error
+            throw error
+        }
+    }
+}

package/templates/CraftNativeScreen.swift

@@ -9301,7 +9301,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             field.textColor = color(style["color"]) ?? .label
             field.font = textFont(style, default: .systemFont(ofSize: 16))
             field.textAlignment = textAlignment(style["textAlign"])
-            field.defaultTextAttributes = inputTextAttributes(style, font: field.font ?? .systemFont(ofSize: 16), alignment: field.textAlignment)
+            field.defaultTextAttributes = inputTextAttributes(style, font: field.font ?? .systemFont(ofSize: 16), alignment: field.textAlignment, singleLine: true)
             let desiredKeyboardType = keyboardType(props["keyboardType"])
             if field.keyboardType != desiredKeyboardType { field.keyboardType = desiredKeyboardType }
             let desiredReturnKeyType = returnKeyType(props["returnKeyType"])
@@ -10779,6 +10779,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         // beneath the screen's floating chrome.
         let overflow = style["overflow"] as? String
         view.clipsToBounds = overflow == "hidden"
+            // A single-line editor owns a text viewport. Its private label
+            // can be wider than the control while editing or showing a URL;
+            // inherited visible overflow must not open that viewport.
+            || view is UITextField
             || (view is UIScrollView && overflow != "visible")
             || (view is UILabel && (view.craftRequestedCornerRadius ?? 0) > 0)
             || ((view is UIImageView || view is CraftNativePositionedImageView) && (borderRadius > 0 || hasCornerRadii))
@@ -10930,7 +10934,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func inputTextAttributes(
         _ style: [String: Any],
         font: UIFont,
-        alignment: NSTextAlignment
+        alignment: NSTextAlignment,
+        singleLine: Bool = false
     ) -> [NSAttributedString.Key: Any] {
         var attributes: [NSAttributedString.Key: Any] = [
             .foregroundColor: color(style["color"]) ?? .label,
@@ -10940,6 +10945,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         // UIKit otherwise resets the field's alignment to natural when these attributes are applied.
         let paragraph = NSMutableParagraphStyle()
         paragraph.alignment = alignment
+        // The default paragraph wraps even inside a UITextField. A long URL
+        // then paints a second line outside the field instead of scrolling.
+        if singleLine { paragraph.lineBreakMode = .byClipping }
         if let lineHeight = number(style["lineHeight"]) {
             paragraph.minimumLineHeight = lineHeight
             paragraph.maximumLineHeight = lineHeight

package/templates/testing/DriverTests.swift.template

@@ -182,6 +182,30 @@ final class DriverTests: XCTestCase {
         return nil
     }
 
+    /// Safari's web view extends behind its browser bars. Those regions accept
+    /// touches for the bars, not for page controls reported inside the web view.
+    func browserContentFrame(_ frame: CGRect, topBar: CGRect?, bottomBar: CGRect?) -> CGRect {
+        var top = frame.minY
+        var bottom = frame.maxY
+        if let bar = topBar, bar.contains(CGPoint(x: frame.midX, y: bar.midY)), bar.intersects(frame) {
+            top = max(top, bar.maxY)
+        }
+        if let bar = bottomBar, bar.contains(CGPoint(x: frame.midX, y: bar.midY)), bar.intersects(frame) {
+            bottom = min(bottom, bar.minY)
+        }
+        return CGRect(x: frame.minX, y: top, width: frame.width, height: max(0, bottom - top))
+    }
+
+    func scrollViewport() -> CGRect {
+        let webView = app.webViews.firstMatch
+        let topBar = app.otherElements["TopBrowserBar"]
+        let bottomBar = app.toolbars["BottomBrowserToolbar"]
+        guard webView.exists, topBar.exists || bottomBar.exists else { return app.frame }
+        return browserContentFrame(webView.frame.intersection(app.frame),
+            topBar: topBar.exists ? topBar.frame : nil,
+            bottomBar: bottomBar.exists ? bottomBar.frame : nil)
+    }
+
     /// A short target fits entirely; an oversized target fills the viewport.
     func visibleScrollFrame(_ target: CGRect, in viewport: CGRect) -> Bool {
         let visible = target.intersection(viewport)
@@ -192,7 +216,7 @@ final class DriverTests: XCTestCase {
 
     func scrollTargetVisible(_ target: XCUIElement?) -> Bool {
         guard let target, target.exists, target.isHittable,
-              visibleScrollFrame(target.frame, in: app.frame) else { return false }
+              visibleScrollFrame(target.frame, in: scrollViewport()) else { return false }
         // Hittable alone accepts controls clipped by the scroll view's edge.
         // Only an ancestor scroll view clips this target, not its siblings.
         // One that does not overlap the target is not its ancestor, whatever
@@ -220,7 +244,7 @@ final class DriverTests: XCTestCase {
     /// below the screen while drawing it over the lower half - and it stops
     /// short of a keyboard whose frame is known.
     func scrollPage(towardTop: Bool) {
-        let frame = app.frame
+        let frame = scrollViewport()
         var lower = frame.minY + frame.height * 0.55
         let keyboard = app.keyboards.firstMatch
         if keyboard.exists, !keyboard.frame.isEmpty, keyboard.frame.minY < frame.maxY {
@@ -719,7 +743,7 @@ final class DriverTests: XCTestCase {
             var found = element(containing: arg)
             var drags = 0
             while !scrollTargetVisible(found) && drags < 12 {
-                let towardTop = found.map { !$0.frame.isEmpty && $0.frame.midY < app.frame.midY } ?? false
+                let towardTop = found.map { !$0.frame.isEmpty && $0.frame.midY < scrollViewport().midY } ?? false
                 scrollPage(towardTop: towardTop)
                 drags += 1
                 found = element(containing: arg)