perf(mobile): optimize offline folder counts with caching and indexing

Performance Optimizations:
- Consolidate SQL queries from 5 separate queries to 1 optimized query (~80% reduction)
- Add composite database indexes for count queries (O(log n) instead of O(n) lookups)
- Implement 10s short-lived cache for offline counts to prevent recalculation
- Add helper functions to eliminate code duplication (112 lines deduplicated)

Bug Fixes:
- Fix folder counts not displaying when offline (calculate from SQLite cache)
- Fix race condition in ViewNote attachment loading with proper cleanup
- Fix infinite error toasts when viewing notes offline
- Improve error handling to return complete interfaces

UX Improvements:
- Add 500ms debouncing for network status changes (prevents flaky connection issues)
- Add prefetch during master password authentication for instant offline access
- Add two-stage loading UI: "Securing Your Data" → "Caching Your Data"
- Add loading spinner to prevent white screen flash

Security:
- Change default to encrypted cache for better security (decrypt on-demand)
- Add "Offline Cache Security" documentation in Settings
- Maintain end-to-end encryption throughout

Author: batalabs

apps/mobile/v1/src/components/AppWrapper.tsx

@@ -22,6 +22,8 @@ export const AppWrapper: React.FC<AppWrapperProps> = ({ children }) => {
     isNewSetup,
     isChecking,
     userId,
+    loadingStage,
+    cacheMode,
     onPasswordSuccess,
   } = useMasterPassword();
 
@@ -124,6 +126,8 @@ export const AppWrapper: React.FC<AppWrapperProps> = ({ children }) => {
         key={userId} // Force remount when userId changes to reset all state
         userId={userId || ''}
         isNewSetup={isNewSetup}
+        loadingStage={loadingStage}
+        cacheMode={cacheMode}
         onSuccess={onPasswordSuccess}
       />
     );

apps/mobile/v1/src/components/MasterPasswordDialog/LoadingView.tsx

@@ -6,13 +6,15 @@ import { styles } from './styles';
 
 interface LoadingViewProps {
   isNewSetup: boolean;
+  stage?: 'securing' | 'caching';
+  cacheMode?: 'encrypted' | 'decrypted';
 }
 
 /**
  * Loading view component
- * Shows during PBKDF2 key derivation with progress indicator
+ * Shows during PBKDF2 key derivation and note caching
  */
-export function LoadingView({ isNewSetup }: LoadingViewProps) {
+export function LoadingView({ isNewSetup, stage = 'securing', cacheMode = 'encrypted' }: LoadingViewProps) {
   const theme = useTheme();
   const [dots, setDots] = useState('');
 
@@ -28,6 +30,50 @@ export function LoadingView({ isNewSetup }: LoadingViewProps) {
     return () => clearInterval(interval);
   }, []);
 
+  // Content for "Securing Your Data" stage
+  if (stage === 'securing') {
+    return (
+      <View style={styles.loadingContent}>
+        <View style={styles.loadingCenter}>
+          <ActivityIndicator
+            size="large"
+            color={theme.colors.primary}
+            style={{ marginBottom: 24 }}
+          />
+
+          <Text style={[styles.loadingTitle, { color: theme.colors.foreground }]}>
+            Securing Your Data{dots}
+          </Text>
+
+          <View
+            style={[
+              styles.notice,
+              {
+                backgroundColor: theme.colors.card,
+                borderColor: theme.colors.border,
+              },
+            ]}
+          >
+            <Text style={[styles.noticeText, { color: theme.colors.foreground }]}>
+              {isNewSetup
+                ? 'We are generating military-grade encryption with 250,000 security iterations to protect your notes. Please wait and do not close the app.'
+                : 'Verifying your master password and loading encryption keys. This may take a moment.'}
+            </Text>
+            <Text
+              style={[
+                styles.noticeText,
+                { color: theme.colors.foreground, marginTop: 12, fontWeight: '600' },
+              ]}
+            >
+              This process can take 2-5 minutes. The app may appear frozen but it&apos;s working{dots}
+            </Text>
+          </View>
+        </View>
+      </View>
+    );
+  }
+
+  // Content for "Caching Your Data" stage
   return (
     <View style={styles.loadingContent}>
       <View style={styles.loadingCenter}>
@@ -38,7 +84,7 @@ export function LoadingView({ isNewSetup }: LoadingViewProps) {
         />
 
         <Text style={[styles.loadingTitle, { color: theme.colors.foreground }]}>
-          Securing Your Data{dots}
+          Caching Your Data{dots}
         </Text>
 
         <View
@@ -51,17 +97,19 @@ export function LoadingView({ isNewSetup }: LoadingViewProps) {
           ]}
         >
           <Text style={[styles.noticeText, { color: theme.colors.foreground }]}>
-            {isNewSetup
-              ? 'We are generating military-grade encryption with 250,000 security iterations to protect your notes. Please wait and do not close the app.'
-              : 'Verifying your master password and loading encryption keys. This may take a moment.'}
+            {cacheMode === 'decrypted'
+              ? 'Downloading and decrypting all your notes for instant offline access. This improves performance but stores decrypted content locally.'
+              : 'Downloading all your notes in encrypted form for offline access. Notes will be decrypted on-demand for better security.'}
           </Text>
           <Text
             style={[
               styles.noticeText,
               { color: theme.colors.foreground, marginTop: 12, fontWeight: '600' },
             ]}
           >
-            This process can take 2-5 minutes. The app may appear frozen but it&apos;s working{dots}
+            {cacheMode === 'decrypted'
+              ? `This may take 5-10 seconds${dots}`
+              : `This should only take a few seconds${dots}`}
           </Text>
         </View>
       </View>

apps/mobile/v1/src/components/MasterPasswordDialog/index.tsx

@@ -12,6 +12,8 @@ import { useKeyboardHandler } from './useKeyboardHandler';
 interface MasterPasswordScreenProps {
   userId: string;
   isNewSetup: boolean;
+  loadingStage?: 'securing' | 'caching';
+  cacheMode?: 'encrypted' | 'decrypted';
   onSuccess: (password: string) => Promise<void>;
 }
 
@@ -21,6 +23,8 @@ interface MasterPasswordScreenProps {
  */
 export function MasterPasswordScreen({
   isNewSetup,
+  loadingStage = 'securing',
+  cacheMode = 'encrypted',
   onSuccess,
 }: MasterPasswordScreenProps) {
   const theme = useTheme();
@@ -72,7 +76,11 @@ export function MasterPasswordScreen({
               onSubmit={handleFormSubmit}
             />
           ) : (
-            <LoadingView isNewSetup={isNewSetup} />
+            <LoadingView
+              isNewSetup={isNewSetup}
+              stage={loadingStage}
+              cacheMode={cacheMode}
+            />
           )}
         </ScrollView>
       </Animated.View>

apps/mobile/v1/src/hooks/useMasterPassword.ts

@@ -10,6 +10,8 @@ import {
   unlockWithMasterPassword,
 } from '../lib/encryption';
 import { logger } from '../lib/logger';
+import { getCacheDecryptedContentPreference } from '../lib/preferences';
+import { useApiService } from '../services/api';
 
 // Global function to force all hook instances to refresh
 export function forceGlobalMasterPasswordRefresh() {
@@ -23,6 +25,9 @@ export function useMasterPassword() {
   const [isNewSetup, setIsNewSetup] = useState(false);
   const [isChecking, setIsChecking] = useState(true);
   const [, setLastCheckTime] = useState<number>(0);
+  const [loadingStage, setLoadingStage] = useState<'securing' | 'caching'>('securing');
+  const [cacheMode, setCacheMode] = useState<'encrypted' | 'decrypted'>('encrypted');
+  const api = useApiService();
 
   const userId = user?.id;
 
@@ -111,6 +116,9 @@ export function useMasterPassword() {
     }
 
     try {
+      // Stage 1: Securing (PBKDF2 key derivation)
+      setLoadingStage('securing');
+
       if (isNewSetup) {
         // Setting up new master password
         await setupMasterPassword(password, userId);
@@ -133,7 +141,60 @@ export function useMasterPassword() {
         });
       }
 
-      // Successfully authenticated - update state
+      // Stage 2: Caching (prefetch notes and folders)
+      setLoadingStage('caching');
+
+      // Check cache mode preference
+      const cacheDecrypted = await getCacheDecryptedContentPreference();
+      setCacheMode(cacheDecrypted ? 'decrypted' : 'encrypted');
+
+      if (__DEV__) {
+        console.log(`[PREFETCH] Starting prefetch with ${cacheDecrypted ? 'DECRYPTED' : 'ENCRYPTED'} cache mode`);
+      }
+
+      try {
+        const prefetchStart = performance.now();
+
+        // Prefetch folders first (faster)
+        if (__DEV__) console.log('[PREFETCH] Step 1: Fetching folders...');
+        await api.getFolders();
+        if (__DEV__) console.log('[PREFETCH] Step 1 complete: Folders fetched');
+
+        // Then prefetch notes (slower)
+        if (__DEV__) console.log('[PREFETCH] Step 2: Fetching notes...');
+
+        // Add 15 second timeout for notes fetch
+        // IMPORTANT: Skip background refresh during prefetch to prevent hanging
+        const notesFetchPromise = api.getNotes({}, { skipBackgroundRefresh: true });
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          setTimeout(() => reject(new Error('Notes fetch timeout after 15 seconds')), 15000);
+        });
+
+        await Promise.race([notesFetchPromise, timeoutPromise]);
+        if (__DEV__) console.log('[PREFETCH] Step 2 complete: Notes fetched');
+
+        const prefetchEnd = performance.now();
+        if (__DEV__) {
+          console.log(`[PREFETCH] ✅ Completed in ${(prefetchEnd - prefetchStart).toFixed(2)}ms - cache ready!`);
+        }
+
+        logger.recordEvent('notes_prefetch_completed', {
+          durationMs: prefetchEnd - prefetchStart,
+          cacheMode: cacheDecrypted ? 'decrypted' : 'encrypted',
+        });
+      } catch (error) {
+        // Log error but continue - user can still use app, they'll just fetch on demand
+        if (__DEV__) {
+          console.error('[PREFETCH] Failed to prefetch notes (non-critical):', error);
+        }
+        logger.warn('[PREFETCH] Failed to prefetch notes', {
+          attributes: {
+            error: error instanceof Error ? error.message : 'Unknown error',
+          },
+        });
+      }
+
+      // Successfully authenticated and cached - update state
       setNeedsUnlock(false);
       setIsNewSetup(false);
       setIsChecking(false);
@@ -162,6 +223,8 @@ export function useMasterPassword() {
     isNewSetup,
     isChecking,
     userId,
+    loadingStage,
+    cacheMode,
     onPasswordSuccess,
     signOut,
     refreshStatus: checkMasterPasswordStatus,

apps/mobile/v1/src/lib/database/index.ts

@@ -87,6 +87,10 @@ async function migrateDatabase(db: SQLite.SQLiteDatabase): Promise<void> {
           CREATE INDEX IF NOT EXISTS idx_notes_archived ON notes(archived);
           CREATE INDEX IF NOT EXISTS idx_notes_deleted ON notes(deleted);
           CREATE INDEX IF NOT EXISTS idx_folders_user_id ON folders(user_id);
+
+          -- Composite indexes for optimized count queries
+          CREATE INDEX IF NOT EXISTS idx_notes_status_composite ON notes(deleted, archived, starred);
+          CREATE INDEX IF NOT EXISTS idx_notes_folder_status ON notes(folder_id, deleted, archived) WHERE folder_id IS NOT NULL;
         `);
 
         console.log('[SQLite] Migration to v3 completed');
@@ -238,6 +242,10 @@ export async function initializeDatabase(): Promise<SQLite.SQLiteDatabase> {
       CREATE INDEX IF NOT EXISTS idx_folders_user_id ON folders(user_id);
       CREATE INDEX IF NOT EXISTS idx_cache_resource ON cache_metadata(resource_type, resource_id);
       CREATE INDEX IF NOT EXISTS idx_sync_status ON sync_queue(status);
+
+      -- Composite indexes for optimized count queries
+      CREATE INDEX IF NOT EXISTS idx_notes_status_composite ON notes(deleted, archived, starred);
+      CREATE INDEX IF NOT EXISTS idx_notes_folder_status ON notes(folder_id, deleted, archived) WHERE folder_id IS NOT NULL;
     `);
 
     console.log('[SQLite] Database initialized successfully');

apps/mobile/v1/src/lib/preferences.ts

@@ -17,27 +17,27 @@ const PREFERENCE_KEYS = {
 /**
  * Get whether to cache decrypted content locally
  *
- * When enabled (default):
+ * When enabled:
  * - Decrypted notes stored in SQLite for instant loading (~50ms)
  * - Better performance but decrypted data stored locally
  *
- * When disabled:
+ * When disabled (default):
  * - Only encrypted notes stored, decrypt on each load (~550ms)
  * - Better security but slower loading
  */
 export async function getCacheDecryptedContentPreference(): Promise<boolean> {
   try {
     const value = await AsyncStorage.getItem(PREFERENCE_KEYS.CACHE_DECRYPTED_CONTENT);
 
-    // Default to true (better UX) if not set
+    // Default to false (better security) if not set
     if (value === null) {
-      return true;
+      return false;
     }
 
     return value === 'true';
   } catch (error) {
     console.error('[Preferences] Failed to get cache preference:', error);
-    return true; // Default to enabled on error
+    return false; // Default to disabled on error
   }
 }
 

apps/mobile/v1/src/screens/FoldersScreen.tsx

@@ -10,6 +10,7 @@ import { SafeAreaView } from 'react-native-safe-area-context';
 
 import { OfflineIndicator } from '../components/OfflineIndicator';
 import { ACTION_BUTTON, FOLDER_CARD, FOLDER_COLORS } from '../constants/ui';
+import { useNetworkStatus } from '../hooks/useNetworkStatus';
 import { type Folder, type FolderCounts,useApiService } from '../services/api';
 import { useTheme } from '../theme';
 
@@ -49,6 +50,7 @@ export default function FoldersScreen() {
   const theme = useTheme();
   const api = useApiService();
   const router = useRouter();
+  const { isConnected, isInternetReachable } = useNetworkStatus();
   const [allFolders, setAllFolders] = useState<Folder[]>([]);
   const [loading, setLoading] = useState(true);
   const [showLoading, setShowLoading] = useState(false);
@@ -199,6 +201,21 @@ export default function FoldersScreen() {
     };
   }, [isFocused, loadFoldersData]);
 
+  // Reload data when network status changes (debounced to prevent flaky connections)
+  useEffect(() => {
+    if (!isFocused) return;
+
+    // Debounce network status changes to avoid rapid reloads on flaky connections
+    const timer = setTimeout(() => {
+      if (__DEV__) {
+        console.log('[FoldersScreen] Network status changed, reloading data');
+      }
+      loadFoldersData();
+    }, 500); // 500ms debounce
+
+    return () => clearTimeout(timer);
+  }, [isConnected, isInternetReachable, isFocused, loadFoldersData]);
+
   // Handle loading delay
   useEffect(() => {
     let timer: ReturnType<typeof setTimeout>;

apps/mobile/v1/src/screens/ListNotes/index.tsx

@@ -3,7 +3,7 @@ import { BottomSheetModal } from '@gorhom/bottom-sheet';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { useFocusEffect } from '@react-navigation/native';
 import React, { useCallback,useEffect, useMemo, useRef, useState } from 'react';
-import { Alert, Animated, FlatList, RefreshControl, StyleSheet, View } from 'react-native';
+import { ActivityIndicator, Alert, Animated, FlatList, RefreshControl, StyleSheet, View } from 'react-native';
 
 import { type Folder, type Note, useApiService } from '../../services/api';
 import { useTheme } from '../../theme';
@@ -258,6 +258,12 @@ export default function NotesListScreen({ navigation, route, renderHeader, scrol
 
   return (
     <View style={[styles.container, { backgroundColor: theme.colors.background }]}>
+      {/* Show loading spinner on initial load */}
+      {loading && notes.length === 0 && (
+        <View style={styles.loadingContainer}>
+          <ActivityIndicator size="large" color={theme.colors.primary} />
+        </View>
+      )}
 
       <Animated.FlatList
         ref={flatListRef}
@@ -315,6 +321,16 @@ const styles = StyleSheet.create({
   container: {
     flex: 1,
   },
+  loadingContainer: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    justifyContent: 'center',
+    alignItems: 'center',
+    zIndex: 10,
+  },
   scrollView: {
     flex: 1,
     paddingHorizontal: 0,