@mentra/engine 0.1.0-dev.0

package/src/services/asg/gallerySyncService.ts

@@ -0,0 +1,2167 @@
+/**
+ * Gallery Sync Service
+ * Orchestrates gallery sync independently of UI lifecycle
+ */
+
+import * as RNFS from "@dr.pogodin/react-native-fs"
+import NetInfo from "@react-native-community/netinfo"
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import CrustModule from "@mentra/crust"
+import {AppState, AppStateStatus, Platform} from "react-native"
+import BleManager from "react-native-ble-manager"
+import WifiManager from "react-native-wifi-reborn"
+
+import {useGallerySyncStore, HotspotInfo} from "../../stores/gallerySync"
+import {selectGlassesConnected, useGlassesStore} from "../../stores/glasses"
+import {isGlassesConnected} from "../GlassesReadiness"
+import {SETTINGS, useSettingsStore} from "../../stores/settings"
+import {PhotoInfo, CaptureGroup} from "../../types/asg"
+import GlobalEventEmitter from "../../utils/GlobalEventEmitter"
+import {BgTimer} from "../../utils/timers"
+import {fixGlassesClockIfSkewed} from "../glassesClockSync"
+import {detectClockSkew, isSyncManifestEmpty} from "../gallerySyncClock"
+import {MediaLibraryPermissions} from "../../utils/permissions/MediaLibraryPermissions"
+import {permissions, PermissionFeatures} from "../../facades/permissions"
+
+import {asgCameraApi} from "./asgCameraApi"
+import {gallerySettingsService} from "./gallerySettingsService"
+import {gallerySyncNotifications} from "./gallerySyncNotifications"
+import {localStorageService} from "./localStorageService"
+import {mediaProcessingQueue} from "./mediaProcessingQueue"
+import {validateCaptureMetadataForDownload} from "./galleryMediaValidation"
+import {emitGalleryNotice} from "./galleryNotices"
+
+// Timing constants
+const TIMING = {
+  HOTSPOT_CONNECT_DELAY_MS: 3000, // Increased from 1000ms - hotspot needs time to broadcast and become discoverable
+  HOTSPOT_REQUEST_TIMEOUT_MS: 30000, // Timeout waiting for hotspot to enable
+  WIFI_CONNECTION_TIMEOUT_MS: 30000,
+  RETRY_DELAY_MS: 2000,
+  MAX_QUEUE_AGE_MS: 2 * 60 * 1000, // 2 min - glasses hotspot auto-disables after 40s inactivity
+  // iOS WiFi connection timing - the system shows a dialog that user must accept
+  IOS_WIFI_RETRY_DELAY_MS: 3000, // Wait for user to interact with iOS dialog
+  IOS_WIFI_MAX_RETRIES: 5, // Retry multiple times to give user time to accept
+  // WiFi initialization cooldown - prevents repeated "enable WiFi" alerts while WiFi is initializing
+  WIFI_COOLDOWN_MS: 3000, // Wait 3 seconds after user visits WiFi settings before showing alert again
+  // Cap the native location-services (GPS) check so a hung CrustModule call can't freeze
+  // the sync pre-flight (mirrors the host's former PermissionsUtils guard).
+  LOCATION_SERVICES_CHECK_TIMEOUT_MS: 5000,
+} as const
+
+type SyncManifestData = {
+  api_version?: number
+  client_id: string
+  captures?: CaptureGroup[]
+  changed_files: PhotoInfo[]
+  deleted_files?: string[]
+  server_time: number
+  total_changed?: number
+  total_size?: number
+}
+
+class GallerySyncService {
+  private static instance: GallerySyncService
+  private hotspotListenerRegistered = false
+  private hotspotConnectionTimeout: number | null = null
+  private hotspotRequestTimeout: number | null = null
+  private abortController: AbortController | null = null
+  private isInitialized = false
+  private glassesStoreUnsubscribe: (() => void) | null = null
+  private appStateSubscription: ReturnType<typeof AppState.addEventListener> | null = null
+  private waitingForWifiRetry = false
+  // Guards full-sync recovery so we don't re-download the entire gallery every sync
+  // when glasses retain leftover files (e.g. a previous delete-from-glasses failed).
+  // Keyed by `${client_id}:${last_sync_time}` — same pair = already tried, skip.
+  private lastFullSyncRetryKey: string | null = null
+  private wifiSettingsOpenedAt: number | null = null // Timestamp when user was sent to WiFi settings
+  private syncStartPromise: Promise<void> | null = null
+  private startAborted = false
+
+  private constructor() {}
+
+  static getInstance(): GallerySyncService {
+    if (!GallerySyncService.instance) {
+      GallerySyncService.instance = new GallerySyncService()
+    }
+    return GallerySyncService.instance
+  }
+
+  /**
+   * Initialize the service - register event listeners
+   */
+  initialize(): void {
+    if (this.isInitialized) return
+
+    // Listen for hotspot status changes
+    GlobalEventEmitter.addListener("hotspot_status_change", this.handleHotspotStatusChange)
+    GlobalEventEmitter.addListener("hotspot_error", this.handleHotspotError)
+    GlobalEventEmitter.addListener("gallery_status", this.handleGalleryStatus)
+
+    // Subscribe to glasses store to detect disconnection during sync
+    this.glassesStoreUnsubscribe = useGlassesStore.subscribe(selectGlassesConnected, (connected, prevConnected) => {
+      // Only trigger on disconnect (was connected, now not connected)
+      if (prevConnected && !connected) {
+        this.handleGlassesDisconnected()
+      }
+    })
+
+    // Listen for app state changes to auto-retry sync after user enables WiFi
+    this.appStateSubscription = AppState.addEventListener("change", this.handleAppStateChange)
+
+    this.hotspotListenerRegistered = true
+    this.isInitialized = true
+
+    // console.log("[GallerySyncService] Initialized")
+
+    // Check for resumable sync on startup
+    this.checkForResumableSync()
+  }
+
+  /**
+   * Cleanup - remove event listeners
+   */
+  cleanup(): void {
+    if (this.hotspotListenerRegistered) {
+      GlobalEventEmitter.removeListener("hotspot_status_change", this.handleHotspotStatusChange)
+      GlobalEventEmitter.removeListener("hotspot_error", this.handleHotspotError)
+      GlobalEventEmitter.removeListener("gallery_status", this.handleGalleryStatus)
+      this.hotspotListenerRegistered = false
+    }
+
+    if (this.glassesStoreUnsubscribe) {
+      this.glassesStoreUnsubscribe()
+      this.glassesStoreUnsubscribe = null
+    }
+
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove()
+      this.appStateSubscription = null
+    }
+
+    if (this.hotspotConnectionTimeout) {
+      BgTimer.clearTimeout(this.hotspotConnectionTimeout!)
+      this.hotspotConnectionTimeout = null
+    }
+
+    if (this.hotspotRequestTimeout) {
+      BgTimer.clearTimeout(this.hotspotRequestTimeout!)
+      this.hotspotRequestTimeout = null
+    }
+
+    this.syncStartPromise = null
+    this.isInitialized = false
+    console.log("[GallerySyncService] Cleaned up")
+  }
+
+  /**
+   * Handle glasses disconnection during sync
+   */
+  private handleGlassesDisconnected = (): void => {
+    const store = useGallerySyncStore.getState()
+
+    // Pre-flight has no sync state yet — abort quietly; runStartSync checks this flag after awaits
+    if (this.syncStartPromise && !this.isSyncing()) {
+      console.log("[GallerySyncService] Glasses disconnected during pre-flight — aborting start")
+      this.startAborted = true
+      return
+    }
+
+    // Only handle if we're actively syncing
+    if (!this.isSyncing()) {
+      return
+    }
+
+    console.log("[GallerySyncService] Glasses disconnected during sync - cancelling")
+    store.setSyncError("Glasses disconnected")
+
+    // Abort ongoing downloads
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+
+    // Clear timeouts
+    if (this.hotspotConnectionTimeout) {
+      BgTimer.clearTimeout(this.hotspotConnectionTimeout!)
+      this.hotspotConnectionTimeout = null
+    }
+    if (this.hotspotRequestTimeout) {
+      BgTimer.clearTimeout(this.hotspotRequestTimeout!)
+      this.hotspotRequestTimeout = null
+    }
+
+    gallerySyncNotifications.showSyncError("Glasses disconnected")
+  }
+
+  /**
+   * Handle app state changes to auto-retry sync when user returns from settings
+   */
+  private handleAppStateChange = async (nextAppState: AppStateStatus): Promise<void> => {
+    // Only handle when app comes to foreground
+    if (nextAppState !== "active") {
+      return
+    }
+
+    // Only auto-retry if we were waiting for WiFi
+    if (!this.waitingForWifiRetry) {
+      return
+    }
+
+    console.log("[GallerySyncService] App returned to foreground - checking if WiFi is enabled")
+
+    const store = useGallerySyncStore.getState()
+    const glassesStore = useGlassesStore.getState()
+    const glassesConnected = isGlassesConnected(glassesStore.connection)
+
+    // Check if glasses are still connected
+    if (!glassesConnected) {
+      console.log("[GallerySyncService] Glasses disconnected - not retrying sync")
+      this.waitingForWifiRetry = false
+      return
+    }
+
+    // Check if WiFi is now enabled (Android only)
+    // Use retry logic because WiFi status takes time to propagate after user enables it
+    if (Platform.OS === "android") {
+      const MAX_RETRIES = 5
+      const RETRY_DELAY_MS = 1000 // Wait 500ms between checks
+
+      console.log("[GallerySyncService] Waiting for WiFi to initialize (may take a moment after enabling)...")
+
+      for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+          await new Promise<void>((resolve) => BgTimer.setTimeout(() => resolve(), RETRY_DELAY_MS))
+
+          const netState = await NetInfo.fetch()
+          console.log(
+            `[GallerySyncService] WiFi check attempt ${attempt}/${MAX_RETRIES}: enabled=${netState.isWifiEnabled}`,
+          )
+
+          if (netState.isWifiEnabled === true) {
+            console.log("[GallerySyncService] ✅ WiFi is now enabled - auto-retrying sync")
+            this.waitingForWifiRetry = false
+            this.wifiSettingsOpenedAt = null // Clear cooldown timestamp
+            // Clear previous error state
+            store.setSyncState("idle")
+            // Auto-retry sync
+            await this.startSync()
+            return
+          }
+
+          // If this was the last attempt, log and give up
+          if (attempt === MAX_RETRIES) {
+            console.log(
+              "[GallerySyncService] ❌ WiFi still disabled after all retries - user may need to tap sync manually",
+            )
+            this.waitingForWifiRetry = false
+            this.wifiSettingsOpenedAt = null // Clear cooldown timestamp
+          }
+        } catch (error) {
+          console.warn(`[GallerySyncService] Failed to check WiFi status on attempt ${attempt}:`, error)
+          // Continue to next retry
+        }
+      }
+    }
+  }
+
+  /**
+   * Handle gallery status from glasses
+   */
+  private handleGalleryStatus = (data: any): void => {
+    console.log("[GallerySyncService] Received gallery_status:", data)
+
+    const store = useGallerySyncStore.getState()
+    store.setGlassesGalleryStatus(data.photos || 0, data.videos || 0, data.total || 0, data.has_content || false)
+  }
+
+  /**
+   * Handle hotspot status change event
+   */
+  private handleHotspotStatusChange = async (eventData: any): Promise<void> => {
+    console.log("[GallerySyncService] Hotspot status changed:", eventData)
+
+    const store = useGallerySyncStore.getState()
+
+    // Only process if we're in a connecting state
+    if (store.syncState !== "requesting_hotspot" && store.syncState !== "connecting_wifi") {
+      console.log("[GallerySyncService] Ignoring hotspot event - not in connecting state")
+      return
+    }
+
+    if (!eventData.enabled || !eventData.ssid || !eventData.password) {
+      console.log("[GallerySyncService] Hotspot not ready yet")
+      return
+    }
+
+    // Clear the hotspot request timeout since we got a response
+    if (this.hotspotRequestTimeout) {
+      BgTimer.clearTimeout(this.hotspotRequestTimeout!)
+      this.hotspotRequestTimeout = null
+    }
+
+    // Pre-flight: do not start the wait if already disconnected (e.g. BT dropped right after hotspot enabled)
+    if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+      console.log("[GallerySyncService] ❌ Glasses disconnected on hotspot_status_change - aborting (no wait)")
+      store.setSyncError("Glasses disconnected")
+      gallerySyncNotifications.showSyncError("Glasses disconnected")
+      return
+    }
+
+    const hotspotInfo: HotspotInfo = {
+      ssid: eventData.ssid,
+      password: eventData.password,
+      ip: eventData.local_ip,
+    }
+
+    store.setHotspotInfo(hotspotInfo)
+
+    // Wait for hotspot to become discoverable
+    console.log(
+      `[GallerySyncService] Hotspot enabled, waiting ${TIMING.HOTSPOT_CONNECT_DELAY_MS}ms for broadcast initialization...`,
+    )
+    console.log("[GallerySyncService] 📡 Glasses need time to start WiFi AP and broadcast SSID")
+
+    if (this.hotspotConnectionTimeout) {
+      BgTimer.clearTimeout(this.hotspotConnectionTimeout!)
+    }
+
+    this.hotspotConnectionTimeout = BgTimer.setTimeout(() => {
+      this.hotspotConnectionTimeout = null
+      // Pre-flight: abort if Bluetooth disconnected during the wait
+      const stillConnected = isGlassesConnected(useGlassesStore.getState().connection)
+      if (!stillConnected) {
+        console.log("[GallerySyncService] ❌ Glasses disconnected during hotspot wait - skipping WiFi connection")
+        const currentStore = useGallerySyncStore.getState()
+        currentStore.setSyncError("Glasses disconnected")
+        gallerySyncNotifications.showSyncError("Glasses disconnected")
+        return
+      }
+      console.log("[GallerySyncService] ✅ Hotspot broadcast window complete - attempting connection")
+      this.connectToHotspotWifi(hotspotInfo)
+    }, TIMING.HOTSPOT_CONNECT_DELAY_MS)
+  }
+
+  /**
+   * Handle hotspot error event
+   */
+  private handleHotspotError = (eventData: any): void => {
+    console.error("[GallerySyncService] Hotspot error:", eventData)
+
+    const store = useGallerySyncStore.getState()
+
+    if (this.hotspotConnectionTimeout) {
+      BgTimer.clearTimeout(this.hotspotConnectionTimeout!)
+      this.hotspotConnectionTimeout = null
+    }
+
+    store.setSyncError(eventData.error_message || "Failed to start hotspot")
+    gallerySyncNotifications.showSyncError("Failed to start hotspot")
+  }
+
+  /**
+   * Start the sync process
+   */
+  async startSync(): Promise<void> {
+    if (this.syncStartPromise) {
+      console.log("[GallerySyncService] ⚠️ Sync start already in progress, joining existing attempt")
+      return this.syncStartPromise
+    }
+
+    this.syncStartPromise = this.runStartSync().finally(() => {
+      this.syncStartPromise = null
+    })
+    return this.syncStartPromise
+  }
+
+  /**
+   * Native location-services (GPS on/off) check, raced against a timeout so a hung
+   * CrustModule call can't freeze the sync pre-flight. Mirrors the host's former
+   * PermissionsUtils.isLocationServicesEnabled exactly: on timeout assume enabled
+   * (proceed); on any other native error assume disabled (block + prompt). Android-only
+   * callers; iOS doesn't need location for BLE since iOS 13.
+   */
+  private async isLocationServicesEnabled(): Promise<boolean> {
+    try {
+      return await Promise.race([
+        CrustModule.isLocationServicesEnabled(),
+        new Promise<boolean>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("Location services check timed out")),
+            TIMING.LOCATION_SERVICES_CHECK_TIMEOUT_MS,
+          ),
+        ),
+      ])
+    } catch (error) {
+      console.error("[GallerySyncService] Error checking location services:", error)
+      if (error instanceof Error && error.message.includes("timed out")) {
+        console.warn("[GallerySyncService] Location services check timed out — assuming enabled so sync can proceed")
+        return true
+      }
+      return false
+    }
+  }
+
+  /**
+   * Mirrors the host's old PermissionsUtils.isBluetoothEnabled exactly: poll
+   * BleManager for up to 500ms while the adapter reports "unknown"; assume
+   * enabled on a timeout (a slow adapter must not block the sync) and disabled
+   * on a check error.
+   */
+  private async isBluetoothAdapterEnabled(): Promise<boolean> {
+    try {
+      await BleManager.start({showAlert: false})
+      for (let attempt = 0; attempt < 10; attempt++) {
+        const state = await BleManager.checkState()
+        if (state !== "unknown") {
+          return state === "on"
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50))
+      }
+      console.warn("[GallerySyncService] Bluetooth state still unknown after 500ms - assuming enabled")
+      return true
+    } catch (error) {
+      console.error("[GallerySyncService] Error checking Bluetooth state:", error)
+      return false
+    }
+  }
+
+  private shouldAbortPreFlight(): boolean {
+    if (this.startAborted) {
+      this.startAborted = false
+      return true
+    }
+    if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+      return true
+    }
+    return false
+  }
+
+  private async runStartSync(): Promise<void> {
+    // Clear stale abort flag — it can persist when a prior pre-flight exited through
+    // a non-shouldAbortPreFlight path (e.g. connectivity failed, disk full), which
+    // would otherwise cause the next sync attempt to abort spuriously.
+    this.startAborted = false
+
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] 🚀 SYNC START INITIATED")
+    console.log("[GallerySyncService] ========================================")
+
+    const store = useGallerySyncStore.getState()
+    const glassesStore = useGlassesStore.getState()
+    const glassesConnected = isGlassesConnected(glassesStore.connection)
+    const glassesHotspot =
+      glassesStore.hotspot.state === "enabled"
+        ? {
+            ssid: glassesStore.hotspot.ssid,
+            password: glassesStore.hotspot.password,
+            ip: glassesStore.hotspot.localIp,
+          }
+        : null
+
+    // R1: Check if already syncing (including requesting_hotspot to prevent double-tap)
+    if (
+      store.syncState === "syncing" ||
+      store.syncState === "connecting_wifi" ||
+      store.syncState === "requesting_hotspot"
+    ) {
+      console.log(`[GallerySyncService] ⚠️ Already syncing (state: ${store.syncState}), ignoring start request`)
+      return
+    }
+
+    // Engine-owned pre-flight: glasses reachable + bluetooth adapter on. The host
+    // renders the alerts off the structured notices; Android location permission
+    // and services are handled in the permission steps below.
+    if (!glassesConnected) {
+      console.warn("[GallerySyncService] Sync aborted - Glasses not connected")
+      store.setSyncError("Glasses not connected")
+      emitGalleryNotice({code: "glasses_disconnected"})
+      return
+    }
+
+    if (!(await this.isBluetoothAdapterEnabled())) {
+      console.warn("[GallerySyncService] Sync aborted - Bluetooth is disabled")
+      store.setSyncError("Bluetooth disabled - enable Bluetooth and try again")
+      emitGalleryNotice({code: "bluetooth_off"})
+      return
+    }
+
+    console.log("[GallerySyncService] ✅ Pre-flight check passed - BT enabled, Glasses connected")
+    console.log("[GallerySyncService] 📊 Glasses info:", {
+      connected: glassesConnected,
+      hotspotEnabled: glassesHotspot !== null,
+    })
+
+    // Reset processing queue only after pre-flight passes — avoids clobbering an active session
+    mediaProcessingQueue.reset()
+
+    // Request all permissions upfront so user isn't interrupted during WiFi/download
+    console.log("[GallerySyncService] 🔐 Step 1/6: Requesting permissions...")
+
+    // 1. Notification permission (for background sync progress)
+    console.log("[GallerySyncService]   📱 Requesting notification permission...")
+    await gallerySyncNotifications.requestPermissions()
+    if (this.shouldAbortPreFlight()) {
+      console.log("[GallerySyncService] Pre-flight aborted after notification permission")
+      return
+    }
+    console.log("[GallerySyncService]   ✅ Notification permission handled")
+
+    // 2. Location permission (required to read WiFi SSID for hotspot verification)
+    console.log("[GallerySyncService]   📍 Checking location permission...")
+    const hasLocationPermission = await permissions.check(PermissionFeatures.LOCATION)
+    if (!hasLocationPermission) {
+      console.log("[GallerySyncService]   ⚠️ Location permission not granted - requesting...")
+      const granted = await permissions.request(PermissionFeatures.LOCATION)
+      if (!granted) {
+        console.warn("[GallerySyncService]   ❌ Location permission denied - WiFi SSID verification may fail")
+        // Don't block sync - we'll try anyway and fall back to IP-based verification if needed
+      } else {
+        console.log("[GallerySyncService]   ✅ Location permission granted")
+      }
+    } else {
+      console.log("[GallerySyncService]   ✅ Location permission already granted")
+    }
+    if (this.shouldAbortPreFlight()) {
+      console.log("[GallerySyncService] Pre-flight aborted after location permission")
+      return
+    }
+
+    // 3. Camera roll permission (if auto-save is enabled)
+    const shouldAutoSave = await gallerySettingsService.getAutoSaveToCameraRoll()
+    console.log(`[GallerySyncService]   📸 Auto-save to camera roll: ${shouldAutoSave}`)
+    if (shouldAutoSave) {
+      console.log("[GallerySyncService]   📸 Checking camera roll permission...")
+      const hasPermission = await MediaLibraryPermissions.checkPermission()
+      if (!hasPermission) {
+        console.log("[GallerySyncService]   ⚠️ Camera roll permission not granted - requesting...")
+        const granted = await MediaLibraryPermissions.requestPermission()
+        if (!granted) {
+          console.warn("[GallerySyncService]   ❌ Camera roll permission denied - photos will still sync to app")
+          // Don't block sync - photos will still be downloaded to app storage
+          // They just won't be saved to the camera roll
+        } else {
+          console.log("[GallerySyncService]   ✅ Camera roll permission granted")
+        }
+      } else {
+        console.log("[GallerySyncService]   ✅ Camera roll permission already granted")
+      }
+    }
+    if (this.shouldAbortPreFlight()) {
+      console.log("[GallerySyncService] Pre-flight aborted after camera roll permission")
+      return
+    }
+
+    // S1: Disk space check — abort early if insufficient space
+    try {
+      const fsInfo = await RNFS.getFSInfo()
+      const freeSpaceMB = fsInfo.freeSpace / (1024 * 1024)
+      console.log(`[GallerySyncService]   💾 Free disk space: ${freeSpaceMB.toFixed(0)} MB`)
+      if (fsInfo.freeSpace < 500 * 1024 * 1024) {
+        console.error("[GallerySyncService]   ❌ Insufficient disk space (<500MB)")
+        emitGalleryNotice({code: "insufficient_storage", data: {freeSpaceMB: Math.round(freeSpaceMB)}})
+        store.setSyncError("Insufficient storage space")
+        return
+      }
+    } catch (fsError) {
+      console.warn("[GallerySyncService]   ⚠️ Could not check disk space:", fsError)
+      // Continue — don't block sync if check fails
+    }
+    if (this.shouldAbortPreFlight()) {
+      console.log("[GallerySyncService] Pre-flight aborted after disk space check")
+      return
+    }
+
+    // Reset abort controller
+    this.abortController = new AbortController()
+
+    // COOLDOWN CHECK: If user just went to WiFi settings, show a "please wait" message
+    // This prevents showing "enable WiFi" alert repeatedly while WiFi is initializing
+    if (Platform.OS === "android" && this.wifiSettingsOpenedAt) {
+      const timeSinceSettingsOpened = Date.now() - this.wifiSettingsOpenedAt
+      const cooldownRemaining = TIMING.WIFI_COOLDOWN_MS - timeSinceSettingsOpened
+
+      if (cooldownRemaining > 0) {
+        console.log(
+          `[GallerySyncService] WiFi cooldown active (${Math.round(
+            cooldownRemaining / 1000,
+          )}s remaining) - showing wait message`,
+        )
+
+        emitGalleryNotice({code: "wifi_initializing"})
+        return
+      } else {
+        // Cooldown expired, clear the timestamp
+        console.log("[GallerySyncService] WiFi cooldown expired - resuming normal behavior")
+        this.wifiSettingsOpenedAt = null
+      }
+    }
+
+    // Pre-flight WiFi check on Android BEFORE any connection attempts
+    // This prevents sync failures even when we think we're already connected
+    // NOTE: We use WifiManager.isEnabled() instead of NetInfo.isWifiEnabled because
+    // NetInfo can return stale/cached data that reports WiFi as enabled when it's actually OFF
+    console.log("[GallerySyncService] 📡 Step 2/6: WiFi pre-flight check...")
+    if (Platform.OS === "android") {
+      try {
+        // Use WifiManager.isEnabled() for accurate WiFi state (NetInfo can be stale)
+        const wifiEnabled = await WifiManager.isEnabled()
+        console.log("[GallerySyncService]   📡 WiFi enabled (WifiManager):", wifiEnabled)
+
+        // Also log NetInfo for debugging comparison
+        const netState = await NetInfo.fetch()
+        console.log("[GallerySyncService]   📡 WiFi enabled (NetInfo):", netState.isWifiEnabled)
+        console.log("[GallerySyncService]   📡 Connected:", netState.isConnected)
+        console.log("[GallerySyncService]   📡 Internet reachable:", netState.isInternetReachable)
+
+        if (!wifiEnabled) {
+          console.error("[GallerySyncService]   ❌ WiFi is disabled - cannot sync")
+
+          // Don't arm the auto-retry / "WiFi initializing" cooldown yet — whether to arm
+          // them depends on the user's choice in the host's prompt, which only the host
+          // learns. The host renders an "enable WiFi → open settings" alert from this
+          // notice and calls ack() ONLY when the user opts to open settings; on Cancel it
+          // does nothing, so a declined prompt leaves no pending retry or phantom cooldown.
+          // The engine still owns what arming MEANS (this closure) — the host only reports
+          // that the user took the affirmative action.
+          emitGalleryNotice({
+            code: "wifi_off",
+            ack: () => {
+              this.waitingForWifiRetry = true
+              this.wifiSettingsOpenedAt = Date.now()
+            },
+          })
+          store.setSyncError("WiFi disabled - enable WiFi and try again")
+
+          // Return early - do NOT proceed with sync
+          return
+        } else {
+          // WiFi is enabled - clear any cooldown timestamp
+          console.log("[GallerySyncService]   ✅ WiFi is enabled - proceeding")
+          this.wifiSettingsOpenedAt = null
+        }
+      } catch (error) {
+        console.warn("[GallerySyncService]   ⚠️ Failed to check WiFi status:", error)
+        // Continue with sync attempt - don't block if check fails
+      }
+      if (this.shouldAbortPreFlight()) {
+        console.log("[GallerySyncService] Pre-flight aborted after WiFi check")
+        return
+      }
+    } else {
+      console.log("[GallerySyncService]   ℹ️ iOS - WiFi check not required")
+    }
+
+    // Check if Location Services is enabled (Android only - required for WiFi operations)
+    // This must be checked BEFORE attempting any WiFi connection to avoid cryptic errors
+    if (Platform.OS === "android") {
+      console.log("[GallerySyncService]   📍 Checking Location Services status...")
+      try {
+        const locationServicesEnabled = await this.isLocationServicesEnabled()
+        console.log("[GallerySyncService]   📍 Location Services enabled:", locationServicesEnabled)
+
+        if (!locationServicesEnabled) {
+          console.error("[GallerySyncService]   ❌ Location Services is OFF - cannot sync")
+          console.error("[GallerySyncService]   ❌ Android requires Location Services for WiFi operations")
+
+          // Emit a notice; the host shows the "enable Location Services" alert + dialog.
+          emitGalleryNotice({code: "location_services_off"})
+          store.setSyncError("Location Services disabled - enable in Settings and try again")
+
+          // Return early - do NOT proceed with sync
+          return
+        } else {
+          console.log("[GallerySyncService]   ✅ Location Services is enabled - proceeding")
+        }
+      } catch (error) {
+        console.warn("[GallerySyncService]   ⚠️ Failed to check Location Services status:", error)
+        // Continue with sync attempt - don't block if check fails
+      }
+      if (this.shouldAbortPreFlight()) {
+        console.log("[GallerySyncService] Pre-flight aborted after location services check")
+        return
+      }
+    }
+
+    // Check if already connected to hotspot
+    // IMPORTANT: We must verify the phone's WiFi is actually connected to the hotspot SSID,
+    // not just that the glasses reported hotspot is enabled (which persists across app restarts)
+    console.log("[GallerySyncService] 🔌 Step 3/6: Checking hotspot connection status...")
+
+    // Re-read current glasses state from the store — the snapshot from the top of the function
+    // may be stale if glasses disconnected during one of the above awaits.
+    const currentGlassesConnected = isGlassesConnected(useGlassesStore.getState().connection)
+    if (!currentGlassesConnected) {
+      console.log("[GallerySyncService] Pre-flight aborted — glasses no longer connected at hotspot check")
+      return
+    }
+    const currentGlassesStore = useGlassesStore.getState()
+    const currentGlassesHotspot =
+      currentGlassesStore.hotspot.state === "enabled"
+        ? {
+            ssid: currentGlassesStore.hotspot.ssid,
+            password: currentGlassesStore.hotspot.password,
+            ip: currentGlassesStore.hotspot.localIp,
+          }
+        : null
+
+    let isAlreadyConnected = false
+    if (currentGlassesHotspot) {
+      console.log("[GallerySyncService]   📊 Glasses hotspot status:")
+      console.log("[GallerySyncService]      - Enabled: true")
+      console.log(`[GallerySyncService]      - SSID: ${currentGlassesHotspot.ssid}`)
+      console.log(`[GallerySyncService]      - IP: ${currentGlassesHotspot.ip}`)
+
+      try {
+        const currentSSID = await WifiManager.getCurrentWifiSSID()
+        if (this.shouldAbortPreFlight()) {
+          console.log("[GallerySyncService] Pre-flight aborted after SSID check")
+          return
+        }
+        console.log(`[GallerySyncService]   📱 Phone current WiFi SSID: "${currentSSID}"`)
+        console.log(`[GallerySyncService]   🔍 Comparing with glasses hotspot SSID: "${currentGlassesHotspot.ssid}"`)
+
+        isAlreadyConnected = currentSSID === currentGlassesHotspot.ssid
+        if (isAlreadyConnected) {
+          console.log("[GallerySyncService]   ✅ Phone is already connected to glasses hotspot!")
+        } else if (currentSSID) {
+          console.log(`[GallerySyncService]   ⚠️ Phone is on different network (${currentSSID})`)
+          console.log("[GallerySyncService]   ➡️ Will request hotspot connection")
+        } else {
+          console.log("[GallerySyncService]   ⚠️ Phone not connected to any WiFi network")
+        }
+      } catch (error) {
+        console.warn("[GallerySyncService]   ⚠️ Could not verify current WiFi SSID:", error)
+        // If we can't verify, don't assume we're connected - request hotspot
+        isAlreadyConnected = false
+      }
+    } else {
+      console.log("[GallerySyncService]   ℹ️ Glasses hotspot not currently enabled")
+      console.log("[GallerySyncService]   ➡️ Will request hotspot activation")
+    }
+
+    if (isAlreadyConnected && currentGlassesHotspot) {
+      console.log("[GallerySyncService] 🚀 Skipping hotspot request - already connected!")
+      const hotspotInfo: HotspotInfo = currentGlassesHotspot
+      store.setHotspotInfo(hotspotInfo)
+      store.setSyncState("connecting_wifi")
+      await this.startFileDownload(hotspotInfo)
+      return
+    }
+
+    // Request hotspot
+    console.log("[GallerySyncService] 📡 Step 4/6: Requesting hotspot from glasses...")
+    store.setRequestingHotspot()
+    store.setSyncServiceOpenedHotspot(true)
+
+    // Set timeout for hotspot request - if we don't get a response, fail gracefully
+    this.hotspotRequestTimeout = BgTimer.setTimeout(() => {
+      const currentStore = useGallerySyncStore.getState()
+      if (currentStore.syncState === "requesting_hotspot") {
+        console.error("[GallerySyncService] Hotspot request timed out")
+        currentStore.setSyncError("Hotspot request timed out")
+        currentStore.setSyncServiceOpenedHotspot(false)
+        gallerySyncNotifications.showSyncError("Could not start hotspot - please try again")
+      }
+      this.hotspotRequestTimeout = null
+    }, TIMING.HOTSPOT_REQUEST_TIMEOUT_MS)
+
+    try {
+      console.log("[GallerySyncService]   📤 Sending hotspot enable command to glasses...")
+      await BluetoothSdk.setHotspotState(true)
+      console.log("[GallerySyncService]   ✅ Hotspot enabled by glasses")
+    } catch (error) {
+      // Clear the timeout since we got an immediate error
+      if (this.hotspotRequestTimeout) {
+        BgTimer.clearTimeout(this.hotspotRequestTimeout!)
+        this.hotspotRequestTimeout = null
+      }
+      console.error("[GallerySyncService]   ❌ Failed to request hotspot:", error)
+      store.setSyncError("Failed to start hotspot")
+      store.setSyncServiceOpenedHotspot(false)
+    }
+  }
+
+  /**
+   * Show explanation dialog before WiFi connection (first time only)
+   * Returns true if user wants to proceed, false if cancelled
+   */
+  private async showWifiJoinExplanation(ssid: string): Promise<boolean> {
+    const settingsStore = useSettingsStore.getState()
+    const hasSeenExplanation = settingsStore.getSetting(SETTINGS.gallery_sync_explained.key)
+
+    if (hasSeenExplanation) {
+      console.log("[GallerySyncService] User has seen WiFi explanation before - skipping")
+      return true
+    }
+
+    console.log("[GallerySyncService] First sync - showing WiFi join explanation")
+
+    return new Promise<boolean>((resolve) => {
+      const proceed = () => {
+        // Mark as explained so we don't show again.
+        settingsStore.setSetting(SETTINGS.gallery_sync_explained.key, true, false)
+        resolve(true)
+      }
+      // Emit the one-time wifi-join explanation as a notice the host renders + acknowledges.
+      // The host owns the alert + its dismiss timing (Android's native WiFi connect freezes
+      // the UI thread, so it should let the dialog fully dismiss before calling ack).
+      const delivered = emitGalleryNotice({
+        code: "connect_to_glasses",
+        data: {ssid, platform: Platform.OS},
+        ack: proceed,
+      })
+      // No host listening (e.g. an OEM that hasn't wired onNotice) — don't hang the sync.
+      if (delivered === 0) proceed()
+    })
+  }
+
+  /**
+   * Connect to hotspot WiFi with retry logic (unified for both platforms)
+   * Both iOS and Android benefit from retries:
+   * - iOS: Library throws "internal error" before user responds to system dialog
+   * - Android: Hotspot needs time to initialize, especially when glasses WiFi was cold
+   */
+  private async connectToHotspotWifi(hotspotInfo: HotspotInfo): Promise<void> {
+    const store = useGallerySyncStore.getState()
+
+    // Pre-flight: do not attempt WiFi connection if Bluetooth already disconnected
+    if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+      console.log("[GallerySyncService] ❌ Glasses not connected - aborting WiFi connection")
+      store.setSyncError("Glasses disconnected")
+      gallerySyncNotifications.showSyncError("Glasses disconnected")
+      return
+    }
+
+    // Show explanation dialog on first sync (user must acknowledge before proceeding)
+    await this.showWifiJoinExplanation(hotspotInfo.ssid)
+
+    let lastError: any = null
+    const wifiConnectStartTime = Date.now()
+
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] 📡 WIFI CONNECTION PHASE")
+    console.log("[GallerySyncService] ========================================")
+    console.log(`[GallerySyncService] 🎯 Target SSID: ${hotspotInfo.ssid}`)
+    console.log(`[GallerySyncService] 🔑 Password length: ${hotspotInfo.password.length} chars`)
+    console.log(`[GallerySyncService] 🌐 Gateway IP: ${hotspotInfo.ip}`)
+    console.log(`[GallerySyncService] 📱 Platform: ${Platform.OS}`)
+    console.log(`[GallerySyncService] 🔄 Max retry attempts: ${TIMING.IOS_WIFI_MAX_RETRIES}`)
+    console.log(`[GallerySyncService] ⏱️ Retry delay: ${TIMING.IOS_WIFI_RETRY_DELAY_MS}ms`)
+
+    store.setSyncState("connecting_wifi")
+
+    // Setup app state monitoring to detect backgrounding
+    let appBackgrounded = false
+    let appBackgroundTime: number | null = null
+    const appStateHandler = (nextAppState: AppStateStatus) => {
+      if (nextAppState === "background") {
+        appBackgrounded = true
+        appBackgroundTime = Date.now()
+        console.warn("[GallerySyncService] ⚠️ 🚨 APP BACKGROUNDED during WiFi connection!")
+        console.warn("[GallerySyncService] ⚠️ This may indicate Android system dialog appeared")
+        console.warn(
+          "[GallerySyncService] ⚠️ Time since WiFi connect started:",
+          Date.now() - wifiConnectStartTime,
+          "ms",
+        )
+      } else if (nextAppState === "active" && appBackgrounded) {
+        console.log("[GallerySyncService] ✅ App returned to foreground")
+        console.log("[GallerySyncService] ⏱️ Time spent in background:", Date.now() - (appBackgroundTime || 0), "ms")
+      }
+    }
+
+    const appStateSubscription = AppState.addEventListener("change", appStateHandler)
+    console.log("[GallerySyncService] 👂 App state listener registered")
+
+    // L2: Wrap retry loop in try/finally to guarantee listener cleanup on all exit paths
+    try {
+      for (let attempt = 1; attempt <= TIMING.IOS_WIFI_MAX_RETRIES; attempt++) {
+        const attemptStartTime = Date.now()
+
+        // Check if cancelled
+        if (this.abortController?.signal.aborted) {
+          console.log("[GallerySyncService] 🛑 Sync was cancelled - aborting WiFi connection")
+          store.setSyncError("Sync cancelled")
+          return
+        }
+
+        try {
+          console.log("[GallerySyncService] ----------------------------------------")
+          console.log(
+            `[GallerySyncService] 📡 ATTEMPT ${attempt}/${TIMING.IOS_WIFI_MAX_RETRIES} - Starting WiFi connection`,
+          )
+          console.log(`[GallerySyncService] ⏱️ Time since WiFi phase started: ${Date.now() - wifiConnectStartTime}ms`)
+          console.log(`[GallerySyncService] 📱 App backgrounded during connection: ${appBackgrounded}`)
+
+          // Check current WiFi state before attempting connection
+          let preConnectSSID = "unknown"
+          try {
+            preConnectSSID = await WifiManager.getCurrentWifiSSID()
+            console.log(`[GallerySyncService] 📡 Current WiFi SSID: "${preConnectSSID}"`)
+
+            // Check if already connected (shouldn't happen, but good to verify)
+            if (preConnectSSID === hotspotInfo.ssid) {
+              console.log("[GallerySyncService] ✅ Already connected to target SSID! Proceeding to download.")
+              appStateSubscription.remove()
+
+              const totalWifiDuration = Date.now() - wifiConnectStartTime
+              console.log("[GallerySyncService] ========================================")
+              console.log("[GallerySyncService] ✅ WIFI CONNECTION COMPLETE (already connected)")
+              console.log("[GallerySyncService] ========================================")
+              console.log(`[GallerySyncService] ⏱️ Total WiFi phase duration: ${totalWifiDuration}ms`)
+              console.log(`[GallerySyncService] 🚀 Proceeding to file download from ${hotspotInfo.ip}:8089`)
+
+              await this.startFileDownload(hotspotInfo)
+              return // Exit function successfully
+            }
+          } catch (preError: any) {
+            console.warn(`[GallerySyncService] ⚠️ Could not get current SSID: ${preError?.message}`)
+            console.warn("[GallerySyncService] ⚠️ Error code:", preError?.code)
+          }
+
+          // Use connectToProtectedSSID with joinOnce=false for persistent connection
+          console.log(`[GallerySyncService] 🔌 Calling WifiManager.connectToProtectedSSID...`)
+          console.log(`[GallerySyncService] 🔌 Parameters:`)
+          console.log(`[GallerySyncService]    - SSID: "${hotspotInfo.ssid}"`)
+          console.log(`[GallerySyncService]    - Password: ${"*".repeat(hotspotInfo.password.length)}`)
+          console.log(`[GallerySyncService]    - joinOnce: false`)
+          console.log(`[GallerySyncService]    - isHidden: false`)
+
+          const connectCallStartTime = Date.now()
+          appBackgrounded = false // Reset flag for this attempt
+          appBackgroundTime = null
+
+          await WifiManager.connectToProtectedSSID(hotspotInfo.ssid, hotspotInfo.password, false, false)
+
+          const connectCallDuration = Date.now() - connectCallStartTime
+          console.log(`[GallerySyncService] ✅ WifiManager.connectToProtectedSSID returned successfully`)
+          console.log(`[GallerySyncService] ⏱️ Library call duration: ${connectCallDuration}ms`)
+          console.log(`[GallerySyncService] 📱 App was backgrounded during call: ${appBackgrounded}`)
+          if (appBackgrounded && appBackgroundTime) {
+            console.log(
+              `[GallerySyncService] ⏱️ Time until backgrounding: ${appBackgroundTime - connectCallStartTime}ms`,
+            )
+          }
+          console.log(`[GallerySyncService] 📝 Note: On iOS, this does NOT guarantee actual connection!`)
+
+          // iOS-specific: Verify actual WiFi connection by polling SSID
+          // The library promise resolves when iOS ACCEPTS the request, not when connection completes
+          if (Platform.OS === "ios") {
+            console.log(`[GallerySyncService] 🍎 iOS: Starting connection verification...`)
+            console.log(`[GallerySyncService] 🍎 Will poll getCurrentWifiSSID() for up to 15 seconds`)
+
+            const maxVerifyAttempts = 30 // 30 × 500ms = 15 seconds
+            let connected = false
+            let lastSeenSSID = "unknown"
+
+            for (let i = 0; i < maxVerifyAttempts; i++) {
+              try {
+                const currentSSID = await WifiManager.getCurrentWifiSSID()
+                lastSeenSSID = currentSSID || "null"
+
+                console.log(
+                  `[GallerySyncService] 🍎 Verify poll ${i + 1}/${maxVerifyAttempts}: Current="${currentSSID}", Target="${
+                    hotspotInfo.ssid
+                  }"`,
+                )
+
+                if (currentSSID === hotspotInfo.ssid) {
+                  console.log(
+                    `[GallerySyncService] 🍎 ✅ VERIFICATION SUCCESS! Connected to target network after ${
+                      (i + 1) * 500
+                    }ms`,
+                  )
+                  connected = true
+                  break
+                } else if (i === 0 && currentSSID === lastSeenSSID) {
+                  console.log(
+                    `[GallerySyncService] 🍎 ⚠️ Still on original network - iOS dialog may not have appeared yet`,
+                  )
+                }
+              } catch (ssidError: any) {
+                console.log(`[GallerySyncService] 🍎 ⚠️ Poll ${i + 1}: Could not check SSID: ${ssidError?.message}`)
+                lastSeenSSID = "error"
+              }
+
+              // Don't wait after last attempt
+              if (i < maxVerifyAttempts - 1) {
+                await new Promise<void>((resolve) => BgTimer.setTimeout(() => resolve(), 500))
+              }
+            }
+
+            if (!connected) {
+              console.error(`[GallerySyncService] 🍎 ❌ VERIFICATION FAILED after 15 seconds`)
+              console.error(`[GallerySyncService] 🍎 Last seen SSID: "${lastSeenSSID}"`)
+              console.error(`[GallerySyncService] 🍎 Expected SSID: "${hotspotInfo.ssid}"`)
+              console.error(`[GallerySyncService] 🍎 Possible causes:`)
+              console.error(`[GallerySyncService] 🍎   1. User did not tap "Join" on iOS WiFi dialog`)
+              console.error(`[GallerySyncService] 🍎   2. iOS dialog did not appear (permission issue?)`)
+              console.error(`[GallerySyncService] 🍎   3. iOS refused to switch networks`)
+              throw new Error(
+                `iOS WiFi verification failed - still on "${lastSeenSSID}", expected "${hotspotInfo.ssid}"`,
+              )
+            }
+          }
+
+          const attemptDuration = Date.now() - attemptStartTime
+          console.log(`[GallerySyncService] ✅ WiFi connection successful!`)
+          console.log(`[GallerySyncService] ⏱️ Total attempt duration: ${attemptDuration}ms`)
+          console.log(`[GallerySyncService] 🎉 Platform: ${Platform.OS}`)
+
+          // Remove app state listener
+          appStateSubscription.remove()
+          console.log("[GallerySyncService] 👂 App state listener removed")
+
+          // Final verification: Check SSID one more time before starting download
+          try {
+            const finalSSID = await WifiManager.getCurrentWifiSSID()
+            console.log(`[GallerySyncService] 📶 Final SSID check before download: "${finalSSID}"`)
+            if (Platform.OS === "android") {
+              // Some local builds can have stale generated typings for the Bluetooth SDK module.
+              ;(BluetoothSdk as any).logCurrentWifiFrequency?.()
+            }
+            if (finalSSID !== hotspotInfo.ssid) {
+              console.error(
+                `[GallerySyncService] ❌ SSID mismatch detected! Expected "${hotspotInfo.ssid}", got "${finalSSID}"`,
+              )
+              throw new Error(`WiFi SSID mismatch - connected to "${finalSSID}" instead of "${hotspotInfo.ssid}"`)
+            }
+          } catch (finalError: any) {
+            console.warn(`[GallerySyncService] ⚠️ Could not perform final SSID check: ${finalError?.message}`)
+            // Continue anyway - we've done our best to verify
+          }
+
+          // iOS-specific: Wait for actual network connectivity to glasses
+          // Even though SSID is correct, iOS needs time for routing tables to update
+          // We actively probe the glasses HTTP server until it's reachable
+          if (Platform.OS === "ios") {
+            console.log(`[GallerySyncService] 🍎 Waiting for iOS network routes to glasses IP...`)
+            console.log(`[GallerySyncService] 🍎 Will probe http://${hotspotInfo.ip}:8089/api/health`)
+
+            const maxProbeAttempts = 20 // 20 attempts × 500ms = 10 seconds max
+            let networkReady = false
+
+            for (let probeNum = 1; probeNum <= maxProbeAttempts; probeNum++) {
+              try {
+                console.log(`[GallerySyncService] 🍎 Connectivity probe ${probeNum}/${maxProbeAttempts}...`)
+
+                // Try to reach the glasses health endpoint with a short timeout
+                const probeController = new AbortController()
+                const probeTimeout = BgTimer.setTimeout(() => probeController.abort(), 1000) // 1 second timeout per probe
+
+                const probeStartTime = Date.now()
+                const probeResponse = await fetch(`http://${hotspotInfo.ip}:8089/api/health`, {
+                  method: "GET",
+                  signal: probeController.signal,
+                })
+                BgTimer.clearTimeout(probeTimeout)
+
+                const probeDuration = Date.now() - probeStartTime
+                console.log(
+                  `[GallerySyncService] 🍎 Probe ${probeNum} response: HTTP ${probeResponse.status} (${probeDuration}ms)`,
+                )
+
+                if (probeResponse.status === 200 || probeResponse.status === 404) {
+                  // 200 = health endpoint exists, 404 = glasses responded (no health endpoint)
+                  // Either way, network is working!
+                  console.log(`[GallerySyncService] 🍎 ✅ Network connectivity verified after ${probeNum} probes!`)
+                  networkReady = true
+                  break
+                }
+              } catch (probeError: any) {
+                const errorMsg = probeError?.message || "unknown"
+                console.log(
+                  `[GallerySyncService] 🍎 Probe ${probeNum} failed: ${errorMsg.substring(0, 50)}${
+                    errorMsg.length > 50 ? "..." : ""
+                  }`,
+                )
+                // Continue to next probe
+              }
+
+              // Wait 500ms before next probe (unless this was the last attempt)
+              if (probeNum < maxProbeAttempts) {
+                await new Promise<void>((resolve) => BgTimer.setTimeout(() => resolve(), 500))
+              }
+            }
+
+            if (!networkReady) {
+              console.error(
+                `[GallerySyncService] 🍎 ❌ Network connectivity probe failed after ${maxProbeAttempts} attempts`,
+              )
+              console.error(`[GallerySyncService] 🍎 iOS routing tables may not be ready for ${hotspotInfo.ip}`)
+              throw new Error(
+                `iOS network not ready - could not reach ${hotspotInfo.ip}:8089 after ${maxProbeAttempts} attempts`,
+              )
+            }
+          }
+
+          // Start the actual download
+          const totalWifiDuration = Date.now() - wifiConnectStartTime
+          console.log("[GallerySyncService] ========================================")
+          console.log("[GallerySyncService] ✅ WIFI CONNECTION COMPLETE")
+          console.log("[GallerySyncService] ========================================")
+          console.log(`[GallerySyncService] ⏱️ Total WiFi phase duration: ${totalWifiDuration}ms`)
+          console.log(`[GallerySyncService] 🎯 Attempts used: ${attempt}/${TIMING.IOS_WIFI_MAX_RETRIES}`)
+          console.log(`[GallerySyncService] 🚀 Proceeding to file download from ${hotspotInfo.ip}:8089`)
+
+          await this.startFileDownload(hotspotInfo)
+          return // Success - exit the retry loop
+        } catch (error: any) {
+          lastError = error
+          const attemptDuration = Date.now() - attemptStartTime
+
+          console.error("[GallerySyncService] ❌ ========================================")
+          console.error(`[GallerySyncService] ❌ WiFi ATTEMPT ${attempt} FAILED`)
+          console.error("[GallerySyncService] ❌ ========================================")
+          console.error(`[GallerySyncService] ❌ Error message: ${error?.message || "No message"}`)
+          console.error(`[GallerySyncService] ❌ Error code: ${error?.code || "No code"}`)
+          console.error(`[GallerySyncService] ❌ Error type: ${error?.name || typeof error}`)
+          console.error(`[GallerySyncService] ❌ Platform: ${Platform.OS}`)
+          console.error(`[GallerySyncService] ❌ Attempt duration: ${attemptDuration}ms`)
+          console.error(`[GallerySyncService] ❌ App was backgrounded: ${appBackgrounded}`)
+          if (appBackgrounded && appBackgroundTime) {
+            console.error(`[GallerySyncService] ❌ Time in background: ${Date.now() - appBackgroundTime}ms`)
+          }
+          console.error(`[GallerySyncService] ❌ Full error object:`, JSON.stringify(error, null, 2))
+
+          // If user explicitly denied, don't retry
+          if (error?.code === "userDenied" || error?.message?.includes("cancel")) {
+            console.warn("[GallerySyncService] 🚫 User cancelled WiFi connection - aborting")
+            appStateSubscription.remove()
+            store.setSyncError("WiFi connection cancelled")
+            if (store.syncServiceOpenedHotspot) {
+              await this.closeHotspot()
+            }
+            return
+          }
+
+          // Handle "didNotFindNetwork" - hotspot may still be initializing
+          if (error?.code === "didNotFindNetwork") {
+            console.warn("[GallerySyncService] 🔍 Network not found - hotspot may still be initializing")
+            console.warn(
+              `[GallerySyncService] 🔍 Will retry in ${TIMING.IOS_WIFI_RETRY_DELAY_MS}ms (attempt ${attempt}/${TIMING.IOS_WIFI_MAX_RETRIES})`,
+            )
+          }
+
+          // Handle "timeoutOccurred" - likely caused by app backgrounding during WiFi dialog
+          if (error?.code === "timeoutOccurred") {
+            console.error("[GallerySyncService] ⏰ WiFi connection timeout occurred")
+            console.error(`[GallerySyncService] ⏰ App was backgrounded: ${appBackgrounded}`)
+            if (appBackgrounded && appBackgroundTime) {
+              console.error(`[GallerySyncService] ⏰ Time in background: ${Date.now() - appBackgroundTime}ms`)
+              console.error("[GallerySyncService] ⏰ Android may have shown WiFi dialog that user didn't interact with")
+            }
+            console.warn(
+              `[GallerySyncService] 🔍 Will retry in ${TIMING.IOS_WIFI_RETRY_DELAY_MS}ms (attempt ${attempt}/${TIMING.IOS_WIFI_MAX_RETRIES})`,
+            )
+          }
+
+          // DISABLED: Check if WiFi was disabled during connection attempt (Android 10+ specific error)
+          // if (Platform.OS === "android" && error?.message?.includes("enable wifi manually")) {
+          //   console.error("[GallerySyncService] WiFi was disabled during connection")
+          //
+          //   // Mark that we're waiting for WiFi so we can auto-retry when user returns
+          //   this.waitingForWifiRetry = true
+          //
+          //   showAlert("WiFi Required", "WiFi must be enabled to sync photos. Please enable WiFi and try again.", [
+          //     {
+          //       text: "Cancel",
+          //       style: "cancel",
+          //       onPress: () => {
+          //         this.waitingForWifiRetry = false
+          //         this.wifiSettingsOpenedAt = null
+          //         store.setSyncError("WiFi disabled - enable WiFi and try again")
+          //         if (store.syncServiceOpenedHotspot) {
+          //           this.closeHotspot()
+          //         }
+          //       },
+          //     },
+          //     {
+          //       text: "Open Settings",
+          //       onPress: async () => {
+          //         // Set timestamp so we can enforce cooldown on next sync attempt
+          //         this.wifiSettingsOpenedAt = Date.now()
+          //         await SettingsNavigationUtils.openWifiSettings()
+          //         store.setSyncError("Enable WiFi and try sync again")
+          //         if (store.syncServiceOpenedHotspot) {
+          //           await this.closeHotspot()
+          //         }
+          //       },
+          //     },
+          //   ])
+          //   return
+          // }
+
+          // Let connection fail naturally and show generic error
+          if (Platform.OS === "android" && error?.message?.includes("enable wifi manually")) {
+            console.error("[GallerySyncService] 🚫 WiFi was disabled during connection - aborting")
+            appStateSubscription.remove()
+            store.setSyncError("Could not connect - check WiFi is enabled")
+            if (store.syncServiceOpenedHotspot) {
+              await this.closeHotspot()
+            }
+            return
+          }
+
+          // For "internal error" or "unableToConnect", wait and retry
+          // iOS: Gives user time to interact with system dialog
+          // Android: Gives hotspot time to fully initialize and start broadcasting
+          if (attempt < TIMING.IOS_WIFI_MAX_RETRIES) {
+            const reason =
+              Platform.OS === "ios" ? "user may be seeing system dialog" : "hotspot may still be initializing"
+            console.log("[GallerySyncService] ----------------------------------------")
+            console.log(`[GallerySyncService] 🔄 Preparing retry ${attempt + 1}/${TIMING.IOS_WIFI_MAX_RETRIES}`)
+            console.log(`[GallerySyncService] ⏱️ Waiting ${TIMING.IOS_WIFI_RETRY_DELAY_MS}ms (${reason})`)
+            console.log(`[GallerySyncService] 📱 App currently: ${AppState.currentState}`)
+            await new Promise<void>((resolve) => BgTimer.setTimeout(() => resolve(), TIMING.IOS_WIFI_RETRY_DELAY_MS))
+            console.log(`[GallerySyncService] ⏱️ Wait complete - starting retry`)
+          } else {
+            console.error("[GallerySyncService] 🚫 No more retry attempts available")
+          }
+        }
+      }
+
+      // All retries exhausted
+      const totalWifiDuration = Date.now() - wifiConnectStartTime
+
+      console.error("[GallerySyncService] ❌ ========================================")
+      console.error("[GallerySyncService] ❌ WIFI CONNECTION FAILED - ALL RETRIES EXHAUSTED")
+      console.error("[GallerySyncService] ❌ ========================================")
+      console.error(`[GallerySyncService] ❌ Platform: ${Platform.OS}`)
+      console.error(`[GallerySyncService] ❌ Total attempts: ${TIMING.IOS_WIFI_MAX_RETRIES}`)
+      console.error(`[GallerySyncService] ❌ Total duration: ${totalWifiDuration}ms`)
+      console.error(`[GallerySyncService] ❌ App was backgrounded at some point: ${appBackgrounded}`)
+      console.error(`[GallerySyncService] ❌ Last error message: ${lastError?.message || "No message"}`)
+      console.error(`[GallerySyncService] ❌ Last error code: ${lastError?.code || "No code"}`)
+      console.error("[GallerySyncService] ❌ ========================================")
+
+      // Provide user-friendly error message based on error type
+      let userErrorMessage = lastError?.message || "Failed to connect to glasses WiFi"
+
+      if (lastError?.code === "timeoutOccurred" && appBackgrounded) {
+        userErrorMessage =
+          "WiFi connection timed out. Android may be blocking automatic WiFi switching. Please manually connect to the glasses hotspot in Settings."
+      } else if (lastError?.message?.includes("internal error")) {
+        userErrorMessage =
+          "Could not connect to glasses WiFi. Please ensure you accept the WiFi prompt when it appears."
+      }
+
+      store.setSyncError(userErrorMessage)
+
+      if (store.syncServiceOpenedHotspot) {
+        await this.closeHotspot()
+      }
+    } finally {
+      // L2: Guarantee listener cleanup on all exit paths (cancel, success, error, exhaustion)
+      appStateSubscription.remove()
+    }
+  }
+
+  private async fetchSyncManifest(clientId: string, lastSyncTime: number): Promise<SyncManifestData> {
+    const syncResponse = await asgCameraApi.syncWithServer(clientId, lastSyncTime, true)
+    return (syncResponse.data || syncResponse) as SyncManifestData
+  }
+
+  /**
+   * Resolve sync manifest: detect skew, optionally fix clock, retry full sync when needed.
+   */
+  private async resolveSyncManifest(
+    clientId: string,
+    lastSyncTime: number,
+  ): Promise<{syncData: SyncManifestData; usedFullSync: boolean} | null> {
+    const store = useGallerySyncStore.getState()
+    let syncData = await this.fetchSyncManifest(clientId, lastSyncTime)
+    let clockFixed = false
+
+    const skewOnFirst = detectClockSkew(Date.now(), syncData.server_time, lastSyncTime)
+    if (skewOnFirst.skewed) {
+      clockFixed = await fixGlassesClockIfSkewed(syncData.server_time, lastSyncTime)
+      if (clockFixed) {
+        console.log("[GallerySyncService]   🔄 Retrying /api/sync with last_sync_time=0 after clock fix")
+        syncData = await this.fetchSyncManifest(clientId, 0)
+      }
+    }
+
+    if (!isSyncManifestEmpty(syncData)) {
+      return {syncData, usedFullSync: clockFixed || lastSyncTime === 0}
+    }
+
+    // Guard against re-firing the full-sync retry every sync when glasses retain leftover files
+    // from a failed delete-from-glasses: at most one retry per (client_id, last_sync_time) pair
+    // per process lifetime. Without this, we'd re-download the entire gallery on every sync.
+    const retryKey = `${clientId}:${lastSyncTime}`
+    const alreadyRetriedForThisWatermark = this.lastFullSyncRetryKey === retryKey
+    if (!clockFixed && store.glassesHasContent && lastSyncTime !== 0 && !alreadyRetriedForThisWatermark) {
+      this.lastFullSyncRetryKey = retryKey
+      console.log("[GallerySyncService]   🔄 Empty sync but glasses report content — retrying with last_sync_time=0")
+      syncData = await this.fetchSyncManifest(clientId, 0)
+      if (!isSyncManifestEmpty(syncData)) {
+        return {syncData, usedFullSync: true}
+      }
+    } else if (!clockFixed && store.glassesHasContent && lastSyncTime !== 0 && alreadyRetriedForThisWatermark) {
+      console.warn(
+        "[GallerySyncService]   ⚠️ Glasses still report content but /api/sync empty — already retried this watermark, skipping to avoid re-download loop",
+      )
+    }
+
+    if (store.glassesHasContent) {
+      console.warn("[GallerySyncService]   ⚠️ Empty sync while glasses still report gallery content")
+      return null
+    }
+
+    return {syncData, usedFullSync: false}
+  }
+
+  /**
+   * Start downloading files
+   */
+  private async startFileDownload(hotspotInfo: HotspotInfo): Promise<void> {
+    const store = useGallerySyncStore.getState()
+
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] 📥 Step 5/6: Starting file download phase")
+    console.log("[GallerySyncService] ========================================")
+    console.log(`[GallerySyncService]   🌐 Server: ${hotspotInfo.ip}:8089`)
+
+    try {
+      // Set up the API client
+      asgCameraApi.setServer(hotspotInfo.ip, 8089)
+      console.log("[GallerySyncService]   ✅ API client configured")
+
+      // Get sync state and files to download
+      // IMPORTANT: This creates a SNAPSHOT of files at this moment based on last_sync_time.
+      // Any photos taken AFTER this call (during the sync) will NOT be included in this sync.
+      // They will be detected in the next sync when we query gallery status again.
+      console.log("[GallerySyncService]   📊 Fetching sync state from local storage...")
+      const syncState = await localStorageService.getSyncState()
+      console.log("[GallerySyncService]   📊 Sync state:", {
+        client_id: syncState.client_id,
+        last_sync_time: syncState.last_sync_time,
+        last_sync_date: syncState.last_sync_time > 0 ? new Date(syncState.last_sync_time).toISOString() : "Never",
+        total_downloaded: syncState.total_downloaded,
+        total_size: `${(syncState.total_size / 1024 / 1024).toFixed(2)} MB`,
+      })
+
+      console.log("[GallerySyncService]   📡 Calling /api/sync endpoint...")
+      const syncStartTime = Date.now()
+      const resolved = await this.resolveSyncManifest(syncState.client_id, syncState.last_sync_time)
+      const _syncDuration = Date.now() - syncStartTime
+      console.log(`[GallerySyncService]   ✅ /api/sync completed in ${_syncDuration}ms`)
+
+      if (!resolved) {
+        const syncErrorMessage = "Could not sync gallery — try again"
+        store.setSyncError(syncErrorMessage)
+        await gallerySyncNotifications.showSyncError(syncErrorMessage)
+        if (store.syncServiceOpenedHotspot) {
+          await this.closeHotspot()
+        }
+        return
+      }
+
+      const {syncData} = resolved
+
+      console.log("[GallerySyncService]   📋 Sync response received:")
+      console.log(`[GallerySyncService]      - Server time: ${syncData.server_time}`)
+      console.log(`[GallerySyncService]      - Changed files: ${syncData.changed_files?.length || 0}`)
+      console.log(`[GallerySyncService]      - Captures: ${syncData.captures?.length || 0}`)
+
+      if (isSyncManifestEmpty(syncData)) {
+        console.log("[GallerySyncService]   ✅ No new files to sync - already up to date!")
+        store.setSyncComplete()
+        await this.onSyncComplete(0, 0)
+        return
+      }
+
+      // Detect API version and route to appropriate download path
+      const useCaptures = syncData.api_version === 2 && syncData.captures && syncData.captures.length > 0
+
+      if (useCaptures) {
+        // New capture-aware sync path
+        const captures: CaptureGroup[] = syncData.captures!
+        console.log(`[GallerySyncService]   📊 Found ${captures.length} captures to download (api_version=2)`)
+
+        captures.slice(0, 5).forEach((c: CaptureGroup, idx: number) => {
+          console.log(
+            `[GallerySyncService]      ${idx + 1}. ${c.capture_id} (${c.type}, ${c.files.length} files, ${(
+              c.total_size / 1024
+            ).toFixed(1)} KB)`,
+          )
+        })
+        if (captures.length > 5) {
+          console.log(`[GallerySyncService]      ... and ${captures.length - 5} more captures`)
+        }
+
+        // Build a PhotoInfo[] for the store (one per capture, using primary file info)
+        const capturePhotoInfos: PhotoInfo[] = captures.map((c) => {
+          const primaryFile = c.files.find((f) => f.role === "primary") || c.files[0]
+          return {
+            name: c.capture_id,
+            url: `/api/photo?file=${encodeURIComponent(primaryFile.name)}`,
+            download: `/api/download?file=${encodeURIComponent(primaryFile.name)}`,
+            size: c.total_size,
+            modified: c.timestamp,
+            is_video: c.type === "video",
+            thumbnail_data: c.thumbnail_data,
+            duration: c.duration,
+          }
+        })
+
+        store.setSyncing(capturePhotoInfos)
+
+        await localStorageService.saveSyncQueue({
+          files: capturePhotoInfos,
+          currentIndex: 0,
+          startedAt: Date.now(),
+          hotspotInfo,
+        })
+
+        await gallerySyncNotifications.showSyncStarted(captures.length)
+
+        console.log("[GallerySyncService]   🚀 Beginning capture download execution...")
+        await this.executeCaptureDownload(captures, syncData.server_time)
+      } else {
+        // Legacy flat file sync path
+        const filesToSync = syncData.changed_files
+        // Count only user-visible media files (exclude HDR brackets and IMU sidecars)
+        const userVisibleCount = filesToSync.filter(
+          (f: any) => !f.name?.match(/_ev-?\d+\.(jpg|jpeg)$/i) && !f.name?.match(/\.imu\.json$/i),
+        ).length
+        console.log(
+          `[GallerySyncService]   📊 Found ${filesToSync.length} files to download (${userVisibleCount} media items, legacy path):`,
+        )
+
+        console.log("[GallerySyncService]   📋 First 5 files:")
+        filesToSync.slice(0, 5).forEach((_file: any, _idx: number) => {
+          console.log(
+            `[GallerySyncService]      ${_idx + 1}. ${_file.name} (${_file.is_video ? "video" : "photo"}, ${(
+              _file.size / 1024
+            ).toFixed(1)} KB)`,
+          )
+        })
+        if (filesToSync.length > 5) {
+          console.log(`[GallerySyncService]      ... and ${filesToSync.length - 5} more files`)
+        }
+
+        store.setSyncing(filesToSync)
+
+        await localStorageService.saveSyncQueue({
+          files: filesToSync,
+          currentIndex: 0,
+          startedAt: Date.now(),
+          hotspotInfo,
+        })
+
+        await gallerySyncNotifications.showSyncStarted(userVisibleCount)
+
+        console.log("[GallerySyncService]   🚀 Beginning download execution (legacy)...")
+        await this.executeDownload(filesToSync, syncData.server_time)
+      }
+    } catch (error: any) {
+      console.error("[GallerySyncService] Failed to start download:", error)
+      store.setSyncError(error?.message || "Failed to start download")
+      await gallerySyncNotifications.showSyncError("Failed to start download")
+
+      if (store.syncServiceOpenedHotspot) {
+        await this.closeHotspot()
+      }
+    }
+  }
+
+  /**
+   * Execute the actual file download.
+   * Used for old asg_client firmware that doesn't send api_version=2 / captures.
+   * NOTE: The sidecar/bracket filtering within is likely dead code — old firmware
+   * only produces flat photos/videos with no sidecars or HDR brackets.
+   */
+  private async executeDownload(files: PhotoInfo[], serverTime: number): Promise<void> {
+    const downloadStartTime = Date.now()
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] ⬇️ DOWNLOAD EXECUTION STARTED")
+    console.log("[GallerySyncService] ========================================")
+    console.log(`[GallerySyncService]   📊 Files to download: ${files.length}`)
+
+    const store = useGallerySyncStore.getState()
+    const settingsStore = useSettingsStore.getState()
+    const defaultWearable = settingsStore.getSetting(SETTINGS.default_wearable.key)
+
+    let downloadedCount = 0
+    let failedCount = 0
+
+    // Check if auto-save to camera roll is enabled (we'll save each file immediately after download)
+    const shouldAutoSave = await gallerySettingsService.getAutoSaveToCameraRoll()
+    const shouldProcessImages = useSettingsStore.getState().getSetting(SETTINGS.media_post_processing.key)
+    console.log(`[GallerySyncService]   📸 Auto-save to camera roll: ${shouldAutoSave}`)
+    console.log(`[GallerySyncService]   🎨 Image processing: ${shouldProcessImages}`)
+
+    try {
+      const downloadResult = await asgCameraApi.batchSyncFiles(
+        files,
+        true,
+        (current, total, fileName, fileProgress, downloadedFile) => {
+          // CRITICAL: This callback MUST NOT throw!
+          // RNFS progress callbacks run inside native bridge — throwing here causes
+          // EXC_BAD_ACCESS. Cancellation is handled via AbortSignal → RNFS.stopDownload.
+
+          // Check if cancelled — just return, abort signal will stop the download
+          if (this.abortController?.signal.aborted) {
+            return
+          }
+
+          // Update store
+          const currentStore = useGallerySyncStore.getState()
+
+          if (fileProgress === 0 || fileProgress === undefined) {
+            // Starting a new file - but only mark previous complete if this is a NEW file
+            // (not just another 0% progress report for the same file)
+            // This prevents double-counting when both batchSyncFiles and RNFS report 0%
+            const isNewFile = currentStore.currentFile !== fileName
+
+            if (isNewFile) {
+              // Mark previous file as complete when moving to next
+              if (current > 1 && currentStore.currentFile) {
+                currentStore.onFileComplete(currentStore.currentFile)
+                // Persist queue index so we can resume from here if app is killed
+                localStorageService.updateSyncQueueIndex(current - 1).catch((err) => {
+                  console.error("[GallerySyncService] Failed to persist queue index:", err)
+                })
+              }
+              // Now set the new current file
+              currentStore.setCurrentFile(fileName, 0)
+            }
+          } else {
+            currentStore.onFileProgress(fileName, fileProgress || 0)
+          }
+
+          // When file completes (100%), update it in the queue with downloaded paths
+          if (fileProgress === 100 && downloadedFile) {
+            // Update file with local paths and URLs for immediate preview display
+            const localFileUrl = downloadedFile.filePath
+              ? downloadedFile.filePath.startsWith("file://")
+                ? downloadedFile.filePath
+                : `file://${downloadedFile.filePath}`
+              : downloadedFile.url
+
+            const localThumbnailUrl = downloadedFile.thumbnailPath
+              ? downloadedFile.thumbnailPath.startsWith("file://")
+                ? downloadedFile.thumbnailPath
+                : `file://${downloadedFile.thumbnailPath}`
+              : undefined
+
+            const updatedFile = {
+              ...downloadedFile,
+              url: localFileUrl, // Update URL to local file for immediate preview
+              download: localFileUrl, // Update download URL for videos
+              filePath: downloadedFile.filePath,
+              thumbnailPath: localThumbnailUrl,
+            }
+            currentStore.updateFileInQueue(fileName, updatedFile)
+
+            // 🎯 IMMEDIATELY process + save to camera roll if enabled
+            if (downloadedFile.filePath) {
+              // Parse the capture timestamp from the photo metadata
+              let captureTime: number | undefined
+              if (downloadedFile.modified) {
+                captureTime =
+                  typeof downloadedFile.modified === "string"
+                    ? parseInt(downloadedFile.modified, 10)
+                    : downloadedFile.modified
+                if (isNaN(captureTime)) {
+                  console.warn(
+                    `[GallerySyncService] Invalid modified timestamp for ${downloadedFile.name}:`,
+                    downloadedFile.modified,
+                  )
+                  captureTime = undefined
+                }
+              }
+
+              // Enqueue for background processing (non-blocking)
+              const isVideo = downloadedFile.name?.match(/\.(mp4|mov)$/i)
+              const leaf = downloadedFile.name?.includes("/")
+                ? downloadedFile.name.substring(downloadedFile.name.lastIndexOf("/") + 1)
+                : downloadedFile.name
+              const isImuSidecar = leaf?.match(/^imu\.json$/i)
+              const isHdrBracket = leaf?.match(/^ev-?\d+\.jpe?g$/i)
+
+              if (!isImuSidecar && !isHdrBracket && downloadedFile.filePath) {
+                const imuSidecarPath = downloadedFile.filePath.replace(/\.[^.]+$/, ".imu.json")
+                mediaProcessingQueue.enqueue({
+                  id: downloadedFile.name,
+                  type: isVideo ? "video" : "photo",
+                  primaryPath: downloadedFile.filePath,
+                  sidecarPath: isVideo ? imuSidecarPath : undefined,
+                  timestamp: captureTime,
+                  totalSize: downloadedFile.size,
+                  duration: downloadedFile.duration,
+                  glassesModel: defaultWearable,
+                  shouldProcess: !!shouldProcessImages,
+                  shouldAutoSave: !!shouldAutoSave,
+                  thumbnailPath: downloadedFile.thumbnailPath,
+                  deleteFromGlasses: [downloadedFile.name],
+                })
+              }
+            }
+          }
+
+          // Update notification
+          gallerySyncNotifications.updateProgress(current, total, fileName, fileProgress || 0)
+        },
+        this.abortController?.signal,
+      )
+
+      downloadedCount = downloadResult.downloaded.length
+      failedCount = downloadResult.failed.length
+
+      const downloadDuration = Date.now() - downloadStartTime
+      console.log("[GallerySyncService] ========================================")
+      console.log("[GallerySyncService] ✅ DOWNLOAD EXECUTION COMPLETE")
+      console.log("[GallerySyncService] ========================================")
+      console.log("[GallerySyncService]   📊 Results:")
+      console.log(`[GallerySyncService]      - Downloaded: ${downloadedCount}`)
+      console.log(`[GallerySyncService]      - Failed: ${failedCount}`)
+      console.log(`[GallerySyncService]      - Duration: ${(downloadDuration / 1000).toFixed(1)}s`)
+      console.log(`[GallerySyncService]      - Total size: ${(downloadResult.total_size / 1024 / 1024).toFixed(2)} MB`)
+      if (downloadDuration > 0 && downloadResult.total_size > 0) {
+        const _speedMbps = downloadResult.total_size / 1024 / 1024 / (downloadDuration / 1000)
+        console.log(`[GallerySyncService]      - Avg speed: ${_speedMbps.toFixed(2)} MB/s`)
+      }
+
+      // Mark the last file as complete (if any files were downloaded)
+      if (downloadResult.downloaded.length > 0) {
+        const lastFileName = downloadResult.downloaded[downloadResult.downloaded.length - 1]?.name
+        if (lastFileName) {
+          const currentStore = useGallerySyncStore.getState()
+          currentStore.onFileComplete(lastFileName)
+        }
+      }
+
+      // Save downloaded files metadata (skip auxiliary files from gallery entries)
+      for (const photoInfo of downloadResult.downloaded) {
+        // Skip HDR brackets and IMU sidecars — they shouldn't appear as separate gallery items
+        const isAuxiliary =
+          photoInfo.name?.match(/_ev-?\d+\.(jpg|jpeg)$/i) ||
+          photoInfo.name?.match(/\.imu\.json$/i) ||
+          photoInfo.name?.match(/\/ev-?\d+\.jpe?g$/i) ||
+          photoInfo.name?.match(/\/imu\.json$/i)
+        if (isAuxiliary) continue
+
+        const downloadedFile = localStorageService.convertToDownloadedFile(
+          photoInfo,
+          photoInfo.filePath || "",
+          photoInfo.thumbnailPath,
+          defaultWearable,
+        )
+        await localStorageService.saveDownloadedFile(downloadedFile)
+      }
+
+      // Update queue index to final position
+      await localStorageService.updateSyncQueueIndex(files.length)
+
+      // Mark failed files in store
+      for (const failedFileName of downloadResult.failed) {
+        const currentStore = useGallerySyncStore.getState()
+        currentStore.onFileFailed(failedFileName)
+      }
+
+      // Wait for processing queue to finish before marking complete
+      console.log("[GallerySyncService]   ⏳ Waiting for processing queue to drain...")
+      await mediaProcessingQueue.waitUntilDrained()
+      console.log("[GallerySyncService]   ✅ Processing queue drained")
+
+      // Update sync state — only advance watermark if files were downloaded.
+      // If any failed, set it before the oldest failure so they get retried.
+      let syncWatermark = serverTime
+      if (downloadedCount === 0) {
+        const currentSyncState = await localStorageService.getSyncState()
+        syncWatermark = currentSyncState.last_sync_time
+        console.log("[GallerySyncService]   ℹ️ No files downloaded — last_sync_time unchanged")
+      } else if (downloadResult.failed.length > 0) {
+        const failedSet = new Set(downloadResult.failed)
+        let oldestFailed = Infinity
+        for (const f of files) {
+          if (failedSet.has(f.name)) {
+            const ts = typeof f.modified === "number" ? f.modified : parseInt(String(f.modified), 10)
+            if (!isNaN(ts) && ts < oldestFailed) oldestFailed = ts
+          }
+        }
+        if (oldestFailed < Infinity) {
+          syncWatermark = Math.max(0, oldestFailed - 1)
+          console.log(
+            `[GallerySyncService]   ⚠️ ${downloadResult.failed.length} files failed — sync watermark set to ${syncWatermark} instead of ${serverTime}`,
+          )
+        }
+      } else {
+        let maxModified = 0
+        const failedSet = new Set(downloadResult.failed)
+        for (const f of files) {
+          if (failedSet.has(f.name)) continue
+          const ts = typeof f.modified === "number" ? f.modified : parseInt(String(f.modified), 10)
+          if (!isNaN(ts)) maxModified = Math.max(maxModified, ts)
+        }
+        if (maxModified > 0) {
+          syncWatermark = maxModified
+        }
+      }
+      console.log("[GallerySyncService]   💾 Updating sync state in local storage...")
+      const currentSyncState = await localStorageService.getSyncState()
+      // Persist if we downloaded anything OR if a failure needs the watermark rolled back.
+      // (Otherwise a clock-skew-triggered full sync where every legacy file fails would
+      // leave the stale future watermark on disk and never retry those files.)
+      if (downloadedCount > 0 || downloadResult.failed.length > 0) {
+        await localStorageService.updateSyncState({
+          last_sync_time: syncWatermark,
+          total_downloaded: currentSyncState.total_downloaded + downloadedCount,
+          total_size: currentSyncState.total_size + downloadResult.total_size,
+        })
+      }
+      console.log("[GallerySyncService]   ✅ Sync state updated:")
+      console.log(
+        `[GallerySyncService]      - New last_sync_time: ${syncWatermark} (${new Date(syncWatermark).toISOString()})`,
+      )
+      console.log(
+        `[GallerySyncService]      - Total downloads (lifetime): ${
+          currentSyncState.total_downloaded + downloadedCount
+        }`,
+      )
+      console.log(
+        `[GallerySyncService]      - Total data (lifetime): ${(
+          (currentSyncState.total_size + downloadResult.total_size) /
+          1024 /
+          1024
+        ).toFixed(2)} MB`,
+      )
+
+      // Complete
+      store.setSyncComplete()
+      await this.onSyncComplete(downloadedCount, failedCount)
+    } catch (error: any) {
+      mediaProcessingQueue.abort()
+      if (error?.message === "Sync cancelled") {
+        console.log("[GallerySyncService] Sync was cancelled")
+        store.setSyncCancelled()
+        await gallerySyncNotifications.showSyncCancelled()
+      } else {
+        console.error("[GallerySyncService] Download failed:", error)
+        store.setSyncError(error?.message || "Download failed")
+        await gallerySyncNotifications.showSyncError(error?.message || "Download failed")
+      }
+
+      if (store.syncServiceOpenedHotspot) {
+        await this.closeHotspot()
+      }
+    }
+  }
+
+  /**
+   * Execute capture-aware download (api_version=2).
+   * Downloads captures as groups, runs HDR merge, saves single metadata entry per capture.
+   */
+  private async executeCaptureDownload(captures: CaptureGroup[], serverTime: number): Promise<void> {
+    const downloadStartTime = Date.now()
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] ⬇️ CAPTURE DOWNLOAD EXECUTION STARTED")
+    console.log("[GallerySyncService] ========================================")
+    console.log(`[GallerySyncService]   📊 Captures to download: ${captures.length}`)
+
+    const store = useGallerySyncStore.getState()
+    const settingsStore = useSettingsStore.getState()
+    const defaultWearable = settingsStore.getSetting(SETTINGS.default_wearable.key)
+
+    let downloadedCount = 0
+    let failedCount = 0
+    let totalSizeDownloaded = 0
+    let oldestFailedTimestamp = Infinity // Track for sync watermark
+    let maxSuccessfulTimestamp = 0
+
+    const shouldAutoSave = await gallerySettingsService.getAutoSaveToCameraRoll()
+    const shouldProcessImages = useSettingsStore.getState().getSetting(SETTINGS.media_post_processing.key)
+
+    try {
+      for (let i = 0; i < captures.length; i++) {
+        const capture = captures[i]
+
+        // Check cancellation
+        if (this.abortController?.signal.aborted) {
+          throw new Error("Sync cancelled")
+        }
+
+        // Update store progress
+        const currentStore = useGallerySyncStore.getState()
+        if (i > 0) {
+          // Mark previous capture as complete
+          currentStore.onFileComplete(captures[i - 1].capture_id)
+          await localStorageService.updateSyncQueueIndex(i)
+        }
+        currentStore.setCurrentFile(capture.capture_id, 0)
+
+        try {
+          console.log(
+            `[GallerySyncService]   📦 Downloading capture ${i + 1}/${captures.length}: ${capture.capture_id} (${capture.files.length} files)`,
+          )
+
+          validateCaptureMetadataForDownload(capture)
+
+          // Download all files in this capture
+          const result = await asgCameraApi.downloadCapture(
+            capture,
+            (bytesDownloaded, totalBytes) => {
+              // Don't throw in progress callbacks — abort signal stops the download
+              if (this.abortController?.signal.aborted) return
+              const progress = totalBytes > 0 ? Math.round((bytesDownloaded / totalBytes) * 100) : 0
+              const cs = useGallerySyncStore.getState()
+              cs.onFileProgress(capture.capture_id, Math.min(progress, 99))
+              gallerySyncNotifications.updateProgress(i + 1, captures.length, capture.capture_id, progress)
+            },
+            this.abortController?.signal,
+          )
+
+          // Mark 100% progress
+          const cs2 = useGallerySyncStore.getState()
+          cs2.onFileProgress(capture.capture_id, 100)
+
+          totalSizeDownloaded += capture.total_size
+          downloadedCount++
+          if (capture.timestamp > maxSuccessfulTimestamp) {
+            maxSuccessfulTimestamp = capture.timestamp
+          }
+
+          // Enqueue for processing (runs concurrently with next download)
+          // Delete from glasses happens after processing completes to avoid data loss on crash
+          mediaProcessingQueue.enqueue({
+            id: capture.capture_id,
+            type: capture.type,
+            primaryPath: result.primaryPath,
+            bracketPaths: result.bracketPaths,
+            sidecarPath: result.sidecarPath,
+            thumbnailData: capture.thumbnail_data,
+            captureDir: result.captureDir,
+            timestamp: capture.timestamp,
+            totalSize: capture.total_size,
+            duration: capture.duration,
+            glassesModel: defaultWearable,
+            shouldProcess: !!shouldProcessImages,
+            shouldAutoSave: !!shouldAutoSave,
+            deleteFromGlasses: [capture.capture_id],
+          })
+        } catch (captureError: any) {
+          if (captureError?.message === "Sync cancelled") throw captureError
+          const errMsg = captureError?.message || captureError?.toString?.() || JSON.stringify(captureError)
+          console.error(`[GallerySyncService]   ❌ Failed to download capture ${capture.capture_id}: ${errMsg}`)
+          failedCount++
+          // Track oldest failed timestamp so we don't advance sync past it
+          if (capture.timestamp < oldestFailedTimestamp) {
+            oldestFailedTimestamp = capture.timestamp
+          }
+          const cs = useGallerySyncStore.getState()
+          cs.onFileFailed(capture.capture_id)
+        }
+      }
+
+      // Mark last capture as complete
+      if (captures.length > 0) {
+        const lastCapture = captures[captures.length - 1]
+        const cs = useGallerySyncStore.getState()
+        cs.onFileComplete(lastCapture.capture_id)
+      }
+
+      await localStorageService.updateSyncQueueIndex(captures.length)
+
+      const downloadDuration = Date.now() - downloadStartTime
+      console.log("[GallerySyncService] ========================================")
+      console.log("[GallerySyncService] ✅ CAPTURE DOWNLOAD EXECUTION COMPLETE")
+      console.log("[GallerySyncService] ========================================")
+      console.log(`[GallerySyncService]   📊 Downloaded: ${downloadedCount}, Failed: ${failedCount}`)
+      console.log(`[GallerySyncService]   ⏱️ Duration: ${(downloadDuration / 1000).toFixed(1)}s`)
+
+      // Wait for processing queue to finish before marking complete
+      console.log("[GallerySyncService]   ⏳ Waiting for processing queue to drain...")
+      await mediaProcessingQueue.waitUntilDrained()
+      console.log("[GallerySyncService]   ✅ Processing queue drained")
+
+      // Reconcile failures from the processing queue. validateDownloadedMediaFile
+      // (post-download validation in mediaProcessingQueue) runs AFTER enqueue
+      // returns, so a failure there doesn't reach the per-capture catch above. The
+      // gallerySync store collects those failures via onFileFailed — pull them in
+      // here so the watermark holds them back for retry on the next sync.
+      const captureTimestampById = new Map<string, number>()
+      for (const c of captures) {
+        if (typeof c.timestamp === "number") {
+          captureTimestampById.set(c.capture_id, c.timestamp)
+        }
+      }
+      const failedSnapshot = useGallerySyncStore.getState().failedFiles
+      const observedFailures = new Set<string>(failedSnapshot)
+      for (const failedId of observedFailures) {
+        const ts = captureTimestampById.get(failedId)
+        if (ts === undefined) continue // failure from a different scope (e.g. file-level), skip
+        if (ts < oldestFailedTimestamp) {
+          oldestFailedTimestamp = ts
+        }
+      }
+      // failedCount should reflect the total set of failed captures from THIS batch.
+      const failedFromThisBatch = captures.filter((c) => observedFailures.has(c.capture_id)).length
+      if (failedFromThisBatch > failedCount) {
+        failedCount = failedFromThisBatch
+      }
+
+      // Update sync state — only advance watermark when captures were downloaded.
+      let syncWatermark = serverTime
+      const currentSyncState = await localStorageService.getSyncState()
+      if (failedCount > 0 && oldestFailedTimestamp < Infinity) {
+        // Failures take priority — roll the watermark back before the oldest failure so it
+        // gets retried, regardless of whether anything else succeeded in this batch.
+        syncWatermark = Math.max(0, oldestFailedTimestamp - 1)
+        console.log(
+          `[GallerySyncService]   ⚠️ ${failedCount} captures failed — sync watermark set to ${syncWatermark} instead of ${serverTime} so they will be retried`,
+        )
+      } else if (downloadedCount === 0) {
+        syncWatermark = currentSyncState.last_sync_time
+        console.log("[GallerySyncService]   ℹ️ No captures downloaded — last_sync_time unchanged")
+      } else if (maxSuccessfulTimestamp > 0) {
+        syncWatermark = maxSuccessfulTimestamp
+      }
+      // Persist if we downloaded anything OR if a failure needs the watermark rolled back
+      // (zero-byte / validation failures otherwise leave a stale watermark on disk).
+      if (downloadedCount > 0 || (failedCount > 0 && oldestFailedTimestamp < Infinity)) {
+        await localStorageService.updateSyncState({
+          last_sync_time: syncWatermark,
+          total_downloaded: currentSyncState.total_downloaded + downloadedCount,
+          total_size: currentSyncState.total_size + totalSizeDownloaded,
+        })
+      }
+
+      store.setSyncComplete()
+      await this.onSyncComplete(downloadedCount, failedCount)
+    } catch (error: any) {
+      mediaProcessingQueue.abort()
+      if (error?.message === "Sync cancelled") {
+        console.log("[GallerySyncService] Sync was cancelled")
+        store.setSyncCancelled()
+        await gallerySyncNotifications.showSyncCancelled()
+      } else {
+        console.error("[GallerySyncService] Capture download failed:", error)
+        store.setSyncError(error?.message || "Download failed")
+        await gallerySyncNotifications.showSyncError(error?.message || "Download failed")
+      }
+
+      if (store.syncServiceOpenedHotspot) {
+        await this.closeHotspot()
+      }
+    }
+  }
+
+  /**
+   * Handle sync completion
+   */
+  private async onSyncComplete(downloadedCount: number, failedCount: number): Promise<void> {
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] 🎉 Step 6/6: Sync completion")
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService]   📊 Final results:")
+    console.log(`[GallerySyncService]      - Downloaded: ${downloadedCount}`)
+    console.log(`[GallerySyncService]      - Failed: ${failedCount}`)
+    console.log(
+      `[GallerySyncService]      - Success rate: ${
+        downloadedCount > 0 ? ((downloadedCount / (downloadedCount + failedCount)) * 100).toFixed(1) : 0
+      }%`,
+    )
+
+    // 🔍 DIAGNOSTIC: Show all pictures currently in storage after sync
+    // try {
+    //   const allStoredFiles = await localStorageService.getDownloadedFiles()
+    //   const fileNames = Object.keys(allStoredFiles)
+    //   console.log(`[GallerySyncService] 📸 POST-SYNC INVENTORY: ${fileNames.length} total files in storage`)
+    //   console.log(`[GallerySyncService] 📋 Complete file list:`)
+    //   fileNames
+    //     .sort((a, b) => {
+    //       const fileA = allStoredFiles[a]
+    //       const fileB = allStoredFiles[b]
+    //       return fileB.downloaded_at - fileA.downloaded_at // Most recent first
+    //     })
+    //     .slice(0, 20)
+    //     .forEach((fileName, idx) => {
+    //       const file = allStoredFiles[fileName]
+    //       const captureDate = new Date(file.modified).toISOString()
+    //       const downloadDate = new Date(file.downloaded_at).toISOString()
+    //       console.log(
+    //         `[GallerySyncService]   ${idx + 1}. ${fileName} - captured: ${captureDate}, downloaded: ${downloadDate}`,
+    //       )
+    //     })
+    //   if (fileNames.length > 20) {
+    //     console.log(`[GallerySyncService]   ... and ${fileNames.length - 20} more files`)
+    //   }
+    // } catch (error) {
+    //   console.error(`[GallerySyncService] Failed to get post-sync inventory:`, error)
+    // }
+
+    // Clear the queue
+    console.log("[GallerySyncService]   🧹 Clearing sync queue...")
+    await localStorageService.clearSyncQueue()
+
+    // Show completion notification
+    console.log("[GallerySyncService]   📱 Showing completion notification...")
+    await gallerySyncNotifications.showSyncComplete(downloadedCount, failedCount)
+
+    // Close hotspot if we opened it
+    const store = useGallerySyncStore.getState()
+    if (store.syncServiceOpenedHotspot) {
+      console.log("[GallerySyncService]   📡 Closing hotspot (service opened it)...")
+      await this.closeHotspot()
+    } else {
+      console.log("[GallerySyncService]   ℹ️ Hotspot was not opened by service - leaving it enabled")
+    }
+
+    // Clear glasses gallery count immediately after successful sync
+    // This ensures UI shows 0 items remaining right away
+    // The subsequent query will update this if new photos were taken during sync
+    console.log("[GallerySyncService]   🔄 Clearing glasses gallery count (synced all items)")
+    store.clearGlassesGalleryStatus()
+
+    // Auto-reset to idle after 4 seconds to clear "Sync complete!" message,
+    // then query glasses for any new content taken during the sync.
+    // The query MUST happen after the reset — otherwise setGlassesGalleryStatus
+    // sees syncState="complete" + hasContent=true and immediately resets to idle,
+    // making it look like sync accomplished nothing (circular sync loop).
+    console.log("[GallerySyncService]   ⏲️ Scheduling auto-reset to idle in 4 seconds...")
+    BgTimer.setTimeout(async () => {
+      const currentStore = useGallerySyncStore.getState()
+      if (currentStore.syncState === "complete") {
+        console.log("[GallerySyncService]   🔄 Auto-resetting sync state to idle")
+        currentStore.setSyncState("idle")
+      }
+      // Now query glasses — any content reported will show the sync button
+      // naturally without preempting the "Sync complete!" message
+      console.log("[GallerySyncService]   🔍 Querying glasses for post-sync gallery status...")
+      await this.queryGlassesGalleryStatus()
+    }, 4000)
+
+    console.log("[GallerySyncService] ========================================")
+    console.log("[GallerySyncService] ✅ SYNC FULLY COMPLETE")
+    console.log("[GallerySyncService] ========================================")
+  }
+
+  /**
+   * Cancel the current sync
+   */
+  async cancelSync(): Promise<void> {
+    console.log("[GallerySyncService] Cancelling sync...")
+
+    // Abort any ongoing downloads
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+
+    // Clear timeout
+    if (this.hotspotConnectionTimeout) {
+      BgTimer.clearTimeout(this.hotspotConnectionTimeout!)
+      this.hotspotConnectionTimeout = null
+    }
+
+    const store = useGallerySyncStore.getState()
+
+    // Close hotspot if we opened it
+    if (store.syncServiceOpenedHotspot) {
+      await this.closeHotspot()
+    }
+
+    // Update store
+    store.setSyncCancelled()
+
+    // Clear queue
+    await localStorageService.clearSyncQueue()
+
+    // Dismiss notification
+    await gallerySyncNotifications.showSyncCancelled()
+  }
+
+  /**
+   * Close the hotspot
+   */
+  private async closeHotspot(): Promise<void> {
+    const store = useGallerySyncStore.getState()
+
+    try {
+      console.log("[GallerySyncService] Closing hotspot...")
+      await BluetoothSdk.setHotspotState(false)
+      store.setSyncServiceOpenedHotspot(false)
+      store.setHotspotInfo(null)
+      console.log("[GallerySyncService] Hotspot closed")
+    } catch (error) {
+      console.error("[GallerySyncService] Failed to close hotspot:", error)
+    }
+  }
+
+  /**
+   * Check for resumable sync on app start
+   */
+  async checkForResumableSync(): Promise<boolean> {
+    const hasResumable = await localStorageService.hasResumableSyncQueue()
+
+    if (hasResumable) {
+      console.log("[GallerySyncService] Found resumable sync queue")
+      // Don't auto-resume - let user decide
+      // Could emit an event here for UI to show "Resume sync?" prompt
+    }
+
+    return hasResumable
+  }
+
+  /**
+   * Resume a previously interrupted sync
+   */
+  async resumeSync(): Promise<void> {
+    const queue = await localStorageService.getSyncQueue()
+
+    if (!queue || queue.currentIndex >= queue.files.length) {
+      console.log("[GallerySyncService] No queue to resume")
+      await localStorageService.clearSyncQueue()
+      return
+    }
+
+    // Check if queue is too old - hotspot auto-disables after 40s of inactivity,
+    // so stale queues can't be resumed (hotspot credentials are no longer valid)
+    const queueAge = Date.now() - queue.startedAt
+    if (queueAge > TIMING.MAX_QUEUE_AGE_MS) {
+      console.log(`[GallerySyncService] Queue too old (${Math.round(queueAge / 1000)}s) - clearing stale queue`)
+      await localStorageService.clearSyncQueue()
+      // Don't auto-start - let user tap sync button if they want to continue
+      return
+    }
+
+    // R5: Resume by going through full startSync() flow to re-request hotspot
+    // (stale hotspot credentials are unreliable). The saved queue will be used
+    // to skip already-downloaded files when startFileDownload detects them.
+    console.log(`[GallerySyncService] Resuming sync from file ${queue.currentIndex + 1}/${queue.files.length}`)
+    console.log("[GallerySyncService] Re-requesting hotspot via full startSync flow")
+    await this.startSync()
+  }
+
+  /**
+   * Query glasses for gallery status
+   */
+  async queryGlassesGalleryStatus(): Promise<void> {
+    try {
+      await BluetoothSdk.queryGalleryStatus()
+    } catch (error) {
+      console.error("[GallerySyncService] Failed to query gallery status:", error)
+    }
+  }
+
+  /** True while pre-flight startSync work is in flight (before sync state transitions). */
+  isSyncStarting(): boolean {
+    return this.syncStartPromise !== null
+  }
+
+  /**
+   * Check if sync is currently in progress (hotspot/WiFi/download phases).
+   * Does not include pre-flight — use isSyncStarting() for that.
+   */
+  isSyncing(): boolean {
+    const store = useGallerySyncStore.getState()
+    return (
+      store.syncState === "syncing" || store.syncState === "connecting_wifi" || store.syncState === "requesting_hotspot"
+    )
+  }
+}
+
+export const gallerySyncService = GallerySyncService.getInstance()