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

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,12 +141,30 @@ 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.
 dependencies {
   testImplementation 'junit:junit:4.13.2'
   testImplementation 'org.robolectric:robolectric:4.11.1'
+  // Local HTTP server for the miniapp fetch bridge tests; matches okhttp above.
+  testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'
+}
+
+// Robolectric loads classes, and so QuickJS's JNI library, in its own sandbox
+// class loader. Plain JUnit QuickJS tests in the same JVM then crash inside
+// JNI, so every test class runs in a fresh JVM.
+tasks.withType(Test).configureEach {
+  forkEvery = 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

@@ -2,6 +2,8 @@ package com.mentra.crust.jsc
 
 import android.util.Log
 import java.io.IOException
+import java.nio.ByteBuffer
+import java.nio.charset.CharacterCodingException
 import okhttp3.MediaType.Companion.toMediaTypeOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
@@ -12,6 +14,7 @@ import okhttp3.Callback
 import okhttp3.WebSocket
 import okhttp3.WebSocketListener
 import okio.ByteString
+import okio.ByteString.Companion.decodeBase64
 import okio.ByteString.Companion.toByteString
 import org.json.JSONObject
 import org.json.JSONArray
@@ -37,7 +40,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,41 +48,74 @@ 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?,
+        bodyBytes: ByteString? = null,
+    ): Request {
         val builder = Request.Builder().url(url)
         for ((name, value) in headers) builder.header(name, value)
         val contentType = headers.entries
             .firstOrNull { (name, _) -> name.equals("content-type", ignoreCase = true) }
             ?.value
+        val mediaType = (contentType ?: "application/octet-stream").toMediaTypeOrNull()
         val upperMethod = method.uppercase()
         val requestBody = when {
-            bodyString != null -> bodyString.toRequestBody((contentType ?: "application/octet-stream").toMediaTypeOrNull())
+            bodyBytes != null -> bodyBytes.toRequestBody(mediaType)
+            bodyString != null -> bodyString.toRequestBody(mediaType)
             upperMethod == "POST" || upperMethod == "PUT" || upperMethod == "PATCH" -> "".toRequestBody(null)
             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 builder.build()
+    }
+
+    /**
+     * The `result` of a `fetch.request` response envelope. The body is sent
+     * as the string `body` only when its bytes are exactly that string's
+     * UTF-8 encoding, and as `bodyBase64` otherwise, so binary bodies keep
+     * every byte. The JS polyfill decodes base64 bodies and applies UTF-8 rules.
+     */
+    internal fun fetchResult(response: Response): JSONObject {
+        val headerMap = mutableMapOf<String, String>()
+        for (name in response.headers.names()) {
+            headerMap[name.lowercase()] = response.headers.values(name).joinToString(", ")
+        }
+        val body = try {
+            response.body?.bytes() ?: ByteArray(0)
+        } catch (e: Throwable) {
+            Log.w(TAG, "fetch read body threw: ${e.message}")
+            ByteArray(0)
+        }
+        val text = exactUtf8(body)
+        return JSONObject().apply {
+            put("status", response.code)
+            put("statusText", response.message)
+            put("headers", JSONObject(headerMap as Map<*, *>))
+            if (text != null) {
+                put("body", text)
+            } else {
+                put("bodyBase64", body.toByteString().base64())
             }
-            return HttpResult(
-                status = response.code,
-                statusText = response.message,
-                headers = responseHeaders,
-                body = response.body?.string() ?: "",
-            )
+            put("ok", response.code in 200..299)
         }
     }
 
+    /** [bytes] as a String when they are exactly its UTF-8 encoding, else null. */
+    private fun exactUtf8(bytes: ByteArray): String? {
+        // A new decoder reports malformed input, so binary fails at its first invalid byte.
+        val text = try {
+            Charsets.UTF_8.newDecoder().decode(ByteBuffer.wrap(bytes)).toString()
+        } catch (_: CharacterCodingException) {
+            return null
+        }
+        // Re-encoding proves the round trip even if a decoder lets an unpaired surrogate through.
+        return text.takeIf { it.toByteArray(Charsets.UTF_8).contentEquals(bytes) }
+    }
+
     /** Idempotent. Call once on host boot, after the dispatcher is created. */
     fun install(runtime: JSCRuntime) {
         installFetch(runtime)
@@ -219,53 +255,27 @@ object JSCPolyfillBridge {
                 ks to vs
             }?.toMap() ?: emptyMap()
             val bodyString = req["body"] as? String
+            val bodyBytes = (req["bodyBase64"] as? String)?.let { encoded ->
+                encoded.decodeBase64()
+                    ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request: bodyBase64 is not base64")
+            }
 
-            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, bodyBytes)
 
-            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}")
                 }
 
                 override fun onResponse(call: Call, response: Response) {
-                    response.use { r ->
-                        val status = r.code
-                        val statusText = r.message
-                        val headerMap = mutableMapOf<String, String>()
-                        for (name in r.headers.names()) {
-                            headerMap[name.lowercase()] = r.headers.values(name).joinToString(", ")
-                        }
-                        val bodyStr = try {
-                            r.body?.string() ?: ""
-                        } catch (e: Throwable) {
-                            Log.w(TAG, "fetch read body threw: ${e.message}")
-                            ""
-                        }
-                        val envelope = JSONObject().apply {
-                            put("kind", "response")
-                            put("reqId", reqId)
-                            put("ok", true)
-                            put("result", JSONObject().apply {
-                                put("status", status)
-                                put("statusText", statusText)
-                                put("headers", JSONObject(headerMap as Map<*, *>))
-                                put("body", bodyStr)
-                                put("ok", status in 200..299)
-                            })
-                        }
-                        runtime.dispatchToJs(packageName, envelope.toString())
+                    val result = response.use { fetchResult(it) }
+                    val envelope = JSONObject().apply {
+                        put("kind", "response")
+                        put("reqId", reqId)
+                        put("ok", true)
+                        put("result", result)
                     }
+                    runtime.dispatchToJs(packageName, envelope.toString())
                 }
             })
             JSCDispatchOutcome.Async