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

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

@@ -88,6 +88,7 @@ object NavigationManager {
 
   private var mapboxNavigation: MapboxNavigation? = null
   private var appContext: Context? = null
+  private val sessionGuard = NavigationSessionGuard()
 
   private var activeCallbacks: Callbacks? = null
   private var lastEmittedKey: String? = null
@@ -153,6 +154,9 @@ object NavigationManager {
    */
   private var skipCrossingsEnabled: Boolean = false
   private var skipCrossingsTimer: java.util.Timer? = null
+  private val simulationHandler = android.os.Handler(android.os.Looper.getMainLooper())
+  @Volatile private var deviationRerouteRunnable: Runnable? = null
+  @Volatile private var deviationReattachRunnable: Runnable? = null
   private val SKIP_CROSSINGS_BASE_M_PER_TICK = 0.56
   private val SKIP_CROSSINGS_TICK_MS = 400L
   private val CROSSING_MAX_LEG_METERS = 25.0
@@ -382,6 +386,12 @@ object NavigationManager {
       return
     }
 
+    // Invalidate every callback owned by the previous session before clearing
+    // its native state. Mapbox can replay cached observer values on registration
+    // and an earlier route request can finish after stop/start.
+    val session = sessionGuard.begin()
+    cleanupSession(nav)
+
     activeCallbacks = callbacks
     activeOptions = options
     simulating = options.simulate
@@ -389,7 +399,7 @@ object NavigationManager {
     offRouteFired = false
     arrivedHandled = false
 
-    attachObservers(nav, callbacks)
+    attachObservers(nav, callbacks, session)
 
     // Origin handling — the crux of a correct trip start.
     //
@@ -407,7 +417,9 @@ object NavigationManager {
     // params until the gate fires; `handleLocation` invokes it on the first
     // location and clears it.
     pendingRouteRequest = { originLat, originLng ->
-      requestAndStartRoute(nav, activity, options, originLat, originLng, callbacks)
+      if (sessionGuard.acceptsCallback(session)) {
+        requestAndStartRoute(nav, activity, options, originLat, originLng, callbacks, session)
+      }
     }
     startTripSession(nav, options)
   }
@@ -424,6 +436,7 @@ object NavigationManager {
     originLat: Double,
     originLng: Double,
     callbacks: Callbacks,
+    session: NavigationSessionGuard.Token,
   ) {
     val coordinates = ArrayList<Point>()
     coordinates.add(Point.fromLngLat(originLng, originLat))
@@ -446,25 +459,34 @@ object NavigationManager {
       routeOptions,
       object : NavigationRouterCallback {
         override fun onRoutesReady(routes: List<NavigationRoute>, routerOrigin: String) {
+          if (!sessionGuard.acceptsCallback(session)) return
           if (routes.isEmpty()) {
+            stop()
             callbacks.onError("no route found")
             return
           }
+          val route = routes.first()
+          if (!sessionGuard.activateInitialRoute(session, route.id)) return
           nav.setNavigationRoutes(routes)
           // In sim mode the ReplayRouteSession observes setNavigationRoutes
           // and starts driving the puck automatically — no manual replay
           // kick needed here.
-          emitRoute(routes.first(), callbacks)
+          emitRoute(route, callbacks)
         }
 
         override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) {
+          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")
         }
       },
     )
@@ -588,7 +610,11 @@ object NavigationManager {
 
   fun stop() {
     Log.d(TAG, "stop")
-    val nav = mapboxNavigation
+    sessionGuard.invalidate()
+    cleanupSession(mapboxNavigation)
+  }
+
+  private fun cleanupSession(nav: MapboxNavigation?) {
     activeCallbacks = null
     lastEmittedKey = null
     simulating = false
@@ -597,6 +623,10 @@ object NavigationManager {
     // Tear down dev walkers first.
     skipCrossingsEnabled = false
     skipCrossingsTimer?.cancel(); skipCrossingsTimer = null
+    deviationRerouteRunnable?.let(simulationHandler::removeCallbacks)
+    deviationRerouteRunnable = null
+    deviationReattachRunnable?.let(simulationHandler::removeCallbacks)
+    deviationReattachRunnable = null
     wrongSidewalkOffsetEnabled = false
 
     if (nav != null) {
@@ -637,7 +667,11 @@ object NavigationManager {
   // Observers — translate Mapbox events into the existing Callbacks shape.
   // =====================================================================
 
-  private fun attachObservers(nav: MapboxNavigation, callbacks: Callbacks) {
+  private fun attachObservers(
+    nav: MapboxNavigation,
+    callbacks: Callbacks,
+    session: NavigationSessionGuard.Token,
+  ) {
     // REROUTING IS FULLY OWNED BY MAPBOX. Auto-reroute is ON by default in
     // v3 — when the user diverges, the SDK detects off-route AND fetches a
     // new route on its own. We do NOT hand-roll perpendicular-distance
@@ -653,6 +687,7 @@ object NavigationManager {
     // clear our off-route flag and (for the host) reads as a fresh route.
     val routesObs = RoutesObserver { result: RoutesUpdatedResult ->
       val route = result.navigationRoutes.firstOrNull() ?: return@RoutesObserver
+      if (!sessionGuard.acceptRouteUpdate(session, route.id)) return@RoutesObserver
       val reason = result.reason
       // Ignore refresh (same geometry, just live traffic) — it would
       // needlessly re-emit the whole polyline + rebuild pivots.
@@ -669,6 +704,7 @@ object NavigationManager {
     // RouteProgressObserver — every location tick. Carries current step,
     // upcoming maneuver, distance-to-maneuver, and trip totals.
     val progressObs = RouteProgressObserver { progress: RouteProgress ->
+      if (!sessionGuard.acceptsProgress(session, progress.navigationRoute.id)) return@RouteProgressObserver
       handleRouteProgress(progress, callbacks)
     }
     routeProgressObserver = progressObs
@@ -679,17 +715,22 @@ object NavigationManager {
     val locObs = object : LocationObserver {
       override fun onNewRawLocation(rawLocation: Location) { /* prefer matched */ }
       override fun onNewLocationMatcherResult(result: LocationMatcherResult) {
+        if (!sessionGuard.acceptsLocation(session)) return
         handleLocation(result, callbacks)
       }
     }
     locationObserver = locObs
     nav.registerLocationObserver(locObs)
+    // Mapbox synchronously replays its cached matcher result from register().
+    // Only locations delivered after registration belong to this fresh trip.
+    sessionGuard.enableLocationCallbacks(session)
 
     // OffRouteObserver — Mapbox's automatic off-route edge signal. PURELY
     // OBSERVATIONAL: registering it does NOT disable auto-reroute. We
     // surface onOffRoute for the UI's "off route" banner; the SDK handles
     // the actual reroute and the new route arrives via RoutesObserver.
     val offRouteObs = OffRouteObserver { offRoute: Boolean ->
+      if (!sessionGuard.acceptsCallback(session)) return@OffRouteObserver
       if (offRoute && !offRouteFired) {
         offRouteFired = true
         // Distance from the route is best-effort context for the banner;
@@ -707,6 +748,7 @@ object NavigationManager {
     // route then lands via RoutesObserver(REROUTE). Available only while
     // auto-reroute is enabled (getRerouteController() is null otherwise).
     val rerouteObs = RerouteController.RerouteStateObserver { state: RerouteState ->
+      if (!sessionGuard.acceptsCallback(session)) return@RerouteStateObserver
       when (state) {
         is RerouteState.FetchingRoute -> {
           Log.d(TAG, "reroute state: FetchingRoute → onRerouting")
@@ -1054,6 +1096,10 @@ object NavigationManager {
    */
   @OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
   fun simulateDeviation(offsetMeters: Double = 0.0) {
+    val session = sessionGuard.captureActive() ?: run {
+      Log.w(TAG, "simulateDeviation: no active navigation session")
+      return
+    }
     val replayer = replayer ?: run {
       Log.w(TAG, "simulateDeviation: not in simulate mode — nothing to push off-route")
       return
@@ -1138,8 +1184,11 @@ object NavigationManager {
       // onRoute exactly like an automatic reroute. Fire it slightly after
       // the off-route events start playing so the controller reroutes from
       // the diverged position, not the on-route one.
-      val mainHandler = android.os.Handler(android.os.Looper.getMainLooper())
-      mainHandler.postDelayed({
+      deviationRerouteRunnable?.let(simulationHandler::removeCallbacks)
+      lateinit var rerouteRunnable: Runnable
+      rerouteRunnable = Runnable {
+        if (deviationRerouteRunnable === rerouteRunnable) deviationRerouteRunnable = null
+        if (!sessionGuard.acceptsCallback(session)) return@Runnable
         try {
           val controller = mapboxNavigation?.getRerouteController()
           if (controller != null) {
@@ -1148,6 +1197,7 @@ object NavigationManager {
             Log.d(TAG, "simulateDeviation: requesting reroute() directly")
             controller.reroute(
               RerouteController.RoutesCallback { routes: List<NavigationRoute>, _: String ->
+                if (!sessionGuard.acceptsCallback(session)) return@RoutesCallback
                 // RoutesObserver(REROUTE) will also fire and emit the route;
                 // we don't setNavigationRoutes here (the controller does).
                 Log.d(TAG, "simulateDeviation: reroute() returned ${routes.size} route(s)")
@@ -1159,20 +1209,28 @@ object NavigationManager {
         } catch (e: Throwable) {
           Log.e(TAG, "simulateDeviation reroute() failed", e)
         }
-      }, 1500L)
+      }
+      deviationRerouteRunnable = rerouteRunnable
+      simulationHandler.postDelayed(rerouteRunnable, 1500L)
 
       // Re-attach the session so it resumes driving the puck once a route is
       // active again (locationResetEnabled snaps it onto the new route).
       // Delay until AFTER the off-route events + reroute fetch.
       val playSeconds = (ts / simulationSpeed.coerceAtLeast(0.1f)).toDouble()
       val reattachMs = ((playSeconds + 4.0) * 1000.0).toLong().coerceIn(5000L, 20000L)
-      mainHandler.postDelayed({
+      deviationReattachRunnable?.let(simulationHandler::removeCallbacks)
+      lateinit var reattachRunnable: Runnable
+      reattachRunnable = Runnable {
+        if (deviationReattachRunnable === reattachRunnable) deviationReattachRunnable = null
+        if (!sessionGuard.acceptsCallback(session)) return@Runnable
         try {
           if (simulating) replaySession?.onAttached(nav)
         } catch (e: Throwable) {
           Log.w(TAG, "simulateDeviation: re-attach session failed: ${e.message}")
         }
-      }, reattachMs)
+      }
+      deviationReattachRunnable = reattachRunnable
+      simulationHandler.postDelayed(reattachRunnable, reattachMs)
     } catch (e: Throwable) {
       Log.e(TAG, "simulateDeviation push failed", e)
     }
@@ -1199,6 +1257,10 @@ object NavigationManager {
   }
 
   private fun startSkipCrossingsWalker() {
+    val session = sessionGuard.captureActive() ?: run {
+      Log.w(TAG, "startSkipCrossingsWalker: no active navigation session")
+      return
+    }
     val flat = activePolyline
     if (flat == null || flat.size < 2) { Log.w(TAG, "startSkipCrossingsWalker: no route polyline"); return }
     try { replayer?.stop() } catch (_: Throwable) {}
@@ -1215,6 +1277,8 @@ object NavigationManager {
     timer.scheduleAtFixedRate(object : java.util.TimerTask() {
       override fun run() {
         mainHandler.post {
+          if (!sessionGuard.acceptsCallback(session)) return@post
+          if (skipCrossingsTimer !== timer) return@post
           try {
             if (!skipCrossingsEnabled) { cancel(); return@post }
             cursor = advanceCursor(modified, cursor, stepMeters)

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

@@ -0,0 +1,74 @@
+package com.mentra.crust.navigation
+
+/**
+ * Separates callbacks from successive uses of the process-wide MapboxNavigation instance.
+ * Mapbox observers replay cached values when registered, and route requests can complete
+ * after stop(), so callers must pass this guard before touching shared navigation state.
+ */
+internal class NavigationSessionGuard {
+  @JvmInline
+  value class Token internal constructor(internal val value: Long)
+
+  private var generation = 0L
+  private var activeSession = false
+  private var activeRouteId: String? = null
+  private var locationCallbacksEnabled = false
+
+  @Synchronized
+  fun begin(): Token {
+    generation += 1
+    activeSession = true
+    activeRouteId = null
+    locationCallbacksEnabled = false
+    return Token(generation)
+  }
+
+  @Synchronized
+  fun invalidate() {
+    generation += 1
+    activeSession = false
+    activeRouteId = null
+    locationCallbacksEnabled = false
+  }
+
+  @Synchronized
+  fun acceptsCallback(token: Token): Boolean = token.value == generation
+
+  /** Snapshot the active session for work that will execute asynchronously. */
+  @Synchronized
+  fun captureActive(): Token? = if (activeSession) Token(generation) else null
+
+  /** Enable locations only after observer registration has replayed its cached values. */
+  @Synchronized
+  fun enableLocationCallbacks(token: Token) {
+    if (token.value == generation) locationCallbacksEnabled = true
+  }
+
+  @Synchronized
+  fun acceptsLocation(token: Token): Boolean =
+    token.value == generation && locationCallbacksEnabled
+
+  /** Accept the guarded initial request and establish the route progress may belong to. */
+  @Synchronized
+  fun activateInitialRoute(token: Token, routeId: String): Boolean {
+    if (token.value != generation) return false
+    activeRouteId = routeId
+    return true
+  }
+
+  /**
+   * Accept a route observer update only after this session established its initial route.
+   * A different route id is valid here: Mapbox uses the observer for automatic reroutes.
+   */
+  @Synchronized
+  fun acceptRouteUpdate(token: Token, routeId: String): Boolean {
+    if (token.value != generation || activeRouteId == null) return false
+    activeRouteId = routeId
+    return true
+  }
+
+  /** Reject cached or queued progress from another route, including after a reroute. */
+  @Synchronized
+  fun acceptsProgress(token: Token, routeId: String): Boolean =
+    token.value == generation && routeId == activeRouteId
+}

package/android/src/main/java/com/mentra/crust/preview/PixelCopyPreview.kt

@@ -0,0 +1,76 @@
+package com.mentra.crust.preview
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Rect
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import android.view.PixelCopy
+import android.view.View
+import java.io.File
+import kotlin.coroutines.resumeWithException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withContext
+
+/** Copies the displayed miniapp pixels without invoking WebView's software renderer. */
+object PixelCopyPreview {
+  @OptIn(ExperimentalCoroutinesApi::class)
+  suspend fun capture(activity: Activity, viewTag: Int): String =
+    withContext(Dispatchers.Main.immediate) {
+      check(!activity.isFinishing && !activity.isDestroyed) { "Screenshot activity is unavailable" }
+      val window = activity.window
+      val decor = window.decorView
+      val view = decor.findViewById<View>(viewTag)
+        ?: error("Screenshot view $viewTag is unavailable")
+      check(view.isAttachedToWindow && view.isLaidOut && view.width > 0 && view.height > 0) {
+        "Screenshot view is not ready"
+      }
+
+      val location = IntArray(2)
+      view.getLocationInWindow(location)
+      val bounds = Rect(location[0], location[1], location[0] + view.width, location[1] + view.height)
+      check(Rect(0, 0, decor.width, decor.height).contains(bounds)) {
+        "Screenshot view must be fully inside the window"
+      }
+
+      val bitmap = Bitmap.createBitmap(bounds.width(), bounds.height(), Bitmap.Config.ARGB_8888)
+      val captured = suspendCancellableCoroutine<Bitmap> { continuation ->
+        try {
+          PixelCopy.request(window, bounds, bitmap, { result ->
+            if (result == PixelCopy.SUCCESS) {
+              // A cancelled request still owns its bitmap until PixelCopy finishes.
+              continuation.resume(bitmap) { bitmap.recycle() }
+            } else {
+              bitmap.recycle()
+              continuation.resumeWithException(IllegalStateException("PixelCopy failed: $result"))
+            }
+          }, Handler(Looper.getMainLooper()))
+        } catch (error: Exception) {
+          bitmap.recycle()
+          continuation.resumeWithException(error)
+        }
+      }
+
+      try {
+        withContext(Dispatchers.IO) {
+          val file = File.createTempFile("miniapp-preview-", ".jpg", activity.cacheDir)
+          try {
+            file.outputStream().use { output ->
+              check(captured.compress(Bitmap.CompressFormat.JPEG, 50, output)) {
+                "Unable to encode miniapp screenshot"
+              }
+            }
+            Uri.fromFile(file).toString()
+          } catch (error: Exception) {
+            file.delete()
+            throw error
+          }
+        }
+      } finally {
+        captured.recycle()
+      }
+    }
+}

package/android/src/main/java/com/mentra/crust/services/RuntimeRecoveryService.kt

@@ -0,0 +1,12 @@
+package com.mentra.crust.services
+
+import android.content.Intent
+import com.facebook.react.HeadlessJsTaskService
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+
+/** Boots the normal app runtime while the Bluetooth foreground service keeps it alive. */
+class RuntimeRecoveryService : HeadlessJsTaskService() {
+    override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig =
+        HeadlessJsTaskConfig("MentraRuntimeRecovery", Arguments.createMap(), 120_000L, true)
+}

package/android/src/test/java/com/mentra/crust/http/NativeHttpFailureTest.kt

@@ -0,0 +1,44 @@
+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.SSLHandshakeException
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class NativeHttpFailureTest {
+    @Test fun `preserves failure category without exception text`() {
+        val privateMessage = "https://private.example?token=secret SSID private-address"
+        val cases = listOf(
+            UnknownHostException(privateMessage) to "E_NATIVE_HTTP_DNS",
+            ConnectException(privateMessage) to "E_NATIVE_HTTP_CONNECT",
+            NoRouteToHostException(privateMessage) to "E_NATIVE_HTTP_CONNECT",
+            SocketTimeoutException(privateMessage) to "E_NATIVE_HTTP_TIMEOUT",
+            SSLHandshakeException(privateMessage) to "E_NATIVE_HTTP_TLS",
+            SocketException(privateMessage) to "E_NATIVE_HTTP_SOCKET",
+            InterruptedIOException(privateMessage) to "E_NATIVE_HTTP_INTERRUPTED",
+            IOException(privateMessage) to "E_NATIVE_HTTP_IO",
+            IllegalStateException(privateMessage) to "E_NATIVE_HTTP_OTHER",
+        )
+        cases.forEach { (error, expected) -> assertEquals(expected, nativeHttpFailureCode(error)) }
+    }
+
+    @Test fun `retains a specific cause inside a generic native wrapper`() {
+        val wrapped = IOException("private wrapper", UnknownHostException("private hostname"))
+        assertEquals("E_NATIVE_HTTP_DNS", nativeHttpFailureCode(wrapped))
+        assertEquals("E_NATIVE_HTTP_IO", nativeHttpFailureCode(IllegalStateException(IOException("private"))))
+    }
+
+    @Test fun `never parses a category from private error text and bounds cyclic causes`() {
+        assertEquals("E_NATIVE_HTTP_OTHER", nativeHttpFailureCode(Exception("E_NATIVE_HTTP_DNS")))
+        val first = Exception("private one")
+        val second = Exception("private two", first)
+        first.initCause(second)
+        assertEquals("E_NATIVE_HTTP_OTHER", nativeHttpFailureCode(first))
+    }
+}