@craft-native/ios 0.0.244 → 0.0.246

package/dist/cli.js

@@ -298,6 +298,8 @@ function hybridConfigProblems(config) {
     else if (!usesNativeBundle(config))
       problems.push('nativeApp runs in the native bundle; it needs nativeScreens or renderer: "native".');
   }
+  if (config.nativeScriptThread !== undefined && config.nativeScriptThread !== "main" && config.nativeScriptThread !== "background")
+    problems.push(`nativeScriptThread "${String(config.nativeScriptThread)}" must be "main" or "background".`);
   return problems;
 }
 function installNativeBundle(source, output) {

package/dist/index.d.ts

@@ -240,6 +240,15 @@ export interface CraftConfig {
      * `nativeScreens` or `renderer: "native"`, and the native bundle.
      */
     nativeApp?: string;
+    /**
+     * Where native screens run their JavaScript. `"main"` (the default) runs it
+     * on the main thread; `"background"` gives screens a serial thread of their
+     * own, so a screen's script, its timers and its renders never hold the
+     * main thread while it scrolls or animates. UIKit still runs on main: the
+     * shell hands each render to it, and a pushed screen waits for its first
+     * render (at most 0.3 s) so it never slides in empty.
+     */
+    nativeScriptThread?: 'main' | 'background';
     /**
      * The native tab bar, shown from the first frame, before the page loads.
      * The page's own `tabBar.set` replaces it later. Each `id` is the tab's
@@ -253,6 +262,14 @@ export interface CraftConfig {
      * `craft.secureStorage.getSync('auth.token')`. Turns on secure storage.
      */
     shareStorage?: Record<string, string>;
+    /**
+     * The secure-storage key the signed-in account's token lives under
+     * (default `auth.token`). `craft.session` follows it: a change of it, made
+     * by any native screen or by the page through a `shareStorage` key, is
+     * `SESSION_CHANGED { key, token, previous }` on every native screen and a
+     * `craftsession` event on the page.
+     */
+    sessionTokenKey?: string;
     /**
      * Crash and error reporting to bughq (CraftCrashReporter.swift): crashes
      * and hangs (signal handlers, NSException, MetricKit), uncaught JavaScript
@@ -311,13 +328,27 @@ export declare function usesNativeBundle(config: Pick<CraftConfig, 'renderer' |
  */
 export declare function nativeStartPath(config: Pick<CraftConfig, 'devServerURL'>): string;
 /** What is wrong with a config's hybrid and tab settings, one sentence each. */
-export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'tabs' | 'shareStorage' | 'devServerURL' | 'nativeApp'>): string[];
+export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'tabs' | 'shareStorage' | 'devServerURL' | 'nativeApp' | 'nativeScriptThread'>): string[];
 /**
  * The builder installs a directory of route bundles (stx's `routesDir`) as
  * well as the one-file bundle, and the app runs each screen from its own
  * route's file. Stacks asks for route bundles only when this is true.
  */
 export declare const nativeRouteBundles = true;
+/**
+ * The app evaluates stx's shared runtime (`__runtime.js`, stx's
+ * `sharedRuntime`) in each screen's context before the route's own file.
+ * Stacks asks stx for it only when this is true: a route file built so
+ * refuses to run without it.
+ */
+export declare const nativeRouteRuntime = true;
+/**
+ * The app gives a screen its messages a language at a time (stx's
+ * `messages`, `native-screens/__messages/`): read when the screen first
+ * looks inside them (`__stxNativeReadMessages`). Stacks leaves the languages
+ * out of the screens' code only when this is true.
+ */
+export declare const nativeMessages = true;
 export interface CraftBackgroundRefresh {
     enabled: boolean;
     /** The BGTaskScheduler identifier. Default `<bundleId>.refresh`. */

package/dist/index.js

@@ -482,9 +482,13 @@ function hybridConfigProblems(config) {
     else if (!usesNativeBundle(config))
       problems.push('nativeApp runs in the native bundle; it needs nativeScreens or renderer: "native".');
   }
+  if (config.nativeScriptThread !== undefined && config.nativeScriptThread !== "main" && config.nativeScriptThread !== "background")
+    problems.push(`nativeScriptThread "${String(config.nativeScriptThread)}" must be "main" or "background".`);
   return problems;
 }
 var nativeRouteBundles = true;
+var nativeRouteRuntime = true;
+var nativeMessages = true;
 function installNativeBundle(source, output) {
   if (!existsSync(source))
     throw new Error(`Native bundle not found: ${source}`);
@@ -1568,7 +1572,9 @@ export {
   open,
   normalizeNativePath,
   nativeStartPath,
+  nativeRouteRuntime,
   nativeRouteBundles,
+  nativeMessages,
   matchNativePath,
   isHybrid,
   installRuntime,

package/package.json

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

package/templates/CraftApp.swift

@@ -1619,9 +1619,17 @@ struct CraftConfig: Codable {
     /// Hybrid: web-storage keys the page's own code writes, mirrored into the
     /// Keychain under another name for native screens (`{"auth_token": "auth.token"}`).
     var shareStorage: [String: String]? = nil
+    /// The secure-storage key the signed-in account's token lives under
+    /// (`auth.token` unless set): `craft.session` follows it, and a change of
+    /// it is `SESSION_CHANGED` on every screen (CraftSession).
+    var sessionTokenKey: String? = nil
     /// The bundle route of the app script: a screen-less script that runs for
     /// the app's whole life and hears the app's events (CraftHybrid.swift).
     var nativeApp: String? = nil
+    /// Where native screens run their JavaScript: `"main"` (the default) or
+    /// `"background"`, a thread of their own, so a screen's script and its
+    /// renders never hold the main thread (CraftNativeScriptThread).
+    var nativeScriptThread: String? = nil
     /// Crash and error reporting to bughq (CraftCrashReporter.swift). Off
     /// unless the config names a project key.
     var crashReporting: CrashReporting? = nil

package/templates/CraftHybrid.swift

@@ -354,6 +354,7 @@ final class CraftHybrid: NSObject {
         guard !isConfigured else { return }
         isConfigured = true
         self.config = config
+        CraftNativeScriptThread.isBackground = config.nativeScriptThread == "background"
         hasWeb = config.renderer != "native"
         siteURL = config.devServerURL.flatMap(URL.init(string:)).flatMap { url in
             ["http", "https"].contains((url.scheme ?? "").lowercased()) ? url : nil
@@ -488,12 +489,16 @@ final class CraftHybrid: NSObject {
     func pageScript() -> String {
         let routeList = (config.nativeScreens ?? [:]).map { ["pattern": $0.key, "screen": $0.value] }
         let share = Array((config.shareStorage ?? [:]).keys).sorted()
+        // The page's key for the sign-in token, when it shares one.
+        let tokenKey = CraftSession.tokenKey(config)
+        let session = (config.shareStorage ?? [:]).filter { $0.value == tokenKey }.map(\.key).sorted().first
         func json(_ value: Any) -> String {
             (try? JSONSerialization.data(withJSONObject: value)).flatMap { String(data: $0, encoding: .utf8) } ?? "[]"
         }
         return Self.pageScriptTemplate
             .replacingOccurrences(of: "__CRAFT_HYBRID_ROUTES__", with: json(routeList))
             .replacingOccurrences(of: "__CRAFT_HYBRID_SHARE__", with: json(share))
+            .replacingOccurrences(of: "__CRAFT_HYBRID_SESSION__", with: session.map { json([$0]) } ?? "[]")
     }
 
     // CRAFT_HYBRID_PAGE_SCRIPT_START
@@ -691,13 +696,46 @@ final class CraftHybrid: NSObject {
 
       // Web storage the config shares with native screens (`shareStorage`).
       var shared = {};
-      function share(key) {
+      // The page's key for the sign-in token (`sessionTokenKey`), if shared.
+      var SESSION = (__CRAFT_HYBRID_SESSION__)[0] || null;
+      var sessionListeners = [];
+      function stored(key) {
         var value = null;
         try { value = window.sessionStorage.getItem(key); } catch (e) {}
         try { if (value === null) value = window.localStorage.getItem(key); } catch (e) {}
+        return value;
+      }
+      function sessionToken(value) { return typeof value === 'string' && value !== '' ? value : null; }
+      function share(key) {
+        var value = stored(key);
         if (shared[key] === value) return;
+        var known = Object.prototype.hasOwnProperty.call(shared, key);
+        var before = shared[key];
         shared[key] = value;
         post({ type: 'shareStorage', key: key, value: value });
+        // A sign-in, sign-out or another account, made here or on a native
+        // screen: `craftsession { key, token, previous }` and craft.session.
+        if (key === SESSION && known && sessionToken(before) !== sessionToken(value)) {
+          var change = { key: key, token: sessionToken(value), previous: sessionToken(before) };
+          sessionListeners.slice().forEach(function (callback) {
+            try { callback(change.token, change.previous); } catch (e) { console.error(e); }
+          });
+          try { window.dispatchEvent(new CustomEvent('craftsession', { detail: change })); } catch (e) {}
+        }
+      }
+      if (SESSION && window.craft && !window.craft.session) {
+        window.craft.session = {
+          key: SESSION,
+          token: function () { return sessionToken(stored(SESSION)); },
+          onChange: function (callback) {
+            if (typeof callback !== 'function') throw new TypeError('craft.session.onChange needs a function');
+            sessionListeners.push(callback);
+            return function () {
+              var index = sessionListeners.indexOf(callback);
+              if (index >= 0) sessionListeners.splice(index, 1);
+            };
+          }
+        };
       }
       if (SHARE.length && window.Storage) {
         var proto = window.Storage.prototype;
@@ -808,7 +846,9 @@ final class CraftHybrid: NSObject {
             guard let nativeKey = config.shareStorage?[key] else { return }
             // The page's own write, or its echo of one a native screen made.
             pendingShared.removeValue(forKey: key)
-            CraftHybridKeychain.set(nativeKey, value: value)
+            // The page's sign-in or sign-out moves the account for every
+            // screen; an echo writes what is already there and moves nothing.
+            CraftSession.observe(key: nativeKey, config: config) { CraftHybridKeychain.set(nativeKey, value: value) }
         case .navigated(let path, let direction, let depth, let byHost):
             pagePath = path
             pageDepth = depth
@@ -1065,6 +1105,21 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// this separate from the live frame: deriving it after the drag begins
     /// makes the target jump when the translation crosses the midpoint.
     private var tabSwipeFrom: CGFloat = 0
+    /// A native screen waiting for its first content before it is pushed.
+    private var pendingPush: String?
+    /// Where the current screen already was when this gesture took over: a
+    /// swipe that caught the last one while it settled starts from there.
+    private var tabSwipeBase: CGFloat = 0
+    /// A screen still partly on screen when this gesture caught a settling
+    /// swipe and went the other way: it keeps its distance from the current
+    /// screen (`tabSwipeTrailingGap`) until it has left.
+    private var tabSwipeTrailing: UINavigationController?
+    private var tabSwipeTrailingGap: CGFloat = 0
+    /// The end of the settle under way, run at once when a swipe catches it.
+    private var settleNow: (() -> Void)?
+    private var settleCompleting = false
+    /// A caught settle's screens, where they were, for the gesture that caught it.
+    private var caughtSettle: (other: String, otherX: CGFloat, currentX: CGFloat)?
 
     init(config: CraftConfig) {
         self.config = config
@@ -1121,6 +1176,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     @objc private func tabSwipeRecognized(_ recognizer: UIPanGestureRecognizer) {
+        // A finger that lands while the last swipe settles takes the screens
+        // from where they are, as a paging scroll view does. This swipe used
+        // to be ignored until the settle ended.
+        if recognizer.state == .began, tabSwipeSettling { catchSettlingSwipe() }
         guard !tabSwipeSettling else { return }
         let tabs = hybrid.tabIds
         guard let index = tabs.firstIndex(of: currentTab), tabs.count > 1 else { return }
@@ -1138,6 +1197,9 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             updateInteractiveTabSwipe(translation: translation)
         case .ended, .cancelled, .failed:
             guard let target = activeTabSwipeTarget else {
+                // Caught and let go without a direction (or toward the edge):
+                // the caught screens finish where they were going.
+                if caughtSettle != nil { settleCaughtScreens(); return }
                 guard recognizer.state == .ended else { return }
                 let delta = abs(translation) >= 32 ? translation : velocity
                 guard abs(delta) >= 32 else { return }
@@ -1152,7 +1214,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             // jumping straight to their destination.
             tabSwipeSettling = true
             let direction: CGFloat = tabSwipeFrom > 0 ? -1 : 1
-            let progress = translation * direction
+            let progress = (translation + tabSwipeBase) * direction
             let speed = velocity * direction
             let complete = recognizer.state == .ended && speed > -700
                 && (progress >= max(32, view.bounds.width * 0.28) || speed > 700)
@@ -1213,7 +1275,20 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         target.view.isHidden = false
         let width = view.bounds.width
         tabSwipeFrom = -direction * width
-        target.view.frame = view.bounds.offsetBy(dx: tabSwipeFrom, dy: 0)
+        // Caught from a settle: the current screen is still where the last
+        // swipe left it, and the other screen it showed either is this
+        // target (the finger went back to it) or trails behind.
+        tabSwipeBase = 0
+        tabSwipeTrailing = nil
+        if let caught = caughtSettle {
+            caughtSettle = nil
+            tabSwipeBase = caught.currentX
+            if caught.other != id, let other = stacks[caught.other] {
+                tabSwipeTrailing = other
+                tabSwipeTrailingGap = caught.otherX - caught.currentX
+            }
+        }
+        target.view.frame = view.bounds.offsetBy(dx: tabSwipeFrom + tabSwipeBase, dy: 0)
         view.bringSubviewToFront(target.view)
         CraftChrome.shared.beginTabSwipe(to: id, from: currentTab)
         lastNavigation = CACurrentMediaTime()
@@ -1226,13 +1301,16 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
               let target = stacks[targetId] else { return }
         let width = max(1, view.bounds.width)
         // Reversing past the start stays at zero progress, rather than
-        // pulling both screens away and exposing the background.
+        // pulling both screens away and exposing the background; past where
+        // a caught swipe left the screens, when it left them further out.
+        let raw = translation + tabSwipeBase
         let offset = tabSwipeFrom > 0
-            ? min(0, max(-width, translation))
-            : max(0, min(width, translation))
+            ? min(max(0, tabSwipeBase), max(-width, raw))
+            : max(min(0, tabSwipeBase), min(width, raw))
         target.view.frame.origin.x = tabSwipeFrom + offset
         current.view.frame.origin.x = offset
-        CraftChrome.shared.updateTabSwipe(progress: abs(offset) / width)
+        tabSwipeTrailing?.view.frame.origin.x = offset + tabSwipeTrailingGap
+        CraftChrome.shared.updateTabSwipe(progress: max(0, tabSwipeFrom > 0 ? -offset : offset) / width)
     }
 
     private func finishInteractiveTabSwipe(completed: Bool, velocity: CGFloat, completion: @escaping () -> Void) {
@@ -1247,13 +1325,20 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         CraftChrome.shared.settleTabSwipe(completed: completed, duration: duration)
         let remaining = end - target.view.frame.minX
         let initialVelocity = abs(remaining) > 1 ? max(0, min(12, velocity / remaining)) : 0
+        let trailing = tabSwipeTrailing
+        let gap = tabSwipeTrailingGap
         let move = {
             target.view.frame.origin.x = end
             current.view.frame.origin.x = completed ? -direction * width : 0
+            trailing?.view.frame.origin.x = current.view.frame.origin.x + gap
         }
-        let settled: (Bool) -> Void = { _ in
-            guard self.tabSwipeGeneration == generation,
-                  self.activeTabSwipeTarget == targetId else { return }
+        let finish = {
+            if let trailing {
+                trailing.view.isHidden = true
+                trailing.view.frame = self.view.bounds
+            }
+            self.tabSwipeTrailing = nil
+            self.tabSwipeBase = 0
             if completed {
                 current.view.isHidden = true
                 current.view.frame = self.view.bounds
@@ -1270,15 +1355,81 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             }
             completion()
         }
+        settleNow = finish
+        settleCompleting = completed
+        let settled: (Bool) -> Void = { _ in
+            guard self.tabSwipeGeneration == generation,
+                  self.activeTabSwipeTarget == targetId else { return }
+            self.settleNow = nil
+            finish()
+        }
         UIView.animate(withDuration: duration, delay: 0, usingSpringWithDamping: 1,
                        initialSpringVelocity: initialVelocity,
                        options: [.beginFromCurrentState, .allowUserInteraction], animations: move, completion: settled)
     }
 
+    /// A finger landed while the last swipe settled. Its end happens now,
+    /// commit or cancel, chrome and events included, and the two screens go
+    /// back exactly where they were on screen (no frame is drawn between),
+    /// for this gesture to carry on from.
+    private func catchSettlingSwipe() {
+        guard let finish = settleNow, let targetId = activeTabSwipeTarget,
+              let current = visibleStack, let target = stacks[targetId] else { return }
+        let outgoing = currentTab
+        let currentX = current.view.layer.presentation()?.frame.minX ?? current.view.frame.minX
+        let targetX = target.view.layer.presentation()?.frame.minX ?? target.view.frame.minX
+        tabSwipeGeneration &+= 1
+        for nav in [current, target] + (tabSwipeTrailing.map { [$0] } ?? []) { nav.view.layer.removeAllAnimations() }
+        settleNow = nil
+        let completing = settleCompleting
+        CraftFramePacing.shared.end("tab swipe")
+        finish()
+        let (stay, stayX, other, otherId, otherX) = completing
+            ? (target, targetX, current, outgoing, currentX)
+            : (current, currentX, target, targetId, targetX)
+        guard abs(stayX) > 0.5 else { return }
+        stay.view.frame = view.bounds.offsetBy(dx: stayX, dy: 0)
+        other.view.isHidden = false
+        other.view.frame = view.bounds.offsetBy(dx: otherX, dy: 0)
+        caughtSettle = (otherId, otherX, stayX)
+    }
+
+    /// A caught settle that no new swipe took on: its screens finish where
+    /// they were going.
+    private func settleCaughtScreens(animated: Bool = true) {
+        guard let caught = caughtSettle else { return }
+        caughtSettle = nil
+        guard let current = visibleStack else { return }
+        let other = stacks[caught.other]
+        let gap = caught.otherX - caught.currentX
+        let generation = tabSwipeGeneration
+        let done = {
+            guard self.tabSwipeGeneration == generation else { return }
+            current.view.frame = self.view.bounds
+            other?.view.frame = self.view.bounds
+            if other !== current { other?.view.isHidden = true }
+        }
+        guard animated, CraftChrome.motion(.easeOut(duration: 0.18)) != nil else { done(); return }
+        UIView.animate(withDuration: 0.18, delay: 0, usingSpringWithDamping: 1, initialSpringVelocity: 0,
+                       options: [.beginFromCurrentState, .allowUserInteraction], animations: {
+            current.view.frame.origin.x = 0
+            other?.view.frame.origin.x = gap
+        }, completion: { _ in done() })
+    }
+
     /// A newer navigation action wins immediately, including a tap back on
     /// the outgoing tab. Invalidate the old animation before removing it:
     /// UIKit may deliver its completion while the replacement is starting.
     private func interruptTabSwipe(restoringSelection: Bool) {
+        if caughtSettle != nil { settleCaughtScreens(animated: false) }
+        if let trailing = tabSwipeTrailing {
+            trailing.view.layer.removeAllAnimations()
+            trailing.view.frame = view.bounds
+            trailing.view.isHidden = trailing !== visibleStack
+            tabSwipeTrailing = nil
+        }
+        tabSwipeBase = 0
+        settleNow = nil
         guard let targetId = activeTabSwipeTarget else { return }
         tabSwipeGeneration &+= 1
         activeTabSwipeTarget = nil
@@ -1529,6 +1680,15 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             }
             (nav.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
             (self.visibleStack?.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
+            // A script on its own thread draws a moment later: its first
+            // content is drawn ahead too, once it is there.
+            if CraftNativeScriptThread.isBackground, let screen = nav.topViewController as? CraftNativeScreenController {
+                screen.whenFirstRendered(within: 1) { [weak nav] in
+                    guard let nav, nav.view.isHidden else { return }
+                    nav.view.layoutIfNeeded()
+                    Self.drawContents(of: nav.view.layer)
+                }
+            }
             self.prepareAdjacentNativeTabs()
         }
         preparation = timer
@@ -1640,10 +1800,25 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             return
         }
         let screen = entry(for: raw, isTabRoot: false, depth: nil)
-        if replace, !nav.viewControllers.isEmpty {
-            nav.setViewControllers(Array(nav.viewControllers.dropLast()) + [screen], animated: true)
-        } else {
-            nav.pushViewController(screen, animated: true)
+        let show = { [weak nav] in
+            guard let nav else { return }
+            if replace, !nav.viewControllers.isEmpty {
+                nav.setViewControllers(Array(nav.viewControllers.dropLast()) + [screen], animated: true)
+            } else {
+                nav.pushViewController(screen, animated: true)
+            }
+        }
+        guard let native = screen as? CraftNativeScreenController, CraftNativeScriptThread.isBackground else { show(); return }
+        // Its script runs on its own thread: it slides in with its content,
+        // and a second tap meanwhile does not push it twice.
+        guard pendingPush != match.path else { return }
+        pendingPush = match.path
+        native.whenFirstRendered(within: 0.3) { [weak self, weak nav] in
+            guard let self, self.pendingPush == match.path else { return }
+            self.pendingPush = nil
+            // Not into a tab the person has left meanwhile.
+            guard let nav, nav === self.visibleStack else { return }
+            show()
         }
     }
 
@@ -1906,7 +2081,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     func gestureRecognizerShouldBegin(_ gestureRecognizer: UIGestureRecognizer) -> Bool {
         if tabSwipeRecognizers.contains(where: { $0 === gestureRecognizer }) {
-            guard activeTabSwipeTarget == nil, !tabSwipeSettling,
+            // A swipe may begin while the last one settles: it catches it.
+            guard activeTabSwipeTarget == nil || tabSwipeSettling,
                   hybrid.tabIds.count > 1, let nav = visibleStack, let top = nav.topViewController else { return false }
             guard CraftChrome.shared.tabSwipeEnabled else { return false }
             // Only between the tabs' own first screens, as the bar shows them:

package/templates/CraftNativeActions.swift

@@ -205,11 +205,21 @@ enum CraftNativeActions {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Secure storage is disabled"), completion)
                 return
             }
-            sync = secureStorage(method: method, args: args)
-            // A key the web page shares (`shareStorage`): the page gets it too,
-            // so a sign-in on a native screen signs the page in.
-            if case .success = sync, ["set", "remove", "delete"].contains(method), let key = args.first as? String {
-                CraftHybrid.shared.nativeWroteShared(nativeKey: key, value: method == "set" ? args.count > 1 ? args[1] as? String : nil : nil)
+            let write = { () -> Result<Any, CraftNativeActionError> in
+                let result = secureStorage(method: method, args: args)
+                // A key the web page shares (`shareStorage`): the page gets it too,
+                // so a sign-in on a native screen signs the page in.
+                if case .success = result, ["set", "remove", "delete"].contains(method), let key = args.first as? String {
+                    CraftHybrid.shared.nativeWroteShared(nativeKey: key, value: method == "set" ? args.count > 1 ? args[1] as? String : nil : nil)
+                }
+                return result
+            }
+            // A write that moves the sign-in token is the account's change:
+            // every screen hears it (CraftSession). Reads skip the check.
+            if ["set", "remove", "delete", "clear"].contains(method) {
+                sync = CraftSession.observe(key: method == "clear" ? nil : args.first as? String, config: config, write)
+            } else {
+                sync = write()
             }
         case ("Biometrics", "isAvailable"):
             sync = config.enableBiometric ? .success(biometricContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)) : failure("CAPABILITY_DISABLED", "Biometric authentication is disabled")
@@ -1423,6 +1433,54 @@ extension CraftNativeActions {
     }
 }
 
+/// The signed-in account: the token kept in secure storage under
+/// `sessionTokenKey` (default `auth.token`). Whoever moves it, a native
+/// screen's `craft.secureStorage`, the page's own sign-in through a
+/// `shareStorage` key, or a sign-out's clear, posts `changed` once with
+/// `key`, `token` and `previous` (NSNull when signed out), after the Keychain
+/// holds the new value. Each native screen hands it to its script as
+/// `SESSION_CHANGED` and to `craft.session.onChange` (CraftNativeScreen).
+enum CraftSession {
+    static let changed = Notification.Name("craftSessionChanged")
+    static let defaultKey = "auth.token"
+    /// One write and its before and after at a time, so two quick writes
+    /// from different queues are two changes, never one reported twice.
+    private static let lock = NSLock()
+
+    static func tokenKey(_ config: CraftConfig) -> String {
+        guard let key = config.sessionTokenKey, !key.isEmpty else { return defaultKey }
+        return key
+    }
+
+    /// The token now, as `craft.secureStorage.getSync` reads it; nil when
+    /// signed out (an empty token is no account either).
+    static func token(_ config: CraftConfig) -> String? {
+        guard config.enableSecureStorage,
+              let value = CraftNativeActions.webSecureValue(forKey: tokenKey(config)), !value.isEmpty else { return nil }
+        return value
+    }
+
+    /// Run `write`, and post `changed` when it moved the token. `key` is the
+    /// key written; nil for a clear, which can remove every key.
+    static func observe<T>(key: String?, config: CraftConfig, _ write: () -> T) -> T {
+        let name = tokenKey(config)
+        guard key == nil || key == name else { return write() }
+        lock.lock()
+        let before = token(config)
+        let result = write()
+        let after = token(config)
+        lock.unlock()
+        if before != after { post(key: name, token: after, previous: before) }
+        return result
+    }
+
+    static func post(key: String, token: String?, previous: String?) {
+        let info: [String: Any] = ["key": key, "token": token ?? NSNull(), "previous": previous ?? NSNull()]
+        let send = { NotificationCenter.default.post(name: changed, object: nil, userInfo: info) }
+        if Thread.isMainThread { send() } else { DispatchQueue.main.async(execute: send) }
+    }
+}
+
 /// Last-known data for a screen's first frame: one JSON file per name in
 /// `Application Support/craft-snapshots/<name>.json`. A web page writes them
 /// (`snapshots.set` in the mobile API) and a native screen reads them

package/templates/CraftNativeFlatList.swift

@@ -52,11 +52,19 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         var onRecycle: ((String) -> Void)?
         override func prepareForReuse() {
             super.prepareForReuse()
-            releaseHostedView()
+            recycle()
+        }
+
+        /// The row this cell showed is gone; its views stay in the cell, and
+        /// the next row it shows reuses them when it has the same shape.
+        func recycle() {
+            if let identity = representedIdentity { onRecycle?(identity) }
+            representedIdentity = nil
+            onRecycle = nil
         }
 
         func host(_ view: UIView, identity: String) {
-            if representedIdentity != identity { releaseHostedView() }
+            if let shown = representedIdentity, shown != identity { recycle() }
             representedIdentity = identity
             guard hostedView !== view else { return }
             hostedView?.removeFromSuperview()
@@ -72,11 +80,9 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         }
 
         func releaseHostedView() {
-            if let identity = representedIdentity { onRecycle?(identity) }
+            recycle()
             hostedView?.removeFromSuperview()
             hostedView = nil
-            representedIdentity = nil
-            onRecycle = nil
         }
 
         override func preferredLayoutAttributesFitting(
@@ -354,7 +360,8 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
 
     @objc private func refreshTriggered() {
         refreshHandler?()
-        DispatchQueue.main.async { [weak self] in
+        // Once the script has answered the pull, on its own thread or not.
+        CraftNativeScriptThread.afterScript { [weak self] in
             guard let self, !self.refreshingProp, self.nativeRefreshControl.isRefreshing else { return }
             self.nativeRefreshControl.endRefreshing()
         }