create-apexjs 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apexjs",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Scaffold a new Apex JS app",
   "type": "module",
   "license": "MIT",

package/templates/default/AGENTS.md

@@ -21,8 +21,8 @@ apex make page dashboard          # pages/dashboard.alpine (a route → /dashboa
 apex make component Card          # components/Card.alpine  (<Card /> in templates)
 apex make component ui/Navbar     # group in a folder → components/ui/Navbar.alpine (<UiNavbar />)
 apex make client                  # app.client.ts — register Alpine plugins/directives/magics
-apex make model Post title:string body:string   # models/Post.ts → defineModel('posts') → /api/posts + MCP CRUD
-apex make composable Post         # composables/usePosts.ts — typed client data-hook off the model
+apex make model Article title:string body:string # models/Article.ts → defineModel('articles') → /api/articles + MCP CRUD (avoid `Post` — the starter ships a posts demo)
+apex make composable Article      # composables/useArticles.ts — typed client data-hook off the model (make the model first)
 apex make api webhooks            # server/api/webhooks.ts (defineApexRoute; also an MCP tool)
 apex make service Billing         # services/BillingService.ts
 apex extend auth                  # add sealed-cookie sessions + login/logout + /account
@@ -36,12 +36,12 @@ apex test                         # run Vitest
 ```
 `apex make <kind> …` kinds: `page component api service store layout middleware test model migration auth client composable`.
 
-**Data flow, end to end.** One `defineModel` drives the whole stack: schema + migration + REST (`/api/posts` list/get/create/update/delete) + MCP tools **and** the client. `apex make composable Post` emits `composables/usePosts.ts` — a typed `usePosts()` returning `items / loading / error` + `fetch / find / create / update / remove` bound to that resource. Spread it into an x-data:
+**Data flow, end to end.** One `defineModel` drives the whole stack: schema + migration + REST (`/api/articles` list/get/create/update/delete) + MCP tools **and** the client. `apex make composable Article` emits `composables/useArticles.ts` — a typed `useArticles()` returning `items / loading / error` + `fetch / find / create / update / remove` bound to that resource. Spread it into an x-data:
 ```alpine
 <script client>
-  import { usePosts } from '../composables/usePosts'
+  import { useArticles } from '../composables/useArticles'
 </script>
-<template x-data="{ ...usePosts(), init() { this.fetch() } }">
+<template x-data="{ ...useArticles(), init() { this.fetch() } }">
   <template x-for="p in items" :key="p.id"><li x-text="p.title"></li></template>
 </template>
 ```
@@ -87,7 +87,7 @@ tests/*.test.ts     Vitest. createTestApp boots the whole app in-process.
 
 ## APIs you'll use (import from `@apex-stack/core`, `/server`, `/testing`; data from `@apex-stack/data`)
 - **Route** → `defineApexRoute({ method, input: { …zod }, mcp: true, auth: true, can, handler })`. `mcp: true` makes it an AI-callable tool at `/mcp`.
-- **Model** → `defineModel('posts', { fields: {…}, use: [timestamps(), owned()] })` → `.resource(handle)` mounts REST + MCP CRUD.
+- **Model** → `defineModel('articles', { fields: {…}, use: [timestamps(), owned()] })` → `.resource(handle)` mounts REST + MCP CRUD. Its route imports `@apex-stack/data`, so install it (`npm i @apex-stack/data @libsql/client`) — otherwise `createTestApp` can't mount `/api` and every API test errors (or pass `createTestApp({ root, lenientRoutes: true })` to skip unresolvable routes).
 - **Auth** → `server/auth.ts` default-exports `sessionAuth({ password })`; gate routes with `auth: true` / `can`. In loaders, the user is `locals.user`.
 - **Config** → `apex.config.ts`: `defineConfig({ runtimeConfig: { …, public: {…} }, i18n: {…} })`. Read with `useRuntimeConfig()`.
 - **Test** → `createTestApp({ root })` → `app.get/post(path, body?, { user })`, `app.mcp.listTools()`.

package/templates/default/layouts/default.alpine

@@ -4,29 +4,58 @@
 <template>
   <div class="flex min-h-svh flex-col bg-surface text-on-surface dark:bg-surface-dark dark:text-on-surface-dark">
     <header class="border-b border-outline dark:border-outline-dark">
-      <nav
-        class="mx-auto flex max-w-5xl items-center gap-2 px-6 py-4"
-        x-data="{ dark: false }"
+      <div
+        class="relative"
+        x-data="{ dark: false, open: false }"
         x-init="dark = localStorage.getItem('theme') ? localStorage.getItem('theme') === 'dark' : (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches); document.documentElement.classList.toggle('dark', dark)"
+        @resize.window="open = false"
         client:load
       >
-        <a href="/" class="mr-auto flex items-center gap-2 font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">
-          <img src="/favicon.svg" alt="" width="24" height="24" class="size-6" />
-          {{name}}
-        </a>
-        <a href="/" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Home</a>
-        <a href="/blog" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Blog</a>
-        <a href="/about" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">About</a>
-        <button
-          type="button"
-          aria-label="Toggle dark mode"
-          class="ml-1 rounded-radius border border-outline p-2 text-on-surface hover:bg-surface-alt dark:border-outline-dark dark:text-on-surface-dark dark:hover:bg-surface-dark-alt"
-          @click="dark = !dark; document.documentElement.classList.toggle('dark', dark); localStorage.setItem('theme', dark ? 'dark' : 'light')"
+        <nav class="mx-auto flex max-w-5xl items-center gap-2 px-6 py-4">
+          <a href="/" class="mr-auto flex items-center gap-2 font-title text-lg font-bold text-on-surface-strong dark:text-on-surface-dark-strong">
+            <img src="/favicon.svg" alt="" width="24" height="24" class="size-6" />
+            {{name}}
+          </a>
+          <!-- Inline links on ≥sm; collapse into the hamburger menu on mobile. -->
+          <div class="hidden items-center gap-1 sm:flex">
+            <a href="/" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Home</a>
+            <a href="/blog" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Blog</a>
+            <a href="/about" class="rounded-radius px-3 py-1.5 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">About</a>
+          </div>
+          <button
+            type="button"
+            aria-label="Toggle dark mode"
+            class="rounded-radius border border-outline p-2 text-on-surface hover:bg-surface-alt dark:border-outline-dark dark:text-on-surface-dark dark:hover:bg-surface-dark-alt"
+            @click="dark = !dark; document.documentElement.classList.toggle('dark', dark); localStorage.setItem('theme', dark ? 'dark' : 'light')"
+          >
+            <svg x-show="!dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
+            <svg x-cloak x-show="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+          </button>
+          <!-- Hamburger: mobile only. -->
+          <button
+            type="button"
+            aria-label="Menu"
+            :aria-expanded="open"
+            class="rounded-radius border border-outline p-2 text-on-surface hover:bg-surface-alt sm:hidden dark:border-outline-dark dark:text-on-surface-dark dark:hover:bg-surface-dark-alt"
+            @click="open = !open"
+          >
+            <svg x-show="!open" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16"/></svg>
+            <svg x-cloak x-show="open" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18"/></svg>
+          </button>
+        </nav>
+        <!-- Floating mobile menu — overlays the page (doesn't push content down). -->
+        <div x-cloak x-show="open" @click="open = false" class="fixed inset-0 z-40 sm:hidden" aria-hidden="true"></div>
+        <div
+          x-cloak x-show="open"
+          x-transition:enter="transition ease-out duration-150" x-transition:enter-start="opacity-0 -translate-y-1" x-transition:enter-end="opacity-100 translate-y-0"
+          x-transition:leave="transition ease-in duration-100" x-transition:leave-start="opacity-100" x-transition:leave-end="opacity-0"
+          class="absolute right-4 top-full z-50 mt-1 w-52 rounded-radius border border-outline bg-surface p-1.5 shadow-lg sm:hidden dark:border-outline-dark dark:bg-surface-dark"
         >
-          <svg x-show="!dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
-          <svg x-cloak x-show="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
-        </button>
-      </nav>
+          <a href="/" @click="open = false" class="block rounded-radius px-3 py-2 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Home</a>
+          <a href="/blog" @click="open = false" class="block rounded-radius px-3 py-2 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">Blog</a>
+          <a href="/about" @click="open = false" class="block rounded-radius px-3 py-2 text-sm font-medium hover:bg-surface-alt dark:hover:bg-surface-dark-alt">About</a>
+        </div>
+      </div>
     </header>
 
     <main class="mx-auto w-full max-w-5xl flex-1 px-6 py-10">

package/templates/features/data/db/index.ts

@@ -1,28 +1,29 @@
-import { createDb } from '@apex-stack/data'
+import { lazyDb } from '@apex-stack/data'
 import { Message } from '../models/Message.js'
 
-// Use a hosted Postgres (Supabase / Neon / any Postgres) when DATABASE_URL is
-// set — otherwise an in-memory libSQL for zero-setup local dev. createDb
-// auto-tunes Postgres for a transaction pooler (e.g. Supabase's, on port 6543):
-// it disables prepared statements and enables SSL. Requires the `postgres` driver
-// (already a dependency of this app).
+// Open the database lazily — no top-level `await`, so this module also bundles into the
+// classic-script `apex build --mobile` output (a bare on-device engine can't do top-level
+// await). On-device, `createDb`'s libSQL driver transparently becomes an in-memory sql.js
+// database; a hosted Postgres is used when DATABASE_URL is set (server/dev only). The real
+// connection opens + migrates + seeds on first use.
 const url = process.env.DATABASE_URL
-export const handle = url
-  ? await createDb({ driver: 'postgres', url })
-  : await createDb({ driver: 'libsql', url: ':memory:' })
+export const handle = lazyDb(
+  () => (url ? { driver: 'postgres', url } : { driver: 'libsql', url: ':memory:' }),
+  {
+    init: async (h) => {
+      // Create the schema — dialect-aware (SQLite vs Postgres) and idempotent, from the model.
+      await h.exec(Message.migrationSql(h.dialect))
 
-// Create the schema — dialect-aware (SQLite vs Postgres) and idempotent, straight
-// from the model. For a long-lived Postgres you'd normally run `apex migrate`
-// once and drop this; keeping it makes the showcase zero-setup on either backend.
-await handle.exec(Message.migrationSql(handle.dialect))
-
-// Seed a couple of rows if the table is empty.
-const now = handle.dialect === 'postgres' ? 'now()' : "datetime('now')"
-const seeded = await handle.query('SELECT COUNT(*) AS n FROM messages')
-if (Number(seeded[0]?.n ?? 0) === 0) {
-  await handle.exec(
-    `INSERT INTO messages (author, body, created_at, updated_at) VALUES
-      ('Ada Lovelace', 'Apex feels like HTML with superpowers.', ${now}, ${now}),
-      ('Alan Turing', 'One route — and my AI assistant can call it too.', ${now}, ${now})`,
-  )
-}
+      // Seed a couple of rows if the table is empty.
+      const now = h.dialect === 'postgres' ? 'now()' : "datetime('now')"
+      const seeded = await h.query('SELECT COUNT(*) AS n FROM messages')
+      if (Number(seeded[0]?.n ?? 0) === 0) {
+        await h.exec(
+          `INSERT INTO messages (author, body, created_at, updated_at) VALUES
+            ('Ada Lovelace', 'Apex feels like HTML with superpowers.', ${now}, ${now}),
+            ('Alan Turing', 'One route — and my AI assistant can call it too.', ${now}, ${now})`,
+        )
+      }
+    },
+  },
+)

package/templates/mobile/android/README.md

@@ -0,0 +1,53 @@
+# Apex Android shell
+
+A native Android app that runs your Apex backend **on the device** (offline, no server) and
+renders it in a WebView. Produced by `assemble-android.mjs` + `apex build --mobile`.
+
+## What's here
+```
+android/
+├─ settings.gradle.kts / build.gradle.kts / gradle.properties
+├─ app/build.gradle.kts                 # androidx.javascriptengine + splashscreen + coroutines
+└─ app/src/main/
+   ├─ AndroidManifest.xml               # launcher activity, no INTERNET permission (offline)
+   ├─ java/site/apexjs/shell/
+   │   ├─ MainActivity.kt               # WebView + native splash → loads /splash
+   │   ├─ ApexEngine.kt                 # loads server.mjs + apex-bridge.js, runs __apexHandle
+   │   └─ ApexInterceptor.kt            # every request → engine (assets served from APK)
+   ├─ assets/                           # ← server.mjs, apex-bridge.js, client assets (assembler fills)
+   └─ res/                              # ← generated launcher icon, adaptive icon, splash color
+```
+
+## Build it
+From your **Apex app root**:
+```bash
+node path/to/native-shell/assemble-android.mjs --icon public/icon.png --splash public/icon.png --bg '#0b1120'
+```
+That runs `apex build --mobile`, copies the bundle + client assets into `app/src/main/assets/`,
+and generates the launcher/adaptive icons + native splash from your source image.
+
+Then:
+```bash
+cd native-shell/android
+./gradlew assembleDebug          # → app/build/outputs/apk/debug/app-debug.apk
+# or open the folder in Android Studio and Run on the emulator
+adb install -r app/build/outputs/apk/debug/app-debug.apk
+```
+
+The installed app has your **launcher icon**, shows the **native splash** (icon on your bg),
+then your **`pages/splash.alpine`** animated intro, then the app — all rendered by the Apex
+server running inside the app on `androidx.javascriptengine`. Turn Wi-Fi off: it still works.
+
+## Engine note
+`ApexEngine` uses Google's **androidx.javascriptengine** (out-of-process JS sandbox, no JNI).
+`__apexHandle` returns a `Promise<string>`; that resolves via the `PROMISE_RETURN` feature
+(beta01+). Swap in an embedded QuickJS (JNI) or Hermes (in an RN shell) with the same shape.
+
+## On-device drivers
+`apex build --mobile` reports routes needing `crypto.subtle` (sessions) or `@libsql/client/web`
+(DB). `androidx.javascriptengine` provides `crypto`; for DB, alias `@libsql/client` →
+`@libsql/client/web` (WASM) before bundling, or bridge to Android's native SQLite.
+
+## Verify (before a device)
+`node ../verify-bundle.mjs ../../<app>/dist/mobile/server.mjs` renders the bundle under QuickJS
+on your machine — proves the on-device path without building the APK.

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

@@ -0,0 +1,30 @@
+plugins {
+  id("com.android.application")
+  id("org.jetbrains.kotlin.android")
+}
+android {
+  namespace = "site.apexjs.shell"
+  compileSdk = 34
+  defaultConfig {
+    applicationId = "site.apexjs.shell"
+    minSdk = 26           // adaptive icons + androidx.javascriptengine
+    targetSdk = 34
+    versionCode = 1
+    versionName = "1.0"
+  }
+  compileOptions {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+  }
+  kotlinOptions { jvmTarget = "17" }
+}
+dependencies {
+  implementation("androidx.core:core-ktx:1.13.1")
+  implementation("androidx.core:core-splashscreen:1.0.1")
+  implementation("androidx.appcompat:appcompat:1.7.0")
+  implementation("androidx.activity:activity-ktx:1.9.2")
+  implementation("androidx.javascriptengine:javascriptengine:1.0.0-beta01")
+  implementation("androidx.webkit:webkit:1.11.0") // WebViewCompat.addDocumentStartJavaScript
+  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
+  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.8.1")
+}

package/templates/mobile/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <!-- No INTERNET permission needed: the backend runs on-device, offline. Add it only if
+       your app makes outbound network calls. -->
+
+  <application
+    android:allowBackup="true"
+    android:icon="@mipmap/ic_launcher"
+    android:roundIcon="@mipmap/ic_launcher_round"
+    android:label="@string/app_name"
+    android:theme="@style/Theme.Apex.Splash">
+
+    <activity
+      android:name=".MainActivity"
+      android:exported="true"
+      android:configChanges="orientation|screenSize|keyboardHidden">
+      <intent-filter>
+        <action android:name="android.intent.action.MAIN" />
+        <category android:name="android.intent.category.LAUNCHER" />
+      </intent-filter>
+    </activity>
+  </application>
+</manifest>

package/templates/mobile/android/app/src/main/java/site/apexjs/shell/ApexBridge.kt

@@ -0,0 +1,59 @@
+package site.apexjs.shell
+
+import android.content.Context
+import android.webkit.CookieManager
+import android.webkit.JavascriptInterface
+import kotlinx.coroutines.runBlocking
+import org.json.JSONObject
+
+/**
+ * JS -> native bridge for DYNAMIC requests (fetch/XHR) from the page.
+ *
+ * Android's WebViewClient.shouldInterceptRequest cannot read a request BODY, so POST/PUT/PATCH
+ * from the app's fetch() calls (e.g. POST /api/messages, /api/login) are routed here instead —
+ * see the document-start fetch patch installed in MainActivity — where the body IS available.
+ *
+ * It also owns the HttpOnly session cookie via CookieManager: the page can't read or set an
+ * HttpOnly cookie itself, so the bridge injects the stored Cookie on the way in and persists
+ * any Set-Cookie on the way out. Navigations (GET) go through ApexInterceptor, which does the
+ * same, so a login made via fetch() is visible to the next full page load.
+ *
+ * @JavascriptInterface methods run on a WebView binder thread (not the UI thread), so blocking
+ * on the engine coroutine here is fine. NOTE: avoid a slash-star sequence in KDoc.
+ */
+class ApexBridge(private val engine: ApexEngine, private val context: Context) {
+  @JavascriptInterface
+  fun handle(requestJson: String): String {
+    val req = JSONObject(requestJson)
+    val url = req.optString("url")
+    val method = req.optString("method", "GET").uppercase()
+    val headers = req.optJSONObject("headers") ?: JSONObject()
+
+    // Attach the stored session cookie (the page can't read HttpOnly cookies).
+    val cookie = CookieManager.getInstance().getCookie(url)
+    if (!cookie.isNullOrBlank() && !headers.has("cookie")) headers.put("cookie", cookie)
+    req.put("headers", headers)
+
+    val resStr = runBlocking { engine.handle(req.toString()) }
+    persistSetCookie(url, resStr)
+
+    // A mutating request may have changed the DB — persist a fresh snapshot so it survives a
+    // cold start. (All body-bearing writes come through this bridge; navigations are GET.)
+    if (method != "GET" && method != "HEAD" && method != "OPTIONS") {
+      runBlocking { ApexDbStore.write(context, engine.snapshot()) }
+    }
+    return resStr
+  }
+
+  companion object {
+    /** Store any Set-Cookie from an engine response JSON into the CookieManager. */
+    fun persistSetCookie(url: String, responseJson: String) {
+      val setCookie = JSONObject(responseJson).optJSONObject("headers")?.optString("set-cookie").orEmpty()
+      if (setCookie.isBlank()) return
+      val cm = CookieManager.getInstance()
+      // A combined header may hold several cookies separated by ", " before a `name=`.
+      setCookie.split(Regex(",(?=[^;,]+=)")).forEach { cm.setCookie(url, it.trim()) }
+      cm.flush()
+    }
+  }
+}

package/templates/mobile/android/app/src/main/java/site/apexjs/shell/ApexDbStore.kt

@@ -0,0 +1,31 @@
+package site.apexjs.shell
+
+import android.content.Context
+import java.io.File
+
+/**
+ * Persistence for the on-device database (Approach A: native file bridge).
+ *
+ * The on-device SQLite lives in 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__`; ApexBridge writes it back after a mutating request.
+ * Simple, atomic-enough for a single-user app, and no extra dependency.
+ */
+object ApexDbStore {
+  private const val FILE = "apex-db.b64"
+
+  private fun file(context: Context) = File(context.filesDir, FILE)
+
+  /** The saved snapshot (base64), or null if none yet. */
+  fun read(context: Context): String? =
+    file(context).takeIf { it.exists() }?.readText()?.ifBlank { null }
+
+  /** Persist the snapshot (base64). A blank value (app has no DB) is ignored. */
+  fun write(context: Context, base64: String) {
+    if (base64.isBlank()) return
+    val f = file(context)
+    val tmp = File(f.parentFile, "$FILE.tmp")
+    tmp.writeText(base64)
+    tmp.renameTo(f) // replace atomically so a crash mid-write can't corrupt the DB file
+  }
+}

package/templates/mobile/android/app/src/main/java/site/apexjs/shell/ApexEngine.kt

@@ -0,0 +1,66 @@
+package site.apexjs.shell
+
+import android.content.Context
+import androidx.javascriptengine.JavaScriptSandbox
+import androidx.javascriptengine.JavaScriptIsolate
+import kotlinx.coroutines.guava.await
+
+/**
+ * Embedded JS engine that runs the Apex on-device server bundle.
+ *
+ * Uses Google's official androidx.javascriptengine (a WebView-backed, out-of-process JS
+ * sandbox — no JNI, no bundled engine). It loads `server.mjs` (from `apex build --mobile`)
+ * and `apex-bridge.js` from assets, then evaluates `__apexHandle(requestJson)` per request.
+ *
+ * Alternative engines with the same shape: an embedded QuickJS (react-native-quick-js /
+ * a QuickJS-Android JNI wrapper) or, in a React Native shell, Hermes directly.
+ *
+ * Gradle: implementation("androidx.javascriptengine:javascriptengine:1.0.0-beta01")
+ *         implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:<ver>")
+ */
+class ApexEngine private constructor(
+  private val sandbox: JavaScriptSandbox,
+  private val isolate: JavaScriptIsolate,
+) {
+  companion object {
+    suspend fun create(context: Context): ApexEngine {
+      val sandbox = JavaScriptSandbox.createConnectedInstanceAsync(context).await()
+      val isolate = sandbox.createIsolate()
+      // Restore a persisted DB snapshot (if any) BEFORE the bundle boots, so the on-device
+      // database opens from it instead of empty. See ApexDbStore + ApexBridge.
+      ApexDbStore.read(context)?.let { snap ->
+        isolate.evaluateJavaScriptAsync(
+          "globalThis.__APEX_DB_SNAPSHOT__=" + org.json.JSONObject.quote(snap),
+        ).await()
+      }
+      // Load the self-contained server bundle (sets globalThis.APEX) then the bridge.
+      isolate.evaluateJavaScriptAsync(context.assets.readText("server.mjs")).await()
+      isolate.evaluateJavaScriptAsync(context.assets.readText("apex-bridge.js")).await()
+      return ApexEngine(sandbox, isolate)
+    }
+  }
+
+  /** Current DB bytes (base64) for persistence, or "" if the app has no on-device DB. */
+  suspend fun snapshot(): String =
+    isolate.evaluateJavaScriptAsync(
+      "(typeof __APEX_DB_EXPORT__==='function')?__APEX_DB_EXPORT__():''",
+    ).await()
+
+  /**
+   * Handle one request. `requestJson` = {"url","method","headers","body"}.
+   * Returns {"status","headers","body"} as JSON. __apexHandle returns a Promise<string>;
+   * javascriptengine resolves it when the PROMISE_RETURN feature is supported (beta01+).
+   */
+  suspend fun handle(requestJson: String): String {
+    val escaped = org.json.JSONObject.quote(requestJson) // safe JS string literal
+    return isolate.evaluateJavaScriptAsync("__apexHandle($escaped)").await()
+  }
+
+  fun close() {
+    isolate.close()
+    sandbox.close()
+  }
+}
+
+private fun android.content.res.AssetManager.readText(name: String): String =
+  open(name).bufferedReader().use { it.readText() }

package/templates/mobile/android/app/src/main/java/site/apexjs/shell/ApexInterceptor.kt

@@ -0,0 +1,83 @@
+package site.apexjs.shell
+
+import android.content.Context
+import android.webkit.WebResourceRequest
+import android.webkit.WebResourceResponse
+import android.webkit.WebView
+import android.webkit.WebViewClient
+import kotlinx.coroutines.runBlocking
+import org.json.JSONObject
+import java.io.ByteArrayInputStream
+
+/**
+ * Serves every WebView request from the on-device Apex engine — offline, no network.
+ * Static client assets (the built client bundle under assets, favicon) are served straight from
+ * the APK; everything else goes to `__apexHandle` (SSR pages + /api). shouldInterceptRequest runs
+ * off the UI thread, so blocking on the engine coroutine here is fine.
+ * NOTE: avoid a slash-star sequence in KDoc — Kotlin block comments nest and it won't close.
+ */
+class ApexInterceptor(
+  private val context: Context,
+  private val engine: ApexEngine,
+) : WebViewClient() {
+
+  override fun shouldInterceptRequest(
+    view: WebView,
+    request: WebResourceRequest,
+  ): WebResourceResponse? {
+    val path = request.url.path ?: "/"
+
+    // 1) Static client assets from the APK (client JS/CSS bundle, favicon).
+    if (path.startsWith("/assets/") || path == "/favicon.svg") {
+      return try {
+        val asset = context.assets.open(path.removePrefix("/"))
+        WebResourceResponse(mimeOf(path), "utf-8", asset)
+      } catch (e: Exception) {
+        null
+      }
+    }
+
+    // 2) Dynamic routes (SSR pages) → the engine. shouldInterceptRequest can't read a request
+    //    body, so these are effectively GET/navigation; POST/fetch with a body goes through the
+    //    ApexBridge JS interface instead. We inject the stored session cookie so a login made via
+    //    fetch() is visible to the next full page load.
+    val url = request.url.toString()
+    val reqHeaders = JSONObject(request.requestHeaders as Map<*, *>)
+    val cookie = android.webkit.CookieManager.getInstance().getCookie(url)
+    if (!cookie.isNullOrBlank() && !reqHeaders.has("cookie") && !reqHeaders.has("Cookie")) {
+      reqHeaders.put("cookie", cookie)
+    }
+    val reqJson = JSONObject().apply {
+      put("url", url)
+      put("method", request.method)
+      put("headers", reqHeaders)
+      put("body", JSONObject.NULL)
+    }.toString()
+
+    val resStr = try {
+      runBlocking { engine.handle(reqJson) }
+    } catch (e: Exception) {
+      return WebResourceResponse("text/html", "utf-8", 500, "Server Error", emptyMap(),
+        ByteArrayInputStream("<h1>Apex engine error</h1><pre>${e.message}</pre>".toByteArray()))
+    }
+    ApexBridge.persistSetCookie(url, resStr)
+    val res = JSONObject(resStr)
+
+    val headers = res.optJSONObject("headers") ?: JSONObject()
+    val contentType = headers.optString("content-type", "text/html")
+    return WebResourceResponse(
+      contentType.substringBefore(";").ifBlank { "text/html" },
+      "utf-8",
+      res.optInt("status", 200),
+      "OK",
+      headers.keys().asSequence().associateWith { headers.getString(it) },
+      ByteArrayInputStream(res.optString("body", "").toByteArray(Charsets.UTF_8)),
+    )
+  }
+
+  private fun mimeOf(path: String) = when (path.substringAfterLast('.')) {
+    "js", "mjs" -> "text/javascript"; "css" -> "text/css"; "svg" -> "image/svg+xml"
+    "json" -> "application/json"; "png" -> "image/png"; "woff2" -> "font/woff2"
+    else -> "application/octet-stream"
+  }
+}

package/templates/mobile/android/app/src/main/java/site/apexjs/shell/MainActivity.kt

@@ -0,0 +1,96 @@
+package site.apexjs.shell
+
+import android.os.Bundle
+import android.webkit.CookieManager
+import android.webkit.WebView
+import androidx.activity.ComponentActivity
+import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
+import androidx.webkit.WebViewCompat
+import androidx.webkit.WebViewFeature
+import kotlinx.coroutines.launch
+import androidx.lifecycle.lifecycleScope
+
+// Installed at document-start (before any page script) so the app's fetch() calls — which
+// carry a request BODY the native interceptor can't see — route through the ApexBridge JS
+// interface to the on-device engine. Same-origin only; anything else falls back to real fetch.
+private const val FETCH_PATCH = """
+(function(){
+  if (window.__apexFetchPatched) return; window.__apexFetchPatched = true;
+  var orig = window.fetch ? window.fetch.bind(window) : null;
+  window.fetch = function(input, init){
+    return new Promise(function(resolve, reject){
+      try {
+        init = init || {};
+        var url = typeof input === 'string' ? input : (input && input.url);
+        var abs = new URL(url, location.href);
+        if (abs.origin !== location.origin || !window.__ApexNative) {
+          if (orig) { resolve(orig(input, init)); return; } throw new Error('no fetch');
+        }
+        var method = (init.method || (typeof input !== 'string' && input && input.method) || 'GET').toUpperCase();
+        var headers = {};
+        var ih = init.headers || (typeof input !== 'string' && input && input.headers);
+        if (ih) { if (typeof ih.forEach === 'function') ih.forEach(function(v,k){ headers[k]=v; }); else for (var k in ih) headers[k]=ih[k]; }
+        if (!headers.origin && !headers.Origin) headers.origin = location.origin;
+        var body = init.body != null ? (typeof init.body === 'string' ? init.body : JSON.stringify(init.body)) : null;
+        var resStr = window.__ApexNative.handle(JSON.stringify({ url: abs.href, method: method, headers: headers, body: body }));
+        var res = JSON.parse(resStr);
+        resolve(new Response(res.body, { status: res.status || 200, headers: res.headers || {} }));
+      } catch (e) { if (orig) resolve(orig(input, init)); else reject(e); }
+    });
+  };
+})();
+"""
+
+/**
+ * The Apex native shell. Boots the embedded JS engine (which runs the on-device Apex server
+ * bundle), points a WebView at the app root, and intercepts every request to serve it from
+ * that engine — offline, no server, no port.
+ *
+ * Splash: the native cold-start splash (Theme.Apex.Splash) bridges process start; the WebView
+ * then loads the `pages/splash.alpine` route (your animated intro, SSR-rendered instantly),
+ * which navigates to `/` when it signals ready.
+ */
+class MainActivity : ComponentActivity() {
+  private lateinit var engine: ApexEngine
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    val splash = installSplashScreen() // native cold-start splash (androidx.core:core-splashscreen)
+    super.onCreate(savedInstanceState)
+
+    val webView = WebView(this)
+    setContentView(webView)
+    webView.settings.javaScriptEnabled = true
+    webView.settings.domStorageEnabled = true
+
+    // Cookies: the session is an HttpOnly cookie the bridge/interceptor manage via CookieManager.
+    CookieManager.getInstance().setAcceptCookie(true)
+    CookieManager.getInstance().setAcceptThirdPartyCookies(webView, true)
+
+    lifecycleScope.launch {
+      // 1) Start the engine + load the on-device server bundle from assets/.
+      engine = ApexEngine.create(applicationContext)
+
+      // 2) Intercept navigations/static → engine (assets served directly).
+      webView.webViewClient = ApexInterceptor(applicationContext, engine)
+
+      // 3) Bridge dynamic fetch() (with bodies) → engine. shouldInterceptRequest can't read a
+      //    request body, so POST/login go through this JS interface + a document-start patch.
+      webView.addJavascriptInterface(ApexBridge(engine, applicationContext), "__ApexNative")
+      if (WebViewFeature.isFeatureSupported(WebViewFeature.DOCUMENT_START_SCRIPT)) {
+        WebViewCompat.addDocumentStartJavaScript(webView, FETCH_PATCH, setOf("*"))
+      }
+
+      // 4) Load the app. Start at the animated splash route; it navigates to '/' when ready.
+      //    (Any origin — every request is intercepted; the host is ignored.)
+      webView.loadUrl("https://localhost/splash")
+
+      // Keep the native splash until the first paint, then let the .alpine splash take over.
+      splash.setKeepOnScreenCondition { false }
+    }
+  }
+
+  override fun onDestroy() {
+    if (::engine.isInitialized) engine.close()
+    super.onDestroy()
+  }
+}