@mentra/engine 0.1.0-beta.0

package/src/utils/hardware/hardware.ts

@@ -0,0 +1,166 @@
+import {
+  Capabilities,
+  HardwareRequirement,
+  HardwareType,
+  HardwareRequirementLevel,
+  DeviceTypes,
+} from "../../types"
+import {simulatedGlasses} from "../../types"
+
+/**
+ * Result of a hardware compatibility check
+ */
+export interface CompatibilityResult {
+  isCompatible: boolean
+  missingRequired: HardwareRequirement[]
+  missingOptional: HardwareRequirement[]
+  warnings: string[]
+}
+
+/**
+ * Service for checking hardware compatibility between apps and glasses
+ */
+export class HardwareCompatibility {
+  /**
+   * Check if app is compatible with given device capabilities
+   * @param app The app to check
+   * @param capabilities The device capabilities (null if no device connected)
+   * @returns Detailed compatibility result
+   */
+  static checkCompatibility(
+    hardwareRequirements: HardwareRequirement[],
+    capabilities: Capabilities | null,
+  ): CompatibilityResult {
+    const result: CompatibilityResult = {
+      isCompatible: true,
+      missingRequired: [],
+      missingOptional: [],
+      warnings: [],
+    }
+
+    // If no hardware requirements specified, app is compatible with any hardware
+    if (hardwareRequirements.length === 0) {
+      return result
+    }
+
+    // If no capabilities available assume simulated glasses:
+    if (!capabilities) {
+      capabilities = simulatedGlasses
+    }
+
+    // Check each hardware requirement
+    for (const requirement of hardwareRequirements) {
+      const hasHardware = this.checkHardwareAvailable(requirement.type, capabilities!)
+      if (!hasHardware) {
+        if (requirement.level === HardwareRequirementLevel.REQUIRED) {
+          result.missingRequired.push(requirement)
+          result.isCompatible = false
+        } else {
+          result.missingOptional.push(requirement)
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Check if specific hardware is available in capabilities
+   * @param hardwareType The type of hardware to check
+   * @param capabilities The device capabilities
+   * @returns true if hardware is available
+   */
+  private static checkHardwareAvailable(hardwareType: HardwareType, capabilities: Capabilities): boolean {
+    if (hardwareType === HardwareType.EXIST) {
+      if (capabilities.modelName === DeviceTypes.NONE) {
+        return false
+      }
+      return true
+    }
+
+    switch (hardwareType) {
+      case HardwareType.CAMERA:
+        return capabilities.hasCamera
+
+      case HardwareType.DISPLAY:
+        return capabilities.hasDisplay
+
+      case HardwareType.MICROPHONE:
+        return capabilities.hasMicrophone
+
+      case HardwareType.SPEAKER:
+        return capabilities.hasSpeaker
+
+      case HardwareType.IMU:
+        return capabilities.hasIMU
+
+      case HardwareType.BUTTON:
+        return capabilities.hasButton
+
+      case HardwareType.LIGHT:
+        return capabilities.hasLight
+
+      case HardwareType.WIFI:
+        return capabilities.hasWifi
+
+      default:
+        // Unknown hardware type - assume not available
+        return false
+    }
+  }
+
+  /**
+   * Get human-readable compatibility message
+   * @param result The compatibility check result
+   * @returns User-friendly message about compatibility
+   */
+  static getCompatibilityMessage(result: CompatibilityResult): string {
+    if (result.isCompatible) {
+      if (result.missingOptional.length > 0) {
+        const optionalHardware = result.missingOptional.map((req) => req.type.toLowerCase()).join(", ")
+        return `This app works with your glasses but has optional features that require: ${optionalHardware}`
+      }
+      return "This app is fully compatible with your glasses"
+    }
+
+    const requiredHardware = result.missingRequired.map((req) => req.type.toLowerCase()).join(", ")
+
+    if (result.missingRequired.length === 1) {
+      return `This app requires a ${requiredHardware} which is not available on your connected glasses`
+    } else {
+      return `This app requires the following hardware which is not available on your connected glasses: ${requiredHardware}`
+    }
+  }
+
+  /**
+   * Get detailed compatibility messages including descriptions
+   * @param result The compatibility check result
+   * @returns Array of detailed messages
+   */
+  static getDetailedMessages(result: CompatibilityResult): string[] {
+    const messages: string[] = []
+
+    // Add warnings first
+    messages.push(...result.warnings)
+
+    // Add missing required hardware
+    for (const req of result.missingRequired) {
+      let message = `❌ Missing required ${req.type.toLowerCase()}`
+      if (req.description) {
+        message += `: ${req.description}`
+      }
+      messages.push(message)
+    }
+
+    // Add missing optional hardware
+    for (const req of result.missingOptional) {
+      let message = `⚠️ Missing optional ${req.type.toLowerCase()}`
+      if (req.description) {
+        message += `: ${req.description}`
+      }
+      messages.push(message)
+    }
+
+    return messages
+  }
+}

package/src/utils/hardware/index.ts

@@ -0,0 +1 @@
+export * from "./hardware"

package/src/utils/miniappGlobals.ts

@@ -0,0 +1,260 @@
+/**
+ * miniappGlobals — shared builder for the window.MentraOS globals injected
+ * into every miniapp WebView (both cloud and local).
+ *
+ * Authors should be able to use one API in their miniapp code regardless of
+ * whether it's hosted in the cloud or on-device. So both injection paths
+ * (webview.tsx for cloud miniapps, MiniappHost.tsx for local miniapps) funnel
+ * through this util.
+ */
+
+import {Dimensions, Platform} from "react-native"
+
+export interface MiniappSafeArea {
+  top: number
+  bottom: number
+  left: number
+  right: number
+}
+
+export interface CapsuleMenuRect {
+  top: number
+  right: number
+  bottom: number
+  left: number
+  width: number
+  height: number
+}
+
+/**
+ * The capsule menu bounding rect in the WebView's own coordinate space.
+ *
+ * Keep in sync with CapsuleMenu.tsx:
+ *   - CapsuleButton height ≈ h-7.5 (30px), width ≈ 73px
+ *   - Positioned at right-2 (8px), top = theme.spacing.s2 (8px) below insets.top
+ */
+const CAPSULE_MENU_HEIGHT = 30
+const CAPSULE_MENU_WIDTH = 73
+const CAPSULE_MENU_PADDING = 8
+
+/**
+ * @param topInsetOffset  extra top offset to add when the WebView container does
+ *   NOT already pad by the safe-area inset (i.e. WebView fills edge-to-edge under
+ *   the status bar). Pass `insets.top` in that case, or 0 when the container
+ *   already applies top padding.
+ */
+export function getCapsuleMenuRect(topInsetOffset = 0): CapsuleMenuRect {
+  const screenWidth = Dimensions.get("window").width
+  const top = topInsetOffset + CAPSULE_MENU_PADDING
+  return {
+    top,
+    right: CAPSULE_MENU_PADDING,
+    bottom: top + CAPSULE_MENU_HEIGHT,
+    left: screenWidth - CAPSULE_MENU_PADDING - CAPSULE_MENU_WIDTH,
+    width: CAPSULE_MENU_WIDTH,
+    height: CAPSULE_MENU_HEIGHT,
+  }
+}
+
+export type MiniappColorScheme = "light" | "dark"
+
+export interface BuildMiniappGlobalsOptions {
+  packageName?: string
+  capabilities?: string[]
+  miniappLocal?: boolean
+  miniappDeveloperMode?: boolean
+  safeAreaInsets: MiniappSafeArea
+  /**
+   * True when the WebView container renders edge-to-edge (no top padding for
+   * the status bar). In that case the capsule menu rect needs to shift down by
+   * the top inset so its coords match where it's actually drawn on screen.
+   */
+  webviewFillsStatusBar?: boolean
+  /** Current host color scheme. Miniapps may follow this to match the phone. */
+  colorScheme?: MiniappColorScheme
+}
+
+/**
+ * Returns the JS string to inject into a miniapp WebView before its content
+ * loads. Sets window.MentraOS with the standard fields miniapps read:
+ *
+ *   window.MentraOS = {
+ *     platform, packageName?, capabilities, safeAreaInsets, capsuleMenu,
+ *     miniappLocal?, miniappDeveloperMode?
+ *   }
+ *
+ * Also defines a stub window.receiveNativeMessage so the miniapp can safely
+ * assign to it before the native bridge wires in.
+ */
+export function buildMiniappGlobalsScript(opts: BuildMiniappGlobalsOptions): string {
+  const capsuleTopOffset = opts.webviewFillsStatusBar ? opts.safeAreaInsets.top : 0
+  const globals: Record<string, unknown> = {
+    platform: Platform.OS,
+    capabilities: opts.capabilities ?? ["share", "open_url", "copy_clipboard", "download"],
+    safeAreaInsets: opts.safeAreaInsets,
+    capsuleMenu: getCapsuleMenuRect(capsuleTopOffset),
+  }
+  if (opts.packageName) globals.packageName = opts.packageName
+  if (opts.miniappLocal) globals.miniappLocal = true
+  if (opts.miniappDeveloperMode) globals.miniappDeveloperMode = true
+  if (opts.colorScheme) globals.colorScheme = opts.colorScheme
+
+  // CSS custom properties that mirror the capsule menu / safe-area data.
+  // Miniapp CSS (or Tailwind arbitrary values) can read these without
+  // touching JS: e.g. `style="margin-top: var(--mentra-capsule-top)"`.
+  const capsule = globals.capsuleMenu as CapsuleMenuRect
+  const insets = opts.safeAreaInsets
+  const capsuleCenter = capsule.top + capsule.height / 2
+  const cssVars: Record<string, string> = {
+    "--mentra-safe-top": `${insets.top}px`,
+    "--mentra-safe-bottom": `${insets.bottom}px`,
+    "--mentra-safe-left": `${insets.left}px`,
+    "--mentra-safe-right": `${insets.right}px`,
+    "--mentra-capsule-top": `${capsule.top}px`,
+    "--mentra-capsule-bottom": `${capsule.bottom}px`,
+    "--mentra-capsule-left": `${capsule.left}px`,
+    "--mentra-capsule-right": `${capsule.right}px`,
+    "--mentra-capsule-width": `${capsule.width}px`,
+    "--mentra-capsule-height": `${capsule.height}px`,
+    "--mentra-capsule-center-y": `${capsuleCenter}px`,
+    // Right-side gutter to reserve so content doesn't slide under the
+    // capsule: capsule width + 16px breathing room.
+    "--mentra-capsule-gutter": `${capsule.width + 16}px`,
+  }
+  const cssVarsBlock = Object.entries(cssVars)
+    .map(([k, v]) => `${k}: ${v};`)
+    .join(" ")
+
+  // Console-tap shim: wrap console.log/warn/error/info/debug so each call
+  // also forwards a `dev_log` envelope back to the phone via
+  // ReactNativeWebView.postMessage. Dev mode forwards to the laptop's
+  // `mentra-miniapp dev` terminal; non-dev mode falls back to the React
+  // Native log stream (Metro / Xcode console / adb logcat) so installed-
+  // miniapp errors are still inspectable when there's no laptop sidecar.
+  //
+  // Also tap window.onerror and window.onunhandledrejection so synchronous
+  // throws and unhandled promise rejections surface even when the bundle
+  // never gets a chance to call console.error itself.
+  const consoleTapBlock = `
+    (function() {
+      try {
+        var levels = ["log", "warn", "error", "info", "debug"];
+        var seen = new WeakSet();
+        function safeSerialize(arg) {
+          if (arg instanceof Error) return {__error: true, message: arg.message, stack: arg.stack};
+          if (arg === null || typeof arg !== "object") return arg;
+          try {
+            return JSON.parse(JSON.stringify(arg, function(k, v) {
+              if (v !== null && typeof v === "object") {
+                if (seen.has(v)) return "[Circular]";
+                seen.add(v);
+              }
+              return v;
+            }));
+          } catch (e) {
+            try { return String(arg); } catch (_) { return "[unserializable]"; }
+          }
+        }
+        levels.forEach(function(level) {
+          var original = console[level];
+          if (typeof original !== "function") return;
+          console[level] = function() {
+            try { original.apply(console, arguments); } catch (_) {}
+            try {
+              var args = Array.prototype.slice.call(arguments).map(safeSerialize);
+              if (window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === "function") {
+                window.ReactNativeWebView.postMessage(JSON.stringify({
+                  payload: {
+                    type: "dev_log",
+                    level: level,
+                    args: args,
+                    packageName: (window.MentraOS && window.MentraOS.packageName) || null,
+                    timestamp: Date.now()
+                  }
+                }));
+              }
+            } catch (_) { /* swallow */ }
+          };
+        });
+      } catch (_) { /* ignore */ }
+
+      // Surface synchronous errors and unhandled promise rejections via the
+      // same dev_log channel — many bundle-startup crashes never get to call
+      // console.error themselves.
+      try {
+        window.addEventListener("error", function(e) {
+          try {
+            if (window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === "function") {
+              window.ReactNativeWebView.postMessage(JSON.stringify({
+                payload: {
+                  type: "dev_log",
+                  level: "error",
+                  args: ["[window.error] " + (e.message || "unknown"), {filename: e.filename, lineno: e.lineno, colno: e.colno, stack: e.error && e.error.stack}],
+                  packageName: (window.MentraOS && window.MentraOS.packageName) || null,
+                  timestamp: Date.now()
+                }
+              }));
+            }
+          } catch (_) {}
+        });
+        window.addEventListener("unhandledrejection", function(e) {
+          try {
+            if (window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === "function") {
+              var reason = e.reason;
+              var serialized = reason instanceof Error
+                ? {__error: true, message: reason.message, stack: reason.stack}
+                : (typeof reason === "object" ? JSON.stringify(reason) : String(reason));
+              window.ReactNativeWebView.postMessage(JSON.stringify({
+                payload: {
+                  type: "dev_log",
+                  level: "error",
+                  args: ["[unhandledrejection]", serialized],
+                  packageName: (window.MentraOS && window.MentraOS.packageName) || null,
+                  timestamp: Date.now()
+                }
+              }));
+            }
+          } catch (_) {}
+        });
+      } catch (_) {}
+    })();
+  `
+
+  // Lock zoom so miniapps feel like apps, not pages: force a non-scalable
+  // viewport meta (overriding whatever the miniapp shipped) and disable
+  // double-tap-zoom via CSS. Re-applies on DOMContentLoaded in case the
+  // miniapp re-writes <head> during boot.
+  return `
+    window.MentraOS = ${JSON.stringify(globals)};
+    window.receiveNativeMessage = window.receiveNativeMessage || function() {};
+    (function() {
+      try {
+        var styleEl = document.createElement("style");
+        styleEl.setAttribute("data-mentra-injected", "1");
+        styleEl.textContent =
+          ":root { ${cssVarsBlock} }" +
+          "html, body { touch-action: manipulation; -ms-content-zooming: none; }";
+        (document.head || document.documentElement).appendChild(styleEl);
+      } catch (e) { /* ignore */ }
+
+      function lockViewport() {
+        try {
+          var content = "width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no, viewport-fit=cover";
+          var existing = document.querySelector('meta[name="viewport"]');
+          if (existing) {
+            existing.setAttribute("content", content);
+          } else {
+            var meta = document.createElement("meta");
+            meta.setAttribute("name", "viewport");
+            meta.setAttribute("content", content);
+            (document.head || document.documentElement).appendChild(meta);
+          }
+        } catch (e) { /* ignore */ }
+      }
+      lockViewport();
+      document.addEventListener("DOMContentLoaded", lockViewport);
+    })();
+    ${consoleTapBlock}
+    true;
+  `
+}

package/src/utils/permissions/MediaLibraryPermissions.ts

@@ -0,0 +1,161 @@
+import {Platform} from "react-native"
+import {check, request, PERMISSIONS, RESULTS} from "react-native-permissions"
+
+import CrustModule from "@mentra/crust"
+
+import {deriveGalleryDisplayName} from "./galleryDisplayName"
+
+export interface MediaLibrarySaveReceipt {
+  success: boolean
+  platform: "ios" | "android" | "unknown"
+  uri?: string
+  identifier?: string
+  error?: string
+}
+
+/**
+ * MediaLibraryPermissions - Handles save-only permissions for camera roll
+ *
+ * Platform behavior:
+ * - iOS: Uses PHOTO_LIBRARY (read-write) so we can manage the MentraOS album
+ * - Android 10+ (API 29+): No permission needed to save your own files to MediaStore
+ * - Android 9-: Uses WRITE_EXTERNAL_STORAGE (legacy)
+ */
+export class MediaLibraryPermissions {
+  /** Limited iOS access cannot see historical, unselected assets for duplicate reconciliation. */
+  static async hasLimitedAccess(): Promise<boolean> {
+    if (Platform.OS !== "ios") return false
+    try {
+      return (await check(PERMISSIONS.IOS.PHOTO_LIBRARY)) === RESULTS.LIMITED
+    } catch (error) {
+      console.error("[MediaLibrary] Error checking limited-library access:", error)
+      // Conservatively block legacy reconciliation when the scope cannot be verified.
+      return true
+    }
+  }
+
+  /**
+   * Check if we have permission to save to the camera roll
+   * Note: On Android 10+, this always returns true since no permission is needed
+   */
+  static async checkPermission(): Promise<boolean> {
+    try {
+      if (Platform.OS === "ios") {
+        const status = await check(PERMISSIONS.IOS.PHOTO_LIBRARY)
+        return status === RESULTS.GRANTED || status === RESULTS.LIMITED
+      }
+
+      if (Platform.OS === "android") {
+        // Android 10+ (API 29+): No permission needed to save your own files
+        if (Platform.Version >= 29) {
+          return true
+        }
+        // Android 9 and below: Check legacy write permission
+        const status = await check(PERMISSIONS.ANDROID.WRITE_EXTERNAL_STORAGE)
+        return status === RESULTS.GRANTED
+      }
+
+      return false
+    } catch (error) {
+      console.error("[MediaLibrary] Error checking permission:", error)
+      // On error, assume we can try (Android 10+ doesn't need permission anyway)
+      return Platform.OS === "android" && Platform.Version >= 29
+    }
+  }
+
+  /**
+   * Request permission to save to the camera roll
+   * Note: On Android 10+, this always returns true since no permission is needed
+   */
+  static async requestPermission(): Promise<boolean> {
+    try {
+      if (Platform.OS === "ios") {
+        const status = await request(PERMISSIONS.IOS.PHOTO_LIBRARY)
+        return status === RESULTS.GRANTED || status === RESULTS.LIMITED
+      }
+
+      if (Platform.OS === "android") {
+        // Android 10+ (API 29+): No permission needed to save your own files
+        if (Platform.Version >= 29) {
+          return true
+        }
+        // Android 9 and below: Request legacy write permission
+        const status = await request(PERMISSIONS.ANDROID.WRITE_EXTERNAL_STORAGE)
+        return status === RESULTS.GRANTED
+      }
+
+      return false
+    } catch (error) {
+      console.error("[MediaLibrary] Error requesting permission:", error)
+      // On error, assume we can try (Android 10+ doesn't need permission anyway)
+      return Platform.OS === "android" && Platform.Version >= 29
+    }
+  }
+
+  /**
+   * Save a file to the photo library in a glasses-specific location (MentraOS album on iOS;
+   * Pictures/MentraOS or Movies/MentraOS on Android 10+).
+   * On Android 10+, this works without any permission.
+   *
+   * IMPORTANT: This method sets the DATE_TAKEN (Android) or creation date (iOS)
+   * metadata to the original capture time, so gallery apps show the correct date.
+   * Also saves files in chronological order for proper "date added" ordering.
+   *
+   * @param filePath - Path to the file to save
+   * @param creationTime - Optional creation/capture time in milliseconds (Unix timestamp)
+   */
+  static async saveToLibrary(filePath: string, creationTime?: number): Promise<boolean> {
+    return (await this.saveToLibraryWithReceipt(filePath, creationTime)).success
+  }
+
+  /** Save and return the durable MediaStore/PhotoKit identifier used as the export receipt. */
+  static async saveToLibraryWithReceipt(filePath: string, creationTime?: number): Promise<MediaLibrarySaveReceipt> {
+    const platform = Platform.OS === "ios" || Platform.OS === "android" ? Platform.OS : "unknown"
+    try {
+      // On Android 10+, we can save without permission
+      // On iOS and older Android, check permission first
+      if (!(Platform.OS === "android" && Platform.Version >= 29)) {
+        const hasPermission = await this.checkPermission()
+        if (!hasPermission) {
+          // Try requesting permission one more time
+          const granted = await this.requestPermission()
+          if (!granted) {
+            console.warn("[MediaLibrary] No permission to save to library - photos saved to app storage only")
+            return {success: false, platform, error: "permission denied"}
+          }
+        }
+      }
+
+      // Remove file:// prefix if present
+      const cleanPath = filePath.replace("file://", "")
+      const displayName = deriveGalleryDisplayName(cleanPath)
+
+      // Use native module to save with proper DATE_TAKEN / creation date metadata
+      // This ensures gallery apps show the correct capture date, not the sync date
+      const result = await CrustModule.saveToGalleryWithDate(cleanPath, creationTime, displayName)
+
+      if (result.success) {
+        if (creationTime) {
+          const captureDate = new Date(creationTime)
+          console.log(
+            `[MediaLibrary] Saved to camera roll with DATE_TAKEN: ${cleanPath} (captured: ${captureDate.toISOString()})`,
+          )
+        } else {
+          console.log(`[MediaLibrary] Saved to camera roll: ${cleanPath}`)
+        }
+        return {
+          success: true,
+          platform,
+          uri: result.uri,
+          identifier: result.identifier,
+        }
+      } else {
+        console.error(`[MediaLibrary] Failed to save to library: ${result.error}`)
+        return {success: false, platform, error: result.error || "native export failed"}
+      }
+    } catch (error) {
+      console.error("[MediaLibrary] Error saving to library:", error)
+      return {success: false, platform, error: error instanceof Error ? error.message : String(error)}
+    }
+  }
+}

package/src/utils/permissions/galleryDisplayName.ts

@@ -0,0 +1,28 @@
+const CAPTURE_FOLDER_PATTERN = /^(IMG|VID)_/
+
+/**
+ * Derive a unique MediaStore display name for camera-roll saves.
+ *
+ * Capture downloads use folder layout `IMG_xxx/base.jpg` (or `VID_xxx/base.mp4`).
+ * Using the leaf filename (`base.jpg`) causes MediaStore collisions on Android.
+ */
+export function deriveGalleryDisplayName(filePath: string): string {
+  const cleanPath = filePath.replace("file://", "")
+  const lastSlash = cleanPath.lastIndexOf("/")
+  if (lastSlash < 0) {
+    return cleanPath
+  }
+
+  const fileName = cleanPath.substring(lastSlash + 1)
+  const parentDir = cleanPath.substring(0, lastSlash)
+  const parentSlash = parentDir.lastIndexOf("/")
+  const parentName = parentSlash < 0 ? parentDir : parentDir.substring(parentSlash + 1)
+
+  if (!CAPTURE_FOLDER_PATTERN.test(parentName)) {
+    return fileName
+  }
+
+  const isVideo = /\.(mp4|mov|m4v|avi)(\.|$)/i.test(fileName)
+  const extension = isVideo ? "mp4" : "jpg"
+  return `${parentName}.${extension}`
+}

package/src/utils/storage/index.ts

@@ -0,0 +1,2 @@
+export {storage, StorageValueNotFoundError} from "./storage"
+export {printDirectory} from "./zip"