@mentra/engine 0.1.0-dev.0 → 3.1.0-beta.100

package/src/services/otaManifestPolicy.ts

@@ -0,0 +1,42 @@
+const OTA_VERSION_URL_LEGACY_PROD = "https://ota.mentraglass.com/prod_live_version.json"
+
+function trimmed(value?: string | null): string | null {
+  const result = value?.trim()
+  return result || null
+}
+
+export function isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {
+  const buildNumber = Number.parseInt(glassesBuildNumber ?? "", 10)
+  return Number.isFinite(buildNumber) && buildNumber < 39
+}
+
+export function selectModernOtaManifestPin({
+  developerOverride,
+  hostReleasePin,
+  engineReleasePin,
+}: {
+  developerOverride?: string | null
+  hostReleasePin?: string | null
+  engineReleasePin?: string | null
+}): string | null {
+  return trimmed(developerOverride) || trimmed(hostReleasePin) || trimmed(engineReleasePin)
+}
+
+export function resolveOtaManifestPolicy({
+  glassesUrl,
+  glassesBuildNumber,
+  developerOverride,
+  hostReleasePin,
+  engineReleasePin,
+}: {
+  glassesUrl?: string | null
+  glassesBuildNumber?: string | null
+  developerOverride?: string | null
+  hostReleasePin?: string | null
+  engineReleasePin?: string | null
+}): string | null {
+  if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {
+    return trimmed(glassesUrl) || OTA_VERSION_URL_LEGACY_PROD
+  }
+  return selectModernOtaManifestPin({developerOverride, hostReleasePin, engineReleasePin})
+}

package/src/services/otaManifestUrl.ts

@@ -0,0 +1,44 @@
+import {ENGINE_RELEASE_METADATA} from "../generated/releaseMetadata"
+import {SETTINGS, useSettingsStore} from "../stores/settings"
+import {resolveOtaManifestPolicy, selectModernOtaManifestPin} from "./otaManifestPolicy"
+
+function getOtaVersionUrlDevOverride(): string | null {
+  // Super mode only: a wrong OTA manifest can brick glasses, so a saved
+  // override is inert unless super mode is currently enabled.
+  if (!useSettingsStore.getState().getSetting(SETTINGS.super_mode.key)) {
+    return null
+  }
+  const value = useSettingsStore.getState().getSetting(SETTINGS.ota_version_url.key)
+  const trimmed = typeof value === "string" ? value.trim() : ""
+  return trimmed || null
+}
+
+function getHostReleasePin(): string | null {
+  const value = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
+  return value || null
+}
+
+function getEmbeddedEngineReleasePin(): string | null {
+  const value = ENGINE_RELEASE_METADATA.otaManifestUrl?.trim()
+  return value || null
+}
+
+export function hasConfiguredModernOtaManifestPin(): boolean {
+  return Boolean(
+    selectModernOtaManifestPin({
+      developerOverride: getOtaVersionUrlDevOverride(),
+      hostReleasePin: getHostReleasePin(),
+      engineReleasePin: getEmbeddedEngineReleasePin(),
+    }),
+  )
+}
+
+export function resolveOtaManifestUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string | null {
+  return resolveOtaManifestPolicy({
+    glassesUrl,
+    glassesBuildNumber,
+    developerOverride: getOtaVersionUrlDevOverride(),
+    hostReleasePin: getHostReleasePin(),
+    engineReleasePin: getEmbeddedEngineReleasePin(),
+  })
+}

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/services/slimStreamStatus.ts

@@ -1,10 +1,22 @@
 import type {StreamStatusEvent} from "@mentra/bluetooth-sdk/internal"
 
+/**
+ * 1Hz encoder FPS/bitrate telemetry on `stream_status.stats`.
+ * Lifecycle status (started/stopped/error) is unaffected.
+ * Keep false in production; flip locally to debug the Mentra Call FPS ladder.
+ *
+ * Compatibility kill switch: old glasses can still emit stats. Copy onto a new object;
+ * never mutate the incoming event. Manual acceptance with every layer false: join
+ * waterfall yes; BLE stream_status.stats / STREAM_QUALITY / encoder-stats / watch-stats no.
+ */
+export const ENABLE_PIPELINE_FPS_TELEMETRY = false
+
 /** Fields forwarded to cloud / miniapps after the first resolvedConfig ack. */
 export function slimStreamStatusEvent(
   event: StreamStatusEvent,
-  options: {includeResolvedConfig?: boolean} = {},
+  options: {includeResolvedConfig?: boolean; enableFpsTelemetry?: boolean} = {},
 ): Record<string, unknown> {
+  const enableFpsTelemetry = options.enableFpsTelemetry ?? ENABLE_PIPELINE_FPS_TELEMETRY
   const slim: Record<string, unknown> = {
     type: "stream_status",
     kind: event.kind,
@@ -16,10 +28,9 @@ export function slimStreamStatusEvent(
   if (options.includeResolvedConfig && event.resolvedConfig) {
     slim.resolvedConfig = event.resolvedConfig
   }
-  // Live telemetry passes straight through — unlike resolvedConfig it changes
-  // per event, and the signature dedupe upstream only suppresses identical
-  // payloads.
-  if (event.stats) slim.stats = event.stats
+  // Compatibility kill switch: old glasses may still emit 1Hz stats. Copy onto a
+  // new object; never mutate `event` — other consumers may still need the original.
+  if (enableFpsTelemetry && event.stats) slim.stats = event.stats
   return slim
 }
 

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

@@ -20,10 +20,12 @@ import {getModelCapabilities} from "../types/hardware"
 import {HardwareCompatibility, type CompatibilityResult} from "../utils/hardware/hardware"
 import {storage} from "../utils/storage/storage"
 import appRegistry from "../services/AppRegistry"
+import localDisplayManager from "../services/LocalDisplayManager"
 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"
 
@@ -220,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
@@ -540,6 +547,17 @@ miniappRunningRegistry.subscribe(() => {
   }
 })
 
+// The display-manager's core (foreground) slot is DERIVED state: always the
+// currently-running standard app, no matter HOW it came to run — user tap
+// (start()), boot restore (autostartLocalMiniapps → registry projection
+// above), crash-respawn, or interop. One reconciler instead of per-path call
+// sites, so no launch/stop path can forget to claim or release the slot.
+// onCoreAppChange is idempotent, so firing on every store write is free.
+useAppStatusStore.subscribe((state) => {
+  const core = state.apps.find((a) => a.running && (a.type === "standard" || !a.type))
+  localDisplayManager.onCoreAppChange(core?.packageName ?? null)
+})
+
 // AppRegistry change events trigger a store refresh.
 appRegistry.subscribe(() => {
   void useAppStatusStore.getState().refresh()

package/src/stores/bluetoothSettingKeys.ts

@@ -5,6 +5,8 @@ export const MENTRA_LIVE_SETTING_KEYS: string[] = [
   "sensing_enabled",
   "lc3_frame_size",
   "preferred_mic",
+  "voice_activity_detection_enabled",
+  "loudness_gate_enabled",
   "core_token",
   "auth_email",
   "button_photo_size",

package/src/stores/core.ts

@@ -1,13 +1,13 @@
 import {create} from "zustand"
 import {subscribeWithSelector} from "zustand/middleware"
-import type {BluetoothStatus} from "@mentra/bluetooth-sdk/internal"
+import type {PublicBluetoothStatus} from "@mentra/bluetooth-sdk"
 
-export interface CoreState extends BluetoothStatus {
-  setCoreInfo: (info: Partial<BluetoothStatus>) => void
+export interface CoreState extends PublicBluetoothStatus {
+  setCoreInfo: (info: Partial<PublicBluetoothStatus>) => void
   reset: () => void
 }
 
-const initialState: BluetoothStatus = {
+const initialState: PublicBluetoothStatus = {
   // state:
   searching: false,
   searchingController: false,

package/src/stores/gallerySync.ts

@@ -53,6 +53,7 @@ export interface SyncQueue {
 export interface GallerySyncInfo {
   // State machine
   syncState: SyncState
+  syncStarting: boolean
 
   // Progress tracking
   currentFile: string | null
@@ -82,6 +83,7 @@ export interface GallerySyncInfo {
 export interface GallerySyncState extends GallerySyncInfo {
   // State transitions
   setSyncState: (state: SyncState) => void
+  setSyncStarting: (starting: boolean) => void
   setRequestingHotspot: () => void
   setConnectingWifi: () => void
   setSyncing: (files: PhotoInfo[]) => void
@@ -122,6 +124,7 @@ export interface GallerySyncState extends GallerySyncInfo {
 
 const initialState: GallerySyncInfo & {processingFiles: Set<string>; processedFiles: number} = {
   syncState: "idle",
+  syncStarting: false,
   currentFile: null,
   currentFileProgress: 0,
   completedFiles: 0,
@@ -146,6 +149,7 @@ export const useGallerySyncStore = create<GallerySyncState>()(
 
     // State transitions
     setSyncState: (syncState: SyncState) => set({syncState}),
+    setSyncStarting: (syncStarting: boolean) => set({syncStarting}),
 
     setRequestingHotspot: () =>
       set({

package/src/stores/glasses.ts

@@ -1,12 +1,12 @@
 import type {
   GlassesConnectionStatus,
-  GlassesStatus,
   HotspotStatus,
   OtaProgress,
   OtaStatus,
   OtaUpdateInfo,
+  PublicGlassesStatus,
   WifiStatus,
-} from "@mentra/bluetooth-sdk/internal"
+} from "@mentra/bluetooth-sdk"
 import {isGlassesConnected, isGlassesLinkLayerBusy, isGlassesReady} from "../services/GlassesReadiness"
 import {create} from "zustand"
 import {subscribeWithSelector} from "zustand/middleware"
@@ -20,7 +20,14 @@ export const selectGlassesConnected = (state: {connection: GlassesConnectionStat
 
 export const selectGlassesReady = (state: {connection: GlassesConnectionStatus}) => isGlassesReady(state.connection)
 
-export interface GlassesState extends GlassesStatus {
+type EngineGlassesStatus = PublicGlassesStatus & {
+  otaUpdateAvailable: OtaUpdateInfo | null
+  otaProgress: OtaProgress | null
+  otaInProgress: boolean
+  otaVersionUrl: string
+}
+
+export interface GlassesState extends EngineGlassesStatus {
   systemTimeMs: number
   wifiStatusKnown: boolean
   setGlassesInfo: (info: GlassesInfoUpdate) => void
@@ -53,7 +60,7 @@ type LegacyHotspotFields = {
   hotspotLocalIp?: string
 }
 
-type GlassesInfoUpdate = Partial<GlassesStatus> & LegacyWifiFields & LegacyHotspotFields
+type GlassesInfoUpdate = Partial<EngineGlassesStatus> & LegacyWifiFields & LegacyHotspotFields
 
 function wifiFromLegacyFields(info: LegacyWifiFields): WifiStatus | null {
   if (info.wifiConnected === true) {
@@ -80,7 +87,7 @@ function hotspotFromLegacyFields(info: LegacyHotspotFields): HotspotStatus | nul
   return null
 }
 
-export const getGlasesInfoPartial = (state: GlassesStatus) => {
+export const getGlasesInfoPartial = (state: EngineGlassesStatus) => {
   const wifi = state.wifi
   const connected = isGlassesConnected(state.connection)
   return {
@@ -98,7 +105,7 @@ export const getGlasesInfoPartial = (state: GlassesStatus) => {
   }
 }
 
-interface GlassesStore extends GlassesStatus {
+interface GlassesStore extends EngineGlassesStatus {
   systemTimeMs: number
   mtkUpdatedThisSession: boolean
   wifiStatusKnown: boolean
@@ -118,6 +125,7 @@ const initialState: GlassesStore = {
   androidVersion: "",
   firmwareVersion: "",
   bluetoothMacAddress: "",
+  wifiMacAddress: "",
   leftMacAddress: "",
   rightMacAddress: "",
   buildNumber: "",
@@ -130,6 +138,7 @@ const initialState: GlassesStore = {
   color: "",
   mtkFirmwareVersion: "",
   besFirmwareVersion: "",
+  hotspotOtaVersion: 0,
   // wifi info
   wifi: {state: "disconnected"},
   wifiStatusKnown: false,
@@ -193,6 +202,7 @@ export const useGlassesStore = create<GlassesState>()(
         }
         if (!isGlassesConnected(next.connection)) {
           next.wifiStatusKnown = false
+          next.hotspotOtaVersion = 0
         }
         return next
       }),