@craft-native/ios 0.0.497 → 0.0.499

package/package.json

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

package/templates/CraftApp.swift

@@ -822,6 +822,9 @@ final class CraftChrome: ObservableObject {
         /// A shared material capsule; nil keeps separate floating buttons.
         var accessoryLayout: String? = nil
         var companions: [Tab] = []
+        /// A floating action that is on: a mode it switched (tracking in
+        /// Maps), drawn in the tint whatever screen is showing.
+        var active = false
         /// A tap opens these destinations in a compact menu instead of navigating.
         var menu: [TabMenuItem] = []
     }
@@ -846,6 +849,8 @@ final class CraftChrome: ObservableObject {
         guard let path = visiblePath else { return false }
         return path == accessory.id || path.hasPrefix(accessory.id + "/")
     }
+    /// Drawn in the tint: its destination is showing, or the app says it is on.
+    func accessoryActive(_ accessory: Tab) -> Bool { accessory.active || accessorySelected(accessory) }
     var highlightedTab: String? { accessorySelected ? nil : selected }
     let tabSwipeProgress = CraftTabSwipeProgress()
     private(set) var tabSwipePosition: CGFloat? {
@@ -977,13 +982,15 @@ final class CraftChrome: ObservableObject {
                           let companionTitle = action["title"] as? String else { return nil }
                     return Tab(id: companionPath, title: companionTitle, symbol: action["symbol"] as? String ?? "circle",
                         accessibilityLabel: action["accessibilityLabel"] as? String, iconOnly: true,
+                        active: action["selected"] as? Bool ?? false,
                         menu: ((action["menu"] as? [[String: Any]]) ?? []).prefix(12).compactMap { choice in
                             guard let destination = choice["path"] as? String,
                                   destination.hasPrefix("/"), !destination.hasPrefix("//"),
                                   let label = choice["title"] as? String, !label.isEmpty else { return nil }
                             return TabMenuItem(id: destination, title: label, symbol: choice["symbol"] as? String ?? "circle")
                         })
-                })
+                },
+                active: item["selected"] as? Bool ?? false)
         } else {
             next = nil
         }

package/templates/CraftHybrid.swift

@@ -1483,12 +1483,10 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 let button = UIButton(type: .system)
                 var configuration = UIButton.Configuration.plain()
                 configuration.image = UIImage(systemName: action.symbol)
-                configuration.preferredSymbolConfigurationForImage = UIImage.SymbolConfiguration(pointSize: 22, weight: .regular)
                 button.configuration = configuration
                 button.accessibilityIdentifier = "craft-tab-companion:" + action.id
                 button.accessibilityLabel = action.accessibilityLabel ?? action.title
                 button.accessibilityValue = action.badge
-                button.accessibilityTraits = chrome.accessorySelected(action) ? [.button, .selected] : [.button]
                 if action.menu.isEmpty {
                     button.addAction(UIAction { [weak self] _ in self?.hybrid.open(action.id) }, for: .touchUpInside)
                 } else {
@@ -1512,9 +1510,6 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 companionButtons.append(button)
             }
         }
-        for (index, action) in companionModels.enumerated() {
-            companionButtons[index].accessibilityTraits = chrome.accessorySelected(action) ? [.button, .selected] : [.button]
-        }
         let grouped = model?.accessoryLayout != nil
         // A group is one control, as the map controls in Maps are: its
         // actions live inside the shared surface, so the glass lights the
@@ -1522,16 +1517,12 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         // Separate actions stay in the shell, each on its own surface.
         let actionHost: UIView = grouped ? accessoryGlass.contentView : view
         for glass in companionGlasses { glass.isHidden = grouped }
-        for button in companionButtons {
+        for (index, button) in companionButtons.enumerated() {
             if button.superview !== actionHost { actionHost.addSubview(button) }
-            button.tintColor = grouped ? .label : nil
-            button.configuration?.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
+            styleAccessory(button, for: companionModels[index], grouped: grouped)
         }
-        accessoryButton.tintColor = grouped ? .label : nil
         if let model {
             var configuration = UIButton.Configuration.plain()
-            configuration.image = UIImage(systemName: model.symbol)
-            configuration.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
             configuration.title = model.iconOnly ? nil : model.displayTitle
             configuration.subtitle = model.iconOnly ? nil : model.badge
             configuration.imagePadding = model.iconOnly ? 0 : 8
@@ -1539,7 +1530,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
                 button.configuration = configuration
                 button.accessibilityLabel = model.accessibilityLabel ?? model.displayTitle
                 button.accessibilityValue = model.badge
-                button.accessibilityTraits = chrome.accessorySelected(model) ? [.button, .selected] : [.button]
+                styleAccessory(button, for: model, grouped: grouped)
             }
         }
 #if compiler(>=6.2)
@@ -1597,10 +1588,32 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         view.setNeedsLayout()
     }
 
-    /// Symbols in a group carry the weight of the system's own map controls;
-    /// a separate action keeps the lighter bar-button weight.
+    /// Symbols in a group carry the weight of the system's own map controls,
+    /// and their size: at 20 points a symbol filled its 48-point action
+    /// where the ones in Maps leave half of theirs clear. The control and
+    /// its touch targets keep their size; only the symbol is smaller. A
+    /// separate action keeps the lighter bar-button weight.
     private static func accessorySymbol(grouped: Bool) -> UIImage.SymbolConfiguration {
-        UIImage.SymbolConfiguration(pointSize: grouped ? 20 : 22, weight: grouped ? .medium : .regular)
+        UIImage.SymbolConfiguration(pointSize: grouped ? 15 : 22, weight: grouped ? .medium : .regular)
+    }
+
+    /// One action's symbol, tint and state. An action that is on (its
+    /// destination is showing, or the app says so) is drawn in the tint and,
+    /// where the symbol has one, filled: Maps' location arrow while tracking.
+    /// Off, a grouped action is the label colour, as the map controls are.
+    private func styleAccessory(_ button: UIButton, for action: CraftChrome.Tab, grouped: Bool) {
+        let active = CraftChrome.shared.accessoryActive(action)
+        let filled = active && !action.symbol.hasSuffix(".fill") ? UIImage(systemName: action.symbol + ".fill") : nil
+        let tint: UIColor = CraftChrome.shared.tint ?? config.tintColor.flatMap { UIColor(hex: $0) } ?? view.tintColor
+        button.configuration?.image = filled ?? UIImage(systemName: action.symbol)
+        button.configuration?.preferredSymbolConfigurationForImage = Self.accessorySymbol(grouped: grouped)
+        // Said to the configuration as well as the view: glass draws its
+        // content in the label colour unless the content names its own.
+        button.configuration?.baseForegroundColor = active ? tint : grouped ? .label : nil
+        // A group places each symbol itself, when it lays out.
+        if !grouped { button.configuration?.contentInsets = .zero }
+        button.tintColor = active ? tint : grouped ? .label : nil
+        button.accessibilityTraits = active ? [.button, .selected] : [.button]
     }
 
     /// The surface under the floating actions. A group is a capsule of
@@ -1639,10 +1652,11 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         }
     }
 
-    /// A group's breadth, and each action's length along it: the system map
-    /// controls' proportions, every target at least 48 points.
+    /// A group's breadth, and the distance from one symbol to the next. As
+    /// in Maps, the first and last symbols sit at the centres of the
+    /// capsule's round ends, so two actions make a 48 by 103 point control.
     static let accessoryGroupBreadth: CGFloat = 48
-    static let accessoryGroupStep: CGFloat = 52
+    static let accessoryGroupStep: CGFloat = 55
 
     @objc private func openTabAccessory() {
         if let accessoryModel { hybrid.open(accessoryModel.id) }
@@ -1694,7 +1708,7 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         let breadth = Self.accessoryGroupBreadth
         let step = Self.accessoryGroupStep
         let buttons = companionButtons + [accessoryButton]
-        let length = step * CGFloat(buttons.count)
+        let length = breadth + step * CGFloat(buttons.count - 1)
         let size = vertical ? CGSize(width: breadth, height: length) : CGSize(width: length, height: breadth)
         let rightToLeft = view.effectiveUserInterfaceLayoutDirection == .rightToLeft
         // The tab bar's own platter sits this far in from the screen's edge.
@@ -1702,10 +1716,21 @@ final class CraftHybridController: UITabBarController, UITabBarControllerDelegat
         let x = rightToLeft ? view.safeAreaInsets.left + margin : view.bounds.maxX - view.safeAreaInsets.right - size.width - margin
         accessoryGlass.frame = CGRect(x: x, y: tabBar.frame.minY - size.height - 10, width: size.width, height: size.height)
         for (index, button) in buttons.enumerated() {
-            let place = CGFloat(rightToLeft && !vertical ? buttons.count - 1 - index : index) * step
+            // Every point of the capsule belongs to the nearest action; its
+            // symbol stays where Maps puts it, at the centre of a round end
+            // for the first and the last.
+            let place = rightToLeft && !vertical ? buttons.count - 1 - index : index
+            let centre = breadth / 2 + CGFloat(place) * step
+            let from = place == 0 ? 0 : centre - step / 2
+            let to = place == buttons.count - 1 ? length : centre + step / 2
             button.frame = vertical
-                ? CGRect(x: 0, y: place, width: breadth, height: step)
-                : CGRect(x: place, y: 0, width: step, height: breadth)
+                ? CGRect(x: 0, y: from, width: breadth, height: to - from)
+                : CGRect(x: from, y: 0, width: to - from, height: breadth)
+            let shift = 2 * (centre - from) - (to - from)
+            let before = max(0, shift), after = max(0, -shift)
+            button.configuration?.contentInsets = vertical
+                ? NSDirectionalEdgeInsets(top: before, leading: 0, bottom: after, trailing: 0)
+                : NSDirectionalEdgeInsets(top: 0, leading: rightToLeft ? after : before, bottom: 0, trailing: rightToLeft ? before : after)
         }
         let badgeWidth = max(18, accessoryBadge.intrinsicContentSize.width + 8)
         let primary = accessoryButton.convert(accessoryButton.bounds, to: view)

package/templates/CraftNativeActions.swift

@@ -391,7 +391,7 @@ enum CraftNativeActions {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Local database is disabled"), completion)
                 return
             }
-            databaseQueue.async { complete(requestToken, database(method: method, args: args), completion) }
+            databaseQueue.async { complete(requestToken, database(requestToken: requestToken, method: method, args: args), completion) }
             return
         case ("Browser", "open"):
             // SFSafariViewController, or for `mode: 'auth'` the system's web
@@ -1275,7 +1275,47 @@ enum CraftNativeActions {
         #endif
     }
 
-    private static func database(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+    /// A screen has gone. A transaction it began and never finished is rolled
+    /// back.
+    ///
+    /// The database is one connection shared by every screen, and a
+    /// transaction left open on it does not end with the screen that began
+    /// it: every later write joins it, reads back as written, and is gone
+    /// when the process exits, since nobody is left to commit; every later
+    /// `beginTransaction` is refused. Rolling back loses what the closed
+    /// screen had not committed, which is what closing mid-transaction means,
+    /// and gives every later write its own fate back. Queued behind whatever
+    /// that screen had already asked for.
+    static func endScope(_ scope: String) {
+        databaseQueue.async {
+            guard transactionScope == scope else { return }
+            transactionScope = nil
+            guard let database, sqlite3_get_autocommit(database) == 0 else { return }
+            _ = execute(sql: "ROLLBACK", params: [])
+        }
+    }
+
+    /// Which screen's transaction is open, read off the database around each
+    /// call rather than off the method's name, so a `BEGIN` sent through
+    /// `execute` is owned like one sent through `beginTransaction`: a call
+    /// that leaves a transaction open where there was none began it, and one
+    /// that leaves none ended it. The scope is the part of a request token
+    /// before its last `/`. Only touched on `databaseQueue`.
+    private static var transactionScope: String?
+
+    private static func database(requestToken: String, method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+        let before = database.map { sqlite3_get_autocommit($0) == 0 } ?? false
+        let answer = databaseCall(method: method, args: args)
+        let after = database.map { sqlite3_get_autocommit($0) == 0 } ?? false
+        if after && !before {
+            transactionScope = requestToken.range(of: "/", options: .backwards).map { String(requestToken[..<$0.lowerBound]) } ?? ""
+        } else if !after {
+            transactionScope = nil
+        }
+        return answer
+    }
+
+    private static func databaseCall(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
         guard openDatabase() else { return failure("DATABASE_ERROR", "Could not open the local database") }
         switch method {
         case "execute":
@@ -1497,7 +1537,11 @@ enum CraftNativeActions {
             "host": url.host ?? "",
             "path": url.path,
             "query": url.query ?? "",
-            "queryParams": Dictionary(uniqueKeysWithValues: (components?.queryItems ?? []).map { ($0.name, $0.value ?? "") }),
+            // A link is whatever its sender wrote, and may name a parameter
+            // twice. Built with unique keys this trapped, and the app closed
+            // on being opened by such a link. The first value is kept, which
+            // is the one Android gives.
+            "queryParams": Dictionary((components?.queryItems ?? []).map { ($0.name, $0.value ?? "") }, uniquingKeysWith: { first, _ in first }),
         ]
     }
 

package/templates/CraftNativeFiles.swift

@@ -902,8 +902,15 @@ enum CraftNativeFiles {
         guard let text = data as? String else {
             return .failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.write needs its contents as a string"))
         }
+        // Absent or null is utf8. Anything else that is not one of the two
+        // names is refused, a number included, rather than read as utf8.
+        let encoding: String?
+        switch options["encoding"] {
+        case nil, is NSNull: encoding = "utf8"
+        case let named: encoding = named as? String
+        }
         let bytes: Data
-        switch options["encoding"] as? String ?? "utf8" {
+        switch encoding {
         case "utf8":
             bytes = Data(text.utf8)
         case "base64":

package/templates/CraftNativeScreen.swift

@@ -4798,14 +4798,23 @@ final class CraftPressFeedbackDelegate: NSObject, UIGestureRecognizerDelegate {
 
 /// Whether a scrolling view's gesture runs together with `other`. A scroll
 /// view is the delegate of its own pan as well as of its keyboard tap, so this
-/// answers for both. Everything runs together (the keyboard tap watches
+/// answers for both. Most things run together (the keyboard tap watches
 /// alongside a control's own gestures; the back-swipe and the tab swipe decide
-/// for themselves) except two scroll views' pans: run together, a drag on a
-/// nested scroll view scrolled its parent at the same time.
+/// for themselves), with two exceptions for a scroll view's pan.
+///
+/// Another scroll view's pan: run together, a drag on a nested scroll view
+/// scrolled its parent at the same time.
+///
+/// A press. A row or a card that can be pressed is a view with a tap
+/// recognizer, and UIKit fails a tap the moment a drag begins on the scroll
+/// view around it. That is what keeps a flick, or the touch that stops a
+/// moving list, from also pressing whatever is under the finger. Told to run
+/// together, both happened: a short scroll pressed the thing it began on.
 func craftScrollGesture(_ gesture: UIGestureRecognizer, runsWith other: UIGestureRecognizer) -> Bool {
-    guard let scroll = gesture.view as? UIScrollView, gesture === scroll.panGestureRecognizer,
-          let otherScroll = other.view as? UIScrollView, other === otherScroll.panGestureRecognizer else { return true }
-    return false
+    guard let scroll = gesture.view as? UIScrollView, gesture === scroll.panGestureRecognizer else { return true }
+    if let otherScroll = other.view as? UIScrollView, other === otherScroll.panGestureRecognizer { return false }
+    if other is UITapGestureRecognizer, other.delegate is CraftPressGestureDelegate { return false }
+    return true
 }
 
 /// Scroll containers observe taps without cancelling native input focus or
@@ -6930,6 +6939,17 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private var runningAnimation: CraftNativeRunningAnimation?
     private var renderedRoot: RenderedNode?
     private weak var lastFocusedInput: UIView?
+    /// On its way off screen, or off it: from `viewWillDisappear` until the
+    /// screen is next about to appear.
+    ///
+    /// A screen ends editing as it starts to leave (#497), and its view stays
+    /// in the window for the length of the transition. Whatever put focus
+    /// back in that time brought the keyboard up for a screen that was then
+    /// removed, where nothing could put it away: a render, and a sign-in
+    /// screen makes one as it navigates; the acknowledgement an input had
+    /// scheduled a tenth of a second before; a modal closing; `autoFocus`.
+    /// Each of them asks this first.
+    private var isLeavingScreen = false
 
     /// The person put the keyboard away (Return, or a tap on nothing in a
     /// scroll view): the last input is let go. Kept, the next render or
@@ -7035,6 +7055,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let timers = self.timers
         CraftNativeScriptThread.run { timers.pending.values.forEach { $0.cancel() } }
         pendingCapabilityRequests.forEach { CraftNativeActions.cancel(requestToken: $0) }
+        CraftNativeActions.endScope(capabilityScope)
         lifecycleObservers.forEach(NotificationCenter.default.removeObserver)
         if let deepLinkListener = deepLinkListener { DeepLinkManager.shared.removeNativeListener(deepLinkListener) }
     }
@@ -7091,6 +7112,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     override func viewWillAppear(_ animated: Bool) {
         super.viewWillAppear(animated)
+        isLeavingScreen = false
         if let navigationBarHidden, navigationController?.isNavigationBarHidden != navigationBarHidden {
             navigationController?.setNavigationBarHidden(navigationBarHidden, animated: animated)
         } else if navigationBarHidden == nil, navigationController?.isNavigationBarHidden == true,
@@ -7133,7 +7155,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         //
         // `lastFocusedInput` is deliberately left alone. A screen merely
         // covered by a push comes back, and restoreFocus putting the person
-        // back where they were is the behaviour that was already there.
+        // back where they were is the behaviour that was already there. It
+        // is not consulted again until the screen is coming back, or what
+        // is ended here would be started again a moment later.
+        isLeavingScreen = true
         view.endEditing(true)
         screenVisibilityChanged(false)
         stopCelebrations(in: view)
@@ -7298,6 +7323,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         pendingCapabilityDeadlines.values.forEach { $0.cancel() }
         pendingCapabilityDeadlines.removeAll()
         pendingCapabilityRequests.forEach { CraftNativeActions.cancel(requestToken: $0) }
+        CraftNativeActions.endScope(capabilityScope)
         pendingCapabilityRequests.removeAll()
         if let owner = voiceRecordingOwner {
             voiceRecordingOwner = nil
@@ -9307,7 +9333,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                     reply(.failure(CraftNativeActionError(code: "UNSUPPORTED_TARGET", message: "Keyboard focus is supported only for text inputs")))
                     return true
                 }
-                guard node.view.becomeFirstResponder() else {
+                // A screen that is leaving does not open a keyboard it will
+                // not be there to close.
+                guard !isLeavingScreen, node.view.becomeFirstResponder() else {
                     reply(.failure(CraftNativeActionError(code: "FOCUS_FAILED", message: "The mounted view refused keyboard focus")))
                     return true
                 }
@@ -9652,6 +9680,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func restoreFocus(_ focused: UIView?) {
+        guard !isLeavingScreen else { return }
         guard let focused, focused.window != nil, !focused.isFirstResponder,
               lastFocusedInput === focused, firstResponder(in: rootStack) == nil else { return }
         var ancestor: UIView? = focused
@@ -9862,7 +9891,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             updateAuxiliaryHandler(events["onEndEditing"], in: &endEditingHandlers, for: field)
             updateAuxiliaryHandler(events["onSubmitEditing"], in: &submitHandlers, for: field)
             if props["autoFocus"] as? Bool == true, !field.isFirstResponder {
-                DispatchQueue.main.async { _ = field.becomeFirstResponder() }
+                DispatchQueue.main.async { [weak self] in
+                    guard self?.isLeavingScreen == false else { return }
+                    _ = field.becomeFirstResponder()
+                }
             }
         case "SegmentedControl":
             let control = result as! CraftNativeSegmentedControl
@@ -9982,7 +10014,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if !visible, wasVisible == true {
                 let restore = modalFocusRestore.removeValue(forKey: modalID)
                 DispatchQueue.main.async { [weak self, weak restore] in
-                    guard let self, let restore, restore.window != nil, restore.isDescendant(of: self.view) else { return }
+                    guard let self, !self.isLeavingScreen, let restore, restore.window != nil, restore.isDescendant(of: self.view) else { return }
                     self.lastFocusedInput = restore
                     _ = restore.becomeFirstResponder()
                 }
@@ -11185,7 +11217,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         updateAuxiliaryHandler(events["onEndEditing"], in: &endEditingHandlers, for: textView)
         updateAuxiliaryHandler(events["onSubmitEditing"], in: &submitHandlers, for: textView)
         if props["autoFocus"] as? Bool == true, !textView.isFirstResponder {
-            DispatchQueue.main.async { _ = textView.becomeFirstResponder() }
+            DispatchQueue.main.async { [weak self] in
+                guard self?.isLeavingScreen == false else { return }
+                _ = textView.becomeFirstResponder()
+            }
         }
     }
 

package/templates/CraftPersistentStorage.swift

@@ -13,11 +13,22 @@ enum CraftPersistentStorage {
         let digest = SHA256.hash(data: Data(key.utf8)).map { String(format: "%02x", $0) }.joined()
         return directory.appendingPathComponent(digest + ".json")
     }
+    /// What an entry file holds, or nil when it is there and is not an entry.
+    ///
+    /// A file that cannot be parsed is a corrupt value, as one that parses to
+    /// the wrong thing is, and an app starts that value again. Only a file
+    /// that cannot be read at all is the disk failing, which an app retries;
+    /// that still throws. The two used to share the disk's answer.
+    private static func entry(at source: URL) throws -> [String: Any]? {
+        let contents = try Data(contentsOf: source)
+        return (try? JSONSerialization.jsonObject(with: contents)) as? [String: Any]
+    }
+
     static func get(_ key: String, prefix: String, storageDirectory: URL? = nil) throws -> Data? {
         lock.lock(); defer { lock.unlock() }
         let source = path(key, directory: storageDirectory ?? directory)
         if FileManager.default.fileExists(atPath: source.path) {
-            guard let saved = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], saved["key"] as? String == key else {
+            guard let saved = try entry(at: source), saved["key"] as? String == key else {
                 throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
             }
             if saved["deleted"] as? Bool == true { return nil }
@@ -26,7 +37,9 @@ enum CraftPersistentStorage {
         }
         guard let legacy = UserDefaults.standard.data(forKey: prefix + key) else { return nil }
         // Only valid legacy JSON qualifies for deferred migration on I/O failure.
-        _ = try JSONSerialization.jsonObject(with: legacy, options: .fragmentsAllowed)
+        guard (try? JSONSerialization.jsonObject(with: legacy, options: .fragmentsAllowed)) != nil else {
+            throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Stored value is not valid JSON")
+        }
         // Reading a valid legacy checkpoint must survive a full disk. Migration
         // can be retried on a later read; only a successful set promises a new
         // durable checkpoint and permits the application to acknowledge it.
@@ -84,9 +97,11 @@ enum CraftPersistentStorage {
         var result = Set(UserDefaults.standard.dictionaryRepresentation().keys.filter { $0.hasPrefix(prefix) }.map { String($0.dropFirst(prefix.count)) })
         if FileManager.default.fileExists(atPath: directory.path) {
             for source in try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil) where source.pathExtension == "json" {
-                guard let entry = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], let key = entry["key"] as? String else {
-                    throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
-                }
+                // A file that is not an entry names no key. It used to fail
+                // the whole listing, and `clear` with it, over a value
+                // neither call had been asked about. `get` of its key still
+                // answers STORAGE_CORRUPT.
+                guard let entry = try entry(at: source), let key = entry["key"] as? String else { continue }
                 if entry["deleted"] as? Bool == true { result.remove(key) } else { result.insert(key) }
             }
         }
@@ -95,5 +110,13 @@ enum CraftPersistentStorage {
     static func clear(prefix: String) throws {
         lock.lock(); defer { lock.unlock() }
         for key in try keys(prefix: prefix) { try set(key, data: nil, prefix: prefix) }
+        // Clearing a key writes over its file, so what is still not an entry
+        // belongs to no key this store knows, and cannot be marked removed.
+        // It is deleted. No earlier value can come back in its place: every
+        // one this store mirrors was removed just above.
+        guard FileManager.default.fileExists(atPath: directory.path) else { return }
+        for source in try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil) where source.pathExtension == "json" {
+            if try entry(at: source)?["key"] as? String == nil { try FileManager.default.removeItem(at: source) }
+        }
     }
 }