create-apexjs 0.6.6 → 0.6.8

package/templates/mobile/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?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>

package/templates/mobile/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?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>

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)")
+    }
+  }
+}