feat: standardize error handling

doc/errors.md

···
+# Error Handling Patterns
+
+This project standardizes error handling so UI messages stay user-friendly and
+network failures are predictable.
+
+## Standard Error Types
+
+- `NetworkFailure` (in `lib/src/infrastructure/network/network_failure.dart`)
+    - `ConnectionFailure`, `AuthFailure`, `RateLimitFailure`, `ClientFailure`,
+    `ServerFailure`, `DecodeFailure`
+- `OAuthException` (in `lib/src/infrastructure/auth/oauth_exceptions.dart`)
+- `ValidationError` (in `lib/src/features/dms/domain/outbox_error.dart`)
+
+## UI Messaging
+
+Use `errorMessage(error)` from `lib/src/core/utils/error_message.dart` instead of
+`error.toString()` to avoid leaking raw exception text into the UI.
+
+Example:
+
+```dart
+ErrorView(
+  title: 'Failed to load feed',
+  message: errorMessage(error),
+  onRetry: () => ref.read(feedContentProvider(uri).notifier).refresh(),
+);
+```
+
+## Logging vs Display
+
+- Log raw errors and stacks for debugging (`logger.error(...)`).
+- Display standardized UI messages via `errorMessage(...)`.
+- Prefer typed errors (e.g., `NetworkFailure`) at repository boundaries.
+
+## Tests
+
+Add or update tests whenever new error types are introduced or UI messaging
+changes, especially for networking/auth flows.

doc/roadmap.txt

···
 - [ ] Type safety improvements:
       - Use freezed for critical models
       - Add typed JSON parsing where appropriate
-- [ ] Error handling standardization:
+- [x] Error handling standardization:
       - Define standard error types for common failures (network, auth,
         validation)
       - Standardize error display messages (no raw .toString() in UI)

lib/src/core/utils/error_message.dart

···
+import 'package:lazurite/src/features/dms/domain/outbox_error.dart';
+import 'package:lazurite/src/infrastructure/auth/oauth_exceptions.dart';
+import 'package:lazurite/src/infrastructure/network/network_failure.dart';
+
+/// Returns a user-friendly error message for UI display.
+String errorMessage(Object? error, {String fallback = 'Something went wrong. Please try again.'}) {
+  if (error == null) return fallback;
+
+  if (error is NetworkFailure) {
+    return switch (error) {
+      ConnectionFailure() => 'Network error. Check your connection and try again.',
+      AuthFailure(:final requiresReauth) =>
+        requiresReauth
+            ? 'Session expired. Please sign in again.'
+            : 'Authentication failed. Please try again.',
+      RateLimitFailure(:final retryAfter) =>
+        retryAfter != null
+            ? 'Too many requests. Try again in ${retryAfter.inSeconds}s.'
+            : 'Too many requests. Try again later.',
+      ServerFailure() => 'Server error. Please try again later.',
+      ClientFailure(:final statusCode) =>
+        statusCode == 404
+            ? 'Not found. The item may have been deleted.'
+            : 'Request failed. Please try again.',
+      DecodeFailure() => 'We received an unexpected response. Please try again.',
+    };
+  }
+
+  if (error is OAuthException) {
+    return error.errorDescription ?? 'Authorization failed. Please try again.';
+  }
+
+  if (error is ValidationError) {
+    return error.message ?? 'Invalid input. Please update and retry.';
+  }
+
+  if (error is FormatException) {
+    return error.message.isNotEmpty ? error.message : fallback;
+  }
+
+  if (error is StateError) {
+    final message = error.message;
+    if (message.contains('authenticated')) {
+      return 'Please sign in to continue.';
+    }
+  }
+
+  return fallback;
+}

lib/src/features/composer/application/composer_notifier.dart

···
 import 'dart:async';
 
 import 'package:equatable/equatable.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/composer/domain/draft.dart';
 import 'package:lazurite/src/features/composer/infrastructure/draft_repository.dart';
 import 'package:lazurite/src/features/profile/application/profile_providers.dart';
···
     } catch (e) {
       final updatedState = state.asData?.value;
       if (updatedState != null) {
-        state = AsyncValue.data(updatedState.copyWith(isPublishing: false, error: e.toString()));
+        state = AsyncValue.data(
+          updatedState.copyWith(isPublishing: false, error: errorMessage(e)),
+        );
       }
       return null;
     }

lib/src/features/composer/infrastructure/draft_repository.dart

···
 
 import 'package:dio/dio.dart';
 import 'package:drift/drift.dart' show Value;
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/utils/image_compressor.dart';
 import 'package:lazurite/src/core/utils/logger.dart';
 import 'package:lazurite/src/features/composer/domain/draft.dart' as composer;
···
         ownerDid,
         DraftsCompanion(
           status: Value(composer.DraftStatus.failed.name),
-          errorMessage: Value(e.toString()),
+          errorMessage: Value(errorMessage(e)),
           updatedAt: Value(DateTime.now()),
         ),
       );

lib/src/features/composer/presentation/screens/composer_screen.dart

···
 import 'package:go_router/go_router.dart';
 import 'package:image_picker/image_picker.dart';
 import 'package:lazurite/src/core/domain/post.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/composer/application/composer_notifier.dart';
 import 'package:lazurite/src/features/composer/application/composer_providers.dart';
 import 'package:lazurite/src/features/composer/presentation/widgets/alt_text_editor_sheet.dart';
···
               Text('Failed to load composer', style: theme.textTheme.bodyLarge),
               const SizedBox(height: 8),
               Text(
-                error.toString(),
+                errorMessage(error),
                 style: theme.textTheme.bodySmall?.copyWith(color: colorScheme.onSurfaceVariant),
                 textAlign: TextAlign.center,
               ),

lib/src/features/developer_tools/presentation/screens/collections_page.dart

···
 import 'package:go_router/go_router.dart';
 import 'package:lazurite/src/app/providers.dart';
 import 'package:lazurite/src/app/routes.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/developer_tools/application/devtools_providers.dart';
 import 'package:lazurite/src/features/developer_tools/domain/repo_collection.dart';
 
···
                       Text('Failed to load collections', style: theme.textTheme.titleMedium),
                       const SizedBox(height: 8),
                       Text(
-                        error.toString(),
+                        errorMessage(error),
                         textAlign: TextAlign.center,
                         style: theme.textTheme.bodySmall?.copyWith(
                           color: theme.colorScheme.onSurfaceVariant,

lib/src/features/developer_tools/presentation/screens/record_detail_page.dart

···
 import 'package:flutter_json/flutter_json.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/developer_tools/application/devtools_providers.dart';
 import 'package:lazurite/src/features/developer_tools/domain/repo_record.dart';
 
···
                 Text('Failed to load record', style: theme.textTheme.titleMedium),
                 const SizedBox(height: 8),
                 Text(
-                  error.toString(),
+                  errorMessage(error),
                   textAlign: TextAlign.center,
                   style: theme.textTheme.bodySmall?.copyWith(
                     color: theme.colorScheme.onSurfaceVariant,

lib/src/features/developer_tools/presentation/screens/records_page.dart

···
 import 'package:go_router/go_router.dart';
 import 'package:lazurite/src/app/routes.dart';
 import 'package:lazurite/src/app/providers.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/developer_tools/application/devtools_providers.dart';
 import 'package:lazurite/src/features/developer_tools/domain/repo_record.dart';
 
···
                     Text('Failed to load records', style: theme.textTheme.titleMedium),
                     const SizedBox(height: 8),
                     Text(
-                      state.error.toString(),
+                      errorMessage(state.error),
                       textAlign: TextAlign.center,
                       style: theme.textTheme.bodySmall?.copyWith(
                         color: theme.colorScheme.onSurfaceVariant,
···
                 Text('Failed to load records', style: theme.textTheme.titleMedium),
                 const SizedBox(height: 8),
                 Text(
-                  error.toString(),
+                  errorMessage(error),
                   textAlign: TextAlign.center,
                   style: theme.textTheme.bodySmall?.copyWith(
                     color: theme.colorScheme.onSurfaceVariant,

lib/src/features/dms/presentation/conversation_detail_screen.dart

···
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../../../core/animations/animation_utils.dart';
+import '../../../core/utils/error_message.dart';
 import '../../../core/widgets/error_view.dart';
 import '../../../core/widgets/loading_view.dart';
 import '../../../core/widgets/pull_to_refresh_wrapper.dart';
···
                 loading: () => const LoadingView(),
                 error: (error, stack) => ErrorView(
                   title: 'Failed to load messages',
-                  message: error.toString(),
+                  message: errorMessage(error),
                   onRetry: () =>
                       ref.read(conversationDetailProvider(widget.convoId).notifier).refresh(),
                 ),

lib/src/features/dms/presentation/conversation_list_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/dms/presentation/widgets/message_request_card.dart';
 
 import '../../../core/animations/animation_utils.dart';
···
           loading: () => const LoadingView(),
           error: (error, stack) => ErrorView(
             title: 'Failed to load messages',
-            message: error.toString(),
+            message: errorMessage(error),
             onRetry: () => ref.read(conversationListProvider.notifier).refresh(),
           ),
         ),

lib/src/features/feeds/application/feed_providers.dart

···
 import 'dart:async';
 
 import 'package:lazurite/src/app/providers.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/utils/logger_provider.dart';
 import 'package:lazurite/src/features/auth/application/auth_providers.dart';
 import 'package:lazurite/src/features/auth/domain/auth_state.dart';
···
       );
       state = state.copyWith(results: results, isLoading: false);
     } catch (e) {
-      state = state.copyWith(isLoading: false, error: e.toString());
+      state = state.copyWith(isLoading: false, error: errorMessage(e));
     }
   }
 

lib/src/features/feeds/infrastructure/feed_repository.dart

···
 import 'package:lazurite/src/infrastructure/db/daos/profile_dao.dart';
 import 'package:lazurite/src/infrastructure/db/daos/saved_feeds_dao.dart';
 import 'package:lazurite/src/infrastructure/network/xrpc_client.dart';
+import 'package:uuid/uuid.dart';
 
 /// Duration after which permanently failed sync items are cleaned up.
 const Duration kSyncQueueCleanupAge = Duration(days: 30);
···
 /// from app.bsky.feed.getFeedGenerator.
 class FeedRepository {
   FeedRepository(this._api, this._dao, this._syncQueueDao, this._profileDao, this._logger);
+
+  static const _uuid = Uuid();
 
   final XrpcClient _api;
   final SavedFeedsDao _dao;
···
     if (!_api.isAuthenticated) throw Exception('User not authenticated');
     _validateFeedUri(feedUri);
 
+    final existing = await _dao.getFeed(feedUri, ownerDid);
     FeedGenerator? metadata;
     String displayName = 'Saved Feed';
     String? description;
···
     }
 
     final allFeeds = await _dao.getAllFeeds(ownerDid);
+    final sortOrder = existing?.sortOrder ?? allFeeds.length;
+    final lastSynced = existing?.lastSynced ?? DateTime.now();
     int? queueId;
 
     try {
···
             avatar: Value(avatar),
             creatorDid: creatorDid,
             likeCount: Value(likeCount ?? 0),
-            sortOrder: allFeeds.length,
+            sortOrder: sortOrder,
             isPinned: Value(pin),
-            lastSynced: DateTime.now(),
+            lastSynced: lastSynced,
             localUpdatedAt: Value(DateTime.now()),
           ),
         );
···
     try {
       await _executeRemoteSaveFeed(feedUri, pin);
       if (queueId != null) await _syncQueueDao.deleteItem(queueId);
+      await _clearLocalModifications([feedUri], ownerDid);
     } catch (e) {
       _logger.error('Failed to save feed', {'error': e});
     }
   }
 
   Future<void> _executeRemoteSaveFeed(String feedUri, bool pin) async {
-    final currentPrefsResponse = await _api.call('app.bsky.actor.getPreferences');
-    final prefs = List<Map<String, dynamic>>.from(
-      (currentPrefsResponse['preferences'] as List).map(
-        (p) => Map<String, dynamic>.from(p as Map),
-      ),
-    );
+    final snapshot = await _loadSavedFeedsPreferences();
 
-    var savedFeedsPref = prefs.cast<Map<String, dynamic>>().firstWhere(
-      (p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref',
-      orElse: () => <String, dynamic>{},
-    );
-
-    if (savedFeedsPref.isEmpty) {
-      savedFeedsPref = {
-        '\$type': 'app.bsky.actor.defs#savedFeedsPref',
-        'saved': <String>[],
-        'pinned': <String>[],
-      };
-      prefs.add(savedFeedsPref);
+    if (snapshot.v2 != null) {
+      final updatedItems = _upsertV2Item(snapshot.v2!.items, feedUri, pin);
+      _updatePreferences(
+        snapshot,
+        v2: SavedFeedsPrefV2(items: updatedItems),
+        v1: snapshot.v1,
+      );
     } else {
-      savedFeedsPref = Map<String, dynamic>.from(savedFeedsPref);
-      final index = prefs.indexWhere((p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref');
-      prefs[index] = savedFeedsPref;
-    }
+      final existingSaved = snapshot.v1?.saved ?? [];
+      final existingPinned = snapshot.v1?.pinned ?? [];
+      final saved = List<String>.from(existingSaved);
+      final pinned = List<String>.from(existingPinned);
 
-    final saved = List<String>.from(savedFeedsPref['saved'] ?? []);
-    final pinned = List<String>.from(savedFeedsPref['pinned'] ?? []);
+      if (!saved.contains(feedUri)) {
+        saved.add(feedUri);
+      }
 
-    if (!saved.contains(feedUri)) {
-      saved.add(feedUri);
-    }
+      if (pin) {
+        if (!pinned.contains(feedUri)) {
+          pinned.add(feedUri);
+        }
+      } else {
+        pinned.remove(feedUri);
+      }
 
-    if (pin && !pinned.contains(feedUri)) {
-      pinned.add(feedUri);
+      _updatePreferences(
+        snapshot,
+        v1: SavedFeedsPref(saved: saved, pinned: pinned),
+      );
     }
 
-    savedFeedsPref['saved'] = saved;
-    savedFeedsPref['pinned'] = pinned;
-
-    await _api.call('app.bsky.actor.putPreferences', body: {'preferences': prefs});
+    await _api.call('app.bsky.actor.putPreferences', body: {'preferences': snapshot.preferences});
   }
 
   /// Removes a feed from user preferences and local cache.
···
   }
 
   Future<void> _executeRemoteRemoveFeed(String feedUri) async {
-    final currentPrefsResponse = await _api.call('app.bsky.actor.getPreferences');
-    final prefs = List<Map<String, dynamic>>.from(
-      (currentPrefsResponse['preferences'] as List).map(
-        (p) => Map<String, dynamic>.from(p as Map),
-      ),
-    );
+    final snapshot = await _loadSavedFeedsPreferences();
 
-    var savedFeedsPref = prefs.cast<Map<String, dynamic>>().firstWhere(
-      (p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref',
-      orElse: () => <String, dynamic>{},
-    );
-
-    if (savedFeedsPref.isNotEmpty) {
-      savedFeedsPref = Map<String, dynamic>.from(savedFeedsPref);
-      final index = prefs.indexWhere((p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref');
-      prefs[index] = savedFeedsPref;
-
-      final saved = List<String>.from(savedFeedsPref['saved'] ?? []);
-      final pinned = List<String>.from(savedFeedsPref['pinned'] ?? []);
-
-      saved.remove(feedUri);
-      pinned.remove(feedUri);
-
-      savedFeedsPref['saved'] = saved;
-      savedFeedsPref['pinned'] = pinned;
-
-      await _api.call('app.bsky.actor.putPreferences', body: {'preferences': prefs});
+    if (snapshot.v2 != null) {
+      final updatedItems = snapshot.v2!.items.where((item) => item.value != feedUri).toList();
+      _updatePreferences(
+        snapshot,
+        v2: SavedFeedsPrefV2(items: updatedItems),
+        v1: snapshot.v1,
+      );
+    } else if (snapshot.v1 != null) {
+      final saved = List<String>.from(snapshot.v1!.saved)..remove(feedUri);
+      final pinned = List<String>.from(snapshot.v1!.pinned)..remove(feedUri);
+      _updatePreferences(
+        snapshot,
+        v1: SavedFeedsPref(saved: saved, pinned: pinned),
+      );
+    } else {
+      return;
     }
+
+    await _api.call('app.bsky.actor.putPreferences', body: {'preferences': snapshot.preferences});
   }
 
   /// Reorders feeds according to the provided URI list.
···
     try {
       await _executeRemoteReorderFeeds(orderedUris);
       if (queueId != null) await _syncQueueDao.deleteItem(queueId);
+      await _clearLocalModifications(orderedUris, ownerDid);
     } catch (e) {
       _logger.error('Failed to reorder feeds', {'error': e});
     }
   }
 
   Future<void> _executeRemoteReorderFeeds(List<String> orderedUris) async {
-    final currentPrefsResponse = await _api.call('app.bsky.actor.getPreferences');
-    final prefs = List<Map<String, dynamic>>.from(
-      (currentPrefsResponse['preferences'] as List).map(
-        (p) => Map<String, dynamic>.from(p as Map),
-      ),
-    );
+    final snapshot = await _loadSavedFeedsPreferences();
 
-    var savedFeedsPref = prefs.cast<Map<String, dynamic>>().firstWhere(
-      (p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref',
-      orElse: () => <String, dynamic>{},
-    );
+    if (snapshot.v2 != null) {
+      final updatedItems = _reorderV2Items(snapshot.v2!.items, orderedUris);
+      _updatePreferences(
+        snapshot,
+        v2: SavedFeedsPrefV2(items: updatedItems),
+        v1: snapshot.v1,
+      );
+    } else if (snapshot.v1 != null) {
+      final currentSaved = List<String>.from(snapshot.v1!.saved);
+      final currentPinned = List<String>.from(snapshot.v1!.pinned);
+      final reorderedSaved = <String>[];
+      final reorderedPinned = <String>[];
 
-    if (savedFeedsPref.isEmpty) {
-      return;
-    }
+      for (final uri in orderedUris) {
+        if (currentSaved.contains(uri)) {
+          reorderedSaved.add(uri);
+          if (currentPinned.contains(uri)) {
+            reorderedPinned.add(uri);
+          }
+        }
+      }
 
-    savedFeedsPref = Map<String, dynamic>.from(savedFeedsPref);
-    final index = prefs.indexWhere((p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref');
-    prefs[index] = savedFeedsPref;
-
-    final currentSaved = List<String>.from(savedFeedsPref['saved'] ?? []);
-    final currentPinned = List<String>.from(savedFeedsPref['pinned'] ?? []);
-
-    final reorderedSaved = <String>[];
-    final reorderedPinned = <String>[];
-
-    for (final uri in orderedUris) {
-      if (currentSaved.contains(uri)) {
-        reorderedSaved.add(uri);
-        if (currentPinned.contains(uri)) {
-          reorderedPinned.add(uri);
+      for (final uri in currentSaved) {
+        if (!reorderedSaved.contains(uri)) {
+          reorderedSaved.add(uri);
         }
       }
-    }
 
-    for (final uri in currentSaved) {
-      if (!reorderedSaved.contains(uri)) {
-        reorderedSaved.add(uri);
-      }
+      _updatePreferences(
+        snapshot,
+        v1: SavedFeedsPref(saved: reorderedSaved, pinned: reorderedPinned),
+      );
+    } else {
+      return;
     }
 
-    savedFeedsPref['saved'] = reorderedSaved;
-    savedFeedsPref['pinned'] = reorderedPinned;
-
-    await _api.call('app.bsky.actor.putPreferences', body: {'preferences': prefs});
+    await _api.call('app.bsky.actor.putPreferences', body: {'preferences': snapshot.preferences});
   }
 
   /// Discovers trending feed generators or searches for them if a query is provided.
···
         }
 
         await _syncQueueDao.deleteItem(item.id);
+        if (item.type == 'save') {
+          await _clearLocalModifications([item.payload], ownerDid);
+        } else if (item.type == 'reorder') {
+          await _clearLocalModifications(item.payload.split(','), ownerDid);
+        }
       } catch (e) {
         _logger.error('Failed to process sync item ${item.id}', {
           'error': e,
···
     });
     return results;
   }
+
+  Future<_SavedFeedsPreferencesSnapshot> _loadSavedFeedsPreferences() async {
+    final currentPrefsResponse = await _api.call('app.bsky.actor.getPreferences');
+    final prefsRaw = currentPrefsResponse['preferences'];
+    if (prefsRaw is! List) {
+      throw FormatException('preferences must be a List', currentPrefsResponse);
+    }
+
+    final preferences = prefsRaw
+        .map((p) => Map<String, dynamic>.from(p as Map))
+        .toList(growable: true);
+
+    final parsed = SavedFeedsPreferenceParser.parse(preferences);
+    final v2Index = preferences.indexWhere(
+      (p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPrefV2',
+    );
+    final v1Index = preferences.indexWhere(
+      (p) => p['\$type'] == 'app.bsky.actor.defs#savedFeedsPref',
+    );
+
+    return _SavedFeedsPreferencesSnapshot(
+      preferences: preferences,
+      v2: parsed.v2,
+      v1: parsed.v1,
+      v2Index: v2Index >= 0 ? v2Index : null,
+      v1Index: v1Index >= 0 ? v1Index : null,
+    );
+  }
+
+  void _updatePreferences(
+    _SavedFeedsPreferencesSnapshot snapshot, {
+    SavedFeedsPrefV2? v2,
+    SavedFeedsPref? v1,
+  }) {
+    if (v2 != null) {
+      final json = v2.toJson();
+      if (snapshot.v2Index != null) {
+        snapshot.preferences[snapshot.v2Index!] = json;
+      } else {
+        snapshot.preferences.add(json);
+      }
+
+      if (snapshot.v1Index != null) {
+        final v1FromV2 = SavedFeedsPref(saved: v2.savedUris, pinned: v2.pinnedUris);
+        snapshot.preferences[snapshot.v1Index!] = v1FromV2.toJson();
+      }
+    } else if (v1 != null) {
+      final json = v1.toJson();
+      if (snapshot.v1Index != null) {
+        snapshot.preferences[snapshot.v1Index!] = json;
+      } else {
+        snapshot.preferences.add(json);
+      }
+    }
+  }
+
+  List<SavedFeedItem> _upsertV2Item(List<SavedFeedItem> items, String feedUri, bool pinned) {
+    final updated = List<SavedFeedItem>.from(items);
+    final index = updated.indexWhere((item) => item.value == feedUri);
+    if (index >= 0) {
+      final existing = updated[index];
+      updated[index] = SavedFeedItem(value: feedUri, pinned: pinned, id: existing.id);
+    } else {
+      updated.add(SavedFeedItem(value: feedUri, pinned: pinned, id: _uuid.v4()));
+    }
+    return updated;
+  }
+
+  List<SavedFeedItem> _reorderV2Items(List<SavedFeedItem> items, List<String> orderedUris) {
+    final itemByUri = {for (final item in items) item.value: item};
+    final reordered = <SavedFeedItem>[];
+
+    for (final uri in orderedUris) {
+      final item = itemByUri[uri];
+      if (item != null) {
+        reordered.add(item);
+      }
+    }
+
+    for (final item in items) {
+      if (!reordered.any((existing) => existing.value == item.value)) {
+        reordered.add(item);
+      }
+    }
+
+    return reordered;
+  }
+
+  Future<void> _clearLocalModifications(List<String> uris, String ownerDid) async {
+    await _dao.db.transaction(() async {
+      for (final uri in uris) {
+        await _dao.clearLocalModification(uri, ownerDid);
+      }
+    });
+  }
 }
 
 /// Helper class for representing a partial feed update during merge.
···
   final bool isPinned;
   final int sortOrder;
 }
+
+class _SavedFeedsPreferencesSnapshot {
+  const _SavedFeedsPreferencesSnapshot({
+    required this.preferences,
+    required this.v2,
+    required this.v1,
+    required this.v2Index,
+    required this.v1Index,
+  });
+
+  final List<Map<String, dynamic>> preferences;
+  final SavedFeedsPrefV2? v2;
+  final SavedFeedsPref? v1;
+  final int? v2Index;
+  final int? v1Index;
+}

lib/src/features/feeds/presentation/screens/bookmarks_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/core/widgets/pull_to_refresh_wrapper.dart';
···
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           SnackBar(
-            content: Text('Failed to refresh bookmarks: ${e.toString()}'),
+            content: Text('Failed to refresh bookmarks: ${errorMessage(e)}'),
             action: SnackBarAction(label: 'Retry', onPressed: _refresh),
           ),
         );
···
           loading: () => const LoadingView(),
           error: (e, st) => ErrorView(
             title: 'Failed to load bookmarks',
-            message: e.toString(),
+            message: errorMessage(e),
             onRetry: _refresh,
           ),
         ),

lib/src/features/feeds/presentation/screens/feed_management_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/features/feeds/application/feed_providers.dart';
···
         loading: () => const LoadingView(),
         error: (err, stack) => ErrorView(
           title: 'Failed to load feeds',
-          message: err.toString(),
+          message: errorMessage(err),
           onRetry: () => ref.invalidate(allFeedsProvider),
         ),
       ),

lib/src/features/feeds/presentation/screens/feed_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:lazurite/src/core/animations/animation_utils.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/core/widgets/pull_to_refresh_wrapper.dart';
···
           error: (err, stack) => ErrorView(
             key: const ValueKey('error'),
             title: 'Failed to load feed',
-            message: err.toString(),
+            message: errorMessage(err),
             onRetry: () => ref.read(feedContentProvider(activeFeedUri).notifier).refresh(),
           ),
         ),

lib/src/features/feeds/presentation/widgets/feed_preview_modal.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/features/feeds/application/feed_content_notifier.dart';
···
                   loading: () => const LoadingView(),
                   error: (err, stack) => ErrorView(
                     title: 'Failed to load preview',
-                    message: err.toString(),
+                    message: errorMessage(err),
                     onRetry: () {
                       ref.read(feedContentProvider(widget.feedUri).notifier).refresh();
                     },

lib/src/features/notifications/presentation/notifications_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:lazurite/src/core/animations/animation_utils.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/pull_to_refresh_wrapper.dart';
 import 'package:lazurite/src/features/auth/application/auth_providers.dart';
···
           error: (err, stack) => ErrorView(
             key: const ValueKey('error'),
             title: 'Failed to load notifications',
-            message: err.toString(),
+            message: errorMessage(err),
             onRetry: () => ref.read(notificationsProvider.notifier).refresh(),
           ),
         ),

lib/src/features/profile/presentation/followers_page.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/actor_row.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
···
         loading: () => const LoadingView(),
         error: (error, stack) => ErrorView(
           title: 'Failed to load followers',
+          message: errorMessage(error),
           onRetry: () => ref.invalidate(followersProvider(widget.did)),
         ),
         data: (followers) {

lib/src/features/profile/presentation/following_page.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/actor_row.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
···
         loading: () => const LoadingView(),
         error: (error, stack) => ErrorView(
           title: 'Failed to load following',
+          message: errorMessage(error),
           onRetry: () => ref.invalidate(followingProvider(widget.did)),
         ),
         data: (following) {

lib/src/features/profile/presentation/profile_screen.dart

···
 import 'package:go_router/go_router.dart';
 import 'package:lazurite/src/app/routes.dart';
 import 'package:lazurite/src/core/constants/layout_constants.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/feed_post_card.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
···
         appBar: AppBar(title: const Text('Profile')),
         body: ErrorView(
           title: 'Failed to load profile',
-          message: error.toString(),
+          message: errorMessage(error),
           onRetry: () => ref.read(profileProvider(widget.did).notifier).refresh(),
         ),
       ),

lib/src/features/search/presentation/search_screen.dart

···
 import 'package:go_router/go_router.dart';
 import 'package:lazurite/src/core/constants/layout_constants.dart';
 import 'package:lazurite/src/core/domain/post.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/features/feeds/presentation/widgets/post/post_embeds.dart';
 import 'package:lazurite/src/features/search/application/search_providers.dart';
···
         children: [
           const Icon(Icons.error_outline, size: 48),
           const SizedBox(height: 16),
-          Text('Error: $error'),
+          Text(errorMessage(error)),
           const SizedBox(height: 16),
           ElevatedButton(onPressed: onRetry, child: const Text('Retry')),
         ],

lib/src/features/thread/presentation/thread_screen.dart

···
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/core/widgets/error_view.dart';
 import 'package:lazurite/src/core/widgets/loading_view.dart';
 import 'package:lazurite/src/features/feeds/presentation/screens/widgets/feed_post_card.dart';
···
         loading: () => const LoadingView(),
         error: (err, stack) => ErrorView(
           title: 'Could not load thread',
-          message: err.toString(),
+          message: errorMessage(err),
           onRetry: () => ref.refresh(threadProvider(widget.postUri)),
         ),
         data: (thread) {
···
       loading: () => const LoadingView(),
       error: (err, stack) => ErrorView(
         title: 'Thread cache unavailable',
-        message: err.toString(),
+        message: errorMessage(err),
         onRetry: () => ref.refresh(threadProvider(widget.postUri)),
       ),
     );

test/src/core/utils/error_message_test.dart

···
+import 'package:flutter_test/flutter_test.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
+import 'package:lazurite/src/features/dms/domain/outbox_error.dart';
+import 'package:lazurite/src/infrastructure/auth/oauth_exceptions.dart';
+import 'package:lazurite/src/infrastructure/network/network_failure.dart';
+
+void main() {
+  group('errorMessage', () {
+    test('returns network-friendly messages', () {
+      expect(
+        errorMessage(const ConnectionFailure()),
+        'Network error. Check your connection and try again.',
+      );
+      expect(
+        errorMessage(const AuthFailure(requiresReauth: true)),
+        'Session expired. Please sign in again.',
+      );
+      expect(
+        errorMessage(const RateLimitFailure(retryAfter: Duration(seconds: 12))),
+        'Too many requests. Try again in 12s.',
+      );
+      expect(
+        errorMessage(const ClientFailure(statusCode: 404)),
+        'Not found. The item may have been deleted.',
+      );
+      expect(
+        errorMessage(const ServerFailure(statusCode: 500)),
+        'Server error. Please try again later.',
+      );
+      expect(
+        errorMessage(const DecodeFailure()),
+        'We received an unexpected response. Please try again.',
+      );
+    });
+
+    test('returns OAuth and validation messages', () {
+      const oauthError = InvalidGrantException(errorDescription: 'Token expired');
+      expect(errorMessage(oauthError), 'Token expired');
+
+      const validation = ValidationError(message: 'Message too long');
+      expect(errorMessage(validation), 'Message too long');
+    });
+
+    test('handles format and auth state errors', () {
+      expect(errorMessage(const FormatException('Invalid response')), 'Invalid response');
+      expect(
+        errorMessage(StateError('Must be authenticated to continue')),
+        'Please sign in to continue.',
+      );
+    });
+
+    test('falls back to default message for unknown errors', () {
+      expect(errorMessage(Exception('oops')), 'Something went wrong. Please try again.');
+      expect(errorMessage(null), 'Something went wrong. Please try again.');
+    });
+  });
+}

test/src/features/composer/infrastructure/draft_repository_test.dart

···
 import 'package:drift/native.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:lazurite/src/core/auth/session_model.dart';
+import 'package:lazurite/src/core/utils/error_message.dart';
 import 'package:lazurite/src/features/composer/domain/draft.dart' as composer;
 import 'package:lazurite/src/features/composer/infrastructure/draft_repository.dart';
 import 'package:lazurite/src/infrastructure/db/app_database.dart';
···
 
     final failed = await repository.getDraft(draft.id);
     expect(failed.status, composer.DraftStatus.failed);
-    expect(failed.errorMessage, contains('publish failed'));
+    expect(failed.errorMessage, errorMessage(Exception('publish failed')));
     expect(failed.media.single.uploadCid, 'cid-test');
   });
 

test/src/features/feeds/infrastructure/feed_repository_sync_test.dart

···
 
       final feed = await db.savedFeedsDao.getFeed(feedUri, ownerDid);
       expect(feed, isNotNull, reason: 'Local feed should be saved');
+      expect(feed!.localUpdatedAt, isNull, reason: 'Local modifications should be cleared');
 
       final queueItems = await db.preferenceSyncQueueDao.getPendingItems(ownerDid);
       expect(queueItems, isEmpty, reason: 'Queue should be empty after successful sync');
···
 
       final queueItems = await db.preferenceSyncQueueDao.getPendingItems(ownerDid);
       expect(queueItems, isEmpty, reason: 'Queue should be empty after successful sync');
+    });
+
+    test('saveFeed unpins feeds in legacy preferences when pin is false', () async {
+      const feedUri = 'at://did:plc:unpin/app.bsky.feed.generator/test';
+
+      final currentPrefs = {
+        'preferences': [
+          {
+            '\$type': 'app.bsky.actor.defs#savedFeedsPref',
+            'saved': [feedUri],
+            'pinned': [feedUri],
+          },
+        ],
+      };
+
+      final feedMetadata = {
+        'view': {
+          'uri': feedUri,
+          'cid': 'bafytest',
+          'did': 'did:web:feedgen.test',
+          'displayName': 'Test Feed',
+          'description': 'Test feed description',
+          'avatar': 'avatar.jpg',
+          'creator': {'did': 'did:plc:unpin', 'handle': 'unpin.user'},
+          'likeCount': 1,
+        },
+      };
+
+      when(
+        () => mockApi.call('app.bsky.feed.getFeedGenerator', params: {'feed': feedUri}),
+      ).thenAnswer((_) async => feedMetadata);
+      when(
+        () => mockApi.call('app.bsky.actor.getPreferences'),
+      ).thenAnswer((_) async => currentPrefs);
+
+      final capturedBodies = <Map<String, dynamic>>[];
+      when(
+        () => mockApi.call('app.bsky.actor.putPreferences', body: any(named: 'body')),
+      ).thenAnswer((invocation) async {
+        capturedBodies.add(invocation.namedArguments[#body] as Map<String, dynamic>);
+        return {};
+      });
+
+      await repository.saveFeed(feedUri, ownerDid, pin: false);
+
+      final prefs = capturedBodies.single['preferences'] as List<dynamic>;
+      final savedPref = prefs.cast<Map<String, dynamic>>().firstWhere(
+        (pref) => pref['\$type'] == 'app.bsky.actor.defs#savedFeedsPref',
+      );
+      final pinned = List<String>.from(savedPref['pinned'] as List);
+
+      expect(pinned.contains(feedUri), false, reason: 'Feed should be unpinned remotely');
+    });
+
+    test('saveFeed updates pinned state in V2 preferences', () async {
+      const feedUri = 'at://did:plc:v2/app.bsky.feed.generator/test';
+
+      final currentPrefs = {
+        'preferences': [
+          {
+            '\$type': 'app.bsky.actor.defs#savedFeedsPrefV2',
+            'items': [
+              {'value': feedUri, 'pinned': true, 'id': 'item-1'},
+            ],
+          },
+          {
+            '\$type': 'app.bsky.actor.defs#savedFeedsPref',
+            'saved': [feedUri],
+            'pinned': [feedUri],
+          },
+        ],
+      };
+
+      final feedMetadata = {
+        'view': {
+          'uri': feedUri,
+          'cid': 'bafytest',
+          'did': 'did:web:feedgen.test',
+          'displayName': 'Test Feed V2',
+          'description': 'Test feed description',
+          'avatar': 'avatar.jpg',
+          'creator': {'did': 'did:plc:v2', 'handle': 'v2.user'},
+          'likeCount': 1,
+        },
+      };
+
+      when(
+        () => mockApi.call('app.bsky.feed.getFeedGenerator', params: {'feed': feedUri}),
+      ).thenAnswer((_) async => feedMetadata);
+      when(
+        () => mockApi.call('app.bsky.actor.getPreferences'),
+      ).thenAnswer((_) async => currentPrefs);
+
+      final capturedBodies = <Map<String, dynamic>>[];
+      when(
+        () => mockApi.call('app.bsky.actor.putPreferences', body: any(named: 'body')),
+      ).thenAnswer((invocation) async {
+        capturedBodies.add(invocation.namedArguments[#body] as Map<String, dynamic>);
+        return {};
+      });
+
+      await repository.saveFeed(feedUri, ownerDid, pin: false);
+
+      final prefs = capturedBodies.single['preferences'] as List<dynamic>;
+      final v2Pref = prefs.cast<Map<String, dynamic>>().firstWhere(
+        (pref) => pref['\$type'] == 'app.bsky.actor.defs#savedFeedsPrefV2',
+      );
+      final items = v2Pref['items'] as List<dynamic>;
+      final item = items.cast<Map<String, dynamic>>().first;
+
+      expect(item['id'], 'item-1', reason: 'V2 item id should be preserved');
+      expect(item['pinned'], false, reason: 'Pinned flag should be updated');
+    });
+
+    test('reorderFeeds clears local modifications after successful sync', () async {
+      const feedUriA = 'at://did:plc:reorder/app.bsky.feed.generator/a';
+      const feedUriB = 'at://did:plc:reorder/app.bsky.feed.generator/b';
+
+      final now = DateTime.now();
+      await db.savedFeedsDao.upsertFeed(
+        SavedFeedsCompanion.insert(
+          uri: feedUriA,
+          displayName: 'Feed A',
+          creatorDid: 'did:plc:reorder',
+          sortOrder: 0,
+          lastSynced: now,
+          ownerDid: ownerDid,
+        ),
+      );
+      await db.savedFeedsDao.upsertFeed(
+        SavedFeedsCompanion.insert(
+          uri: feedUriB,
+          displayName: 'Feed B',
+          creatorDid: 'did:plc:reorder',
+          sortOrder: 1,
+          lastSynced: now,
+          ownerDid: ownerDid,
+        ),
+      );
+
+      final currentPrefs = {
+        'preferences': [
+          {
+            '\$type': 'app.bsky.actor.defs#savedFeedsPref',
+            'saved': [feedUriA, feedUriB],
+            'pinned': <String>[],
+          },
+        ],
+      };
+
+      when(
+        () => mockApi.call('app.bsky.actor.getPreferences'),
+      ).thenAnswer((_) async => currentPrefs);
+      when(
+        () => mockApi.call('app.bsky.actor.putPreferences', body: any(named: 'body')),
+      ).thenAnswer((_) async => {});
+
+      await repository.reorderFeeds([feedUriB, feedUriA], ownerDid);
+
+      final feedA = await db.savedFeedsDao.getFeed(feedUriA, ownerDid);
+      final feedB = await db.savedFeedsDao.getFeed(feedUriB, ownerDid);
+      expect(feedA!.localUpdatedAt, isNull);
+      expect(feedB!.localUpdatedAt, isNull);
     });
 
     test('rolls back local save when queue enqueue fails', () async {

test/src/features/search/presentation/search_screen_test.dart

···
 import 'package:lazurite/src/features/search/presentation/search_screen.dart';
 import 'package:lazurite/src/features/search/presentation/widgets/search_bar_widget.dart';
 import 'package:lazurite/src/infrastructure/db/app_database.dart' hide Post;
+import 'package:lazurite/src/infrastructure/network/network_failure.dart';
 import 'package:mocktail/mocktail.dart';
 
 class MockSearchRepository extends Mock implements SearchRepository {}
···
 
     testWidgets('retry on error', (tester) async {
       const query = 'error';
-      when(() => mockRepository.searchPosts(query, cursor: null)).thenThrow('Network Error');
+      when(
+        () => mockRepository.searchPosts(query, cursor: null),
+      ).thenThrow(const ConnectionFailure());
       when(
         () => mockRepository.searchActors(query, cursor: null),
       ).thenAnswer((_) async => const PaginatedResult(items: [], cursor: null));
···
       await tester.pumpWidget(createSubject(initialQuery: query));
       await tester.pumpAndSettle();
 
-      expect(find.text('Error: Network Error'), findsOneWidget);
+      expect(find.text('Network error. Check your connection and try again.'), findsOneWidget);
       expect(find.text('Retry'), findsOneWidget);
 
       await tester.tap(find.text('Retry'));