@craft-native/ios 0.0.115 → 0.0.119

package/README.md

@@ -106,7 +106,7 @@ 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`, `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. The default remains `web`; existing iOS apps are unchanged. Most Craft 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. The portable component, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
+The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `TextInput`, `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 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. 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
@@ -439,6 +439,20 @@ await window.craft.restorePurchases();
 window.craft.setKeepAwake(true);  // Prevent screen dimming
 window.craft.setKeepAwake(false); // Allow screen dimming
 
+// Speech: short spoken cues that duck the person's music instead of stopping
+// it, and play with the silent switch on. Always available (no config flag).
+// Resolves when the utterance ends: true if spoken, false if stopped or
+// interrupted. Rejects with INVALID_ARGUMENT for empty text.
+const spoken = await window.craft.speech.speak('Rest, 15 seconds. Up next: Dead Bug', {
+  rate: 1,          // 0.5 to 2, 1 = normal
+  language: 'en-US', // BCP-47; defaults to the device's language
+  interrupt: true   // default: stop what is being said first; false queues
+});
+await window.craft.speech.stop(); // pending speak() calls resolve false
+// Or `import { speech } from 'craft-native/mobile'`: the same calls, falling
+// back to the Web Speech API in a browser and resolving false where neither
+// exists. speech.isAvailable() says which.
+
 // Orientation Lock
 window.craft.lockOrientation('portrait');   // Lock to portrait
 window.craft.lockOrientation('landscape');  // Lock to landscape

package/dist/cli.js

@@ -116,6 +116,27 @@ function renderOrientations(config) {
   return values.map((value) => `        <string>${names[value]}</string>`).join(`
 `);
 }
+function renderAppBoundDomains(config) {
+  const hostOf = (value) => {
+    try {
+      const url = new URL(value);
+      return url.protocol === "https:" || url.protocol === "http:" ? url.hostname.toLowerCase() : null;
+    } catch {
+      return null;
+    }
+  };
+  const domains = config.appBoundDomains !== undefined ? config.appBoundDomains.map((value) => value.trim().toLowerCase()).filter(Boolean) : (config.trustedOrigins ?? []).map(hostOf).filter((host) => !!host);
+  if (!domains.length)
+    return "";
+  const devHost = config.devServerURL ? hostOf(config.devServerURL) : null;
+  if (devHost)
+    domains.push(devHost);
+  const unique = [...new Set(domains)].slice(0, 10);
+  return `    <key>WKAppBoundDomains</key>
+    <array>
+${plistArray(unique)}
+    </array>`;
+}
 function renderUrlTypes(config) {
   const schemes = [...new Set(config.urlSchemes?.map((value) => value.trim()).filter(Boolean) ?? [])];
   if (!schemes.length)
@@ -173,6 +194,12 @@ ${plistArray(config.appGroups)}
     entries.push(`    <key>aps-environment</key>
     <string>$(CRAFT_APNS_ENVIRONMENT)</string>`);
   }
+  if (config.enableSecureStorage) {
+    entries.push(`    <key>keychain-access-groups</key>
+    <array>
+        <string>$(AppIdentifierPrefix)$(CFBundleIdentifier)</string>
+    </array>`);
+  }
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -415,7 +442,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"));
   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>
+  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(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");

package/dist/index.d.ts

@@ -66,6 +66,22 @@ export interface CraftConfig {
     teamId?: string;
     urlSchemes?: string[];
     trustedOrigins?: string[];
+    /**
+     * The domains the app's web view treats as its own (WKAppBoundDomains, at
+     * most 10). Service workers only run in an iOS web view on these, so a site
+     * that works offline in Safari works offline in the app. Unset, they are the
+     * hosts of `trustedOrigins` and the dev server: the origins the bridge is
+     * already injected into, and once any are declared iOS keeps script
+     * injection to them. `[]` declares none.
+     */
+    appBoundDomains?: string[];
+    /**
+     * Also refuse to load anything but the app-bound domains in the web view
+     * (WKWebViewConfiguration.limitsNavigationsToAppBoundDomains). Off by
+     * default: links elsewhere already open in Safari, and embedded players and
+     * maps in iframes keep loading.
+     */
+    limitNavigationsToAppBoundDomains?: boolean;
     associatedDomains?: string[];
     appGroups?: string[];
     appIconPath?: string;
@@ -148,6 +164,8 @@ export declare function renderAppearance(config: Pick<CraftConfig, 'appearance'
 };
 export declare function renderUsageDescriptions(config: CraftConfig): string;
 export declare function renderOrientations(config: CraftConfig): string;
+/** WKAppBoundDomains: the configured domains plus the dev server's host, at most 10. */
+export declare function renderAppBoundDomains(config: CraftConfig): string;
 export declare function renderUrlTypes(config: CraftConfig): string;
 export declare function renderBackgroundModes(config: CraftConfig): string;
 export declare function renderEntitlements(config: CraftConfig): string;

package/dist/index.js

@@ -111,6 +111,27 @@ function renderOrientations(config) {
   return values.map((value) => `        <string>${names[value]}</string>`).join(`
 `);
 }
+function renderAppBoundDomains(config) {
+  const hostOf = (value) => {
+    try {
+      const url = new URL(value);
+      return url.protocol === "https:" || url.protocol === "http:" ? url.hostname.toLowerCase() : null;
+    } catch {
+      return null;
+    }
+  };
+  const domains = config.appBoundDomains !== undefined ? config.appBoundDomains.map((value) => value.trim().toLowerCase()).filter(Boolean) : (config.trustedOrigins ?? []).map(hostOf).filter((host) => !!host);
+  if (!domains.length)
+    return "";
+  const devHost = config.devServerURL ? hostOf(config.devServerURL) : null;
+  if (devHost)
+    domains.push(devHost);
+  const unique = [...new Set(domains)].slice(0, 10);
+  return `    <key>WKAppBoundDomains</key>
+    <array>
+${plistArray(unique)}
+    </array>`;
+}
 function renderUrlTypes(config) {
   const schemes = [...new Set(config.urlSchemes?.map((value) => value.trim()).filter(Boolean) ?? [])];
   if (!schemes.length)
@@ -168,6 +189,12 @@ ${plistArray(config.appGroups)}
     entries.push(`    <key>aps-environment</key>
     <string>$(CRAFT_APNS_ENVIRONMENT)</string>`);
   }
+  if (config.enableSecureStorage) {
+    entries.push(`    <key>keychain-access-groups</key>
+    <array>
+        <string>$(AppIdentifierPrefix)$(CFBundleIdentifier)</string>
+    </array>`);
+  }
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -410,7 +437,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"));
   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>
+  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(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");
@@ -729,6 +756,7 @@ export {
   renderDeviceFamilies,
   renderBackgroundModes,
   renderAppearance,
+  renderAppBoundDomains,
   productName,
   pickSimulator,
   orderSimulators,

package/package.json

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

package/templates/CraftApp.swift

@@ -259,6 +259,7 @@ class DeepLinkManager {
     // the one the app was opened with; a link that arrives later is not, and
     // is no answer to getInitialURL.
     private var hasBeenReady = false
+    private var nativeListeners: [UUID: (URL, Bool) -> Void] = [:]
 
     private init() {}
 
@@ -289,7 +290,9 @@ class DeepLinkManager {
             initialURL = url
         }
 
-        if isReady && webView != nil {
+        if !nativeListeners.isEmpty {
+            dispatchNative(url, initial: false)
+        } else if isReady && webView != nil {
             dispatchDeepLink(url, initial: false)
         } else {
             pendingURLs.append(url)
@@ -300,6 +303,28 @@ class DeepLinkManager {
         return initialURL
     }
 
+    @discardableResult
+    func addNativeListener(_ listener: @escaping (URL, Bool) -> Void) -> UUID {
+        let token = UUID()
+        nativeListeners[token] = listener
+        let firstNativeScreen = !hasBeenReady
+        hasBeenReady = true
+        let urls = pendingURLs
+        pendingURLs.removeAll()
+        for url in urls {
+            listener(url, firstNativeScreen && url == initialURL)
+        }
+        return token
+    }
+
+    func removeNativeListener(_ token: UUID) {
+        nativeListeners.removeValue(forKey: token)
+    }
+
+    private func dispatchNative(_ url: URL, initial: Bool) {
+        for listener in nativeListeners.values { listener(url, initial) }
+    }
+
     private func dispatchDeepLink(_ url: URL, initial: Bool) {
         guard let webView = webView else { return }
 
@@ -392,6 +417,8 @@ struct CraftConfig: Codable {
     var backgroundColorDark: String? = nil
     /// Edge-swipe back and forward through the page's history.
     var swipeNavigation: Bool? = nil
+    /// Refuse to load anything but the Info.plist's WKAppBoundDomains.
+    var limitNavigationsToAppBoundDomains: Bool? = nil
     var enableSpeechRecognition: Bool = false
     var enableHaptics: Bool = false
     var enableShare: Bool = false
@@ -596,6 +623,13 @@ struct CraftWebView: UIViewRepresentable {
         webConfig.allowsInlineMediaPlayback = true
         webConfig.mediaTypesRequiringUserActionForPlayback = []
         webConfig.setURLSchemeHandler(BundledAssetSchemeHandler(), forURLScheme: "craft")
+        // The app's own domains (WKAppBoundDomains in Info.plist) get what an
+        // iOS web view reserves for them, service workers among them, so a
+        // site that works offline in Safari works offline here. This only
+        // narrows loading further when the app asks for it.
+        if config.limitNavigationsToAppBoundDomains == true {
+            webConfig.limitsNavigationsToAppBoundDomains = true
+        }
 
         // Add native bridge
         let contentController = WKUserContentController()
@@ -722,6 +756,24 @@ struct CraftWebView: UIViewRepresentable {
         // Keep awake
         private var isKeepingAwake = false
 
+        // Speech synthesis. One synthesizer for the life of the web view, so a
+        // cue can interrupt the one before it; each utterance it has not
+        // finished yet is held beside the call waiting on it.
+        private lazy var speechSynthesizer: AVSpeechSynthesizer = {
+            let synthesizer = AVSpeechSynthesizer()
+            synthesizer.delegate = self
+            return synthesizer
+        }()
+        private var pendingUtterances: [(utterance: AVSpeechUtterance, callbackId: String?)] = []
+        /// What the session was before speech claimed it; nil while speech
+        /// does not hold it.
+        private var speechAudioSessionToRestore: (AVAudioSession.Category, AVAudioSession.Mode, AVAudioSession.CategoryOptions)?
+        /// Activating and deactivating the audio session blocks until the
+        /// audio hardware answers, which iOS flags as a hang risk on the main
+        /// thread. They run here instead, in order, and the session state
+        /// above is only touched here.
+        private let speechAudioQueue = DispatchQueue(label: "craft.speech.audio")
+
         // Orientation lock
         private var lockedOrientation: UIInterfaceOrientationMask?
 
@@ -1058,6 +1110,16 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "setFlashlight needs true or false", code: "INVALID_ARGUMENT")
                 }
+            // Speech synthesis. Ungated, like the flashlight: speaking needs no
+            // permission and no entitlement.
+            case "speak":
+                if let text = body["text"] as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    speak(text, body: body, callbackId: callbackId)
+                } else {
+                    rejectCallback(callbackId, error: "speak needs some text to say", code: "INVALID_ARGUMENT")
+                }
+            case "stopSpeaking":
+                stopSpeaking(callbackId: callbackId)
             // Vibrate pattern
             case "vibrate":
                 if let pattern = body["pattern"] as? [Int] {
@@ -1850,6 +1912,7 @@ struct CraftWebView: UIViewRepresentable {
                     orientationLock: \(config.enableOrientationLock),
                     deepLinks: \(config.enableDeepLinks),
                     flashlight: true,
+                    speech: true,
                     network: true,
                     deviceInfo: true,
                     badge: true,
@@ -2788,6 +2851,37 @@ struct CraftWebView: UIViewRepresentable {
                     });
                 },
 
+                // Speech synthesis. speak() settles when the utterance ends:
+                // true when it was spoken, false when something stopped it.
+                // No timeout, because a long sentence at a slow rate can
+                // outlast any deadline that would be fair to a short one.
+                speech: {
+                    speak: function(text, options) {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        options = options || {};
+                        window.webkit.messageHandlers.craft.postMessage({
+                            action: 'speak',
+                            text: text == null ? '' : String(text),
+                            rate: typeof options.rate === 'number' ? options.rate : null,
+                            language: typeof options.language === 'string' ? options.language : null,
+                            interrupt: options.interrupt !== false,
+                            callbackId: id
+                        });
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    },
+                    stop: function() {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        window.webkit.messageHandlers.craft.postMessage({action: 'stopSpeaking', callbackId: id});
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    }
+                },
+
                 // Orientation Lock
                 lockOrientation: function(orientation) {
                     var self = this;
@@ -3400,6 +3494,10 @@ struct CraftWebView: UIViewRepresentable {
                 craft.secureStorage = {
                     set: function(key, value) { return legacySecureStore.set(key, value).then(function() {}); },
                     get: function(key) { return legacySecureStore.get(key); },
+                    // `remove` is the legacy name retained by the public Craft
+                    // type declaration; keep it as an alias of `delete` so
+                    // native STX callers can migrate without a feature check.
+                    remove: function(key) { return legacySecureStore.remove(key).then(function() {}); },
                     delete: function(key) { return legacySecureStore.remove(key).then(function() {}); },
                     clear: function() { return craft._invoke('secureClear').then(function() {}); }
                 };
@@ -4762,6 +4860,153 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
+        // MARK: - Speech Synthesis
+        //
+        // Native rather than the page's own `speechSynthesis`, which in a
+        // WKWebView plays through the default soloAmbient session: it stops
+        // the person's music and the silent switch mutes it. A workout cue has
+        // to do neither, so the session is set up here for as long as there is
+        // something to say, and handed back when there is not.
+
+        private func speak(_ text: String, body: [String: Any], callbackId: String?) {
+            DispatchQueue.main.async {
+                if body["interrupt"] as? Bool ?? true {
+                    self.cancelPendingSpeech()
+                }
+
+                let utterance = AVSpeechUtterance(string: text)
+                utterance.rate = Self.utteranceRate(body["rate"] as? Double ?? 1)
+                // An unknown language finds no voice, and a nil voice is the
+                // device's own, which is the default anyway.
+                if let language = body["language"] as? String, !language.isEmpty,
+                   let voice = AVSpeechSynthesisVoice(language: language) {
+                    utterance.voice = voice
+                }
+
+                self.pendingUtterances.append((utterance, callbackId))
+                self.claimAudioSessionForSpeech {
+                    // Stopped while the session was being set up: say nothing.
+                    guard self.pendingUtterances.contains(where: { $0.utterance === utterance }) else { return }
+                    self.speechSynthesizer.speak(utterance)
+                }
+            }
+        }
+
+        private func stopSpeaking(callbackId: String?) {
+            DispatchQueue.main.async {
+                // When something was playing, its didCancel releases the
+                // session once the audio has actually stopped; deactivating
+                // before that fails as busy and leaves the music ducked.
+                if !self.cancelPendingSpeech() { self.releaseAudioSessionIfSilent() }
+                self.resolveCallback(callbackId, result: true)
+            }
+        }
+
+        /// Stop what is being said and settle every call waiting on it, false.
+        /// Returns whether the synthesizer was making a sound.
+        ///
+        /// Settled here rather than in `didCancel`, because the delegate hears
+        /// about the utterance that was playing and nothing about the ones
+        /// queued behind it, whose calls would otherwise never settle.
+        @discardableResult
+        private func cancelPendingSpeech() -> Bool {
+            let waiting = pendingUtterances
+            pendingUtterances.removeAll()
+            let synthesizer = speechSynthesizer
+            let wasSounding = synthesizer.isSpeaking || synthesizer.isPaused
+            if wasSounding { synthesizer.stopSpeaking(at: .immediate) }
+            for entry in waiting {
+                resolveCallback(entry.callbackId, result: false)
+            }
+            return wasSounding
+        }
+
+        /// The page's rate, where 1 is normal, on AVSpeechUtterance's scale.
+        ///
+        /// Apple's scale is not linear in speed: the default sits at 0.5 and
+        /// the maximum is far faster than twice that. So a slower rate scales
+        /// the default down in proportion, and a faster one climbs toward the
+        /// maximum at half the slope, which keeps 2 brisk but intelligible.
+        private static func utteranceRate(_ rate: Double) -> Float {
+            let requested = Float(min(max(rate.isFinite ? rate : 1, 0.5), 2))
+            let normal = AVSpeechUtteranceDefaultSpeechRate
+            let mapped = requested <= 1
+                ? normal * requested
+                : normal + (AVSpeechUtteranceMaximumSpeechRate - normal) * (requested - 1) / 2
+            return min(max(mapped, AVSpeechUtteranceMinimumSpeechRate), AVSpeechUtteranceMaximumSpeechRate)
+        }
+
+        /// Duck the music rather than stop it, and play through the silent
+        /// switch.
+        ///
+        /// `.playback` is what the switch does not mute, `.duckOthers` lowers
+        /// the music under the cue, and the spoken-audio option pauses a
+        /// podcast rather than talking over it. Left alone while recognition
+        /// or a recording holds the session: switching it to playback would
+        /// cut their microphone off mid-take.
+        ///
+        /// Set up on the speech queue, then `start` runs on the main thread.
+        private func claimAudioSessionForSpeech(then start: @escaping () -> Void) {
+            let microphoneBusy = audioEngine.isRunning || (audioRecorder?.isRecording ?? false)
+            speechAudioQueue.async {
+                if self.speechAudioSessionToRestore == nil && !microphoneBusy {
+                    let session = AVAudioSession.sharedInstance()
+                    let previous = (session.category, session.mode, session.categoryOptions)
+                    do {
+                        try session.setCategory(.playback, mode: .voicePrompt, options: [.duckOthers, .interruptSpokenAudioAndMixWithOthers])
+                        try session.setActive(true)
+                        self.speechAudioSessionToRestore = previous
+                    } catch {
+                        // Still speak, through whatever session the app has: a
+                        // cue that does not duck beats one that never plays.
+                        print("[Craft] Speech audio session failed: \(error.localizedDescription)")
+                    }
+                }
+                DispatchQueue.main.async(execute: start)
+            }
+        }
+
+        /// Hand the audio back once nothing is left to say, so the music
+        /// returns to full volume instead of staying ducked, and put back the
+        /// category the app had, so the page's own media plays as before.
+        ///
+        /// Checked on the main thread, where the queue of utterances lives, and
+        /// done on the speech queue after any setup already asked for, so a
+        /// cue that arrives meanwhile reclaims the session after this.
+        private func releaseAudioSessionIfSilent(retry: Bool = true) {
+            guard pendingUtterances.isEmpty else { return }
+            speechAudioQueue.async {
+                guard let previous = self.speechAudioSessionToRestore else { return }
+                let session = AVAudioSession.sharedInstance()
+                do {
+                    try session.setActive(false, options: .notifyOthersOnDeactivation)
+                } catch {
+                    // Busy: the synthesizer's audio has not quite drained, or
+                    // the page has its own media playing. Once more shortly
+                    // covers the first; for the second, staying active is
+                    // right, and the ducking still ends when the music app
+                    // hears nothing more.
+                    if retry {
+                        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                            self.releaseAudioSessionIfSilent(retry: false)
+                        }
+                        return
+                    }
+                    print("[Craft] Speech audio session release failed: \(error.localizedDescription)")
+                }
+                self.speechAudioSessionToRestore = nil
+                try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
+            }
+        }
+
+        fileprivate func speechDidEnd(_ utterance: AVSpeechUtterance, spoken: Bool) {
+            if let index = pendingUtterances.firstIndex(where: { $0.utterance === utterance }) {
+                let entry = pendingUtterances.remove(at: index)
+                resolveCallback(entry.callbackId, result: spoken)
+            }
+            releaseAudioSessionIfSilent()
+        }
+
         // MARK: - Orientation Lock
         private func lockOrientation(_ orientation: String, callbackId: String?) {
             var mask: UIInterfaceOrientationMask = .all
@@ -6698,6 +6943,20 @@ extension URL {
 }
 
 // MARK: - Contact Picker Delegate
+// MARK: - AVSpeechSynthesizerDelegate
+//
+// The end of an utterance is what `craft.speech.speak()` waits for. Hopped to
+// main because every piece of speech state is touched there and nowhere else.
+extension CraftWebView.Coordinator: AVSpeechSynthesizerDelegate {
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: true) }
+    }
+
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: false) }
+    }
+}
+
 extension CraftWebView.Coordinator: CNContactPickerDelegate {
     func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
         let contactData = formatContact(contact)

package/templates/CraftNativeActions.swift

@@ -1,63 +1,498 @@
+import Foundation
+import LocalAuthentication
+import SQLite3
+import Security
 import UIKit
+import UserNotifications
+
+let craftNativeCapabilityProtocolVersion = 1
 
-/// 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
 }
 
+/// Process-wide capability services used by every retained native route.
+/// Database work is serialized so transactions cannot be interleaved by two
+/// JavaScript contexts, while completions return to JavaScriptCore on main.
 enum CraftNativeActions {
-    /// Nil means this small shared router does not own the action. Both hosts
-    /// can then continue through their existing unsupported-action path.
+    private static let storagePrefix = "craft.native.storage."
+    private static let databaseQueue = DispatchQueue(label: "dev.craft.native.database")
+    private static let cancellationLock = NSLock()
+    private static var cancelledRequests = Set<String>()
+    private static var biometricContexts = [String: LAContext]()
+    private static var initialDeepLinkClaimed = false
+    private static var database: OpaquePointer?
+    private static let sqliteTransient = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
+
+    static func capabilities(config: CraftConfig) -> [String] {
+        var values = ["device", "clipboard", "haptics", "storage", "lifecycle"]
+        if config.enableBiometric { values.append("biometric") }
+        if config.enableSecureStorage { values.append("secureStorage") }
+        if config.enableLocalDatabase { values.append("database") }
+        if config.enableDeepLinks { values.append("deepLinks") }
+        if config.enableLocalNotifications { values.append("notifications") }
+        return values
+    }
+
+    /// Nil means this small shared router does not own the action.
     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"))
-            }
+            guard config.enableHaptics else { return failure("CAPABILITY_DISABLED", "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 config.enableClipboard else { return failure("CAPABILITY_DISABLED", "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"))
+                return failure("INVALID_ARGUMENT", "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"))
-            }
+            guard config.enableClipboard else { return failure("CAPABILITY_DISABLED", "Clipboard is disabled") }
             return .success(UIPasteboard.general.string ?? "")
         default:
             return nil
         }
     }
 
+    static func perform(
+        requestToken: String,
+        version: Int,
+        module: String,
+        method: String,
+        args: [Any],
+        config: CraftConfig,
+        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+    ) {
+        cancellationLock.lock()
+        cancelledRequests.remove(requestToken)
+        cancellationLock.unlock()
+        guard version == craftNativeCapabilityProtocolVersion else {
+            complete(requestToken, failure("UNSUPPORTED_VERSION", "Unsupported native capability protocol version"), completion)
+            return
+        }
+
+        let sync: Result<Any, CraftNativeActionError>?
+        switch (module, method) {
+        case ("Device", "getInfo"):
+            sync = perform(action: "getDeviceInfo", body: [:], config: config)
+        case ("Haptics", "impact"):
+            sync = perform(action: "haptic", body: ["style": args.first ?? NSNull()], config: config)
+        case ("Clipboard", "write"):
+            sync = perform(action: "clipboardWrite", body: ["text": args.first ?? NSNull()], config: config)
+        case ("Clipboard", "read"):
+            sync = perform(action: "clipboardRead", body: [:], config: config)
+        case ("Storage", _):
+            sync = storage(method: method, args: args)
+        case ("SecureStorage", _):
+            guard config.enableSecureStorage else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Secure storage is disabled"), completion)
+                return
+            }
+            sync = secureStorage(method: method, args: args)
+        case ("Biometrics", "isAvailable"):
+            sync = config.enableBiometric ? .success(biometricContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)) : failure("CAPABILITY_DISABLED", "Biometric authentication is disabled")
+        case ("Biometrics", "getBiometricType"):
+            sync = config.enableBiometric ? .success(biometricType()) : failure("CAPABILITY_DISABLED", "Biometric authentication is disabled")
+        case ("Biometrics", "authenticate"):
+            guard config.enableBiometric else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Biometric authentication is disabled"), completion)
+                return
+            }
+            authenticate(requestToken: requestToken, args: args, completion: completion)
+            return
+        case ("Lifecycle", "getState"):
+            sync = .success(currentAppState())
+        case ("DeepLinks", "getInitialURL"):
+            if config.enableDeepLinks {
+                sync = .success(claimInitialDeepLink().map(deepLinkData) ?? NSNull())
+            } else {
+                sync = failure("CAPABILITY_DISABLED", "Deep links are disabled")
+            }
+        case ("Database", _):
+            guard config.enableLocalDatabase else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Local database is disabled"), completion)
+                return
+            }
+            databaseQueue.async { complete(requestToken, database(method: method, args: args), completion) }
+            return
+        case ("Notifications", _):
+            guard config.enableLocalNotifications else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Local notifications are disabled"), completion)
+                return
+            }
+            notifications(requestToken: requestToken, method: method, args: args, completion: completion)
+            return
+        default:
+            sync = failure("UNKNOWN_ACTION", "Unsupported native API")
+        }
+        complete(requestToken, sync ?? failure("UNKNOWN_ACTION", "Unsupported native API"), completion)
+    }
+
+    static func cancel(requestToken: String) {
+        cancellationLock.lock()
+        cancelledRequests.insert(requestToken)
+        let context = biometricContexts.removeValue(forKey: requestToken)
+        cancellationLock.unlock()
+        context?.invalidate()
+    }
+
+    private static func claimInitialDeepLink() -> URL? {
+        cancellationLock.lock()
+        defer { cancellationLock.unlock() }
+        guard !initialDeepLinkClaimed else { return nil }
+        initialDeepLinkClaimed = true
+        return DeepLinkManager.shared.getInitialURL()
+    }
+
+    private static func complete(
+        _ requestToken: String,
+        _ result: Result<Any, CraftNativeActionError>,
+        _ completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+    ) {
+        DispatchQueue.main.async {
+            cancellationLock.lock()
+            let cancelled = cancelledRequests.remove(requestToken) != nil
+            cancellationLock.unlock()
+            if !cancelled { completion(result) }
+        }
+    }
+
+    private static func storage(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+        if method == "clear" {
+            for key in UserDefaults.standard.dictionaryRepresentation().keys where key.hasPrefix(storagePrefix) {
+                UserDefaults.standard.removeObject(forKey: key)
+            }
+            return .success(true)
+        }
+        if method == "keys" {
+            let keys = UserDefaults.standard.dictionaryRepresentation().keys
+                .filter { $0.hasPrefix(storagePrefix) }
+                .map { String($0.dropFirst(storagePrefix.count)) }
+                .sorted()
+            return .success(keys)
+        }
+        guard let key = validKey(args.first) else { return failure("INVALID_ARGUMENT", "Storage needs a non-empty key") }
+        let defaultsKey = storagePrefix + key
+        switch method {
+        case "get":
+            guard let data = UserDefaults.standard.data(forKey: defaultsKey) else { return .success(NSNull()) }
+            do {
+                return .success(try JSONSerialization.jsonObject(with: data, options: [.fragmentsAllowed]))
+            } catch {
+                return failure("STORAGE_CORRUPT", "Stored value is not valid JSON")
+            }
+        case "set":
+            guard args.count == 2 else { return failure("INVALID_ARGUMENT", "Storage.set needs a key and value") }
+            do {
+                let data = try JSONSerialization.data(withJSONObject: args[1], options: [.fragmentsAllowed])
+                UserDefaults.standard.set(data, forKey: defaultsKey)
+                return .success(true)
+            } catch {
+                return failure("INVALID_ARGUMENT", "Storage values must be JSON serializable")
+            }
+        case "remove":
+            UserDefaults.standard.removeObject(forKey: defaultsKey)
+            return .success(true)
+        default:
+            return failure("UNKNOWN_ACTION", "Unsupported Storage method")
+        }
+    }
+
+    private static func secureStorage(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+        let service = "dev.craft.native.secure"
+        if method == "clear" {
+            let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service]
+            let status = SecItemDelete(query as CFDictionary)
+            guard status == errSecSuccess || status == errSecItemNotFound else {
+                return failure("SECURE_STORAGE_ERROR", "Secure storage could not be cleared")
+            }
+            return .success(true)
+        }
+        guard let key = validKey(args.first) else { return failure("INVALID_ARGUMENT", "Secure storage needs a non-empty key") }
+        let base: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: key,
+        ]
+        switch method {
+        case "set":
+            guard args.count == 2, let value = args[1] as? String else {
+                return failure("INVALID_ARGUMENT", "SecureStorage.set needs a key and string value")
+            }
+            var query = base
+            query[kSecValueData as String] = Data(value.utf8)
+            query[kSecAttrAccessible as String] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+            let removed = SecItemDelete(base as CFDictionary)
+            guard removed == errSecSuccess || removed == errSecItemNotFound else {
+                return failure("SECURE_STORAGE_ERROR", "Secure storage could not be replaced (\(removed))")
+            }
+            let status = SecItemAdd(query as CFDictionary, nil)
+            return status == errSecSuccess ? .success(true) : failure("SECURE_STORAGE_ERROR", "Secure storage could not be written (\(status))")
+        case "get":
+            var query = base
+            query[kSecReturnData as String] = true
+            query[kSecMatchLimit as String] = kSecMatchLimitOne
+            var result: AnyObject?
+            let status = SecItemCopyMatching(query as CFDictionary, &result)
+            if status == errSecItemNotFound { return .success(NSNull()) }
+            guard status == errSecSuccess, let data = result as? Data else {
+                return failure("SECURE_STORAGE_ERROR", "Secure storage could not be read")
+            }
+            return .success(String(decoding: data, as: UTF8.self))
+        case "remove":
+            let status = SecItemDelete(base as CFDictionary)
+            return status == errSecSuccess || status == errSecItemNotFound ? .success(true) : failure("SECURE_STORAGE_ERROR", "Secure storage could not be removed")
+        default:
+            return failure("UNKNOWN_ACTION", "Unsupported SecureStorage method")
+        }
+    }
+
+    private static func biometricContext() -> LAContext {
+        let context = LAContext()
+        context.localizedCancelTitle = "Cancel"
+        return context
+    }
+
+    private static func biometricType() -> String {
+        let context = biometricContext()
+        _ = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
+        switch context.biometryType {
+        case .faceID: return "faceId"
+        case .touchID: return "touchId"
+        default: return "none"
+        }
+    }
+
+    private static func authenticate(
+        requestToken: String,
+        args: [Any],
+        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+    ) {
+        let reason = (args.first as? String).flatMap { $0.isEmpty ? nil : $0 } ?? "Authenticate to continue"
+        let context = biometricContext()
+        cancellationLock.lock()
+        biometricContexts[requestToken] = context
+        cancellationLock.unlock()
+        context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: reason) { result, error in
+            cancellationLock.lock()
+            biometricContexts.removeValue(forKey: requestToken)
+            cancellationLock.unlock()
+            if result { complete(requestToken, .success(true), completion) }
+            else { complete(requestToken, failure("AUTHENTICATION_FAILED", error?.localizedDescription ?? "Biometric authentication failed"), completion) }
+        }
+    }
+
+    private static func database(method: String, args: [Any]) -> Result<Any, CraftNativeActionError> {
+        guard openDatabase() else { return failure("DATABASE_ERROR", "Could not open the local database") }
+        switch method {
+        case "execute":
+            guard let sql = args.first as? String, !sql.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                return failure("INVALID_ARGUMENT", "Database.execute needs a SQL statement")
+            }
+            return execute(sql: sql, params: args.count > 1 ? args[1] as? [Any] ?? [] : [])
+        case "query":
+            guard let sql = args.first as? String, !sql.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                return failure("INVALID_ARGUMENT", "Database.query needs a SQL statement")
+            }
+            return query(sql: sql, params: args.count > 1 ? args[1] as? [Any] ?? [] : [])
+        case "beginTransaction": return transaction(sql: "BEGIN TRANSACTION")
+        case "commit": return transaction(sql: "COMMIT")
+        case "rollback": return transaction(sql: "ROLLBACK")
+        default: return failure("UNKNOWN_ACTION", "Unsupported Database method")
+        }
+    }
+
+    private static func transaction(sql: String) -> Result<Any, CraftNativeActionError> {
+        switch execute(sql: sql, params: []) {
+        case .success: return .success(true)
+        case .failure(let error): return .failure(error)
+        }
+    }
+
+    private static func openDatabase() -> Bool {
+        if database != nil { return true }
+        guard let directory = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else { return false }
+        do { try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) } catch { return false }
+        let path = directory.appendingPathComponent("craft-native.sqlite").path
+        if sqlite3_open(path, &database) != SQLITE_OK {
+            if database != nil { sqlite3_close(database) }
+            database = nil
+            return false
+        }
+        sqlite3_busy_timeout(database, 5_000)
+        return true
+    }
+
+    private static func bind(_ params: [Any], to statement: OpaquePointer?) -> Bool {
+        for (offset, value) in params.enumerated() {
+            let index = Int32(offset + 1)
+            let code: Int32
+            switch value {
+            case is NSNull: code = sqlite3_bind_null(statement, index)
+            case let string as String: code = sqlite3_bind_text(statement, index, string, -1, sqliteTransient)
+            case let number as NSNumber:
+                if CFGetTypeID(number) == CFBooleanGetTypeID() {
+                    code = sqlite3_bind_int64(statement, index, number.boolValue ? 1 : 0)
+                } else if number.doubleValue.rounded() == number.doubleValue {
+                    code = sqlite3_bind_int64(statement, index, number.int64Value)
+                } else {
+                    code = sqlite3_bind_double(statement, index, number.doubleValue)
+                }
+            default: return false
+            }
+            if code != SQLITE_OK { return false }
+        }
+        return true
+    }
+
+    private static func execute(sql: String, params: [Any]) -> Result<Any, CraftNativeActionError> {
+        var statement: OpaquePointer?
+        guard sqlite3_prepare_v2(database, sql, -1, &statement, nil) == SQLITE_OK else { return databaseFailure() }
+        defer { sqlite3_finalize(statement) }
+        guard bind(params, to: statement) else { return failure("INVALID_ARGUMENT", "Database parameters must be strings, numbers, booleans, or null") }
+        guard sqlite3_step(statement) == SQLITE_DONE else { return databaseFailure() }
+        return .success(["rowsAffected": Int(sqlite3_changes(database)), "lastInsertId": Int(sqlite3_last_insert_rowid(database))])
+    }
+
+    private static func query(sql: String, params: [Any]) -> Result<Any, CraftNativeActionError> {
+        var statement: OpaquePointer?
+        guard sqlite3_prepare_v2(database, sql, -1, &statement, nil) == SQLITE_OK else { return databaseFailure() }
+        defer { sqlite3_finalize(statement) }
+        guard bind(params, to: statement) else { return failure("INVALID_ARGUMENT", "Database parameters must be strings, numbers, booleans, or null") }
+        var rows: [[String: Any]] = []
+        while true {
+            let step = sqlite3_step(statement)
+            if step == SQLITE_DONE { return .success(rows) }
+            guard step == SQLITE_ROW else { return databaseFailure() }
+            var row: [String: Any] = [:]
+            for column in 0..<sqlite3_column_count(statement) {
+                let name = String(cString: sqlite3_column_name(statement, column))
+                switch sqlite3_column_type(statement, column) {
+                case SQLITE_INTEGER: row[name] = Int(sqlite3_column_int64(statement, column))
+                case SQLITE_FLOAT: row[name] = sqlite3_column_double(statement, column)
+                case SQLITE_TEXT: row[name] = sqlite3_column_text(statement, column).map { String(cString: $0) } ?? ""
+                case SQLITE_BLOB:
+                    let length = Int(sqlite3_column_bytes(statement, column))
+                    row[name] = sqlite3_column_blob(statement, column).map { Data(bytes: $0, count: length).base64EncodedString() } ?? ""
+                default: row[name] = NSNull()
+                }
+            }
+            rows.append(row)
+        }
+    }
+
+    private static func databaseFailure() -> Result<Any, CraftNativeActionError> {
+        let message = database.map { String(cString: sqlite3_errmsg($0)) } ?? "Database unavailable"
+        return failure("DATABASE_ERROR", message)
+    }
+
+    private static func notifications(
+        requestToken: String,
+        method: String,
+        args: [Any],
+        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+    ) {
+        let center = UNUserNotificationCenter.current()
+        switch method {
+        case "cancel":
+            guard let id = validKey(args.first) else {
+                complete(requestToken, failure("INVALID_ARGUMENT", "Notifications.cancel needs an id"), completion)
+                return
+            }
+            center.removePendingNotificationRequests(withIdentifiers: [id])
+            complete(requestToken, .success(true), completion)
+        case "cancelAll":
+            center.removeAllPendingNotificationRequests()
+            complete(requestToken, .success(true), completion)
+        case "pending":
+            center.getPendingNotificationRequests { requests in
+                complete(requestToken, .success(requests.map { request in
+                    ["id": request.identifier, "title": request.content.title, "body": request.content.body]
+                }), completion)
+            }
+        case "schedule":
+            guard let value = args.first as? [String: Any], let title = value["title"] as? String, !title.isEmpty else {
+                complete(requestToken, failure("INVALID_ARGUMENT", "Notifications.schedule needs a title"), completion)
+                return
+            }
+            center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, authorizationError in
+                guard authorizationError == nil, granted else {
+                    complete(requestToken, failure("PERMISSION_DENIED", authorizationError?.localizedDescription ?? "Notification permission denied"), completion)
+                    return
+                }
+                let content = UNMutableNotificationContent()
+                content.title = title
+                content.body = value["body"] as? String ?? ""
+                content.sound = .default
+                if let data = value["data"] as? [String: Any] { content.userInfo = data }
+                if let badge = value["badge"] as? NSNumber { content.badge = badge }
+                let id = (value["id"] as? String).flatMap { validKey($0) } ?? UUID().uuidString
+                let delay = (value["delay"] as? NSNumber)?.doubleValue
+                let trigger = delay.map { UNTimeIntervalNotificationTrigger(timeInterval: max($0 / 1_000, 1), repeats: false) }
+                center.add(UNNotificationRequest(identifier: id, content: content, trigger: trigger)) { addError in
+                    if let addError = addError {
+                        complete(requestToken, failure("NOTIFICATION_ERROR", addError.localizedDescription), completion)
+                    } else {
+                        complete(requestToken, .success(id), completion)
+                    }
+                }
+            }
+        default:
+            complete(requestToken, failure("UNKNOWN_ACTION", "Unsupported Notifications method"), completion)
+        }
+    }
+
+    static func deepLinkData(_ url: URL) -> [String: Any] {
+        let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
+        return [
+            "url": url.absoluteString,
+            "scheme": url.scheme ?? "",
+            "host": url.host ?? "",
+            "path": url.path,
+            "query": url.query ?? "",
+            "queryParams": Dictionary(uniqueKeysWithValues: (components?.queryItems ?? []).map { ($0.name, $0.value ?? "") }),
+        ]
+    }
+
     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()
+        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()
         }
     }
 
+    static func currentAppState() -> String {
+        switch UIApplication.shared.applicationState {
+        case .active: return "active"
+        case .inactive: return "inactive"
+        case .background: return "background"
+        @unknown default: return "inactive"
+        }
+    }
+
+    private static func validKey(_ value: Any?) -> String? {
+        guard let key = value as? String, !key.isEmpty, key.count <= 512, !key.contains("\0") else { return nil }
+        return key
+    }
+
+    private static func error(_ code: String, _ message: String) -> CraftNativeActionError {
+        CraftNativeActionError(code: code, message: message)
+    }
+
+    private static func failure(_ code: String, _ message: String) -> Result<Any, CraftNativeActionError> {
+        .failure(error(code, message))
+    }
+
     private static func deviceInfo() -> [String: Any] {
         let device = UIDevice.current
         let screen = UIScreen.main
@@ -75,19 +510,25 @@ enum CraftNativeActions {
         }
         return [
             "platform": "ios",
+            "osVersion": device.systemVersion,
             "model": device.model,
+            "manufacturer": "Apple",
+            "deviceId": device.identifierForVendor?.uuidString ?? "",
+            "isTablet": device.userInterfaceIdiom == .pad,
+            "screen": ["width": screen.bounds.width, "height": screen.bounds.height, "scale": screen.scale],
+            "battery": ["level": device.batteryLevel, "isCharging": device.batteryState == .charging || device.batteryState == .full],
+            "locale": Locale.current.identifier,
+            "timezone": TimeZone.current.identifier,
+            "isSimulator": isSimulator,
             "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

@@ -3,6 +3,8 @@ import JavaScriptCore
 import SwiftUI
 import UIKit
 
+private let craftNativeCapabilityTimeoutMilliseconds = 30_000
+
 /// 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.
@@ -83,6 +85,11 @@ final class CraftNativeScreenController: UIViewController {
     private var flatListRows: [ObjectIdentifier: [String: RenderedNode]] = [:]
     private var flatListOwners: [String: String] = [:]
     private let mutationDocument = CraftNativeMutationDocument()
+    private let capabilityScope = UUID().uuidString
+    private var pendingCapabilityRequests = Set<String>()
+    private var pendingCapabilityDeadlines: [String: DispatchWorkItem] = [:]
+    private var lifecycleObservers: [NSObjectProtocol] = []
+    private var deepLinkListener: UUID?
 
     init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:]) {
         self.config = config
@@ -97,6 +104,10 @@ final class CraftNativeScreenController: UIViewController {
 
     deinit {
         imageTasks.values.forEach { $0.cancel() }
+        pendingCapabilityDeadlines.values.forEach { $0.cancel() }
+        pendingCapabilityRequests.forEach { CraftNativeActions.cancel(requestToken: $0) }
+        lifecycleObservers.forEach(NotificationCenter.default.removeObserver)
+        if let deepLinkListener = deepLinkListener { DeepLinkManager.shared.removeNativeListener(deepLinkListener) }
     }
 
     override func viewDidLoad() {
@@ -116,6 +127,7 @@ final class CraftNativeScreenController: UIViewController {
         ])
         setupJavaScript()
         loadBundle()
+        observeNativeEvents()
     }
 
     private func setupJavaScript() {
@@ -130,10 +142,18 @@ final class CraftNativeScreenController: UIViewController {
             self?.receive(json)
         }
         jsContext.setObject(postMessage, forKeyedSubscript: "craftNativePostMessage" as NSString)
+        let capabilities = CraftNativeActions.capabilities(config: config)
+        let capabilityData = try? JSONSerialization.data(withJSONObject: capabilities)
+        let capabilityJSON = capabilityData.flatMap { String(data: $0, encoding: .utf8) } ?? "[]"
         jsContext.evaluateScript("""
             globalThis.__stxNativeCallback = null;
             globalThis.__stxNativeBridge = {
+                platform: "ios",
                 mutationProtocolVersion: 1,
+                capabilityProtocolVersion: \(craftNativeCapabilityProtocolVersion),
+                capabilityTimeoutMs: \(craftNativeCapabilityTimeoutMilliseconds),
+                capabilities: \(capabilityJSON),
+                initialAppState: "\(CraftNativeActions.currentAppState())",
                 postMessage: function(message) { craftNativePostMessage(message); },
                 onMessage: function(callback) { globalThis.__stxNativeCallback = callback; }
             };
@@ -156,6 +176,31 @@ final class CraftNativeScreenController: UIViewController {
         }
     }
 
+    private func observeNativeEvents() {
+        func observe(_ name: Notification.Name, state: String) {
+            lifecycleObservers.append(NotificationCenter.default.addObserver(
+                forName: name,
+                object: nil,
+                queue: .main
+            ) { [weak self] _ in self?.sendAppState(state) })
+        }
+        observe(UIApplication.didBecomeActiveNotification, state: "active")
+        observe(UIApplication.willResignActiveNotification, state: "inactive")
+        observe(UIApplication.didEnterBackgroundNotification, state: "background")
+        sendAppState(CraftNativeActions.currentAppState())
+        deepLinkListener = DeepLinkManager.shared.addNativeListener { [weak self] url, initial in
+            guard let self = self, self.navigationController?.topViewController === self else { return }
+            var payload = CraftNativeActions.deepLinkData(url)
+            payload["initial"] = initial
+            self.send(type: "DEEP_LINK", payload: payload)
+        }
+    }
+
+    private func sendAppState(_ state: String) {
+        guard navigationController?.topViewController === self else { return }
+        send(type: "APP_STATE", payload: ["state": state])
+    }
+
     private func showError(_ message: String) {
         let label = UILabel()
         label.numberOfLines = 0
@@ -219,30 +264,56 @@ final class CraftNativeScreenController: UIViewController {
         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
+            let requestToken = "\(capabilityScope)/\(id)"
+            pendingCapabilityRequests.insert(requestToken)
+            let deadline = DispatchWorkItem { [weak self] in
+                guard let self = self, self.pendingCapabilityRequests.remove(requestToken) != nil else { return }
+                self.pendingCapabilityDeadlines.removeValue(forKey: requestToken)
+                CraftNativeActions.cancel(requestToken: requestToken)
+                self.send(type: "API_ERROR", payload: [
+                    "version": craftNativeCapabilityProtocolVersion,
+                    "requestId": id,
+                    "code": "TIMEOUT",
+                    "message": "Native API request timed out",
+                ], correlationId: id)
             }
-            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)
+            pendingCapabilityDeadlines[requestToken] = deadline
+            DispatchQueue.main.asyncAfter(
+                deadline: .now() + .milliseconds(craftNativeCapabilityTimeoutMilliseconds),
+                execute: deadline
+            )
+            CraftNativeActions.perform(
+                requestToken: requestToken,
+                version: payload["version"] as? Int ?? craftNativeCapabilityProtocolVersion,
+                module: payload["module"] as? String ?? "",
+                method: payload["method"] as? String ?? "",
+                args: args,
+                config: config
+            ) { [weak self] answer in
+                guard let self = self, self.pendingCapabilityRequests.remove(requestToken) != nil else { return }
+                self.pendingCapabilityDeadlines.removeValue(forKey: requestToken)?.cancel()
+                switch answer {
+                case .success(let data):
+                    self.send(type: "API_RESPONSE", payload: [
+                        "version": craftNativeCapabilityProtocolVersion,
+                        "requestId": id,
+                        "data": data,
+                    ], correlationId: id)
+                case .failure(let error):
+                    self.send(type: "API_ERROR", payload: [
+                        "version": craftNativeCapabilityProtocolVersion,
+                        "requestId": id,
+                        "code": error.code,
+                        "message": error.message,
+                    ], correlationId: id)
+                }
             }
+        case "API_CANCEL":
+            guard let id = payload["requestId"] as? String else { return }
+            let requestToken = "\(capabilityScope)/\(id)"
+            pendingCapabilityRequests.remove(requestToken)
+            pendingCapabilityDeadlines.removeValue(forKey: requestToken)?.cancel()
+            CraftNativeActions.cancel(requestToken: requestToken)
         default:
             break
         }

package/templates/Info.plist.template

@@ -43,6 +43,7 @@
     <false/>
 {{USAGE_DESCRIPTIONS}}
 {{URL_TYPES}}
+{{APP_BOUND_DOMAINS}}
 {{BACKGROUND_MODES}}
 {{LIVE_ACTIVITY_SUPPORT}}
     <key>NSAppTransportSecurity</key>