craft-native 0.0.395 → 0.0.408

package/dist/macos/templates/CraftMacRuntime.swift

@@ -1,9 +1,73 @@
 import AppKit
 import ZigJS
 import Foundation
+import Security
+
+/// The macOS Keychain behind `craft.secureStorage`: one generic password per
+/// key, under a service named for the app. The data-protection keychain is
+/// used when the app is signed for it (a Mac App Store build, which carries
+/// the application-identifier / keychain-access-groups entitlements); an
+/// unsigned or ad-hoc development build has none and uses the login keychain,
+/// so the same code runs both.
+enum CraftMacKeychain {
+    static var service: String { (Bundle.main.bundleIdentifier ?? "dev.craft.native") + ".secure" }
+    /// Whether this process carries the keychain-access-groups entitlement, which
+    /// is what the data-protection keychain requires. Decided once, from the
+    /// signature, so reads and writes always use the same keychain: a failure
+    /// based fallback let a write land in the login keychain and the next
+    /// launch read an empty data-protection one.
+    private static var dataProtection: Bool = {
+        guard let task = SecTaskCreateFromSelf(nil) else { return false }
+        return SecTaskCopyValueForEntitlement(task, "keychain-access-groups" as CFString, nil) != nil
+            || SecTaskCopyValueForEntitlement(task, "com.apple.application-identifier" as CFString, nil) != nil
+    }()
+    private static func base(_ account: String?) -> [String: Any] {
+        var query: [String: Any] = [kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service]
+        if let account { query[kSecAttrAccount as String] = account }
+        if dataProtection { query[kSecUseDataProtectionKeychain as String] = true }
+        return query
+    }
+    private static func run(_ account: String?, _ body: ([String: Any]) -> OSStatus) -> OSStatus { body(base(account)) }
+    static func get(_ account: String) -> String? {
+        var result: AnyObject?
+        let status = run(account) { query in
+            var query = query; query[kSecReturnData as String] = true; query[kSecMatchLimit as String] = kSecMatchLimitOne
+            // Never stop the main thread on a Keychain permission prompt: an older item's
+            // access list does not trust a rebuilt app, and the prompt (with no window behind
+            // it) would hang the launch. With interaction off the read fails instead, the
+            // user signs in again, and the new item is trusted. Neither LAContext nor
+            // kSecUseAuthenticationUI stops a login-keychain access-list prompt; this does.
+            SecKeychainSetUserInteractionAllowed(false)
+            defer { SecKeychainSetUserInteractionAllowed(true) }
+            return SecItemCopyMatching(query as CFDictionary, &result)
+        }
+        guard status == errSecSuccess, let data = result as? Data else { return nil }
+        return String(decoding: data, as: UTF8.self)
+    }
+    @discardableResult static func set(_ account: String, _ value: String) -> Bool {
+        _ = run(account) { SecItemDelete($0 as CFDictionary) }
+        let status = run(account) { query in
+            var query = query; query[kSecValueData as String] = Data(value.utf8); query[kSecAttrAccessible as String] = kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+            return SecItemAdd(query as CFDictionary, nil)
+        }
+        return status == errSecSuccess
+    }
+    @discardableResult static func remove(_ account: String?) -> Bool {
+        let status = run(account) { SecItemDelete($0 as CFDictionary) }
+        return status == errSecSuccess || status == errSecItemNotFound
+    }
+}
 
 /// One zig-js context per STX window. No DOM and no browser view.
 final class CraftMacRuntime {
+    /// What this host offers a screen. `web` (tabs in a `<WebView>`) only in a build made with `webkit: true`.
+    static var capabilities: [String] {
+        var list = ["desktop", "fetch", "eventStream", "storage", "secureStorage", "clipboard", "dialog", "linking", "haptics", "notifications"]
+        #if CRAFT_WEBKIT
+        list.append("web")
+        #endif
+        return list
+    }
     let context = ZigJSContext()!
     let route: String
     let network: CraftMacNetwork
@@ -39,6 +103,18 @@ final class CraftMacRuntime {
             if level == "error" { self?.errors.append(text) }
             fputs("[stx \(level)] \(text)\n", stderr)
         }
+        // The synchronous halves of craft.storage and craft.secureStorage
+        // (getSync/setSync), which the stx runtime keeps when the host has them.
+        let storageGet: @convention(block) (String) -> String? = { key in
+            guard let value = UserDefaults.standard.object(forKey: "craft.native." + key) else { return nil }
+            if let text = value as? String { return text }
+            return (try? JSONSerialization.data(withJSONObject: value, options: [.fragmentsAllowed])).flatMap { String(data: $0, encoding: .utf8) }
+        }
+        let storageSet: @convention(block) (String, String) -> Void = { key, json in UserDefaults.standard.set(json, forKey: "craft.native." + key) }
+        let secureGet: @convention(block) (String) -> String? = { key in CraftMacKeychain.get(key) }
+        context.setObject(storageGet, forKeyedSubscript: "craftNativeStorageGet" as NSString)
+        context.setObject(storageSet, forKeyedSubscript: "craftNativeStorageSet" as NSString)
+        context.setObject(secureGet, forKeyedSubscript: "craftNativeSecureGet" as NSString)
         context.setObject(post, forKeyedSubscript: "craftNativePostMessage" as NSString)
         context.setObject(schedule, forKeyedSubscript: "craftNativeScheduleTimer" as NSString)
         context.setObject(cancel, forKeyedSubscript: "craftNativeCancelTimer" as NSString)
@@ -48,7 +124,8 @@ final class CraftMacRuntime {
         let info = Bundle.main.infoDictionary ?? [:]
         let bridge: [String: Any] = [
             "platform": "macos", "mutationProtocolVersion": 1, "capabilityProtocolVersion": 1,
-            "capabilityTimeoutMs": 30_000, "capabilities": ["desktop", "fetch", "eventStream", "storage", "clipboard", "dialog", "linking", "haptics", "notifications"],
+            "capabilityTimeoutMs": 30_000, "capabilities": Self.capabilities,
+            "sessionTokenKey": "auth.token",
             "initialAppState": "active", "colorScheme": CraftMacColor.isDark ? "dark" : "light",
             "appURL": network.base.absoluteString, "appVersion": info["CFBundleShortVersionString"] as? String ?? "", "appBuild": info["CFBundleVersion"] as? String ?? ""
         ]
@@ -58,6 +135,12 @@ final class CraftMacRuntime {
         globalThis.__stxNativeBridge = \(bridgeJSON);
         __stxNativeBridge.postMessage = function(text) { craftNativePostMessage(text); };
         __stxNativeBridge.onMessage = function(callback) { globalThis.__stxNativeCallback = callback; };
+        globalThis.craft = globalThis.craft || {};
+        craft.storage = {
+            getSync: function(key) { var raw = craftNativeStorageGet(String(key)); if (raw === null || raw === undefined) return null; try { return JSON.parse(raw); } catch (e) { return raw; } },
+            setSync: function(key, value) { craftNativeStorageSet(String(key), JSON.stringify(value === undefined ? null : value)); }
+        };
+        craft.secureStorage = { getSync: function(key) { var value = craftNativeSecureGet(String(key)); return value === null || value === undefined ? null : value; } };
         globalThis.console = {};
         ['log','info','warn','error','debug'].forEach(function(level) {
             console[level] = function() { craftNativeLog(level, Array.from(arguments).map(String).join(' ')); };
@@ -88,6 +171,9 @@ final class CraftMacRuntime {
 
     func dispose() {
         guard !disposed else { return }
+        #if CRAFT_WEBKIT
+        CraftMacWebTabs.shared.closeAll(owner: self)
+        #endif
         context.objectForKeyedSubscript("__stxNativeUnmount")?.call(withArguments: [])
         disposed = true
         timers.values.forEach { $0.cancel() }; timers.removeAll()
@@ -138,6 +224,14 @@ final class CraftMacRuntime {
         }
     }
 
+    /// `craft.session.onChange`: the sign-in token moved, in any window.
+    private func sessionChanged(_ key: String, token: String?, previous: String?) {
+        guard key == "auth.token", token != previous else { return }
+        for scene in CraftMacApplication.shared.scenes.values {
+            scene.runtime.send("SESSION_CHANGED", ["key": key, "token": token ?? NSNull(), "previous": previous ?? NSNull()])
+        }
+    }
+
     func answer(_ id: String, _ value: Any = NSNull()) {
         tasks.removeValue(forKey: id)
         send("API_RESPONSE", ["version": 1, "requestId": id, "data": value], correlation: id)
@@ -168,6 +262,22 @@ final class CraftMacRuntime {
                 }
             }
             tasks[id] = task; task.resume()
+        case "SecureStorage":
+            if method == "clear" { CraftMacKeychain.remove(nil); answer(id, true); return }
+            guard let key = args.first as? String, !key.isEmpty else { fail(id, "INVALID_ARGUMENT", "Secure storage needs a non-empty key"); return }
+            switch method {
+            case "get": answer(id, CraftMacKeychain.get(key) ?? NSNull())
+            case "set":
+                guard args.count == 2, let value = args[1] as? String else { fail(id, "INVALID_ARGUMENT", "SecureStorage.set needs a key and string value"); return }
+                let previous = CraftMacKeychain.get(key)
+                guard CraftMacKeychain.set(key, value) else { fail(id, "SECURE_STORAGE_ERROR", "Secure storage could not be written"); return }
+                sessionChanged(key, token: value, previous: previous); answer(id, true)
+            case "remove":
+                let previous = CraftMacKeychain.get(key)
+                guard CraftMacKeychain.remove(key) else { fail(id, "SECURE_STORAGE_ERROR", "Secure storage could not be removed"); return }
+                sessionChanged(key, token: nil, previous: previous); answer(id, true)
+            default: fail(id, "UNKNOWN_ACTION", "Unsupported SecureStorage method")
+            }
         case "Storage":
             let prefix = "craft.native."
             let key = prefix + (args.first as? String ?? "")
@@ -191,6 +301,9 @@ final class CraftMacRuntime {
         case "Linking":
             guard let text = args.first as? String, let url = URL(string: text), let scheme = url.scheme, ["https", "http", "imessage", "sms", "mailto", "x-apple.systempreferences"].contains(scheme) else { fail(id, "INVALID_ARGUMENT", "Unsupported URL scheme"); return }
             answer(id, method == "canOpenURL" ? NSWorkspace.shared.urlForApplication(toOpen: url) != nil : NSWorkspace.shared.open(url))
+        #if CRAFT_WEBKIT
+        case "Web": CraftMacWebTabs.shared.perform(method, args, owner: self, answer: { [weak self] value in self?.answer(id, value) }, fail: { [weak self] code, message in self?.fail(id, code, message) })
+        #endif
         case "Desktop": CraftMacApplication.shared.perform(method, args: args, scene: scene, reply: { [weak self] value in self?.answer(id, value) })
         case "Notifications": CraftMacApplication.shared.notification(method, options: options, reply: { [weak self] value in self?.answer(id, value) })
         default: fail(id, "CAPABILITY_DISABLED", "Unsupported native capability \(module).\(method)")

package/dist/macos/templates/CraftMacWebView.swift

@@ -0,0 +1,416 @@
+#if CRAFT_WEBKIT
+import AppKit
+import CryptoKit
+import WebKit
+
+// Web content for the AppKit host: one WKWebView per tab, for apps built with
+// `buildMacOSNative({ webkit: true })` (a browser, a help viewer). The app's
+// own screens still render as native controls through zig-js; only the pages
+// a `<WebView>` shows are web content. Without the flag none of this is
+// compiled and the host links no WebKit at all.
+//
+// Tabs belong to `CraftMacWebTabs`, not to the view showing them, so a tab
+// keeps its page while the screen re-renders, moves between split panes, or
+// is not on screen at all. A `<WebView tab="...">` decides where it appears.
+
+/// One WKWebViewConfiguration per profile. Every tab of a profile shares its
+/// website data store (cookies, storage, cache); profiles never share one.
+final class CraftMacWebProfiles {
+    static let shared = CraftMacWebProfiles()
+    private var configurations: [String: WKWebViewConfiguration] = [:]
+
+    /// Safari's own suffix, so sites serve the desktop Safari experience rather than an unknown WebKit embedder's.
+    static let userAgentSuffix: String = {
+        let safari = Bundle(path: "/Applications/Safari.app")?.infoDictionary?["CFBundleShortVersionString"] as? String ?? "26.0"
+        return "Version/\(safari) Safari/605.1.15"
+    }()
+
+    /// `ephemeral` keeps nothing on disk (a private window); named profiles persist under their own identifier.
+    func configuration(profile: String, ephemeral: Bool) -> WKWebViewConfiguration {
+        let key = (ephemeral ? "ephemeral:" : "") + profile
+        if let existing = configurations[key] { return existing.copy() as! WKWebViewConfiguration }
+        let configuration = WKWebViewConfiguration()
+        configuration.websiteDataStore = store(profile: profile, ephemeral: ephemeral)
+        configuration.applicationNameForUserAgent = Self.userAgentSuffix
+        configuration.preferences.isElementFullscreenEnabled = true
+        configuration.preferences.isFraudulentWebsiteWarningEnabled = true
+        configuration.allowsAirPlayForMediaPlayback = true
+        configurations[key] = configuration
+        return configuration.copy() as! WKWebViewConfiguration
+    }
+
+    func store(profile: String, ephemeral: Bool) -> WKWebsiteDataStore {
+        if ephemeral { return .nonPersistent() }
+        if profile == "default" { return .default() }
+        if #available(macOS 14.0, *) { return WKWebsiteDataStore(forIdentifier: Self.identifier(profile)) }
+        return .default()
+    }
+
+    /// A stable UUID per profile name, so a profile finds its data again on every launch.
+    static func identifier(_ profile: String) -> UUID {
+        var bytes = Array(SHA256.hash(data: Data(("craft.web.profile:" + profile).utf8)).prefix(16))
+        bytes[6] = (bytes[6] & 0x0F) | 0x50; bytes[8] = (bytes[8] & 0x3F) | 0x80
+        return UUID(uuid: (bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7], bytes[8], bytes[9], bytes[10], bytes[11], bytes[12], bytes[13], bytes[14], bytes[15]))
+    }
+}
+
+/// A tab: its WKWebView, the screen it reports to, and the state it reports.
+final class CraftMacTab: NSObject, WKNavigationDelegate, WKUIDelegate {
+    let id: String
+    let profile: String
+    let ephemeral: Bool
+    let view: WKWebView
+    /// The window whose script hears this tab's events. Showing the tab in another window moves it there.
+    weak var owner: CraftMacRuntime?
+    private var observations: [NSKeyValueObservation] = []
+    private var statePending = false
+    private var lastFavicon = ""
+
+    init(id: String, profile: String, ephemeral: Bool, configuration: WKWebViewConfiguration, owner: CraftMacRuntime?) {
+        self.id = id; self.profile = profile; self.ephemeral = ephemeral; self.owner = owner
+        view = WKWebView(frame: .zero, configuration: configuration)
+        super.init()
+        view.navigationDelegate = self
+        view.uiDelegate = self
+        view.allowsBackForwardNavigationGestures = true
+        view.allowsMagnification = true
+        view.autoresizingMask = [.width, .height]
+        view.setAccessibilityIdentifier("web:\(id)")
+        // KVO fires once per property per change; a page load changes several at once.
+        // They are reported together, at most once per run-loop turn.
+        let report: (Any, Any) -> Void = { [weak self] _, _ in self?.scheduleState() }
+        observations = [
+            view.observe(\.title, changeHandler: report), view.observe(\.url, changeHandler: report),
+            view.observe(\.estimatedProgress, changeHandler: report), view.observe(\.isLoading, changeHandler: report),
+            view.observe(\.canGoBack, changeHandler: report), view.observe(\.canGoForward, changeHandler: report),
+            view.observe(\.hasOnlySecureContent, changeHandler: report), view.observe(\.themeColor, changeHandler: report),
+            view.observe(\.cameraCaptureState, changeHandler: report), view.observe(\.microphoneCaptureState, changeHandler: report),
+        ]
+    }
+
+    var state: [String: Any] {
+        var state: [String: Any] = [
+            "tab": id, "profile": profile, "private": ephemeral,
+            "title": view.title ?? "", "url": view.url?.absoluteString ?? "",
+            "progress": view.estimatedProgress, "loading": view.isLoading,
+            "canGoBack": view.canGoBack, "canGoForward": view.canGoForward,
+            "secure": view.hasOnlySecureContent, "zoom": view.pageZoom,
+            "camera": view.cameraCaptureState == .active, "microphone": view.microphoneCaptureState == .active,
+        ]
+        if let color = view.themeColor?.usingColorSpace(.sRGB) {
+            state["themeColor"] = String(format: "#%02x%02x%02x", Int(round(color.redComponent * 255)), Int(round(color.greenComponent * 255)), Int(round(color.blueComponent * 255)))
+        }
+        return state
+    }
+
+    func emit(_ type: String, _ detail: [String: Any] = [:]) {
+        var payload = detail; payload["tab"] = id; payload["type"] = type
+        owner?.send("CRAFT_EVENT", ["event": "craftWebView", "detail": payload])
+    }
+
+    private func scheduleState() {
+        guard !statePending else { return }
+        statePending = true
+        DispatchQueue.main.async { [weak self] in
+            guard let self else { return }
+            self.statePending = false
+            self.emit("state", self.state)
+        }
+    }
+
+    func close() {
+        observations.forEach { $0.invalidate() }; observations.removeAll()
+        view.stopLoading()
+        view.navigationDelegate = nil; view.uiDelegate = nil
+        view.removeFromSuperview()
+    }
+
+    // MARK: navigation
+
+    private static let pageSchemes: Set<String> = ["http", "https", "about", "data", "blob", "file"]
+
+    func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
+        guard let url = action.request.url else { decisionHandler(.cancel); return }
+        let scheme = url.scheme?.lowercased() ?? ""
+        if scheme == "javascript" { decisionHandler(.allow); return }
+        // mailto:, facetime:, zoommtg: and the like belong to other apps.
+        if !Self.pageSchemes.contains(scheme) {
+            if NSWorkspace.shared.urlForApplication(toOpen: url) != nil { NSWorkspace.shared.open(url) }
+            decisionHandler(.cancel); return
+        }
+        if action.shouldPerformDownload { decisionHandler(.download); return }
+        // ⌘-click (and middle click) opens the link in a new tab, as every browser does; the screen decides where.
+        if action.navigationType == .linkActivated, action.targetFrame?.isMainFrame ?? true,
+           action.modifierFlags.contains(.command) || action.buttonNumber == 2 {
+            emit("open", ["url": url.absoluteString, "background": !action.modifierFlags.contains(.shift), "reason": "modifier"])
+            decisionHandler(.cancel); return
+        }
+        decisionHandler(.allow)
+    }
+
+    func webView(_ webView: WKWebView, decidePolicyFor response: WKNavigationResponse, decisionHandler: @escaping (WKNavigationResponsePolicy) -> Void) {
+        let attachment = (response.response as? HTTPURLResponse)?.value(forHTTPHeaderField: "Content-Disposition")?.lowercased().hasPrefix("attachment") == true
+        decisionHandler(response.isForMainFrame && (attachment || !response.canShowMIMEType) ? .download : .allow)
+    }
+
+    func webView(_ webView: WKWebView, navigationAction: WKNavigationAction, didBecome download: WKDownload) { CraftMacDownloads.shared.adopt(download, tab: self) }
+    func webView(_ webView: WKWebView, navigationResponse: WKNavigationResponse, didBecome download: WKDownload) { CraftMacDownloads.shared.adopt(download, tab: self) }
+
+    func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) { emit("navigationStart", ["url": webView.url?.absoluteString ?? ""]) }
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        emit("navigationFinish", ["url": webView.url?.absoluteString ?? ""])
+        readFavicon()
+    }
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) { failed(error) }
+    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) { failed(error) }
+    private func failed(_ error: Error) {
+        let nsError = error as NSError
+        // A navigation replaced by another one, or turned into a download, is not a failure.
+        if nsError.domain == NSURLErrorDomain && nsError.code == NSURLErrorCancelled { return }
+        if nsError.domain == "WebKitErrorDomain" && nsError.code == 102 { return }
+        emit("navigationError", ["url": (nsError.userInfo[NSURLErrorFailingURLStringErrorKey] as? String) ?? view.url?.absoluteString ?? "", "code": nsError.code, "domain": nsError.domain, "message": nsError.localizedDescription])
+    }
+
+    /// The page's renderer died (out of memory, a crash). Reload it rather than leave a blank tab.
+    func webViewWebContentProcessDidTerminate(_ webView: WKWebView) {
+        emit("crashed", ["url": webView.url?.absoluteString ?? ""])
+        webView.reload()
+    }
+
+    /// The icon the page declares, else `/favicon.ico`. Read in an isolated world the page's scripts cannot see.
+    private func readFavicon() {
+        let script = """
+        (() => { const links = [...document.querySelectorAll('link[rel~="icon"], link[rel="apple-touch-icon"]')]
+          .map(l => ({ href: l.href, size: parseInt((l.sizes && l.sizes.value || '').split('x')[0]) || (l.rel.includes('apple') ? 180 : 16) }))
+          .filter(l => l.href).sort((a, b) => Math.abs(a.size - 32) - Math.abs(b.size - 32));
+          return links.length ? links[0].href : (location.protocol.startsWith('http') ? location.origin + '/favicon.ico' : '') })()
+        """
+        view.evaluateJavaScript(script, in: nil, in: .defaultClient) { [weak self] result in
+            guard let self, case .success(let value) = result, let href = value as? String, !href.isEmpty, href != self.lastFavicon else { return }
+            self.lastFavicon = href
+            self.emit("favicon", ["url": href])
+        }
+    }
+
+    // MARK: windows, dialogs, files
+
+    /// `window.open` and `target=_blank`. WebKit needs the new view right now, so the tab is
+    /// created here and announced; the screen adopts it by id like any other tab.
+    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for action: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        let child = CraftMacWebTabs.shared.make(profile: profile, ephemeral: ephemeral, configuration: configuration, owner: owner)
+        let popup = windowFeatures.width != nil || windowFeatures.height != nil
+        var detail: [String: Any] = ["child": child.id, "url": action.request.url?.absoluteString ?? "", "popup": popup, "reason": "script"]
+        if popup { detail["width"] = windowFeatures.width?.doubleValue ?? 0; detail["height"] = windowFeatures.height?.doubleValue ?? 0 }
+        emit("open", detail)
+        return child.view
+    }
+
+    func webViewDidClose(_ webView: WKWebView) { emit("close") }
+
+    func webView(_ webView: WKWebView, runJavaScriptAlertPanelWithMessage message: String, initiatedByFrame frame: WKFrameInfo, completionHandler: @escaping () -> Void) {
+        present(message, frame: frame, buttons: ["OK"]) { _, _ in completionHandler() }
+    }
+    func webView(_ webView: WKWebView, runJavaScriptConfirmPanelWithMessage message: String, initiatedByFrame frame: WKFrameInfo, completionHandler: @escaping (Bool) -> Void) {
+        present(message, frame: frame, buttons: ["OK", "Cancel"]) { response, _ in completionHandler(response == .alertFirstButtonReturn) }
+    }
+    func webView(_ webView: WKWebView, runJavaScriptTextInputPanelWithPrompt prompt: String, defaultText: String?, initiatedByFrame frame: WKFrameInfo, completionHandler: @escaping (String?) -> Void) {
+        present(prompt, frame: frame, buttons: ["OK", "Cancel"], input: defaultText ?? "") { response, text in completionHandler(response == .alertFirstButtonReturn ? text : nil) }
+    }
+    private func present(_ message: String, frame: WKFrameInfo, buttons: [String], input: String? = nil, done: @escaping (NSApplication.ModalResponse, String) -> Void) {
+        let alert = NSAlert()
+        alert.messageText = frame.securityOrigin.host.isEmpty ? "This page says" : "\(frame.securityOrigin.host) says"
+        alert.informativeText = message
+        buttons.forEach { alert.addButton(withTitle: $0) }
+        let field = input.map { value -> NSTextField in let field = NSTextField(string: value); field.frame = CGRect(x: 0, y: 0, width: 280, height: 24); return field }
+        alert.accessoryView = field
+        guard let window = view.window else { done(alert.runModal(), field?.stringValue ?? ""); return }
+        alert.beginSheetModal(for: window) { response in done(response, field?.stringValue ?? "") }
+    }
+
+    func webView(_ webView: WKWebView, runOpenPanelWith parameters: WKOpenPanelParameters, initiatedByFrame frame: WKFrameInfo, completionHandler: @escaping ([URL]?) -> Void) {
+        let panel = NSOpenPanel()
+        panel.allowsMultipleSelection = parameters.allowsMultipleSelection
+        panel.canChooseDirectories = parameters.allowsDirectories
+        panel.canChooseFiles = true
+        guard let window = view.window else { completionHandler(panel.runModal() == .OK ? panel.urls : nil); return }
+        panel.beginSheetModal(for: window) { response in completionHandler(response == .OK ? panel.urls : nil) }
+    }
+}
+
+/// Downloads started by any tab, saved to ~/Downloads under a name that never overwrites.
+final class CraftMacDownloads: NSObject, WKDownloadDelegate {
+    static let shared = CraftMacDownloads()
+    private struct Entry { let id: String; weak var tab: CraftMacTab?; var path: String; var observation: NSKeyValueObservation? }
+    private var entries: [ObjectIdentifier: Entry] = [:]
+    private var lastReport: [String: CFAbsoluteTime] = [:]
+
+    func adopt(_ download: WKDownload, tab: CraftMacTab) {
+        download.delegate = self
+        let id = UUID().uuidString
+        var entry = Entry(id: id, tab: tab, path: "")
+        entry.observation = download.progress.observe(\.fractionCompleted) { [weak self, weak download] _, _ in
+            guard let self, let download else { return }
+            DispatchQueue.main.async { self.report(download, state: "progress") }
+        }
+        entries[ObjectIdentifier(download)] = entry
+    }
+
+    func download(_ download: WKDownload, decideDestinationUsing response: URLResponse, suggestedFilename: String, completionHandler: @escaping (URL?) -> Void) {
+        let folder = FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask)[0]
+        let name = (suggestedFilename as NSString).lastPathComponent.isEmpty ? "download" : (suggestedFilename as NSString).lastPathComponent
+        var destination = folder.appendingPathComponent(name), copy = 1
+        let stem = (name as NSString).deletingPathExtension, ext = (name as NSString).pathExtension
+        while FileManager.default.fileExists(atPath: destination.path) {
+            copy += 1
+            destination = folder.appendingPathComponent(ext.isEmpty ? "\(stem) \(copy)" : "\(stem) \(copy).\(ext)")
+        }
+        entries[ObjectIdentifier(download)]?.path = destination.path
+        report(download, state: "started")
+        completionHandler(destination)
+    }
+
+    func downloadDidFinish(_ download: WKDownload) { report(download, state: "finished"); finish(download) }
+    func download(_ download: WKDownload, didFailWithError error: Error, resumeData: Data?) {
+        report(download, state: "failed", extra: ["message": error.localizedDescription])
+        finish(download)
+    }
+
+    /// Progress is reported at most every 250ms; a start, finish or failure always is.
+    private func report(_ download: WKDownload, state: String, extra: [String: Any] = [:]) {
+        guard let entry = entries[ObjectIdentifier(download)] else { return }
+        let now = CFAbsoluteTimeGetCurrent()
+        if state == "progress", now - (lastReport[entry.id] ?? 0) < 0.25 { return }
+        lastReport[entry.id] = now
+        var detail: [String: Any] = ["id": entry.id, "state": state, "path": entry.path, "name": (entry.path as NSString).lastPathComponent,
+            "url": download.originalRequest?.url?.absoluteString ?? "",
+            "received": download.progress.completedUnitCount, "total": download.progress.totalUnitCount, "fraction": download.progress.fractionCompleted]
+        extra.forEach { detail[$0.key] = $0.value }
+        entry.tab?.emit("download", detail)
+    }
+
+    private func finish(_ download: WKDownload) {
+        if let entry = entries.removeValue(forKey: ObjectIdentifier(download)) { entry.observation?.invalidate(); lastReport.removeValue(forKey: entry.id) }
+    }
+}
+
+/// Every tab, by id, and the screens' `Web` capability module.
+final class CraftMacWebTabs {
+    static let shared = CraftMacWebTabs()
+    private(set) var tabs: [String: CraftMacTab] = [:]
+    private let hosts = NSHashTable<CraftMacWebHost>.weakObjects()
+
+    @discardableResult
+    func make(id: String? = nil, profile: String = "default", ephemeral: Bool = false, configuration: WKWebViewConfiguration? = nil, owner: CraftMacRuntime?) -> CraftMacTab {
+        let id = id.flatMap { $0.isEmpty ? nil : $0 } ?? UUID().uuidString.lowercased()
+        if let existing = tabs[id] { return existing }
+        let tab = CraftMacTab(id: id, profile: profile, ephemeral: ephemeral,
+            configuration: configuration ?? CraftMacWebProfiles.shared.configuration(profile: profile, ephemeral: ephemeral), owner: owner)
+        tabs[id] = tab
+        // A `<WebView>` may have named this tab before it existed (the render and the create cross).
+        for host in hosts.allObjects where host.wanted == id { host.show(id) }
+        return tab
+    }
+
+    func register(_ host: CraftMacWebHost) { hosts.add(host) }
+
+    func close(_ id: String) { tabs.removeValue(forKey: id)?.close() }
+
+    /// A closed window takes its tabs with it.
+    func closeAll(owner: CraftMacRuntime) {
+        for (id, tab) in tabs where tab.owner == nil || tab.owner === owner { tabs.removeValue(forKey: id); tab.close() }
+    }
+
+    func perform(_ method: String, _ args: [Any], owner: CraftMacRuntime, answer: @escaping (Any) -> Void, fail: @escaping (String, String) -> Void) {
+        let options = args.first as? [String: Any] ?? [:]
+        if method == "create" {
+            let tab = make(id: options["id"] as? String, profile: options["profile"] as? String ?? "default", ephemeral: options["private"] as? Bool == true, owner: owner)
+            tab.view.isInspectable = options["inspectable"] as? Bool ?? true
+            if let address = options["url"] as? String, !address.isEmpty {
+                guard let url = URL(string: address), url.scheme != nil else { fail("INVALID_ARGUMENT", "Not an absolute URL: \(address)"); return }
+                tab.view.load(URLRequest(url: url))
+            }
+            answer(tab.state); return
+        }
+        if method == "list" { answer(tabs.values.map(\.state)); return }
+        guard let id = args.first as? String, let tab = tabs[id] else { fail("NOT_FOUND", "No tab \(String(describing: args.first ?? ""))"); return }
+        let view = tab.view
+        switch method {
+        case "navigate":
+            guard let address = args.dropFirst().first as? String, let url = URL(string: address), url.scheme != nil else { fail("INVALID_ARGUMENT", "navigate needs an absolute URL"); return }
+            view.load(URLRequest(url: url)); answer(true)
+        case "back": answer(view.goBack() != nil)
+        case "forward": answer(view.goForward() != nil)
+        case "reload":
+            let ignoreCache = (args.dropFirst().first as? [String: Any])?["ignoreCache"] as? Bool == true
+            if ignoreCache { view.reloadFromOrigin() } else { view.reload() }
+            answer(true)
+        case "stop": view.stopLoading(); answer(true)
+        case "close": close(id); answer(true)
+        case "state": answer(tab.state)
+        case "focus": view.window?.makeFirstResponder(view); answer(view.window != nil)
+        case "setZoom": view.pageZoom = number(args.dropFirst().first).map { max(0.25, min(5, $0)) } ?? 1; answer(view.pageZoom)
+        case "setInspectable": view.isInspectable = args.dropFirst().first as? Bool ?? true; answer(true)
+        case "evaluate":
+            let script = args.dropFirst().first as? String ?? ""
+            // The page's own world by default (to read what its scripts set up); `isolated` hides the call from them.
+            let world: WKContentWorld = (args.dropFirst(2).first as? [String: Any])?["isolated"] as? Bool == true ? .defaultClient : .page
+            view.evaluateJavaScript(script, in: nil, in: world) { result in
+                switch result {
+                case .success(let value): answer(JSONSerialization.isValidJSONObject(["v": value]) ? value : String(describing: value))
+                case .failure(let error): fail("SCRIPT_ERROR", error.localizedDescription)
+                }
+            }
+        case "find":
+            let text = args.dropFirst().first as? String ?? ""
+            let options = args.dropFirst(2).first as? [String: Any] ?? [:]
+            let configuration = WKFindConfiguration()
+            configuration.backwards = options["backwards"] as? Bool == true
+            configuration.caseSensitive = options["caseSensitive"] as? Bool == true
+            configuration.wraps = options["wraps"] as? Bool ?? true
+            view.find(text, configuration: configuration) { result in answer(["found": result.matchFound]) }
+        case "snapshot":
+            let configuration = WKSnapshotConfiguration()
+            if let width = number((args.dropFirst().first as? [String: Any])?["width"]) { configuration.snapshotWidth = NSNumber(value: Double(width)) }
+            view.takeSnapshot(with: configuration) { image, error in
+                guard let image, let tiff = image.tiffRepresentation, let bitmap = NSBitmapImageRep(data: tiff),
+                      let jpeg = bitmap.representation(using: .jpeg, properties: [.compressionFactor: 0.7]) else { fail("SNAPSHOT_FAILED", error?.localizedDescription ?? "No image"); return }
+                answer("data:image/jpeg;base64," + jpeg.base64EncodedString())
+            }
+        default: fail("UNSUPPORTED_METHOD", "Web.\(method) is not supported")
+        }
+    }
+}
+
+/// What a `<WebView tab="...">` renders as: the tab's WKWebView, filling the box.
+/// Every tab it has shown stays attached and hidden, so switching back is a visibility change
+/// (WebKit throttles hidden pages) rather than a reparent.
+final class CraftMacWebHost: NSView {
+    weak var box: CraftMacBox?
+    private(set) var wanted: String?
+    override var isFlipped: Bool { true }
+
+    init(box: CraftMacBox) {
+        self.box = box
+        super.init(frame: .zero)
+        CraftMacWebTabs.shared.register(self)
+    }
+    required init?(coder: NSCoder) { fatalError("Created from STX") }
+
+    func show(_ id: String?) {
+        wanted = id
+        let tab = id.flatMap { CraftMacWebTabs.shared.tabs[$0] }
+        for case let view as WKWebView in subviews where view !== tab?.view { view.isHidden = true }
+        // Tabs closed elsewhere leave nothing behind.
+        for case let view as WKWebView in subviews where !CraftMacWebTabs.shared.tabs.values.contains(where: { $0.view === view }) { view.removeFromSuperview() }
+        guard let tab else { return }
+        if let runtime = box?.renderer?.runtime { tab.owner = runtime }
+        if tab.view.superview !== self { tab.view.frame = bounds; addSubview(tab.view) }
+        tab.view.isHidden = false
+    }
+
+    override func layout() {
+        super.layout()
+        for view in subviews { view.frame = bounds }
+    }
+}
+#endif

package/dist/macos/templates/CraftNativeMutation.swift

@@ -35,6 +35,9 @@ final class CraftNativeMutationDocument {
         var style: [String: Any]
         var events: [String: Any]
         var text: [String]
+        // Legacy snapshots may interleave bare text and native children.
+        // Keep each text fragment's slot among the child nodes on import.
+        var textPositions: [Int]? = nil
         var children: [String]
         var parent: String?
     }
@@ -43,6 +46,11 @@ final class CraftNativeMutationDocument {
     private var rootId: String?
     private(set) var revision = 0
 
+    /// The normalized committed tree, whose root need not be named "root".
+    var document: [String: Any]? {
+        rootId.flatMap { materialize($0, nodes: nodes) }
+    }
+
     func replace(with document: [String: Any]) {
         var replacement: [String: Node] = [:]
         let root = importNode(document, preferredId: "root", parent: nil, nodes: &replacement)
@@ -217,6 +225,7 @@ final class CraftNativeMutationDocument {
         if patch.keys.contains("events") { mergePatch(patch["events"], into: &node.events) }
         if patch.keys.contains("children") || patch.keys.contains("text") {
             node.text = try textChildren(patch["children"] ?? patch["text"])
+            node.textPositions = nil
         }
         nodes[id] = node
     }
@@ -422,9 +431,18 @@ final class CraftNativeMutationDocument {
             "events": node.events,
         ]
         if let key = node.key { value["key"] = key }
-        let text: [Any] = node.text
         let children: [Any] = node.children.compactMap { materialize($0, nodes: nodes) }
-        value["children"] = text + children
+        var content: [Any] = []
+        var textIndex = 0
+        for index in 0...children.count {
+            while textIndex < node.text.count,
+                  min(node.textPositions?[textIndex] ?? 0, children.count) == index {
+                content.append(node.text[textIndex])
+                textIndex += 1
+            }
+            if index < children.count { content.append(children[index]) }
+        }
+        value["children"] = content
         return value
     }
 
@@ -440,6 +458,12 @@ final class CraftNativeMutationDocument {
         var id = explicit ?? key.map { "\(parent ?? "root")/key:\($0)" } ?? preferredId
         if nodes[id] != nil { id = "\(preferredId)#\(nodes.count)" }
         let children = value["children"] as? [Any] ?? []
+        var textPositions: [Int] = []
+        var childCount = 0
+        for child in children {
+            if child is String { textPositions.append(childCount) }
+            else if child is [String: Any] { childCount += 1 }
+        }
         nodes[id] = Node(
             id: id,
             key: value["key"] as? String,
@@ -448,6 +472,7 @@ final class CraftNativeMutationDocument {
             style: dictionary(value["style"]),
             events: dictionary(value["events"]),
             text: children.compactMap { $0 as? String },
+            textPositions: textPositions,
             children: [],
             parent: parent
         )