@craft-native/ios 0.0.124 → 0.0.126

package/README.md

@@ -64,7 +64,10 @@ Build native iOS apps with web technologies using Craft.
 
 The iOS support is built into the main `craft` CLI:
 
-`FlatList` item roots receive the same `onLayout` callback as ordinary native
+`Pressable`, `TouchableOpacity`, and `TouchableHighlight` render as native
+pressable flow containers. `Modal` renders a parent-scoped blocking layer in native mode, with `visible`,
+`transparent`, `animationType`, `onShow`, `onDismiss`, and `onRequestClose`
+support. `FlatList` item roots receive the same `onLayout` callback as ordinary native
 views when rows are materialized or recycled.
 
 ```bash
@@ -109,16 +112,19 @@ In Xcode:
 
 ### Experimental WebView-free screen
 
-The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `TextInput`, `ActivityIndicator`, `Image`, `ScrollView`, and recycling `FlatList` nodes as UIKit controls. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. Native views support `onLayout` callbacks with point-based frame measurements that refresh after safe-area or orientation changes. Flex items support `flex`, `flexGrow`, `flexShrink`, and numeric `flexBasis` for main-axis space distribution. Native screens also expose the versioned capability bridge: JSON storage and SQLite survive relaunch, lifecycle and deep-link events are scoped to the top route, and local notifications use `UNUserNotificationCenter`. Enable each capability in `craft.config.json`; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code and every request has deterministic timeout/cancellation behavior. The default remains `web`; existing iOS apps are unchanged. `Switch` supports state-aware `trackColor`, `thumbColor`, and iOS `ios_backgroundColor`; `Slider` supports track/thumb tint props and `step` snapping; `Image` reports load lifecycle events and structured failures. The portable component, capability, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
+Keyboard frame changes update the native controller's additional safe area, so
+focused inputs and responsive `onLayout` measurements move with the keyboard.
+
+The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `Link`, `TextInput`, `Picker`, `Switch`, `Slider`, `ActivityIndicator`, `Image`, `ScrollView`, and recycling `FlatList` nodes as UIKit controls. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. Native views support `onLayout` callbacks with point-based frame measurements that refresh after safe-area or orientation changes. Flex items support `flex`, `flexGrow`, `flexShrink`, and numeric `flexBasis` for main-axis space distribution. Native screens also expose the versioned capability bridge: JSON storage and SQLite survive relaunch, lifecycle and deep-link events are scoped to the top route, and local notifications use `UNUserNotificationCenter`. Enable each capability in `craft.config.json`; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code and every request has deterministic timeout/cancellation behavior. The default remains `web`; existing iOS apps are unchanged. `Picker` renders `<select>`/`<option>` values with `onValueChange` or `onChange`; `Switch` supports state-aware `trackColor`, `thumbColor`, and iOS `ios_backgroundColor`; `Slider` supports track/thumb tint props and `step` snapping; `Image` reports load lifecycle events and structured failures. The portable component, capability, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
 
 ```bash
 craft ios init NativeDemo --renderer native --output ./ios-native
-stx-native compile Screen.stx --format bundle --output ./screen.js
+stx native compile Screen.stx --format bundle --output ./screen.js
 craft ios build --output ./ios-native --native-bundle ./screen.js
 craft ios run --output ./ios-native --simulator
 ```
 
-`stx-native` is currently a private package in the sibling [stx repository](https://github.com/stacksjs/stx). Run its source CLI with Bun until it is published or linked locally. A runnable screen is in [`fixtures/native-screen/Screen.stx`](./fixtures/native-screen/Screen.stx). In native mode, the app never instantiates `WKWebView`; a missing `dist/native-screen.js` fails the build rather than silently opening the web placeholder.
+`stx native compile` is part of the [stx](https://github.com/stacksjs/stx) CLI (`@stacksjs/stx`); build tools can call `compileNativeBundle` from `@stacksjs/stx/native` instead. A runnable screen is in [`fixtures/native-screen/Screen.stx`](./fixtures/native-screen/Screen.stx). In native mode, the app never instantiates `WKWebView`; a missing `dist/native-screen.js` fails the build rather than silently opening the web placeholder.
 
 Native screen updates use the versioned mutation protocol when the bundle
 supports it and fall back to whole-document rendering for older bundles.
@@ -133,7 +139,7 @@ the [Native STX guide](../../docs/guides/native-stx.md). On macOS,
 `bun packages/ios/scripts/test-native-render.ts` runs the renderer's unit and
 simulator UI tests.
 
-For multiple native screens, configure named `.stx` routes and an initial screen in `stx-native.config.json` (see [`fixtures/native-navigation`](./fixtures/native-navigation)). Compile without a positional file: `stx-native compile --format bundle --output ./screen.js`. A screen can call `craft.navigation.push('details', { id: 7 })`, `.replace('home')`, or `.back()`; the destination reads `craft.route.params`. Craft uses a native navigation stack, so the back button and edge-swipe reveal the existing controller and retain its JavaScript and input state. `bun packages/ios/scripts/test-native-navigation.ts` compiles the fixture and runs its simulator test; the default WebView renderer is unchanged.
+For multiple native screens, configure named `.stx` routes and an initial screen in `native.config.json` (see [`fixtures/native-navigation`](./fixtures/native-navigation)). Compile without a positional file: `stx native compile --format bundle --output ./screen.js`. A screen can call `craft.navigation.push('details', { id: 7 })`, `.replace('home')`, or `.back()`; the destination reads `craft.route.params`. Craft uses a native navigation stack, so the back button and edge-swipe reveal the existing controller and retain its JavaScript and input state. `bun packages/ios/scripts/test-native-navigation.ts` compiles the fixture and runs its simulator test; the default WebView renderer is unchanged.
 
 The optional Liquid Glass tab-bar styling is compiler-gated for Xcode 26/Swift 6.2 and later. Older SDKs compile the same tab bar with the material fallback, so generated projects remain buildable on Xcode 16.
 

package/dist/cli.js

@@ -16,6 +16,62 @@ var CRAFT_VERSION = (() => {
     return "0.0.0";
   }
 })();
+function normalizeNativePath(raw) {
+  if (typeof raw !== "string")
+    return null;
+  let path = raw;
+  const cut = path.search(/[?#]/);
+  if (cut >= 0)
+    path = path.slice(0, cut);
+  if (!path.startsWith("/"))
+    return null;
+  path = path.replace(/\/{2,}/g, "/");
+  if (path.length > 1 && path.endsWith("/"))
+    path = path.slice(0, -1);
+  return path;
+}
+function routeSegments(path) {
+  return path === "/" ? [] : path.slice(1).split("/");
+}
+function isHybrid(config) {
+  return (config.renderer ?? "web") === "web" && Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+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.`);
+    if (routeSegments(normalizeNativePath(pattern) ?? "/").slice(0, -1).includes("*"))
+      problems.push(`nativeScreens path "${pattern}" may only end in *.`);
+    if (typeof screen !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(screen))
+      problems.push(`nativeScreens screen "${String(screen)}" for "${pattern}" must be a screen name from the native bundle.`);
+  }
+  const ids = new Set;
+  for (const tab of config.tabs ?? []) {
+    if (!tab || typeof tab.id !== "string" || !tab.id || typeof tab.title !== "string" || !tab.title)
+      problems.push("Each tab needs an id (its root path) and a title.");
+    else if (ids.has(tab.id))
+      problems.push(`Tab "${tab.id}" is listed twice.`);
+    else
+      ids.add(tab.id);
+  }
+  for (const [key, target] of Object.entries(config.shareStorage ?? {})) {
+    if (!key || typeof target !== "string" || !target)
+      problems.push(`shareStorage "${key}" needs the Keychain key native screens read it under.`);
+  }
+  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 });
+  if (resolve(source) !== resolve(destination))
+    cpSync(source, destination);
+}
 var DEFAULT_CONFIG = {
   renderer: "web",
   version: "1.0.0",
@@ -648,6 +704,12 @@ async function init(options) {
   }
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
+  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);
@@ -657,6 +719,7 @@ async function init(options) {
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.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, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.swift"));
   const infoPlistTemplate = readFileSync(join(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/>
@@ -749,12 +812,18 @@ ${nativeDependencies.join(`
     writeFileSync(join(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
   writeFileSync(join(output, "dist", "index.html"), renderOfflinePage(config));
+  if (isHybrid(config)) {
+    if (config.nativeBundle)
+      installNativeBundle(config.nativeBundle, output);
+    else
+      console.warn("   \u26A0 nativeScreens is set without nativeBundle: every path opens in the web view until `craft ios build --native-bundle` supplies one.");
+  }
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
   if (config.renderer === "native") {
-    console.log("  2. Compile your screen: stx-native compile Screen.stx --format bundle --output screen.js");
+    console.log("  2. Compile your screen: stx native compile Screen.stx --format bundle --output screen.js");
     console.log("  3. Run: craft ios build --native-bundle screen.js");
   } else {
     console.log("  2. Add your web content to dist/index.html");
@@ -785,11 +854,15 @@ async function build(options) {
         cpSync(nativeBundlePath, destination);
     }
     if (!existsSync(join(output, "dist", "native-screen.js"))) {
-      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with stx-native first.");
+      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
-  } else if (nativeBundlePath) {
-    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  } else if (nativeBundlePath && !isHybrid(config)) {
+    throw new Error('--native-bundle requires renderer: "native", or nativeScreens, in craft.config.json.');
   }
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
   if (devServer) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;
@@ -801,6 +874,15 @@ async function build(options) {
     syncWebAssets(htmlPath, output);
     console.log(`   Synced: ${htmlPath} \u2192 dist/`);
   }
+  if (isHybrid(config)) {
+    const bundle = nativeBundlePath ?? config.nativeBundle;
+    if (bundle) {
+      installNativeBundle(bundle, output);
+      console.log(`   Native screens: ${bundle} \u2192 dist/native-screen.js`);
+    } else if (!existsSync(join(output, "dist", "native-screen.js"))) {
+      console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
+    }
+  }
   await refreshRuntime(output, options.runtimeDir);
   if (!generateProject)
     return;
@@ -962,7 +1044,7 @@ Options:
   -t, --team-id <id>        Apple Developer Team ID
   --renderer <kind>         iOS renderer: web (default) or native
   --html-path <path>        Path to HTML file or directory
-  --native-bundle <path>    JavaScript bundle compiled by stx-native
+  --native-bundle <path>    JavaScript bundle from \`stx native compile\`
   -d, --dev-server <url>    Development server URL
   -o, --output <dir>        Output directory (default: ./ios)
   -s, --simulator           Run on simulator instead of device

package/dist/index.d.ts

@@ -144,7 +144,55 @@ export interface CraftConfig {
     requestTimeoutSeconds?: number;
     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.
+     */
+    nativeScreens?: Record<string, string>;
+    /** Hybrid: the bundle `stx native compile --format bundle` wrote, copied to `dist/native-screen.js`. */
+    nativeBundle?: 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
+     * root path, as the page's tab links name it.
+     */
+    tabs?: CraftTab[];
+    /**
+     * Hybrid: web-storage keys the page writes (localStorage or
+     * sessionStorage) that native screens need, mirrored into the Keychain
+     * under the name given, e.g. `{ "auth_token": "auth.token" }` for
+     * `craft.secureStorage.getSync('auth.token')`. Turns on secure storage.
+     */
+    shareStorage?: Record<string, string>;
+}
+export interface CraftTab {
+    /** The tab's root path; comes back to the page in `craftTabSelect`. */
+    id: string;
+    title: string;
+    /** An SF Symbol name. */
+    symbol?: string;
+}
+/** `/a//b/?q#h` → `/a/b`, the way the shell and the page compare paths. Null for a relative path. */
+export declare function normalizeNativePath(raw: string): string | null;
+export interface NativePathMatch {
+    path: string;
+    screen: string;
+    params: Record<string, string>;
 }
+/**
+ * The native screen for a path, by the rules the shell (`CraftHybridRoutes`)
+ * and the page script apply: static segments win over `:params`, which win
+ * over a trailing `*`; query items become params under the path's own.
+ */
+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;
+/** 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 interface CraftBackgroundRefresh {
     enabled: boolean;
     /** The BGTaskScheduler identifier. Default `<bundleId>.refresh`. */
@@ -191,7 +239,7 @@ export interface InitOptions {
 }
 export interface BuildOptions {
     htmlPath?: string;
-    /** JavaScript bundle emitted by `stx-native compile Screen.stx --format bundle`. */
+    /** JavaScript bundle emitted by `stx native compile Screen.stx --format bundle`. */
     nativeBundlePath?: string;
     devServer?: string;
     output: string;

package/dist/index.js

@@ -11,6 +11,122 @@ var CRAFT_VERSION = (() => {
     return "0.0.0";
   }
 })();
+function normalizeNativePath(raw) {
+  if (typeof raw !== "string")
+    return null;
+  let path = raw;
+  const cut = path.search(/[?#]/);
+  if (cut >= 0)
+    path = path.slice(0, cut);
+  if (!path.startsWith("/"))
+    return null;
+  path = path.replace(/\/{2,}/g, "/");
+  if (path.length > 1 && path.endsWith("/"))
+    path = path.slice(0, -1);
+  return path;
+}
+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 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.`);
+    if (routeSegments(normalizeNativePath(pattern) ?? "/").slice(0, -1).includes("*"))
+      problems.push(`nativeScreens path "${pattern}" may only end in *.`);
+    if (typeof screen !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(screen))
+      problems.push(`nativeScreens screen "${String(screen)}" for "${pattern}" must be a screen name from the native bundle.`);
+  }
+  const ids = new Set;
+  for (const tab of config.tabs ?? []) {
+    if (!tab || typeof tab.id !== "string" || !tab.id || typeof tab.title !== "string" || !tab.title)
+      problems.push("Each tab needs an id (its root path) and a title.");
+    else if (ids.has(tab.id))
+      problems.push(`Tab "${tab.id}" is listed twice.`);
+    else
+      ids.add(tab.id);
+  }
+  for (const [key, target] of Object.entries(config.shareStorage ?? {})) {
+    if (!key || typeof target !== "string" || !target)
+      problems.push(`shareStorage "${key}" needs the Keychain key native screens read it under.`);
+  }
+  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 });
+  if (resolve(source) !== resolve(destination))
+    cpSync(source, destination);
+}
 var DEFAULT_CONFIG = {
   renderer: "web",
   version: "1.0.0",
@@ -643,6 +759,12 @@ async function init(options) {
   }
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
+  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);
@@ -652,6 +774,7 @@ async function init(options) {
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.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, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.swift"));
   const infoPlistTemplate = readFileSync(join(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/>
@@ -744,12 +867,18 @@ ${nativeDependencies.join(`
     writeFileSync(join(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
   writeFileSync(join(output, "dist", "index.html"), renderOfflinePage(config));
+  if (isHybrid(config)) {
+    if (config.nativeBundle)
+      installNativeBundle(config.nativeBundle, output);
+    else
+      console.warn("   \u26A0 nativeScreens is set without nativeBundle: every path opens in the web view until `craft ios build --native-bundle` supplies one.");
+  }
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
   if (config.renderer === "native") {
-    console.log("  2. Compile your screen: stx-native compile Screen.stx --format bundle --output screen.js");
+    console.log("  2. Compile your screen: stx native compile Screen.stx --format bundle --output screen.js");
     console.log("  3. Run: craft ios build --native-bundle screen.js");
   } else {
     console.log("  2. Add your web content to dist/index.html");
@@ -780,11 +909,15 @@ async function build(options) {
         cpSync(nativeBundlePath, destination);
     }
     if (!existsSync(join(output, "dist", "native-screen.js"))) {
-      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with stx-native first.");
+      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
-  } else if (nativeBundlePath) {
-    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  } else if (nativeBundlePath && !isHybrid(config)) {
+    throw new Error('--native-bundle requires renderer: "native", or nativeScreens, in craft.config.json.');
   }
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
   if (devServer) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;
@@ -796,6 +929,15 @@ async function build(options) {
     syncWebAssets(htmlPath, output);
     console.log(`   Synced: ${htmlPath} \u2192 dist/`);
   }
+  if (isHybrid(config)) {
+    const bundle = nativeBundlePath ?? config.nativeBundle;
+    if (bundle) {
+      installNativeBundle(bundle, output);
+      console.log(`   Native screens: ${bundle} \u2192 dist/native-screen.js`);
+    } else if (!existsSync(join(output, "dist", "native-screen.js"))) {
+      console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
+    }
+  }
   await refreshRuntime(output, options.runtimeDir);
   if (!generateProject)
     return;
@@ -944,8 +1086,12 @@ export {
   pickSimulator,
   orderSimulators,
   open,
+  normalizeNativePath,
+  matchNativePath,
+  isHybrid,
   installRuntime,
   init,
+  hybridConfigProblems,
   build,
   bootSimulator,
   backgroundRefreshIdentifier,

package/package.json

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