@mentra/engine 3.1.0-dev.4 → 3.1.0-dev.42

package/src/services/BlobStore.ts

@@ -40,8 +40,15 @@ const LOG_TAG = "LocalMiniappRuntime"
 /** Per-app blob quota: 1 GB. */
 export const BLOB_QUOTA_BYTES = 1024 * 1024 * 1024
 const ROOT_DIR_NAME = "mentra_blobs"
-/** Cache dir root holding short-lived, properly-named copies handed to the OS share sheet (one unique subdir per share). */
+/** Cache dir root holding short-lived, properly-named copies handed to the OS share sheet (one subdir per stored blob). */
 const SHARE_DIR_NAME = "mentra_blob_share"
+/**
+ * Keep prepared share handoffs alive long enough for recipient apps to read
+ * them asynchronously (for example, an email composer attaching the file).
+ * Stale copies are collected before the next share; the OS may evict cache
+ * files sooner under storage pressure.
+ */
+const SHARE_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000
 const META_KEY_ROOT = "mentraos_blobmeta_"
 /** Cap md5 computation so we don't block the JS thread hashing a huge file. */
 const MD5_MAX_BYTES = 50 * 1024 * 1024
@@ -598,6 +605,32 @@ export class BlobStore {
 
   // ---- share ---------------------------------------------------------------
 
+  /** Best-effort GC for prepared share handoffs retained in the OS cache. */
+  private cleanupShareCache(now = Date.now()): void {
+    try {
+      const root = new Directory(Paths.cache, SHARE_DIR_NAME)
+      if (!root.exists) return
+      const cutoff = now - SHARE_CACHE_MAX_AGE_MS
+      for (const entry of root.list()) {
+        if (!(entry instanceof Directory)) continue
+        try {
+          const info = entry.info()
+          // modificationTime is available on both platforms; creationTime can
+          // be absent on Android versions before API 26. The directory id
+          // begins with Date.now().toString(36), which is a final fallback.
+          const encoded = entry.name.split("-", 1)[0]
+          const encodedTime = /^[0-9a-z]+$/.test(encoded) ? Number.parseInt(encoded, 36) : Number.NaN
+          const timestamp = info.modificationTime ?? info.creationTime ?? encodedTime
+          if (Number.isFinite(timestamp) && timestamp < cutoff) entry.delete()
+        } catch {
+          // Keep scanning if one cache entry disappears or is unreadable.
+        }
+      }
+    } catch {
+      // Cache cleanup must never prevent a share.
+    }
+  }
+
   async handleShare(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
     const key = payload.key as string
     const meta = this.readMeta(packageName, key)
@@ -615,23 +648,33 @@ export class BlobStore {
     // applies to base64/data payloads, not file:// URLs), so sharing `file.uri`
     // directly would hand the recipient a machine-named file. Copy to a temp
     // file that carries the real display name + extension, share that, then
-    // clean it up.
+    // clean it up after the recipient has had time to consume it.
     const shareName = shareFileName(meta)
-    // Copy into a per-share unique subdir so two concurrent shares that resolve
-    // to the same display name can't clobber each other's temp file while
-    // Share.open still references it. The file keeps `shareName` as its basename
-    // so the OS share sheet shows the right name + extension.
+    // Key the cache directory by the immutable stored filename. Repeated or
+    // concurrent shares of the same blob can safely reference the same bytes,
+    // avoiding an extra full-sized cache copy for every share. Different blobs
+    // still get isolated directories even when they use the same display name.
+    // The file keeps `shareName` as its basename so the OS share sheet shows the
+    // right name + extension.
     let tempDir: Directory | null = null
+    let cacheReady = false
     try {
-      tempDir = new Directory(Paths.cache, SHARE_DIR_NAME, this.makeId())
-      tempDir.create({intermediates: true})
+      this.cleanupShareCache()
+      tempDir = new Directory(Paths.cache, SHARE_DIR_NAME, sanitizeSegment(meta.fileName))
+      if (!tempDir.exists) tempDir.create({intermediates: true})
       const temp = new File(tempDir, shareName)
-      file.copy(temp)
+      if (!temp.exists || temp.size !== meta.bytes) {
+        if (temp.exists) temp.delete()
+        file.copy(temp)
+      }
+      cacheReady = true
       await Share.open({
         url: temp.uri,
         type: meta.mimeType || OCTET,
         filename: shareName,
       })
+      // Share.open resolves once the OS accepts the handoff. Recipient apps may
+      // still read the URI asynchronously, so retain this cache copy for GC.
       this.hooks.sendResult(packageName, requestId, true, {success: true})
     } catch (error: any) {
       if (error?.message?.includes("User did not share")) {
@@ -641,7 +684,11 @@ export class BlobStore {
         this.hooks.sendResult(packageName, requestId, true, {success: false})
       }
     } finally {
-      if (tempDir) {
+      // Once a reusable cache entry is ready, retain it even if this particular
+      // sheet is cancelled or fails: another concurrent/recent share may still
+      // be reading the same file. Only remove an entry whose preparation did
+      // not finish; ready entries are collected after the retention window.
+      if (tempDir && !cacheReady) {
         try {
           if (tempDir.exists) tempDir.delete()
         } catch {

package/src/services/GlassesStatusProjection.ts

@@ -11,17 +11,18 @@
  *
  * Started by `engine.start()`. Idempotent.
  */
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {GlassesStatus} from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk, {type PublicGlassesStatus} from "@mentra/bluetooth-sdk"
 import {useCoreStore} from "../stores/core"
 import {useGlassesStore} from "../stores/glasses"
 
 let unsubs: Array<() => void> = []
 let projectionRunId = 0
-let glassesStatusForwarder: ((status: Partial<GlassesStatus>) => void) | null = null
+let glassesStatusForwarder: ((status: Partial<PublicGlassesStatus>) => void) | null = null
 let hydrationPromise: Promise<void> | null = null
 
-export function startGlassesStatusProjection(forwarder?: (status: Partial<GlassesStatus>) => void): Promise<void> {
+export function startGlassesStatusProjection(
+  forwarder?: (status: Partial<PublicGlassesStatus>) => void,
+): Promise<void> {
   if (forwarder) glassesStatusForwarder = forwarder
   if (unsubs.length) return hydrationPromise ?? Promise.resolve()
 
@@ -49,7 +50,7 @@ export function startGlassesStatusProjection(forwarder?: (status: Partial<Glasse
 
   // Bluetooth-adapter status -> core store.
   unsubs.push(
-    BluetoothSdk.onBluetoothStatus((changed) => {
+    BluetoothSdk.subscribeBluetoothStatus((changed) => {
       bluetoothEventSeen = true
       useCoreStore.getState().setCoreInfo(changed)
     }),
@@ -58,7 +59,7 @@ export function startGlassesStatusProjection(forwarder?: (status: Partial<Glasse
   // Glasses status -> glasses store (+ optional full-runtime forwarding to local
   // miniapps; clear any stale OTA-available flag on disconnect).
   unsubs.push(
-    BluetoothSdk.onGlassesStatus((changed) => {
+    BluetoothSdk.subscribeGlassesStatus((changed) => {
       glassesEventSeen = true
       useGlassesStore.getState().setGlassesInfo(changed)
       glassesStatusForwarder?.(changed)

package/src/services/HotspotOtaTransport.ts

@@ -1,4 +1,5 @@
-import BluetoothSdk, {isEnabledHotspotStatus, MentraOtaServer} from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk, {isEnabledHotspotStatus} from "@mentra/bluetooth-sdk"
+import {otaServer} from "@mentra/bluetooth-sdk/ota-transport"
 // One coordinator selects the native Android or iOS staging implementation at runtime.
 // eslint-disable-next-line react-native/split-platform-components
 import {PermissionsAndroid, Platform} from "react-native"
@@ -83,7 +84,7 @@ class HotspotOtaTransport {
       let localAddress = scopedAddress
       if (Platform.OS === "ios") {
         try {
-          localAddress = await MentraOtaServer.waitForWifiAddress(hotspot.localIp, 15_000)
+          localAddress = await otaServer.waitForWifiAddress(hotspot.localIp, 15_000)
         } catch (error) {
           throw new HotspotOtaTransportError(
             "hotspot_join_failed",
@@ -94,10 +95,10 @@ class HotspotOtaTransport {
       const artifactPaths = Object.fromEntries(this.prepared.map((artifact) => [artifact.sha256, artifact.filePath]))
       // Start exactly one native listener to learn its selected port, then atomically replace
       // the placeholder with the immutable rewritten manifest before ota_start is sent.
-      const server = await MentraOtaServer.startOtaServer("{}", artifactPaths, localAddress)
+      const server = await otaServer.start("{}", artifactPaths, localAddress)
       this.serverStarted = true
       const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)
-      const published = await MentraOtaServer.startOtaServer(manifest, artifactPaths, server.host)
+      const published = await otaServer.start(manifest, artifactPaths, server.host)
       if (published.manifestUrl !== server.manifestUrl) {
         throw new Error("Local OTA server endpoint changed while publishing the manifest")
       }
@@ -141,11 +142,11 @@ class HotspotOtaTransport {
     destination: string,
     onProgress?: (bytesWritten: number, contentLength: number) => void,
   ): Promise<{statusCode: number}> => {
-    const subscription = MentraOtaServer.addListener("artifactDownloadProgress", (event) => {
+    const subscription = otaServer.onArtifactDownloadProgress((event) => {
       if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)
     })
     try {
-      return await MentraOtaServer.downloadArtifact(entry.url, destination)
+      return await otaServer.downloadArtifact(entry.url, destination)
     } finally {
       subscription.remove()
     }
@@ -164,7 +165,7 @@ class HotspotOtaTransport {
           console.warn("[OTA_PROGRESS] glasses hotspot shutdown was not confirmed after bounded retries")
         }
       }
-      if (this.serverStarted) await MentraOtaServer.stopOtaServer().catch(() => {})
+      if (this.serverStarted) await otaServer.stop().catch(() => {})
       if (this.localNetworkConnected) await localNetworkTransport.disconnect().catch(() => {})
       await cleanupArtifacts().catch(() => {})
       this.prepared = []

package/src/services/OtaAutoChain.ts

@@ -6,10 +6,18 @@ export const OTA_AUTO_CHAIN_RECONNECT_TIMEOUT_MS = 120_000
 type OtaAutoChainSession = {
   approvedDowngrade: boolean
   passCount: number
+  releaseRange: OtaAutoChainReleaseRange
   reconnectDeadline: number | null
   seenFingerprints: Set<string>
 }
 
+export type OtaAutoChainReleaseRange = {
+  fromVersion: string | null
+  toVersion: string | null
+  /** Exact coordinated release identity for the OTA pin, absent for legacy manifests. */
+  releaseVersion?: string | null
+}
+
 export type OtaAutoChainAdvanceResult =
   | {advance: true; passCount: number}
   | {advance: false; reason: "inactive" | "duplicate" | "max_passes" | "downgrade_not_approved"}
@@ -42,10 +50,15 @@ export function otaAutoChainFingerprint(result: OtaCheckCurrentGlassesResult): s
 }
 
 /** Start a chain after the user explicitly approves its first update pass. */
-export function beginOtaAutoChain(initialFingerprint: string, approvedDowngrade: boolean): void {
+export function beginOtaAutoChain(
+  initialFingerprint: string,
+  approvedDowngrade: boolean,
+  releaseRange: OtaAutoChainReleaseRange,
+): void {
   session = {
     approvedDowngrade,
     passCount: 1,
+    releaseRange: {...releaseRange},
     reconnectDeadline: null,
     seenFingerprints: new Set([initialFingerprint]),
   }
@@ -55,6 +68,10 @@ export function isOtaAutoChainActive(): boolean {
   return session !== null
 }
 
+export function otaAutoChainReleaseRange(): OtaAutoChainReleaseRange | null {
+  return session ? {...session.releaseRange} : null
+}
+
 /** End the current chain. Safe to call when no chain is active. */
 export function stopOtaAutoChain(): void {
   session = null
@@ -80,7 +97,12 @@ export function clearOtaAutoChainReconnectWait(): void {
  * Admit the next pass of an active chain. Repeated offers, unexpectedly
  * destructive downgrades, and runaway chains fail closed and end automation.
  */
-export function tryAdvanceOtaAutoChain(fingerprint: string, isDowngrade: boolean): OtaAutoChainAdvanceResult {
+export function tryAdvanceOtaAutoChain(
+  fingerprint: string,
+  isDowngrade: boolean,
+  targetVersion: string | null,
+  releaseVersion: string | null = null,
+): OtaAutoChainAdvanceResult {
   if (!session) {
     return {advance: false, reason: "inactive"}
   }
@@ -102,5 +124,7 @@ export function tryAdvanceOtaAutoChain(fingerprint: string, isDowngrade: boolean
 
   session.seenFingerprints.add(fingerprint)
   session.passCount += 1
+  if (targetVersion) session.releaseRange.toVersion = targetVersion
+  if (releaseVersion) session.releaseRange.releaseVersion = releaseVersion
   return {advance: true, passCount: session.passCount}
 }

package/src/services/OtaInstallCoordinator.ts

@@ -17,8 +17,7 @@
  * state written mid-pass queues a follow-up pass — the same way a setState
  * during React effects scheduled a re-render after the current effect batch.
  */
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk"
+import BluetoothSdk, {type OtaProgress, type OtaStatus} from "@mentra/bluetooth-sdk"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {isGlassesConnected, useGlassesStore} from "../stores/glasses"
 import {resolveOtaManifestUrl} from "./otaManifestUrl"
@@ -170,6 +169,8 @@ export interface OtaInstallSnapshot {
   /** Pre-ota_start phone staging/join state for a hotspot attempt. */
   hotspotPhase: HotspotOtaPhase
   hotspotArtifactPercent: number | null
+  /** Transport selected from the checked glasses capabilities and Wi-Fi state. */
+  transport: "wifi" | "hotspot"
 }
 
 type OtaStartOutcome = "pending" | "acknowledged" | "rejected"
@@ -407,7 +408,7 @@ class OtaInstallCoordinator {
         if (this.otaStartOwnership?.outcome === "pending") {
           void this.sendOtaStartWithWatchdogs()
         } else {
-          void BluetoothSdk.sendOtaQueryStatus().catch(() => {})
+          void BluetoothSdk.queryOtaStatus().catch(() => {})
           this.armQueryReplyFallback("retry")
         }
       }
@@ -449,16 +450,17 @@ class OtaInstallCoordinator {
    * stays in the screen): clear the selected update, and after an APK step
    * clear the stale build number so the next check re-reads version_info.
    */
-  finish(): void {
+  async finish(): Promise<void> {
     if (this.otaStartOwnership?.outcome !== "pending") {
       this.otaStartOwnership = null
     }
     useGlassesStore.getState().setOtaUpdateAvailable(null)
     if (this.apkStepSeen) {
-      BluetoothSdk.updateGlasses({buildNumber: ""})
       useGlassesStore.getState().setGlassesInfo({buildNumber: ""})
     }
-    void this.teardownHotspotTransport()
+    // The post-install check needs internet again. Do not let callers leave the
+    // terminal screen while Android still owns the no-internet hotspot route.
+    await this.teardownHotspotTransport()
   }
 
   /**
@@ -467,8 +469,8 @@ class OtaInstallCoordinator {
    * deriveDisplayState doesn't resurrect the stale install when the host
    * navigates away and back through /ota routes.
    */
-  discard(): void {
-    this.finish()
+  async discard(): Promise<void> {
+    await this.finish()
     const store = useGlassesStore.getState()
     store.setOtaStatus(null)
     store.setOtaProgress(null)
@@ -505,6 +507,7 @@ class OtaInstallCoordinator {
       versionChangePhase: this.deriveVersionChangePhase(connected),
       hotspotPhase: this.hotspotPhase,
       hotspotArtifactPercent: this.hotspotArtifactPercent,
+      transport: this.selectedTransport,
     }
   }
 
@@ -1065,7 +1068,7 @@ class OtaInstallCoordinator {
     if (this.otaStartOwnership?.outcome === "pending") {
       void this.sendOtaStartWithWatchdogs()
     }
-    void BluetoothSdk.sendOtaQueryStatus()
+    void BluetoothSdk.queryOtaStatus().catch(() => {})
     this.armQueryReplyFallback("reconnect")
     return true
   }
@@ -1109,7 +1112,7 @@ class OtaInstallCoordinator {
     if (noSessionYet) {
       if (!isIdleStatus && this.otaStartOwnership?.outcome === "acknowledged") {
         console.log("[OTA_PROGRESS] initial mount, acknowledged session has no cached status — reconciling")
-        void BluetoothSdk.sendOtaQueryStatus().catch(() => {})
+        void BluetoothSdk.queryOtaStatus().catch(() => {})
         this.armQueryReplyFallback("initial-mount")
         return
       }
@@ -1125,7 +1128,7 @@ class OtaInstallCoordinator {
       void this.sendOtaStartWithWatchdogs()
     } else {
       console.log("[OTA_PROGRESS] initial mount, session exists, sending ota_query_status")
-      void BluetoothSdk.sendOtaQueryStatus()
+      void BluetoothSdk.queryOtaStatus().catch(() => {})
       this.armQueryReplyFallback("initial-mount")
     }
   }
@@ -1154,7 +1157,7 @@ class OtaInstallCoordinator {
     this.clearProgressTimeout()
     this.onFirstActivity()
     this.onFirstNonZeroProgress()
-    void BluetoothSdk.sendOtaQueryStatus()
+    void BluetoothSdk.queryOtaStatus().catch(() => {})
     useGlassesStore.getState().setMtkUpdatedThisSession(true)
   }
 
@@ -1345,7 +1348,7 @@ class OtaInstallCoordinator {
     const s = useGlassesStore.getState().otaStatus
     if (s?.stepType === "apk" && s.phase === "install" && s.status === "in_progress") {
       this.apkInstallPollInFlight = true
-      void BluetoothSdk.sendOtaQueryStatus()
+      void BluetoothSdk.queryOtaStatus()
         .catch(() => {})
         .finally(() => {
           this.apkInstallPollInFlight = false

package/src/services/OtaService.ts

@@ -10,8 +10,7 @@
  *
  * Started by `engine.start()`. Idempotent.
  */
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk, {type OtaStatus} from "@mentra/bluetooth-sdk"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {useGlassesStore} from "../stores/glasses"
 import {handleOtaClockSkewFromGlasses} from "./glassesClockSync"

package/src/services/OtaUpdateCheckService.ts

@@ -1,8 +1,9 @@
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
-import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk"
+import BluetoothSdk, {type OtaUpdateInfo} from "@mentra/bluetooth-sdk"
+import {ENGINE_RELEASE_METADATA} from "../generated/releaseMetadata"
 import {getGlassesSystemTimeMs, isGlassesConnected, useGlassesStore, waitForGlassesState} from "../stores/glasses"
 import {maybeFixGlassesClockFromVersionInfo} from "./glassesClockSync"
 import {hasConfiguredModernOtaManifestPin, resolveOtaManifestUrl} from "./otaManifestUrl"
+import {resolveOtaReleaseVersion} from "./otaReleaseVersion"
 
 /**
  * Phone-side mirror of ASG's `DOWNGRADE_FLOOR_VERSION_CODE`. Set to the versionCode of the first
@@ -38,6 +39,7 @@ export interface BesFirmware {
 }
 
 export interface VersionJson {
+  releaseVersion?: string
   apps?: {
     [packageName: string]: VersionInfo
   }
@@ -66,6 +68,8 @@ export interface OtaCheckResult {
    * instead of racing it with a second fetch of the same URL.
    */
   manifestBody: string | null
+  /** Coordinated release identity for the selected OTA pin. */
+  releaseVersion: string | null
   /**
    * Why the check failed, when it did. "network" is retryable (connection/server
    * trouble); "pin_unavailable" is permanent for this app build (manifest 404/gone,
@@ -106,6 +110,7 @@ function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurren
     besVersion: null,
     isApkDowngrade: false,
     manifestBody: null,
+    releaseVersion: null,
     updateInfo: null,
     isRequired: true,
     skippedReason,
@@ -122,7 +127,7 @@ async function fetchVersionInfoDetailed(url: string): Promise<ManifestFetchResul
   try {
     const response = await fetch(url)
     if (!response.ok) {
-      console.error("Failed to fetch version info:", response.status)
+      console.warn("Failed to fetch version info:", response.status)
       // 4xx: the manifest does not exist (or is gone) — permanent for this app
       // build, retrying cannot help. Everything else is transient server/network
       // trouble and retryable.
@@ -134,11 +139,11 @@ async function fetchVersionInfoDetailed(url: string): Promise<ManifestFetchResul
     try {
       return {json: await response.json()}
     } catch (parseError) {
-      console.error("OTA: manifest is not valid JSON:", parseError)
+      console.warn("OTA: manifest is not valid JSON:", parseError)
       return {json: null, failureReason: "pin_unavailable"}
     }
   } catch (error) {
-    console.error("OTA: Error fetching version info:", error)
+    console.warn("OTA: Error fetching version info:", error)
     return {json: null, failureReason: "network"}
   }
 }
@@ -298,6 +303,7 @@ export async function checkForOtaUpdate(
         besVersion: null,
         isApkDowngrade: false,
         manifestBody: null,
+        releaseVersion: null,
         checkFailureReason: fetched.failureReason ?? "network",
       }
     }
@@ -329,6 +335,7 @@ export async function checkForOtaUpdate(
         besVersion: null,
         isApkDowngrade: false,
         manifestBody: null,
+        releaseVersion: null,
         checkFailureReason: "pin_unavailable",
       }
     }
@@ -367,6 +374,12 @@ export async function checkForOtaUpdate(
       besVersion: versionJson?.bes_firmware?.version || null,
       isApkDowngrade: apkDirection === "downgrade",
       manifestBody: versionJson ? JSON.stringify(versionJson) : null,
+      releaseVersion: resolveOtaReleaseVersion({
+        manifestReleaseVersion: versionJson.releaseVersion,
+        manifestUrl: otaVersionUrl,
+        packagedManifestUrl: ENGINE_RELEASE_METADATA.otaManifestUrl,
+        packagedReleaseIdentity: ENGINE_RELEASE_METADATA.releaseIdentity,
+      }),
     }
   } catch (error) {
     console.error("Error checking for OTA update:", error)
@@ -379,6 +392,7 @@ export async function checkForOtaUpdate(
       besVersion: null,
       isApkDowngrade: false,
       manifestBody: null,
+      releaseVersion: null,
       checkFailureReason: "network",
     }
   }
@@ -406,9 +420,13 @@ export async function checkCurrentGlassesForUpdate(
   }
 
   if (refreshVersionInfo) {
-    void BluetoothSdk.requestVersionInfo().catch((error) => {
-      console.warn("OTA: Failed to request version_info from glasses:", error)
-    })
+    void BluetoothSdk.requestVersionInfo()
+      .then((versionInfo) => {
+        useGlassesStore.getState().setGlassesInfo(versionInfo)
+      })
+      .catch((error) => {
+        console.warn("OTA: Failed to request version_info from glasses:", error)
+      })
   }
 
   let buildNumber = useGlassesStore.getState().buildNumber

package/src/services/asg/localNetworkTransport.ts

@@ -1,5 +1,5 @@
 import * as RNFS from "@dr.pogodin/react-native-fs"
-import {MentraLocalNetwork, type LocalNetworkDownloadProgress} from "@mentra/bluetooth-sdk/internal"
+import {otaLocalNetwork, type OtaLocalNetworkDownloadProgress} from "@mentra/bluetooth-sdk/ota-transport"
 import {Buffer} from "buffer"
 import {Platform} from "react-native"
 import WifiManager from "react-native-wifi-reborn"
@@ -17,7 +17,7 @@ export function shouldUseScopedLocalNetwork(os: string, moduleAvailable: boolean
 }
 
 function supportsScopedConnection(): boolean {
-  return shouldUseScopedLocalNetwork(Platform.OS, MentraLocalNetwork != null)
+  return shouldUseScopedLocalNetwork(Platform.OS, otaLocalNetwork.isAvailable())
 }
 
 function normalizeHeaders(headers?: HeadersInit): Record<string, string> {
@@ -48,25 +48,25 @@ export const localNetworkTransport = {
       await WifiManager.connectToProtectedSSID(ssid, password, false, false)
       return undefined
     }
-    const result = await MentraLocalNetwork!.connect(ssid, password)
+    const result = await otaLocalNetwork.connect(ssid, password)
     scopedConnectionActive = true
     return result.localAddress
   },
 
   async disconnect(): Promise<void> {
     if (supportsScopedConnection()) {
-      await MentraLocalNetwork!.disconnect().catch(() => {})
+      await otaLocalNetwork.disconnect().catch(() => {})
     }
     scopedConnectionActive = false
     nativeJobs.clear()
   },
 
   async fetch(url: string | URL | Request, init?: RequestInit, timeoutMs = 30_000): Promise<Response> {
-    if (!scopedConnectionActive || !MentraLocalNetwork || typeof url !== "string") {
+    if (!scopedConnectionActive || !otaLocalNetwork.isAvailable() || typeof url !== "string") {
       return globalThis.fetch(url, init)
     }
 
-    const nativeModule = MentraLocalNetwork
+    const nativeModule = otaLocalNetwork
     const id = requestId("request")
     const signal = init?.signal
     const cancel = () => void nativeModule.cancel(id)
@@ -92,13 +92,13 @@ export const localNetworkTransport = {
   },
 
   downloadFile(options: DownloadOptions): DownloadHandle {
-    if (!scopedConnectionActive || !MentraLocalNetwork) return RNFS.downloadFile(options)
+    if (!scopedConnectionActive || !otaLocalNetwork.isAvailable()) return RNFS.downloadFile(options)
 
     const jobId = nextJobId++
     const id = requestId("download")
     let began = false
     nativeJobs.set(jobId, id)
-    const subscription = MentraLocalNetwork.addListener("downloadProgress", (event: LocalNetworkDownloadProgress) => {
+    const subscription = otaLocalNetwork.onDownloadProgress((event: OtaLocalNetworkDownloadProgress) => {
       if (event.requestId !== id) return
       if (!began) {
         began = true
@@ -116,14 +116,15 @@ export const localNetworkTransport = {
       })
     })
 
-    const promise = MentraLocalNetwork.download(
-      id,
-      options.fromUrl,
-      options.toFile,
-      options.headers || {},
-      options.connectionTimeout || 30_000,
-      options.readTimeout || 30_000,
-    )
+    const promise = otaLocalNetwork
+      .download(
+        id,
+        options.fromUrl,
+        options.toFile,
+        options.headers || {},
+        options.connectionTimeout || 30_000,
+        options.readTimeout || 30_000,
+      )
       .then((result) => {
         if (!began) {
           options.begin?.({
@@ -154,16 +155,16 @@ export const localNetworkTransport = {
 
   stopDownload(jobId: number): void {
     const nativeId = nativeJobs.get(jobId)
-    if (nativeId && MentraLocalNetwork) {
+    if (nativeId && otaLocalNetwork.isAvailable()) {
       cancelledNativeJobs.add(jobId)
-      void MentraLocalNetwork.cancel(nativeId)
+      void otaLocalNetwork.cancel(nativeId)
       return
     }
     RNFS.stopDownload(jobId)
   },
 }
 
-MentraLocalNetwork?.addListener("networkLost", () => {
+otaLocalNetwork.onNetworkLost(() => {
   scopedConnectionActive = false
   nativeJobs.clear()
 })

package/src/services/glassesClockSync.ts

@@ -2,7 +2,7 @@
  * Push phone time to glasses only when clock skew is detected (gallery sync, OTA, etc.).
  */
 
-import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import BluetoothSdk from "@mentra/bluetooth-sdk"
 import {BgTimer} from "../utils/timers"
 import {useGlassesStore} from "../stores/glasses"
 

package/src/services/otaReleaseVersion.ts

@@ -0,0 +1,22 @@
+const COORDINATED_RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-(?:dev|beta)\.[1-9]\d*)?$/
+
+type OtaReleaseVersionInput = {
+  manifestReleaseVersion?: string | null
+  manifestUrl: string
+  packagedManifestUrl?: string | null
+  packagedReleaseIdentity?: string | null
+}
+
+function validReleaseVersion(version: string | null | undefined): string | null {
+  const trimmed = version?.trim()
+  return trimmed && COORDINATED_RELEASE_VERSION.test(trimmed) ? trimmed : null
+}
+
+/** Resolve the label for the selected OTA pin, including stable promotion of exact beta OTA bytes. */
+export function resolveOtaReleaseVersion(input: OtaReleaseVersionInput): string | null {
+  const packagedRelease = validReleaseVersion(input.packagedReleaseIdentity)
+  if (packagedRelease && input.packagedManifestUrl?.trim() === input.manifestUrl.trim()) {
+    return packagedRelease
+  }
+  return validReleaseVersion(input.manifestReleaseVersion)
+}

package/src/stores/appVisibility.ts

@@ -0,0 +1,3 @@
+/** Combine registry-enforced visibility with the user's home-screen choice. */
+export const resolveHiddenStatus = (registryHidden: boolean, userHidden: boolean): boolean =>
+  registryHidden || userHidden

package/src/stores/apps.ts

@@ -25,6 +25,7 @@ import {islandNotifications} from "../services/NotificationsEmitter"
 import sttModelManager from "../services/STTModelManager"
 import {miniappLauncher} from "../services/MiniappLauncher"
 import {miniappRunningRegistry} from "../services/MiniappRunningRegistry"
+import {resolveHiddenStatus} from "./appVisibility"
 import {SETTINGS, useSettingsStore} from "./settings"
 import BluetoothSdk from "@mentra/bluetooth-sdk"
 
@@ -221,7 +222,12 @@ function projectApps(previousState: AppStatusState, localApps: ClientApp[]): Cli
       ...app,
       screenshot: previousByPackage.get(app.packageName)?.screenshot ?? app.screenshot,
       compatibility: HardwareCompatibility.checkCompatibility(app.hardwareRequirements, capabilities),
-      hidden: previousState.getHiddenStatus(app.packageName),
+      // A registry source can force an app off the primary home screen (for
+      // example, Miniapp Developer while its home-screen setting is disabled).
+      // Compose that gate with the user's persisted home-screen layout instead
+      // of replacing it, otherwise a default-false persisted value makes a
+      // source-hidden app visible again during projection.
+      hidden: resolveHiddenStatus(app.hidden, previousState.getHiddenStatus(app.packageName)),
       // Derive the foreground flag from the store's single source of truth
       // (`foregroundedPackage`), NOT from the previous snapshot. Carrying it over
       // per-app meant a refresh that momentarily omitted an app (e.g. the