@mentra/engine 0.1.0-beta.0

package/src/stores/connection.ts

@@ -0,0 +1,69 @@
+import {create} from "zustand"
+
+// Relocated from the host @/services/ws-types so this store is self-contained
+// inside engine. Its writer (the host WebSocketManager) was deleted in the
+// Cloud V1 ripout; the store survives only for the engine-side legacy-surface
+// removal (issue #3392).
+export enum WebSocketStatus {
+  DISCONNECTED = "disconnected",
+  CONNECTING = "connecting",
+  CONNECTED = "connected",
+  ERROR = "error",
+}
+
+export interface ConnectionState {
+  status: WebSocketStatus
+  url: string | null
+  error: string | null
+  lastConnectedAt: Date | null
+  lastDisconnectedAt: Date | null
+  reconnectAttempts: number
+
+  setStatus: (status: WebSocketStatus) => void
+  setUrl: (url: string | null) => void
+  setError: (error: string | null) => void
+  incrementReconnectAttempts: () => void
+  resetReconnectAttempts: () => void
+  reset: () => void
+}
+
+export const useConnectionStore = create<ConnectionState>((set) => ({
+  status: WebSocketStatus.DISCONNECTED,
+  url: null,
+  error: null,
+  lastConnectedAt: null,
+  lastDisconnectedAt: null,
+  reconnectAttempts: 0,
+
+  setStatus: (status) =>
+    set((state) => ({
+      status,
+      error: status === WebSocketStatus.ERROR ? state.error : null,
+      lastConnectedAt: status === WebSocketStatus.CONNECTED ? new Date() : state.lastConnectedAt,
+      lastDisconnectedAt:
+        status === WebSocketStatus.DISCONNECTED || status === WebSocketStatus.ERROR
+          ? new Date()
+          : state.lastDisconnectedAt,
+    })),
+
+  setUrl: (url) => set({url}),
+
+  setError: (error) => set({error, status: WebSocketStatus.ERROR, lastDisconnectedAt: new Date()}),
+
+  incrementReconnectAttempts: () =>
+    set((state) => ({
+      reconnectAttempts: state.reconnectAttempts + 1,
+    })),
+
+  resetReconnectAttempts: () => set({reconnectAttempts: 0}),
+
+  reset: () =>
+    set({
+      status: WebSocketStatus.DISCONNECTED,
+      url: null,
+      error: null,
+      lastConnectedAt: null,
+      lastDisconnectedAt: null,
+      reconnectAttempts: 0,
+    }),
+}))

package/src/stores/core.ts

@@ -0,0 +1,32 @@
+import {create} from "zustand"
+import {subscribeWithSelector} from "zustand/middleware"
+import type {BluetoothStatus} from "@mentra/bluetooth-sdk/internal"
+
+export interface CoreState extends BluetoothStatus {
+  setCoreInfo: (info: Partial<BluetoothStatus>) => void
+  reset: () => void
+}
+
+const initialState: BluetoothStatus = {
+  // state:
+  searching: false,
+  searchingController: false,
+  micRanking: ["glasses", "phone", "bluetooth", "bluetoothClassic"],
+  systemMicUnavailable: false,
+  currentMic: null,
+  searchResults: [],
+  wifiScanResults: [],
+  lastLog: [],
+  otherBtConnected: false,
+  galleryModeEnabled: true,
+}
+
+export const useCoreStore = create<CoreState>()(
+  subscribeWithSelector((set) => ({
+    ...initialState,
+
+    setCoreInfo: (info) => set((state) => ({...state, ...info})),
+
+    reset: () => set(initialState),
+  })),
+)

package/src/stores/display.ts

@@ -0,0 +1,121 @@
+import {create} from "zustand"
+import {subscribeWithSelector} from "zustand/middleware"
+
+import {BgTimer} from "../utils/timers"
+import {logE2EMetric} from "../utils/e2eMetrics"
+
+function extractDisplayText(displayEvent: any): string[] {
+  const layout = displayEvent?.layout
+  if (!layout || typeof layout !== "object") {
+    return []
+  }
+  switch (layout.layoutType) {
+    case "text_wall":
+    case "text_line":
+      return typeof layout.text === "string" ? layout.text.split("\n") : []
+    case "double_text_wall":
+      return [layout.topText, layout.bottomText].filter((value): value is string => typeof value === "string")
+    case "text_rows":
+      return Array.isArray(layout.text)
+        ? layout.text.filter((value: unknown): value is string => typeof value === "string")
+        : []
+    default:
+      return []
+  }
+}
+
+/** Coalesce rapid caption updates (~3.3 Hz) into one store write per window. */
+const DISPLAY_COALESCE_MS = 150
+
+type DisplayEvent = Record<string, unknown> & {view?: string}
+
+function applyDisplayEvent(
+  set: (partial: Partial<DisplayStore>) => void,
+  get: () => DisplayStore,
+  event: DisplayEvent,
+) {
+  const currentView = get().view
+  const targetBucket = event.view === "dashboard" ? "dashboardEvent" : "mainEvent"
+
+  const updates: Partial<DisplayStore> = {
+    [targetBucket]: event,
+  }
+
+  // also update the current event if the view is the same:
+  if (event.view === currentView) {
+    updates.currentEvent = event
+  }
+
+  const visibleEvent = (updates.currentEvent ?? event) as DisplayEvent
+  const textLines = extractDisplayText(visibleEvent)
+  if (textLines.some((line) => line.trim() !== "")) {
+    logE2EMetric("display_store_update", {
+      view: visibleEvent.view ?? currentView,
+      layout_type: (visibleEvent.layout as {layoutType?: string} | undefined)?.layoutType ?? "",
+      text_lines: textLines,
+    })
+  }
+
+  set(updates)
+}
+
+export interface DisplayStore {
+  currentEvent: any
+  dashboardEvent: any
+  mainEvent: any
+  setDisplayEvent: (event: DisplayEvent | string) => void
+  view: string
+  setView: (view: string) => void
+}
+
+let pendingDisplayEvent: DisplayEvent | null = null
+let displayCoalesceTimer: ReturnType<typeof BgTimer.setTimeout> | null = null
+
+export const useDisplayStore = create<DisplayStore>()(
+  subscribeWithSelector((set, get) => ({
+    currentEvent: {} as any,
+    dashboardEvent: {} as any,
+    mainEvent: {} as any,
+    view: "main",
+    setDisplayEvent: (event: DisplayEvent | string) => {
+      const parsed: DisplayEvent = typeof event === "string" ? JSON.parse(event) : event
+      pendingDisplayEvent = parsed
+      if (displayCoalesceTimer) return
+      displayCoalesceTimer = BgTimer.setTimeout(() => {
+        displayCoalesceTimer = null
+        const next = pendingDisplayEvent
+        pendingDisplayEvent = null
+        if (next) applyDisplayEvent(set, get, next)
+      }, DISPLAY_COALESCE_MS)
+    },
+    setView: (view: string) => {
+      const currentView = get().view
+      if (view === currentView) {
+        return
+      }
+
+      // update the view and the currentEvent with the corresponding event:
+      let newEvent
+      if (view === "dashboard") {
+        newEvent = get().dashboardEvent
+      } else {
+        newEvent = get().mainEvent
+      }
+      logE2EMetric("display_view_changed", {view})
+      set({view, currentEvent: newEvent})
+    },
+  })),
+)
+
+/** Test helper — flush any pending coalesced display update immediately. */
+export function flushDisplayCoalesceForTests(): void {
+  if (displayCoalesceTimer) {
+    BgTimer.clearTimeout(displayCoalesceTimer)
+    displayCoalesceTimer = null
+  }
+  if (pendingDisplayEvent) {
+    const event = pendingDisplayEvent
+    pendingDisplayEvent = null
+    applyDisplayEvent(useDisplayStore.setState, useDisplayStore.getState, event)
+  }
+}

package/src/stores/gallerySync.ts

@@ -0,0 +1,380 @@
+/**
+ * Gallery Sync Store
+ * Manages gallery sync state independently of UI lifecycle
+ */
+
+import {create} from "zustand"
+import {subscribeWithSelector} from "zustand/middleware"
+
+// Relocated from the host @/types/asg so this store is self-contained inside
+// engine. The host barrel re-exports this (a shim), so its importers are unchanged.
+export interface PhotoInfo {
+  name: string
+  url: string
+  download: string
+  size: number
+  modified: string | number // Unix timestamp (milliseconds) - can be string or number from API
+  mime_type?: string
+  is_video?: boolean
+  thumbnail_data?: string
+  downloaded_at?: number
+  // Video duration in milliseconds (from glasses sync response)
+  duration?: number
+  // New fields for filesystem storage
+  filePath?: string
+  thumbnailPath?: string
+  // Glasses model that captured this media
+  glassesModel?: string
+}
+
+// Sync state machine states
+export type SyncState =
+  | "idle"
+  | "requesting_hotspot"
+  | "connecting_wifi"
+  | "syncing"
+  | "complete"
+  | "error"
+  | "cancelled"
+
+export interface HotspotInfo {
+  ssid: string
+  password: string
+  ip: string
+}
+
+export interface SyncQueue {
+  files: PhotoInfo[]
+  currentIndex: number
+  startedAt: number
+  hotspotInfo: HotspotInfo
+}
+
+export interface GallerySyncInfo {
+  // State machine
+  syncState: SyncState
+
+  // Progress tracking
+  currentFile: string | null
+  currentFileProgress: number // 0-100
+  completedFiles: number
+  totalFiles: number
+  failedFiles: string[]
+
+  // Queue (persisted separately via localStorageService)
+  queue: PhotoInfo[]
+  queueIndex: number
+
+  // Hotspot info
+  hotspotInfo: HotspotInfo | null
+  syncServiceOpenedHotspot: boolean
+
+  // Gallery status from glasses
+  glassesPhotoCount: number
+  glassesVideoCount: number
+  glassesTotalCount: number
+  glassesHasContent: boolean
+
+  // Error tracking
+  lastError: string | null
+}
+
+export interface GallerySyncState extends GallerySyncInfo {
+  // State transitions
+  setSyncState: (state: SyncState) => void
+  setRequestingHotspot: () => void
+  setConnectingWifi: () => void
+  setSyncing: (files: PhotoInfo[]) => void
+  setSyncComplete: () => void
+  setSyncError: (error: string) => void
+  setSyncCancelled: () => void
+
+  // Progress updates
+  setCurrentFile: (fileName: string | null, progress: number) => void
+  onFileProgress: (fileName: string, progress: number) => void
+  onFileComplete: (fileName: string) => void
+  onFileFailed: (fileName: string, error?: string) => void
+  onFileProcessing: (fileName: string) => void
+  onFileProcessed: (fileName: string) => void
+  updateFileInQueue: (fileName: string, updatedFile: PhotoInfo) => void
+  removeFilesFromQueue: (fileNames: string[]) => void
+
+  // Processing queue tracking
+  processingFiles: Set<string>
+  processedFiles: number
+
+  // Hotspot management
+  setHotspotInfo: (info: HotspotInfo | null) => void
+  setSyncServiceOpenedHotspot: (opened: boolean) => void
+
+  // Gallery status from glasses
+  setGlassesGalleryStatus: (photos: number, videos: number, total: number, hasContent: boolean) => void
+  clearGlassesGalleryStatus: () => void
+
+  // Queue management (for resume)
+  setQueue: (files: PhotoInfo[], startIndex?: number) => void
+  advanceQueue: () => void
+  clearQueue: () => void
+
+  // Full reset
+  reset: () => void
+}
+
+const initialState: GallerySyncInfo & {processingFiles: Set<string>; processedFiles: number} = {
+  syncState: "idle",
+  currentFile: null,
+  currentFileProgress: 0,
+  completedFiles: 0,
+  totalFiles: 0,
+  failedFiles: [],
+  queue: [],
+  queueIndex: 0,
+  hotspotInfo: null,
+  syncServiceOpenedHotspot: false,
+  glassesPhotoCount: 0,
+  glassesVideoCount: 0,
+  glassesTotalCount: 0,
+  glassesHasContent: false,
+  lastError: null,
+  processingFiles: new Set<string>(),
+  processedFiles: 0,
+}
+
+export const useGallerySyncStore = create<GallerySyncState>()(
+  subscribeWithSelector((set, get) => ({
+    ...initialState,
+
+    // State transitions
+    setSyncState: (syncState: SyncState) => set({syncState}),
+
+    setRequestingHotspot: () =>
+      set({
+        syncState: "requesting_hotspot",
+        lastError: null,
+        failedFiles: [],
+      }),
+
+    setConnectingWifi: () =>
+      set({
+        syncState: "connecting_wifi",
+      }),
+
+    setSyncing: (files: PhotoInfo[]) =>
+      set({
+        syncState: "syncing",
+        // C4: Strip thumbnail_data (base64) from store to prevent OOM
+        queue: files.map(({thumbnail_data: _thumbnailData, ...rest}) => rest),
+        queueIndex: 0,
+        totalFiles: files.length,
+        completedFiles: 0,
+        currentFile: files.length > 0 ? files[0].name : null,
+        currentFileProgress: 0,
+        failedFiles: [],
+        lastError: null,
+        processedFiles: 0,
+        processingFiles: new Set<string>(),
+      }),
+
+    setSyncComplete: () =>
+      set({
+        syncState: "complete",
+        currentFile: null,
+        currentFileProgress: 0,
+        // Keep queue intact so photos remain visible after sync
+        // Don't clear: queue: [], queueIndex: 0
+      }),
+
+    setSyncError: (error: string) =>
+      set({
+        syncState: "error",
+        lastError: error,
+        currentFile: null,
+        currentFileProgress: 0,
+      }),
+
+    setSyncCancelled: () =>
+      set({
+        syncState: "cancelled",
+        currentFile: null,
+        currentFileProgress: 0,
+        queue: [],
+        queueIndex: 0,
+      }),
+
+    // Progress updates
+    setCurrentFile: (fileName: string | null, progress: number) =>
+      set({
+        currentFile: fileName,
+        currentFileProgress: Math.max(0, Math.min(100, progress)),
+      }),
+
+    onFileProgress: (fileName: string, progress: number) => {
+      const state = get()
+      const clampedProgress = Math.max(0, Math.min(100, progress))
+      // Throttle: skip update if same file and same percentage (prevents Zustand flood)
+      if (clampedProgress === state.currentFileProgress && fileName === state.currentFile) {
+        return
+      }
+      set({
+        currentFile: fileName,
+        currentFileProgress: clampedProgress,
+      })
+    },
+
+    onFileComplete: (_fileName: string) => {
+      const state = get()
+      const newCompletedFiles = state.completedFiles + 1
+      const newQueueIndex = state.queueIndex + 1
+      const nextFile = state.queue[newQueueIndex]
+
+      set({
+        completedFiles: newCompletedFiles,
+        queueIndex: newQueueIndex,
+        currentFile: nextFile?.name || null,
+        currentFileProgress: 0,
+      })
+    },
+
+    onFileFailed: (fileName: string, _error?: string) => {
+      const state = get()
+      const newQueueIndex = state.queueIndex + 1
+      const nextFile = state.queue[newQueueIndex]
+
+      set({
+        failedFiles: [...state.failedFiles, fileName],
+        queueIndex: newQueueIndex,
+        currentFile: nextFile?.name || null,
+        currentFileProgress: 0,
+      })
+    },
+
+    onFileProcessing: (fileName: string) => {
+      const state = get()
+      const newSet = new Set(state.processingFiles)
+      newSet.add(fileName)
+      set({processingFiles: newSet})
+    },
+
+    onFileProcessed: (fileName: string) => {
+      const state = get()
+      const newSet = new Set(state.processingFiles)
+      newSet.delete(fileName)
+      set({processingFiles: newSet, processedFiles: state.processedFiles + 1})
+    },
+
+    updateFileInQueue: (fileName: string, updatedFile: PhotoInfo) => {
+      const state = get()
+      const updatedQueue = state.queue.map((file) => (file.name === fileName ? updatedFile : file))
+      set({queue: updatedQueue})
+    },
+
+    removeFilesFromQueue: (fileNames: string[]) => {
+      if (fileNames.length === 0) return
+
+      const filesToRemove = new Set(fileNames)
+      const state = get()
+      const failedFilesSet = new Set(state.failedFiles)
+      const filesBeforeQueueIndex = state.queue
+        .slice(0, state.queueIndex)
+        .filter((file) => filesToRemove.has(file.name))
+      const removedBeforeQueueIndex = filesBeforeQueueIndex.length
+      const removedCompletedBeforeQueueIndex = filesBeforeQueueIndex.filter(
+        (file) => !failedFilesSet.has(file.name),
+      ).length
+      const filteredQueue = state.queue.filter((file) => !filesToRemove.has(file.name))
+      const removedCount = state.queue.length - filteredQueue.length
+
+      if (removedCount === 0) return
+
+      const nextQueueIndex = state.queueIndex - removedBeforeQueueIndex
+      const currentFileRemoved = state.currentFile !== null && filesToRemove.has(state.currentFile)
+
+      set({
+        queue: filteredQueue,
+        totalFiles: state.totalFiles - removedCount,
+        completedFiles: Math.max(0, state.completedFiles - removedCompletedBeforeQueueIndex),
+        queueIndex: nextQueueIndex,
+        failedFiles: state.failedFiles.filter((fileName) => !filesToRemove.has(fileName)),
+        processingFiles: new Set(Array.from(state.processingFiles).filter((fileName) => !filesToRemove.has(fileName))),
+        currentFile: currentFileRemoved ? filteredQueue[nextQueueIndex]?.name || null : state.currentFile,
+      })
+    },
+
+    // Hotspot management
+    setHotspotInfo: (info: HotspotInfo | null) => set({hotspotInfo: info}),
+
+    setSyncServiceOpenedHotspot: (opened: boolean) => set({syncServiceOpenedHotspot: opened}),
+
+    // Gallery status from glasses
+    setGlassesGalleryStatus: (photos: number, videos: number, total: number, hasContent: boolean) => {
+      const state = get()
+      // Reset to idle if sync is in a terminal state and new content is available
+      // This allows syncing again after taking new photos
+      const shouldResetToIdle =
+        hasContent && (state.syncState === "complete" || state.syncState === "error" || state.syncState === "cancelled")
+
+      set({
+        glassesPhotoCount: photos,
+        glassesVideoCount: videos,
+        glassesTotalCount: total,
+        glassesHasContent: hasContent,
+        ...(shouldResetToIdle ? {syncState: "idle" as SyncState} : {}),
+      })
+    },
+
+    clearGlassesGalleryStatus: () =>
+      set({
+        glassesPhotoCount: 0,
+        glassesVideoCount: 0,
+        glassesTotalCount: 0,
+        glassesHasContent: false,
+      }),
+
+    // Queue management
+    setQueue: (files: PhotoInfo[], startIndex: number = 0) =>
+      set({
+        // C4: Strip thumbnail_data (base64) from store to prevent OOM
+        queue: files.map(({thumbnail_data: _thumbnailData, ...rest}) => rest),
+        queueIndex: startIndex,
+        totalFiles: files.length,
+        completedFiles: startIndex,
+      }),
+
+    advanceQueue: () => {
+      const state = get()
+      set({queueIndex: state.queueIndex + 1})
+    },
+
+    clearQueue: () =>
+      set({
+        queue: [],
+        queueIndex: 0,
+        totalFiles: 0,
+        completedFiles: 0,
+      }),
+
+    // Full reset
+    reset: () => set({...initialState, processingFiles: new Set<string>()}),
+  })),
+)
+
+// Selector helpers for common subscriptions
+export const selectSyncProgress = (state: GallerySyncState) => ({
+  syncState: state.syncState,
+  currentFile: state.currentFile,
+  currentFileProgress: state.currentFileProgress,
+  completedFiles: state.completedFiles,
+  totalFiles: state.totalFiles,
+  failedFiles: state.failedFiles,
+  processingFiles: state.processingFiles,
+})
+
+export const selectIssyncing = (state: GallerySyncState) =>
+  state.syncState === "syncing" || state.syncState === "requesting_hotspot" || state.syncState === "connecting_wifi"
+
+export const selectGlassesGalleryStatus = (state: GallerySyncState) => ({
+  photos: state.glassesPhotoCount,
+  videos: state.glassesVideoCount,
+  total: state.glassesTotalCount,
+  hasContent: state.glassesHasContent,
+})