noo/.claude/context/server.md

Server integration

Auth: Login Flow v2

The app never collects a Nextcloud password directly. It implements Login Flow v2 via LoginFlowService:

1. LoginFlowService.initiate(serverUrl) POSTs to {server}/index.php/login/v2, gets back a browser login URL + a poll endpoint/token.
2. The app opens the login URL for the user to authenticate/authorize in LoginWebViewView, a normal screen this app owns (package:webview_flutter) - pushed by LoginView the moment loginFlowStatus flips to awaitingBrowser, for every login (first account or an additional one), not just add-account. This used to be split: first login went through a Chrome Custom Tab (url_launcher, LaunchMode.inAppBrowserView) for Chrome's own autofill, and only add-account used the embedded WebView, specifically to avoid a Custom Tab silently reusing Chrome's existing session for a different account. But a Custom Tab has real costs even for the first login - no way to close it automatically on success (the user has to switch back manually), and it's a separate task outside this app's own navigation entirely - so both paths now use the same owned screen. url_launcher is no longer a dependency. The cost is no Chrome-autofill (Android's own system Autofill framework, e.g. a password manager, may still work in the WebView; Chrome's own saved-password autofill specifically cannot, since that's Chrome-only). LoginWebViewView also clears cookies (WebViewCookieManager(). clearCookies()) before every load, not just once - Android's WebView CookieManager is a single store shared/persisted across every WebView instance in the app process, not scoped per-controller, so without this a second/"Add Account" login silently reuses whichever account's Nextcloud session cookie is already there instead of prompting for credentials (the same class of bug the Custom-Tab-reuse issue above was, just recurring one layer down once everything moved to the owned WebView).
3. SessionController polls LoginFlowService.poll(pollEndpoint, token) every 2 seconds (Timer.periodic, see _pollTimer/_pollTimeoutTimer in session_controller.dart) until it gets a 200 with server/loginName/ appPassword, a non-404 error, or a 10-minute timeout. A single dropped connection mid-poll (http.ClientException) is swallowed and retried on the next tick rather than aborting the whole flow.
4. The returned app password (scoped, revocable) is what gets stored and used for every subsequent request — real user passwords are never in memory or on disk.

LoginFlowStatus (idle → initiating → awaitingBrowser → error) drives LoginView's UI; see LoginFlowService's doc comment for the full flow rationale before changing it.

startLoginFlow(serverUrl, {addAccount = false}) is reused verbatim for both the first/only login and "add another account" (pushed from Settings while already logged into a different account, LoginView(isAddingAccount: true)) — addAccount only flags isAddAccountFlow for the UI (so the pushed screen knows to auto-pop on success and cancel the flow on back-swipe); the persistence path on success is identical either way, see below.

Talking to the server

NextcloudService is the client for an authenticated session — constructed with serverUrl + username + the app password, one instance per login (held as SessionController.service, recreated on every login/switch/logout). It's effectively stateless per-instance (three final fields, headers rebuilt per request), which is what makes it trivial to have one saved per account rather than needing a rewrite for multi-account support.

• Files: WebDAV (PROPFIND/MKCOL/DELETE/MOVE/PUT etc. against /remote.php/dav/files/{username}/...) via raw http/dio calls with a hand-rolled XML request body and package:xml for parsing responses — there is no WebDAV client dependency. _parseDavDate/_davPath in this file exist because WebDAV responses use RFC 1123 dates and either bare paths or full URLs for href; reuse them rather than re-deriving. creationdate specifically needs _parseDavCreationDate, not _parseDavDate directly - Nextcloud has no real per-file creation-time tracking for most setups, so that property routinely comes back as a placeholder Unix-epoch date rather than being omitted, which _parseDavDate alone parses "successfully" into a real (if bogus) January 1970 DateTime. _parseDavCreationDate treats that placeholder as absent instead, so NextcloudItem.dateCreated falls back to lastModified (its constructor's default) the same as it would for a missing/unparseable value.
• Everything else (shares, activity, trash, favorites, quota, user info, file versions) goes through Nextcloud's OCS APIs (/ocs/v2.php/...), JSON in, with the OCS-APIRequest: true header required on every OCS call. Toggling a favorite is OCS; listing every favorite (fetchFavorites, for the Favorites tab) is WebDAV instead - the same SEARCH mechanism fetchAllMedia/fetchRecentFiles use, filtered by oc:favorite instead of mimetype/date. Favorites is a real tab (views/favorites_view.dart/FavoritesController.items/ fetchAll/_allFavorites), not a filter toggle scoped to whatever folder the Files tab happens to be browsing (that's what it used to be - see the note below on why that didn't work). It shares Files' own sort/hidden/storage-scope/grid-list display prefs (applyFilesDisplayPrefs, also used by the Move/Copy destination picker) rather than a separate parallel settings dimension. Tapping a favorited folder switches to the Files tab, navigated there (FilesController.navigateToAbsoluteFolder + SettingsController.requestTab); a favorited file opens directly from the Favorites tab itself. ItemOperations.deleteItem/renameItem/move/ copy all re-sync FavoritesController._allFavorites afterward via FavoritesController.syncIfLoaded (only once Favorites has actually been opened this session, tracked by _everFetched, so those actions don't pay for an extra request on every edit for an account that's never visited the tab) since none of them know how to patch _allFavorites in place the way ItemOperations.toggleItemFavorite does (added/removed/ updated by id, right inline via FavoritesController.applyFavoriteToggle). Note: this used to be a "favorites-only" filter toggle on the Files tab's controls row instead of its own tab, filtering the currently browsed folder's _items. That had two real bugs in sequence: first, the filter dropped every non-favorited item including folders, so a non-favorited folder (containing a favorited item nested inside) vanished from the listing entirely, with no way to navigate into it; fixing that by exempting folders from the filter was itself wrong, because the actual intent was for favorites-only to show every favorited item account-wide, not just direct children of whatever folder was open - a strict filter over the wrong scope. Converting it to a real tab, backed by an account-wide fetch, was the actual fix; keep favorites account-wide rather than reintroducing a current-folder-scoped filter.
• Auth header is HTTP Basic (username:appPassword, base64), built in _headers/exposed as authHeaders for widgets that need to hit URLs directly (e.g. Image.network(url, headers: service.authHeaders) for thumbnails/previews).
• NextcloudService.downloadToFile (Dio, progress callbacks) is still used for small in-app-only downloads: text/PDF previews (fetchBytes via package:http) and "open externally" (FileViewerScreen._downloadToTemp streams to the app's own cache dir so open_file can hand it to another app). Explicitly saving a file to the device - the "Download" action in Files/Photos' selection toolbar and the media viewer's download button
  • instead hands off to DownloadService.kt, an Android foreground service, the same way "Share to Noo" hands its upload off to ShareUploadService.kt (see that section below) rather than downloading in Dart and prompting file_saver per file: a real Service survives the app being closed mid-download, with one cancellable notification for the whole batch. DownloadService.kt re-implements a plain WebDAV GET in Kotlin for the same reason ShareUploadService.kt's PUT does - keep NextcloudService.downloadToFile in sync manually if download semantics change - and writes straight into the device's public Downloads collection via MediaStore.Downloads (API 29+; a background Service can't prompt file_saver's SAF picker the way the Flutter/Activity side can, so this is the direct equivalent) with a legacy Environment.DIRECTORY_DOWNLOADS file-write fallback pre-Android-10. Folders are filtered out client-side before handing off (no recursive/ zip download support); DetailsVersionsTab's version-restore download and ShareSheet's "Share file directly" (native OS share, not saved to Downloads) keep using downloadToFile directly instead, since both need the bytes in-app rather than saved to Downloads.
• Move/Copy (moveItem/copyItem(itemPath, destFolderPath, {overwrite, newName})) share one private _moveOrCopy helper with renameItem (itself just a same-folder MOVE) - WebDAV MOVE/COPY are the same request shape, just a different verb, and both are recursive by default for a folder ("collection"), so no extra Depth header is needed. They return the raw HTTP status rather than a bool: 412 Precondition Failed is WebDAV's standard signal for "something's already there" when Overwrite: F, which is exactly the conflict ItemOperations.moveItems/ copyItems need to detect without a separate existence-check request per item. ItemOperations attempts every item in the batch first, collects conflicts into MoveCopyResult.conflicts (models/move_copy_result.dart), and only then shows one summary (MoveCopyConflictSheet) instead of prompting per conflict as they're hit; resolving picks overwrite/keep-both (auto-renamed via _nextAvailableName against a fresh listing of the destination, fetched once up front, not per item)/skip per item via resolveConflicts. The destination-picker screen behind this (views/move_copy_destination_picker.dart) is covered in architecture.md, including why it can't reuse the Files tab's shared navigation state the way ShareUploadView does.
• Uploads: there's no more in-app-only upload path - NextcloudService's own uploadFileFromPath was removed once the Files tab's "+" → "Upload File" was unified with the share-to-upload flow (below). Every upload, however it's triggered, now goes through ShareUploadView (caller-chosen destination via FilesController.navigateToAbsoluteFolder, then UploadService/ShareUploadService.kt).
• Receiving a shared file from another app: hand-rolled in MainActivity.kt (Android ACTION_SEND/ACTION_SEND_MULTIPLE, android:launchMode singleTask in the manifest so a second share while running hits onNewIntent instead of spawning a new instance) plus ShareIntentService on the Dart side - not the receive_sharing_intent plugin, which this used to be. That plugin resolves a shared content:// Uri by synchronously copying the entire file into the cache dir on the main thread during activity startup; for a large file that blocks long enough that Android kills the newly-launched activity for failing to draw a first frame, dropping the user straight back to the home screen with no error and no Dart code ever running. MainActivity.kt's doc comment has the full story. The fix: getInitialShare/onNewShare only ever query cheap Uri metadata (name/size/mime, not content) so ShareUploadView's destination picker - which mirrors the Files tab's own controls/filters/listing, reusing the same FilesController fields and widgets/item_icon.dart - always appears instantly regardless of file size.
• Uploading a shared file: once the user picks a destination in ShareUploadView, UploadService hands the whole batch off to ShareUploadService.kt, an Android foreground service, rather than uploading from Dart in that screen. This is deliberate, not just an implementation detail: the point is that closing the app right after confirming a destination doesn't interrupt the upload, the same guarantee a real file-manager app's upload notification gives you - a plain Dart Future (even one kept alive by a singleton service class) stops running once the Flutter engine/Activity are gone, only an actual Android Service survives that. The service re-implements the WebDAV PUT itself in Kotlin (HttpURLConnection, no new HTTP dependency) since it can't reach the Dart-side NextcloudService/ Dio from a separate process lifecycle - UploadService.startUpload passes everything the Kotlin side needs (the pre-built Authorization header from NextcloudService.authHeaders, not the raw password) as Intent extras, a one-way handoff for the start of the upload - the Kotlin side never asks Dart anything mid-upload, since the app may not even be running by then. Keep the two upload implementations in sync manually if upload semantics change. Progress/cancellation is entirely notification- driven (one ongoing, updatable notification for the whole batch; its Cancel action re-delivers an Intent to the same running service instance, which an AtomicBoolean the copy/upload loops poll) - the notification is the only UI a closed app gets. There is one thing that does come back, when the app is still running: once a batch finishes with at least one success, ShareUploadService.kt publishes into UploadEventBus (an in-process pub/sub, same shape as SyncStatusBus below), which MainActivity.kt forwards to Dart over the dev.ayushya.noo/upload_service/status EventChannel - UploadService.completions. FilesController subscribes in its own constructor and calls refreshData() when the event's folder matches currentFolderPath, so a file uploaded into the folder currently on screen shows up without a manual pull-to-refresh. Follows SyncService.statusStream's "one shared static final stream" rule (see its own doc comment) - a second receiveBroadcastStream() subscriber would silently steal the single native-side listener from the first.

Being picked by other apps (photo/file picker)

Noo can also be launched by another app as a GET_CONTENT picker (e.g. Google Drive/Instagram's "choose a file" flow), the reverse direction of "Share to Noo" above - hand-rolled the same way, not a plugin.

• MainActivity.kt matches ACTION_GET_CONTENT (OPENABLE, any mimeType - a single */* filter, since Android matches it against whatever the caller actually requested) alongside its existing ACTION_SEND/SEND_MULTIPLE filters, and exposes the caller's requested mimeType/multi-select flag/app label via the dev.ayushya.noo/pick_intent method+event channel pair (PickIntentService/ PickRequest) - same cold-start-vs-already-running split as the share-intent channels.
• PickController.pickRequest/isPicking drive picking mode app-wide once MainShellView learns about a request at startup or via onNewPickRequest. While picking, MainShellView restricts the visible bottom-nav tabs to just Files and Photos (see architecture.md) - FilesView/PhotosView route taps through itemMatchesPickFilter/confirmPick instead of their normal open/select behavior (folders still navigate; a mime-mismatched file is rejected with a snackbar; matching files toggle-select or immediately confirm depending on PickRequest.allowMultiple).
• PickController.confirmPick downloads the selected item(s) to a picker/ scratch subfolder in the app's cache dir (downloadToFile, same as any other download) - each item into its own picker/<item.id>/ subfolder, keeping the on-disk filename as plain item.name rather than prefixing it with the id to dodge collisions between same-named items; the caller reads that on-disk name back as the display name, so prefixing it there was a real bug (Drive showing e.g. 163332_photo.jpg instead of photo.jpg) - then hands the local paths to PickIntentService.finishPick, which calls back into MainActivity.kt.finishPick: it wraps each file in a content:// Uri via this app's own FileProvider (${applicationId}.picker.fileprovider, scoped to just that cache subfolder - see android/app/src/main/res/xml/ file_paths.xml) and returns it to the caller via setResult. Single file uses setDataAndType (never .data =/.type = as two separate calls - each one silently nulls out the other field on a plain Intent); multiple files use ClipData. cancelPick mirrors this for backing out (system back while picking, or a picked-item mismatch) with RESULT_CANCELED instead.

Device sync

Mirrors selected folders to app-private local storage (getExternalFilesDir(null)/sync/<accountId>/... - wiped on uninstall, no extra storage permission needed) and keeps them updated in the background, even with the app fully closed. Same rationale as the upload/download services for going native instead of a Dart background-task plugin (see above): a periodic job has to run without the Flutter engine loaded, and a notification action has to resolve without launching the UI. Rather than add workmanager (whose Dart callbackDispatcher spins up a second, minimal Flutter engine that has to re-register every plugin it touches), the whole engine is plain Kotlin using Android's WorkManager directly.

• SyncEngine.kt holds the shared primitives, reused by both workers below: a Depth-1 (or Depth-0, for refreshing one item) PROPFIND (propfindChildren/ propfindSelf) requesting d:getetag alongside the usual props - unlike every PROPFIND in nextcloud_service.dart, which never requests it (etag is a dead field on NextcloudItem today); plain HttpURLConnection GET/PUT (downloadFile/uploadFile, same style as DownloadService.kt/ShareUploadService.kt); and diffFolder, which compares one folder's freshly-walked manifest against the persisted per-account sync-state map (native SharedPreferences, JSON keyed by oc:fileid - stable across renames/moves, unlike path) to decide, per file: download (new, or server etag changed), upload (local file's mtime/size changed and the server didn't), delete locally (missing server-side, unchanged locally), re-download a file whose local copy is missing even though state says it was mirrored (stale state from an earlier sync of the path - treating that as "user deleted it" used to skip the download and report phantom removals), or flag a conflict (both changed since the last recorded state). The "removed" count in the summary notification only counts local files that actually existed and were deleted.
• SyncWorker.kt (CoroutineWorker) is both the periodic job and the one-off "Sync now": for each configured path, propfindSelfs it first to check whether it's a file or a folder - a folder gets the full recursive walkRemoteTree, a file is diffed directly as a one-item list (nothing else about diffFolder/download/upload/delete cares whether its entries came from a walk or a single lookup, so single-file sync needed no engine changes, just this one branch) - applies diffFolder's decisions, then posts a summary notification (files updated/uploaded/removed) and, for any conflicts, one notification per file with two actions. A progress notification (notifyProgress) is shown lazily - only once the first actual download/upload starts, not unconditionally at the top of every run, so a periodic pass that finds nothing to transfer never flashes a notification at all. It shares the summary's notification ID (SUMMARY_NOTIFICATION_ID) on purpose: the final notifySummary call naturally replaces the ongoing progress notification in place once the run finishes (no flicker of two separate notifications), and if nothing ended up changing, doWork explicitly cancels that ID since there's no summary to replace it with.
• Live status reaches Dart via a push channel, not polling - SyncStatusBus.kt is a plain in-process pub/sub (no IPC needed - the workers and MainActivity share one process) that SyncWorker/ConflictResolveWorker publish into (syncing started/stopped, which fileIds are mid-transfer right now, new/resolved conflicts) and MainActivity.kt's dev.ayushya.noo/sync_service/status EventChannel forwards to Dart, same pattern as the share/pick-intent channels. It deliberately does not track "which files are already synced" itself - that's read fresh from SyncEngine's durable per-account state map (SyncEngine.loadState(accountId).keys) each time a snapshot is built, so there's one source of truth for "synced" instead of two that could drift - which is also why SyncWorker.doWork() saves state before its final SyncStatusBus.setSyncing(accountId, false) publish, not after: that publish is what tells Dart's live listener to recompute syncedFileIds, so publishing first would hand back a snapshot still missing every file the run just downloaded, with no further event ever arriving afterward to correct it - newly-synced files would sit with no badge until the app restarted and force-refreshed via getStatus(). SyncService.getStatus(accountId) (one-shot, seeds SyncStatusController right after login/account-switch - the account id is passed explicitly because SyncStatusBus only learns an account once a sync pass has run in this process, so on a fresh app start it'd report empty syncedFileIds; SyncStatusController._applySnapshot likewise ignores the bus's initial null-account emission so it can't wipe that seed) and SyncService.statusStream (live) both return the same snapshot shape. SyncStatusController.syncHeaderStatus (off/syncing/done/alert - drives SyncedHeaderScaffold's persistent chip/panel, replacing what used to be the WebDAV-refresh-loading indicator there) and syncStatusFor(item) (none/syncing/synced/conflict
  • drives the small corner badge on Files' tiles, SyncStatusBadge) are both computed from this state, not fetched per-item. Folders never get their own entry in the native state map (diffFolder only ever tracks individual files - if (entry.isFolder) continue), so syncStatusFor derives a folder's badge differently than a file's: synced once the folder's own path (or an ancestor of it) is in sync scope (_isPathInSyncScope, shared with localSyncedFilePath), syncing while any sync pass is running, conflict if a pending conflict's remotePath falls under it - not from syncedFileIds, which only ever contains individual files.
• In-app conflict resolution reuses the exact same enqueue path as the notification actions - ConflictResolveWorker.enqueue(...) is a shared companion function; SyncConflictReceiver (the notification action) and MainActivity.kt's resolveConflict MethodChannel method (the sync header's "Keep local"/"Use server" buttons, SyncStatusController.resolveSyncConflict) both just call it, so there's one resolution code path regardless of which surface triggered it.
• Conflicts are never auto-resolved. The notification's "Keep local"/ "Use server" actions are PendingIntent.getBroadcasts (same shape as the Cancel action on upload/download notifications, just broadcast instead of service-targeted) to SyncConflictReceiver
  • a manifest-registered BroadcastReceiver (works even with the app process dead) that can't itself block on network, so it just dismisses the notification and enqueues a one-shot ConflictResolveWorker to actually push the local copy up or pull the server copy down and refresh that file's recorded state.
• Keeping synced files current automatically - no "Sync now" needed. Synced paths follow the Files Cache rule (Settings, right under Device Sync; default Refresh periodically, 15 min), driven by SyncStatusController (see its doc comment): periodically = a WorkManager PeriodicWorkRequest at max(interval, 15) min (Android's floor) via reschedule(intervalMinutes:), plus an in-app Timer at the exact interval and a pass on app resume if one is due; never cache = no background job, a pass on each app open/resume; manual = only pull-to-refresh (SyncedHeaderScaffold calls syncOnPull, on any tab) and "Sync now". There's no server push: Nextcloud's push options (notify_push needs a server app plus a persistent WebSocket, which Android kills in the background without a foreground service; Nextcloud's FCM/UnifiedPush proxy needs a registered app identity) aren't viable for a self-hosted-server client, so it polls - and polling is made cheap by the root-etag shortcut: Nextcloud propagates any descendant change up through every ancestor folder's getetag, so each run first does one Depth-0 PROPFIND per synced root and skips the recursive walk if the etag matches the stored SyncEngine.RootMarker and every local file still matches its recorded size/mtime (localMatchesState - nothing to upload or re-download). A root is only marked after a fully clean pass (no failed transfer, no conflict), a full walk is forced at least every 6 h (FULL_WALK_MAX_AGE_MS; etag propagation is unreliable on external storage), and "Sync now" (KEY_FORCE) always walks. Automatic/pull passes are force: false: silent (progress notification only once a transfer starts), ExistingWorkPolicy.KEEP (never cancel a run in progress), and automatic ones also carry the Wi-Fi-only constraint. Safety: PROPFIND failures (network error, 5xx) throw RemoteUnavailableException and the path is skipped that run - previously they returned an empty listing, which made every synced file look deleted server-side and the diff deleted the local copies (a real risk once passes run every few minutes). Only a clean 404 means "gone".
• MainActivity.kt's dev.ayushya.noo/sync_service channel (reschedule/cancel/syncNow/removeLocalSync) is the only bridge from Dart: a periodic WorkRequest's input Data and Constraints are fixed at enqueue time, so changing the synced-folder list, the active account, or the Wi-Fi-only setting means cancelling and re-enqueueing, not updating in place. SyncService (Dart) wraps this - SyncStatusController calls SyncService.reschedule after every successful login/account switch and every synced-folder/ cache-rule/syncOnCellular change. reschedule covers every saved account, not just the active one: each account with sync enabled gets its own periodic job (SyncWorker.periodicNameFor(accountId)) carrying that account's own credentials (read from AccountStore), paths and interval - the active account's from live SyncStatusController state, the others' from their persisted per-account prefs (_SyncConfig.fromPrefs). Logging out stops that account's background sync: SessionController.logout records it in AccountStore's signed-out set (so a later reschedule for another account doesn't resurrect its job) and cancels it via SyncService.cancelAccount; activating the account again clears the flag. Removing an account cancels its job too. One-off runs are per-account (oneOffNameFor).
• Folders, not just files, are mirrored. After applying a path's diff, SyncWorker calls SyncEngine.mirrorFolders (a local directory for every remote folder, so an empty folder created on the web appears on device) and pruneRemovedFolders (removes local directories the server no longer has, but only empty ones - the diff has already deleted the files that were in them - and never the sync root). Root-etag markers carry a version (ROOTS_VERSION) so bumping it forces one full walk after a change like this. A configured path the server 404s (deleted on the web) is recorded via setRootMissing; the snapshot's missingRoots lets SyncStatusController._applySnapshot drop it from the synced list.
• Notifications. Sync notifications are silent (channel device_sync_v2, IMPORTANCE_LOW + setSilent), with ids and titles scoped per account (summaryNotificationId/conflictNotificationId) so accounts don't overwrite each other. "Background sync notifications" (Settings, global, default on) gates progress/summary for automatic runs (KEY_NOTIFY, baked into the periodic job input so it needs a reschedule); conflicts and user-initiated "Sync now" always notify. Manual download/upload notifications use file_downloads_v2/share_upload_v2 at default importance (progress silent, completion audible). Channel importance can't be changed once created, so changing it means a new channel id plus NooNotificationChannels.ensure(legacyIds = ...) deleting the old one.
• One sync at a time. SyncEngine.syncLock (a process-wide coroutine Mutex) wraps both SyncWorker and ConflictResolveWorker. WorkManager runs differently-named jobs concurrently, and both workers load the whole sync-state map, mutate it and save it back - so overlapping runs (periodic
  • a pull, two accounts due at once) silently discarded each other's updates, and SyncStatusBus only tracks one account at a time. A run that has to wait simply starts when the current one finishes. The network constraint is NetworkType.UNMETERED by default (!syncOnCellular, Wi-Fi only) or NetworkType.CONNECTED if the user's opted into cellular sync. Turning sync off for a path (SyncStatusController.removeSyncedPath) also calls SyncService.removeLocalSync, which runs SyncEngine.removeLocalSync on a background thread (deletes the local mirror files under that path and their entries in the native sync-state map - clearing state too, not just the files, matters because a bare "file's gone but the server hasn't changed" without a state reset reads as a user-initiated local deletion to diffFolder, so a later re-add wouldn't re-download anything).
• Synced-path list (SyncStatusController.syncedPaths - files or folders, not just folders despite the name of the underlying pref/native Data key, which stayed ui_synced_folders/folders to avoid a storage-key migration for a rename) follows the standard per-account-pref pattern (JSON-encoded string list, in AccountStore.perAccountPrefKeys); a parallel _syncedPathTypes map (path -> isFolder, ui_synced_folder_types) tracks which of those paths are folders vs individual files for the sync header's folder/item counts, defaulting missing entries to folder (the common case, and what any path added before this map existed will look like). addSyncedPaths/removeSyncedPaths gate on _accountLoadedGate (a Completer, deliberately starting incomplete - not pre-completed - completed once _onAccountActivated's async per-account prefs load actually finishes, re-armed on _onAccountCleared) before touching _syncedPaths at all - without this, syncing a folder soon enough after opening the app (or an account switch) could race that load: the mutator spreads the current in-memory _syncedPaths (still [], the pre-load default) and immediately persists the result, silently overwriting the previously-saved list and losing every other folder that had been synced before. Starting the gate pre-completed was an actual bug here - it meant only account switches (which call _onAccountCleared, re-arming it) were protected, leaving the very first cold-start load completely exposed to the race. A second, related guard, _hasLoadedSyncedPathsForAccount, stops _onAccountActivated from re-reading _syncedPaths from storage more than once per account - activation can fire again for the same account (e.g. SessionController re-verifying a provisional/offline login once connectivity returns), and a second read could clobber an in-memory mutation made between the first load and that one if its own persist hadn't landed yet. syncEverything (ui_sync_everything, per account) works the same way - when on, SyncService sends ['/'] as the path list instead of syncedPaths, mirroring the whole account rather than requiring per-item opt-in. syncOnCellular is a plain global pref. syncEverything and syncOnCellular are managed from Settings → Device Sync (a "Sync everything" switch, the cellular toggle, a manual "Sync now", and a "View offline files" row that pushes the Offline tab - see below); the configured path list itself, with its remove buttons, lives on the Offline tab now, not Settings. Individual files or folders are toggled from Files' selection toolbar ("Sync to device", works over the whole selection at once - either item type, folders or files - not just a single item; the action reads as "stop syncing" only once every selected item is already synced, otherwise it syncs whichever ones aren't yet, and either direction ends with a confirmation SnackBar). Multi-item add/remove goes through SyncStatusController.addSyncedPaths/ removeSyncedPaths (batched), never a per-item loop of addSyncedPath/removeSyncedPath - looping was an actual bug: each addSyncedPath call fires its own SyncService.syncNow, and syncNow's native side enqueues via WorkManager.enqueueUniqueWork(..., ExistingWorkPolicy.REPLACE, ...), so a second item's call cancelled the first item's still-in-flight sync pass instead of letting it finish - only ever syncing the last item enqueued. The batched methods mutate _syncedPaths for the whole set and call reschedule/syncNow exactly once, with the complete folder list, so SyncWorker handles every item in one run (it already loops its whole folders list sequentially within a single doWork() call - see above).
• The Offline tab (FilesView(offline: true) over OfflineController, see architecture.md's FolderBrowser) is the Files tab itself - same breadcrumbs, controls, tiles and thumbnails - over whatever device-sync has actually landed on disk - deliberately no selection/multi-select toolbar, since delete/share/move don't make sense for an already-synced local mirror. Reads straight off <externalFilesDir>/sync/<accountId>/<currentFolder> (non-recursive Directory.list() per folder) via dart:io, not fetched from the server (mirrors SyncEngine.kt#syncRoot's layout exactly), so it works with no connection and never round-trips through a MethodChannel just to list files. OfflineController refetches the current folder automatically whenever a SyncService.statusStream snapshot shows syncing just stopped, so newly-downloaded files show up without a manual pull-to-refresh. Tapping an item opens FileViewerScreen with localPath set (see below) - same in-app viewer Files uses, just reading from disk instead of the server; tapping a folder navigates into it, same as Files. Resolves the local path via OfflineController.localPathFor(item), a pure function of the item's path - deliberately not SyncStatusController.localSyncedFilePath, which additionally re-verifies the item falls under a configured sync target (_isPathInSyncScope). That check is redundant and was actually a bug here: every item this controller ever hands out already came from listing this exact directory tree, so it's definitionally already local, and re-deriving "is this still in scope" from syncedPaths could disagree with what's genuinely sitting on disk (e.g. nested paths, timing right after a scope change) and report a visibly-listed file as "no longer available". Pull-to-refresh triggers SyncService.syncNow followed by a re-list. The configured sync targets themselves (with "stop syncing" per target, what used to be Settings' Device Sync card's own inline list) live in a bottom sheet behind the app bar's sync icon (_ManageSyncedFoldersSheet) rather than inline in the main view, so the browser itself stays a plain Files-style listing; Settings' own "View offline files" row just pushes this whole tab.
• android/app/proguard-rules.pro exists specifically for this feature, and keeps androidx.work.** wholesale rather than naming individual classes. Flutter's own Gradle plugin auto-enables R8 minification for release builds (FlutterPlugin.kt sets isMinifyEnabled = true unconditionally for the release build type, and auto-wires this exact file if it exists - nothing in this project's own build.gradle.kts opts into it), which broke device sync on real-device testing twice in a row: first WorkDatabase (WorkManager locates its bundled Room database by reflecting off the abstract database class's own, possibly-renamed, name), then - after narrowly keeping just that class - OverwritingInputMerger (WorkManager's default input merger, also reflection-instantiated) broke the exact same way and silently ate every enqueueUniqueWork call, including "Sync now", with zero indication beyond a WM-InputMerger NoSuchMethodException in logcat - no crash, no Dart-visible error, just a folder that stayed empty. R8's member-level shrinking strips whatever a class's reflection-only callers don't reference directly, even when the class itself survives a plain -keep class with no wildcard, and WorkManager reflects into more of its own internals than any one test pass is likely to exercise - hence the wholesale keep instead of chasing individual classes one crash at a time. If adding another native background component reached only via reflection (not a manifest-declared component, which AGP already keeps automatically), don't assume default AndroidX consumer rules cover it - verify on an actual release build, not just flutter analyze/a debug build, since minification only applies to release.
• Files land under Android/data/<package>/files/sync/... (getExternalFilesDir), which no third-party file manager can browse without root - Android's scoped storage sandboxes that whole directory tree from other apps by design, same as any app-private storage. This surprised real-device testing (a file manager app logged "Can't read directory ... trying su" and came up empty even though the sync had actually worked) - it's expected, not a bug. Confirm synced files landed via adb shell run-as/a rooted shell, not a regular file manager UI.
• Already-synced files skip the network in two places: SyncStatusController.localSyncedFilePath(item) is a pure function of the remote path (mirrors SyncEngine.kt's syncRoot layout exactly, so Dart never needs to read the native sync-state SharedPreferences) that returns the local mirror path if it exists on disk. ShareSheet's "Share file directly" and FilesView._downloadSelected (only when every selected file is already synced - a mixed selection still goes through the normal DownloadService batch) both check it first.

Working offline

ConnectivityController wraps connectivity_plus (OS-level route detection - Wi-Fi/mobile/none, not a guarantee the Nextcloud server itself is reachable) and is the single source of truth every offline-aware decision in the app consults. Its very first checkConnectivity() call is re-verified once more, ~2 seconds later - that first check can spuriously report "no network" while Android's connectivity stack is still attaching callbacks to a just-started process (a real cold-start quirk, not a genuine transition), and since onConnectivityChanged only fires on actual transitions, a false initial "offline" read would otherwise stick for the rest of the session with no further event ever correcting it - SessionController would keep treating the login as provisional indefinitely, and every network-fetching controller (Files/Photos/Favorites/Trash/Shares/Recent) would simply never receive its real activation signal, leaving every tab permanently empty despite the device being online the whole time. This was a real, previously-shipped regression, not a hypothetical.

• Session restore never makes a doomed HTTP request. SessionController._applyCredentialsForAccount checks connectivity.isOffline before calling NextcloudService.testConnection()
  • if there's no route at all, it skips the request entirely rather than letting it fail (fast or slow) and parsing the exception. Either way (no route, or a network-level exception once a request is attempted - timeout, DNS, unreachable host, a transient 5xx), the session logs in provisionally: _isLoggedIn = true with the already-constructed _service kept around, _isProvisionalLogin = true. Only an actual 401 (_errorMessage contains "401") is treated as a real rejection - drops the stored password and logs out for real. Provisional login exists specifically so a genuinely offline cold start still lands on MainShellView (restricted to the Offline tab - see below) instead of bouncing to LoginView, which would strand the user with no way back in short of Login Flow v2 again (switchAccount no-ops when "switching" to the account that's already nominally active, and activeAccountId is never cleared by a network failure).
• Two account-activation signals, not one, precisely so a provisional login doesn't cascade into a pile of doomed requests from every other controller: addAccountActivatedListener (fires only on a real, verified login - what FilesController/PhotosController/ FavoritesController/TrashController/SharesController/ RecentController all register for, since their own activation work is a network fetch) vs. addAccountReadyListener (fires on either a verified or a provisional login - what SyncStatusController/ OfflineController register for instead, since their own activation work - loading prefs, listing local files, calling the native sync MethodChannel - is local/native-only and safe with no connection at all). A provisional login fires only ready, never activated; a verified login fires both.
• Reconnecting re-verifies automatically. SessionController listens to connectivity itself; the moment it flips from offline to online while _isProvisionalLogin is still true, it re-runs _applyCredentialsForAccount with the same cached account/password. On success this is what finally fires _notifyAccountActivated for real, so Files/Photos/etc. get their first actual fetch without the user having to force-quit/restart the app.
• MainShellView collapses the bottom nav to just the Offline tab while connectivity.isOffline, the same override mechanism already used for picking mode (see architecture.md) - every other tab would just show its own loading spinner or error state with no connection, so there's nothing useful to switch to. MoreTabsButton hides entirely in this state too, for the same reason it hides while picking - there's no hidden tab it could usefully open either.
• The sync header's "Offline" label wins over everything else. _syncHeaderDisplay/_syncSummary (synced_header_scaffold.dart) both take a bool isOffline and check it first, ahead of conflicts/syncing/ configured-targets - with no connection, why nothing's syncing right now matters more than what would otherwise be shown, so "Sync off" (nothing configured) and "Offline" (nothing can sync right now, regardless of configuration) stay distinct messages.
• FileViewerScreen can read a file straight from disk. Its optional localPathResolver param (Future<String?> Function(NextcloudItem), only ever set by the Offline tab, passing OfflineController. localPathFor) swaps every preview widget's data source - _ImagePreview/_VideoPreview use Image.file/ VideoPlayerController.file instead of the .network/.networkUrl variants, _PdfPreview/_TextPreview read via File(path).readAsBytes() instead of NextcloudService.fetchBytes - same in-app viewer either way, no separate "offline preview" screen. Unlike a single up-front path, a resolver is what makes siblings (swipe-between-media) behave identically to Files/Photos while offline: the swipeable PageView.builder calls it again for whichever sibling you've swiped to (wrapped in a FutureBuilder, since each resolution is an async disk check), not just the item the viewer opened on - the Offline tab passes its whole current folder's items as siblings, same as Files does with its own. The action bar hides Favorite/Delete/ Download-to-device (showServerActions: false) since those need a live server - Share and Open-externally still work (_openExternally calls the resolver directly instead of downloading to a temp file first; Share already prefers a local copy when one exists, see ShareSheet._shareFileDirectly).

Multi-account storage & session persistence

AccountStore owns everything account-identity-related; SessionController owns everything about which account is currently live (see architecture.md).

• Per-account secrets: one flutter_secure_storage key per account, nc_app_password_<accountId> — never shared_preferences. accountId is deterministic (SavedAccount.makeId(serverUrl, username), a slug of both), so re-adding the same account refreshes its password instead of creating a duplicate.
• Account identity list (non-secret: id/serverUrl/username) and which one is active live in shared_preferences as accounts_list (JSON array) and active_account_id.
• Global UI prefs (theme, dynamic color, AMOLED, bottom-bar opacity/blur, tap-to-scroll-top, seek bar style, tab order/hidden/default, swipe actions) stay flat, un-namespaced shared_preferences keys — same as before multi-account, untouched by switching.
• Per-account browsing prefs (grid/list view, favorites-only ×2, storage scope, show-hidden ×2, Photos sort field/ascending, Files' per-folder sort map, cache policy/interval — the full list is AccountStore.perAccountPrefKeys) are namespaced acct_<accountId>_<key> and owned by whichever controller that domain belongs to (e.g. FilesController for grid/list/storage-scope/sort, PhotosController for Photos' own sort/filter). Each reloads its own slice in its _onAccountActivated listener, registered via SessionController.addAccountActivatedListener in its constructor - there's no longer one central method that reloads every domain's prefs at once; SessionController just fires the notification, and every sibling controller reacts independently.
• Legacy migration: AccountStore.migrateLegacyIfNeeded runs once ever (guarded by the account_migration_v1_done flag), turning a pre-multi- account install's 3 flat secure-storage keys + flat browsing prefs into the first saved (and active) account, so upgrading users are never logged out. Never assume the legacy keys are gone — always check the migration flag rather than the keys' absence.
• On startup, SessionController's constructor awaits the migration, loads the account list + active id, then _restoreSession() looks up the active account's password and calls _applyCredentialsForAccount (generation-guarded, account-aware) to rebuild the session without re-hitting the login flow - firing _notifyAccountActivated() on success, which is what triggers every sibling controller's own initial fetch.
• Switching accounts (switchAccount/cycleToNextAccount/ cycleToPreviousAccount/removeAccount's fallback, plus landing on a freshly-added account) all funnel through the single _activateAccount engine: bump sessionGeneration, cancel any pending login flow, call _notifyAccountCleared() (every sibling controller's registered addAccountClearedListener callback resets that controller's own state) without ever setting isLoggedIn false (that's the detail that keeps main.dart's root routing from bouncing through LoginView mid-switch), then verify its credentials and refetch everything. This is a full teardown-and-reload every time — there is deliberately no simultaneous multi-account state or background sync; only one account's content is ever live.
• logout() vs removeAccount() are deliberately different actions, both funneling into a shared _deactivateSession() helper for the teardown/pointer-clearing part:
  • logout() ends the active session but keeps the account itself fully intact (password, prefs, its entry in accounts all untouched) — always lands on LoginView even if other accounts are saved (it does not fall back to one of them the way removeAccount does). This exists so LoginView can offer a "Continue as ..." one-tap resume list (_SavedAccountsSection in login_view.dart) with no Login Flow v2 needed - logging out must never be mistaken for forgetting an account.
  • removeAccount(id) deletes everything for that account (secure-storage password, namespaced prefs, its accounts entry) and, only if it was the active one, falls back to another saved account or - if none remain - calls the same _deactivateSession(). This is the only path (besides logout()) that can set isLoggedIn false, and the only one that's actually destructive/irreversible - UI call sites (AccountView) gate it behind a confirmation dialog; logout() doesn't need one.
  • Any UI code that calls either and might have ended the session should check !session.isLoggedIn afterward and Navigator.popUntil((r) => r.isFirst) if so — otherwise a screen pushed on top (Settings) is left stranded over a root route that's silently swapped to LoginView underneath it. Don't pop unconditionally — removing a non-active account, or one that fell back to another, keeps the user logged in and Settings should just stay open.

App lock (login lock)

An orthogonal, app-wide security layer on top of the Nextcloud login/session above — not account credentials, just a gate on using the app. AppLockService wraps local_auth; this app never implements its own PIN entry/storage/hashing — authenticate() always delegates to whatever the OS already has configured (biometric, or device PIN/pattern/password as fallback, via biometricOnly: false). Never build a custom in-app PIN screen for this — extend AppLockService/the SessionController gates described in architecture.md instead.

Android native requirements (both already done, keep them if you touch these files): MainActivity.kt must extend FlutterFragmentActivity, not the default FlutterActivity — local_auth's Android implementation hosts its prompt via a Fragment and silently fails to build/crashes without it. AndroidManifest.xml needs <uses-permission android:name="android.permission.USE_BIOMETRIC"/> (also declared by the plugin's own manifest via merge, but kept explicit here too). android/app/build.gradle.kts floors minSdk at 24 (local_auth_android's own requirement) via maxOf(24, flutter.minSdkVersion) rather than trusting Flutter's own default to already be high enough.

isRestoringSession still gates the splash screen until the above resolves — see standards.md for why widget tests must mock both storage channels rather than relying on this async path throwing naturally.

• putBytes(path, bytes) does a WebDAV PUT to overwrite a file; used by the text/markdown editor (MediaTextPreview).

Changing a share's permissions

NextcloudService.updateSharePermissions does PUT /ocs/v2.php/apps/files_sharing/api/v1/shares/{id} with a permissions bitmask (1 read, 2 update, 4 create, 8 delete, 16 reshare). The share sheet's per-person pill opens a menu with Can view (1) / Can edit (3 for files, 15 for folders), keeping the existing reshare bit, plus Remove access.