Complete offline library sync and fix annotation editing and favorites

app/lib/data/repositories/library_repository.dart

@@ -0,0 +1,66 @@
+import 'package:papyrus/data/repositories/book_repository.dart';
+import 'package:papyrus/models/annotation.dart';
+import 'package:papyrus/models/book.dart';
+import 'package:papyrus/models/bookmark.dart';
+import 'package:papyrus/models/book_shelf_relation.dart';
+import 'package:papyrus/models/book_tag_relation.dart';
+import 'package:papyrus/models/note.dart';
+import 'package:papyrus/models/shelf.dart';
+import 'package:papyrus/models/tag.dart';
+
+abstract interface class EntityRepository<T> {
+  Future<T?> getById(String id);
+  Future<void> upsert(T value, {T? previous});
+  Future<void> delete(String id);
+}
+
+abstract interface class EditableBookRepository implements BookRepository {
+  bool get isCurrent;
+  Future<void> update(Book book, {required Book previous});
+}
+
+abstract interface class LibraryRepository {
+  Stream<LibrarySnapshot> watchLibrary();
+  EditableBookRepository get scopedBooks;
+  EntityRepository<Shelf> get shelves;
+  EntityRepository<Tag> get tags;
+  EntityRepository<Note> get notes;
+  EntityRepository<Annotation> get annotations;
+  EntityRepository<Bookmark> get bookmarks;
+  EntityRepository<BookShelfRelation> get bookShelves;
+  EntityRepository<BookTagRelation> get bookTags;
+  LibraryMembershipWriter get memberships;
+}
+
+abstract interface class LibraryMembershipWriter {
+  Future<void> updateMemberships({
+    required Set<String> bookIds,
+    List<String>? shelfIds,
+    List<String>? tagIds,
+    Set<String>? previousShelfIds,
+    Set<String>? previousTagIds,
+    bool additive = false,
+  });
+}
+
+class LibrarySnapshot {
+  final List<Book> books;
+  final List<Shelf> shelves;
+  final List<Tag> tags;
+  final List<Note> notes;
+  final List<Annotation> annotations;
+  final List<Bookmark> bookmarks;
+  final List<BookShelfRelation> bookShelves;
+  final List<BookTagRelation> bookTags;
+
+  const LibrarySnapshot({
+    this.books = const [],
+    this.shelves = const [],
+    this.tags = const [],
+    this.notes = const [],
+    this.annotations = const [],
+    this.bookmarks = const [],
+    this.bookShelves = const [],
+    this.bookTags = const [],
+  });
+}

app/lib/main.dart

@@ -411,7 +411,7 @@ class _PapyrusState extends State<Papyrus> {
         ChangeNotifierProvider.value(value: _acquisitionAvailabilityProvider),
         _acquisitionDownloadsComposition.providerRegistration(),
         ChangeNotifierProvider(create: (_) => SidebarProvider()),
-        ChangeNotifierProvider(create: (_) => LibraryProvider()),
+        ChangeNotifierProvider(create: (_) => LibraryProvider(dataStore: _dataStore)),
         ChangeNotifierProvider.value(value: _preferencesProvider),
       ],
       child: Consumer<PreferencesProvider>(

app/lib/models/annotation.dart

@@ -133,6 +133,7 @@ class Annotation {
     HighlightColor? color,
     BookLocation? location,
     String? note,
+    bool clearNote = false,
     DateTime? createdAt,
     DateTime? updatedAt,
   }) {
@@ -142,7 +143,7 @@ class Annotation {
       selectedText: selectedText ?? this.selectedText,
       color: color ?? this.color,
       location: location ?? this.location,
-      note: note ?? this.note,
+      note: clearNote ? null : note ?? this.note,
       createdAt: createdAt ?? this.createdAt,
       updatedAt: updatedAt ?? this.updatedAt,
     );

app/lib/models/book.dart

@@ -178,11 +178,16 @@ class Book {
     String? coverUrl,
     bool clearCoverUrl = false,
     String? fileMediaId,
+    bool clearFileMediaId = false,
     String? coverMediaId,
+    bool clearCoverMediaId = false,
     String? filePath,
     BookFormat? fileFormat,
+    bool clearFileFormat = false,
     int? fileSize,
+    bool clearFileSize = false,
     String? fileHash,
+    bool clearFileHash = false,
     bool? isPhysical,
     String? physicalLocation,
     bool clearPhysicalLocation = false,
@@ -192,21 +197,28 @@ class Book {
     bool clearLentAt = false,
     LibraryReadingStatus? readingStatus,
     int? currentPage,
+    bool clearCurrentPage = false,
     double? currentPosition,
     String? currentCfi,
+    bool clearCurrentCfi = false,
     bool? isFavorite,
     int? rating,
     bool clearRating = false,
     Map<String, dynamic>? customMetadata,
+    bool clearCustomMetadata = false,
     String? seriesId,
+    bool clearSeriesId = false,
     String? seriesName,
     bool clearSeriesName = false,
     double? seriesNumber,
     bool clearSeriesNumber = false,
     DateTime? addedAt,
     DateTime? startedAt,
+    bool clearStartedAt = false,
     DateTime? completedAt,
+    bool clearCompletedAt = false,
     DateTime? lastReadAt,
+    bool clearLastReadAt = false,
   }) {
     return Book(
       id: id ?? this.id,
@@ -222,30 +234,30 @@ class Book {
       pageCount: clearPageCount ? null : (pageCount ?? this.pageCount),
       description: clearDescription ? null : (description ?? this.description),
       coverUrl: clearCoverUrl ? null : (coverUrl ?? this.coverUrl),
-      fileMediaId: fileMediaId ?? this.fileMediaId,
-      coverMediaId: coverMediaId ?? this.coverMediaId,
+      fileMediaId: clearFileMediaId ? null : fileMediaId ?? this.fileMediaId,
+      coverMediaId: clearCoverMediaId ? null : coverMediaId ?? this.coverMediaId,
       filePath: filePath ?? this.filePath,
-      fileFormat: fileFormat ?? this.fileFormat,
-      fileSize: fileSize ?? this.fileSize,
-      fileHash: fileHash ?? this.fileHash,
+      fileFormat: clearFileFormat ? null : fileFormat ?? this.fileFormat,
+      fileSize: clearFileSize ? null : fileSize ?? this.fileSize,
+      fileHash: clearFileHash ? null : fileHash ?? this.fileHash,
       isPhysical: isPhysical ?? this.isPhysical,
       physicalLocation: clearPhysicalLocation ? null : (physicalLocation ?? this.physicalLocation),
       lentTo: clearLentTo ? null : (lentTo ?? this.lentTo),
       lentAt: clearLentAt ? null : (lentAt ?? this.lentAt),
       readingStatus: readingStatus ?? this.readingStatus,
-      currentPage: currentPage ?? this.currentPage,
+      currentPage: clearCurrentPage ? null : currentPage ?? this.currentPage,
       currentPosition: currentPosition ?? this.currentPosition,
-      currentCfi: currentCfi ?? this.currentCfi,
+      currentCfi: clearCurrentCfi ? null : currentCfi ?? this.currentCfi,
       isFavorite: isFavorite ?? this.isFavorite,
       rating: clearRating ? null : (rating ?? this.rating),
-      customMetadata: customMetadata ?? this.customMetadata,
-      seriesId: seriesId ?? this.seriesId,
+      customMetadata: clearCustomMetadata ? null : customMetadata ?? this.customMetadata,
+      seriesId: clearSeriesId ? null : seriesId ?? this.seriesId,
       seriesName: clearSeriesName ? null : (seriesName ?? this.seriesName),
       seriesNumber: clearSeriesNumber ? null : (seriesNumber ?? this.seriesNumber),
       addedAt: addedAt ?? this.addedAt,
-      startedAt: startedAt ?? this.startedAt,
-      completedAt: completedAt ?? this.completedAt,
-      lastReadAt: lastReadAt ?? this.lastReadAt,
+      startedAt: clearStartedAt ? null : startedAt ?? this.startedAt,
+      completedAt: clearCompletedAt ? null : completedAt ?? this.completedAt,
+      lastReadAt: clearLastReadAt ? null : lastReadAt ?? this.lastReadAt,
     );
   }
 

app/lib/models/note.dart

@@ -57,6 +57,7 @@ class Note {
     String? title,
     String? content,
     BookLocation? location,
+    bool clearLocation = false,
     List<String>? tags,
     bool? isPinned,
     DateTime? createdAt,
@@ -67,7 +68,7 @@ class Note {
       bookId: bookId ?? this.bookId,
       title: title ?? this.title,
       content: content ?? this.content,
-      location: location ?? this.location,
+      location: clearLocation ? null : location ?? this.location,
       tags: tags ?? this.tags,
       isPinned: isPinned ?? this.isPinned,
       createdAt: createdAt ?? this.createdAt,

app/lib/models/shelf.dart

@@ -13,13 +13,42 @@ class CoverPreview {
   const CoverPreview({required this.bookId, this.url, this.mediaId, required this.title});
 }
 
+/// Stored icon identity, including icons unavailable in this app's font bundle.
+class ShelfIconDescriptor {
+  final int codePoint;
+  final String? fontFamily;
+  final String? fontPackage;
+  final bool matchTextDirection;
+
+  const ShelfIconDescriptor({
+    required this.codePoint,
+    this.fontFamily,
+    this.fontPackage,
+    this.matchTextDirection = false,
+  });
+
+  factory ShelfIconDescriptor.fromIcon(IconData icon) => ShelfIconDescriptor(
+    codePoint: icon.codePoint,
+    fontFamily: icon.fontFamily,
+    fontPackage: icon.fontPackage,
+    matchTextDirection: icon.matchTextDirection,
+  );
+
+  bool matches(IconData icon) =>
+      codePoint == icon.codePoint &&
+      fontFamily == icon.fontFamily &&
+      fontPackage == icon.fontPackage &&
+      matchTextDirection == icon.matchTextDirection;
+}
+
 /// Data model for a book shelf (collection).
 class Shelf {
   final String id;
   final String name;
   final String? description;
   final String? colorHex;
   final IconData? icon;
+  final ShelfIconDescriptor? _storedIconDescriptor;
   final String? parentShelfId;
   final bool isSmart;
   final String? smartQuery;
@@ -37,6 +66,7 @@ class Shelf {
     this.description,
     this.colorHex,
     this.icon,
+    ShelfIconDescriptor? iconDescriptor,
     this.parentShelfId,
     this.isSmart = false,
     this.smartQuery,
@@ -45,7 +75,7 @@ class Shelf {
     required this.updatedAt,
     this.bookCount = 0,
     this.coverPreviews = const [],
-  });
+  }) : _storedIconDescriptor = iconDescriptor;
 
   /// Get display text for book count.
   String get bookCountLabel {
@@ -67,17 +97,25 @@ class Shelf {
   /// Get default icon if none specified.
   IconData get displayIcon => icon ?? Icons.folder_outlined;
 
+  /// The original identity is independent of the icon used for rendering.
+  ShelfIconDescriptor? get iconDescriptor =>
+      _storedIconDescriptor ?? (icon == null ? null : ShelfIconDescriptor.fromIcon(icon!));
+
   /// Create a copy with updated fields.
   Shelf copyWith({
     String? id,
     String? name,
     String? description,
     bool clearDescription = false,
     String? colorHex,
+    bool clearColorHex = false,
     IconData? icon,
+    bool clearIcon = false,
     String? parentShelfId,
+    bool clearParentShelfId = false,
     bool? isSmart,
     String? smartQuery,
+    bool clearSmartQuery = false,
     int? sortOrder,
     DateTime? createdAt,
     DateTime? updatedAt,
@@ -88,11 +126,13 @@ class Shelf {
       id: id ?? this.id,
       name: name ?? this.name,
       description: clearDescription ? null : description ?? this.description,
-      colorHex: colorHex ?? this.colorHex,
-      icon: icon ?? this.icon,
-      parentShelfId: parentShelfId ?? this.parentShelfId,
+      colorHex: clearColorHex ? null : colorHex ?? this.colorHex,
+      icon: clearIcon ? null : icon ?? this.icon,
+      // Editors also pass the unchanged display icon when editing other fields.
+      iconDescriptor: clearIcon || (icon != null && icon != this.icon) ? null : _storedIconDescriptor,
+      parentShelfId: clearParentShelfId ? null : parentShelfId ?? this.parentShelfId,
       isSmart: isSmart ?? this.isSmart,
-      smartQuery: smartQuery ?? this.smartQuery,
+      smartQuery: clearSmartQuery ? null : smartQuery ?? this.smartQuery,
       sortOrder: sortOrder ?? this.sortOrder,
       createdAt: createdAt ?? this.createdAt,
       updatedAt: updatedAt ?? this.updatedAt,
@@ -103,12 +143,16 @@ class Shelf {
 
   /// Convert to JSON for API/storage.
   Map<String, dynamic> toJson() {
+    final descriptor = iconDescriptor;
     return {
       'id': id,
       'name': name,
       'description': description,
       'color_hex': colorHex,
-      'icon': icon?.codePoint,
+      'icon': descriptor?.codePoint,
+      'icon_font_family': descriptor?.fontFamily,
+      'icon_font_package': descriptor?.fontPackage,
+      'icon_match_text_direction': descriptor?.matchTextDirection ?? false,
       'parent_shelf_id': parentShelfId,
       'is_smart': isSmart,
       'smart_query': smartQuery,
@@ -120,12 +164,25 @@ class Shelf {
 
   /// Create from JSON.
   factory Shelf.fromJson(Map<String, dynamic> json) {
+    final codePoint = json['icon'] as int?;
+    final descriptor = codePoint == null
+        ? null
+        : ShelfIconDescriptor(
+            codePoint: codePoint,
+            // Legacy shelf JSON stored only the Material icon's code point.
+            fontFamily: json.containsKey('icon_font_family')
+                ? json['icon_font_family'] as String?
+                : Icons.folder_outlined.fontFamily,
+            fontPackage: json['icon_font_package'] as String?,
+            matchTextDirection: json['icon_match_text_direction'] as bool? ?? false,
+          );
     return Shelf(
       id: json['id'] as String,
       name: json['name'] as String,
       description: json['description'] as String?,
       colorHex: json['color_hex'] as String?,
-      icon: _iconFromCodePoint(json['icon'] as int?),
+      icon: _iconFromDescriptor(descriptor),
+      iconDescriptor: descriptor,
       parentShelfId: json['parent_shelf_id'] as String?,
       isSmart: json['is_smart'] as bool? ?? false,
       smartQuery: json['smart_query'] as String?,
@@ -135,14 +192,13 @@ class Shelf {
     );
   }
 
-  /// Convert icon code point to IconData.
-  /// Returns null if codePoint is null.
+  /// Resolve a stored descriptor to a constant display icon.
   /// Only returns icons from availableIcons to allow tree shaking.
-  static IconData? _iconFromCodePoint(int? codePoint) {
-    if (codePoint == null) return null;
+  static IconData? _iconFromDescriptor(ShelfIconDescriptor? descriptor) {
+    if (descriptor == null) return null;
     // Look up in available icons only (for tree shaking compatibility)
     for (final icon in availableIcons) {
-      if (icon.codePoint == codePoint) return icon;
+      if (descriptor.matches(icon)) return icon;
     }
     // Return default icon if not found (instead of creating non-const IconData)
     return Icons.folder_outlined;

app/lib/models/tag.dart

@@ -21,12 +21,19 @@ class Tag {
   }
 
   /// Create a copy with updated fields.
-  Tag copyWith({String? id, String? name, String? colorHex, String? description, DateTime? createdAt}) {
+  Tag copyWith({
+    String? id,
+    String? name,
+    String? colorHex,
+    String? description,
+    bool clearDescription = false,
+    DateTime? createdAt,
+  }) {
     return Tag(
       id: id ?? this.id,
       name: name ?? this.name,
       colorHex: colorHex ?? this.colorHex,
-      description: description ?? this.description,
+      description: clearDescription ? null : description ?? this.description,
       createdAt: createdAt ?? this.createdAt,
     );
   }