Offline tab as Files view, automatic background sync, sync notifications

- Offline tab is now FilesView(offline: true) over a FolderBrowser interface
  (FilesController / OfflineController) sharing controls, tiles, thumbnails
- Synced files follow the Files Cache rule (default: refresh every 15 min):
  per-account WorkManager jobs, in-app timer, resume and pull triggers;
  root-etag shortcut skips full walks when nothing changed
- Single sync at a time (shared lock); logging out stops that account's sync
- Sync safety: PROPFIND failures skip the path instead of deleting local files
- Mirror empty folders and remove deleted ones; drop synced paths deleted on
  the server; missing local files are re-downloaded
- Notifications: silent per-account sync notifications, "Background sync
  notifications" setting, audible upload/download completion
- Files refresh in place (no spinner flash); retry after network returns
- Fix sync badges not updating (shared native status stream), "Sync off" on
  launch (eager providers), Files Cache section moved under Device Sync

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

lib/providers/connectivity_controller.dart

@@ -0,0 +1,53 @@
+import 'dart:async';
+import 'package:connectivity_plus/connectivity_plus.dart';
+import 'package:flutter/foundation.dart';
+
+/// Whether the device currently has *any* network route (Wi-Fi, mobile
+/// data, ethernet - not a guarantee the Nextcloud server itself is
+/// reachable, just OS-level connectivity). The single source of truth
+/// other controllers/views consult before attempting a network request or
+/// deciding whether to fall back to offline-only behavior - see
+/// `SessionController` (skips its login-restore HTTP call entirely while
+/// offline) and `MainShellView` (restricts the bottom nav to just the
+/// Offline tab while offline).
+class ConnectivityController extends ChangeNotifier {
+  bool _isOffline = false;
+  StreamSubscription<List<ConnectivityResult>>? _sub;
+  Timer? _recheckTimer;
+
+  bool get isOffline => _isOffline;
+
+  ConnectivityController() {
+    Connectivity().checkConnectivity().then(_apply);
+    _sub = Connectivity().onConnectivityChanged.listen(_apply);
+    // The very first check can spuriously report "no network" while the
+    // OS's connectivity stack is still attaching callbacks to this
+    // just-started process - a real Android cold-start quirk, not a
+    // genuine transition. That matters here specifically because
+    // onConnectivityChanged only fires on actual transitions, so a false
+    // initial "offline" read would otherwise stick for the rest of the
+    // session (SessionController would keep treating every login as
+    // provisional, and every network-fetching controller would never get
+    // its real activation signal - see addAccountReadyListener's doc
+    // comment) even though the device was online the whole time. Re-
+    // verify once, shortly after, to correct it.
+    _recheckTimer = Timer(const Duration(seconds: 2), () {
+      Connectivity().checkConnectivity().then(_apply);
+    });
+  }
+
+  void _apply(List<ConnectivityResult> results) {
+    final offline =
+        results.isEmpty || results.every((r) => r == ConnectivityResult.none);
+    if (offline == _isOffline) return;
+    _isOffline = offline;
+    notifyListeners();
+  }
+
+  @override
+  void dispose() {
+    _sub?.cancel();
+    _recheckTimer?.cancel();
+    super.dispose();
+  }
+}

lib/providers/files_controller.dart

@@ -3,6 +3,7 @@ import 'dart:convert';
 import 'package:flutter/material.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import '../models/nextcloud_item.dart';
+import 'folder_browser.dart';
 import 'session_controller.dart';
 
 enum FileSortField { name, dateCreated, dateModified, size }
@@ -20,7 +21,8 @@ enum FilesTypeFilter { all, filesOnly, foldersOnly }
 /// content - just the list of names/sizes/dates) are reused across
 /// navigation instead of refetched from the server every time.
 enum CachePolicy {
-  /// Every navigation refetches - today's behavior.
+  /// Every navigation refetches. Synced files are checked each time the app
+  /// opens (and on pull-to-refresh), but not on a background schedule.
   never,
 
   /// A listing is reused until it's older than [FilesController.
@@ -29,9 +31,17 @@ enum CachePolicy {
   interval,
 
   /// A listing is reused indefinitely until the user pulls to refresh.
+  /// Synced files likewise only update on pull-to-refresh / "Sync now".
   manual,
 }
 
+/// New accounts (and anyone who's never touched the setting) refresh
+/// periodically - the Files Cache rule also drives how often synced
+/// folders/files are brought in line with the server, see
+/// `SyncStatusController`.
+const defaultCachePolicy = CachePolicy.interval;
+const defaultCacheIntervalMinutes = 15;
+
 /// One cached folder listing and when it was fetched.
 class _CachedDirectory {
   final List<NextcloudItem> items;
@@ -52,7 +62,9 @@ class _CachedDirectory {
 /// comments for why they depend on this one.
 ///
 /// Split out of the former single `ServerProvider` god object.
-class FilesController extends ChangeNotifier with WidgetsBindingObserver {
+class FilesController extends ChangeNotifier
+    with WidgetsBindingObserver
+    implements FolderBrowser {
   final SessionController session;
 
   static const _prefGridView = 'ui_grid_view';
@@ -60,8 +72,8 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
   static const _prefFilesTypeFilter = 'ui_files_type_filter';
   static const _prefShowHiddenFiles = 'ui_show_hidden';
   static const _prefFolderSort = 'ui_folder_sort';
-  static const _prefCachePolicy = 'ui_cache_policy';
-  static const _prefCacheIntervalMinutes = 'ui_cache_interval_minutes';
+  static const prefCachePolicy = 'ui_cache_policy';
+  static const prefCacheIntervalMinutes = 'ui_cache_interval_minutes';
 
   String _currentFolderPath = '/';
   List<String> _pathStack = ['/'];
@@ -74,11 +86,16 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
   final Map<String, FileSortField> _folderSortField = {};
   final Map<String, bool> _folderSortAscending = {};
 
-  CachePolicy _cachePolicy = CachePolicy.never;
-  int _cacheIntervalMinutes = 5;
+  CachePolicy _cachePolicy = defaultCachePolicy;
+  int _cacheIntervalMinutes = defaultCacheIntervalMinutes;
   final Map<String, _CachedDirectory> _directoryCache = {};
   Timer? _cacheRefreshTimer;
 
+  // Auto-retry of a failed (not in-place) load that looks like a network
+  // hiccup - see [_scheduleNetworkRetry].
+  Timer? _retryTimer;
+  int _retryAttempt = 0;
+
   List<NextcloudItem> _items = [];
   NextcloudUserQuota? _quota;
   List<NextcloudActivity> _activities = [];
@@ -89,26 +106,37 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     WidgetsBinding.instance.addObserver(this);
     session.addAccountClearedListener(_onAccountCleared);
     session.addAccountActivatedListener(_onAccountActivated);
+    session.addAccountReadyListener(_restoreDisplayPrefs);
   }
 
   // Getters
+  @override
   String get currentFolderPath => _currentFolderPath;
+  @override
   List<String> get pathStack => _pathStack;
   bool get isGridView => _isGridView;
   StorageScope get storageScope => _storageScope;
   FilesTypeFilter get filesTypeFilter => _filesTypeFilter;
   bool get showHiddenFiles => _showHiddenFiles;
-  FileSortField get filesSortField =>
-      _folderSortField[_currentFolderPath] ?? FileSortField.name;
-  bool get filesSortAscending =>
-      _folderSortAscending[_currentFolderPath] ?? true;
+  FileSortField get filesSortField => sortFieldFor(_currentFolderPath);
+  bool get filesSortAscending => sortAscendingFor(_currentFolderPath);
+
+  /// Per-folder sort prefs keyed by remote path - also what the Offline tab
+  /// reads for the same path in the local mirror, so a folder sorts the
+  /// same in both places.
+  FileSortField sortFieldFor(String path) =>
+      _folderSortField[path] ?? FileSortField.name;
+  bool sortAscendingFor(String path) => _folderSortAscending[path] ?? true;
   CachePolicy get cachePolicy => _cachePolicy;
   int get cacheIntervalMinutes => _cacheIntervalMinutes;
+  @override
   bool get isLoading => _isLoading;
+  @override
   String? get errorMessage => _errorMessage;
   NextcloudUserQuota? get quota => _quota;
   List<NextcloudActivity> get activities => _activities;
 
+  @override
   List<NextcloudItem> get items => applyFilesDisplayPrefs(_items);
 
   int _compareItems(NextcloudItem a, NextcloudItem b, FileSortField field) {
@@ -140,6 +168,7 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     List<NextcloudItem> source, {
     required bool showFavoritesOnly,
     required bool showHidden,
+    bool applyStorageScope = true,
   }) {
     var filtered = source;
     if (showFavoritesOnly) {
@@ -148,13 +177,15 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     if (!showHidden) {
       filtered = filtered.where((item) => !_isHiddenItem(item)).toList();
     }
-    filtered = filtered
-        .where(
-          (item) => _storageScope == StorageScope.external
-              ? item.isExternalStorage
-              : !item.isExternalStorage,
-        )
-        .toList();
+    if (applyStorageScope) {
+      filtered = filtered
+          .where(
+            (item) => _storageScope == StorageScope.external
+                ? item.isExternalStorage
+                : !item.isExternalStorage,
+          )
+          .toList();
+    }
     return filtered;
   }
 
@@ -165,13 +196,22 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
   /// listings via [fetchFolderListing] rather than reading [items] itself)
   /// can render with the exact same controls/behavior as the Files tab
   /// without duplicating this logic.
-  List<NextcloudItem> applyFilesDisplayPrefs(List<NextcloudItem> rawItems) {
+  ///
+  /// [folderPath] picks which folder's sort prefs apply (default: the
+  /// Files tab's current folder). [applyStorageScope] is off for the
+  /// Offline tab, whose local mirror has no cloud/external distinction.
+  List<NextcloudItem> applyFilesDisplayPrefs(
+    List<NextcloudItem> rawItems, {
+    String? folderPath,
+    bool applyStorageScope = true,
+  }) {
     var filtered = applyCommonFilters(
       rawItems,
       // Files itself doesn't filter by favorite - that's the dedicated
       // Favorites tab's job.
       showFavoritesOnly: false,
       showHidden: _showHiddenFiles,
+      applyStorageScope: applyStorageScope,
     );
     switch (_filesTypeFilter) {
       case FilesTypeFilter.all:
@@ -182,17 +222,21 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
         filtered = filtered.where((i) => i.isFolder).toList();
     }
 
-    final field = filesSortField;
+    final path = folderPath ?? _currentFolderPath;
+    final field = sortFieldFor(path);
     final folders = filtered.where((i) => i.isFolder).toList()
       ..sort((a, b) => _compareItems(a, b, field));
     final files = filtered.where((i) => !i.isFolder).toList()
       ..sort((a, b) => _compareItems(a, b, field));
-    return filesSortAscending
+    return sortAscendingFor(path)
         ? [...folders, ...files]
         : [...folders.reversed, ...files.reversed];
   }
 
   void _onAccountCleared() {
+    _prefsRestore = null;
+    _retryTimer?.cancel();
+    _retryAttempt = 0;
     _cacheRefreshTimer?.cancel();
     _directoryCache.clear();
     _folderSortField.clear();
@@ -206,61 +250,97 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     _storageScope = StorageScope.cloud;
     _filesTypeFilter = FilesTypeFilter.all;
     _showHiddenFiles = false;
-    _cachePolicy = CachePolicy.never;
-    _cacheIntervalMinutes = 5;
+    _cachePolicy = defaultCachePolicy;
+    _cacheIntervalMinutes = defaultCacheIntervalMinutes;
     _isLoading = false;
     _errorMessage = null;
     notifyListeners();
   }
 
-  Future<void> _onAccountActivated() async {
+  // Memoized per account (reset in _onAccountCleared) so the ready-event
+  // and activated-event paths below share one restore instead of racing
+  // two reads of the same prefs.
+  Future<void>? _prefsRestore;
+
+  /// Loads this account's display prefs (grid/list, hidden, type filter,
+  /// sort, cache policy) - hooked to `addAccountReadyListener` as well as
+  /// activation so the Offline tab, which reads these same prefs, respects
+  /// them even on a provisional/offline login where activation never fires.
+  Future<void> _restoreDisplayPrefs() => _prefsRestore ??= _doRestoreDisplayPrefs();
+
+  /// Completes once this account's cache policy/display prefs have been
+  /// loaded from storage - lets `SyncStatusController` schedule background
+  /// sync from the user's real policy instead of the defaults.
+  Future<void> get displayPrefsLoaded => _restoreDisplayPrefs();
+
+  Future<void> _doRestoreDisplayPrefs() async {
     final id = session.activeAccountId;
     if (id != null) {
-      final prefs = await session.prefsFuture;
-      String k(String base) => session.accountStore.accountPrefKey(id, base);
+      // The whole prefs-restore block is wrapped, not just the JSON
+      // decode below - a single bad/mistyped stored value here (an
+      // unguarded `prefs.getBool`/`getString`/`getInt` throws if the
+      // key holds a different runtime type than requested) would
+      // otherwise propagate uncaught out of this method entirely,
+      // silently skipping `refreshData()` below and leaving the Files
+      // tab permanently empty on this activation with no error surfaced
+      // anywhere - exactly what happened before this was guarded.
+      try {
+        final prefs = await session.prefsFuture;
+        String k(String base) => session.accountStore.accountPrefKey(id, base);
 
-      _isGridView = prefs.getBool(k(_prefGridView)) ?? false;
-      final storageScopeName = prefs.getString(k(_prefStorageScope));
-      _storageScope = StorageScope.values.firstWhere(
-        (s) => s.name == storageScopeName,
-        orElse: () => StorageScope.cloud,
-      );
-      final filesTypeFilterName = prefs.getString(k(_prefFilesTypeFilter));
-      _filesTypeFilter = FilesTypeFilter.values.firstWhere(
-        (f) => f.name == filesTypeFilterName,
-        orElse: () => FilesTypeFilter.all,
-      );
-      _showHiddenFiles = prefs.getBool(k(_prefShowHiddenFiles)) ?? false;
+        _isGridView = prefs.getBool(k(_prefGridView)) ?? false;
+        final storageScopeName = prefs.getString(k(_prefStorageScope));
+        _storageScope = StorageScope.values.firstWhere(
+          (s) => s.name == storageScopeName,
+          orElse: () => StorageScope.cloud,
+        );
+        final filesTypeFilterName = prefs.getString(k(_prefFilesTypeFilter));
+        _filesTypeFilter = FilesTypeFilter.values.firstWhere(
+          (f) => f.name == filesTypeFilterName,
+          orElse: () => FilesTypeFilter.all,
+        );
+        _showHiddenFiles = prefs.getBool(k(_prefShowHiddenFiles)) ?? false;
 
-      final folderSortJson = prefs.getString(k(_prefFolderSort));
-      if (folderSortJson != null) {
-        try {
-          final decoded = jsonDecode(folderSortJson) as Map<String, dynamic>;
-          for (final entry in decoded.entries) {
-            final value = entry.value as Map<String, dynamic>;
-            final fieldName = value['field'] as String?;
-            if (fieldName != null) {
-              _folderSortField[entry.key] = FileSortField.values.firstWhere(
-                (f) => f.name == fieldName,
-                orElse: () => FileSortField.name,
-              );
+        final folderSortJson = prefs.getString(k(_prefFolderSort));
+        if (folderSortJson != null) {
+          try {
+            final decoded = jsonDecode(folderSortJson) as Map<String, dynamic>;
+            for (final entry in decoded.entries) {
+              final value = entry.value as Map<String, dynamic>;
+              final fieldName = value['field'] as String?;
+              if (fieldName != null) {
+                _folderSortField[entry.key] = FileSortField.values.firstWhere(
+                  (f) => f.name == fieldName,
+                  orElse: () => FileSortField.name,
+                );
+              }
+              final ascending = value['ascending'] as bool?;
+              if (ascending != null) {
+                _folderSortAscending[entry.key] = ascending;
+              }
             }
-            final ascending = value['ascending'] as bool?;
-            if (ascending != null) _folderSortAscending[entry.key] = ascending;
+          } catch (e) {
+            debugPrint('[FilesController] Folder sort restore failed: $e');
           }
-        } catch (e) {
-          debugPrint('[FilesController] Folder sort restore failed: $e');
         }
-      }
 
-      final cachePolicyName = prefs.getString(k(_prefCachePolicy));
-      _cachePolicy = CachePolicy.values.firstWhere(
-        (c) => c.name == cachePolicyName,
-        orElse: () => CachePolicy.never,
-      );
-      _cacheIntervalMinutes = prefs.getInt(k(_prefCacheIntervalMinutes)) ?? 5;
-      notifyListeners();
+        final cachePolicyName = prefs.getString(k(prefCachePolicy));
+        _cachePolicy = CachePolicy.values.firstWhere(
+          (c) => c.name == cachePolicyName,
+          orElse: () => defaultCachePolicy,
+        );
+        _cacheIntervalMinutes =
+            prefs.getInt(k(prefCacheIntervalMinutes)) ??
+            defaultCacheIntervalMinutes;
+        notifyListeners();
+      } catch (e) {
+        debugPrint('[FilesController] Account-activation prefs restore failed: $e');
+      }
     }
+  }
+
+  Future<void> _onAccountActivated() async {
+    await _restoreDisplayPrefs();
     _startCacheRefreshTimerIfNeeded();
     await refreshData();
   }
@@ -305,10 +385,21 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     // can recognize it's for an account the user has already left and
     // discard itself instead of overwriting the new account's content.
     final gen = session.sessionGeneration;
+    _retryTimer?.cancel();
 
-    _isLoading = true;
-    _errorMessage = null;
-    notifyListeners();
+    // Refreshing a folder that's already on screen (pull-to-refresh, the
+    // periodic cache refresh) swaps the listing in place once the server
+    // answers - blanking the list to a spinner first made every refresh
+    // look like the files vanished and reappeared. The spinner is only for
+    // when there's nothing to show yet (first load, just navigated into a
+    // new folder - see [_navigateTo], which clears the outgoing folder's
+    // items - or retrying after an error).
+    final inPlace = _items.isNotEmpty && _errorMessage == null;
+    if (!inPlace) {
+      _isLoading = true;
+      _errorMessage = null;
+      notifyListeners();
+    }
 
     debugPrint('[FilesController] Refreshing data for path: $_currentFolderPath');
 
@@ -320,6 +411,11 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
         _items,
         DateTime.now(),
       );
+      // Show the new listing now rather than after the quota/activity
+      // fetches below - they're unrelated to what the list displays.
+      _isLoading = false;
+      _retryAttempt = 0;
+      notifyListeners();
       debugPrint(
         '[FilesController] Loaded ${_items.length} items for $_currentFolderPath',
       );
@@ -336,7 +432,12 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     } catch (e) {
       if (gen != session.sessionGeneration) return;
       debugPrint('[FilesController] Error fetching directory: $e');
-      _errorMessage = e.toString().replaceAll('Exception: ', '');
+      // A failed in-place refresh keeps the (slightly stale) listing on
+      // screen instead of replacing it with an error page.
+      if (!inPlace) {
+        _errorMessage = e.toString().replaceAll('Exception: ', '');
+        _scheduleNetworkRetry(e);
+      }
     } finally {
       if (gen == session.sessionGeneration) {
         _isLoading = false;
@@ -345,17 +446,46 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     }
   }
 
+  /// The OS reports "connected" a moment before the route actually works,
+  /// so the first request after regaining Wi-Fi/data can fail with "Network
+  /// is unreachable" - leaving the Files tab on an error page until the
+  /// user taps Retry. Quietly retry a few times (2s, 4s, 8s, 15s) when the
+  /// failure is network-level and the device is online; a real server error
+  /// (auth, 5xx) isn't retried.
+  void _scheduleNetworkRetry(Object error) {
+    final text = error.toString();
+    final isNetworkError =
+        text.contains('SocketException') ||
+        text.contains('ClientException') ||
+        text.contains('TimeoutException') ||
+        text.contains('Network is unreachable');
+    if (!isNetworkError ||
+        _retryAttempt >= 4 ||
+        session.connectivity.isOffline) {
+      return;
+    }
+    final delays = [2, 4, 8, 15];
+    final delay = Duration(seconds: delays[_retryAttempt]);
+    _retryAttempt++;
+    _retryTimer = Timer(delay, () => unawaited(refreshData()));
+  }
+
   Future<List<NextcloudItem>> searchFiles(String query) async {
     final service = session.service;
     if (service == null) return [];
     return service.searchFiles(query);
   }
 
+  @override
+  Future<void> reload() => refreshData();
+
+  @override
   Future<void> navigateToFolder(String path) async {
     _pathStack.add(path);
     await _navigateTo(path);
   }
 
+  @override
   Future<void> navigateUp() async {
     if (_pathStack.length > 1) {
       _pathStack.removeLast();
@@ -365,6 +495,7 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
 
   /// Jumps directly to an ancestor folder by its position in [pathStack]
   /// (as tapped from a breadcrumb), trimming everything below it.
+  @override
   Future<void> navigateToPathIndex(int index) async {
     if (index < 0 || index >= _pathStack.length - 1) return;
     _pathStack = _pathStack.sublist(0, index + 1);
@@ -402,6 +533,10 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
       notifyListeners();
       return;
     }
+    // Don't leave the folder just left on screen under the new breadcrumb
+    // while this one loads - clearing it is what makes [refreshData] show
+    // its spinner (rather than refreshing in place) for a navigation.
+    _items = [];
     await refreshData();
   }
 
@@ -493,15 +628,20 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     );
   }
 
-  void setFilesSortField(FileSortField field) {
-    if (filesSortField == field) return;
-    _folderSortField[_currentFolderPath] = field;
+  void setFilesSortField(FileSortField field) =>
+      setSortFieldFor(_currentFolderPath, field);
+
+  void toggleFilesSortOrder() => toggleSortOrderFor(_currentFolderPath);
+
+  void setSortFieldFor(String path, FileSortField field) {
+    if (sortFieldFor(path) == field) return;
+    _folderSortField[path] = field;
     notifyListeners();
     _persistFolderSort();
   }
 
-  void toggleFilesSortOrder() {
-    _folderSortAscending[_currentFolderPath] = !filesSortAscending;
+  void toggleSortOrderFor(String path) {
+    _folderSortAscending[path] = !sortAscendingFor(path);
     notifyListeners();
     _persistFolderSort();
   }
@@ -511,7 +651,7 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     _cachePolicy = policy;
     notifyListeners();
     _persistAccountPref(
-      _prefCachePolicy,
+      prefCachePolicy,
       (p, key) => p.setString(key, policy.name),
     );
     _startCacheRefreshTimerIfNeeded();
@@ -523,7 +663,7 @@ class FilesController extends ChangeNotifier with WidgetsBindingObserver {
     _cacheIntervalMinutes = clamped;
     notifyListeners();
     _persistAccountPref(
-      _prefCacheIntervalMinutes,
+      prefCacheIntervalMinutes,
       (p, key) => p.setInt(key, clamped),
     );
     _startCacheRefreshTimerIfNeeded();

lib/providers/folder_browser.dart

@@ -0,0 +1,31 @@
+import '../models/nextcloud_item.dart';
+
+/// What `FilesView` needs from whatever is supplying the folder it's
+/// showing: the breadcrumb trail, the (already display-pref-filtered and
+/// sorted) items, loading/error state, and navigation. Implemented by
+/// [FilesController] (the server's folders) and [OfflineController] (the
+/// device-sync mirror of those same folders) so the Files tab and the
+/// Offline tab are literally the same view over two data sources.
+///
+/// Deliberately not a `Listenable` - `context.watch` subscribes to the
+/// concrete provider registered in `main()`, not to this interface, so the
+/// view picks the concrete controller and then treats it as a
+/// [FolderBrowser].
+abstract interface class FolderBrowser {
+  List<String> get pathStack;
+  String get currentFolderPath;
+
+  /// Items in [currentFolderPath] with the shared Files display prefs
+  /// (hidden files, type filter, sort) already applied.
+  List<NextcloudItem> get items;
+
+  bool get isLoading;
+  String? get errorMessage;
+
+  Future<void> navigateToFolder(String path);
+  Future<void> navigateToPathIndex(int index);
+  Future<void> navigateUp();
+
+  /// Re-reads the current folder (pull-to-refresh / retry).
+  Future<void> reload();
+}

lib/providers/offline_controller.dart

@@ -0,0 +1,246 @@
+import 'dart:async';
+import 'dart:io';
+import 'package:flutter/material.dart';
+import 'package:path/path.dart' as p;
+import 'package:path_provider/path_provider.dart';
+import '../models/nextcloud_item.dart';
+import '../services/sync_service.dart';
+import 'files_controller.dart';
+import 'folder_browser.dart';
+import 'session_controller.dart';
+
+/// The Offline tab's data source: `FilesView` (the same view as the Files
+/// tab) over whatever device-sync has actually mirrored to local storage,
+/// i.e. the Files tab's folders filtered down to what's available offline -
+/// read straight off
+/// disk, no server round-trip, since the whole point is browsing what's
+/// available without a connection. Walks
+/// `<externalFilesDir>/sync/<accountId>/...` directly (mirrors
+/// `SyncEngine.kt#syncRoot`'s layout exactly, same technique
+/// `SyncStatusController.localSyncedFilePath` already relies on) rather
+/// than round-tripping through a MethodChannel. Listens for
+/// [SessionController.addAccountReadyListener] rather than
+/// `addAccountActivatedListener` - this controller's own work is entirely
+/// local, so it's safe to run even on a provisional/offline login (see
+/// that method's doc comment).
+///
+/// Display controls (grid/list, sort, hidden files, files/folders filter)
+/// aren't kept here - [items] runs the listing through the Files tab's own
+/// [FilesController] prefs so the two tabs always agree.
+class OfflineController extends ChangeNotifier
+    with WidgetsBindingObserver
+    implements FolderBrowser {
+  final SessionController session;
+  final FilesController files;
+
+  List<String> _pathStack = const ['/'];
+  List<NextcloudItem> _items = [];
+  bool _isLoading = false;
+  String? _errorMessage;
+  bool _wasSyncing = false;
+  // Resolved once in _load - lets [localFileFor] stay synchronous so it can
+  // be called straight from a widget's build.
+  String? _syncBasePath;
+  StreamSubscription<SyncStatusSnapshot>? _statusSub;
+
+  OfflineController(this.session, this.files) {
+    WidgetsBinding.instance.addObserver(this);
+    session.addAccountClearedListener(_onAccountCleared);
+    session.addAccountReadyListener(_onAccountActivated);
+    // Refreshes automatically once a sync pass finishes, so newly
+    // downloaded files show up here without a manual pull-to-refresh.
+    _statusSub = SyncService.statusStream.listen(_onStatusSnapshot);
+  }
+
+  @override
+  List<String> get pathStack => _pathStack;
+  @override
+  String get currentFolderPath => _pathStack.last;
+  @override
+  List<NextcloudItem> get items => files.applyFilesDisplayPrefs(
+    _items,
+    folderPath: currentFolderPath,
+    // The local mirror has no cloud/external distinction to filter on.
+    applyStorageScope: false,
+  );
+  // Only "loading" while there's nothing to show yet - a reload over an
+  // already-listed folder (e.g. the automatic one after a sync pass
+  // finishes) swaps the list in place instead of flashing a spinner.
+  @override
+  bool get isLoading => _isLoading && _items.isEmpty;
+  @override
+  String? get errorMessage => _errorMessage;
+
+  void _onAccountCleared() {
+    _pathStack = const ['/'];
+    _items = [];
+    _isLoading = false;
+    _errorMessage = null;
+    notifyListeners();
+  }
+
+  void _onAccountActivated() {
+    unawaited(_load());
+  }
+
+  /// A background sync (which can run while the app is closed or paused)
+  /// may have added or removed files since this list was last read - re-read
+  /// the folder whenever the app comes back to the foreground.
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state == AppLifecycleState.resumed) unawaited(_load());
+  }
+
+  void _onStatusSnapshot(SyncStatusSnapshot snapshot) {
+    if (_wasSyncing && !snapshot.syncing) {
+      unawaited(_load());
+    }
+    _wasSyncing = snapshot.syncing;
+  }
+
+  /// Reloads the currently browsed folder - used by pull-to-refresh and as
+  /// the account-activation entry point.
+  @override
+  Future<void> reload() => _load();
+
+  @override
+  Future<void> navigateToFolder(String path) async {
+    _pathStack = [..._pathStack, path];
+    await _load();
+  }
+
+  @override
+  Future<void> navigateToPathIndex(int index) async {
+    if (index < 0 || index >= _pathStack.length - 1) return;
+    _pathStack = _pathStack.sublist(0, index + 1);
+    await _load();
+  }
+
+  @override
+  Future<void> navigateUp() async {
+    if (_pathStack.length <= 1) return;
+    _pathStack = _pathStack.sublist(0, _pathStack.length - 1);
+    await _load();
+  }
+
+  Future<void> _load() async {
+    final accountId = session.activeAccountId;
+    if (accountId == null) return;
+
+    _isLoading = true;
+    _errorMessage = null;
+    notifyListeners();
+
+    try {
+      _syncBasePath ??= (await getExternalStorageDirectory())?.path;
+      // A sync can delete the very folder being browsed (deleted on the
+      // server) - step out to the nearest ancestor that still exists rather
+      // than showing a phantom empty folder.
+      final base = _syncBasePath;
+      if (base != null) {
+        while (_pathStack.length > 1 &&
+            !Directory(
+              p.join(
+                base,
+                'sync',
+                accountId,
+                currentFolderPath.replaceFirst('/', ''),
+              ),
+            ).existsSync()) {
+          _pathStack = _pathStack.sublist(0, _pathStack.length - 1);
+        }
+      }
+      _items = await _listFolder(accountId, currentFolderPath);
+    } catch (e) {
+      debugPrint('[OfflineController] Error listing local files: $e');
+      _errorMessage = e.toString().replaceAll('Exception: ', '');
+    } finally {
+      _isLoading = false;
+      notifyListeners();
+    }
+  }
+
+  /// The absolute local path for [item] - a pure function of its remote-
+  /// style `path` (same `<accountId>/<relPath>` layout `SyncEngine.kt#
+  /// syncRoot` uses). Deliberately doesn't re-verify [item] is "in sync
+  /// scope" the way `SyncStatusController.localSyncedFilePath` does for
+  /// arbitrary items from elsewhere in the app - every item this
+  /// controller ever hands out already came from listing this exact
+  /// directory tree, so it's definitionally already local; re-checking
+  /// scope here was the actual bug behind a file the Offline tab had just
+  /// listed reporting itself as "no longer available".
+  /// Synchronous counterpart to [localPathFor] for building thumbnails -
+  /// null until the first [_load] has resolved the storage directory. Doesn't
+  /// check the file exists; the image widget's own error fallback covers a
+  /// missing one.
+  File? localFileFor(NextcloudItem item) {
+    final accountId = session.activeAccountId;
+    final base = _syncBasePath;
+    if (accountId == null || base == null) return null;
+    final relPath = item.path.startsWith('/')
+        ? item.path.substring(1)
+        : item.path;
+    return File(p.join(base, 'sync', accountId, relPath));
+  }
+
+  Future<String?> localPathFor(NextcloudItem item) async {
+    final accountId = session.activeAccountId;
+    if (accountId == null) return null;
+    final base = await getExternalStorageDirectory();
+    if (base == null) return null;
+    final relPath = item.path.startsWith('/')
+        ? item.path.substring(1)
+        : item.path;
+    final file = File(p.join(base.path, 'sync', accountId, relPath));
+    return file.existsSync() ? file.path : null;
+  }
+
+  static Future<List<NextcloudItem>> _listFolder(
+    String accountId,
+    String folderPath,
+  ) async {
+    final base = await getExternalStorageDirectory();
+    if (base == null) return [];
+    final relFolder = folderPath == '/' ? '' : folderPath.replaceFirst('/', '');
+    final dir = Directory(p.join(base.path, 'sync', accountId, relFolder));
+    if (!dir.existsSync()) return [];
+
+    final items = <NextcloudItem>[];
+    await for (final entity in dir.list(followLinks: false)) {
+      final name = p.basename(entity.path);
+      final remotePath = folderPath == '/' ? '/$name' : '$folderPath/$name';
+      if (entity is Directory) {
+        items.add(
+          NextcloudItem(
+            id: remotePath,
+            name: name,
+            path: remotePath,
+            type: NextcloudItemType.folder,
+            size: 0,
+            lastModified: (await entity.stat()).modified,
+          ),
+        );
+      } else if (entity is File) {
+        final stat = await entity.stat();
+        items.add(
+          NextcloudItem(
+            id: remotePath,
+            name: name,
+            path: remotePath,
+            type: NextcloudItem.deduceType(remotePath, false, null),
+            size: stat.size,
+            lastModified: stat.modified,
+          ),
+        );
+      }
+    }
+    return items;
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    _statusSub?.cancel();
+    super.dispose();
+  }
+}

lib/providers/photos_controller.dart

@@ -76,18 +76,27 @@ class PhotosController extends ChangeNotifier {
   Future<void> _onAccountActivated() async {
     final id = session.activeAccountId;
     if (id != null) {
-      final prefs = await session.prefsFuture;
-      String k(String base) => session.accountStore.accountPrefKey(id, base);
-      _showFavoritesOnly =
-          prefs.getBool(k(_prefShowFavoritesOnlyPhotos)) ?? false;
-      _showHidden = prefs.getBool(k(_prefShowHiddenPhotos)) ?? false;
-      final sortFieldName = prefs.getString(k(_prefSortField));
-      _sortField = FileSortField.values.firstWhere(
-        (f) => f.name == sortFieldName,
-        orElse: () => FileSortField.name,
-      );
-      _sortAscending = prefs.getBool(k(_prefSortAscending)) ?? true;
-      notifyListeners();
+      // Wrapped so a single bad/mistyped stored pref value can't
+      // silently skip fetchAllMedia() below and leave Photos permanently
+      // empty on this activation with no error surfaced anywhere - see
+      // FilesController._onAccountActivated's identical guard for the
+      // real incident this mirrors.
+      try {
+        final prefs = await session.prefsFuture;
+        String k(String base) => session.accountStore.accountPrefKey(id, base);
+        _showFavoritesOnly =
+            prefs.getBool(k(_prefShowFavoritesOnlyPhotos)) ?? false;
+        _showHidden = prefs.getBool(k(_prefShowHiddenPhotos)) ?? false;
+        final sortFieldName = prefs.getString(k(_prefSortField));
+        _sortField = FileSortField.values.firstWhere(
+          (f) => f.name == sortFieldName,
+          orElse: () => FileSortField.name,
+        );
+        _sortAscending = prefs.getBool(k(_prefSortAscending)) ?? true;
+        notifyListeners();
+      } catch (e) {
+        debugPrint('[PhotosController] Account-activation prefs restore failed: $e');
+      }
     }
     unawaited(fetchAllMedia());
   }

lib/providers/session_controller.dart

@@ -8,6 +8,7 @@ import '../services/app_lock_service.dart';
 import '../services/login_flow_service.dart';
 import '../services/nextcloud_service.dart';
 import '../services/sync_service.dart';
+import 'connectivity_controller.dart';
 
 enum LoginFlowStatus { idle, initiating, awaitingBrowser, error }
 
@@ -25,10 +26,21 @@ enum LoginFlowStatus { idle, initiating, awaitingBrowser, error }
 /// `.claude/context/architecture.md`'s "State management" section for the
 /// full rationale.
 class SessionController extends ChangeNotifier with WidgetsBindingObserver {
+  final ConnectivityController connectivity;
   final Future<SharedPreferences> prefsFuture =
       SharedPreferences.getInstance();
   final AccountStore accountStore = AccountStore();
 
+  // True from the moment a saved session is restored (or a network
+  // failure keeps it alive - see `_applyCredentialsForAccount`) without
+  // ever having actually reached the server, until a real
+  // `testConnection()` succeeds. Network-fetching controllers have no
+  // reason to check this themselves - they only ever hear about account
+  // activation via [addAccountActivatedListener], which simply doesn't
+  // fire while this is true (see [addAccountReadyListener] for the
+  // signal that *does* fire either way).
+  bool _isProvisionalLogin = false;
+
   String _serverUrl = '';
   String _username = '';
   String _password = '';
@@ -71,13 +83,23 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
   // them - it's constructed first, they depend on it. `cleared` fires
   // wherever `_clearActiveContent()` used to run (about to switch/log out -
   // reset your own state); `activated` fires only once credentials are
-  // actually verified (fetch your own data now).
+  // actually verified against the server, so it's safe to make network
+  // requests (fetch your own data now) - it deliberately does *not* fire
+  // for a provisional/offline login (see `_isProvisionalLogin`), so a
+  // network-fetching controller never has to check connectivity itself.
+  // `ready` fires in *both* cases - verified or provisional - for the
+  // handful of controllers (SyncStatusController/OfflineController) whose
+  // own activation work is local-only (prefs, on-disk files) and safe to
+  // run with no connection at all.
   final List<VoidCallback> _accountClearedListeners = [];
   final List<VoidCallback> _accountActivatedListeners = [];
+  final List<VoidCallback> _accountReadyListeners = [];
   void addAccountClearedListener(VoidCallback cb) =>
       _accountClearedListeners.add(cb);
   void addAccountActivatedListener(VoidCallback cb) =>
       _accountActivatedListeners.add(cb);
+  void addAccountReadyListener(VoidCallback cb) =>
+      _accountReadyListeners.add(cb);
   void _notifyAccountCleared() {
     for (final cb in _accountClearedListeners) {
       cb();
@@ -88,10 +110,20 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     for (final cb in _accountActivatedListeners) {
       cb();
     }
+    for (final cb in _accountReadyListeners) {
+      cb();
+    }
   }
 
-  SessionController() {
+  void _notifyAccountProvisionallyReady() {
+    for (final cb in _accountReadyListeners) {
+      cb();
+    }
+  }
+
+  SessionController(this.connectivity) {
     WidgetsBinding.instance.addObserver(this);
+    connectivity.addListener(_onConnectivityChanged);
     _init();
   }
 
@@ -175,11 +207,16 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
 
   /// Verifies [appPassword] for [account] and, on success, makes it the
   /// live session, firing [_notifyAccountActivated] so every other
-  /// controller fetches its own data. The password is expected to already
-  /// be durably saved by the caller (either freshly, via
-  /// [_completeLoginFlow], or previously, since this is also how a saved
-  /// session is restored/switched to) - this method only writes to
-  /// [AccountStore] to drop a password that turns out to no longer work.
+  /// controller fetches its own data. With no network route at all, or on
+  /// a network-level (not auth) failure, skips/gives up on verification
+  /// but still logs in *provisionally* - see [_isProvisionalLogin] - so
+  /// the app still opens into `MainShellView` (restricted to the Offline
+  /// tab while offline) instead of bouncing to `LoginView`. The password
+  /// is expected to already be durably saved by the caller (either
+  /// freshly, via [_completeLoginFlow], or previously, since this is also
+  /// how a saved session is restored/switched to) - this method only
+  /// writes to [AccountStore] to drop a password that turns out to no
+  /// longer work (an actual 401, never a network failure).
   Future<bool> _applyCredentialsForAccount(
     SavedAccount account,
     String appPassword,
@@ -199,10 +236,25 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
       password: _password,
     );
 
+    // No point even attempting the request with no network route at all -
+    // treat this exactly like the network-failure branch below (stay
+    // logged in provisionally, `service` already assigned) without paying
+    // for a doomed HTTP call first.
+    if (connectivity.isOffline) {
+      if (gen != _sessionGeneration) return false;
+      _isProvisionalLogin = true;
+      _isLoggedIn = true;
+      _isLoading = false;
+      notifyListeners();
+      _notifyAccountProvisionallyReady();
+      return true;
+    }
+
     try {
       final success = await _service!.testConnection();
       if (gen != _sessionGeneration) return false;
       if (success) {
+        _isProvisionalLogin = false;
         _isLoggedIn = true;
         _isLoading = false;
         notifyListeners();
@@ -212,20 +264,35 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     } catch (e) {
       if (gen != _sessionGeneration) return false;
       _errorMessage = e.toString().replaceAll('Exception: ', '');
-      // Only drop the stored password on an actual auth rejection (401) -
-      // testConnection also throws for network-level failures (DNS,
-      // timeout, unreachable host), and those are transient: deleting a
-      // still-valid password on a dropped connection would permanently
-      // log the account out with no way back in short of Login Flow v2
-      // again, since activeAccountId is never cleared and switchAccount()
-      // no-ops when asked to "switch" to the account that's already
-      // (nominally) active.
+      // Only drop the stored password - and only actually log out - on an
+      // actual auth rejection (401). Every other failure (DNS, timeout,
+      // unreachable host, a transient 5xx) is provisional: staying
+      // "logged in" with the cached account/service lets the app still
+      // land on MainShellView instead of bouncing to LoginView, which
+      // would strand a genuinely offline user with no way back in short
+      // of Login Flow v2 again (activeAccountId is never cleared and
+      // switchAccount() no-ops when asked to "switch" to the account
+      // that's already nominally active). `_service` is already assigned
+      // above and needs no re-creation once connectivity returns.
       if (_errorMessage?.contains('401') == true) {
         await accountStore.deletePassword(account.id);
+        _isProvisionalLogin = false;
+        _isLoggedIn = false;
+        _service = null;
+        _isLoading = false;
+        notifyListeners();
+        return false;
       }
+      _isProvisionalLogin = true;
+      _isLoggedIn = true;
+      _isLoading = false;
+      notifyListeners();
+      _notifyAccountProvisionallyReady();
+      return true;
     }
 
     if (gen != _sessionGeneration) return false;
+    _isProvisionalLogin = false;
     _isLoggedIn = false;
     _service = null;
     _isLoading = false;
@@ -233,6 +300,41 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     return false;
   }
 
+  /// Once connectivity actually returns, re-verifies a provisional/offline
+  /// login for real - this is what finally fires [_notifyAccountActivated]
+  /// (not just [_notifyAccountProvisionallyReady]) so network-fetching
+  /// controllers get their first real fetch without requiring an app
+  /// restart.
+  void _onConnectivityChanged() {
+    _reverifyTimer?.cancel();
+    if (!_isProvisionalLogin || connectivity.isOffline) return;
+    unawaited(_reverify(0));
+  }
+
+  Timer? _reverifyTimer;
+
+  /// One re-verification attempt, retried with a growing delay if the
+  /// server still can't be reached. The OS reports "connected" a moment
+  /// before the route actually works (the first request right after
+  /// regaining Wi-Fi/data fails with "Network is unreachable"), and
+  /// `onConnectivityChanged` won't fire again to give a second chance - so
+  /// without retrying, the login stayed provisional and the Files tab showed
+  /// a connection error until the user tapped Retry.
+  Future<void> _reverify(int attempt) async {
+    if (!_isProvisionalLogin || connectivity.isOffline) return;
+    final id = _activeAccountId;
+    if (id == null) return;
+    final account = _accounts.where((a) => a.id == id).firstOrNull;
+    if (account == null) return;
+    await _applyCredentialsForAccount(account, _password);
+    if (_isProvisionalLogin && !connectivity.isOffline && attempt < 5) {
+      _reverifyTimer = Timer(
+        Duration(seconds: 2 * (attempt + 1)),
+        () => unawaited(_reverify(attempt + 1)),
+      );
+    }
+  }
+
   /// Starts Nextcloud Login Flow v2: asks the server for a one-time login
   /// URL, then polls until the user authorizes (in LoginWebViewView, pushed
   /// by LoginView once loginFlowStatus flips to awaitingBrowser below) and
@@ -370,6 +472,8 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     _activeAccountId = accountId;
     final prefs = await prefsFuture;
     await accountStore.saveActiveAccountId(prefs, accountId);
+    // Signed back in (or switched to) - it syncs in the background again.
+    await accountStore.setSignedOut(prefs, accountId, false);
     notifyListeners();
 
     final account = _accounts.where((a) => a.id == accountId).firstOrNull;
@@ -377,6 +481,7 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
         ? null
         : await accountStore.readPassword(accountId);
     if (account == null || password == null) {
+      _isProvisionalLogin = false;
       _isLoading = false;
       _isLoggedIn = false;
       notifyListeners();
@@ -443,6 +548,9 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     for (final key in AccountStore.perAccountPrefKeys) {
       await prefs.remove(accountStore.accountPrefKey(accountId, key));
     }
+    await accountStore.setSignedOut(prefs, accountId, false);
+    // Its background sync job holds that account's credentials - stop it.
+    unawaited(SyncService.cancelAccount(accountId));
 
     if (!wasActive) {
       notifyListeners();
@@ -466,6 +574,7 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
   Future<void> _deactivateSession() async {
     _sessionGeneration++;
     _notifyAccountCleared();
+    _isProvisionalLogin = false;
     _isLoggedIn = false;
     _serverUrl = '';
     _username = '';
@@ -474,7 +583,6 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
     final prefs = await prefsFuture;
     await accountStore.saveActiveAccountId(prefs, null);
     notifyListeners();
-    unawaited(SyncService.cancel());
   }
 
   /// Ends the active session but keeps this account saved - unlike
@@ -484,8 +592,16 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
   /// Always lands on the login screen even if other accounts are saved -
   /// deliberately not the same as switching to one of them.
   Future<void> logout() async {
-    if (_activeAccountId == null) return;
+    final id = _activeAccountId;
+    if (id == null) return;
+    // Logging out stops that account's background sync (the other saved
+    // accounts keep syncing - each has its own job). It's remembered as
+    // signed out so a later reschedule for some other account doesn't
+    // bring its job back; signing in again re-enables it.
+    final prefs = await prefsFuture;
+    await accountStore.setSignedOut(prefs, id, true);
     await _deactivateSession();
+    unawaited(SyncService.cancelAccount(id));
   }
 
   /// Confirms the device can do local auth and prompts once to enable login
@@ -564,6 +680,8 @@ class SessionController extends ChangeNotifier with WidgetsBindingObserver {
   @override
   void dispose() {
     WidgetsBinding.instance.removeObserver(this);
+    connectivity.removeListener(_onConnectivityChanged);
+    _reverifyTimer?.cancel();
     _pollTimer?.cancel();
     _pollTimeoutTimer?.cancel();
     super.dispose();

lib/providers/sync_status_controller.dart

@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
 import '../models/nextcloud_item.dart';
 import '../models/sync_status.dart';
 import '../services/sync_service.dart';
+import 'files_controller.dart';
 import 'session_controller.dart';
 
 /// Device-sync state and settings: which remote paths (files or folders,
@@ -16,13 +17,37 @@ import 'session_controller.dart';
 /// (`syncStatusFor`) despite living in an unrelated domain; now it's a
 /// second, focused provider those views read alongside their own tab
 /// controller.
-class SyncStatusController extends ChangeNotifier {
+///
+/// **Keeping synced files current.** Synced folders/files follow the same
+/// Files Cache rule (Settings) as folder listings, so nothing needs the
+/// "Sync now" button:
+///
+/// - *Refresh periodically (N min)*: a WorkManager periodic job runs in the
+///   background at that interval (Android's floor is 15 min, so shorter
+///   values only apply in the foreground), and while the app's open an
+///   in-app timer runs a pass every N minutes plus one on resume if it's
+///   been longer than that.
+/// - *Never cache*: no background schedule; a pass runs each time the app
+///   is opened/resumed.
+/// - *Refresh manually only*: only pull-to-refresh (any tab's sync header)
+///   and "Sync now".
+///
+/// Every automatic pass is cheap when nothing changed - the native worker
+/// checks each synced root's etag (Nextcloud propagates any descendant
+/// change up to every ancestor's etag) and skips the full walk if it's
+/// unchanged and the local copy is intact. There's no server push: Nextcloud's
+/// only push channels (the `notify_push` server app, or FCM via Nextcloud's
+/// push proxy) need server-side setup and a persistent connection/registered
+/// app identity, so this polls instead.
+class SyncStatusController extends ChangeNotifier with WidgetsBindingObserver {
   final SessionController session;
+  final FilesController files;
 
-  static const _prefSyncedPaths = 'ui_synced_folders';
+  static const prefSyncedPaths = 'ui_synced_folders';
   static const _prefSyncedPathTypes = 'ui_synced_folder_types';
-  static const _prefSyncEverything = 'ui_sync_everything';
+  static const prefSyncEverything = 'ui_sync_everything';
   static const _prefSyncOnCellular = 'ui_sync_on_cellular';
+  static const _prefSyncNotifications = 'ui_sync_notifications';
 
   List<String> _syncedPaths = [];
   // path -> isFolder, keyed the same as [_syncedPaths] - missing entries
@@ -31,6 +56,7 @@ class SyncStatusController extends ChangeNotifier {
   Map<String, bool> _syncedPathTypes = {};
   bool _syncEverything = false;
   bool _syncOnCellular = false;
+  bool _syncNotifications = true;
 
   bool _isSyncingNow = false;
   Set<String> _syncingFileIds = {};
@@ -38,9 +64,45 @@ class SyncStatusController extends ChangeNotifier {
   List<SyncConflictInfo> _syncConflicts = [];
   StreamSubscription<SyncStatusSnapshot>? _statusSub;
 
-  SyncStatusController(this.session) {
+  // Gates addSyncedPaths/removeSyncedPaths (anything that persists
+  // _syncedPaths) against running before _onAccountActivated's async
+  // prefs load has actually finished - without this, syncing a folder
+  // right after opening the app could race the load, overwrite the
+  // persisted list with just the one path being added/removed, and
+  // silently destroy every previously-synced folder. Deliberately starts
+  // *incomplete*, not pre-completed - a mutation is only ever reachable
+  // from Files/Offline UI, which requires a completed activation already
+  // (Files' own item list depends on the same login event), so there's no
+  // real deadlock risk, and starting complete would leave the very first
+  // cold-start load completely unprotected (only account *switches*
+  // re-arm it, via _onAccountCleared - the bug that actually caused
+  // repeated data loss here).
+  Completer<void> _accountLoadedGate = Completer<void>();
+
+  // True once _syncedPaths/_syncedPathTypes/_syncEverything have been
+  // loaded from prefs for the *current* account - _onAccountActivated can
+  // fire more than once per account (e.g. SessionController re-verifying
+  // a provisional/offline login once connectivity returns), and a second
+  // pass re-reading from storage could clobber an in-memory mutation made
+  // between the first load and the second one if its own persist hadn't
+  // landed yet. Reset in _onAccountCleared.
+  bool _hasLoadedSyncedPathsForAccount = false;
+
+  Timer? _autoSyncTimer;
+  bool _foreground = true;
+  DateTime? _lastAutoSyncAt;
+  CachePolicy? _lastPolicy;
+  int? _lastInterval;
+
+  SyncStatusController(this.session, this.files) {
+    WidgetsBinding.instance.addObserver(this);
+    files.addListener(_onFilesChanged);
     session.addAccountClearedListener(_onAccountCleared);
-    session.addAccountActivatedListener(_onAccountActivated);
+    // `ready`, not `activated` - this controller's own activation work
+    // (loading prefs, calling the native sync channel) is local/native
+    // only, so it's safe to run even on a provisional/offline login (see
+    // `SessionController.addAccountReadyListener`'s doc comment).
+    session.addAccountReadyListener(_onAccountActivated);
     _statusSub = SyncService.statusStream.listen(_applySnapshot);
     _loadGlobalPrefs();
   }
@@ -49,7 +111,21 @@ class SyncStatusController extends ChangeNotifier {
   bool get syncEverything => _syncEverything;
   bool get syncOnCellular => _syncOnCellular;
 
+  /// Whether background (automatic) sync runs may post progress/summary
+  /// notifications. Conflicts and user-initiated "Sync now" always notify.
+  bool get syncNotifications => _syncNotifications;
+
   bool get isSyncingNow => _isSyncingNow;
+
+  bool get _hasSyncScope => _syncEverything || _syncedPaths.isNotEmpty;
+
+  /// How often the background WorkManager job should run, or null for no
+  /// background sync at all - only the "refresh periodically" Files Cache
+  /// policy schedules one (see the class doc comment).
+  int? get backgroundSyncIntervalMinutes =>
+      files.cachePolicy == CachePolicy.interval
+      ? files.cacheIntervalMinutes
+      : null;
   List<SyncConflictInfo> get syncConflicts => List.unmodifiable(_syncConflicts);
 
   /// How many of [syncedPaths] are folders (as opposed to individual
@@ -57,11 +133,6 @@ class SyncStatusController extends ChangeNotifier {
   int get syncedFolderCount =>
       _syncedPaths.where((p) => _syncedPathTypes[p] ?? true).length;
 
-  /// How many individual files have actually been mirrored locally so far
-  /// - distinct from [syncedFolderCount]/[syncedPaths], which are just the
-  /// configured *targets*, not what's actually landed on disk yet.
-  int get syncedItemCount => _syncedFileIds.length;
-
   SyncHeaderStatus get syncHeaderStatus {
     if (_syncConflicts.isNotEmpty) return SyncHeaderStatus.alert;
     if (_isSyncingNow) return SyncHeaderStatus.syncing;
@@ -121,10 +192,21 @@ class SyncStatusController extends ChangeNotifier {
   Future<void> _loadGlobalPrefs() async {
     final prefs = await session.prefsFuture;
     _syncOnCellular = prefs.getBool(_prefSyncOnCellular) ?? _syncOnCellular;
+    _syncNotifications =
+        prefs.getBool(_prefSyncNotifications) ?? _syncNotifications;
     notifyListeners();
   }
 
   void _onAccountCleared() {
+    // Re-armed (not completed) here, not just at construction - an
+    // account switch means the *next* activation's load has to finish
+    // before any mutation touching _syncedPaths is safe again. Only
+    // replace the Completer if nothing's still awaiting the old one -
+    // swapping it out from under a pending awaiter would orphan that
+    // await forever, since nothing would ever complete the discarded
+    // instance.
+    if (_accountLoadedGate.isCompleted) _accountLoadedGate = Completer<void>();
+    _hasLoadedSyncedPathsForAccount = false;
     _syncedPaths = [];
     _syncedPathTypes = {};
     _syncEverything = false;
@@ -132,47 +214,175 @@ class SyncStatusController extends ChangeNotifier {
     _syncingFileIds = {};
     _syncedFileIds = {};
     _syncConflicts = [];
+    _autoSyncTimer?.cancel();
+    _lastAutoSyncAt = null;
+    _lastPolicy = null;
+    _lastInterval = null;
     notifyListeners();
   }
 
   Future<void> _onAccountActivated() async {
     final id = session.activeAccountId;
-    if (id != null) {
-      final prefs = await session.prefsFuture;
-      String k(String base) => session.accountStore.accountPrefKey(id, base);
-      final pathsJson = prefs.getString(k(_prefSyncedPaths));
-      if (pathsJson != null) {
-        try {
-          _syncedPaths = (jsonDecode(pathsJson) as List).cast<String>();
-        } catch (e) {
-          debugPrint('[SyncStatusController] Synced paths restore failed: $e');
+    // Only load _syncedPaths/_syncedPathTypes/_syncEverything once per
+    // account, not on every activation - this can fire more than once
+    // for the same account (e.g. SessionController re-verifying a
+    // provisional/offline login once connectivity returns), and a second
+    // read from storage could clobber an in-memory mutation made between
+    // the first load and this one if its own persist hadn't landed yet.
+    // See _hasLoadedSyncedPathsForAccount's doc comment.
+    if (id != null && !_hasLoadedSyncedPathsForAccount) {
+      _hasLoadedSyncedPathsForAccount = true;
+      // Wrapped so a single bad/mistyped stored pref value can't
+      // propagate uncaught out of this method and skip the gate
+      // completion below - that would leave every future
+      // addSyncedPaths/removeSyncedPaths call awaiting a gate that never
+      // completes, hanging forever. See FilesController.
+      // _onAccountActivated's identical guard for the real incident this
+      // mirrors.
+      try {
+        final prefs = await session.prefsFuture;
+        String k(String base) => session.accountStore.accountPrefKey(id, base);
+        final pathsJson = prefs.getString(k(prefSyncedPaths));
+        if (pathsJson != null) {
+          try {
+            _syncedPaths = (jsonDecode(pathsJson) as List).cast<String>();
+          } catch (e) {
+            debugPrint('[SyncStatusController] Synced paths restore failed: $e');
+            _syncedPaths = [];
+          }
+        } else {
           _syncedPaths = [];
         }
-      } else {
-        _syncedPaths = [];
-      }
-      final typesJson = prefs.getString(k(_prefSyncedPathTypes));
-      if (typesJson != null) {
-        try {
-          _syncedPathTypes = (jsonDecode(typesJson) as Map).map(
-            (k, v) => MapEntry(k as String, v as bool),
-          );
-        } catch (e) {
-          debugPrint('[SyncStatusController] Synced path types restore failed: $e');
+        final typesJson = prefs.getString(k(_prefSyncedPathTypes));
+        if (typesJson != null) {
+          try {
+            _syncedPathTypes = (jsonDecode(typesJson) as Map).map(
+              (k, v) => MapEntry(k as String, v as bool),
+            );
+          } catch (e) {
+            debugPrint('[SyncStatusController] Synced path types restore failed: $e');
+            _syncedPathTypes = {};
+          }
+        } else {
           _syncedPathTypes = {};
         }
-      } else {
-        _syncedPathTypes = {};
+        _syncEverything = prefs.getBool(k(prefSyncEverything)) ?? false;
+        notifyListeners();
+      } catch (e) {
+        debugPrint('[SyncStatusController] Account-activation prefs restore failed: $e');
       }
-      _syncEverything = prefs.getBool(k(_prefSyncEverything)) ?? false;
-      notifyListeners();
     }
+    // Only now is it safe for addSyncedPaths/removeSyncedPaths to mutate
+    // and persist _syncedPaths - see _accountLoadedGate's doc comment.
+    if (!_accountLoadedGate.isCompleted) _accountLoadedGate.complete();
+    unawaited(SyncService.getStatus(id).then(_applySnapshot));
+
+    // Scheduling depends on the Files Cache policy, so wait for it to load
+    // rather than scheduling from the defaults and correcting a moment later.
+    await files.displayPrefsLoaded;
+    _lastPolicy = files.cachePolicy;
+    _lastInterval = files.cacheIntervalMinutes;
     unawaited(SyncService.reschedule(session, this));
-    unawaited(SyncService.getStatus().then(_applySnapshot));
+    _restartAutoSyncTimer();
+    if (_dueForAutoSync) unawaited(_autoSync());
+  }
+
+  // ---- Automatic sync (see the class doc comment) ----
+
+  void _onFilesChanged() {
+    // FilesController notifies on every navigation - only the cache rule
+    // itself matters here.
+    if (_lastPolicy == null) return; // account not activated yet
+    final policy = files.cachePolicy;
+    final interval = files.cacheIntervalMinutes;
+    if (policy == _lastPolicy && interval == _lastInterval) return;
+    _lastPolicy = policy;
+    _lastInterval = interval;
+    unawaited(SyncService.reschedule(session, this));
+    _restartAutoSyncTimer();
+  }
+
+  /// Whether an app-open/resume should kick off a pass under the current
+  /// cache rule.
+  bool get _dueForAutoSync {
+    switch (files.cachePolicy) {
+      case CachePolicy.never:
+        return true;
+      case CachePolicy.manual:
+        return false;
+      case CachePolicy.interval:
+        final last = _lastAutoSyncAt;
+        return last == null ||
+            DateTime.now().difference(last) >=
+                Duration(minutes: files.cacheIntervalMinutes);
+    }
+  }
+
+  void _restartAutoSyncTimer() {
+    _autoSyncTimer?.cancel();
+    if (!_foreground ||
+        !_hasSyncScope ||
+        files.cachePolicy != CachePolicy.interval) {
+      return;
+    }
+    _autoSyncTimer = Timer.periodic(
+      Duration(minutes: files.cacheIntervalMinutes),
+      (_) => unawaited(_autoSync()),
+    );
+  }
+
+  /// A quiet, network-setting-respecting pass - see [SyncService.syncNow].
+  Future<void> _autoSync() async {
+    if (!_canSyncQuietly) return;
+    _lastAutoSyncAt = DateTime.now();
+    try {
+      await SyncService.syncNow(
+        session,
+        this,
+        force: false,
+        respectNetworkSetting: true,
+      );
+    } catch (e) {
+      debugPrint('[SyncStatusController] Automatic sync failed: $e');
+    }
+  }
+
+  /// A deliberate pull-to-refresh (any tab's sync header): check for server
+  /// changes now, regardless of the cache rule or the Wi-Fi-only setting.
+  Future<void> syncOnPull() async {
+    if (!_canSyncQuietly) return;
+    try {
+      await SyncService.syncNow(session, this, force: false);
+    } catch (e) {
+      debugPrint('[SyncStatusController] Pull-triggered sync failed: $e');
+    }
+  }
+
+  bool get _canSyncQuietly =>
+      _hasSyncScope &&
+      !_isSyncingNow &&
+      session.isLoggedIn &&
+      !session.connectivity.isOffline;
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state == AppLifecycleState.resumed) {
+      _foreground = true;
+      _restartAutoSyncTimer();
+      if (_dueForAutoSync) unawaited(_autoSync());
+    } else if (state == AppLifecycleState.paused) {
+      // The in-app timer only runs while foregrounded; WorkManager owns the
+      // background schedule.
+      _foreground = false;
+      _autoSyncTimer?.cancel();
+    }
   }
 
   void _applySnapshot(SyncStatusSnapshot snapshot) {
-    if (snapshot.accountId != null &&
+    // A null accountId is the bus's initial "nothing has synced in this
+    // process yet" emission on subscribe - applying it would wipe the
+    // synced-file ids seeded by getStatus(accountId).
+    if (snapshot.accountId == null ||
         snapshot.accountId != session.activeAccountId) {
       return;
     }
@@ -181,6 +391,11 @@ class SyncStatusController extends ChangeNotifier {
     _syncedFileIds = snapshot.syncedFileIds;
     _syncConflicts = snapshot.conflicts;
     notifyListeners();
+
+    // A synced file/folder deleted on the server has nothing left to sync -
+    // drop it from the synced list rather than leaving a dead entry.
+    final gone = snapshot.missingRoots.where(_syncedPaths.contains).toList();
+    if (gone.isNotEmpty) unawaited(removeSyncedPaths(gone));
   }
 
   void _persistSyncedPaths() {
@@ -188,7 +403,7 @@ class SyncStatusController extends ChangeNotifier {
     if (id == null) return;
     session.prefsFuture.then((p) {
       p.setString(
-        session.accountStore.accountPrefKey(id, _prefSyncedPaths),
+        session.accountStore.accountPrefKey(id, prefSyncedPaths),
         jsonEncode(_syncedPaths),
       );
       p.setString(
@@ -200,26 +415,74 @@ class SyncStatusController extends ChangeNotifier {
 
   bool isPathSynced(String path) => _syncedPaths.contains(path);
 
-  void addSyncedPath(String path, {required bool isFolder}) {
-    if (_syncedPaths.contains(path)) return;
-    _syncedPaths = [..._syncedPaths, path];
-    _syncedPathTypes = {..._syncedPathTypes, path: isFolder};
+  Future<void> addSyncedPath(String path, {required bool isFolder}) {
+    return addSyncedPaths({path: isFolder});
+  }
+
+  /// Adds every path in [entries] (path -> isFolder) to sync in one go -
+  /// unlike calling [addSyncedPath] once per item in a loop, this touches
+  /// `_syncedPaths`/persists/reschedules/triggers an immediate sync
+  /// exactly once no matter how many paths are being added. Looping
+  /// `addSyncedPath` from a multi-select "Sync to device" was the actual
+  /// bug behind only the first selected item ever actually syncing: each
+  /// call fired its own `SyncService.syncNow`, and WorkManager's
+  /// `enqueueUniqueWork(..., ExistingWorkPolicy.REPLACE, ...)` policy
+  /// meant each later call cancelled the previous item's still-in-flight
+  /// sync pass (and could stomp on its `SyncEngine.saveState`, which
+  /// overwrites the whole state map rather than merging) instead of
+  /// letting it finish.
+  Future<void> addSyncedPaths(Map<String, bool> entries) async {
+    // Must not mutate/persist _syncedPaths before the per-account load
+    // has actually populated it - see _accountLoadedGate's doc comment.
+    await _accountLoadedGate.future;
+    var changed = false;
+    entries.forEach((path, isFolder) {
+      if (_syncedPaths.contains(path)) return;
+      _syncedPaths = [..._syncedPaths, path];
+      _syncedPathTypes = {..._syncedPathTypes, path: isFolder};
+      changed = true;
+    });
+    if (!changed) return;
     notifyListeners();
     _persistSyncedPaths();
     unawaited(SyncService.reschedule(session, this));
+    _restartAutoSyncTimer();
+    // `reschedule` alone only lines up the *periodic* job, which can be up
+    // to an hour away from its first run - without an immediate one-off
+    // sync here too, newly-added items would just sit unsynced until the
+    // user thought to trigger one manually (e.g. pulling to refresh on
+    // the Offline tab).
+    unawaited(_syncNowSilently());
   }
 
   /// Unsyncs [path] and deletes its already-downloaded local mirror (see
   /// `SyncService.removeLocalSync`) - stopping sync alone would leave
   /// whatever had already been downloaded sitting on disk indefinitely.
-  void removeSyncedPath(String path) {
-    if (!_syncedPaths.contains(path)) return;
-    _syncedPaths = _syncedPaths.where((f) => f != path).toList();
-    _syncedPathTypes = {..._syncedPathTypes}..remove(path);
+  Future<void> removeSyncedPath(String path) {
+    return removeSyncedPaths([path]);
+  }
+
+  /// Batched counterpart to [removeSyncedPath] - see [addSyncedPaths]'s
+  /// doc comment for why a multi-item loop of individual calls is unsafe
+  /// for `reschedule`/native side effects, even though removal itself
+  /// (unlike adding) doesn't trigger a one-off sync to race.
+  Future<void> removeSyncedPaths(List<String> paths) async {
+    await _accountLoadedGate.future;
+    var changed = false;
+    for (final path in paths) {
+      if (!_syncedPaths.contains(path)) continue;
+      _syncedPaths = _syncedPaths.where((f) => f != path).toList();
+      _syncedPathTypes = {..._syncedPathTypes}..remove(path);
+      changed = true;
+    }
+    if (!changed) return;
     notifyListeners();
     _persistSyncedPaths();
     unawaited(SyncService.reschedule(session, this));
-    unawaited(SyncService.removeLocalSync(session, path));
+    _restartAutoSyncTimer();
+    for (final path in paths) {
+      unawaited(SyncService.removeLocalSync(session, path));
+    }
   }
 
   void setSyncEverything(bool value) {
@@ -230,12 +493,24 @@ class SyncStatusController extends ChangeNotifier {
     if (id != null) {
       session.prefsFuture.then(
         (p) => p.setBool(
-          session.accountStore.accountPrefKey(id, _prefSyncEverything),
+          session.accountStore.accountPrefKey(id, prefSyncEverything),
           value,
         ),
       );
     }
     unawaited(SyncService.reschedule(session, this));
+    _restartAutoSyncTimer();
+    if (value) unawaited(_syncNowSilently());
+  }
+
+  void setSyncNotifications(bool value) {
+    if (_syncNotifications == value) return;
+    _syncNotifications = value;
+    notifyListeners();
+    session.prefsFuture.then((p) => p.setBool(_prefSyncNotifications, value));
+    // Baked into each periodic job's input, so the jobs have to be
+    // re-enqueued for the change to reach background runs.
+    unawaited(SyncService.reschedule(session, this));
   }
 
   void setSyncOnCellular(bool value) {
@@ -246,6 +521,18 @@ class SyncStatusController extends ChangeNotifier {
     unawaited(SyncService.reschedule(session, this));
   }
 
+  /// Fire-and-forget immediate sync, swallowing errors - called right
+  /// after turning sync on for something (see [addSyncedPath]/
+  /// [setSyncEverything]) so it actually starts syncing now instead of
+  /// only ever running on the next periodic pass or a manual "Sync now".
+  Future<void> _syncNowSilently() async {
+    try {
+      await SyncService.syncNow(session, this);
+    } catch (e) {
+      debugPrint('[SyncStatusController] Immediate sync failed: $e');
+    }
+  }
+
   /// In-app conflict resolution (the sync header's "Keep local"/"Use
   /// server" buttons) - see `SyncService.resolveConflict`'s doc comment
   /// for why this shares the exact same native path the notification
@@ -277,6 +564,9 @@ class SyncStatusController extends ChangeNotifier {
 
   @override
   void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    files.removeListener(_onFilesChanged);
+    _autoSyncTimer?.cancel();
     _statusSub?.cancel();
     super.dispose();
   }