craft-native 0.0.155 → 0.0.156

package/dist/cli.js

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

package/dist/index.cjs

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

package/dist/index.js

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

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

@@ -83,6 +83,14 @@ export interface CraftConfig {
      * Each replaces the generic sentence Craft writes for that key.
      */
     usageDescriptions?: Record<string, string>;
+    /**
+     * The app's site. With `renderer: "web"` it is the page the web view loads.
+     * With `renderer: "native"` and `nativeScreens` there is no web view: its
+     * path is the path the app starts on (`/` when unset), and a path no native
+     * screen draws (`craft.navigation.open('/terms')`, or a link to this host)
+     * opens in the in-app browser against its origin. Native screens read it as
+     * `__stxNativeBridge.appURL`.
+     */
     devServerURL?: string;
     iosVersion?: string;
     watchosVersion?: string;
@@ -168,16 +176,32 @@ export interface CraftConfig {
     orientations?: Array<'portrait' | 'landscape-left' | 'landscape-right' | 'portrait-upside-down'>;
     deviceFamilies?: Array<'iphone' | 'ipad'>;
     /**
-     * Hybrid: app paths drawn as native stx screens instead of in the
-     * web view, each to the screen in the native bundle that draws it, e.g.
-     * `{ "/m": "Today", "/m/calendar": "Calendar" }`. A segment may be a
-     * parameter (`/m/workout/:id`) and the last one `*`. Needs `renderer: "web"`
-     * and `nativeBundle`; every other path stays in the web view, and a path
-     * whose screen is missing or throws falls back to it.
+     * App paths drawn as native stx screens, each to the screen in the native
+     * bundle that draws it, e.g. `{ "/m": "Today", "/m/calendar": "Calendar" }`.
+     * A segment may be a parameter (`/m/workout/:id`) and the last one `*`.
+     * Needs `nativeBundle`.
+     *
+     * With `renderer: "web"` (hybrid) every other path stays in the web view,
+     * and a path whose screen is missing or throws falls back to it.
+     *
+     * With `renderer: "native"` the app is all native, with the same tabs and
+     * path routing and no web view at all: every tab id and the start path (the
+     * path of `devServerURL`) must be a native screen's, and any other path
+     * opens in the in-app browser on the app's site.
      */
     nativeScreens?: Record<string, string>;
-    /** Hybrid: the bundle `stx native compile --format bundle` wrote, copied to `dist/native-screen.js`. */
+    /** The bundle `stx native compile --format bundle` wrote, copied to `dist/native-screen.js`. */
     nativeBundle?: string;
+    /**
+     * The bundle route of a screen-less script that runs once for the app's
+     * whole life, beside the screens (Stacks names it `__app`). It hears the
+     * app's events (`craftNotificationResponse`, `craftNotificationReceived`,
+     * `craftSilentPush`, `craftBackgroundRefresh`, `craftShortcut`,
+     * `craftSiriShortcut`) as `CRAFT_EVENT` messages instead of the page, every
+     * `APP_STATE`, and can open paths with `craft.navigation.open`. Needs
+     * `nativeScreens` or `renderer: "native"`, and the native bundle.
+     */
+    nativeApp?: string;
     /**
      * 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
@@ -214,8 +238,18 @@ export interface NativePathMatch {
 export declare function matchNativePath(nativeScreens: Record<string, string> | undefined, raw: string): NativePathMatch | null;
 /** Whether a config mixes native screens into its web page. */
 export declare function isHybrid(config: Pick<CraftConfig, 'renderer' | 'nativeScreens'>): boolean;
+/** Whether a config is an all-native app with routes: `renderer: "native"` and `nativeScreens`, tabs and paths with no web view. */
+export declare function hasNativeRoutes(config: Pick<CraftConfig, 'renderer' | 'nativeScreens'>): boolean;
+/** Whether a config draws any native screen, and so needs `dist/native-screen.js`. */
+export declare function usesNativeBundle(config: Pick<CraftConfig, 'renderer' | 'nativeScreens'>): boolean;
+/**
+ * The path the app starts on: the path of `devServerURL` (with its query),
+ * `/` when there is none. The shell reads it the same way
+ * (`CraftHybridRoutes.appPath`).
+ */
+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'>): string[];
+export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'tabs' | 'shareStorage' | 'devServerURL' | 'nativeApp'>): string[];
 export interface CraftBackgroundRefresh {
     enabled: boolean;
     /** The BGTaskScheduler identifier. Default `<bundleId>.refresh`. */

package/dist/ios/src/index.js

@@ -228,11 +228,25 @@ function matchNativePath(nativeScreens, raw) {
 function isHybrid(config) {
   return (config.renderer ?? "web") === "web" && Object.keys(config.nativeScreens ?? {}).length > 0;
 }
+function hasNativeRoutes(config) {
+  return config.renderer === "native" && Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+function usesNativeBundle(config) {
+  return config.renderer === "native" || Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+function nativeStartPath(config) {
+  if (!config.devServerURL)
+    return "/";
+  try {
+    const url = new URL(config.devServerURL);
+    return `${url.pathname || "/"}${url.search}`;
+  } catch {
+    return "/";
+  }
+}
 function hybridConfigProblems(config) {
   const problems = [];
   const screens = Object.entries(config.nativeScreens ?? {});
-  if (screens.length && config.renderer === "native")
-    problems.push('nativeScreens mixes native screens into a web app; it needs renderer: "web" (renderer: "native" is all native already).');
   for (const [pattern, screen] of screens) {
     if (normalizeNativePath(pattern) !== pattern || /[?#]/.test(pattern))
       problems.push(`nativeScreens path "${pattern}" must be an absolute path with no query, hash or trailing slash.`);
@@ -254,6 +268,21 @@ function hybridConfigProblems(config) {
     if (!key || typeof target !== "string" || !target)
       problems.push(`shareStorage "${key}" needs the Keychain key native screens read it under.`);
   }
+  if (hasNativeRoutes(config)) {
+    for (const id of ids) {
+      if (!matchNativePath(config.nativeScreens, id))
+        problems.push(`Tab "${id}" is not a nativeScreens path; with renderer: "native" every tab must be a native screen.`);
+    }
+    const start = nativeStartPath(config);
+    if (!matchNativePath(config.nativeScreens, start))
+      problems.push(`The start path "${start}" (from devServerURL) is not a nativeScreens path; with renderer: "native" the app must start on a native screen.`);
+  }
+  if (config.nativeApp !== undefined) {
+    if (typeof config.nativeApp !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(config.nativeApp))
+      problems.push(`nativeApp "${String(config.nativeApp)}" must be a route name from the native bundle.`);
+    else if (!usesNativeBundle(config))
+      problems.push('nativeApp runs in the native bundle; it needs nativeScreens or renderer: "native".');
+  }
   return problems;
 }
 function installNativeBundle(source, output) {
@@ -1044,11 +1073,13 @@ ${nativeDependencies.join(`
     writeFileSync2(join2(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
   writeFileSync2(join2(output, "dist", "index.html"), renderOfflinePage(config));
-  if (isHybrid(config)) {
+  if (usesNativeBundle(config)) {
     if (config.nativeBundle)
       installNativeBundle(config.nativeBundle, output);
-    else
+    else if (isHybrid(config))
       console.warn("   \u26A0 nativeScreens is set without nativeBundle: every path opens in the web view until `craft ios build --native-bundle` supplies one.");
+    else if (hasNativeRoutes(config))
+      console.warn("   \u26A0 nativeScreens is set without nativeBundle: the app has no screens until `craft ios build --native-bundle` supplies one.");
   }
   console.log("\u2705 Project initialized");
   console.log("");
@@ -1080,11 +1111,9 @@ async function build(options) {
     if (htmlPath || devServer) {
       throw new Error("A native iOS screen cannot use --html-path or --dev-server.");
     }
-    if (nativeBundlePath) {
-      const destination = join2(output, "dist", "native-screen.js");
-      if (resolve(nativeBundlePath) !== resolve(destination))
-        cpSync(nativeBundlePath, destination);
-    }
+    const bundle = nativeBundlePath ?? config.nativeBundle;
+    if (bundle)
+      installNativeBundle(bundle, output);
     if (!existsSync(join2(output, "dist", "native-screen.js"))) {
       throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
@@ -1238,6 +1267,7 @@ async function run(options) {
   }
 }
 export {
+  usesNativeBundle,
   syncWebAssets,
   showSimulator,
   serializeSimulatorSteps,
@@ -1266,12 +1296,14 @@ export {
   orderSimulators,
   open,
   normalizeNativePath,
+  nativeStartPath,
   matchNativePath,
   isHybrid,
   installRuntime,
   initSimulatorDriver,
   init,
   hybridConfigProblems,
+  hasNativeRoutes,
   createNativeMutationValidator,
   build,
   bootSimulator,

package/dist/ios/templates/CraftApp.swift

@@ -195,8 +195,14 @@ struct CraftRecoveryBudget {
 final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
         UNUserNotificationCenter.current().delegate = self
+        let config = CraftConfig.bundled()
         // Before launch finishes, which is the only time iOS accepts it.
-        CraftBackgroundWork.shared.registerRefresh(CraftConfig.bundled())
+        CraftBackgroundWork.shared.registerRefresh(config)
+        // The shell, the app script and an all-native app's services now,
+        // not when SwiftUI first draws: a launch in the background (a silent
+        // push, a refresh, a route recording's location) draws nothing, and
+        // its events still need someone to hear them.
+        CraftHybrid.shared.configure(config)
         if let shortcut = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
             CraftEventManager.shared.handleShortcut(shortcut)
             // Returning false tells UIKit the launch-time item was handled and
@@ -269,12 +275,32 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
 }
 
 // MARK: - Native Event Manager
+
+/// The app's own events: a notification tapped or arriving, a silent push,
+/// background refresh, a home-screen or Siri shortcut. They go to the page,
+/// or, in an app with an app script (`nativeApp`, CraftHybrid.swift), to that
+/// script as `CRAFT_EVENT { event, detail }` instead. Either way an event
+/// that arrives before its listener can hear it (a tap that launched the app)
+/// waits for it, in order.
 class CraftEventManager {
     static let shared = CraftEventManager()
 
+    /// Who hears the app's events. Undecided until the shell is configured
+    /// at launch, which may be after the first event (a launch shortcut).
+    enum Listener {
+        case undecided
+        case page
+        case appScript
+        /// An all-native app with no app script: nothing hears them.
+        case none
+    }
+
     private weak var webView: WKWebView?
     private var isReady = false
+    private var listener: Listener = .undecided
     private var pendingEvents: [(name: String, data: [String: Any])] = []
+    /// The app script's delivery, once its bundle has run.
+    private var appScriptSink: ((String, [String: Any]) -> Void)?
 
     private init() {}
 
@@ -282,12 +308,35 @@ class CraftEventManager {
         self.webView = webView
     }
 
+    /// From `CraftHybrid.configure`: whether an app script hears the app's
+    /// events, and whether there is a page to hear them otherwise.
+    func configure(appScript: Bool, page: Bool) {
+        listener = appScript ? .appScript : (page ? .page : .none)
+        guard listener == .none else { return }
+        // Nothing will ever hear what is waiting; iOS gets its answer now
+        // rather than at the background deadline.
+        let events = pendingEvents
+        pendingEvents.removeAll()
+        for event in events { drop(event.name, data: event.data) }
+    }
+
+    /// The app script has run its bundle: whatever waited for it, in order.
+    func appScriptReady(_ sink: @escaping (String, [String: Any]) -> Void) {
+        appScriptSink = sink
+        guard listener == .appScript else { return }
+        let events = pendingEvents
+        pendingEvents.removeAll()
+        for event in events { sink(event.name, event.data) }
+    }
+
     func setLoading() {
         isReady = false
     }
 
     func setReady() {
         isReady = true
+        // Held for the app script, which the page's readiness says nothing about.
+        guard listener != .appScript else { return }
         let events = pendingEvents
         pendingEvents.removeAll()
         for event in events {
@@ -338,13 +387,37 @@ class CraftEventManager {
         return true
     }
 
-    /// Dispatch now if the page can hear it, or hold it until it can.
+    /// Dispatch now if the page (or the app script) can hear it, or hold it
+    /// until it can. The name says "web" for the page it was written for; the
+    /// event names are spelled at its call sites, where the conformance test
+    /// reads the vocabulary from.
     func sendToWeb(_ event: String, data: [String: Any]) {
-        guard isReady, webView != nil else {
-            pendingEvents.append((event, data))
-            return
+        switch listener {
+        case .appScript:
+            guard let appScriptSink else {
+                pendingEvents.append((event, data))
+                // Background work cannot wait for a first frame that a
+                // launch in the background never draws.
+                if event == "craftSilentPush" || event == "craftBackgroundRefresh" { CraftHybrid.shared.backgroundWorkWaiting() }
+                return
+            }
+            appScriptSink(event, data)
+        case .none:
+            drop(event, data: data)
+        case .page, .undecided:
+            guard listener == .page, isReady, webView != nil else {
+                pendingEvents.append((event, data))
+                return
+            }
+            dispatch(event, data: data)
         }
-        dispatch(event, data: data)
+    }
+
+    /// An event no one will hear: logged, and background work it holds is
+    /// answered at once.
+    private func drop(_ event: String, data: [String: Any]) {
+        NSLog("[craft] %@: the app has no page and no app script (nativeApp) to hear it", event)
+        if let id = data["id"] as? String { CraftBackgroundWork.shared.release(id) }
     }
 
     private func dispatch(_ event: String, data: [String: Any]) {
@@ -363,7 +436,9 @@ class CraftEventManager {
 /// The page's share of background time: a silent push (`craftSilentPush`) and
 /// iOS's scheduled app refresh (`craftBackgroundRefresh`). Each holds iOS's
 /// completion until the page calls `craft.background.complete(ok)` (with the
-/// event's `id`, or with none for everything pending), or for 25 seconds.
+/// event's `id`, or with none for everything pending), or for 25 seconds. In
+/// an app with an app script the script hears both and answers the same way,
+/// through the native `Background.complete` (CraftNativeActions.swift).
 ///
 /// The page has to be alive to do the work: when iOS wakes an app it had
 /// suspended, it is; when it launches one it had ended, the event waits for
@@ -400,6 +475,12 @@ final class CraftBackgroundWork {
         }
     }
 
+    /// Work no one will do (nothing hears its event): iOS is answered now,
+    /// as the deadline would have.
+    func release(_ id: String) {
+        end(id, ok: nil)
+    }
+
     private func end(_ id: String, ok: Bool?) {
         guard let finish = pending.removeValue(forKey: id) else { return }
         finish(ok)
@@ -461,11 +542,12 @@ struct CraftApp: App {
     var body: some SwiftUI.Scene {
         WindowGroup {
             Group {
-                if appState.config.renderer == "native" {
-                    CraftNativeScreen(config: appState.config)
-                } else if CraftHybrid.shared.isEnabled {
-                    // Web plus native screens (CraftHybrid.swift): the native
-                    // screen for the start path at once, the page warm behind it.
+                if CraftHybrid.shared.isEnabled {
+                    // Native screens by path, with tabs (CraftHybrid.swift):
+                    // the native screen for the start path at once, and in a
+                    // web app (hybrid) the page warm behind it. An all-native
+                    // app (renderer "native" with nativeScreens) has the same
+                    // shell and no web view at all.
                     ZStack(alignment: .bottom) {
                         CraftColorSchemeObserver()
                         CraftHybridRoot(config: appState.config)
@@ -477,6 +559,9 @@ struct CraftApp: App {
                     // stack kept out of the keyboard's way and carried the bar
                     // up above it, over the field being typed in.
                     .ignoresSafeArea(.keyboard, edges: .bottom)
+                } else if appState.config.renderer == "native" {
+                    // One native screen and its stack: no paths, no tabs.
+                    CraftNativeScreen(config: appState.config)
                 } else {
                     // The page's own chrome, drawn natively over it: the tab
                     // bar the page asks for, and the splash until it is ready.
@@ -927,10 +1012,13 @@ class DeepLinkManager {
         }
 
         // A hybrid app opens a native path's screen itself, and tells the
-        // native screens that listen; every other link is the page's.
+        // native screens that listen; every other link is the page's. An
+        // all-native app has no page: its native screens hear every link.
         if CraftHybrid.shared.isEnabled {
             if CraftHybrid.shared.handleDeepLink(url) {
                 dispatchNative(url, initial: false)
+            } else if !CraftHybrid.shared.hasWeb {
+                if nativeListeners.isEmpty { pendingURLs.append(url) } else { dispatchNative(url, initial: false) }
             } else if isReady && webView != nil {
                 dispatchDeepLink(url, initial: false)
             } else {
@@ -958,7 +1046,8 @@ class DeepLinkManager {
         nativeListeners[token] = listener
         // In a hybrid app the page is the one waiting for the links that
         // arrived early; a native screen hears only native ones, as they come.
-        if CraftHybrid.shared.isEnabled { return token }
+        // An all-native app has no page, so its first screen hears them.
+        if CraftHybrid.shared.isEnabled && CraftHybrid.shared.hasWeb { return token }
         let firstNativeScreen = !hasBeenReady
         hasBeenReady = true
         let urls = pendingURLs
@@ -1027,7 +1116,8 @@ class AppState: ObservableObject {
             self.config = CraftConfig()
         }
         // Before the first frame: the hybrid start screen, and the tab bar
-        // from the config, are decided here.
+        // from the config, are decided here, if the app delegate has not
+        // already (it does at launch; the first call decides).
         CraftHybrid.shared.configure(config)
     }
 }
@@ -1149,6 +1239,9 @@ 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 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
 
     struct Tab: Codable {
         var id: String
@@ -8500,8 +8593,10 @@ final class CraftZigRuntime: NSObject {
 /// started on a page can be followed on a native screen.
 ///
 /// The coordinator exists wherever the web view does: always in a hybrid app.
-/// Calls go to the Swift dispatcher; a build that links the Zig runtime keeps
-/// the page's calls on Zig.
+/// An app with no web view (renderer "native") has one all the same, without
+/// a web view (`CraftHybrid.configure`), so its native screens have these
+/// services too. Calls go to the Swift dispatcher; a build that links the Zig
+/// runtime keeps the page's calls on Zig.
 enum CraftWebServices {
     private static var waiting: [String: (Result<Any, CraftNativeActionError>) -> Void] = [:]
     /// Coordinator events a native screen hears too.
@@ -8558,7 +8653,8 @@ enum CraftWebServices {
 /// how this codebase accumulated five envelopes.
 @objc(CraftSwiftShim)
 final class CraftSwiftShim: NSObject {
-    /// The coordinator serving hand-offs. Set by `makeCoordinator`.
+    /// The coordinator serving hand-offs. Set by `makeCoordinator`, or in an
+    /// app with no web view by `CraftHybrid.configure`, which holds it.
     static weak var coordinator: CraftWebView.Coordinator?
 
     private typealias DeliverResultFn = @convention(c) (

package/dist/ios/templates/CraftHybrid.swift

@@ -18,6 +18,18 @@ import WebKit
 // reports where it went, and leaves the edge swipe to UIKit while it is at the
 // entry a native screen opened. Nothing in the page has to change for that;
 // craft's typescript mobile API adds `snapshots` and `hybrid` on top.
+//
+// `renderer: "native"` with `nativeScreens` is the same shell with no web
+// view at all (`hasWeb` false): the same tabs, stacks and path routing, every
+// tab and the start path a native screen, and a path no screen draws opened
+// in the in-app browser on the app's site (`devServerURL`). No WKWebView is
+// ever made; the services the web view's coordinator holds (GPS, the route
+// recorder, Apple Music) come from a coordinator with no web view instead.
+//
+// Either way an app may run an app script (`nativeApp`): a bundle route with
+// no screen, loaded once after the first frame and kept for the app's life.
+// It hears the app's events (CraftEventManager) instead of the page, and
+// opens paths through the shell.
 
 /// The `nativeScreens` table: which paths are native, and with what params.
 ///
@@ -128,6 +140,34 @@ struct CraftHybridRoutes {
         return path
     }
 
+    /// Whether a web address is on the app's site: the host of `site`
+    /// (`devServerURL`), over http or https.
+    static func isSite(_ url: URL, site: URL?) -> Bool {
+        let scheme = (url.scheme ?? "").lowercased()
+        guard scheme == "http" || scheme == "https",
+              let host = url.host?.lowercased(), !host.isEmpty,
+              let siteHost = site?.host?.lowercased() else { return false }
+        return host == siteHost
+    }
+
+    /// Where a path no native screen draws opens in an app with no web view:
+    /// a web address as it is, an app path on the origin of `site`. Nil for
+    /// anything else, and for a path when there is no site.
+    static func siteURL(for raw: String, site: URL?) -> URL? {
+        if let url = URL(string: raw), let scheme = url.scheme?.lowercased() {
+            return scheme == "http" || scheme == "https" ? url : nil
+        }
+        // `//host/x` is another host, not a path.
+        guard raw.hasPrefix("/"), !raw.hasPrefix("//"), let site,
+              var origin = URLComponents(url: site, resolvingAgainstBaseURL: false),
+              let scheme = origin.scheme?.lowercased(), scheme == "http" || scheme == "https" else { return nil }
+        origin.percentEncodedPath = ""
+        origin.percentEncodedQuery = nil
+        origin.percentEncodedFragment = nil
+        guard let base = origin.url else { return nil }
+        return URL(string: raw, relativeTo: base)?.absoluteURL
+    }
+
     /// The tab a path belongs to: the tab whose id is the path, or else the
     /// longest tab id that is a whole-segment prefix of it.
     static func tab(owning raw: String, among tabs: [String]) -> String? {
@@ -233,8 +273,15 @@ final class CraftHybrid: NSObject {
 
     private(set) var config = CraftConfig()
     private(set) var routes = CraftHybridRoutes([:])
-    /// Whether this app mixes native screens into its web page.
+    /// Whether this app routes paths to native screens through the shell:
+    /// web plus native screens (hybrid), or all native with paths and tabs.
     private(set) var isEnabled = false
+    /// Whether the app has a web page at all (renderer "web"). False for an
+    /// all-native app, whose shell never makes a web view.
+    private(set) var hasWeb = true
+    /// The app's site (`devServerURL`, http or https): where an all-native
+    /// app opens a path no screen draws, in the in-app browser.
+    private(set) var siteURL: URL?
     /// The path the app opens on: its page's path.
     private(set) var startPath = "/"
     /// Whether that path is a native screen, drawn before the page loads.
@@ -242,6 +289,22 @@ final class CraftHybrid: NSObject {
     weak var controller: CraftHybridController?
     weak var webView: WKWebView?
 
+    /// The app script's bundle route (`nativeApp`), when it runs.
+    private(set) var appScriptRoute: String?
+    /// The app script itself, held for the app's life and never shown.
+    private var appScript: CraftNativeScreenController?
+    /// An all-native app's services: the web view's coordinator, with no web
+    /// view, so GPS, the route recorder (and its relaunch restore) and Apple
+    /// Music serve native screens (CraftWebServices). Held here, because
+    /// `CraftSwiftShim.coordinator` is weak.
+    private var services: CraftWebView.Coordinator?
+    private var isConfigured = false
+    /// A single-stack native app's first frame, which starts the app script.
+    private var firstFrameSeen = false
+    /// What waits for the shell: links and opens that arrived before it
+    /// existed (a launch from a notification or a link).
+    private var untilShell: [(CraftHybridController) -> Void] = []
+
     /// Where the page is, as it last said.
     fileprivate(set) var pagePath: String?
     fileprivate(set) var pageDepth = 0
@@ -261,6 +324,7 @@ final class CraftHybrid: NSObject {
     func nativeWroteShared(nativeKey: String, value: String?) {
         guard let webKey = config.shareStorage?.first(where: { $0.value == nativeKey })?.key else { return }
         CraftHybridKeychain.set(nativeKey, value: value)
+        guard hasWeb else { return }
         DispatchQueue.main.async {
             self.pendingShared[webKey] = value ?? NSNull()
             self.flushShared()
@@ -279,20 +343,113 @@ final class CraftHybrid: NSObject {
             ?? Bundle.main.url(forResource: "native-screen", withExtension: "js")
     }
 
-    /// From the bundled config, before the first frame: whether the app is
-    /// hybrid, where it starts, and the tab bar it starts with.
+    /// From the bundled config, at launch: whether the shell routes paths,
+    /// whether there is a web view, where it starts, the tab bar it starts
+    /// with, the app script, and an all-native app's services. Once: the app
+    /// delegate calls it at launch and AppState again; the first call decides.
     func configure(_ config: CraftConfig) {
+        guard !isConfigured else { return }
+        isConfigured = true
         self.config = config
+        hasWeb = config.renderer != "native"
+        siteURL = config.devServerURL.flatMap(URL.init(string:)).flatMap { url in
+            ["http", "https"].contains((url.scheme ?? "").lowercased()) ? url : nil
+        }
         routes = CraftHybridRoutes(config.nativeScreens ?? [:])
         startPath = config.devServerURL.flatMap(URL.init(string:)).map(CraftHybridRoutes.appPath(of:)) ?? "/"
         if startPath.isEmpty { startPath = "/" }
-        let wanted = config.renderer == "web" && !routes.isEmpty
+        let wanted = !routes.isEmpty
         if wanted && Self.bundleURL == nil {
-            NSLog("[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; every path opens in the web view")
+            NSLog(hasWeb
+                ? "[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; every path opens in the web view"
+                : "[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; the app has no screens to show")
         }
         isEnabled = wanted && Self.bundleURL != nil
+        if isEnabled, !hasWeb, routes.match(startPath) == nil {
+            // No web view to show it in: the first tab a screen draws.
+            let fallback = (config.tabs ?? []).map(\.id).first { routes.match($0) != nil }
+            NSLog("[craft hybrid] no native screen draws the start path %@ and there is no web view; starting on %@", startPath, fallback ?? "nothing")
+            if let fallback { startPath = fallback }
+        }
         startsNative = isEnabled && routes.match(startPath) != nil
-        CraftChrome.shared.configure(tabs: config.tabs ?? [], selected: tabIds(from: config.tabs ?? []).isEmpty ? nil : CraftHybridRoutes.tab(owning: startPath, among: tabIds(from: config.tabs ?? [])), splash: !startsNative)
+        // The splash waits for a page; an all-native app's first screen draws itself.
+        CraftChrome.shared.configure(tabs: config.tabs ?? [], selected: tabIds(from: config.tabs ?? []).isEmpty ? nil : CraftHybridRoutes.tab(owning: startPath, among: tabIds(from: config.tabs ?? [])), splash: hasWeb && !startsNative)
+
+        let script = config.nativeApp.flatMap { $0.isEmpty ? nil : $0 }
+        appScriptRoute = script != nil && Self.bundleURL != nil && (isEnabled || !hasWeb) ? script : nil
+        if let script, appScriptRoute == nil {
+            NSLog("[craft hybrid] nativeApp %@ does not run: it needs dist/native-screen.js, and nativeScreens or renderer \"native\"", script)
+        }
+        CraftEventManager.shared.configure(appScript: appScriptRoute != nil, page: hasWeb)
+
+        if !hasWeb && services == nil {
+            let coordinator = CraftWebView.Coordinator(config: config)
+            services = coordinator
+            CraftSwiftShim.coordinator = coordinator
+        }
+
+        guard appScriptRoute != nil else { return }
+        // It starts after the first frame (`nativeScreenDidRender`), or as
+        // soon as background work waits for it (`backgroundWorkWaiting`).
+        // This is for the rest: a first screen that is the page's, one that
+        // never draws, a launch in the background with nothing to draw.
+        // (`applicationState` cannot tell those apart here: a scene-based app
+        // is `.background` during launch however it was opened.)
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) { self.startAppScript() }
+    }
+
+    /// A silent push or a background refresh is waiting for the app script,
+    /// with iOS's clock running: it starts now rather than after a frame,
+    /// which a launch in the background never draws.
+    func backgroundWorkWaiting() {
+        guard appScriptRoute != nil, appScript == nil else { return }
+        DispatchQueue.main.async { self.startAppScript() }
+    }
+
+    /// The app script: loaded once, off screen, and kept. Started after the
+    /// first frame is committed, so it never delays it, or at once when
+    /// background work is waiting for it. Its `craft.navigation.open` comes here
+    /// (`nativeScreen(_:open:)`), and so to the shell.
+    func startAppScript() {
+        guard appScript == nil, let route = appScriptRoute else { return }
+        let script = CraftNativeScreenController(config: config, routeName: route, isAppScript: true)
+        script.hybridEvents = self
+        appScript = script
+        script.loadViewIfNeeded()
+        #if DEBUG
+        NSLog("[craft hybrid] app script %@ is running", route)
+        #endif
+    }
+
+    /// The shell is up: what waited for it.
+    func shellReady() {
+        guard let controller else { return }
+        let waiting = untilShell
+        untilShell.removeAll()
+        for work in waiting { work(controller) }
+    }
+
+    /// A path or a web address opened by the app script or a single-stack
+    /// screen: the shell opens it (holding it until the shell exists); an app
+    /// with no shell opens a web address in the in-app browser.
+    func open(_ path: String) {
+        if let controller {
+            controller.open(path)
+        } else if isEnabled {
+            untilShell.append { $0.open(path) }
+        } else {
+            openOutside(path)
+        }
+    }
+
+    /// A path no native screen draws, in an app with no web view, or an
+    /// address on another site: the in-app browser.
+    func openOutside(_ raw: String) {
+        guard let url = CraftHybridRoutes.siteURL(for: raw, site: siteURL) else {
+            NSLog("[craft hybrid] %@ has no native screen, and the app has no site (devServerURL) to open it on", raw)
+            return
+        }
+        CraftBrowser.shared.open(url, mode: "safari", callbackScheme: nil, from: nil) { _ in }
     }
 
     private func tabIds(from tabs: [CraftConfig.Tab]) -> [String] { tabs.map(\.id) }
@@ -303,8 +460,10 @@ final class CraftHybrid: NSObject {
         return shown.isEmpty ? (config.tabs ?? []).map(\.id) : shown
     }
 
-    /// Whether the web view is what the person sees: always, outside hybrid.
+    /// Whether the web view is what the person sees: always in a web app
+    /// outside hybrid, never in an app with no web view.
     var webIsVisible: Bool {
+        guard hasWeb else { return false }
         guard isEnabled else { return true }
         return controller?.webIsVisible ?? !startsNative
     }
@@ -631,11 +790,7 @@ final class CraftHybrid: NSObject {
         case .snapshotRemove(let name):
             CraftSnapshots.write(name, json: nil)
         case .snapshotClear:
-            let names = CraftSnapshots.directory
-                .flatMap { try? FileManager.default.contentsOfDirectory(atPath: $0.path) }?
-                .filter { $0.hasSuffix(".json") }
-                .map { String($0.dropLast(5)) } ?? []
-            for name in names { CraftSnapshots.write(name, json: nil) }
+            CraftSnapshots.clear()
         case .shareStorage(let key, let value):
             guard let nativeKey = config.shareStorage?[key] else { return }
             // The page's own write, or its echo of one a native screen made.
@@ -675,12 +830,26 @@ final class CraftHybrid: NSObject {
         controller?.pageSelectedTab(id)
     }
 
-    /// A deep link to a native path opens the native screen; true when it did.
+    /// A deep link to a native path opens the native screen; in an app with
+    /// no web view, a link to its own site that no screen draws opens in the
+    /// in-app browser. True when the shell took it.
     func handleDeepLink(_ url: URL) -> Bool {
-        guard isEnabled, let controller else { return false }
+        guard isEnabled else { return false }
         let path = CraftHybridRoutes.appPath(of: url)
-        guard routes.match(path) != nil else { return false }
-        controller.showNative(path: path, replace: false, fromLink: true)
+        let native = routes.match(path) != nil
+        let browse = !native && !hasWeb && CraftHybridRoutes.isSite(url, site: siteURL)
+        guard native || browse else { return false }
+        let show: (CraftHybridController) -> Void = { [weak self] controller in
+            if native { controller.showNative(path: path, replace: false, fromLink: true) } else { self?.openOutside(url.absoluteString) }
+        }
+        guard let controller else {
+            // Before the shell: a hybrid app's page has it; an all-native app
+            // opens it once the shell is up (a link that launched the app).
+            guard !hasWeb else { return false }
+            untilShell.append(show)
+            return true
+        }
+        show(controller)
         return true
     }
 
@@ -702,6 +871,7 @@ final class CraftHybrid: NSObject {
             answered = true
             completion(depth)
         }
+        guard hasWeb else { answer(nil); return }
         guard let webView, pageReady, let scheme = webView.url?.scheme, scheme == "http" || scheme == "https" else {
             CraftSwiftShim.coordinator?.loadAppPath(path)
             answer(nil)
@@ -719,20 +889,43 @@ final class CraftHybrid: NSObject {
     }
 
     func setPageBase(_ depth: Int?) {
+        guard hasWeb else { return }
         let value = depth.map(String.init) ?? "null"
         webView?.evaluateJavaScript("window.__craftHybrid && window.__craftHybrid.setBase(\(value))", completionHandler: nil)
     }
 
     func pageReset(to path: String) {
-        guard let data = try? JSONSerialization.data(withJSONObject: [path]), let json = String(data: data, encoding: .utf8) else { return }
+        guard hasWeb, let data = try? JSONSerialization.data(withJSONObject: [path]), let json = String(data: data, encoding: .utf8) else { return }
         webView?.evaluateJavaScript("window.__craftHybrid && window.__craftHybrid.reset && window.__craftHybrid.reset(\(json)[0])", completionHandler: nil)
     }
 
     func pageBack(to depth: Int) {
+        guard hasWeb else { return }
         webView?.evaluateJavaScript("window.__craftHybrid && window.__craftHybrid.backTo(\(max(0, depth)))", completionHandler: nil)
     }
 }
 
+/// What the app script and a single-stack native app's screens tell the shell.
+extension CraftHybrid: CraftHybridScreenEvents {
+    /// A single-stack app's first frame: the app script starts once it is
+    /// committed. (The routed shell's controller does the same for its own.)
+    func nativeScreenDidRender(_ screen: CraftNativeScreenController) {
+        guard !firstFrameSeen else { return }
+        firstFrameSeen = true
+        CATransaction.setCompletionBlock { [weak self] in self?.startAppScript() }
+    }
+
+    /// The screen keeps its own error; the app script still runs.
+    func nativeScreen(_ screen: CraftNativeScreenController, didFail message: String) {
+        NSLog("[craft hybrid] the native screen could not draw its first frame: %@", message)
+        DispatchQueue.main.async { self.startAppScript() }
+    }
+
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String) {
+        open(path)
+    }
+}
+
 /// The page's `craftHybrid` channel, only from a trusted origin's main frame.
 final class CraftHybridRelay: NSObject, WKScriptMessageHandler {
     private let trusts: (WKSecurityOrigin) -> Bool
@@ -796,7 +989,8 @@ final class CraftHybridWebSlot: UIViewController {
 final class CraftHybridController: UIViewController, UINavigationControllerDelegate, UIGestureRecognizerDelegate, CraftHybridScreenEvents {
     private let config: CraftConfig
     private let hybrid = CraftHybrid.shared
-    private let webHost: UIHostingController<AnyView>
+    /// The web view's host; nil in an all-native app, which never makes one.
+    private let webHost: UIHostingController<AnyView>?
     /// Where the web view waits, behind the screens, while none of them is web.
     private let parking = UIView()
     private var stacks: [String: UINavigationController] = [:]
@@ -816,7 +1010,9 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         // Edge to edge, but not under the keyboard: the web view ends at its
         // top. Under it, WebKit scrolled the page's layout viewport to show a
         // focused field and carried every sticky header off the screen.
-        webHost = UIHostingController(rootView: AnyView(CraftWebView(config: config).ignoresSafeArea(.container)))
+        webHost = CraftHybrid.shared.hasWeb
+            ? UIHostingController(rootView: AnyView(CraftWebView(config: config).ignoresSafeArea(.container)))
+            : nil
         super.init(nibName: nil, bundle: nil)
         hybrid.controller = self
     }
@@ -831,21 +1027,25 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         view.addSubview(parking)
 
         // A native start screen draws first; the web view, whose creation
-        // costs a frame or more, starts loading straight after it.
-        if !hybrid.startsNative { attachWeb() }
+        // costs a frame or more, starts loading straight after it. An
+        // all-native app has none.
+        if hybrid.hasWeb && !hybrid.startsNative { attachWeb() }
         let tabs = hybrid.tabIds
         let start = CraftHybridRoutes.tab(owning: hybrid.startPath, among: tabs) ?? tabs.first ?? ""
         show(tab: start, rootPath: hybrid.startPath)
-        if hybrid.startsNative {
+        if hybrid.hasWeb && hybrid.startsNative {
             DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in self?.attachWeb() }
         }
+        // Links and opens that arrived before the shell, once the start
+        // screen is up.
+        DispatchQueue.main.async { [weak self] in self?.hybrid.shellReady() }
     }
 
     private var webAttached = false
 
     /// The web view joins the screen, behind the native screens, and loads.
     private func attachWeb() {
-        guard !webAttached else { return }
+        guard let webHost, !webAttached else { return }
         webAttached = true
         webHost.view.backgroundColor = config.resolvedBackgroundColor
         if #available(iOS 16.4, *) { webHost.safeAreaRegions = [.keyboard] }
@@ -859,6 +1059,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// The web view's controller is the child of whichever controller shows
     /// it: UIKit refuses a child's view in another controller's hierarchy.
     private func moveWeb(to owner: UIViewController, in container: UIView) {
+        guard let webHost else { return }
         if webHost.parent !== owner {
             if webHost.parent != nil {
                 webHost.willMove(toParent: nil)
@@ -888,7 +1089,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     private var visibleStack: UINavigationController? { stacks[currentTab] }
 
     var webIsVisible: Bool {
-        guard let slot = visibleStack?.topViewController as? CraftHybridWebSlot else { return false }
+        guard let webHost, let slot = visibleStack?.topViewController as? CraftHybridWebSlot else { return false }
         return webHost.view.superview === slot.view
     }
 
@@ -931,6 +1132,15 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             nativePaths[ObjectIdentifier(screen)] = match.path
             return screen
         }
+        guard hybrid.hasWeb else {
+            // The config checks rule this out (every tab and the start path
+            // are native screens); an empty screen rather than a web entry
+            // nothing would ever fill.
+            NSLog("[craft hybrid] no native screen draws %@, and the app has no web view", path)
+            let empty = UIViewController()
+            empty.view.backgroundColor = config.resolvedBackgroundColor
+            return empty
+        }
         return CraftHybridWebSlot(path: path, depth: depth, isTabRoot: isTabRoot)
     }
 
@@ -959,7 +1169,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     func adoptWeb(into slot: CraftHybridWebSlot) {
-        guard slot.navigationController === visibleStack || visibleStack == nil else { return }
+        guard let webHost, slot.navigationController === visibleStack || visibleStack == nil else { return }
         attachWeb()
         moveWeb(to: slot, in: slot.view)
         webHost.view.alpha = slot.awaitingPage ? 0 : 1
@@ -967,7 +1177,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     private func parkWeb() {
-        guard webAttached else { return }
+        guard webAttached, let webHost else { return }
         webHost.view.alpha = 1
         moveWeb(to: self, in: parking)
     }
@@ -975,8 +1185,19 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     // MARK: Opening paths
 
     /// `craft.navigation.open(path)` or `craft.hybrid.open(path)`: a tab, a
-    /// native screen, or the web view pushed over the screen that asked.
+    /// native screen, or the web view pushed over the screen that asked. In
+    /// an app with no web view, a path no screen draws opens in the in-app
+    /// browser on the app's site. A web address on the app's site is its
+    /// path; one anywhere else opens in the in-app browser.
     func open(_ raw: String) {
+        if let url = URL(string: raw), let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" {
+            guard CraftHybridRoutes.isSite(url, site: hybrid.siteURL) else {
+                hybrid.openOutside(raw)
+                return
+            }
+            open(CraftHybridRoutes.appPath(of: url))
+            return
+        }
         guard let path = CraftHybridRoutes.normalize(raw) else { return }
         if let tab = hybrid.tabIds.first(where: { CraftHybridRoutes.normalize($0) == path }) {
             selectTabAsIfTapped(tab)
@@ -986,7 +1207,11 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             showNative(path: raw, replace: false)
             return
         }
-        pushWeb(raw)
+        if hybrid.hasWeb {
+            pushWeb(raw)
+        } else {
+            hybrid.openOutside(raw)
+        }
     }
 
     private func selectTabAsIfTapped(_ id: String) {
@@ -1035,7 +1260,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// The web view, pushed: the page goes to `path` first, without its own
     /// slide, then the entry slides in over the screen that opened it.
     private func pushWeb(_ path: String) {
-        guard !openingWeb, let nav = visibleStack else { return }
+        guard hybrid.hasWeb, !openingWeb, let nav = visibleStack else { return }
         openingWeb = true
         hybrid.navigatePage(path) { [weak self, weak nav] depth in
             guard let self else { return }
@@ -1056,8 +1281,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     private func reveal(_ slot: CraftHybridWebSlot) {
         slot.awaitingPage = false
-        guard webHost.view.superview === slot.view else { return }
-        UIView.animate(withDuration: 0.15) { self.webHost.view.alpha = 1 }
+        guard let webHost, webHost.view.superview === slot.view else { return }
+        UIView.animate(withDuration: 0.15) { webHost.view.alpha = 1 }
     }
 
     /// Back from the web entry on top, as the page's Back at that entry asks.
@@ -1113,6 +1338,11 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             // then its own first screen).
             return nav.topViewController is CraftHybridWebSlot
         }
+        // No page to wait for: the tab's own stack, now.
+        guard hybrid.hasWeb else {
+            show(tab: id)
+            return true
+        }
         let target = stacks[id]
         let rootIsWeb = target.map { $0.topViewController is CraftHybridWebSlot } ?? (hybrid.routes.match(id) == nil)
         let pageThere = hybrid.pagePath.flatMap { CraftHybridRoutes.tab(owning: $0, among: hybrid.tabIds) } == id
@@ -1265,12 +1495,20 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         CATransaction.setCompletionBlock { [weak self] in
             NSLog("[craft hybrid] native first frame %@", path)
             self?.attachWeb()
+            // The app script after the first frame, never before it.
+            self?.hybrid.startAppScript()
         }
         CraftChrome.shared.hideSplash()
     }
 
     func nativeScreen(_ screen: CraftNativeScreenController, didFail message: String) {
         let path = nativePaths[ObjectIdentifier(screen)] ?? hybrid.startPath
+        guard hybrid.hasWeb else {
+            // No web view to open it in: the screen keeps its own error.
+            NSLog("[craft hybrid] native screen for %@ failed (%@); the app has no web view to open it in", path, message)
+            if !firstFrameLogged { DispatchQueue.main.async { [weak self] in self?.hybrid.startAppScript() } }
+            return
+        }
         NSLog("[craft hybrid] native screen for %@ failed (%@); opening it in the web view", path, message)
         DispatchQueue.main.async { [weak self, weak screen] in
             guard let self, let screen, let nav = screen.navigationController else { return }

package/dist/ios/templates/CraftNativeActions.swift

@@ -57,10 +57,14 @@ enum CraftNativeActions {
         values.append(contentsOf: ["brightness", "statusBar"])
         if config.enableKeepAwake { values.append("keepAwake") }
         // GPS and the route recording are the web view's coordinator's
-        // (CraftWebServices), so a native-only app, which has none, has none.
-        if config.enableGeolocation && config.renderer != "native" { values.append("geolocation") }
+        // (CraftWebServices); an app with no web view has the coordinator
+        // all the same (CraftHybrid.configure).
+        if config.enableGeolocation { values.append("geolocation") }
         // The Music app's song and transport are the coordinator's too.
-        if config.enableAppleMusic && config.renderer != "native" { values.append("music") }
+        if config.enableAppleMusic { values.append("music") }
+        // `craft.background.complete(ok, id)`: the answer to a silent push or
+        // a background refresh, which the app script (`nativeApp`) hears.
+        if config.backgroundRefresh?.enabled == true || config.enablePushNotifications { values.append("background") }
         // A heart-rate strap is the app's own service (CraftHeartRate.swift),
         // so it needs no web view.
         if config.enableHeartRate { values.append("heartRate") }
@@ -407,6 +411,21 @@ enum CraftNativeActions {
                 complete(requestToken, failure("UNKNOWN_ACTION", "Unsupported Push method"), completion)
             }
             return
+        case ("Background", "complete"):
+            // The app script's answer to `craftSilentPush` or
+            // `craftBackgroundRefresh`: args `[ok, id?]`, with no id for
+            // everything still pending, as a page's `craft.background.complete`.
+            guard config.backgroundRefresh?.enabled == true || config.enablePushNotifications else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Background work is disabled"), completion)
+                return
+            }
+            let ok = args.first as? Bool ?? true
+            let id = args.count > 1 ? args[1] as? String : nil
+            DispatchQueue.main.async {
+                CraftBackgroundWork.shared.complete(id: id, ok: ok)
+                complete(requestToken, .success(true), completion)
+            }
+            return
         case ("Notifications", _):
             guard config.enableLocalNotifications else {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Local notifications are disabled"), completion)
@@ -1081,6 +1100,41 @@ enum CraftSnapshots {
             }
         }
     }
+
+    /// Every snapshot there is: on disk, and written but not on disk yet.
+    static func names() -> [String] {
+        var names = Set(directory
+            .flatMap { try? FileManager.default.contentsOfDirectory(atPath: $0.path) }?
+            .filter { $0.hasSuffix(".json") }
+            .map { String($0.dropLast(5)) } ?? [])
+        lock.lock()
+        for (name, json) in pending {
+            if json == nil { names.remove(name) } else { names.insert(name) }
+        }
+        lock.unlock()
+        return names.filter(isValidName).sorted()
+    }
+
+    /// Deletes every snapshot but the ones named in `keep` (a sign-out), each
+    /// as `write(name, json: nil)` does, so each posts `changed`.
+    /// `completion` runs on the main queue: true when every one went.
+    static func clear(keeping keep: Set<String> = [], completion: ((Bool) -> Void)? = nil) {
+        let doomed = names().filter { !keep.contains($0) }
+        guard !doomed.isEmpty else {
+            DispatchQueue.main.async { completion?(true) }
+            return
+        }
+        let group = DispatchGroup()
+        var allRemoved = true
+        for name in doomed {
+            group.enter()
+            write(name, json: nil) { ok in
+                if !ok { allRemoved = false }
+                group.leave()
+            }
+        }
+        group.notify(queue: .main) { completion?(allRemoved) }
+    }
 }
 
 /// The Taptic Engine's generators, held for the life of the process.

package/dist/ios/templates/CraftNativeScreen.swift

@@ -367,7 +367,12 @@ struct CraftNativeScreen: UIViewControllerRepresentable {
     let config: CraftConfig
 
     func makeUIViewController(context: Context) -> UINavigationController {
-        UINavigationController(rootViewController: CraftNativeScreenController(config: config))
+        let screen = CraftNativeScreenController(config: config)
+        // The shell hears the first frame (the app script starts after it)
+        // and `craft.navigation.open`, which has no paths to open here but
+        // web addresses, in the in-app browser.
+        screen.hybridEvents = CraftHybrid.shared
+        return UINavigationController(rootViewController: screen)
     }
 
     func updateUIViewController(_ controller: UINavigationController, context: Context) {}
@@ -2086,11 +2091,17 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     weak var hybridEvents: CraftHybridScreenEvents?
     private var hybridRendered = false
     private var runtimeDisposed = false
+    /// The app script (`nativeApp`, CraftHybrid.swift): a bundle route with
+    /// no screen, loaded once and never shown, that runs for the app's life.
+    /// It hears every `APP_STATE` and the app's events (`CRAFT_EVENT`), no
+    /// `DEEP_LINK`; it can open paths but not push, pop or style a bar.
+    let isAppScript: Bool
 
-    init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:]) {
+    init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:], isAppScript: Bool = false) {
         self.config = config
         self.routeName = routeName
         self.routeParams = routeParams
+        self.isAppScript = isAppScript
         super.init(nibName: nil, bundle: nil)
     }
 
@@ -2127,6 +2138,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         setupJavaScript()
         loadBundle()
         observeNativeEvents()
+        if isAppScript {
+            // Its bundle has run, so its listeners are in place: the app's
+            // events that waited for it arrive now, in order.
+            CraftEventManager.shared.appScriptReady { [weak self] event, detail in
+                self?.send(type: "CRAFT_EVENT", payload: ["event": event, "detail": detail])
+            }
+        }
     }
 
     override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
@@ -2280,6 +2298,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let capabilities = CraftNativeActions.capabilities(config: config)
         let capabilityData = try? JSONSerialization.data(withJSONObject: capabilities)
         let capabilityJSON = capabilityData.flatMap { String(data: $0, encoding: .utf8) } ?? "[]"
+        // The app's site and build, as JSON strings: the site an all-native
+        // app's paths and links belong to (`devServerURL`), and the version a
+        // request or a crash report names.
+        let info = Bundle.main.infoDictionary
+        let appURL = Self.jsonString(config.devServerURL ?? "")
+        let appVersion = Self.jsonString(info?["CFBundleShortVersionString"] as? String ?? "")
+        let appBuild = Self.jsonString(info?["CFBundleVersion"] as? String ?? "")
         jsContext.evaluateScript("""
             globalThis.__stxNativeCallback = null;
             globalThis.__stxNativeBridge = {
@@ -2290,6 +2315,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 capabilities: \(capabilityJSON),
                 initialAppState: "\(CraftNativeActions.currentAppState())",
                 colorScheme: "\(colorScheme)",
+                appURL: \(appURL),
+                appVersion: \(appVersion),
+                appBuild: \(appBuild),
                 postMessage: function(message) { craftNativePostMessage(message); },
                 onMessage: function(callback) { globalThis.__stxNativeCallback = callback; }
             };
@@ -2350,6 +2378,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         """)
     }
 
+    /// `value` as a JavaScript string literal (JSON), quotes and all.
+    static func jsonString(_ value: String) -> String {
+        guard let data = try? JSONSerialization.data(withJSONObject: [value]),
+              let array = String(data: data, encoding: .utf8), array.count >= 2 else { return "\"\"" }
+        return String(array.dropFirst().dropLast())
+    }
+
     /// `"dark"` or `"light"` for the bundle's `dark:` classes (contract A4):
     /// the window's appearance once there is one, else the app's setting.
     private var colorScheme: String {
@@ -2379,6 +2414,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     ///   asynchronous `craft.storage` uses. `getSync` answers what `get` would.
     /// - `craft.snapshots.get(name)` (sync) and `set(name, value)` (a
     ///   promise): `Application Support/craft-snapshots/<name>.json`.
+    ///   `clear(keep?)` (a promise) deletes every snapshot but the names in
+    ///   `keep`, as a sign-out does; each removal is a `SNAPSHOT_CHANGED`
+    ///   for every screen.
     /// - `craft.secureStorage.getSync(key)`: the Keychain item the web page's
     ///   `craft.secureStorage.set` wrote.
     /// - `craft.navigation.setOptions({ title, largeTitle, hidden, backTitle,
@@ -2405,6 +2443,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 done.call(withArguments: [ok])
             }
         }
+        let snapshotClear: @convention(block) (JSValue, JSValue) -> Void = { keep, done in
+            let names = (keep.isUndefined || keep.isNull ? [] : (keep.toArray() ?? [])).compactMap { $0 as? String }
+            CraftSnapshots.clear(keeping: Set(names)) { ok in
+                done.call(withArguments: [ok])
+            }
+        }
         let config = self.config
         let secureGet: @convention(block) (String) -> String? = { key in
             config.enableSecureStorage ? CraftNativeActions.webSecureValue(forKey: key) : nil
@@ -2419,6 +2463,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         jsContext.setObject(storageSet, forKeyedSubscript: "craftNativeStorageSet" as NSString)
         jsContext.setObject(snapshotGet, forKeyedSubscript: "craftNativeSnapshotGet" as NSString)
         jsContext.setObject(snapshotSet, forKeyedSubscript: "craftNativeSnapshotSet" as NSString)
+        jsContext.setObject(snapshotClear, forKeyedSubscript: "craftNativeSnapshotClear" as NSString)
         jsContext.setObject(secureGet, forKeyedSubscript: "craftNativeSecureGet" as NSString)
         jsContext.setObject(setOptions, forKeyedSubscript: "craftNativeSetOptions" as NSString)
         // `AudioContext` and the rest of Web Audio, rendered natively.
@@ -2568,6 +2613,16 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                                 else reject(new Error('craft.snapshots.set could not write ' + name));
                             });
                         });
+                    },
+                    // Every snapshot but the names in `keep` (a sign-out).
+                    clear: function(keep) {
+                        var names = Array.isArray(keep) ? keep.map(String) : [];
+                        return new Promise(function(resolve, reject) {
+                            craftNativeSnapshotClear(names, function(ok) {
+                                if (ok) resolve();
+                                else reject(new Error('craft.snapshots.clear could not remove every snapshot'));
+                            });
+                        });
                     }
                 });
                 keep('secureStorage', {
@@ -2623,6 +2678,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// `craft.navigation.setOptions`: this screen's bar. Every key is
     /// optional and only the keys given change.
     private func applyNavigationOptions(_ options: [String: Any]) {
+        // The app script has no screen, so no bar and no tab bar to change.
+        guard !isAppScript else { return }
         if options.keys.contains("title") {
             navigationItem.title = options["title"] as? String
             titleFromOptions = true
@@ -2826,20 +2883,23 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         observe(UIApplication.didBecomeActiveNotification, state: "active")
         observe(UIApplication.willResignActiveNotification, state: "inactive")
         observe(UIApplication.didEnterBackgroundNotification, state: "background")
-        lifecycleObservers.append(NotificationCenter.default.addObserver(
-            forName: UIResponder.keyboardWillChangeFrameNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] notification in
-            self?.applyKeyboardSafeArea(notification)
-        })
-        lifecycleObservers.append(NotificationCenter.default.addObserver(
-            forName: UIResponder.keyboardWillHideNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] notification in
-            self?.applyKeyboardSafeArea(notification, hidden: true)
-        })
+        // The app script has no screen for the keyboard to cover.
+        if !isAppScript {
+            lifecycleObservers.append(NotificationCenter.default.addObserver(
+                forName: UIResponder.keyboardWillChangeFrameNotification,
+                object: nil,
+                queue: .main
+            ) { [weak self] notification in
+                self?.applyKeyboardSafeArea(notification)
+            })
+            lifecycleObservers.append(NotificationCenter.default.addObserver(
+                forName: UIResponder.keyboardWillHideNotification,
+                object: nil,
+                queue: .main
+            ) { [weak self] notification in
+                self?.applyKeyboardSafeArea(notification, hidden: true)
+            })
+        }
         lifecycleObservers.append(NotificationCenter.default.addObserver(
             forName: CraftSnapshots.changed,
             object: nil,
@@ -2873,6 +2933,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         sounds.emit = { [weak self] payload in self?.send(type: "SOUND_EVENT", payload: payload) }
         streams.emit = { [weak self] payload in self?.send(type: "NETWORK_STREAM", payload: payload) }
         sendAppState(CraftNativeActions.currentAppState())
+        // Links are the screens' to show; the app script hears none.
+        guard !isAppScript else { return }
         deepLinkListener = DeepLinkManager.shared.addNativeListener { [weak self] url, initial in
             guard let self = self, self.navigationController?.topViewController === self else { return }
             var payload = CraftNativeActions.deepLinkData(url)
@@ -2952,7 +3014,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func sendAppState(_ state: String) {
-        guard navigationController?.topViewController === self else { return }
+        // A screen hears it while it is on top of its stack; the app script,
+        // which is on no stack, always.
+        guard isAppScript || navigationController?.topViewController === self else { return }
         send(type: "APP_STATE", payload: ["state": state])
     }
 
@@ -2972,6 +3036,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// is up, and are logged.
     private func hybridFailed(_ message: String) {
         guard !hybridRendered else { return }
+        // The app script draws nothing for anything to stand in for: logged
+        // (by the caller) and left to run on.
+        guard !isAppScript else { return }
         hybridEvents?.nativeScreen(self, didFail: message)
     }
 
@@ -3014,7 +3081,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 ])
             }
         case "NAVIGATE", "NAVIGATE_REPLACE":
-            guard navigationController?.topViewController === self,
+            // A screen's own stack; the app script has none (it opens paths).
+            guard !isAppScript, navigationController?.topViewController === self,
                   let screen = payload["screen"] as? String, !screen.isEmpty,
                   let navigation = navigationController else { return }
             let params = payload["params"] as? [String: Any] ?? [:]
@@ -3034,13 +3102,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             guard let path = payload["path"] as? String, !path.isEmpty else { return }
             hybridEvents?.nativeScreen(self, open: path)
         case "NAVIGATE_BACK":
-            if navigationController?.topViewController === self {
+            if !isAppScript, navigationController?.topViewController === self {
                 navigationController?.popViewController(animated: true)
             }
         case "NAVIGATE_POP_TO_ROOT":
             // Back to the first screen of this screen's stack in one move: a
             // finished task (a saved workout) closes the way it was reached.
-            if navigationController?.topViewController === self {
+            if !isAppScript, navigationController?.topViewController === self {
                 navigationController?.popToRootViewController(animated: true)
             }
         case "API_REQUEST":
@@ -3181,7 +3249,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         renderCommitted(document)
         if !hybridRendered {
             hybridRendered = true
-            hybridEvents?.nativeScreenDidRender(self)
+            // The app script's drawing is never on screen: not a first frame.
+            if !isAppScript { hybridEvents?.nativeScreenDidRender(self) }
         }
     }
 

package/package.json

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