@mentra/crust 0.1.0-beta.0

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

@@ -0,0 +1,30 @@
+package com.mentra.crust
+
+import android.content.Context
+import android.webkit.WebView
+import android.webkit.WebViewClient
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.viewevent.EventDispatcher
+import expo.modules.kotlin.views.ExpoView
+
+class CrustView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  // Creates and initializes an event dispatcher for the `onLoad` event.
+  // The name of the event is inferred from the value and needs to match the event name defined in the module.
+  private val onLoad by EventDispatcher()
+
+  // Defines a WebView that will be used as the root subview.
+  internal val webView = WebView(context).apply {
+    layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
+    webViewClient = object : WebViewClient() {
+      override fun onPageFinished(view: WebView, url: String) {
+        // Sends an event to JavaScript. Triggers a callback defined on the view component in JavaScript.
+        onLoad(mapOf("url" to url))
+      }
+    }
+  }
+
+  init {
+    // Adds the WebView to the view hierarchy.
+    addView(webView)
+  }
+}

package/android/src/main/java/com/mentra/crust/heading/HeadingManager.kt

@@ -0,0 +1,150 @@
+package com.mentra.crust.heading
+
+import android.content.Context
+import android.hardware.Sensor
+import android.hardware.SensorEvent
+import android.hardware.SensorEventListener
+import android.hardware.SensorManager
+import android.util.Log
+import kotlin.math.abs
+import kotlin.math.atan2
+
+/**
+ * HeadingManager
+ *
+ * Reads the OS's fused rotation vector (magnetometer + accelerometer +
+ * gyro) and produces a tilt-robust compass heading in degrees (0 = north,
+ * clockwise). Behaves like Google Maps' compass: stable across the full
+ * range of phone hold angles, including when the user raises the phone
+ * toward their face.
+ *
+ * Independent of nav — works whenever an Android Activity is around.
+ *
+ * --- Why projection instead of getOrientation + remapCoordinateSystem ---
+ * The previous implementation called `remapCoordinateSystem(AXIS_X, AXIS_Z)`
+ * and read azimuth via `getOrientation`. That assumes the phone is held
+ * near-vertical. As the phone tilts toward horizontal — or up toward the
+ * user — the assumed device→world axis mapping breaks down and azimuth
+ * drifts or jumps.
+ *
+ * Instead we directly project the device's "top edge" (+Y in device
+ * coords) into the world horizontal plane and read the bearing of that
+ * projection. The full 3D rotation matrix R from
+ * `getRotationMatrixFromVector` carries the device→world transform with
+ * world axes (X = east, Y = north, Z = up). The image of device +Y
+ * under R is the second column of R; its (east, north) components are
+ * R[0][1] and R[1][1] (row-major indices 1 and 4). We discard the up
+ * component — that's exactly the tilt we want to ignore — and take
+ * `atan2(east, north)` for the heading.
+ *
+ * --- Smoothing ---
+ * Low-pass on the rotation MATRIX (not the angle) so we never average
+ * across the 0°↔360° wrap. Alpha 0.88 ≈ 0.4 s tau at SENSOR_DELAY_UI,
+ * matching the perceived smoothness of Google Maps' compass without
+ * adding noticeable lag.
+ */
+object HeadingManager {
+  private const val TAG = "HeadingManager"
+
+  /** Minimum delta (degrees) before re-emitting. Avoids flooding JS. */
+  private const val MIN_DEGREE_DELTA = 1.0f
+
+  /**
+   * Low-pass coefficient applied per-sample to each entry of the 3×3
+   * rotation matrix. Higher = smoother but laggier. 0.88 at
+   * SENSOR_DELAY_UI (~16 Hz) gives ~0.4 s tau.
+   */
+  private const val ALPHA = 0.88f
+
+  private var sensorManager: SensorManager? = null
+  private var rotationVectorSensor: Sensor? = null
+  private var listener: SensorEventListener? = null
+  private var lastEmitted: Float = -1000f
+
+  interface Callback {
+    fun onHeading(degrees: Float)
+  }
+
+  fun start(context: Context, cb: Callback) {
+    if (listener != null) {
+      Log.d(TAG, "already started")
+      return
+    }
+    val sm = context.applicationContext.getSystemService(Context.SENSOR_SERVICE) as? SensorManager
+    if (sm == null) {
+      Log.w(TAG, "SensorManager unavailable")
+      return
+    }
+    val sensor = sm.getDefaultSensor(Sensor.TYPE_ROTATION_VECTOR)
+    if (sensor == null) {
+      Log.w(TAG, "TYPE_ROTATION_VECTOR sensor unavailable")
+      return
+    }
+
+    val raw = FloatArray(9)
+    val filtered = FloatArray(9)
+    var seeded = false
+
+    val sl = object : SensorEventListener {
+      override fun onSensorChanged(event: SensorEvent) {
+        SensorManager.getRotationMatrixFromVector(raw, event.values)
+
+        if (!seeded) {
+          // Seed the filter from the first sample so we don't slow-pan
+          // from the identity matrix toward the real orientation over
+          // the first ~30 samples after start().
+          System.arraycopy(raw, 0, filtered, 0, 9)
+          seeded = true
+        } else {
+          for (i in 0 until 9) {
+            filtered[i] = ALPHA * filtered[i] + (1f - ALPHA) * raw[i]
+          }
+        }
+
+        // R is row-major device→world. The image of device +Y
+        // (the top edge of the phone in portrait) under R is the
+        // second column, whose east / north components live at
+        // indices 1 and 4. The up component (index 7) is exactly
+        // the tilt we want to ignore — discard it.
+        val east = filtered[1]
+        val north = filtered[4]
+        val deg = ((Math.toDegrees(atan2(east, north).toDouble()).toFloat()) + 360f) % 360f
+        if (!deg.isFinite()) return
+
+        if (lastEmitted < -360f || abs(angleDiff(deg, lastEmitted)) >= MIN_DEGREE_DELTA) {
+          lastEmitted = deg
+          cb.onHeading(deg)
+        }
+      }
+
+      override fun onAccuracyChanged(s: Sensor?, a: Int) {}
+    }
+
+    sm.registerListener(sl, sensor, SensorManager.SENSOR_DELAY_UI)
+    sensorManager = sm
+    rotationVectorSensor = sensor
+    listener = sl
+    Log.d(TAG, "started")
+  }
+
+  fun stop() {
+    val sm = sensorManager
+    val sl = listener
+    if (sm != null && sl != null) {
+      sm.unregisterListener(sl)
+      Log.d(TAG, "stopped")
+    }
+    sensorManager = null
+    rotationVectorSensor = null
+    listener = null
+    lastEmitted = -1000f
+  }
+
+  /** Smallest signed difference between two compass headings. */
+  private fun angleDiff(a: Float, b: Float): Float {
+    var d = (a - b) % 360f
+    if (d > 180f) d -= 360f
+    if (d < -180f) d += 360f
+    return d
+  }
+}

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

@@ -0,0 +1,189 @@
+package com.mentra.crust.jsc
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.util.Log
+import java.security.SecureRandom
+import org.json.JSONArray
+
+/**
+ * MentraJS dispatch table + permission gate for the per-miniapp
+ * `__dispatch(iface, method, args)` bridge. Symmetric with iOS
+ * [JSCDispatcher.swift].
+ *
+ * Built-in local routes (handled inline, no RN round-trip):
+ *  - `__runtime.ready`              — polyfill signals install complete
+ *  - `localStorage.{get,set,remove,clear,key,length}` — SharedPreferences
+ *  - `crypto.getRandomBytes`        — SecureRandom
+ *
+ * Everything else returns [JSCDispatchOutcome.ForwardToRn]; the RN-side
+ * [MentraJSRouter] is the actual handler.
+ */
+sealed class JSCDispatchOutcome {
+    /** Local sync handler returns a JSON string (or null for void). */
+    data class Sync(val json: String?) : JSCDispatchOutcome()
+    /** Handler accepted; response will arrive later via dispatchToJs. */
+    object Async : JSCDispatchOutcome()
+    /** Refused. JS sees a thrown Error with `code` + `message`. */
+    data class Error(val code: String, val message: String?) : JSCDispatchOutcome()
+    /** Forward to RN via the `mentrajs_message` Expo event. */
+    data class ForwardToRn(val payload: Map<String, Any?>) : JSCDispatchOutcome()
+}
+
+data class InstalledMiniappManifest(val permissions: Set<String>)
+
+class JSCDispatcher(private val appContext: Context) {
+    companion object {
+        private const val TAG = "MentraJS.Dispatcher"
+    }
+
+    private val routes = mutableMapOf<String, Handler>()
+    private val manifests = mutableMapOf<String, InstalledMiniappManifest>()
+    private val implicitGrants = setOf("STORAGE", "DISPLAY", "BUTTONS")
+    private val random = SecureRandom()
+
+    var permissionRequirements: Map<String, String> = mapOf(
+        "mic" to "MICROPHONE",
+        "transcription" to "MICROPHONE",
+        "translation" to "MICROPHONE",
+        "camera" to "CAMERA",
+        "location" to "LOCATION",
+        "navigation" to "LOCATION",
+        "heading" to "LOCATION",
+        "calendar" to "CALENDAR",
+    )
+
+    /** Handler runs on the JSContext's queue. */
+    fun interface Handler {
+        fun handle(packageName: String, args: List<Any?>, reqId: String?): JSCDispatchOutcome
+    }
+
+    init {
+        installBuiltinRoutes()
+    }
+
+    fun register(iface: String, method: String, handler: Handler) {
+        synchronized(routes) {
+            routes["$iface.$method"] = handler
+        }
+    }
+
+    fun unregister(iface: String, method: String) {
+        synchronized(routes) {
+            routes.remove("$iface.$method")
+        }
+    }
+
+    fun setManifest(packageName: String, manifest: InstalledMiniappManifest) {
+        synchronized(manifests) {
+            manifests[packageName] = manifest
+        }
+    }
+
+    fun clearManifest(packageName: String) {
+        synchronized(manifests) {
+            manifests.remove(packageName)
+        }
+    }
+
+    fun manifest(packageName: String): InstalledMiniappManifest? {
+        synchronized(manifests) {
+            return manifests[packageName]
+        }
+    }
+
+    /**
+     * Main entry. Called from the `__dispatch` JS global installed on each
+     * QuickJs context by [JSCRuntime.installGlobals]. The JS side invokes
+     * `__dispatch(iface, method, argsJson)` and gets back a JSON string, null,
+     * or a thrown Error.
+     *
+     * Permission gate: bridge-internal calls (`__runtime`, `__log`, crypto,
+     * localStorage) are exempt — they don't touch OS sensors. For everything
+     * else, only the manifest declaration matters. There is no JIT prompt;
+     * install is the consent step (matches the cloud-WebView lifecycle).
+     */
+    fun handle(packageName: String, iface: String, method: String, args: List<Any?>, reqId: String?): JSCDispatchOutcome {
+        val required = permissionRequirements[iface]
+        if (required != null && required !in implicitGrants) {
+            val declared = manifest(packageName)?.permissions ?: emptySet()
+            if (required !in declared) {
+                return JSCDispatchOutcome.Error("PERMISSION_NOT_DECLARED", required)
+            }
+        }
+        val handler = synchronized(routes) { routes["$iface.$method"] }
+        if (handler != null) {
+            return handler.handle(packageName, args, reqId)
+        }
+        return JSCDispatchOutcome.ForwardToRn(mapOf("args" to args))
+    }
+
+    private fun installBuiltinRoutes() {
+        register("__runtime", "ready") { packageName, _, _ ->
+            JSCRuntime.shared(appContext).markReady(packageName)
+            JSCDispatchOutcome.Sync("null")
+        }
+
+        // localStorage — SharedPreferences-backed, scoped per packageName.
+        // String-only contract; the JS shim coerces non-strings via String(v).
+        register("localStorage", "getItem") { pkg, args, _ ->
+            val key = args.firstOrNull() as? String ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "localStorage.getItem(key)")
+            val prefs = prefs(pkg)
+            val v = prefs.getString(key, null)
+            JSCDispatchOutcome.Sync(if (v == null) "null" else JSONArray().put(v).toString().let { arr -> arr.substring(1, arr.length - 1) })
+        }
+        register("localStorage", "setItem") { pkg, args, _ ->
+            if (args.size < 2 || args[0] !is String || args[1] !is String) {
+                return@register JSCDispatchOutcome.Error("INVALID_ARGS", "localStorage.setItem(key, value)")
+            }
+            prefs(pkg).edit().putString(args[0] as String, args[1] as String).apply()
+            JSCDispatchOutcome.Sync("null")
+        }
+        register("localStorage", "removeItem") { pkg, args, _ ->
+            val key = args.firstOrNull() as? String ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "localStorage.removeItem(key)")
+            prefs(pkg).edit().remove(key).apply()
+            JSCDispatchOutcome.Sync("null")
+        }
+        register("localStorage", "clear") { pkg, _, _ ->
+            prefs(pkg).edit().clear().apply()
+            JSCDispatchOutcome.Sync("null")
+        }
+        register("localStorage", "length") { pkg, _, _ ->
+            JSCDispatchOutcome.Sync(prefs(pkg).all.size.toString())
+        }
+        register("localStorage", "key") { pkg, args, _ ->
+            val idx = (args.firstOrNull() as? Number)?.toInt()
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "localStorage.key(index)")
+            val keys = prefs(pkg).all.keys.sorted()
+            if (idx < 0 || idx >= keys.size) {
+                JSCDispatchOutcome.Sync("null")
+            } else {
+                val str = JSONArray().put(keys[idx]).toString()
+                JSCDispatchOutcome.Sync(str.substring(1, str.length - 1))
+            }
+        }
+
+        register("crypto", "getRandomBytes") { _, args, _ ->
+            val n = (args.firstOrNull() as? Number)?.toInt()
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "getRandomBytes(n)")
+            if (n < 0 || n > (1 shl 20)) {
+                return@register JSCDispatchOutcome.Error("INVALID_ARGS", "getRandomBytes max 1MB")
+            }
+            val bytes = ByteArray(n)
+            try {
+                random.nextBytes(bytes)
+            } catch (e: Throwable) {
+                Log.w(TAG, "SecureRandom failed: ${e.message}")
+                return@register JSCDispatchOutcome.Error("NATIVE_THROW", "SecureRandom: ${e.message}")
+            }
+            // Return as JSON array of unsigned bytes.
+            val arr = JSONArray()
+            for (b in bytes) arr.put(b.toInt() and 0xff)
+            JSCDispatchOutcome.Sync(arr.toString())
+        }
+    }
+
+    private fun prefs(packageName: String): SharedPreferences {
+        return appContext.getSharedPreferences("MentraJS-$packageName", Context.MODE_PRIVATE)
+    }
+}

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

@@ -0,0 +1,287 @@
+package com.mentra.crust.jsc
+
+import android.util.Log
+import java.io.IOException
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.WebSocket
+import okhttp3.WebSocketListener
+import okio.ByteString
+import okio.ByteString.Companion.toByteString
+import org.json.JSONObject
+import org.json.JSONArray
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.TimeUnit
+import android.util.Base64
+
+/**
+ * Native bridge for the network polyfills that can't be implemented in
+ * pure JS (fetch, WebSocket). Mirrors iOS [JSCPolyfillBridge.swift].
+ *
+ * Each request opens an OkHttp call that outlives the originating
+ * __dispatch invocation, so we route the response back via
+ * [JSCRuntime.dispatchToJs] when the call completes. The JS polyfill's
+ * Promise correlator (the `__mentraSendRequest` reqId map) takes it from
+ * there.
+ *
+ * Microtask discipline: the response evaluator goes through the
+ * QuickJs.evaluate path (bridge re-entry) which drains pending Promise
+ * jobs automatically. We never need to call QuickJS's private
+ * `JS_ExecutePendingJob` — see the spec's Android microtask section.
+ */
+object JSCPolyfillBridge {
+    private const val TAG = "MentraJS.PolyfillBridge"
+
+    private val httpClient: OkHttpClient by lazy {
+        OkHttpClient.Builder()
+            .connectTimeout(30, TimeUnit.SECONDS)
+            .readTimeout(60, TimeUnit.SECONDS)
+            .callTimeout(120, TimeUnit.SECONDS)
+            .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 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 upperMethod = method.uppercase()
+        val requestBody = when {
+            bodyString != null -> bodyString.toRequestBody((contentType ?: "application/octet-stream").toMediaTypeOrNull())
+            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 HttpResult(
+                status = response.code,
+                statusText = response.message,
+                headers = responseHeaders,
+                body = response.body?.string() ?: "",
+            )
+        }
+    }
+
+    /** Idempotent. Call once on host boot, after the dispatcher is created. */
+    fun install(runtime: JSCRuntime) {
+        installFetch(runtime)
+        installWebSocket(runtime)
+    }
+
+    private val sockets = ConcurrentHashMap<String, OkSocketRecord>()
+
+    private data class OkSocketRecord(
+        val packageName: String,
+        val socket: WebSocket,
+        @Volatile var closedSent: Boolean = false,
+    )
+
+    private fun installWebSocket(runtime: JSCRuntime) {
+        runtime.dispatcher.register("ws", "open") { packageName, args, _ ->
+            val req = args.firstOrNull() as? Map<*, *>
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open expects {sid, url, protocols?}")
+            val sid = req["sid"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open: missing sid")
+            val url = req["url"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.open: missing url")
+            val protocols = (req["protocols"] as? List<*>)?.mapNotNull { it as? String } ?: emptyList()
+            val builder = Request.Builder().url(url)
+            if (protocols.isNotEmpty()) {
+                builder.header("Sec-WebSocket-Protocol", protocols.joinToString(", "))
+            }
+            val listener = object : WebSocketListener() {
+                override fun onOpen(webSocket: WebSocket, response: okhttp3.Response) {
+                    val proto = response.header("Sec-WebSocket-Protocol")
+                    val payload = if (proto.isNullOrEmpty()) emptyMap<String, Any?>() else mapOf("protocol" to proto)
+                    deliverEvent(runtime, packageName, sid, "open", payload)
+                }
+                override fun onMessage(webSocket: WebSocket, text: String) {
+                    deliverEvent(runtime, packageName, sid, "message", mapOf("kind" to "text", "data" to text))
+                }
+                override fun onMessage(webSocket: WebSocket, bytes: ByteString) {
+                    val b64 = Base64.encodeToString(bytes.toByteArray(), Base64.NO_WRAP)
+                    deliverEvent(runtime, packageName, sid, "message", mapOf("kind" to "binary", "data" to b64))
+                }
+                override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
+                    webSocket.close(code, reason)
+                }
+                override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                    val rec = sockets.remove(sid) ?: return
+                    if (!rec.closedSent) {
+                        rec.closedSent = true
+                        deliverEvent(runtime, packageName, sid, "close", mapOf("code" to code, "reason" to reason))
+                    }
+                }
+                override fun onFailure(webSocket: WebSocket, t: Throwable, response: okhttp3.Response?) {
+                    deliverEvent(runtime, packageName, sid, "error", mapOf("message" to (t.message ?: "ws error")))
+                    val rec = sockets.remove(sid) ?: return
+                    if (!rec.closedSent) {
+                        rec.closedSent = true
+                        deliverEvent(runtime, packageName, sid, "close", mapOf("code" to 1006, "reason" to (t.message ?: "")))
+                    }
+                }
+            }
+            val socket = httpClient.newWebSocket(builder.build(), listener)
+            sockets[sid] = OkSocketRecord(packageName, socket)
+            JSCDispatchOutcome.Sync("null")
+        }
+
+        runtime.dispatcher.register("ws", "send") { _, args, _ ->
+            val req = args.firstOrNull() as? Map<*, *>
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send expects {sid, kind, payload}")
+            val sid = req["sid"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: missing sid")
+            val kind = req["kind"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: missing kind")
+            val payload = req["payload"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: missing payload")
+            val rec = sockets[sid]
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: unknown sid")
+            val ok = when (kind) {
+                "text" -> rec.socket.send(payload)
+                "binary" -> {
+                    val bytes = try {
+                        Base64.decode(payload, Base64.DEFAULT)
+                    } catch (e: IllegalArgumentException) {
+                        return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: bad base64")
+                    }
+                    rec.socket.send(bytes.toByteString())
+                }
+                else -> return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.send: kind must be text|binary")
+            }
+            if (!ok) {
+                Log.w(TAG, "ws.send returned false for sid=$sid (queue full?)")
+            }
+            JSCDispatchOutcome.Sync("null")
+        }
+
+        runtime.dispatcher.register("ws", "close") { _, args, _ ->
+            val req = args.firstOrNull() as? Map<*, *>
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.close expects {sid, code?, reason?}")
+            val sid = req["sid"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "ws.close: missing sid")
+            val rec = sockets[sid] ?: return@register JSCDispatchOutcome.Sync("null")
+            val code = (req["code"] as? Number)?.toInt() ?: 1000
+            val reason = (req["reason"] as? String) ?: ""
+            rec.socket.close(code, reason)
+            JSCDispatchOutcome.Sync("null")
+        }
+    }
+
+    private fun deliverEvent(
+        runtime: JSCRuntime,
+        packageName: String,
+        sid: String,
+        wsType: String,
+        payload: Map<String, Any?>,
+    ) {
+        val envelope = JSONObject().apply {
+            put("kind", "ws-event")
+            put("sid", sid)
+            put("wsType", wsType)
+            put("payload", JSONObject(payload as Map<*, *>))
+        }
+        runtime.dispatchToJs(packageName, envelope.toString())
+    }
+
+    private fun installFetch(runtime: JSCRuntime) {
+        runtime.dispatcher.register("fetch", "request") { packageName, args, reqId ->
+            val req = args.firstOrNull() as? Map<*, *>
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request expects {url,...}")
+            val url = req["url"] as? String
+                ?: return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request: missing url")
+            if (reqId == null) {
+                return@register JSCDispatchOutcome.Error("INVALID_ARGS", "fetch.request requires reqId (use __mentraSendRequest)")
+            }
+
+            val method = (req["method"] as? String) ?: "GET"
+            val headers = (req["headers"] as? Map<*, *>)?.mapNotNull { (k, v) ->
+                val ks = k as? String ?: return@mapNotNull null
+                val vs = (v as? String) ?: v?.toString() ?: return@mapNotNull null
+                ks to vs
+            }?.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)
+
+            httpClient.newCall(builder.build()).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())
+                    }
+                }
+            })
+            JSCDispatchOutcome.Async
+        }
+    }
+
+    private fun deliverError(runtime: JSCRuntime, packageName: String, reqId: String, message: String) {
+        val envelope = JSONObject().apply {
+            put("kind", "response")
+            put("reqId", reqId)
+            put("ok", false)
+            put("error", JSONObject().apply {
+                put("code", "NATIVE_THROW")
+                put("message", message)
+            })
+        }
+        runtime.dispatchToJs(packageName, envelope.toString())
+    }
+}