@mentra/engine 0.1.0-dev.0 → 0.1.0-dev.1

package/src/utils/timers/timers.ts

@@ -1,6 +1,28 @@
-// until https://github.com/tconns/react-native-nitro-bg-timer/issues/2 is resolved, we need to use this class to disable this package on iOS:
-
-import {Platform} from "react-native"
+// BgTimer — background-safe timers for the engine.
+//
+// Everything timing-critical in the engine runs through this class: the
+// miniapp liveness watchdog, display durationMs expiries, boot windows,
+// auth-token refresh. On Android, React Native PAUSES plain JS timers while
+// the app is backgrounded, so those features only keep working in the
+// background when the native implementation (react-native-nitro-bg-timer)
+// is active.
+//
+// Who actually gets native timers:
+//   - Android, dev AND release: always attempted — dev must match production
+//     background behavior. There is no opt-in/opt-out env var. If the native
+//     module is unavailable (a dev client whose binary predates it, or a
+//     broken release binary), the failure is LOUD: a console.error with the
+//     remediation, plus a blocking dev alert. The JS-timer fallback still
+//     engages so foreground behavior keeps working, but backgrounded
+//     behavior is broken until the native rebuild — the error says exactly
+//     that. (A silent dev fallback previously cost a full debugging day of
+//     phantom "zombie miniapp" bugs; see OS-1790.)
+//   - iOS: never, dev or prod — the package is disabled pending
+//     https://github.com/tconns/react-native-nitro-bg-timer/issues/2. iOS
+//     suspends the whole process in background anyway, so background timing
+//     there is handled by native per-device queues, not JS timers.
+
+import {Alert, Platform} from "react-native"
 
 type NitroTimerApi = {
   setInterval: (callback: () => void, delay: number) => number
@@ -11,14 +33,36 @@ type NitroTimerApi = {
 
 let nitroTimer: NitroTimerApi | null | undefined
 let nitroDisabled = false
-let warnedUnavailable = false
-
-function warnUnavailable(reason: string) {
-  if (warnedUnavailable) {
+let failedLoud = false
+
+/**
+ * The native background timer is unavailable — say so ONCE, loudly, with the
+ * remediation. The JS-timer fallback keeps foreground behavior working, but
+ * everything timing-driven freezes while the app is backgrounded, which
+ * presents as phantom miniapp bugs (frozen captions, missed wake words,
+ * watchdog kills on resume). A quiet warning here has already cost a full
+ * debugging day; never downgrade this to console.warn.
+ */
+function failUnavailable(reason: string) {
+  if (failedLoud) {
     return
   }
-  warnedUnavailable = true
-  console.warn(`BgTimer: ${reason}, using JS timers`)
+  failedLoud = true
+  const message =
+    `BgTimer: native background timer unavailable (${reason}). ` +
+    "Backgrounded behavior IS BROKEN until you rebuild the Android app: run `bun android`. " +
+    "Engine timers and local miniapps (captions, wake words) freeze whenever the app is not foregrounded."
+  console.error(message)
+  if (__DEV__) {
+    // A stale dev client may ALSO show the library's own require-time red box
+    // (bridgeless LogBox surfaces it even though we catch below) — this alert
+    // is the actionable one: it names the fix.
+    try {
+      Alert.alert("Background timers unavailable", message)
+    } catch {
+      /* Alert not available (tests / headless) — the console.error stands. */
+    }
+  }
 }
 
 function getNitroTimer(): NitroTimerApi | null {
@@ -26,15 +70,6 @@ function getNitroTimer(): NitroTimerApi | null {
     return null
   }
 
-  // react-native-nitro-bg-timer calls createHybridObject() at require() time. On dev
-  // builds with a stale native binary that throws NPE, React Native still surfaces a
-  // red LogBox error even when the exception is caught. Skip nitro in __DEV__ unless
-  // explicitly enabled after a native rebuild (bun android).
-  if (__DEV__ && process.env.EXPO_PUBLIC_USE_NITRO_BG_TIMER !== "true") {
-    warnUnavailable("nitro bg-timer disabled in dev (set EXPO_PUBLIC_USE_NITRO_BG_TIMER=true after native rebuild)")
-    return null
-  }
-
   if (nitroTimer !== undefined) {
     return nitroTimer
   }
@@ -43,7 +78,7 @@ function getNitroTimer(): NitroTimerApi | null {
     const {isRuntimeAlive} = require("react-native-nitro-modules") as {isRuntimeAlive?: () => boolean}
     if (typeof isRuntimeAlive === "function" && !isRuntimeAlive()) {
       nitroTimer = null
-      warnUnavailable("nitro runtime is not alive")
+      failUnavailable("nitro runtime is not alive")
       return nitroTimer
     }
 
@@ -62,7 +97,7 @@ function getNitroTimer(): NitroTimerApi | null {
   }
 
   if (!nitroTimer) {
-    warnUnavailable("react-native-nitro-bg-timer unavailable")
+    failUnavailable("react-native-nitro-bg-timer failed to load")
   }
   return nitroTimer
 }
@@ -77,7 +112,8 @@ function withNitro<T>(run: (api: NitroTimerApi) => T, fallback: () => T): T {
   } catch (error) {
     nitroDisabled = true
     nitroTimer = null
-    console.warn("BgTimer: nitro timer failed, using JS timers", error)
+    failedLoud = false // a mid-session failure is new information — re-announce
+    failUnavailable(`nitro timer call threw: ${String(error)}`)
     return fallback()
   }
 }

package/build/services/asgOtaVersionUrl.d.ts

@@ -1,2 +0,0 @@
-export declare function getAsgOtaVersionUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string;
-//# sourceMappingURL=asgOtaVersionUrl.d.ts.map

package/build/services/asgOtaVersionUrl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asgOtaVersionUrl.d.ts","sourceRoot":"","sources":["../../src/services/asgOtaVersionUrl.ts"],"names":[],"mappings":"AAsBA,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAkB1G"}

package/build/services/asgOtaVersionUrl.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"asgOtaVersionUrl.js","sourceRoot":"","sources":["../../src/services/asgOtaVersionUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAE,gBAAgB,EAAC,MAAM,oBAAoB,CAAA;AAE7D,MAAM,oBAAoB,GAAG,oDAAoD,CAAA;AAEjF,SAAS,wBAAwB,CAAC,kBAAkC;IAClE,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,kBAAkB,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IACjE,4EAA4E;IAC5E,kCAAkC;IAClC,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,EAAE,CAAA;AACzD,CAAC;AAED,SAAS,2BAA2B;IAClC,sEAAsE;IACtE,4DAA4D;IAC5D,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC,CAAA;IAClF,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7D,OAAO,OAAO,IAAI,IAAI,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAA0B,EAAE,kBAAkC;IAChG,MAAM,SAAS,GAAG,UAAU,EAAE,IAAI,EAAE,CAAA;IACpC,IAAI,wBAAwB,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACjD,yEAAyE;QACzE,6EAA6E;QAC7E,OAAO,SAAS,IAAI,oBAAoB,CAAA;IAC1C,CAAC;IAED,MAAM,cAAc,GAAG,2BAA2B,EAAE,CAAA;IACpD,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,+BAA+B,EAAE,IAAI,EAAE,CAAA;IAClE,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,SAAS,IAAI,oBAAoB,CAAA;AAC1C,CAAC","sourcesContent":["import {SETTINGS, useSettingsStore} from \"../stores/settings\"\n\nconst OTA_VERSION_URL_PROD = \"https://ota.mentraglass.com/prod_live_version.json\"\n\nfunction isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {\n  const buildNumber = Number.parseInt(glassesBuildNumber ?? \"\", 10)\n  // ASG builds before 39 ignore ota_start.ota_version_url, so compare against\n  // the URL they will actually use.\n  return Number.isFinite(buildNumber) && buildNumber < 39\n}\n\nfunction getOtaVersionUrlDevOverride(): string | null {\n  // Super mode only: a wrong OTA manifest can brick glasses, so a saved\n  // override is inert unless super mode is currently enabled.\n  if (!useSettingsStore.getState().getSetting(SETTINGS.super_mode.key)) {\n    return null\n  }\n  const value = useSettingsStore.getState().getSetting(SETTINGS.ota_version_url.key)\n  const trimmed = typeof value === \"string\" ? value.trim() : \"\"\n  return trimmed || null\n}\n\nexport function getAsgOtaVersionUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string {\n  const deviceUrl = glassesUrl?.trim()\n  if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {\n    // Legacy glasses ignore ota_start.ota_version_url and install from their\n    // compiled default, so the developer override does not apply to them either.\n    return deviceUrl || OTA_VERSION_URL_PROD\n  }\n\n  const devOverrideUrl = getOtaVersionUrlDevOverride()\n  if (devOverrideUrl) {\n    return devOverrideUrl\n  }\n\n  const envUrl = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()\n  if (envUrl) {\n    return envUrl\n  }\n  return deviceUrl || OTA_VERSION_URL_PROD\n}\n"]}