@mentra/crust 3.2.1 → 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

@@ -125,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.
@@ -144,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.
@@ -153,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,7 @@
   <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" />

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

@@ -7,6 +7,7 @@ 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
@@ -17,9 +18,12 @@ 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 {
@@ -57,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) {
@@ -101,6 +101,7 @@ class CrustModule : Module() {
           )
   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
@@ -143,7 +144,6 @@ class CrustModule : Module() {
       "onChange",
       "phone_notification",
       "phone_notification_dismissed",
-      "captions_tester_incident",
       "onNavManeuver",
       "onNavRerouting",
       "onNavArrived",
@@ -172,6 +172,7 @@ class CrustModule : Module() {
       notificationEventReceiver = null
       notificationBridgeContext = null
       eventEmitter = null
+      nativeHttpRequests.cancelAll()
       mentraJsQueue.cancel()
       mentraJsExecutor.shutdown()
     }
@@ -184,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.
     }
@@ -303,7 +328,8 @@ 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> ->
@@ -816,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(
@@ -876,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
         }

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,30 +45,6 @@ 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 {
-        val request = buildHttpRequest(method, url, headers, bodyString)
-        httpClient.newCall(request).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() ?: "",
-            )
-        }
-    }
-
     /** 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)

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("{")) {

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

@@ -0,0 +1,44 @@
+package com.mentra.crust.jsc
+
+/** Metadata for one host PING. Never retains the envelope or exception message. */
+internal class JSDeliveryDiagnostics(
+    private val deliveryId: Long,
+    private val contextId: Long?,
+    private val clockMs: () -> Long,
+    private val emit: (Map<String, Any?>) -> Unit,
+) {
+    private val enteredAtMs = clockMs()
+    private var queuedAtMs: Long? = null
+    private var startedAtMs: Long? = null
+
+    fun entry() = report("native-entry")
+
+    fun queued() {
+        queuedAtMs = clockMs()
+        report("queued")
+    }
+
+    fun started() {
+        startedAtMs = clockMs()
+        report("started")
+    }
+
+    fun finished(error: Throwable? = null) = report(if (error == null) "finished" else "evaluate-failed", error)
+
+    fun dropped(reason: String, error: Throwable? = null) = report(reason, error)
+
+    private fun report(phase: String, error: Throwable? = null) {
+        val now = clockMs()
+        emit(mapOf(
+            "event" to "native-ping-delivery",
+            "deliveryId" to deliveryId,
+            "contextId" to contextId,
+            "phase" to phase,
+            "elapsedMs" to now - enteredAtMs,
+            "queueWaitMs" to queuedAtMs?.let { (startedAtMs ?: now) - it },
+            "evaluateMs" to startedAtMs?.let { now - it },
+            "errorClass" to error?.javaClass?.simpleName,
+            "causeClass" to error?.cause?.javaClass?.simpleName,
+        ))
+    }
+}

package/android/src/main/java/com/mentra/crust/navigation/NavigationManager.kt

@@ -461,6 +461,7 @@ object NavigationManager {
         override fun onRoutesReady(routes: List<NavigationRoute>, routerOrigin: String) {
           if (!sessionGuard.acceptsCallback(session)) return
           if (routes.isEmpty()) {
+            stop()
             callbacks.onError("no route found")
             return
           }
@@ -477,12 +478,15 @@ object NavigationManager {
           if (!sessionGuard.acceptsCallback(session)) return
           val msg = reasons.firstOrNull()?.message ?: "route request failed"
           Log.e(TAG, "requestRoutes failed: $msg")
+          stop()
           callbacks.onError(msg)
         }
 
         override fun onCanceled(routeOptions: RouteOptions, routerOrigin: String) {
           if (!sessionGuard.acceptsCallback(session)) return
           Log.w(TAG, "route request canceled")
+          stop()
+          callbacks.onError("route request canceled")
         }
       },
     )