create-apexjs 0.6.7 → 0.6.8

package/templates/mobile/ios/ApexSchemeHandler.swift

@@ -0,0 +1,349 @@
+// ApexSchemeHandler.swift — iOS native shell: custom `apex://` scheme → on-device engine.
+//
+// Mirrors android/ApexInterceptor.kt + android/ApexBridge.kt COMBINED. Every request the WebView
+// makes is intercepted here, handed to the embedded engine's `__apexHandle(...)`, and the returned
+// {status, headers, body} is served straight back — NO network, NO localhost server, NO port (so
+// nothing to suspend when the app backgrounds).
+//
+// ── The big iOS advantage over Android ────────────────────────────────────────────────────
+// Android needs TWO paths because `WebViewClient.shouldInterceptRequest` CANNOT read a request
+// body: navigations/GET go through ApexInterceptor, while body-bearing fetch()/POST are rerouted
+// through a JS bridge (ApexBridge + a document-start fetch patch).
+//
+// On iOS, `WKURLSchemeHandler` receives the FULL `URLRequest`, including `httpBody` — so a single
+// handler covers BOTH navigations and body-bearing fetch()/POST. No JS fetch patch, no
+// @JavascriptInterface bridge. This one file replaces both Android files.
+//
+//   ⚠️ Known caveat (flag for the Mac tester): on some iOS versions WKWebView has historically
+//   dropped the body from custom-scheme requests (`httpBody`/`httpBodyStream` come back nil for
+//   POST). If a Mac tester observes empty POST bodies, the fallback is the Android-style approach:
+//   a `WKScriptMessageHandler` + document-start fetch patch that forwards fetch() bodies. We read
+//   httpBody AND drain httpBodyStream below to maximise the chance the body is present.
+//
+// Cookies: the session is an HttpOnly cookie the engine issues (Set-Cookie) and expects back
+// (Cookie header). Custom-scheme requests do NOT participate in WKHTTPCookieStore, so — exactly
+// like Android's CookieManager usage — we manage it ourselves: inject the stored Cookie on the way
+// in, persist any Set-Cookie on the way out. Kept in this file (a small ApexCookieJar) per spec.
+
+import Foundation
+import WebKit
+
+final class ApexSchemeHandler: NSObject, WKURLSchemeHandler {
+  /// The URL scheme this handler is registered for. The WebView loads `apex://localhost/splash`.
+  static let scheme = "apex"
+
+  private let engine: ApexEngine
+  private let cookieJar = ApexCookieJar()
+
+  /// Tasks currently in flight. WKURLSchemeTask is not thread-safe and must not be messaged after
+  /// `stop` (doing so crashes). We track live tasks and no-op once a task has been stopped.
+  private var activeTasks = Set<ObjectIdentifier>()
+  private let lock = NSLock()
+
+  init(engine: ApexEngine) {
+    self.engine = engine
+  }
+
+  // MARK: - WKURLSchemeHandler
+
+  func webView(_ webView: WKWebView, start task: WKURLSchemeTask) {
+    let id = ObjectIdentifier(task)
+    lock.lock(); activeTasks.insert(id); lock.unlock()
+
+    guard let url = task.request.url else {
+      finishFailing(task, id: id, error: URLError(.badURL))
+      return
+    }
+    let path = url.path.isEmpty ? "/" : url.path
+
+    // 1) Static client assets straight from the app bundle (client JS/CSS bundle, favicon) —
+    //    mirrors ApexInterceptor's `/assets/` + `/favicon.svg` fast path. No engine round-trip.
+    if path.hasPrefix("/assets/") || path == "/favicon.svg" {
+      if serveBundledAsset(path: path, url: url, task: task, id: id) { return }
+      // Fall through to the engine if the file isn't in the bundle (lets the engine 404 cleanly).
+    }
+
+    // 2) Everything else → the on-device engine. Build the {url,method,headers,body} request JSON,
+    //    INCLUDING the body (the iOS advantage), injecting the stored session cookie.
+    let method = (task.request.httpMethod ?? "GET").uppercased()
+    var headers = task.request.allHTTPHeaderFields ?? [:]
+
+    // Inject the stored HttpOnly session cookie if the request doesn't already carry one.
+    if headers["cookie"] == nil, headers["Cookie"] == nil,
+       let stored = cookieJar.cookieHeader(), !stored.isEmpty {
+      headers["cookie"] = stored
+    }
+
+    let bodyString = ApexSchemeHandler.readBody(from: task.request)
+
+    var requestObject: [String: Any] = [
+      "url": url.absoluteString,
+      "method": method,
+      "headers": headers,
+    ]
+    requestObject["body"] = bodyString ?? NSNull()
+
+    guard
+      let data = try? JSONSerialization.data(withJSONObject: requestObject),
+      let requestJSON = String(data: data, encoding: .utf8)
+    else {
+      finishFailing(task, id: id, error: URLError(.cannotParseResponse))
+      return
+    }
+
+    // Off the main thread: call the engine, then hop back to the main thread to message the task
+    // (WKURLSchemeTask callbacks must be delivered consistently; we use the main thread).
+    Task { [weak self] in
+      guard let self else { return }
+      let responseJSON = await self.engine.handle(requestJSON)
+
+      // Persist any Set-Cookie so a login (via fetch) is visible to the next full page load.
+      self.cookieJar.persistSetCookie(from: responseJSON)
+
+      // A mutating request may have changed the DB — persist a fresh snapshot so it survives a
+      // cold start (mirrors ApexBridge). All body-bearing writes come through here.
+      if method != "GET", method != "HEAD", method != "OPTIONS" {
+        ApexDbStore.write(self.engine.snapshot())
+      }
+
+      await MainActor.run {
+        self.deliver(responseJSON: responseJSON, url: url, task: task, id: id)
+      }
+    }
+  }
+
+  func webView(_ webView: WKWebView, stop task: WKURLSchemeTask) {
+    // Mark the task dead so any in-flight completion no-ops instead of messaging a stopped task.
+    lock.lock(); activeTasks.remove(ObjectIdentifier(task)); lock.unlock()
+  }
+
+  // MARK: - Response delivery
+
+  /// Parse the engine's {status,headers,body} JSON and stream it to the WebView task.
+  private func deliver(responseJSON: String, url: URL, task: WKURLSchemeTask, id: ObjectIdentifier) {
+    guard isActive(id) else { return }
+
+    guard
+      let data = responseJSON.data(using: .utf8),
+      let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+    else {
+      finishFailing(task, id: id, error: URLError(.cannotParseResponse))
+      return
+    }
+
+    let status = (obj["status"] as? Int) ?? 200
+    let body = (obj["body"] as? String) ?? ""
+    var headers = (obj["headers"] as? [String: String]) ?? ["content-type": "text/html; charset=utf-8"]
+
+    let bodyData = body.data(using: .utf8) ?? Data()
+    // Set Content-Length so the WebView knows the body is complete.
+    if headers["content-length"] == nil, headers["Content-Length"] == nil {
+      headers["Content-Length"] = String(bodyData.count)
+    }
+
+    guard let response = HTTPURLResponse(
+      url: url,
+      statusCode: status,
+      httpVersion: "HTTP/1.1",
+      headerFields: headers
+    ) else {
+      finishFailing(task, id: id, error: URLError(.cannotParseResponse))
+      return
+    }
+
+    task.didReceive(response)
+    task.didReceive(bodyData)
+    task.didFinish()
+    markDone(id)
+  }
+
+  // MARK: - Static assets
+
+  /// Serve a bundled `/assets/...` or `/favicon.svg` file. Returns true if handled.
+  ///
+  /// Assets are copied into the app bundle under an `assets/` folder reference (see ios/README.md),
+  /// so `/assets/app-abc123.js` maps to bundle resource `app-abc123.js` in subdirectory `assets`,
+  /// and `/favicon.svg` maps to `favicon.svg` at the bundle root.
+  private func serveBundledAsset(path: String, url: URL, task: WKURLSchemeTask, id: ObjectIdentifier) -> Bool {
+    let fileURL: URL?
+    if path == "/favicon.svg" {
+      fileURL = Bundle.main.url(forResource: "favicon", withExtension: "svg")
+    } else {
+      // "/assets/app-abc123.js" → resource "app-abc123", ext "js", subdirectory "assets".
+      let name = (path as NSString).lastPathComponent            // app-abc123.js
+      let ext = (name as NSString).pathExtension                  // js
+      let base = (name as NSString).deletingPathExtension         // app-abc123
+      let subdir = ((path as NSString).deletingLastPathComponent as NSString)
+        .lastPathComponent                                        // assets
+      fileURL = Bundle.main.url(forResource: base, withExtension: ext, subdirectory: subdir)
+    }
+
+    guard let fileURL, let fileData = try? Data(contentsOf: fileURL) else {
+      return false
+    }
+
+    let headers = [
+      "content-type": ApexSchemeHandler.mimeType(for: path),
+      "content-length": String(fileData.count),
+      // Client bundle filenames are content-hashed → safe to cache aggressively.
+      "cache-control": "public, max-age=31536000, immutable",
+    ]
+    guard let response = HTTPURLResponse(url: url, statusCode: 200, httpVersion: "HTTP/1.1", headerFields: headers) else {
+      return false
+    }
+
+    guard isActive(id) else { return true }
+    task.didReceive(response)
+    task.didReceive(fileData)
+    task.didFinish()
+    markDone(id)
+    return true
+  }
+
+  // MARK: - Task bookkeeping
+
+  private func isActive(_ id: ObjectIdentifier) -> Bool {
+    lock.lock(); defer { lock.unlock() }
+    return activeTasks.contains(id)
+  }
+
+  private func markDone(_ id: ObjectIdentifier) {
+    lock.lock(); activeTasks.remove(id); lock.unlock()
+  }
+
+  private func finishFailing(_ task: WKURLSchemeTask, id: ObjectIdentifier, error: Error) {
+    guard isActive(id) else { return }
+    task.didFailWithError(error)
+    markDone(id)
+  }
+
+  // MARK: - Body + MIME helpers
+
+  /// Read the request body: prefer `httpBody`, fall back to draining `httpBodyStream`.
+  /// (See the caveat in the file header about custom-scheme bodies on some iOS versions.)
+  private static func readBody(from request: URLRequest) -> String? {
+    if let body = request.httpBody {
+      return String(data: body, encoding: .utf8)
+    }
+    guard let stream = request.httpBodyStream else { return nil }
+    stream.open()
+    defer { stream.close() }
+    var data = Data()
+    let bufferSize = 4096
+    var buffer = [UInt8](repeating: 0, count: bufferSize)
+    while stream.hasBytesAvailable {
+      let read = stream.read(&buffer, maxLength: bufferSize)
+      if read > 0 { data.append(buffer, count: read) } else { break }
+    }
+    return data.isEmpty ? nil : String(data: data, encoding: .utf8)
+  }
+
+  /// Mirrors ApexInterceptor.mimeOf.
+  private static func mimeType(for path: String) -> String {
+    switch (path as NSString).pathExtension.lowercased() {
+    case "js", "mjs": return "text/javascript; charset=utf-8"
+    case "css": return "text/css; charset=utf-8"
+    case "svg": return "image/svg+xml"
+    case "json": return "application/json; charset=utf-8"
+    case "png": return "image/png"
+    case "jpg", "jpeg": return "image/jpeg"
+    case "webp": return "image/webp"
+    case "woff2": return "font/woff2"
+    case "woff": return "font/woff"
+    case "ttf": return "font/ttf"
+    case "ico": return "image/x-icon"
+    default: return "application/octet-stream"
+    }
+  }
+}
+
+// MARK: - Cookie jar
+
+/// Manages the HttpOnly session cookie the engine issues, the way Android's CookieManager usage in
+/// ApexBridge/ApexInterceptor does. Custom `apex://` requests don't flow through WKHTTPCookieStore,
+/// so we keep a tiny name→value jar ourselves and persist it (mirrors CookieManager's on-disk
+/// persistence) so a login survives a cold start.
+private final class ApexCookieJar {
+  private let defaultsKey = "site.apexjs.shell.cookies"
+  private let lock = NSLock()
+  private var jar: [String: String]   // cookie name → value
+
+  init() {
+    let stored = UserDefaults.standard.dictionary(forKey: defaultsKey) as? [String: String]
+    jar = stored ?? [:]
+  }
+
+  /// The `Cookie:` header value to send to the engine (all stored name=value pairs), or nil.
+  func cookieHeader() -> String? {
+    lock.lock(); defer { lock.unlock() }
+    guard !jar.isEmpty else { return nil }
+    return jar.map { "\($0.key)=\($0.value)" }.joined(separator: "; ")
+  }
+
+  /// Store any Set-Cookie from an engine response JSON. Mirrors ApexBridge.persistSetCookie:
+  /// a combined header may hold several cookies separated by ", " before a `name=`.
+  func persistSetCookie(from responseJSON: String) {
+    guard
+      let data = responseJSON.data(using: .utf8),
+      let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+      let headers = obj["headers"] as? [String: Any]
+    else { return }
+
+    // Header name may be any case.
+    let raw: String? = (headers["set-cookie"] as? String) ?? (headers["Set-Cookie"] as? String)
+    guard let setCookie = raw, !setCookie.isEmpty else { return }
+
+    lock.lock(); defer { lock.unlock() }
+    for chunk in ApexCookieJar.splitCombinedSetCookie(setCookie) {
+      // A single cookie: "name=value; Path=/; HttpOnly; ..." — take the first `name=value` pair.
+      let firstPair = chunk.split(separator: ";", maxSplits: 1).first.map(String.init) ?? chunk
+      guard let eq = firstPair.firstIndex(of: "=") else { continue }
+      let name = firstPair[..<eq].trimmingCharacters(in: .whitespaces)
+      let value = firstPair[firstPair.index(after: eq)...].trimmingCharacters(in: .whitespaces)
+      guard !name.isEmpty else { continue }
+      // A cookie cleared with an expiry in the past / empty value → drop it. Simplified vs a full
+      // RFC 6265 expiry parse; enough for the single-session PoC (logout clears the value).
+      if value.isEmpty {
+        jar.removeValue(forKey: name)
+      } else {
+        jar[name] = value
+      }
+    }
+    UserDefaults.standard.set(jar, forKey: defaultsKey)
+  }
+
+  /// Split a combined Set-Cookie header on the boundary ", " that precedes a new `name=` — the
+  /// same heuristic as Android's regex `,(?=[^;,]+=)`. Avoids splitting on commas inside an
+  /// `Expires=Wed, 09 Jun 2021 ...` attribute.
+  private static func splitCombinedSetCookie(_ header: String) -> [String] {
+    var results: [String] = []
+    var current = ""
+    let chars = Array(header)
+    var i = 0
+    while i < chars.count {
+      if chars[i] == "," {
+        // Look ahead: is the next token `<name>=` before any ';' or ','? If so, this comma is a
+        // cookie separator; otherwise it's part of an attribute value (e.g. an Expires date).
+        var j = i + 1
+        while j < chars.count, chars[j] == " " { j += 1 }
+        var k = j
+        var sawEquals = false
+        while k < chars.count, chars[k] != ";", chars[k] != "," {
+          if chars[k] == "=" { sawEquals = true; break }
+          k += 1
+        }
+        if sawEquals {
+          results.append(current.trimmingCharacters(in: .whitespaces))
+          current = ""
+          i = j
+          continue
+        }
+      }
+      current.append(chars[i])
+      i += 1
+    }
+    let tail = current.trimmingCharacters(in: .whitespaces)
+    if !tail.isEmpty { results.append(tail) }
+    return results
+  }
+}

package/templates/mobile/ios/Assets.xcassets/AppIcon.appiconset/Contents.json

@@ -0,0 +1,14 @@
+{
+  "images": [
+    {
+      "filename": "icon-1024.png",
+      "idiom": "universal",
+      "platform": "ios",
+      "size": "1024x1024"
+    }
+  ],
+  "info": {
+    "author": "apex",
+    "version": 1
+  }
+}

package/templates/mobile/ios/Assets.xcassets/LaunchBackground.colorset/Contents.json

@@ -0,0 +1,20 @@
+{
+  "colors": [
+    {
+      "idiom": "universal",
+      "color": {
+        "color-space": "srgb",
+        "components": {
+          "red": "0x0B",
+          "green": "0x11",
+          "blue": "0x20",
+          "alpha": "1.000"
+        }
+      }
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}

package/templates/mobile/ios/Info.plist

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Info.plist for the Apex iOS shell.
+
+  Mirrors AndroidManifest.xml: a launcher app with a native launch screen and NO network
+  entitlement required (the backend runs on-device, offline). The animated pages/splash.alpine
+  route takes over after this static launch screen — the two-stage splash handoff.
+
+  Most $(…) values are Xcode build-setting placeholders; set them in the target's General tab.
+-->
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleDisplayName</key>
+  <string>Apex</string>
+  <key>CFBundleExecutable</key>
+  <string>$(EXECUTABLE_NAME)</string>
+  <key>CFBundleIdentifier</key>
+  <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>$(PRODUCT_NAME)</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>LSRequiresIPhoneOS</key>
+  <true/>
+
+  <!-- Native cold-start launch screen: a solid brand-colour screen shown before any JS runs.
+       Uses the LaunchBackground colour asset (#0b1120) in Assets.xcassets. The animated
+       pages/splash.alpine renders immediately after and dismisses to '/'. -->
+  <key>UILaunchScreen</key>
+  <dict>
+    <key>UIColorName</key>
+    <string>LaunchBackground</string>
+  </dict>
+
+  <key>UISupportedInterfaceOrientations</key>
+  <array>
+    <string>UIInterfaceOrientationPortrait</string>
+    <string>UIInterfaceOrientationLandscapeLeft</string>
+    <string>UIInterfaceOrientationLandscapeRight</string>
+  </array>
+  <key>UISupportedInterfaceOrientations~ipad</key>
+  <array>
+    <string>UIInterfaceOrientationPortrait</string>
+    <string>UIInterfaceOrientationPortraitUpsideDown</string>
+    <string>UIInterfaceOrientationLandscapeLeft</string>
+    <string>UIInterfaceOrientationLandscapeRight</string>
+  </array>
+
+  <!-- Status-bar handled by SwiftUI/WebView; no scene manifest needed for the SwiftUI App
+       lifecycle (@main struct App). -->
+</dict>
+</plist>

package/templates/mobile/ios/README.md

@@ -0,0 +1,153 @@
+# Apex iOS shell
+
+> ⚠️ **UNVERIFIED — needs a Mac + Xcode to compile and run.** These files were written on Linux,
+> mirroring the already-shipped, device-verified **Android** shell (`../android/`). No part of the
+> iOS build has been compiled or run — treat it as a well-formed starting point, not a proven app.
+> See **"For the Mac tester"** at the bottom for exactly what to check first.
+
+A native iOS app that runs your Apex backend **on the device** (offline, no server, no port) and
+renders it in a `WKWebView`. It is the 1:1 counterpart of the Android shell, using the two iOS
+platform capabilities that make it *simpler* than Android:
+
+| Concern | Android | iOS (here) |
+|---|---|---|
+| JS engine | `androidx.javascriptengine` (out-of-process, async boot, **no host callbacks**) | **JavaScriptCore `JSContext`** (in-process, sync boot, **host callbacks + exception handler**) |
+| Request interception | `WebViewClient.shouldInterceptRequest` (**cannot read POST body**) | **`WKURLSchemeHandler`** for `apex://` (**reads `httpBody` directly**) |
+| Body-bearing `fetch()`/POST | needs a **2nd path**: `@JavascriptInterface` bridge + document-start `fetch` patch | **not needed** — one scheme handler covers navigations *and* POST |
+| Cookies (HttpOnly session) | `CookieManager` | small `ApexCookieJar` inside the scheme handler (custom schemes bypass `WKHTTPCookieStore`) |
+| DB persistence | `apex-db.b64` in `filesDir`, atomic rename | `apex-db.b64` in Application Support, `FileManager.replaceItemAt` |
+
+## What's here
+
+```
+ios/
+├─ ApexApp.swift            # @main SwiftUI App: boots engine, builds WKWebView, loads apex://localhost/splash
+├─ ApexEngine.swift         # JSContext wrapper — loads server.mjs + apex-bridge.js, runs __apexHandle
+├─ ApexSchemeHandler.swift  # WKURLSchemeHandler for apex:// → engine (assets from bundle) + cookie jar
+├─ ApexDbStore.swift        # DB snapshot persistence (Application Support, atomic)
+├─ Info.plist               # launch screen + app config (no network entitlement needed — offline)
+└─ Assets.xcassets/
+   ├─ AppIcon.appiconset/   # app icon (already present)
+   └─ LaunchBackground.colorset/  # #0b1120 launch-screen colour
+```
+
+## Architecture (identical contract to Android)
+
+```
+ WKWebView  ── every request ──►  ApexSchemeHandler (apex:// scheme)
+                                     │  /assets/*, /favicon.svg → bundle files
+                                     │  everything else → engine, WITH body + injected Cookie
+                                     ▼
+                              ApexEngine.handle(requestJSON)
+                                     │  globalThis.__apexHandle(json)  (apex-bridge.js)
+                                     │    └─ APEX.run(request) → { status, headers, body }
+                                     ▼
+                              {status,headers,body}  ── served back ──►  WKWebView hydrates
+```
+
+Because interception is a **function call**, there's no listener and no port — nothing for iOS to
+suspend when the app backgrounds. That's the whole point.
+
+## Create the Xcode project & drop these files in
+
+There is no `.xcodeproj` in this folder (it's binary/machine-specific). Create one on the Mac:
+
+1. **Xcode → New → App.** Interface: **SwiftUI**, Language: **Swift**. Product name e.g. `ApexShell`.
+   Set the **Bundle Identifier** and a signing team in *Signing & Capabilities*.
+2. **Delete** the auto-generated `ContentView.swift` and the generated `…App.swift` (this repo's
+   `ApexApp.swift` provides the `@main` App).
+3. **Add these files** to the target (drag into the project navigator, *Copy items if needed* off if
+   you reference them in place): `ApexApp.swift`, `ApexEngine.swift`, `ApexSchemeHandler.swift`,
+   `ApexDbStore.swift`.
+4. **Info.plist / Assets:** either use this folder's `Info.plist` (set *Build Settings → Info.plist
+   File* to point at it) or copy its `UILaunchScreen` + keys into the generated one. Add the
+   `LaunchBackground` colour set (and your `AppIcon`) to the target's asset catalog.
+5. **Framework:** `import JavaScriptCore` — it's a **system framework**, no dependency to add
+   (link it in *Frameworks, Libraries, and Embedded Content* if the linker complains).
+
+## Copy the built bundle + client assets into the app
+
+From your **Apex app root**, build the mobile bundle:
+
+```bash
+apex build --mobile      # → dist/mobile/server.mjs
+apex build               # (or your normal build) → dist/assets/*, dist/favicon.svg
+```
+
+Then add these to the Xcode target so they land in the app bundle **Resources**:
+
+| Source | Add to bundle as | Read by |
+|---|---|---|
+| `dist/mobile/server.mjs` | `server.mjs` (bundle root) | `ApexEngine` → `Bundle.main.url(forResource:"server", withExtension:"mjs")` |
+| `native-shell/apex-bridge.js` | `apex-bridge.js` (bundle root) | `ApexEngine` → `…forResource:"apex-bridge", withExtension:"js"` |
+| `dist/assets/*` | an **`assets/` folder reference** (blue folder) | `ApexSchemeHandler` → `…forResource:base, withExtension:ext, subdirectory:"assets"` |
+| `dist/favicon.svg` | `favicon.svg` (bundle root) | `ApexSchemeHandler` |
+
+> **Important — use a *folder reference* (blue), not a *group* (yellow), for `assets/`.** A folder
+> reference preserves the `assets/` subdirectory so `subdirectory: "assets"` lookups resolve. A
+> group flattens filenames into the bundle root and the `/assets/...` path lookups will 404.
+
+Also copy `native-shell/splash.alpine` into your app's `pages/splash.alpine` (the animated intro the
+shell loads first) and rebuild — see `../NATIVE_SHELL.md`.
+
+## Run
+
+Select an iOS Simulator (or a provisioned device) and **⌘R**. You should see: the native launch
+screen (#0b1120), then the animated `splash.alpine`, then your app — all served by the Apex server
+running inside the app on JavaScriptCore. Turn the network off: it still works.
+
+## On-device drivers
+
+`apex build --mobile` reports routes needing `crypto.subtle` (sessions) or `@libsql/client/web`
+(DB) — same as Android. JavaScriptCore provides a real `crypto`? **Not by default** — JSCore has no
+WebCrypto. The bundle ships a stub so non-session routes boot; for real sessions, expose a native
+WebCrypto shim as a host object on the `JSContext` (the JSContext host-callback capability makes
+this straightforward — add it in `ApexEngine` before evaluating `server.mjs`). For DB, alias
+`@libsql/client` → `@libsql/client/web` (sql.js asm.js) before bundling, as on Android.
+
+## For the Mac tester (check these first — likeliest failure points)
+
+1. **Bundle resources present.** If you see *"Apex engine failed to start"*, `server.mjs` /
+   `apex-bridge.js` aren't in the bundle. Confirm they're in *Build Phases → Copy Bundle Resources*.
+2. **`/assets/*` 404 → white page after splash.** Almost certainly the `assets/` folder was added as
+   a *group* (yellow) not a *folder reference* (blue). Re-add as a blue folder. Verify by loading
+   `apex://localhost/assets/<one-file>.js` and watching the Xcode console.
+3. **⭐ POST body reaches the engine.** This is the one genuinely unproven iOS assumption. The task's
+   premise is that `WKURLSchemeHandler` exposes `httpBody` for custom schemes — but some iOS
+   versions have historically **dropped** the body from custom-scheme requests. **Test a POST**
+   (log in, or add a guestbook entry) and confirm the engine receives a non-empty `body`. If it's
+   empty: fall back to the Android approach — add a `WKScriptMessageHandler` (`configuration.
+   userContentController.add(...)`) plus a document-start `fetch` patch (port `FETCH_PATCH` from
+   `../android/.../MainActivity.kt`) that forwards `fetch()` bodies to the handler. The engine and
+   cookie/DB plumbing here are unchanged either way.
+4. **Promise resolution.** `ApexEngine.handle` resolves the JS promise via `.then(onFulfilled,
+   onRejected)` and assumes JavaScriptCore drains its microtask queue within the same JS turn (true
+   for our fully-synchronous in-memory pipeline). If a request ever hangs, that assumption broke —
+   pump with `JSVirtualMachine`/a run-loop tick, or wrap the handler to resolve on a `Promise`
+   settled callback.
+5. **HttpOnly session cookie** survives a full page navigation and a cold start (login, force-quit,
+   relaunch → still logged in). The jar persists to `UserDefaults`.
+6. **DB snapshot** survives a cold start (create data, force-quit, relaunch → data still there). File
+   is `apex-db.b64` in Application Support.
+
+## Testing without a Mac — CI on the iOS Simulator
+
+No Mac? The `ios-shell` GitHub Actions workflow (`.github/workflows/ios.yml`) builds this shell and
+runs `Tests/ApexEngineTests.swift` on the iOS Simulator on a **free GitHub-hosted macOS runner**.
+Trigger it from the repo's **Actions → ios-shell → Run workflow** (or it runs on pushes touching
+`ios/`). It:
+
+1. builds the packages + the showcase `--mobile` bundle,
+2. stages `server.mjs` / `apex-bridge.js` / `assets/` / `favicon.svg` into `ios/Generated/`,
+3. `xcodegen generate` (from `project.yml` — no committed `.xcodeproj`),
+4. `xcodebuild test` on an iPhone simulator.
+
+`ApexEngineTests` proves the bundle — the shim, SSR + API pipeline, **asm.js SQLite**, sealed-cookie
+auth, and the snapshot persistence seam — actually runs under **JavaScriptCore** (iOS's engine),
+which is the main iOS unknown. It does NOT exercise `WKURLSchemeHandler` (the custom-scheme POST-body
+question in the checklist above) — that still needs a device/UI test on a real Mac + iPhone.
+
+### To run on your actual iPhone
+Open the generated project on a Mac (`brew install xcodegen && cd ios && xcodegen generate && open
+ApexShell.xcodeproj`), copy the four `Generated/` items into the app's Resources, set a free Apple ID
+signing team, pick your iPhone, and Run. A free personal team gives a 7-day provisioning profile.