@craft-native/ios 0.0.155 → 0.0.156

package/dist/cli.js

@@ -39,14 +39,88 @@ function normalizeNativePath(raw) {
 function routeSegments(path) {
   return path === "/" ? [] : path.slice(1).split("/");
 }
+function matchNativePath(nativeScreens, raw) {
+  const path = normalizeNativePath(raw);
+  if (path === null)
+    return null;
+  const routes = Object.entries(nativeScreens ?? {}).map(([pattern, screen]) => ({ pattern: normalizeNativePath(pattern), screen })).filter((route) => route.pattern !== null && !!route.screen).map((route) => ({ ...route, segments: routeSegments(route.pattern) }));
+  const wild = (segments) => segments.at(-1) === "*" ? 1 : 0;
+  const fixed = (segments) => segments.filter((s) => s !== "*" && !s.startsWith(":")).length;
+  routes.sort((a, b) => wild(a.segments) - wild(b.segments) || fixed(b.segments) - fixed(a.segments) || b.segments.length - a.segments.length || (a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0));
+  const decode = (value) => {
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+  const parts = routeSegments(path);
+  for (const route of routes) {
+    const params = {};
+    let matched = true;
+    for (let i = 0;i < route.segments.length; i++) {
+      const segment = route.segments[i];
+      if (segment === "*") {
+        params["*"] = parts.slice(i).join("/");
+        break;
+      }
+      if (i >= parts.length) {
+        matched = false;
+        break;
+      }
+      if (segment.startsWith(":")) {
+        if (!parts[i]) {
+          matched = false;
+          break;
+        }
+        params[segment.slice(1)] = decode(parts[i]);
+      } else if (segment !== parts[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (!matched)
+      continue;
+    if (route.segments.at(-1) !== "*" && route.segments.length !== parts.length)
+      continue;
+    const query = raw.indexOf("?");
+    if (query >= 0) {
+      for (const item of raw.slice(query + 1).split("#")[0].split("&")) {
+        if (!item)
+          continue;
+        const [rawKey = "", ...rest] = item.split("=");
+        const key = decode(rawKey);
+        if (!key || key in params)
+          continue;
+        params[key] = decode(rest.join("=").replace(/\+/g, " "));
+      }
+    }
+    return { path, screen: route.screen, params };
+  }
+  return null;
+}
 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.`);
@@ -68,6 +142,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) {
@@ -854,11 +943,13 @@ ${nativeDependencies.join(`
     writeFileSync(join2(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
   writeFileSync(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("");
@@ -890,11 +981,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.");
     }

package/dist/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/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/package.json

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

package/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) (