Add client media upload and cache pipeline

app/lib/auth/auth_api_client.dart

@@ -1,8 +1,11 @@
 import 'dart:convert';
+import 'dart:typed_data';
 
 import 'package:http/http.dart' as http;
+import 'package:http_parser/http_parser.dart';
 import 'package:papyrus/auth/auth_models.dart';
 import 'package:papyrus/auth/papyrus_api_config.dart';
+import 'package:papyrus/media/media_models.dart';
 
 class AuthApiException implements Exception {
   final int statusCode;
@@ -151,6 +154,46 @@ class AuthApiClient {
     await _postJson(config.endpoint('/sync/powersync-upload'), accessToken: accessToken, body: {'batch': batch});
   }
 
+  Future<MediaStorageUsage> fetchMediaUsage(String accessToken) async {
+    final json = await _getJson(config.endpoint('/media/usage'), accessToken: accessToken);
+    return MediaStorageUsage.fromJson(json);
+  }
+
+  Future<MediaAsset> uploadMedia(String accessToken, MediaUploadPayload payload) async {
+    final request = http.MultipartRequest('POST', config.endpoint('/media'))
+      ..headers.addAll(_authHeaders(accessToken))
+      ..fields['book_id'] = payload.bookId
+      ..fields['kind'] = payload.kind.apiValue
+      ..files.add(
+        http.MultipartFile.fromBytes(
+          'file',
+          payload.bytes,
+          filename: payload.filename,
+          contentType: _mediaType(payload.contentType),
+        ),
+      );
+
+    final response = await http.Response.fromStream(await _httpClient.send(request));
+    return MediaAsset.fromJson(_decodeResponse(response));
+  }
+
+  Future<Uint8List> downloadMedia(String accessToken, String assetId) async {
+    final response = await _httpClient.get(config.endpoint('/media/$assetId'), headers: _authHeaders(accessToken));
+    if (response.statusCode >= 200 && response.statusCode < 300) {
+      return response.bodyBytes;
+    }
+    _decodeResponse(response);
+    throw const AuthApiException(statusCode: 0, message: 'Media download failed');
+  }
+
+  Future<void> deleteMedia(String accessToken, String assetId) async {
+    final response = await _httpClient.delete(config.endpoint('/media/$assetId'), headers: _authHeaders(accessToken));
+    if (response.statusCode >= 200 && response.statusCode < 300) {
+      return;
+    }
+    _decodeResponse(response);
+  }
+
   Future<Map<String, dynamic>> _getJson(Uri uri, {String? accessToken}) async {
     final response = await _httpClient.get(uri, headers: _headers(accessToken));
 
@@ -185,6 +228,16 @@ class AuthApiClient {
     };
   }
 
+  Map<String, String> _authHeaders(String accessToken) {
+    return {'Accept': 'application/json', 'Authorization': 'Bearer $accessToken'};
+  }
+
+  MediaType _mediaType(String contentType) {
+    final parts = contentType.split('/');
+    if (parts.length != 2) return MediaType('application', 'octet-stream');
+    return MediaType(parts[0], parts[1]);
+  }
+
   Map<String, dynamic> _decodeResponse(http.Response response) {
     final decoded = response.body.isEmpty ? <String, dynamic>{} : jsonDecode(response.body) as Map<String, dynamic>;
 

app/lib/auth/auth_repository.dart

@@ -4,6 +4,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter_web_auth_2/flutter_web_auth_2.dart';
 import 'package:papyrus/auth/auth_api_client.dart';
 import 'package:papyrus/auth/auth_models.dart';
+import 'package:papyrus/media/media_models.dart';
 import 'package:papyrus/auth/token_store.dart';
 import 'package:papyrus/platform/web_redirect.dart';
 
@@ -194,6 +195,30 @@ class AuthRepository {
     });
   }
 
+  Future<MediaStorageUsage> fetchMediaUsage() {
+    return _withFreshAccessToken((accessToken) {
+      return apiClient.fetchMediaUsage(accessToken);
+    });
+  }
+
+  Future<MediaAsset> uploadMedia(MediaUploadPayload payload) {
+    return _withFreshAccessToken((accessToken) {
+      return apiClient.uploadMedia(accessToken, payload);
+    });
+  }
+
+  Future<Uint8List> downloadMedia(String assetId) {
+    return _withFreshAccessToken((accessToken) {
+      return apiClient.downloadMedia(accessToken, assetId);
+    });
+  }
+
+  Future<void> deleteMedia(String assetId) {
+    return _withFreshAccessToken((accessToken) {
+      return apiClient.deleteMedia(accessToken, assetId);
+    });
+  }
+
   Future<void> clearTokens() {
     return tokenStore.clear();
   }

app/lib/data/data_store.dart

@@ -48,6 +48,29 @@ class DataStore extends ChangeNotifier {
 
   bool get isLoaded => _isLoaded;
 
+  /// Completes when the active book repository has emitted its first snapshot.
+  ///
+  /// A direct repository lookup may temporarily return null while persistent
+  /// storage is still opening. Callers should wait for this before treating a
+  /// missing ID as authoritative.
+  Future<void> waitUntilLoaded() {
+    if (_isLoaded) return Future<void>.value();
+
+    final completer = Completer<void>();
+    late VoidCallback listener;
+    listener = () {
+      if (!_isLoaded || completer.isCompleted) return;
+      removeListener(listener);
+      completer.complete();
+    };
+
+    addListener(listener);
+    // Close the gap if loading completed between the initial check and listener
+    // registration.
+    listener();
+    return completer.future;
+  }
+
   List<Book> get books => _books.values.toList();
 
   /// Get all shelves with computed bookCount and coverPreviews.
@@ -74,6 +97,9 @@ class DataStore extends ChangeNotifier {
   Book? getBook(String id) => _books[id];
 
   Future<void> attachBookRepository(BookRepository repository) async {
+    final wasLoaded = _isLoaded;
+    _isLoaded = false;
+    if (wasLoaded) notifyListeners();
     await _bookSubscription?.cancel();
     _bookRepository = repository;
     _bookSubscription = repository.watchAll().listen(
@@ -92,22 +118,54 @@ class DataStore extends ChangeNotifier {
     _bookRepository = null;
   }
 
+  BookRepository requireBookRepository() {
+    final repository = _bookRepository;
+    if (repository == null) {
+      throw StateError('Book repository is not initialized');
+    }
+    return repository;
+  }
+
+  bool isBookRepositoryCurrent(BookRepository repository) => identical(_bookRepository, repository);
+
   void addBook(Book book) {
     final repository = _bookRepository;
     if (repository == null) {
       throw StateError('Book repository is not initialized');
     }
+    _books[book.id] = book;
+    notifyListeners();
     unawaited(repository.upsert(book));
   }
 
+  Future<void> addBookAndWait(Book book) async {
+    final repository = requireBookRepository();
+    await addBookToRepositoryAndWait(repository, book);
+  }
+
+  Future<void> addBookToRepositoryAndWait(BookRepository repository, Book book) async {
+    await repository.upsert(book);
+    if (isBookRepositoryCurrent(repository) && !identical(_books[book.id], book)) {
+      _books[book.id] = book;
+      notifyListeners();
+    }
+  }
+
   void updateBook(Book book) {
     final repository = _bookRepository;
     if (repository == null) {
       throw StateError('Book repository is not initialized');
     }
+    _books[book.id] = book;
+    notifyListeners();
     unawaited(repository.upsert(book));
   }
 
+  Future<void> updateBookAndWait(Book book) async {
+    final repository = requireBookRepository();
+    await addBookToRepositoryAndWait(repository, book);
+  }
+
   void deleteBook(String id) {
     final repository = _bookRepository;
     if (repository == null) {
@@ -116,11 +174,35 @@ class DataStore extends ChangeNotifier {
     unawaited(repository.delete(id));
   }
 
+  Future<void> deleteBookAndWait(String id) async {
+    final repository = requireBookRepository();
+    await deleteBookFromRepositoryAndWait(repository, id);
+  }
+
+  Future<void> deleteBookFromRepositoryAndWait(BookRepository repository, String id) async {
+    await repository.delete(id);
+    if (isBookRepositoryCurrent(repository) && _books.remove(id) != null) {
+      notifyListeners();
+    }
+  }
+
   void replaceBooksFromSync(List<Book> books) {
-    final syncedIds = books.map((book) => book.id).toSet();
+    final mergedBooks = books
+        .map((book) {
+          final localBook = _books[book.id];
+          if (book.coverMediaId == null && localBook?.coverMediaId != null) {
+            // PowerSync can briefly emit the downloaded server row before its
+            // pending local media-reference update is acknowledged. Keep the
+            // established local reference through that transient null snapshot.
+            return book.copyWith(coverMediaId: localBook!.coverMediaId);
+          }
+          return book;
+        })
+        .toList(growable: false);
+    final syncedIds = mergedBooks.map((book) => book.id).toSet();
     _books
       ..clear()
-      ..addEntries(books.map((book) => MapEntry(book.id, book)));
+      ..addEntries(mergedBooks.map((book) => MapEntry(book.id, book)));
     _bookShelfRelations.removeWhere((relation) => !syncedIds.contains(relation.bookId));
     _bookTagRelations.removeWhere((relation) => !syncedIds.contains(relation.bookId));
     _annotations.removeWhere((key, annotation) => !syncedIds.contains(annotation.bookId));
@@ -185,7 +267,10 @@ class DataStore extends ChangeNotifier {
   /// Get cover previews for a shelf (up to 4 books).
   List<CoverPreview> getCoverPreviewsForShelf(String shelfId, {int limit = 4}) {
     final books = getBooksInShelf(shelfId);
-    return books.take(limit).map((b) => CoverPreview(url: b.coverUrl, title: b.title)).toList();
+    return books
+        .take(limit)
+        .map((b) => CoverPreview(bookId: b.id, url: b.coverUrl, mediaId: b.coverMediaId, title: b.title))
+        .toList();
   }
 
   // ============================================================