@craft-native/ios 0.0.105 → 0.0.109

package/README.md

@@ -104,6 +104,25 @@ In Xcode:
 
 ## Configuration
 
+### Experimental WebView-free screen
+
+The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `Text`, `Button`, and `TextInput` nodes as UIKit controls. The default remains `web`; existing iOS apps are unchanged. This is a vertical slice, not yet a replacement for the WebView renderer: the native bridge supports device info, haptics, clipboard read/write, and multi-screen navigation. Lists and the rest of Craft's device APIs still need native adapters. Enable `enableHaptics` and `enableClipboard` in `craft.config.json` before using those two capabilities; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code.
+
+```bash
+craft ios init NativeDemo --renderer native --output ./ios-native
+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.
+
+Native screen updates reconcile the UIKit tree by sibling-scoped `key` (or `testID` for existing screens); unkeyed children reuse their position. `TextInput` objects therefore keep focus and selection while unrelated labels and buttons change. 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.
+
+The iOS host overlays `craft.config.json` on its defaults. Missing or `null` capability flags stay disabled; explicitly set a flag to `true` to enable it. Both the Swift host and Zig bridge reject malformed values and fall back to all capabilities disabled.
+
 Edit `craft.config.json` in your iOS project:
 
 ```json
@@ -222,12 +241,12 @@ const scannedCode = await window.craft.scanQRCode();
 console.log(scannedCode); // "https://example.com"
 
 // File Picker
-const file = await window.craft.pickFile(['public.image', 'public.pdf']);
+const file = await window.craft.pickFile(['public.image', 'application/pdf']);
 console.log(file.name, file.data); // base64 encoded
 
 // File Download
 await window.craft.downloadFile('https://example.com/file.pdf', 'document.pdf');
-await window.craft.saveFile(base64Data, 'image.png', 'image/png');
+await window.craft.saveFile('data:text/plain;base64,SGVsbG8=', 'hello.txt', 'text/plain');
 
 // Social Auth (Apple Sign In)
 const user = await window.craft.signInWithApple();

package/dist/cli.js

@@ -10,6 +10,7 @@ import { dirname, join, resolve } from "path";
 var {$ } = globalThis.Bun;
 var TEMPLATES_DIR = join(dirname(import.meta.dir), "templates");
 var DEFAULT_CONFIG = {
+  renderer: "web",
   version: "1.0.0",
   buildNumber: "1",
   darkMode: true,
@@ -398,12 +399,17 @@ async function init(options) {
     teamId: teamId || "",
     ...given
   };
+  if (config.renderer !== "web" && config.renderer !== "native") {
+    throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
+  }
   if (config.enableBackgroundLocation)
     config.enableGeolocation = 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);
   writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
+  cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.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(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
@@ -538,13 +544,18 @@ ${nativeDependencies.join(`
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
-  console.log("  2. Add your web content to dist/index.html");
-  console.log("  3. Run: craft ios build");
+  if (config.renderer === "native") {
+    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");
+    console.log("  3. Run: craft ios build");
+  }
   console.log("  4. Run: craft ios open");
   console.log("");
 }
 async function build(options) {
-  const { htmlPath, devServer, output, generateProject = true } = options;
+  const { htmlPath, nativeBundlePath, devServer, output, generateProject = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft iOS project...`);
   const configPath = join(output, "craft.config.json");
@@ -552,6 +563,24 @@ async function build(options) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft ios init' first.`);
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  if (config.renderer !== undefined && config.renderer !== "web" && config.renderer !== "native") {
+    throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
+  }
+  if (config.renderer === "native") {
+    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"))) {
+      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with stx-native first.");
+    }
+  } else if (nativeBundlePath) {
+    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  }
   if (devServer) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;
@@ -695,7 +724,9 @@ var { values, positionals } = parseArgs({
     name: { type: "string", short: "n" },
     "bundle-id": { type: "string", short: "b" },
     "team-id": { type: "string", short: "t" },
+    renderer: { type: "string" },
     "html-path": { type: "string" },
+    "native-bundle": { type: "string" },
     "dev-server": { type: "string", short: "d" },
     output: { type: "string", short: "o" },
     simulator: { type: "boolean", short: "s" }
@@ -720,7 +751,9 @@ Options:
   -n, --name <name>         App name
   -b, --bundle-id <id>      Bundle identifier (e.g., com.example.app)
   -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
   -d, --dev-server <url>    Development server URL
   -o, --output <dir>        Output directory (default: ./ios)
   -s, --simulator           Run on simulator instead of device
@@ -730,6 +763,8 @@ Options:
 Examples:
   craft-ios init MyApp
   craft-ios build --html-path ./dist/index.html
+  craft-ios init MyApp --renderer native
+  craft-ios build --native-bundle ./screen.js
   craft-ios build --dev-server http://localhost:3456
   craft-ios run --simulator
 `);
@@ -747,12 +782,14 @@ async function main() {
           name: positionals[1] || values.name || "CraftApp",
           bundleId: values["bundle-id"],
           teamId: values["team-id"],
-          output: values.output || "./ios"
+          output: values.output || "./ios",
+          config: values.renderer ? { renderer: values.renderer } : undefined
         });
         break;
       case "build":
         await build({
           htmlPath: values["html-path"],
+          nativeBundlePath: values["native-bundle"],
           devServer: values["dev-server"],
           output: values.output || "./ios"
         });

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type CraftAppearance = 'light' | 'dark' | 'system';
 export interface CraftConfig {
     appName: string;
     bundleId: string;
+    /** Opt in to UIKit + JavaScriptCore instead of the default WebView. */
+    renderer?: 'web' | 'native';
     version?: string;
     buildNumber?: string;
     darkMode?: boolean;
@@ -108,6 +110,8 @@ export interface InitOptions {
 }
 export interface BuildOptions {
     htmlPath?: string;
+    /** JavaScript bundle emitted by `stx-native compile Screen.stx --format bundle`. */
+    nativeBundlePath?: string;
     devServer?: string;
     output: string;
     generateProject?: boolean;

package/dist/index.js

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "path";
 var {$ } = globalThis.Bun;
 var TEMPLATES_DIR = join(dirname(import.meta.dir), "templates");
 var DEFAULT_CONFIG = {
+  renderer: "web",
   version: "1.0.0",
   buildNumber: "1",
   darkMode: true,
@@ -393,12 +394,17 @@ async function init(options) {
     teamId: teamId || "",
     ...given
   };
+  if (config.renderer !== "web" && config.renderer !== "native") {
+    throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
+  }
   if (config.enableBackgroundLocation)
     config.enableGeolocation = 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);
   writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
+  cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.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(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
@@ -533,13 +539,18 @@ ${nativeDependencies.join(`
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
-  console.log("  2. Add your web content to dist/index.html");
-  console.log("  3. Run: craft ios build");
+  if (config.renderer === "native") {
+    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");
+    console.log("  3. Run: craft ios build");
+  }
   console.log("  4. Run: craft ios open");
   console.log("");
 }
 async function build(options) {
-  const { htmlPath, devServer, output, generateProject = true } = options;
+  const { htmlPath, nativeBundlePath, devServer, output, generateProject = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft iOS project...`);
   const configPath = join(output, "craft.config.json");
@@ -547,6 +558,24 @@ async function build(options) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft ios init' first.`);
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  if (config.renderer !== undefined && config.renderer !== "web" && config.renderer !== "native") {
+    throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
+  }
+  if (config.renderer === "native") {
+    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"))) {
+      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with stx-native first.");
+    }
+  } else if (nativeBundlePath) {
+    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  }
   if (devServer) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;

package/package.json

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

package/templates/CraftApp.swift

@@ -221,8 +221,14 @@ struct CraftApp: App {
 
     var body: some SwiftUI.Scene {
         WindowGroup {
-            CraftWebView(config: appState.config)
-                .ignoresSafeArea()
+            Group {
+                if appState.config.renderer == "native" {
+                    CraftNativeScreen(config: appState.config)
+                } else {
+                    CraftWebView(config: appState.config)
+                        .ignoresSafeArea()
+                }
+            }
                 .preferredColorScheme(appState.config.colorScheme)
                 .environmentObject(appState)
                 .onOpenURL { url in
@@ -375,6 +381,8 @@ extension CraftConfig {
 struct CraftConfig: Codable {
     var appName: String = "Craft App"
     var bundleId: String = "com.craft.app"
+    /// Opt-in UIKit + JavaScriptCore screen; existing apps keep WKWebView.
+    var renderer: String = "web"
     var darkMode: Bool = true
     /// "light", "dark" or "system". Absent in configs older than the field,
     /// which keep what `darkMode` pinned.
@@ -873,6 +881,13 @@ struct CraftWebView: UIViewRepresentable {
         /// `craft_ios_deliver_result` instead of evaluating JavaScript here —
         /// one reply path, owned by whichever side received the page's message.
         func dispatch(action: String, body: [String: Any], callbackId: String?) {
+            if let answer = CraftNativeActions.perform(action: action, body: body, config: config) {
+                switch answer {
+                case .success(let value): resolveCallback(callbackId, result: value)
+                case .failure(let error): rejectCallback(callbackId, error: error.message, code: error.code)
+                }
+                return
+            }
             switch action {
             case "startListening":
                 if config.enableSpeechRecognition {
@@ -888,14 +903,6 @@ struct CraftWebView: UIViewRepresentable {
             case "stopListening":
                 stopSpeechRecognition()
                 resolveCallback(callbackId, result: true)
-            case "haptic":
-                if config.enableHaptics {
-                    let style = body["style"] as? String ?? "medium"
-                    triggerHaptic(style: style)
-                    resolveCallback(callbackId, result: true)
-                } else {
-                    rejectCallback(callbackId, error: "Haptics is disabled", code: "CAPABILITY_DISABLED")
-                }
             case "share":
                 if config.enableShare {
                     if let options = body["options"] as? [String: Any] {
@@ -1028,28 +1035,6 @@ struct CraftWebView: UIViewRepresentable {
                 getLocationRecordingState(callbackId: callbackId)
             case "readLocationRecording":
                 readLocationRecording(callbackId: callbackId)
-            // Clipboard
-            case "clipboardWrite":
-            if config.enableClipboard {
-                    if let text = body["text"] as? String {
-                            UIPasteboard.general.string = text
-                            resolveCallback(callbackId, result: true)
-                    } else {
-                        rejectCallback(callbackId, error: "clipboardWrite was called without the values it needs", code: "INVALID_ARGUMENT")
-                    }
-            } else {
-                rejectCallback(callbackId, error: "Clipboard is disabled", code: "CAPABILITY_DISABLED")
-            }
-            case "clipboardRead":
-                if config.enableClipboard {
-                    let text = UIPasteboard.general.string ?? ""
-                    resolveCallback(callbackId, result: text)
-                } else {
-                    rejectCallback(callbackId, error: "Clipboard is disabled", code: "CAPABILITY_DISABLED")
-                }
-            // Device Info
-            case "getDeviceInfo":
-                getDeviceInfo(callbackId: callbackId)
             // App Badge
             case "setBadge":
                 if let count = body["count"] as? Int {
@@ -1078,7 +1063,7 @@ struct CraftWebView: UIViewRepresentable {
                 if let pattern = body["pattern"] as? [Int] {
                     vibratePattern(pattern)
                 } else {
-                    triggerHaptic(style: "medium")
+                    CraftNativeActions.triggerHaptic(style: "medium")
                 }
                 resolveCallback(callbackId, result: true)
             // Open URL
@@ -3693,7 +3678,7 @@ struct CraftWebView: UIViewRepresentable {
             do {
                 try audioEngine.start()
                 sendToWeb("craftSpeechStart", data: [:])
-                triggerHaptic(style: "light")
+                CraftNativeActions.triggerHaptic(style: "light")
             } catch {
                 sendToWeb("craftSpeechError", data: ["error": "Audio engine failed"])
             }
@@ -3707,27 +3692,7 @@ struct CraftWebView: UIViewRepresentable {
             recognitionTask?.cancel()
             recognitionTask = nil
             sendToWeb("craftSpeechEnd", data: [:])
-            triggerHaptic(style: "light")
-        }
-
-        // MARK: - Haptics
-        private func triggerHaptic(style: String) {
-            switch style {
-            case "light":
-                UIImpactFeedbackGenerator(style: .light).impactOccurred()
-            case "heavy":
-                UIImpactFeedbackGenerator(style: .heavy).impactOccurred()
-            case "success":
-                UINotificationFeedbackGenerator().notificationOccurred(.success)
-            case "warning":
-                UINotificationFeedbackGenerator().notificationOccurred(.warning)
-            case "error":
-                UINotificationFeedbackGenerator().notificationOccurred(.error)
-            case "selection":
-                UISelectionFeedbackGenerator().selectionChanged()
-            default:
-                UIImpactFeedbackGenerator(style: .medium).impactOccurred()
-            }
+            CraftNativeActions.triggerHaptic(style: "light")
         }
 
         // MARK: - Share
@@ -4412,43 +4377,6 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
-        // MARK: - Device Info
-        private func getDeviceInfo(callbackId: String?) {
-            let device = UIDevice.current
-            let screen = UIScreen.main
-            #if targetEnvironment(simulator)
-            let isSimulator = true
-            #else
-            let isSimulator = false
-            #endif
-            let info: [String: Any] = [
-                "platform": "ios",
-                "model": device.model,
-                "name": device.name,
-                "systemName": device.systemName,
-                "systemVersion": device.systemVersion,
-                "identifierForVendor": device.identifierForVendor?.uuidString ?? "",
-                "isSimulator": isSimulator,
-                "screenWidth": screen.bounds.width,
-                "screenHeight": screen.bounds.height,
-                "screenScale": screen.scale,
-                "batteryLevel": device.batteryLevel,
-                "batteryState": getBatteryState(device.batteryState),
-                "locale": Locale.current.identifier,
-                "timezone": TimeZone.current.identifier
-            ]
-            resolveCallback(callbackId, result: info)
-        }
-
-        private func getBatteryState(_ state: UIDevice.BatteryState) -> String {
-            switch state {
-            case .charging: return "charging"
-            case .full: return "full"
-            case .unplugged: return "unplugged"
-            default: return "unknown"
-            }
-        }
-
         // MARK: - App Badge
         private func setBadgeCount(_ count: Int, callbackId: String?) {
             UNUserNotificationCenter.current().requestAuthorization(options: .badge) { granted, _ in

package/templates/CraftNativeActions.swift

@@ -0,0 +1,93 @@
+import UIKit
+
+/// The result of a Craft action, independent of whether the caller is a
+/// WebKit page or the JavaScriptCore native-screen runtime.
+struct CraftNativeActionError: Error {
+    let code: String
+    let message: String
+}
+
+enum CraftNativeActions {
+    /// Nil means this small shared router does not own the action. Both hosts
+    /// can then continue through their existing unsupported-action path.
+    static func perform(action: String, body: [String: Any], config: CraftConfig) -> Result<Any, CraftNativeActionError>? {
+        switch action {
+        case "getDeviceInfo":
+            return .success(deviceInfo())
+        case "haptic":
+            guard config.enableHaptics else {
+                return .failure(CraftNativeActionError(code: "CAPABILITY_DISABLED", message: "Haptics is disabled"))
+            }
+            triggerHaptic(style: body["style"] as? String ?? "medium")
+            return .success(true)
+        case "clipboardWrite":
+            guard config.enableClipboard else {
+                return .failure(CraftNativeActionError(code: "CAPABILITY_DISABLED", message: "Clipboard is disabled"))
+            }
+            guard let text = body["text"] as? String else {
+                return .failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "clipboardWrite was called without the values it needs"))
+            }
+            UIPasteboard.general.string = text
+            return .success(true)
+        case "clipboardRead":
+            guard config.enableClipboard else {
+                return .failure(CraftNativeActionError(code: "CAPABILITY_DISABLED", message: "Clipboard is disabled"))
+            }
+            return .success(UIPasteboard.general.string ?? "")
+        default:
+            return nil
+        }
+    }
+
+    static func triggerHaptic(style: String) {
+        switch style {
+        case "light":
+            UIImpactFeedbackGenerator(style: .light).impactOccurred()
+        case "heavy":
+            UIImpactFeedbackGenerator(style: .heavy).impactOccurred()
+        case "success":
+            UINotificationFeedbackGenerator().notificationOccurred(.success)
+        case "warning":
+            UINotificationFeedbackGenerator().notificationOccurred(.warning)
+        case "error":
+            UINotificationFeedbackGenerator().notificationOccurred(.error)
+        case "selection":
+            UISelectionFeedbackGenerator().selectionChanged()
+        default:
+            UIImpactFeedbackGenerator(style: .medium).impactOccurred()
+        }
+    }
+
+    private static func deviceInfo() -> [String: Any] {
+        let device = UIDevice.current
+        let screen = UIScreen.main
+        #if targetEnvironment(simulator)
+        let isSimulator = true
+        #else
+        let isSimulator = false
+        #endif
+        let batteryState: String
+        switch device.batteryState {
+        case .charging: batteryState = "charging"
+        case .full: batteryState = "full"
+        case .unplugged: batteryState = "unplugged"
+        default: batteryState = "unknown"
+        }
+        return [
+            "platform": "ios",
+            "model": device.model,
+            "name": device.name,
+            "systemName": device.systemName,
+            "systemVersion": device.systemVersion,
+            "identifierForVendor": device.identifierForVendor?.uuidString ?? "",
+            "isSimulator": isSimulator,
+            "screenWidth": screen.bounds.width,
+            "screenHeight": screen.bounds.height,
+            "screenScale": screen.scale,
+            "batteryLevel": device.batteryLevel,
+            "batteryState": batteryState,
+            "locale": Locale.current.identifier,
+            "timezone": TimeZone.current.identifier
+        ]
+    }
+}

package/templates/CraftNativeScreen.swift

@@ -0,0 +1,381 @@
+import Foundation
+import JavaScriptCore
+import SwiftUI
+import UIKit
+
+/// A WebView-free host for the first stx-native vertical slice. The bundled
+/// JavaScript sends whole, compiled view trees to UIKit and receives control
+/// events and Craft API replies through JavaScriptCore.
+struct CraftNativeScreen: UIViewControllerRepresentable {
+    let config: CraftConfig
+
+    func makeUIViewController(context: Context) -> UINavigationController {
+        UINavigationController(rootViewController: CraftNativeScreenController(config: config))
+    }
+
+    func updateUIViewController(_ controller: UINavigationController, context: Context) {}
+}
+
+final class CraftNativeScreenController: UIViewController {
+    private final class RenderedNode {
+        let identity: String
+        let type: String
+        let view: UIView
+        var children: [RenderedNode] = []
+        var widthConstraint: NSLayoutConstraint?
+        var heightConstraint: NSLayoutConstraint?
+
+        init(identity: String, type: String, view: UIView) {
+            self.identity = identity
+            self.type = type
+            self.view = view
+        }
+    }
+
+    private let config: CraftConfig
+    private let routeName: String?
+    private let routeParams: [String: Any]
+    private let jsContext = JSContext()!
+    private let rootStack = UIStackView()
+    private var handlers: [ObjectIdentifier: String] = [:]
+    private var renderedRoot: RenderedNode?
+
+    init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:]) {
+        self.config = config
+        self.routeName = routeName
+        self.routeParams = routeParams
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        navigationItem.title = routeName ?? config.appName
+        view.backgroundColor = config.resolvedBackgroundColor
+        rootStack.axis = .vertical
+        rootStack.alignment = .fill
+        rootStack.distribution = .fill
+        rootStack.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(rootStack)
+        NSLayoutConstraint.activate([
+            rootStack.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
+            rootStack.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
+            rootStack.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
+            rootStack.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor)
+        ])
+        setupJavaScript()
+        loadBundle()
+    }
+
+    private func setupJavaScript() {
+        if let routeName = routeName {
+            jsContext.setObject(routeName, forKeyedSubscript: "__stxNativeRoute" as NSString)
+        }
+        jsContext.setObject(routeParams as NSDictionary, forKeyedSubscript: "__stxNativeParams" as NSString)
+        jsContext.exceptionHandler = { _, exception in
+            NSLog("[craft native] JavaScript exception: %@", exception?.toString() ?? "unknown")
+        }
+        let postMessage: @convention(block) (String) -> Void = { [weak self] json in
+            self?.receive(json)
+        }
+        jsContext.setObject(postMessage, forKeyedSubscript: "craftNativePostMessage" as NSString)
+        jsContext.evaluateScript("""
+            globalThis.__stxNativeCallback = null;
+            globalThis.__stxNativeBridge = {
+                postMessage: function(message) { craftNativePostMessage(message); },
+                onMessage: function(callback) { globalThis.__stxNativeCallback = callback; }
+            };
+            globalThis.console = {
+                log: function() {}, warn: function() {}, error: function() {}
+            };
+        """)
+    }
+
+    private func loadBundle() {
+        guard let url = Bundle.main.url(forResource: "native-screen", withExtension: "js", subdirectory: "dist")
+            ?? Bundle.main.url(forResource: "native-screen", withExtension: "js"),
+            let script = try? String(contentsOf: url, encoding: .utf8) else {
+            showError("Missing dist/native-screen.js. Compile a .stx screen with stx-native first.")
+            return
+        }
+        jsContext.evaluateScript(script)
+        if routeName == nil, let selected = jsContext.objectForKeyedSubscript("__stxNativeRoute")?.toString() {
+            navigationItem.title = selected
+        }
+    }
+
+    private func showError(_ message: String) {
+        let label = UILabel()
+        label.numberOfLines = 0
+        label.textColor = .systemRed
+        label.textAlignment = .center
+        label.text = message
+        rootStack.addArrangedSubview(label)
+        NSLog("[craft native] %@", message)
+    }
+
+    private func receive(_ raw: String) {
+        guard let data = raw.data(using: .utf8),
+              let message = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let type = message["type"] as? String,
+              let payload = message["payload"] as? [String: Any] else { return }
+
+        switch type {
+        case "RENDER":
+            guard let document = payload["document"] as? [String: Any] else { return }
+            render(document)
+        case "NAVIGATE", "NAVIGATE_REPLACE":
+            guard navigationController?.topViewController === self,
+                  let screen = payload["screen"] as? String, !screen.isEmpty,
+                  let navigation = navigationController else { return }
+            let params = payload["params"] as? [String: Any] ?? [:]
+            let next = CraftNativeScreenController(config: config, routeName: screen, routeParams: params)
+            if type == "NAVIGATE" {
+                navigation.pushViewController(next, animated: true)
+            } else {
+                navigation.setViewControllers(Array(navigation.viewControllers.dropLast()) + [next], animated: true)
+            }
+        case "NAVIGATE_BACK":
+            if navigationController?.topViewController === self {
+                navigationController?.popViewController(animated: true)
+            }
+        case "API_REQUEST":
+            guard let id = message["id"] as? String else { return }
+            let args = payload["args"] as? [Any] ?? []
+            let route: (action: String, body: [String: Any])?
+            switch (payload["module"] as? String, payload["method"] as? String) {
+            case ("Device", "getInfo"):
+                route = ("getDeviceInfo", [:])
+            case ("Haptics", "impact"):
+                route = ("haptic", ["style": args.first ?? NSNull()])
+            case ("Clipboard", "write"):
+                route = ("clipboardWrite", ["text": args.first ?? NSNull()])
+            case ("Clipboard", "read"):
+                route = ("clipboardRead", [:])
+            default:
+                route = nil
+            }
+            guard let route = route,
+                  let answer = CraftNativeActions.perform(action: route.action, body: route.body, config: config) else {
+                send(type: "API_ERROR", payload: ["requestId": id, "code": "UNKNOWN_ACTION", "message": "Unsupported native API"], correlationId: id)
+                return
+            }
+            switch answer {
+            case .success(let data):
+                send(type: "API_RESPONSE", payload: ["requestId": id, "data": data], correlationId: id)
+            case .failure(let error):
+                send(type: "API_ERROR", payload: ["requestId": id, "code": error.code, "message": error.message], correlationId: id)
+            }
+        default:
+            break
+        }
+    }
+
+    // Internal so simulator-hosted XCTest can assert actual UIView identity.
+    func render(_ document: [String: Any]) {
+        let previous = renderedRoot
+        let next = reconcile(document, identity: "root", path: "root", previous: previous)
+        if previous?.view !== next.view {
+            if let old = previous { detach(old, from: rootStack) }
+            rootStack.addArrangedSubview(next.view)
+        }
+        renderedRoot = next
+    }
+
+    private func reconcile(_ node: [String: Any], identity: String, path: String, previous: RenderedNode?) -> RenderedNode {
+        let type = node["type"] as? String ?? "View"
+        let props = node["props"] as? [String: Any] ?? [:]
+        let style = node["style"] as? [String: Any] ?? [:]
+        let events = node["events"] as? [String: String] ?? [:]
+        let children = node["children"] as? [Any] ?? []
+        let current: RenderedNode
+        if let previous = previous, previous.identity == identity, previous.type == type {
+            current = previous
+        } else {
+            current = RenderedNode(identity: identity, type: type, view: makeView(type))
+        }
+
+        let result = current.view
+        result.accessibilityIdentifier = explicitKey(node, props: props) ?? path
+        if type != "View" && type != "SafeAreaView" {
+            result.setContentHuggingPriority(.required, for: .vertical)
+        }
+        result.backgroundColor = color(style["backgroundColor"]) ?? .clear
+        result.layer.cornerRadius = number(style["borderRadius"]) ?? 0
+        updateDimension(number(style["width"]), constraint: &current.widthConstraint, anchor: result.widthAnchor)
+        updateDimension(number(style["height"]), constraint: &current.heightConstraint, anchor: result.heightAnchor)
+
+        switch type {
+        case "Text":
+            let label = result as! UILabel
+            label.text = children.compactMap { $0 as? String }.joined()
+            label.textColor = color(style["color"]) ?? .label
+            label.font = .systemFont(ofSize: number(style["fontSize"]) ?? UIFont.systemFontSize)
+        case "Button":
+            let button = result as! UIButton
+            button.setTitle(props["title"] as? String ?? children.compactMap { $0 as? String }.joined(), for: .normal)
+            updateHandler(events["onPress"] ?? events["onClick"], for: button)
+        case "TextInput":
+            let field = result as! UITextField
+            field.placeholder = props["placeholder"] as? String
+            updateField(field, value: props["value"] as? String)
+            updateHandler(events["onChange"] ?? events["onChangeText"], for: field)
+        default:
+            let stack = result as! UIStackView
+            stack.axis = style["flexDirection"] as? String == "row" ? .horizontal : .vertical
+            stack.spacing = number(style["gap"]) ?? 0
+            let padding = number(style["padding"]) ?? 0
+            stack.layoutMargins = UIEdgeInsets(
+                top: number(style["paddingTop"]) ?? padding,
+                left: number(style["paddingLeft"]) ?? padding,
+                bottom: number(style["paddingBottom"]) ?? padding,
+                right: number(style["paddingRight"]) ?? padding
+            )
+            reconcileChildren(children, in: stack, parent: current, path: path)
+        }
+        return current
+    }
+
+    private func makeView(_ type: String) -> UIView {
+        switch type {
+        case "Text":
+            let label = UILabel()
+            label.numberOfLines = 0
+            return label
+        case "Button":
+            let button = UIButton(type: .system)
+            button.addTarget(self, action: #selector(buttonPressed(_:)), for: .touchUpInside)
+            return button
+        case "TextInput":
+            let field = UITextField()
+            field.borderStyle = .roundedRect
+            field.addTarget(self, action: #selector(textChanged(_:)), for: .editingChanged)
+            return field
+        default:
+            let stack = UIStackView()
+            stack.alignment = .fill
+            stack.distribution = .fill
+            stack.isLayoutMarginsRelativeArrangement = true
+            return stack
+        }
+    }
+
+    private func explicitKey(_ node: [String: Any], props: [String: Any]) -> String? {
+        // The current stx-native compiler emits key in props; accept the IR
+        // field too so keyed children keep working when the compiler adopts it.
+        [node["key"], props["key"], props["testID"]]
+            .compactMap { $0 as? String }
+            .first { !$0.isEmpty }
+    }
+
+    private func reconcileChildren(_ children: [Any], in stack: UIStackView, parent: RenderedNode, path: String) {
+        let nodes = children.compactMap { $0 as? [String: Any] }
+        let keys = nodes.compactMap { explicitKey($0, props: $0["props"] as? [String: Any] ?? [:]) }
+        let counts = Dictionary(keys.map { ($0, 1) }, uniquingKeysWith: +)
+        let old = Dictionary(uniqueKeysWithValues: parent.children.map { ($0.identity, $0) })
+        var next: [RenderedNode] = []
+
+        for (index, node) in nodes.enumerated() {
+            let key = explicitKey(node, props: node["props"] as? [String: Any] ?? [:])
+            // Keys are local to a parent. Ambiguous sibling keys fall back to
+            // position so a move never attaches the wrong live control.
+            let identity = key.flatMap { counts[$0] == 1 ? "key:\($0)" : nil } ?? "index:\(index)"
+            let child = reconcile(node, identity: identity, path: "\(path).\(index)", previous: old[identity])
+            next.append(child)
+        }
+
+        for child in parent.children where !next.contains(where: { $0 === child }) {
+            detach(child, from: stack)
+        }
+        for (index, child) in next.enumerated() {
+            if index < stack.arrangedSubviews.count, stack.arrangedSubviews[index] === child.view { continue }
+            if stack.arrangedSubviews.contains(where: { $0 === child.view }) {
+                stack.removeArrangedSubview(child.view)
+            }
+            stack.insertArrangedSubview(child.view, at: index)
+        }
+        parent.children = next
+        if path == "root" && stack.axis == .vertical {
+            // Keep the initial screen pinned to the safe-area top.
+            if stack.arrangedSubviews.count == next.count { stack.addArrangedSubview(UIView()) }
+        } else if stack.arrangedSubviews.count > next.count {
+            for filler in stack.arrangedSubviews.dropFirst(next.count) {
+                stack.removeArrangedSubview(filler)
+                filler.removeFromSuperview()
+            }
+        }
+    }
+
+    private func detach(_ node: RenderedNode, from stack: UIStackView) {
+        forgetHandlers(node)
+        stack.removeArrangedSubview(node.view)
+        node.view.removeFromSuperview()
+    }
+
+    private func forgetHandlers(_ node: RenderedNode) {
+        handlers.removeValue(forKey: ObjectIdentifier(node.view))
+        for child in node.children { forgetHandlers(child) }
+    }
+
+    private func updateHandler(_ handler: String?, for view: UIView) {
+        let id = ObjectIdentifier(view)
+        if let handler = handler { handlers[id] = handler }
+        else { handlers.removeValue(forKey: id) }
+    }
+
+    private func updateField(_ field: UITextField, value: String?) {
+        guard let value = value, field.text != value, field.markedTextRange == nil else { return }
+        let selection = field.selectedTextRange
+        let start = selection.map { field.offset(from: field.beginningOfDocument, to: $0.start) }
+        let end = selection.map { field.offset(from: field.beginningOfDocument, to: $0.end) }
+        field.text = value
+        if let start = start, let end = end,
+           let from = field.position(from: field.beginningOfDocument, offset: min(start, value.utf16.count)),
+           let to = field.position(from: field.beginningOfDocument, offset: min(end, value.utf16.count)) {
+            field.selectedTextRange = field.textRange(from: from, to: to)
+        }
+    }
+
+    private func updateDimension(_ value: CGFloat?, constraint: inout NSLayoutConstraint?, anchor: NSLayoutDimension) {
+        if let value = value {
+            if let constraint = constraint { constraint.constant = value }
+            else {
+                constraint = anchor.constraint(equalToConstant: value)
+                constraint?.isActive = true
+            }
+        } else {
+            constraint?.isActive = false
+            constraint = nil
+        }
+    }
+
+    @objc private func buttonPressed(_ sender: UIButton) {
+        guard let handler = handlers[ObjectIdentifier(sender)] else { return }
+        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": [:]])
+    }
+
+    @objc private func textChanged(_ sender: UITextField) {
+        guard let handler = handlers[ObjectIdentifier(sender)] else { return }
+        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["text": sender.text ?? ""]])
+    }
+
+    private func send(type: String, payload: [String: Any], correlationId: String? = nil) {
+        var message: [String: Any] = ["type": type, "payload": payload]
+        if let correlationId = correlationId { message["correlationId"] = correlationId }
+        guard let data = try? JSONSerialization.data(withJSONObject: message),
+              let json = String(data: data, encoding: .utf8) else { return }
+        jsContext.objectForKeyedSubscript("__stxNativeCallback")?.call(withArguments: [json])
+    }
+
+    private func number(_ value: Any?) -> CGFloat? {
+        (value as? NSNumber).map { CGFloat(truncating: $0) }
+    }
+
+    private func color(_ value: Any?) -> UIColor? {
+        guard let hex = value as? String else { return nil }
+        return UIColor(hex: hex)
+    }
+}