@mentra/engine 0.1.0-dev.0

package/build/services/asg/gallerySyncService.js

@@ -0,0 +1,1839 @@
+/**
+ * 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, Platform } from "react-native";
+import BleManager from "react-native-ble-manager";
+import WifiManager from "react-native-wifi-reborn";
+import { useGallerySyncStore } from "../../stores/gallerySync";
+import { selectGlassesConnected, useGlassesStore } from "../../stores/glasses";
+import { isGlassesConnected } from "../GlassesReadiness";
+import { SETTINGS, useSettingsStore } from "../../stores/settings";
+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,
+};
+class GallerySyncService {
+    static instance;
+    hotspotListenerRegistered = false;
+    hotspotConnectionTimeout = null;
+    hotspotRequestTimeout = null;
+    abortController = null;
+    isInitialized = false;
+    glassesStoreUnsubscribe = null;
+    appStateSubscription = null;
+    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.
+    lastFullSyncRetryKey = null;
+    wifiSettingsOpenedAt = null; // Timestamp when user was sent to WiFi settings
+    syncStartPromise = null;
+    startAborted = false;
+    constructor() { }
+    static getInstance() {
+        if (!GallerySyncService.instance) {
+            GallerySyncService.instance = new GallerySyncService();
+        }
+        return GallerySyncService.instance;
+    }
+    /**
+     * Initialize the service - register event listeners
+     */
+    initialize() {
+        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() {
+        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
+     */
+    handleGlassesDisconnected = () => {
+        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
+     */
+    handleAppStateChange = async (nextAppState) => {
+        // 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((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
+     */
+    handleGalleryStatus = (data) => {
+        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
+     */
+    handleHotspotStatusChange = async (eventData) => {
+        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 = {
+            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
+     */
+    handleHotspotError = (eventData) => {
+        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() {
+        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.
+     */
+    async isLocationServicesEnabled() {
+        try {
+            return await Promise.race([
+                CrustModule.isLocationServicesEnabled(),
+                new Promise((_, 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.
+     */
+    async isBluetoothAdapterEnabled() {
+        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;
+        }
+    }
+    shouldAbortPreFlight() {
+        if (this.startAborted) {
+            this.startAborted = false;
+            return true;
+        }
+        if (!isGlassesConnected(useGlassesStore.getState().connection)) {
+            return true;
+        }
+        return false;
+    }
+    async runStartSync() {
+        // 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 = 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
+     */
+    async showWifiJoinExplanation(ssid) {
+        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((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
+     */
+    async connectToHotspotWifi(hotspotInfo) {
+        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 = 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 = null;
+        const appStateHandler = (nextAppState) => {
+            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) {
+                        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) {
+                                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((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.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) {
+                        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) {
+                                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((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) {
+                    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((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();
+        }
+    }
+    async fetchSyncManifest(clientId, lastSyncTime) {
+        const syncResponse = await asgCameraApi.syncWithServer(clientId, lastSyncTime, true);
+        return (syncResponse.data || syncResponse);
+    }
+    /**
+     * Resolve sync manifest: detect skew, optionally fix clock, retry full sync when needed.
+     */
+    async resolveSyncManifest(clientId, lastSyncTime) {
+        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
+     */
+    async startFileDownload(hotspotInfo) {
+        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 = syncData.captures;
+                console.log(`[GallerySyncService]   📊 Found ${captures.length} captures to download (api_version=2)`);
+                captures.slice(0, 5).forEach((c, idx) => {
+                    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 = 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) => !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, _idx) => {
+                    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) {
+            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.
+     */
+    async executeDownload(files, serverTime) {
+        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;
+                        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) {
+            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.
+     */
+    async executeCaptureDownload(captures, serverTime) {
+        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) {
+                    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();
+            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(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) {
+            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
+     */
+    async onSyncComplete(downloadedCount, failedCount) {
+        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() {
+        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
+     */
+    async closeHotspot() {
+        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() {
+        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() {
+        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() {
+        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() {
+        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() {
+        const store = useGallerySyncStore.getState();
+        return (store.syncState === "syncing" || store.syncState === "connecting_wifi" || store.syncState === "requesting_hotspot");
+    }
+}
+export const gallerySyncService = GallerySyncService.getInstance();
+//# sourceMappingURL=gallerySyncService.js.map