@craft-native/ios 0.0.154 → 0.0.156

package/dist/cli.js

@@ -6,12 +6,18 @@ import { parseArgs } from "util";
 
 // src/index.ts
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { dirname as dirname2, join as join2, resolve } from "path";
 var {$ } = globalThis.Bun;
-var TEMPLATES_DIR = join(dirname(import.meta.dir), "templates");
+
+// src/testing.ts
+import { dirname, join } from "path";
+var templates = join(dirname(import.meta.dir), "templates/testing");
+
+// src/index.ts
+var TEMPLATES_DIR = join2(dirname2(import.meta.dir), "templates");
 var CRAFT_VERSION = (() => {
   try {
-    return JSON.parse(readFileSync(join(dirname(import.meta.dir), "package.json"), "utf8")).version ?? "0.0.0";
+    return JSON.parse(readFileSync(join2(dirname2(import.meta.dir), "package.json"), "utf8")).version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
@@ -33,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.`);
@@ -62,13 +142,28 @@ 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) {
   if (!existsSync(source))
     throw new Error(`Native bundle not found: ${source}`);
-  const destination = join(output, "dist", "native-screen.js");
-  mkdirSync(dirname(destination), { recursive: true });
+  const destination = join2(output, "dist", "native-screen.js");
+  mkdirSync(dirname2(destination), { recursive: true });
   if (resolve(source) !== resolve(destination))
     cpSync(source, destination);
 }
@@ -432,20 +527,20 @@ function writeOpaqueIcon(source, target) {
   }
 }
 function renderAssetCatalog(output, config) {
-  const catalog = join(output, "Assets.xcassets");
-  const appIcon = join(catalog, "AppIcon.appiconset");
-  const launchBackground = join(catalog, "LaunchBackground.colorset");
+  const catalog = join2(output, "Assets.xcassets");
+  const appIcon = join2(catalog, "AppIcon.appiconset");
+  const launchBackground = join2(catalog, "LaunchBackground.colorset");
   mkdirSync(appIcon, { recursive: true });
   mkdirSync(launchBackground, { recursive: true });
-  writeFileSync(join(catalog, "Contents.json"), `${JSON.stringify({ info: { author: "xcode", version: 1 } }, null, 2)}
+  writeFileSync(join2(catalog, "Contents.json"), `${JSON.stringify({ info: { author: "xcode", version: 1 } }, null, 2)}
 `);
   const iconFilename = config.appIconPath ? "AppIcon-1024.png" : undefined;
   if (config.appIconPath) {
     if (!existsSync(config.appIconPath))
       throw new Error(`App icon not found: ${config.appIconPath}`);
-    writeOpaqueIcon(config.appIconPath, join(appIcon, iconFilename));
+    writeOpaqueIcon(config.appIconPath, join2(appIcon, iconFilename));
   }
-  writeFileSync(join(appIcon, "Contents.json"), `${JSON.stringify({
+  writeFileSync(join2(appIcon, "Contents.json"), `${JSON.stringify({
     images: iconFilename ? [{
       filename: iconFilename,
       idiom: "universal",
@@ -472,7 +567,7 @@ function renderAssetCatalog(output, config) {
       idiom: "universal"
     });
   }
-  writeFileSync(join(launchBackground, "Contents.json"), `${JSON.stringify({
+  writeFileSync(join2(launchBackground, "Contents.json"), `${JSON.stringify({
     colors,
     info: { author: "xcode", version: 1 }
   }, null, 2)}
@@ -481,7 +576,7 @@ function renderAssetCatalog(output, config) {
 }
 var LAUNCH_LOGO = "LaunchLogo";
 function renderLaunchLogo(catalog, config) {
-  const imageset = join(catalog, `${LAUNCH_LOGO}.imageset`);
+  const imageset = join2(catalog, `${LAUNCH_LOGO}.imageset`);
   rmSync(imageset, { recursive: true, force: true });
   if (!config.splashImagePath)
     return;
@@ -497,14 +592,14 @@ function renderLaunchLogo(catalog, config) {
     if (extension === "svg" || extension === "pdf")
       vector = true;
     const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
-    cpSync(source, join(imageset, filename));
+    cpSync(source, join2(imageset, filename));
     images.push({
       ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
       filename,
       idiom: "universal"
     });
   }
-  writeFileSync(join(imageset, "Contents.json"), `${JSON.stringify({
+  writeFileSync(join2(imageset, "Contents.json"), `${JSON.stringify({
     images,
     info: { author: "xcode", version: 1 },
     ...vector ? { properties: { "preserves-vector-representation": true } } : {}
@@ -618,15 +713,15 @@ function syncWebAssets(source, output) {
   const sourcePath = resolve(source);
   if (!existsSync(sourcePath))
     throw new Error(`Web asset path not found: ${source}`);
-  const distDir = join(output, "dist");
+  const distDir = join2(output, "dist");
   rmSync(distDir, { recursive: true, force: true });
   mkdirSync(distDir, { recursive: true });
   if (statSync(sourcePath).isDirectory()) {
     cpSync(sourcePath, distDir, { recursive: true });
   } else {
-    cpSync(sourcePath, join(distDir, "index.html"));
+    cpSync(sourcePath, join2(distDir, "index.html"));
   }
-  if (!existsSync(join(distDir, "index.html"))) {
+  if (!existsSync(join2(distDir, "index.html"))) {
     throw new Error(`Web asset directory must contain index.html: ${source}`);
   }
 }
@@ -648,32 +743,32 @@ var RUNTIME_ARCHIVES = {
 };
 async function installRuntime(output, runtimeDir) {
   const resolved = Object.entries(RUNTIME_ARCHIVES).map(([sdk, archives]) => {
-    const present = archives.filter((a) => existsSync(join(runtimeDir, a)));
+    const present = archives.filter((a) => existsSync(join2(runtimeDir, a)));
     if (present.length === 0) {
       throw new Error(`${runtimeDir} has none of ${archives.join(", ")}. ` + `Run \`zig build build-ios-all\` in packages/zig and point at its zig-out/lib.`);
     }
     return { sdk, archives, present };
   });
-  const dest = join(output, "Runtime");
+  const dest = join2(output, "Runtime");
   rmSync(dest, { recursive: true, force: true });
   for (const { sdk, archives, present } of resolved) {
-    const sdkDir = join(dest, sdk);
+    const sdkDir = join2(dest, sdk);
     mkdirSync(sdkDir, { recursive: true });
-    const target = join(sdkDir, "libcraft-ios.a");
+    const target = join2(sdkDir, "libcraft-ios.a");
     if (present.length === 1) {
       const missing = archives.filter((a) => !present.includes(a));
       if (missing.length > 0) {
         console.warn(`   \u26A0 ${sdk}: only ${present[0]} was found; ${missing.join(", ")} is missing. ` + `The generated project will not link on the other architecture.`);
       }
-      cpSync(join(runtimeDir, present[0]), target);
+      cpSync(join2(runtimeDir, present[0]), target);
     } else {
-      await $`lipo -create ${present.map((a) => join(runtimeDir, a))} -output ${target}`.quiet();
+      await $`lipo -create ${present.map((a) => join2(runtimeDir, a))} -output ${target}`.quiet();
     }
   }
   return true;
 }
 async function refreshRuntime(output, override) {
-  if (!existsSync(join(output, "Runtime")))
+  if (!existsSync(join2(output, "Runtime")))
     return;
   const dir = resolveRuntimeDir(override);
   if (!dir) {
@@ -690,6 +785,39 @@ function productName(name) {
     return "Craft";
   return /^\d/.test(joined) ? `App${joined}` : joined;
 }
+function writeShell(output, config) {
+  if (!config.appName || !/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(config.bundleId))
+    throw new Error("The iOS shell needs an appName and a valid bundleId in craft.config.json.");
+  const name = productName(config.appName);
+  mkdirSync(join2(output, "Sources"), { recursive: true });
+  mkdirSync(join2(output, "Shared"), { recursive: true });
+  const swiftTemplate = readFileSync(join2(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
+  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, config.bundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
+  writeFileSync(join2(output, "Sources", `${name}App.swift`), swiftSource);
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeScreen.swift"), join2(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join2(output, "Sources", "CraftNativeFlatList.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeActions.swift"), join2(output, "Sources", "CraftNativeActions.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHealth.swift"), join2(output, "Sources", "CraftHealth.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftMusic.swift"), join2(output, "Sources", "CraftMusic.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHeartRate.swift"), join2(output, "Sources", "CraftHeartRate.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeMutation.swift"), join2(output, "Sources", "CraftNativeMutation.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeUI.swift"), join2(output, "Sources", "CraftNativeUI.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeServices.swift"), join2(output, "Sources", "CraftNativeServices.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeFiles.swift"), join2(output, "Sources", "CraftNativeFiles.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftWebAudio.swift"), join2(output, "Sources", "CraftWebAudio.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHybrid.swift"), join2(output, "Sources", "CraftHybrid.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftActivityAttributes.swift"), join2(output, "Shared", "CraftActivityAttributes.swift"));
+  for (const [enabled, folder, template, filename] of [
+    [config.enableLiveActivities, "WidgetExtension", "CraftLiveActivityWidget.swift.template", `${name}LiveActivity.swift`],
+    [config.enableWatchApp, "WatchExtension", "CraftWatchApp.swift.template", `${name}WatchApp.swift`]
+  ]) {
+    if (!enabled)
+      continue;
+    mkdirSync(join2(output, folder), { recursive: true });
+    const source = readFileSync(join2(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
+    writeFileSync(join2(output, folder, filename), source);
+  }
+}
 async function init(options) {
   const { name: displayName, bundleId, teamId, output } = options;
   const name = productName(displayName);
@@ -697,9 +825,9 @@ async function init(options) {
 \u26A1 Initializing Craft iOS project: ${displayName}`);
   console.log(`   Output: ${output}
 `);
-  const dirs = [output, join(output, "Sources"), join(output, "Shared"), join(output, "dist")];
+  const dirs = [output, join2(output, "Sources"), join2(output, "Shared"), join2(output, "dist")];
   if (options.config?.enableWatchApp)
-    dirs.push(join(output, "WatchApp"), join(output, "WatchExtension"));
+    dirs.push(join2(output, "WatchApp"), join2(output, "WatchExtension"));
   for (const dir of dirs) {
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
@@ -726,29 +854,15 @@ async function init(options) {
 `));
   if (Object.keys(config.shareStorage ?? {}).length)
     config.enableSecureStorage = true;
-  writeFileSync(join(output, "craft.config.json"), JSON.stringify(config, null, 2));
-  const swiftTemplate = readFileSync(join(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
-  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
-  writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
-  cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHealth.swift"), join(output, "Sources", "CraftHealth.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftMusic.swift"), join(output, "Sources", "CraftMusic.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHeartRate.swift"), join(output, "Sources", "CraftHeartRate.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeServices.swift"), join(output, "Sources", "CraftNativeServices.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeFiles.swift"), join(output, "Sources", "CraftNativeFiles.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftWebAudio.swift"), join(output, "Sources", "CraftWebAudio.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.swift"));
-  const infoPlistTemplate = readFileSync(join(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
+  writeFileSync(join2(output, "craft.config.json"), JSON.stringify(config, null, 2));
+  writeShell(output, config);
+  const infoPlistTemplate = readFileSync(join2(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
   const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{APP_BOUND_DOMAINS\}\}/g, renderAppBoundDomains(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{BACKGROUND_TASK_IDENTIFIERS\}\}/g, renderBackgroundTaskIdentifiers(config)).replace(/\{\{LAUNCH_SCREEN\}\}/g, renderLaunchScreen(config)).replace(/\{\{NON_EXEMPT_ENCRYPTION\}\}/g, config.usesNonExemptEncryption ? "true" : "false").replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");
-  writeFileSync(join(output, "Info.plist"), infoPlist);
-  const projectYmlTemplate = readFileSync(join(TEMPLATES_DIR, "project.yml.template"), "utf-8");
+  writeFileSync(join2(output, "Info.plist"), infoPlist);
+  const projectYmlTemplate = readFileSync(join2(TEMPLATES_DIR, "project.yml.template"), "utf-8");
   const nativeDependencies = [];
   if (config.enableLiveActivities)
     nativeDependencies.push(`      - target: ${name}LiveActivity`);
@@ -805,40 +919,37 @@ async function init(options) {
   if (hasRuntime) {
     console.log("   Linked the Zig runtime from", runtimeDir);
   } else {
-    rmSync(join(output, "Runtime"), { recursive: true, force: true });
+    rmSync(join2(output, "Runtime"), { recursive: true, force: true });
   }
   const projectYml = projectYmlTemplate.replace(/\{\{CRAFT_RUNTIME_SETTINGS\}\}/g, hasRuntime ? renderRuntimeSettings() : "").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{BUNDLE_ID_PREFIX\}\}/g, bundleIdPrefix).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{IOS_VERSION\}\}/g, config.iosVersion || "15.0").replace(/\{\{DEVICE_FAMILIES\}\}/g, renderDeviceFamilies(config)).replace(/\{\{TEAM_ID\}\}/g, teamId || "").replace(/\{\{NATIVE_DEPENDENCIES\}\}/g, nativeDependencies.length ? `    dependencies:
 ${nativeDependencies.join(`
 `)}` : "").replace(/\{\{NATIVE_TARGETS\}\}/g, nativeTargets.join(`
 `));
-  writeFileSync(join(output, "project.yml"), projectYml);
-  writeFileSync(join(output, "Craft.entitlements"), renderEntitlements(config));
-  writeFileSync(join(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
+  writeFileSync(join2(output, "project.yml"), projectYml);
+  writeFileSync(join2(output, "Craft.entitlements"), renderEntitlements(config));
+  writeFileSync(join2(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
   renderAssetCatalog(output, config);
-  cpSync(join(TEMPLATES_DIR, "CraftActivityAttributes.swift"), join(output, "Shared", "CraftActivityAttributes.swift"));
   if (config.enableLiveActivities) {
-    mkdirSync(join(output, "WidgetExtension"), { recursive: true });
-    const widgetSource = readFileSync(join(TEMPLATES_DIR, "CraftLiveActivityWidget.swift.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
-    writeFileSync(join(output, "WidgetExtension", `${name}LiveActivity.swift`), widgetSource);
-    const widgetInfo = readFileSync(join(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
-    writeFileSync(join(output, "WidgetExtension", "Info.plist"), widgetInfo);
+    mkdirSync(join2(output, "WidgetExtension"), { recursive: true });
+    const widgetInfo = readFileSync(join2(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
+    writeFileSync(join2(output, "WidgetExtension", "Info.plist"), widgetInfo);
   }
   if (config.enableWatchApp) {
-    const watchSource = readFileSync(join(TEMPLATES_DIR, "CraftWatchApp.swift.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
-    writeFileSync(join(output, "WatchExtension", `${name}WatchApp.swift`), watchSource);
-    const watchInfo = readFileSync(join(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
-    writeFileSync(join(output, "WatchApp", "Info.plist"), watchInfo);
-    writeFileSync(join(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync(join(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
-    writeFileSync(join(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
-    writeFileSync(join(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
+    const watchInfo = readFileSync(join2(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    writeFileSync(join2(output, "WatchApp", "Info.plist"), watchInfo);
+    writeFileSync(join2(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
+    const watchExtensionInfo = readFileSync(join2(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    writeFileSync(join2(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
+    writeFileSync(join2(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
-  writeFileSync(join(output, "dist", "index.html"), renderOfflinePage(config));
-  if (isHybrid(config)) {
+  writeFileSync(join2(output, "dist", "index.html"), renderOfflinePage(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("");
@@ -858,7 +969,7 @@ async function build(options) {
   const { htmlPath, nativeBundlePath, devServer, output, generateProject = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft iOS project...`);
-  const configPath = join(output, "craft.config.json");
+  const configPath = join2(output, "craft.config.json");
   if (!existsSync(configPath)) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft ios init' first.`);
   }
@@ -870,12 +981,10 @@ 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 = join(output, "dist", "native-screen.js");
-      if (resolve(nativeBundlePath) !== resolve(destination))
-        cpSync(nativeBundlePath, destination);
-    }
-    if (!existsSync(join(output, "dist", "native-screen.js"))) {
+    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.");
     }
   } else if (nativeBundlePath && !isHybrid(config)) {
@@ -901,7 +1010,7 @@ async function build(options) {
     if (bundle) {
       installNativeBundle(bundle, output);
       console.log(`   Native screens: ${bundle} \u2192 dist/native-screen.js`);
-    } else if (!existsSync(join(output, "dist", "native-screen.js"))) {
+    } else if (!existsSync(join2(output, "dist", "native-screen.js"))) {
       console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
     }
   }
@@ -931,7 +1040,7 @@ async function open(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}. Run 'craft ios build' first.`);
   }
-  const projectPath = join(output, xcodeproj);
+  const projectPath = join2(output, xcodeproj);
   console.log(`\uD83D\uDE80 Opening ${xcodeproj}...`);
   await $`open ${projectPath}`;
 }
@@ -972,7 +1081,7 @@ async function showSimulator() {
   const selected = await $`xcode-select -p`.quiet().nothrow();
   const developer = selected.exitCode === 0 ? selected.stdout.toString().trim() : "";
   if (developer) {
-    const app = join(developer, "Applications", "Simulator.app");
+    const app = join2(developer, "Applications", "Simulator.app");
     if (existsSync(app)) {
       await $`open ${app}`.quiet().nothrow();
       return;
@@ -988,9 +1097,9 @@ async function run(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}`);
   }
-  const projectPath = join(output, xcodeproj);
+  const projectPath = join2(output, xcodeproj);
   const appName = xcodeproj.replace(".xcodeproj", "");
-  const configPath = join(output, "craft.config.json");
+  const configPath = join2(output, "craft.config.json");
   if (!existsSync(configPath))
     throw new Error(`No craft.config.json found in ${output}. Run 'craft-ios init' first.`);
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
@@ -1003,8 +1112,8 @@ async function run(options) {
     console.log(`   Device: ${device.name} (${device.runtime})`);
     try {
       await bootSimulator(device);
-      const derivedData = join(output, "build");
-      const product = join(derivedData, "Build", "Products", "Debug-iphonesimulator", `${appName}.app`);
+      const derivedData = join2(output, "build");
+      const product = join2(derivedData, "Build", "Products", "Debug-iphonesimulator", `${appName}.app`);
       await $`xcodebuild -project ${projectPath} -scheme ${appName} -configuration Debug -destination ${`id=${device.udid}`} -derivedDataPath ${derivedData} build`;
       if (!existsSync(product)) {
         throw new Error(`xcodebuild reported success but ${product} does not exist. ` + "The scheme may build a different product name than the project.");

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`. */
@@ -412,6 +446,8 @@ export declare function installRuntime(output: string, runtimeDir: string): Prom
  * valid Swift type.
  */
 export declare function productName(name: string): string;
+/** Restore package-owned Swift into an existing project, without changing its Xcode metadata or bundled screens. */
+export declare function restoreShell(output: string): void;
 export declare function init(options: InitOptions): Promise<void>;
 /**
  * Build web assets and generate Xcode project
@@ -475,3 +511,5 @@ export declare function bootSimulator(device: SimulatorDevice): Promise<void>;
  */
 export declare function showSimulator(): Promise<void>;
 export declare function run(options: RunOptions): Promise<void>;
+export { createNativeMutationValidator, initSimulatorDriver, serializeSimulatorSteps } from './testing.js';
+export type { NativeMutationValidator, NativeValidationResult, SimulatorDriverOptions, SimulatorStep } from './testing.js';