@mentra/crust 3.2.1-dev.314 → 3.3.0-beta.942

package/README.md

@@ -31,6 +31,13 @@ core-library desugaring. Add it to the host app's Expo config:
 Building with the navigation feature requires a `MAPBOX_DOWNLOADS_TOKEN` in
 the Android build environment (Mapbox's SDK repository is authenticated).
 
+The plugin also raises the host's Android build to Kotlin 2.3.0 (crust's
+QuickJS library, `quickjs-kt` 1.0.15, is compiled with Kotlin 2.4) and pins
+the root Kotlin Gradle plugin to that version. Every native module in the
+host then compiles with Kotlin 2.3. Known incompatibility:
+`react-native-gesture-handler` before 2.31.0 fails to compile; use 2.31.0 or
+later.
+
 At build time the Android side also reads the MentraJS polyfill bundle from
 its [`@mentra/jspolyfill`](https://www.npmjs.com/package/@mentra/jspolyfill)
 sibling, which is declared as a dependency.
@@ -39,3 +46,23 @@ sibling, which is declared as a dependency.
 
 Source lives in the [MentraOS monorepo](https://github.com/Mentra-Community/MentraOS)
 under `mobile/modules/crust`. Issues and contributions welcome there.
+
+## Android native HTTP cancellation
+
+Engine's cloud client uses `nativeHttpRequest(CrustModule, method, url, headers,
+body, signal?)` from `@mentra/crust`. The helper preserves Android's native
+background HTTP transport and connects the caller's `AbortSignal` to cancellation
+of that exact OkHttp call. Request IDs and native call ownership stay inside the
+transport. Completion removes its listener and native registry entry; module
+shutdown cancels only that module's outstanding host requests.
+
+Engine callers use the ordinary cloud-client API with a signal. They do not call
+native start/cancel methods or maintain their own request registry.
+
+Android native HTTP failures carry fixed `E_NATIVE_HTTP_*` codes for DNS,
+connection, timeout, TLS, socket, interrupted I/O, generic I/O, or other failures.
+The cloud client records only those allowlisted codes in its existing network
+warning; report submission still rejects with `NETWORK_ERROR`. Exception text,
+URLs, credentials and stacks are not copied into that warning. These categories
+describe a failed request; they do not establish the phone's network routing or
+why its Internet connection was unavailable.

package/android/build.gradle

@@ -82,6 +82,9 @@ android {
 }
 
 dependencies {
+  testImplementation 'junit:junit:4.13.2'
+
+  implementation 'com.facebook.react:react-android'
   // Mapbox Navigation SDK v3 (replaces Google Navigation SDK).
   // Drives headless turn-by-turn nav in NavigationManager.kt: route
   // progress, off-route + automatic rerouting, enhanced (map-matched)
@@ -122,13 +125,10 @@ dependencies {
   // for installing Kotlin lambdas as JS globals via `JS_SetPropertyStr`.
   // Mirrors iOS Apple JSC's `setObject(_, forKeyedSubscript:)` pattern.
   //
-  // Version pin: this Expo SDK 55 build uses Kotlin 2.1.20, which can read
-  // metadata up to 2.2.0. dokar3 1.0.1+ ships classes with metadata 2.3.0
-  // (compiled with Kotlin 2.3.x) and is unreadable here. 1.0.0-alpha13 is
-  // the last release compiled with Kotlin 2.0 (metadata 2.0.0) — its API
-  // (`QuickJs.create`, `evaluate`, `function` extension) matches 1.0.5 1:1.
-  // Bump only when the host Kotlin compiler clears 2.3.0 metadata.
-  implementation 'io.github.dokar3:quickjs-kt-android:1.0.0-alpha13'
+  // 1.0.15 is compiled with Kotlin 2.4.10. The crust config plugin raises the
+  // host to Kotlin 2.3.0, which reads one metadata version ahead. The AAR ships
+  // its own 16 KB-aligned JNI libraries and R8 keep rules.
+  implementation 'io.github.dokar3:quickjs-kt-android:1.0.15'
 
   // OkHttp for fetch / WebSocket — already used elsewhere in MentraOS;
   // pinned here so the gradle plugin doesn't downgrade us.
@@ -141,8 +141,8 @@ dependencies {
 
   // Kotlin coroutines: dokar3's `evaluate()` is suspend; we bridge it via
   // `runBlocking(dispatcher)` from the per-miniapp single-thread executor.
-  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1'
-  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0'
 }
 
 // Notification lifecycle tests run against Android APIs without a device.
@@ -150,3 +150,12 @@ dependencies {
   testImplementation 'junit:junit:4.13.2'
   testImplementation 'org.robolectric:robolectric:4.11.1'
 }
+
+// A desktop JVM cannot load the Android QuickJS library, so local unit tests
+// run the same QuickJS build through its desktop JVM artifact.
+configurations.matching { it.name.endsWith('UnitTestRuntimeClasspath') }.configureEach {
+  resolutionStrategy.dependencySubstitution {
+    substitute(module('io.github.dokar3:quickjs-kt-android'))
+      .using(module('io.github.dokar3:quickjs-kt-jvm:1.0.15'))
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -5,6 +5,13 @@
   <uses-permission android:name="${applicationId}.permission.CRUST_NOTIFICATION_BRIDGE" />
 
   <application>
+
+    <meta-data
+      android:name="com.mentra.bluetoothsdk.RUNTIME_RECOVERY_SERVICE"
+      android:value="com.mentra.crust.services.RuntimeRecoveryService" />
+    <service
+      android:name="com.mentra.crust.services.RuntimeRecoveryService"
+      android:exported="false" />
     <service
       android:name="com.mentra.crust.services.NotificationListenerServiceImpl"
       android:label="@string/mentra_crust_notification_listener_label"

package/android/src/main/java/com/mentra/crust/CrustModule.kt

@@ -6,13 +6,24 @@ import com.mentra.crust.services.NotificationListener
 import com.mentra.crust.services.NotificationProcessBridge
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.functions.Queues
+import expo.modules.kotlin.functions.Coroutine
 import java.net.URL
+import java.util.concurrent.Executors
+import kotlinx.coroutines.CoroutineName
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.asCoroutineDispatcher
+import kotlinx.coroutines.cancel
 
 import com.mentra.crust.navigation.NavigationManager
 import com.mentra.crust.heading.HeadingManager
+import com.mentra.crust.preview.PixelCopyPreview
 import com.mentra.crust.jsc.JSCRuntime
 import com.mentra.crust.jsc.InstalledMiniappManifest
 import com.mentra.crust.jsc.JSCPolyfillBridge
+import com.mentra.crust.http.NativeHttpRequests
+import com.mentra.crust.http.nativeHttpFailureCode
 
 class CrustModule : Module() {
   companion object {
@@ -50,10 +61,6 @@ class CrustModule : Module() {
       NotificationProcessBridge.emitDismissed(context, notificationKey, packageName)
     }
 
-    fun emitCaptionsTesterIncident(data: Map<String, Any>) {
-      emitEvent("captions_tester_incident", data)
-    }
-
     private fun emitEvent(eventName: String, data: Map<String, Any>) {
       val emitter = eventEmitter
       if (emitter == null) {
@@ -76,8 +83,25 @@ class CrustModule : Module() {
   // __dispatch from a per-miniapp QuickJS context (SUBSCRIBE, mic, location,
   // display, send, etc.) would be silently dropped on Android.
   @Volatile private var runtimeInstalled: Boolean = false
+
+  // MentraJS calls get their own serial queue. Expo runs every module's default-queue
+  // AsyncFunction on one shared thread, so a blocking call in another module held every
+  // host→miniapp message behind it: the ACS scoped Wi-Fi join waits on the glasses hotspot for
+  // tens of seconds, the miniapp never saw the host's PING, and the host respawned Mentra Call
+  // mid-join. Serial, so spawn, dispatch and kill still run in the order JS issued them.
+  private val mentraJsExecutor =
+          Executors.newSingleThreadExecutor { r ->
+            Thread(r, "MentraJS-bridge").apply { isDaemon = true }
+          }
+  private val mentraJsQueue =
+          CoroutineScope(
+                  mentraJsExecutor.asCoroutineDispatcher() +
+                          SupervisorJob() +
+                          CoroutineName("MentraJS-bridge"),
+          )
   private var notificationEventReceiver: BroadcastReceiver? = null
   private var notificationBridgeContext: android.content.Context? = null
+  private val nativeHttpRequests = NativeHttpRequests(JSCPolyfillBridge.httpClient)
 
   private fun registerNotificationBridgeIfPossible(): Boolean {
     if (notificationEventReceiver != null) return true
@@ -120,7 +144,6 @@ class CrustModule : Module() {
       "onChange",
       "phone_notification",
       "phone_notification_dismissed",
-      "captions_tester_incident",
       "onNavManeuver",
       "onNavRerouting",
       "onNavArrived",
@@ -149,6 +172,9 @@ class CrustModule : Module() {
       notificationEventReceiver = null
       notificationBridgeContext = null
       eventEmitter = null
+      nativeHttpRequests.cancelAll()
+      mentraJsQueue.cancel()
+      mentraJsExecutor.shutdown()
     }
 
     Function("hello") {
@@ -159,17 +185,41 @@ class CrustModule : Module() {
       sendEvent("onChange", mapOf("value" to value))
     }
 
+    AsyncFunction("captureMiniappPreview") Coroutine { viewTag: Int ->
+      val activity = appContext.currentActivity ?: error("No activity available for screenshot")
+      PixelCopyPreview.capture(activity, viewTag)
+    }
+
     AsyncFunction("nativeHttpRequest") {
-      method: String, url: String, headers: Map<String, String>, body: String? ->
-      val result = JSCPolyfillBridge.executeHttp(method, url, headers, body)
-      mapOf(
-        "status" to result.status,
-        "statusText" to result.statusText,
-        "headers" to result.headers,
-        "body" to result.body,
+      requestId: String, method: String, url: String, headers: Map<String, String>, body: String?, promise: expo.modules.kotlin.Promise ->
+      val request = try {
+        JSCPolyfillBridge.buildHttpRequest(method, url, headers, body)
+      } catch (error: Throwable) {
+        promise.reject("E_NATIVE_HTTP", error.message ?: "Native HTTP request failed", error)
+        return@AsyncFunction
+      }
+      nativeHttpRequests.enqueue(
+        requestId,
+        request,
+        onResult = { result ->
+          promise.resolve(
+            mapOf(
+              "status" to result.status,
+              "statusText" to result.statusText,
+              "headers" to result.headers,
+              "body" to result.body,
+            )
+          )
+        },
+        onError = { error -> promise.reject(nativeHttpFailureCode(error), error.message ?: "Native HTTP request failed", error) },
       )
     }
 
+    // Same serial Expo queue as nativeHttpRequest: cancellation cannot precede registration.
+    AsyncFunction("cancelNativeHttpRequest") { requestId: String ->
+      nativeHttpRequests.cancel(requestId)
+    }
+
     Function("showAVRoutePicker") { _: String? ->
       // iOS-only; Android uses system Bluetooth settings / Crust where appropriate.
     }
@@ -254,7 +304,7 @@ class CrustModule : Module() {
           polyfillBundleOverride = polyfillBundle.takeIf { it.isNotEmpty() },
           miniappJs = miniappJs,
       )
-    }
+    }.runOnQueue(mentraJsQueue)
 
     AsyncFunction("mentraJsEvaluate") { packageName: String, source: String ->
       val ctx =
@@ -262,7 +312,7 @@ class CrustModule : Module() {
                       ?: appContext.currentActivity
                               ?: throw IllegalStateException("MentraJS: no context")
       JSCRuntime.shared(ctx).evaluate(packageName, source)
-    }
+    }.runOnQueue(mentraJsQueue)
 
     AsyncFunction("mentraJsKill") { packageName: String ->
       val ctx =
@@ -270,7 +320,7 @@ class CrustModule : Module() {
                       ?: appContext.currentActivity
                               ?: throw IllegalStateException("MentraJS: no context")
       JSCRuntime.shared(ctx).kill(packageName)
-    }
+    }.runOnQueue(mentraJsQueue)
 
     AsyncFunction("mentraJsDispatchToJs") { packageName: String, envelope: Map<String, Any?> ->
       val ctx =
@@ -278,8 +328,9 @@ class CrustModule : Module() {
                       ?: appContext.currentActivity
                               ?: throw IllegalStateException("MentraJS: no context")
       val json = org.json.JSONObject(envelope as Map<*, *>).toString()
-      JSCRuntime.shared(ctx).dispatchToJs(packageName, json)
-    }
+      val deliveryId = (envelope["deliveryId"] as? Number)?.toLong()?.takeIf { it > 0 }
+      JSCRuntime.shared(ctx).dispatchToJs(packageName, json, deliveryId)
+    }.runOnQueue(mentraJsQueue)
 
     AsyncFunction("mentraJsSetManifest") { packageName: String, permissions: List<String> ->
       val ctx =
@@ -290,7 +341,7 @@ class CrustModule : Module() {
           packageName,
           InstalledMiniappManifest(permissions.toSet()),
       )
-    }
+    }.runOnQueue(mentraJsQueue)
 
     Function("mentraJsAlivePackages") {
       val ctx =
@@ -308,7 +359,7 @@ class CrustModule : Module() {
                       ?: appContext.currentActivity
                               ?: return@AsyncFunction false
       JSCRuntime.shared(ctx).debugForceGC(packageName)
-    }
+    }.runOnQueue(mentraJsQueue)
 
     Function("mentraJsLoadPolyfillBundle") {
       val ctx =
@@ -791,7 +842,7 @@ class CrustModule : Module() {
           sendEvent("onNavArrived", emptyMap<String, Any?>())
         }
         override fun onError(message: String) {
-          sendEvent("onNavError", mapOf("message" to message))
+          sendEvent("onNavError", mapOf("message" to message, "terminal" to true))
         }
         override fun onLocation(payload: NavigationManager.LocationPayload) {
           sendEvent(
@@ -851,7 +902,10 @@ class CrustModule : Module() {
           )
           sendEvent(
             "onNavError",
-            mapOf("message" to "ACCESS_FINE_LOCATION not granted — accept the prompt and tap Start again"),
+            mapOf(
+              "message" to "ACCESS_FINE_LOCATION not granted — accept the prompt and tap Start again",
+              "terminal" to true,
+            ),
           )
           return@runOnUiThread
         }
@@ -922,7 +976,7 @@ class CrustModule : Module() {
         android.util.Log.e("CrustModule", "stopNavigation failed", e)
         mapOf("ok" to false, "error" to (e.message ?: "stop failed"))
       }
-    }
+    }.runOnQueue(Queues.MAIN)
 
     // Dev-only: nudge the simulated position ~offsetMeters off-route to
     // exercise the Nav SDK's onRerouting() pipeline without having to

package/android/src/main/java/com/mentra/crust/http/NativeHttpFailure.kt

@@ -0,0 +1,31 @@
+package com.mentra.crust.http
+
+import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.ConnectException
+import java.net.NoRouteToHostException
+import java.net.SocketException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+
+/** Fixed diagnostic codes only: exception messages can contain private URLs and addresses. */
+internal fun nativeHttpFailureCode(error: Throwable): String {
+    var current: Throwable? = error
+    var fallback = "E_NATIVE_HTTP_OTHER"
+    // Native wrappers can retain the useful cause. Bound traversal even for a cyclic cause chain.
+    repeat(8) {
+        val cause = current ?: return fallback
+        when (cause) {
+            is UnknownHostException -> return "E_NATIVE_HTTP_DNS"
+            is SocketTimeoutException -> return "E_NATIVE_HTTP_TIMEOUT"
+            is SSLException -> return "E_NATIVE_HTTP_TLS"
+            is ConnectException, is NoRouteToHostException -> return "E_NATIVE_HTTP_CONNECT"
+            is SocketException -> return "E_NATIVE_HTTP_SOCKET"
+            is InterruptedIOException -> return "E_NATIVE_HTTP_INTERRUPTED"
+            is IOException -> fallback = "E_NATIVE_HTTP_IO"
+        }
+        current = cause.cause
+    }
+    return fallback
+}

package/android/src/main/java/com/mentra/crust/http/NativeHttpRequests.kt

@@ -0,0 +1,86 @@
+package com.mentra.crust.http
+
+import java.io.IOException
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.Request
+import okhttp3.Response
+
+/** Calls owned by one Expo module, separate from miniapp fetch and WebSocket traffic. */
+internal class NativeHttpRequests(private val client: Call.Factory) {
+    data class Result(
+        val status: Int,
+        val statusText: String,
+        val headers: Map<String, String>,
+        val body: String,
+    )
+
+    private val calls = ConcurrentHashMap<String, Call>()
+    private val closed = AtomicBoolean(false)
+    internal val activeCount: Int get() = calls.size
+
+    fun enqueue(
+        requestId: String,
+        request: Request,
+        onResult: (Result) -> Unit,
+        onError: (Throwable) -> Unit,
+    ) {
+        if (closed.get()) {
+            onError(IllegalStateException("Native HTTP module is closed"))
+            return
+        }
+        val call = client.newCall(request)
+        if (calls.putIfAbsent(requestId, call) != null) {
+            onError(IllegalArgumentException("Native HTTP request ID is already active"))
+            return
+        }
+        // Destruction may run on a different thread from Expo's serial request queue.
+        if (closed.get()) {
+            calls.remove(requestId, call)
+            call.cancel()
+            onError(IllegalStateException("Native HTTP module is closed"))
+            return
+        }
+        try {
+            call.enqueue(object : Callback {
+                override fun onFailure(call: Call, e: IOException) {
+                    calls.remove(requestId, call)
+                    onError(e)
+                }
+
+                override fun onResponse(call: Call, response: Response) {
+                    val result = try {
+                        response.use { r ->
+                            val headers = r.headers.names().associate { name ->
+                                name.lowercase() to r.headers.values(name).joinToString(", ")
+                            }
+                            Result(r.code, r.message, headers, r.body?.string() ?: "")
+                        }
+                    } catch (e: Throwable) {
+                        calls.remove(requestId, call)
+                        onError(e)
+                        return
+                    }
+                    calls.remove(requestId, call)
+                    onResult(result)
+                }
+            })
+        } catch (e: Throwable) {
+            calls.remove(requestId, call)
+            onError(e)
+        }
+    }
+
+    fun cancel(requestId: String) {
+        calls.remove(requestId)?.cancel()
+    }
+
+    fun cancelAll() {
+        closed.set(true)
+        for ((requestId, call) in calls) {
+            if (calls.remove(requestId, call)) call.cancel()
+        }
+    }
+}

package/android/src/main/java/com/mentra/crust/jsc/JSCPolyfillBridge.kt

@@ -37,7 +37,7 @@ import android.util.Base64
 object JSCPolyfillBridge {
     private const val TAG = "MentraJS.PolyfillBridge"
 
-    private val httpClient: OkHttpClient by lazy {
+    internal val httpClient: OkHttpClient by lazy {
         OkHttpClient.Builder()
             .connectTimeout(30, TimeUnit.SECONDS)
             .readTimeout(60, TimeUnit.SECONDS)
@@ -45,15 +45,8 @@ object JSCPolyfillBridge {
             .build()
     }
 
-    data class HttpResult(
-        val status: Int,
-        val statusText: String,
-        val headers: Map<String, String>,
-        val body: String,
-    )
-
-    /** Shared OkHttp execution path for host cloud-client requests. */
-    fun executeHttp(method: String, url: String, headers: Map<String, String>, bodyString: String?): HttpResult {
+    /** Keep host HTTP and miniapp fetch body semantics identical, including empty POSTs. */
+    internal fun buildHttpRequest(method: String, url: String, headers: Map<String, String>, bodyString: String?): Request {
         val builder = Request.Builder().url(url)
         for ((name, value) in headers) builder.header(name, value)
         val contentType = headers.entries
@@ -66,18 +59,7 @@ object JSCPolyfillBridge {
             else -> null
         }
         builder.method(upperMethod, requestBody)
-        httpClient.newCall(builder.build()).execute().use { response ->
-            val responseHeaders = mutableMapOf<String, String>()
-            for (name in response.headers.names()) {
-                responseHeaders[name.lowercase()] = response.headers.values(name).joinToString(", ")
-            }
-            return HttpResult(
-                status = response.code,
-                statusText = response.message,
-                headers = responseHeaders,
-                body = response.body?.string() ?: "",
-            )
-        }
+        return builder.build()
     }
 
     /** Idempotent. Call once on host boot, after the dispatcher is created. */
@@ -220,20 +202,9 @@ object JSCPolyfillBridge {
             }?.toMap() ?: emptyMap()
             val bodyString = req["body"] as? String
 
-            val builder = Request.Builder().url(url)
-            for ((k, v) in headers) builder.header(k, v)
-            // HTTP header names are case-insensitive. The JS fetch caller will
-            // commonly provide `Content-Type`; a direct lowercase map lookup
-            // misses that value and causes OkHttp to emit application/octet-stream.
-            val contentType = headers.entries
-                .firstOrNull { (name, _) -> name.equals("content-type", ignoreCase = true) }
-                ?.value
-            val body = if (bodyString.isNullOrEmpty()) null else bodyString.toRequestBody(
-                (contentType ?: "application/octet-stream").toMediaTypeOrNull()
-            )
-            builder.method(method.uppercase(), body)
+            val request = buildHttpRequest(method, url, headers, bodyString)
 
-            httpClient.newCall(builder.build()).enqueue(object : Callback {
+            httpClient.newCall(request).enqueue(object : Callback {
                 override fun onFailure(call: Call, e: IOException) {
                     deliverError(runtime, packageName, reqId, "fetch: ${e.message}")
                 }

package/android/src/main/java/com/mentra/crust/jsc/JSCRuntime.kt

@@ -1,6 +1,7 @@
 package com.mentra.crust.jsc
 
 import android.content.Context
+import android.os.SystemClock
 import android.util.Log
 import com.dokar.quickjs.QuickJs
 import com.dokar.quickjs.binding.function
@@ -11,6 +12,7 @@ import java.util.concurrent.Executors
 import java.util.concurrent.ScheduledExecutorService
 import java.util.concurrent.ScheduledFuture
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicLong
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
 
@@ -133,6 +135,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
     val dispatcher: JSCDispatcher = JSCDispatcher(appContext)
 
     private val contexts = ConcurrentHashMap<String, ContextRecord>()
+    private val nextContextId = AtomicLong()
     private val polyfillBundle: String by lazy { loadPolyfillBundle() }
 
     // Schedule pool for timers; per-context the executor is the same as the
@@ -146,6 +149,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
         val packageName: String,
         val qjs: QuickJs,
         val executor: ExecutorService,
+        val contextId: Long,
         val pendingTimers: MutableMap<Int, ScheduledFuture<*>> = ConcurrentHashMap(),
         @Volatile var readyAcked: Boolean = false,
         @Volatile var readyNackTimer: ScheduledFuture<*>? = null,
@@ -273,6 +277,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
             packageName = packageName,
             qjs = qjs,
             executor = executor,
+            contextId = nextContextId.incrementAndGet(),
         )
         contexts[packageName] = record
 
@@ -288,10 +293,10 @@ class JSCRuntime private constructor(private val appContext: Context) {
                 runBlocking {
                     installGlobals(qjs, packageName)
                     if (bundle.isNotEmpty()) {
-                        qjs.evaluate<Any?>(bundle, filename = "mentrajs:startup.js")
+                        qjs.evaluateForEffect(bundle, filename = "mentrajs:startup.js")
                     }
                     if (miniappJs.isNotEmpty()) {
-                        qjs.evaluate<Any?>(miniappJs, filename = "mentrajs:miniapp.js")
+                        qjs.evaluateForEffect(miniappJs, filename = "mentrajs:miniapp.js")
                     }
                 }
                 Log.i(TAG, "spawned $packageName")
@@ -415,7 +420,7 @@ class JSCRuntime private constructor(private val appContext: Context) {
                 record.executor.submit {
                     runBlocking {
                         try {
-                            record.qjs.evaluate<Any?>(
+                            record.qjs.evaluateForEffect(
                                 "globalThis.__deliverTimer && globalThis.__deliverTimer($token);",
                                 filename = "mentrajs:timer-$token.js",
                             )
@@ -457,10 +462,23 @@ class JSCRuntime private constructor(private val appContext: Context) {
      * Push a `{kind: "event"|"response", …}` envelope into the named
      * context's globalThis.__deliver. Hops onto the per-context executor.
      */
-    fun dispatchToJs(packageName: String, envelopeJson: String) {
-        val record = contexts[packageName] ?: return
+    fun dispatchToJs(packageName: String, envelopeJson: String, deliveryId: Long? = null) {
+        val record = contexts[packageName]
+        // Only host-generated PINGs carry this ID. Ordinary media/event deliveries stay quiet.
+        val diagnostic = deliveryId?.let {
+            JSDeliveryDiagnostics(it, record?.contextId, SystemClock::elapsedRealtime) { metadata ->
+                reportDeliveryDiagnostic(packageName, metadata)
+            }
+        }
+        diagnostic?.entry()
+        if (record == null) {
+            diagnostic?.dropped("context-missing")
+            return
+        }
+        diagnostic?.queued()
         try {
             record.executor.submit {
+                diagnostic?.started()
                 // Arm only once evaluate is about to run. Queue wait during a
                 // long previous turn (WHIP start, etc.) must not count — that
                 // was firing ready_nack while the context was merely busy.
@@ -489,14 +507,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     kill(packageName)
                 }, WATCHDOG_KILL_MS, TimeUnit.MILLISECONDS)
                 record.watchdogTimer = killTimer
+                var failure: Throwable? = null
                 try {
                     val source = "globalThis.__deliver(${jsStringLiteral(envelopeJson)});"
                     runBlocking {
-                        record.qjs.evaluate<Any?>(source, filename = "mentrajs:deliver.js")
+                        record.qjs.evaluateForEffect(source, filename = "mentrajs:deliver.js")
                     }
                 } catch (e: Throwable) {
+                    failure = e
                     Log.w(TAG, "dispatchToJs threw in $packageName: ${e.message}", e)
+                    if (diagnostic == null) {
+                        reportDeliveryDiagnostic(packageName, mapOf(
+                            "event" to "native-delivery-failed",
+                            "contextId" to record.contextId,
+                            "phase" to "evaluate-failed",
+                            "errorClass" to e.javaClass.simpleName,
+                            "causeClass" to e.cause?.javaClass?.simpleName,
+                        ))
+                    }
                 } finally {
+                    diagnostic?.finished(failure)
                     // Success or throw: the host observed the turn end.
                     record.readyNackTimer?.cancel(false)
                     record.readyNackTimer = null
@@ -505,8 +535,26 @@ class JSCRuntime private constructor(private val appContext: Context) {
                     if (record.watchdogTimer === killTimer) record.watchdogTimer = null
                 }
             }
-        } catch (_: java.util.concurrent.RejectedExecutionException) {
-            // Context killed mid-flight — drop. dispatchToJs is best-effort.
+        } catch (e: java.util.concurrent.RejectedExecutionException) {
+            diagnostic?.dropped("executor-rejected", e)
+            Log.w(TAG, "dispatchToJs rejected for $packageName", e)
+        }
+    }
+
+    private fun reportDeliveryDiagnostic(packageName: String, metadata: Map<String, Any?>) {
+        val line = org.json.JSONObject(metadata as Map<*, *>).toString()
+        Log.i(TAG, line)
+        // Use the existing miniapp log route so console interception includes this in reports.
+        try {
+            deliverOrDrop(OutboundMessage(packageName, mapOf(
+                "packageName" to packageName,
+                "iface" to "__log",
+                "method" to if (metadata["errorClass"] == null) "log" else "warn",
+                "argsJson" to org.json.JSONArray().put(org.json.JSONObject(metadata as Map<*, *>)).toString(),
+            )))
+        } catch (e: Throwable) {
+            // Observability cannot change delivery or hide its original failure.
+            Log.w(TAG, "delivery diagnostic forwarding failed: ${e.javaClass.simpleName}")
         }
     }
 
@@ -542,6 +590,15 @@ class JSCRuntime private constructor(private val appContext: Context) {
 
     // ------------------------------------------------------------------
 
+    /**
+     * Evaluate for side effects. A completion value is never converted to
+     * Kotlin: quickjs-kt 1.0.15 hangs converting a Set, Map or array that
+     * contains itself, and miniapp code chooses its bundle's last value.
+     */
+    private suspend fun QuickJs.evaluateForEffect(source: String, filename: String) {
+        evaluate<Any?>("$source\n;undefined", filename = filename)
+    }
+
     private fun parseArgsEnvelope(argsJson: String): Pair<List<Any?>, String?> {
         return try {
             if (argsJson.startsWith("{")) {