create-apexjs 0.6.7 → 0.6.9

package/templates/mobile/android/app/src/main/res/values/ic_launcher_background.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="ic_launcher_background">#0b1120</color>
+</resources>

package/templates/mobile/android/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <string name="app_name">Apex App</string>
+</resources>

package/templates/mobile/android/app/src/main/res/values/themes.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <!-- Native cold-start splash: the generated launcher icon on the generated background.
+       postSplashScreenTheme hands off to the app; then pages/splash.alpine animates. -->
+  <style name="Theme.Apex.Splash" parent="Theme.SplashScreen">
+    <item name="windowSplashScreenBackground">@color/ic_launcher_background</item>
+    <item name="windowSplashScreenAnimatedIcon">@mipmap/ic_launcher_foreground</item>
+    <item name="postSplashScreenTheme">@style/Theme.Apex</item>
+  </style>
+  <style name="Theme.Apex" parent="Theme.AppCompat.DayNight.NoActionBar" />
+</resources>

package/templates/mobile/android/build.gradle.kts

@@ -0,0 +1,4 @@
+plugins {
+  id("com.android.application") version "8.5.0" apply false
+  id("org.jetbrains.kotlin.android") version "1.9.24" apply false
+}

package/templates/mobile/android/gradle.properties

@@ -0,0 +1,3 @@
+org.gradle.jvmargs=-Xmx2048m
+android.useAndroidX=true
+kotlin.code.style=official

package/templates/mobile/android/settings.gradle.kts

@@ -0,0 +1,4 @@
+pluginManagement { repositories { google(); mavenCentral(); gradlePluginPortal() } }
+dependencyResolutionManagement { repositories { google(); mavenCentral() } }
+rootProject.name = "ApexShell"
+include(":app")

package/templates/mobile/apex-bridge.js

@@ -0,0 +1,22 @@
+// apex-bridge.js — the JS side of the native shell.
+//
+// Load order in the embedded engine (Hermes / JSC / QuickJS):
+//   1) server.mjs   (from `apex build --mobile` — sets globalThis.APEX = { run })
+//   2) this file
+//
+// The native interceptor (iOS WKURLSchemeHandler / Android shouldInterceptRequest) calls
+// __apexHandle(jsonRequest) → Promise<jsonResponse>. String-in/string-out keeps the FFI
+// trivial across every engine.
+//
+// jsonRequest  = { "url": "...", "method": "GET", "headers": {..}, "body": "..."|null }
+// jsonResponse = { "status": 200, "headers": {"content-type": "text/html", ...}, "body": "..." }
+
+globalThis.__apexHandle = async function (jsonRequest) {
+  const { url, method, headers, body } = JSON.parse(jsonRequest)
+  const req = new Request(url, { method: method || 'GET', headers: headers || {}, body })
+  const res = await globalThis.APEX.run(req) // { status, headers, body }
+  return JSON.stringify(res)
+}
+
+// Optional: a synchronous readiness flag the native side can poll before the first request.
+globalThis.__apexReady = typeof globalThis.APEX?.run === 'function'

package/templates/mobile/gen-mobile-assets.mjs

@@ -0,0 +1,101 @@
+// gen-mobile-assets.mjs — reference for `apex build --mobile` asset generation.
+// One source icon (+ optional splash) → all native launcher/adaptive/appicon assets.
+//   node gen-mobile-assets.mjs <icon.png> [--out ./native-shell/android] [--splash splash.png] [--bg '#0b0b0b']
+//
+// STATIC native assets only (icons + cold-start splash). The ANIMATED splash is a
+// `pages/splash.alpine` route the shell renders first — no generation, it's just a page.
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Resolve `sharp` from wherever the command RUNS (the app root), not this script's dir — ESM
+// `import 'sharp'` (and NODE_PATH) resolve relative to the file, so a `sharp` installed in the
+// app wouldn't be found. `npm i -D sharp` in your app, then run the assembler from the app root.
+let sharp
+try {
+  sharp = (await import('sharp')).default
+} catch {
+  try {
+    sharp = createRequire(pathToFileURL(join(process.cwd(), 'x.js')).href)('sharp')
+  } catch {
+    console.error('  ✗ `sharp` not found — run `npm i -D sharp` in your app, then re-run.')
+    process.exit(1)
+  }
+}
+
+const args = process.argv.slice(2)
+const srcIcon = args[0]
+const outIdx = args.indexOf('--out')
+const androidDir = outIdx >= 0 ? args[outIdx + 1] : './native-shell/android'
+const out = `${androidDir}/app/src/main/res`
+const splash = args.includes('--splash') ? args[args.indexOf('--splash') + 1] : null
+const bg = args.includes('--bg') ? args[args.indexOf('--bg') + 1] : '#0b0b0b'
+if (!srcIcon) throw new Error('usage: gen-mobile-assets.mjs <icon.png> [--out dir] [--splash s.png] [--bg #hex]')
+
+const write = (p, buf) => {
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, buf)
+}
+
+// ── Android launcher icons (legacy square, all densities) ─────────────────────────
+const DENSITIES = { mdpi: 48, hdpi: 72, xhdpi: 96, xxhdpi: 144, xxxhdpi: 192 }
+for (const [d, px] of Object.entries(DENSITIES)) {
+  const png = await sharp(srcIcon).resize(px, px, { fit: 'cover' }).png().toBuffer()
+  write(join(out, `mipmap-${d}`, 'ic_launcher.png'), png)
+  write(join(out, `mipmap-${d}`, 'ic_launcher_round.png'), png)
+}
+
+// ── Adaptive icon (API 26+): foreground layer at 108dp per density + XML + bg color ──
+// Foreground art occupies the inner ~66dp safe zone; we pad the source into 108dp.
+const FG = { mdpi: 108, hdpi: 162, xhdpi: 216, xxhdpi: 324, xxxhdpi: 432 }
+for (const [d, px] of Object.entries(FG)) {
+  const inner = Math.round(px * 0.62)
+  const fg = await sharp(srcIcon)
+    .resize(inner, inner, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .extend({
+      top: Math.round((px - inner) / 2),
+      bottom: Math.round((px - inner) / 2),
+      left: Math.round((px - inner) / 2),
+      right: Math.round((px - inner) / 2),
+      background: { r: 0, g: 0, b: 0, alpha: 0 },
+    })
+    .png()
+    .toBuffer()
+  write(join(out, `mipmap-${d}`, 'ic_launcher_foreground.png'), fg)
+}
+write(
+  join(out, 'values', 'ic_launcher_background.xml'),
+  `<?xml version="1.0" encoding="utf-8"?>\n<resources>\n  <color name="ic_launcher_background">${bg}</color>\n</resources>\n`,
+)
+const adaptiveXml = `<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@color/ic_launcher_background" />
+  <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+</adaptive-icon>\n`
+write(join(out, 'mipmap-anydpi-v26', 'ic_launcher.xml'), adaptiveXml)
+write(join(out, 'mipmap-anydpi-v26', 'ic_launcher_round.xml'), adaptiveXml)
+
+// ── Play Store icon (512) ─────────────────────────────────────────────────────────
+write('./native-shell/android/play_store_512.png', await sharp(srcIcon).resize(512, 512).png().toBuffer())
+
+// ── Static cold-start splash (Android 12+ theme uses a centered icon on bg) ─────────
+if (splash) {
+  for (const [d, px] of Object.entries({ mdpi: 288, hdpi: 432, xhdpi: 576, xxhdpi: 864, xxxhdpi: 1152 })) {
+    write(join(out, `drawable-${d}`, 'splash.png'),
+      await sharp(splash).resize(px, px, { fit: 'contain', background: bg }).png().toBuffer())
+  }
+}
+
+// ── iOS AppIcon.appiconset (single-size 1024, Xcode 14+ format) ─────────────────────
+const iosDir = './native-shell/ios/Assets.xcassets/AppIcon.appiconset'
+write(join(iosDir, 'icon-1024.png'), await sharp(srcIcon).resize(1024, 1024).flatten({ background: bg }).png().toBuffer())
+write(join(iosDir, 'Contents.json'), JSON.stringify({
+  images: [{ filename: 'icon-1024.png', idiom: 'universal', platform: 'ios', size: '1024x1024' }],
+  info: { author: 'apex', version: 1 },
+}, null, 2))
+
+console.log('✓ Android: mipmap-* (5 densities) launcher + round + adaptive foreground + ic_launcher.xml + bg color')
+console.log('✓ Android: play_store_512.png' + (splash ? ' + drawable-*/splash.png' : ''))
+console.log('✓ iOS: AppIcon.appiconset (1024 + Contents.json)')
+console.log('  (Animated splash = pages/splash.alpine — rendered by the shell first, no generation.)')

package/templates/mobile/ios/ApexApp.swift

@@ -0,0 +1,106 @@
+// ApexApp.swift — SwiftUI entry point for the Apex iOS shell.
+//
+// Mirrors android/MainActivity.kt: boot the on-device JS engine, create a WKWebView whose
+// `apex://` scheme is served by ApexSchemeHandler, and load `apex://localhost/splash`.
+//
+// ── Where this diverges from Android ──────────────────────────────────────────────────────
+//  • Android boots the engine asynchronously (androidx.javascriptengine sandbox handshake) inside
+//    lifecycleScope, then wires the WebView. On iOS, JSContext is synchronous, so we build the
+//    engine up front (in ApexRuntime) — no async gate before the first load.
+//  • Android's fetch()-with-body needs a JS bridge + document-start patch; iOS does NOT (the
+//    scheme handler reads the body directly), so there is nothing extra to install on the WebView.
+//  • Splash: iOS shows a native launch screen (configured via Info.plist `UILaunchScreen`, a solid
+//    brand-colour screen — see ios/README.md) before JS runs, then the WebView loads the
+//    `pages/splash.alpine` route (SSR-rendered instantly), which navigates to `/` when ready —
+//    the same two-stage splash handoff as Android.
+
+import SwiftUI
+import WebKit
+
+@main
+struct ApexShellApp: App {
+  /// The engine + scheme handler live for the whole app lifetime.
+  @StateObject private var runtime = ApexRuntime()
+
+  var body: some Scene {
+    WindowGroup {
+      ApexWebView(runtime: runtime)
+        .ignoresSafeArea()          // full-bleed; the .alpine splash handles safe-area insets itself
+    }
+  }
+}
+
+/// Owns the singleton engine and scheme handler. Building the engine can fail only if the bundle
+/// resources are missing (server.mjs / apex-bridge.js not copied in) — we surface that as an error
+/// page rather than crashing, so a Mac tester sees a clear message.
+final class ApexRuntime: ObservableObject {
+  let engine: ApexEngine?
+  let bootError: String?
+
+  init() {
+    do {
+      // Restore the persisted DB snapshot (if any) BEFORE the bundle boots (see ApexDbStore).
+      let engine = try ApexEngine(snapshot: ApexDbStore.read())
+      self.engine = engine
+      self.bootError = nil
+    } catch {
+      self.engine = nil
+      self.bootError = "\(error)"
+      print("[ApexJS] engine boot failed: \(error)")
+    }
+  }
+}
+
+/// Bridges a WKWebView into SwiftUI. Registers the `apex://` scheme handler on the configuration
+/// (this MUST happen before the WebView is created — you can't add a scheme handler afterwards)
+/// and loads the animated splash route.
+struct ApexWebView: UIViewRepresentable {
+  let runtime: ApexRuntime
+
+  func makeUIView(context: Context) -> WKWebView {
+    let configuration = WKWebViewConfiguration()
+
+    // Enable JavaScript (needed for client hydration in the WebView).
+    if #available(iOS 14.0, *) {
+      configuration.defaultWebpagePreferences.allowsContentJavaScript = true
+    } else {
+      configuration.preferences.javaScriptEnabled = true
+    }
+
+    // Register the custom scheme → on-device engine. If the engine failed to boot we still create
+    // the WebView but load an error page instead.
+    if let engine = runtime.engine {
+      configuration.setURLSchemeHandler(
+        ApexSchemeHandler(engine: engine),
+        forURLScheme: ApexSchemeHandler.scheme
+      )
+    }
+
+    let webView = WKWebView(frame: .zero, configuration: configuration)
+    webView.allowsBackForwardNavigationGestures = true
+    // Match the native launch screen background so there's no flash before the .alpine splash.
+    webView.isOpaque = false
+    webView.backgroundColor = UIColor(red: 0x0b/255, green: 0x11/255, blue: 0x20/255, alpha: 1) // #0b1120
+    webView.scrollView.backgroundColor = webView.backgroundColor
+
+    if runtime.engine != nil {
+      // Load the animated splash route first; it navigates to '/' when ready (same as Android).
+      // Any host works — every request is intercepted; the host ("localhost") is ignored.
+      if let url = URL(string: "\(ApexSchemeHandler.scheme)://localhost/splash") {
+        webView.load(URLRequest(url: url))
+      }
+    } else {
+      let message = runtime.bootError ?? "unknown error"
+      webView.loadHTMLString(
+        "<h1>Apex engine failed to start</h1><pre>\(message)</pre>"
+          + "<p>Check that server.mjs and apex-bridge.js are in the app bundle Resources.</p>",
+        baseURL: nil
+      )
+    }
+    return webView
+  }
+
+  func updateUIView(_ webView: WKWebView, context: Context) {
+    // Stateless — the engine drives everything through the scheme handler. Nothing to reconcile.
+  }
+}

package/templates/mobile/ios/ApexDbStore.swift

@@ -0,0 +1,74 @@
+// ApexDbStore.swift — persistence for the on-device database (Approach A: native file bridge).
+//
+// 1:1 port of android/ApexDbStore.kt. The on-device SQLite lives inside the JS engine as
+// in-memory bytes; to survive a cold start we persist those bytes (base64 of `db.export()`) to a
+// private app file. ApexEngine reads it at boot and injects `__APEX_DB_SNAPSHOT__`; the scheme
+// handler writes it back after a mutating request.
+//
+// ── Where this diverges from Android ──────────────────────────────────────────────────────
+//  • Android writes to `context.filesDir` (app-private) and does an atomic `renameTo`.
+//  • iOS writes to the app's Application Support directory (app-private, backed up, not purgeable
+//    like Caches) and uses `FileManager.replaceItemAt` for the atomic swap — the documented
+//    Foundation primitive for "write tmp, then atomically replace destination".
+
+import Foundation
+
+enum ApexDbStore {
+  private static let fileName = "apex-db.b64"
+
+  /// Application Support dir (created on first use). App-private, included in backups, and — unlike
+  /// Caches — not eligible for eviction under storage pressure, so the DB snapshot is durable.
+  private static func directory() throws -> URL {
+    let fm = FileManager.default
+    let base = try fm.url(
+      for: .applicationSupportDirectory,
+      in: .userDomainMask,
+      appropriateFor: nil,
+      create: true
+    )
+    if !fm.fileExists(atPath: base.path) {
+      try fm.createDirectory(at: base, withIntermediateDirectories: true)
+    }
+    return base
+  }
+
+  private static func fileURL() throws -> URL {
+    try directory().appendingPathComponent(fileName)
+  }
+
+  /// The saved snapshot (base64), or nil if none yet / empty. Mirrors `read()` on Android.
+  static func read() -> String? {
+    guard
+      let url = try? fileURL(),
+      FileManager.default.fileExists(atPath: url.path),
+      let text = try? String(contentsOf: url, encoding: .utf8),
+      !text.isEmpty
+    else {
+      return nil
+    }
+    return text
+  }
+
+  /// Persist the snapshot (base64). A blank value (app has no DB) is ignored. Atomic: write a tmp
+  /// file then swap it into place so a crash mid-write can't corrupt the DB file. Mirrors
+  /// `write()` on Android.
+  static func write(_ base64: String) {
+    guard !base64.isEmpty else { return }
+    do {
+      let fm = FileManager.default
+      let dest = try fileURL()
+      let tmp = try directory().appendingPathComponent("\(fileName).tmp")
+      try base64.data(using: .utf8)?.write(to: tmp, options: .atomic)
+
+      if fm.fileExists(atPath: dest.path) {
+        // Atomic replace of an existing file.
+        _ = try fm.replaceItemAt(dest, withItemAt: tmp)
+      } else {
+        // First write — nothing to replace, just move it into place.
+        try fm.moveItem(at: tmp, to: dest)
+      }
+    } catch {
+      print("[ApexJS] ApexDbStore.write failed: \(error)")
+    }
+  }
+}

package/templates/mobile/ios/ApexEngine.swift

@@ -0,0 +1,253 @@
+// ApexEngine.swift — iOS embedded JS engine for the Apex on-device server bundle.
+//
+// Mirrors android/ApexEngine.kt, but built on **JavaScriptCore** (`JSContext`) instead of
+// androidx.javascriptengine.
+//
+// ── Why this diverges from Android ────────────────────────────────────────────────────────
+//  • Android uses Google's androidx.javascriptengine — an OUT-OF-PROCESS, WebView-backed JS
+//    sandbox. Connecting to it is asynchronous (`createConnectedInstanceAsync(...).await()`),
+//    which is why the Kotlin factory is a `suspend fun`.
+//  • iOS uses JavaScriptCore's `JSContext`, which is IN-PROCESS and synchronous to create and
+//    evaluate. So this initializer is a plain (throwing) init — no async boot handshake needed.
+//  • JSContext ALSO supports host callbacks (Swift closures exposed as JS functions + an
+//    exception handler). Android's sandbox does not; that's the capability we exploit both here
+//    (console/exception bridging) and in the scheme handler (reading POST bodies directly).
+//
+// Load order inside the context (identical contract to Android):
+//   1) restore persisted DB snapshot into `globalThis.__APEX_DB_SNAPSHOT__` (if any),
+//   2) evaluate `server.mjs`   (from `apex build --mobile` — an IIFE that sets globalThis.APEX),
+//   3) evaluate `apex-bridge.js` (defines globalThis.__apexHandle(json) -> Promise<json>).
+//
+// JavaScriptCore is a system framework (`import JavaScriptCore`) — no external dependency, the
+// iOS analogue of Android needing the javascriptengine + coroutines-guava artifacts.
+
+import Foundation
+import JavaScriptCore
+
+final class ApexEngine {
+
+  /// `JSContext` and every JSValue derived from it are NOT thread-safe, so all engine work is
+  /// funnelled through one dedicated thread. That thread has a LARGE stack on purpose:
+  /// JavaScriptCore ties its JS-recursion limit to the native stack, and a normal DispatchQueue
+  /// worker's ~512 KB stack overflows heavy JS ("Maximum call stack size exceeded") — notably the
+  /// asm.js SQLite. 16 MB is plenty and matches what a WKWebView's JS thread gets.
+  private let worker: ApexEngineThread
+  private let context: JSContext
+
+  // MARK: - Boot
+
+  /// Build the engine: create the JSContext, wire host globals JSCore lacks, restore the DB
+  /// snapshot, then evaluate the server bundle + bridge. Synchronous (see file header for why
+  /// this is not async like the Kotlin version). Throws if the bundle resources are missing.
+  init(snapshot: String?, bundle: Bundle = .main) throws {
+    self.worker = ApexEngineThread(stackSize: 16 * 1024 * 1024)
+
+    // Read the bundle resources on the calling thread (plain file I/O).
+    let serverJS = try ApexEngine.bundledSource(resource: "server", ext: "mjs", bundle: bundle)
+    let bridgeJS = try ApexEngine.bundledSource(resource: "apex-bridge", ext: "js", bundle: bundle)
+
+    // Everything that touches the context happens on the high-stack worker thread.
+    let created: JSContext? = worker.sync {
+      guard let context = JSContext() else { return nil }
+
+      // Surface JS errors instead of failing silently. JSCore has no default exception handler.
+      context.exceptionHandler = { _, exception in
+        let message = exception?.toString() ?? "unknown"
+        let stack = exception?.objectForKeyedSubscript("stack")?.toString() ?? ""
+        print("[ApexJS] uncaught JS exception: \(message)\n\(stack)")
+      }
+
+      // `console`: the mobile SHIM installs a NO-OP console via `globalThis.console || {…}`; JSCore
+      // has none, so we set a REAL one first and the shim keeps ours. The only extra global we add
+      // — everything else (Buffer/TextEncoder/URL/Request/Response/Headers/fetch/timers) is in the
+      // bundle's own shim, so we do NOT re-shim it (see NATIVE_SHELL.md).
+      ApexEngine.installConsole(into: context)
+
+      // 1) Restore a persisted DB snapshot (base64 of a prior db.export()) BEFORE the bundle boots.
+      if let snapshot, !snapshot.isEmpty {
+        context.setObject(snapshot, forKeyedSubscript: "__APEX_DB_SNAPSHOT__" as NSString)
+      }
+
+      // 2) + 3) Evaluate the self-contained server bundle (sets globalThis.APEX) then the bridge.
+      context.evaluateScript(serverJS, withSourceURL: URL(string: "apex-internal://server.mjs"))
+      context.evaluateScript(bridgeJS, withSourceURL: URL(string: "apex-internal://apex-bridge.js"))
+
+      let ready = context.evaluateScript("typeof globalThis.__apexHandle === 'function'")?.toBool() ?? false
+      if !ready { print("[ApexJS] WARNING: __apexHandle not defined after loading bundle") }
+      return context
+    }
+
+    guard let context = created else { throw ApexEngineError.contextCreationFailed }
+    self.context = context
+  }
+
+  // MARK: - Request handling
+
+  /// Handle one request. `requestJSON` = {"url","method","headers","body"}.
+  /// Returns {"status","headers","body"} as JSON.
+  ///
+  /// `__apexHandle` returns a JS `Promise<string>`. JavaScriptCore has no built-in async/await
+  /// bridge, so we resolve the promise by attaching `.then(onFulfilled, onRejected)` where both
+  /// handlers are Swift closures exposed as JS functions — the JSContext host-callback capability
+  /// Android's sandbox lacks. The continuation is resumed exactly once.
+  func handle(_ requestJSON: String) async -> String {
+    await withCheckedContinuation { (continuation: CheckedContinuation<String, Never>) in
+      worker.async { [context] in
+        guard
+          let handleFn = context.objectForKeyedSubscript("__apexHandle"),
+          !handleFn.isUndefined, !handleFn.isNull
+        else {
+          continuation.resume(returning: ApexEngine.errorResponseJSON("__apexHandle is not defined"))
+          return
+        }
+
+        guard let promise = handleFn.call(withArguments: [requestJSON]), promise.isObject else {
+          continuation.resume(returning: ApexEngine.errorResponseJSON("__apexHandle did not return a Promise"))
+          return
+        }
+
+        // Guard single resumption. Safe as a plain var: every access happens on the worker thread
+        // (the .then callbacks fire during microtask drain on that same thread).
+        var resumed = false
+        let finish: (String) -> Void = { value in
+          if resumed { return }
+          resumed = true
+          continuation.resume(returning: value)
+        }
+
+        let onFulfilled: @convention(block) (JSValue?) -> Void = { value in
+          finish(value?.toString() ?? "")
+        }
+        let onRejected: @convention(block) (JSValue?) -> Void = { error in
+          finish(ApexEngine.errorResponseJSON(error?.toString() ?? "promise rejected"))
+        }
+
+        // Attach both handlers in one `.then(f, r)` call. JavaScriptCore drains the promise
+        // microtask queue at the end of this JS turn; our pipeline is fully synchronous in-memory
+        // (no real I/O), so the promise settles and the callback runs before invokeMethod returns.
+        promise.invokeMethod(
+          "then",
+          withArguments: [
+            JSValue(object: onFulfilled, in: context) as Any,
+            JSValue(object: onRejected, in: context) as Any,
+          ]
+        )
+      }
+    }
+  }
+
+  // MARK: - Persistence seam
+
+  /// Current DB bytes (base64) for persistence, or "" if the app has no on-device DB.
+  /// Mirrors `ApexEngine.snapshot()` on Android — evaluated synchronously (the export function is
+  /// synchronous; if it were a Promise this would return "[object Promise]", same as Android).
+  func snapshot() -> String {
+    worker.sync {
+      let result = context.evaluateScript(
+        "(typeof __APEX_DB_EXPORT__==='function')?__APEX_DB_EXPORT__():''"
+      )
+      return result?.toString() ?? ""
+    }
+  }
+
+  // MARK: - Helpers
+
+  private static func installConsole(into context: JSContext) {
+    // Uses JSContext.currentArguments() so variadic console.log(a, b, c) is captured, not just
+    // the first arg. A debug aid only; production can leave the shim's no-op console in place.
+    let log: @convention(block) () -> Void = {
+      let args = (JSContext.currentArguments() as? [JSValue]) ?? []
+      let line = args.map { $0.toString() ?? "" }.joined(separator: " ")
+      print("[ApexJS] " + line)
+    }
+    guard let console = JSValue(newObjectIn: context) else { return }
+    for method in ["log", "error", "warn", "info", "debug"] {
+      console.setObject(log, forKeyedSubscript: method as NSString)
+    }
+    context.setObject(console, forKeyedSubscript: "console" as NSString)
+  }
+
+  /// Read a bundled JS resource from the app bundle Resources as UTF-8 text.
+  private static func bundledSource(resource: String, ext: String, bundle: Bundle) throws -> String {
+    guard let url = bundle.url(forResource: resource, withExtension: ext) else {
+      throw ApexEngineError.missingResource("\(resource).\(ext)")
+    }
+    return try String(contentsOf: url, encoding: .utf8)
+  }
+
+  /// A well-formed {status,headers,body} JSON string so the scheme handler can always render
+  /// something (a 500 page) instead of failing to parse.
+  static func errorResponseJSON(_ message: String) -> String {
+    let body = "<h1>Apex engine error</h1><pre>\(message)</pre>"
+    let payload: [String: Any] = [
+      "status": 500,
+      "headers": ["content-type": "text/html; charset=utf-8"],
+      "body": body,
+    ]
+    if let data = try? JSONSerialization.data(withJSONObject: payload),
+       let json = String(data: data, encoding: .utf8) {
+      return json
+    }
+    return #"{"status":500,"headers":{"content-type":"text/html"},"body":"Apex engine error"}"#
+  }
+}
+
+enum ApexEngineError: Error, CustomStringConvertible {
+  case contextCreationFailed
+  case missingResource(String)
+
+  var description: String {
+    switch self {
+    case .contextCreationFailed: return "Failed to create JSContext"
+    case .missingResource(let name): return "Missing bundle resource: \(name)"
+    }
+  }
+}
+
+/// A single long-lived thread with a LARGE stack that runs a run loop, so all JSContext work has
+/// enough native stack for heavy JS. JavaScriptCore derives its JS call-stack limit from the
+/// native thread stack; the default GCD worker stack (~512 KB) overflows the asm.js SQLite with
+/// "Maximum call stack size exceeded". Work is marshalled on with `perform(_:on:...)`.
+final class ApexEngineThread: NSObject {
+  private let thread: Thread
+
+  init(stackSize: Int) {
+    let ready = DispatchSemaphore(value: 0)
+    let t = Thread {
+      // Keep the run loop alive with a dummy port source, then run it forever.
+      let runLoop = RunLoop.current
+      runLoop.add(NSMachPort(), forMode: .default)
+      ready.signal()
+      runLoop.run()
+    }
+    t.stackSize = stackSize
+    t.name = "site.apexjs.shell.engine"
+    self.thread = t
+    super.init()
+    t.start()
+    ready.wait() // ensure the run loop is up before we schedule work
+  }
+
+  /// Boxes a closure so it can ride across `perform(_:on:with:)` (which takes an object).
+  private final class Work {
+    let block: () -> Void
+    init(_ block: @escaping () -> Void) { self.block = block }
+  }
+
+  @objc private func run(_ box: Any) { (box as? Work)?.block() }
+
+  /// Run asynchronously on the engine thread.
+  func async(_ block: @escaping () -> Void) {
+    perform(#selector(run(_:)), on: thread, with: Work(block), waitUntilDone: false)
+  }
+
+  /// Run synchronously on the engine thread and return its result. `waitUntilDone: true` executes
+  /// the block before returning, so the non-escaping closure is safe via `withoutActuallyEscaping`.
+  func sync<T>(_ block: () -> T) -> T {
+    var result: T!
+    withoutActuallyEscaping(block) { escapable in
+      perform(#selector(run(_:)), on: thread, with: Work({ result = escapable() }), waitUntilDone: true)
+    }
+    return result
+  }
+}