Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart
79.5 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:io' show File, Platform;
import 'package:audio_service/audio_service.dart';

import 'package:flutter/foundation.dart';
import 'package:home_widget/home_widget.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'api_service.dart';
import 'server_backend.dart';
import 'audio_player_service.dart';
import 'book_search_index.dart';
import 'download_service.dart';
import 'progress_sync_service.dart';
import 'scoped_prefs.dart';
import 'user_account_service.dart';
import '../l10n/app_localizations.dart';
import '../main.dart' show rootNavigatorKey;

// ─── Media ID scheme ─────────────────────────────────────────────────
//
// Root tabs:
//   continue          → list of in-progress books / podcast episodes
//   library           → list of all libraries (books + podcasts)
//   downloads         → list of downloaded books / podcast episodes
//
// Book library drilldown:
//   lib:<libraryId>:books        → all books in library
//   lib:<libraryId>:series       → list of series
//   lib:<libraryId>:authors      → list of authors
//   series:<seriesId>@<libId>    → books in that series
//   author:<authorId>@<libId>    → books by that author
//
// Podcast library drilldown:
//   lib:<libraryId>              → list of podcast shows
//   show:<showId>@<libId>        → episodes of a show
//
// Playable items:
//   item:<absItemId>             → a playable book
//   item:<showId>-<episodeId>    → a playable podcast episode
// ─────────────────────────────────────────────────────────────────────

class AutoMediaIds {
  // Root tabs
  static const root = 'root';
  static const continueListening = 'continue';
  static const recentlyAdded = 'recently-added';
  static const library = 'library';
  static const downloads = 'downloads';

  // Prefixes
  static const itemPrefix = 'item:';
  static const libPrefix = 'lib:';
  static const seriesPrefix = 'series:';
  static const authorPrefix = 'author:';
  static const showPrefix = 'show:';
  static const collectionPrefix = 'collection:';
  static const playlistPrefix = 'playlist:';

  // Build IDs
  static String itemId(String absId) => '$itemPrefix$absId';
  static String libId(String libraryId) => '$libPrefix$libraryId';
  static String libBooks(String libraryId) => '$libPrefix$libraryId:books';
  static String libSeries(String libraryId) => '$libPrefix$libraryId:series';
  static String libAuthors(String libraryId) => '$libPrefix$libraryId:authors';
  static String libBookPrefix(String libraryId, String prefix) => '$libPrefix$libraryId:p:$prefix';
  static String libCollections(String libraryId) => '$libPrefix$libraryId:collections';
  static String libPlaylists(String libraryId) => '$libPrefix$libraryId:playlists';
  static String collectionId(String cId, String libId) => '$collectionPrefix$cId@$libId';
  static String playlistId(String pId, String libId) => '$playlistPrefix$pId@$libId';
  static String seriesId(String sId, String libId) => '$seriesPrefix$sId@$libId';
  static String authorId(String aId, String libId) => '$authorPrefix$aId@$libId';
  static String showId(String sId, String libId) => '$showPrefix$sId@$libId';

  // Parse helpers
  static String? absItemId(String mediaId) =>
      mediaId.startsWith(itemPrefix) ? mediaId.substring(itemPrefix.length) : null;

  /// Parse "series:<seriesId>@<libId>" → {seriesId, libId}
  static ({String seriesId, String libId})? parseSeries(String mediaId) {
    if (!mediaId.startsWith(seriesPrefix)) return null;
    final rest = mediaId.substring(seriesPrefix.length);
    final at = rest.indexOf('@');
    if (at < 0) return null;
    return (seriesId: rest.substring(0, at), libId: rest.substring(at + 1));
  }

  /// Parse "author:<authorId>@<libId>" → {authorId, libId}
  static ({String authorId, String libId})? parseAuthor(String mediaId) {
    if (!mediaId.startsWith(authorPrefix)) return null;
    final rest = mediaId.substring(authorPrefix.length);
    final at = rest.indexOf('@');
    if (at < 0) return null;
    return (authorId: rest.substring(0, at), libId: rest.substring(at + 1));
  }

  /// Parse "show:<showId>@<libId>" → {showId, libId}
  static ({String showId, String libId})? parseShow(String mediaId) {
    if (!mediaId.startsWith(showPrefix)) return null;
    final rest = mediaId.substring(showPrefix.length);
    final at = rest.indexOf('@');
    if (at < 0) return null;
    return (showId: rest.substring(0, at), libId: rest.substring(at + 1));
  }

  /// Parse "collection:<id>@<libId>" or "playlist:<id>@<libId>".
  static ({String id, String libId})? parseGroup(String mediaId, String prefix) {
    if (!mediaId.startsWith(prefix)) return null;
    final rest = mediaId.substring(prefix.length);
    final at = rest.indexOf('@');
    if (at < 0) return null;
    return (id: rest.substring(0, at), libId: rest.substring(at + 1));
  }

  /// Parse "lib:<libraryId>" or "lib:<libraryId>:books" etc.
  static String? parseLibId(String mediaId) {
    if (!mediaId.startsWith(libPrefix)) return null;
    final rest = mediaId.substring(libPrefix.length);
    final colon = rest.indexOf(':');
    return colon >= 0 ? rest.substring(0, colon) : rest;
  }

  /// Parse sub-category from "lib:<libraryId>:<sub>"
  static String? parseLibSub(String mediaId) {
    if (!mediaId.startsWith(libPrefix)) return null;
    final rest = mediaId.substring(libPrefix.length);
    final colon = rest.indexOf(':');
    return colon >= 0 ? rest.substring(colon + 1) : null;
  }
}

// ─── Data models ─────────────────────────────────────────────────────

class AutoBookEntry {
  final String id;
  final String title;
  final String author;
  final double duration;
  final String? coverUrl;
  final List<dynamic> chapters;
  final double? currentTime;

  /// Non-null for podcast episodes — the episode ID within the show.
  final String? episodeId;
  /// Non-null for podcast episodes — the show (podcast) ID.
  final String? showId;
  /// 'book' or 'podcast'. Used to route recently-added podcast shows into
  /// browseable show drilldown instead of unplayable item ids.
  final String mediaType;
  /// Library ID. Required to build a `show:` browse id for podcast shows.
  final String? libraryId;
  /// When the item was added to the server (ms), for the Date Added sort.
  final int? addedAt;

  const AutoBookEntry({
    required this.id,
    required this.title,
    required this.author,
    required this.duration,
    this.coverUrl,
    this.chapters = const [],
    this.currentTime,
    this.episodeId,
    this.showId,
    this.mediaType = 'book',
    this.libraryId,
    this.addedAt,
  });

  /// True when this entry represents a podcast show (not a single episode)
  /// that can only be browsed, not played directly.
  bool get _isPodcastShow =>
      mediaType == 'podcast' &&
      episodeId == null &&
      libraryId != null &&
      libraryId!.isNotEmpty;

  MediaItem toMediaItem() {
    final uri = coverUrl != null ? Uri.tryParse(coverUrl!) : null;

    // Recently-added podcast show — browseable, drills into episodes.
    if (_isPodcastShow) {
      return MediaItem(
        id: AutoMediaIds.showId(id, libraryId!),
        title: title,
        artUri: uri,
        playable: false,
        extras: uri != null ? {'artUri': uri.toString()} : null,
      );
    }

    // For podcast episodes, use compound key as the playable media ID
    final mediaId = (episodeId != null && showId != null)
        ? AutoMediaIds.itemId('$showId-$episodeId')
        : AutoMediaIds.itemId(id);
    return MediaItem(
      id: mediaId,
      title: title,
      artist: author,
      album: title,
      duration: Duration(seconds: duration.round()),
      artUri: uri,
      playable: true,
      extras: uri != null ? {'artUri': uri.toString()} : null,
    );
  }
}

class AutoLibraryEntry {
  final String id;
  final String name;
  final String mediaType;

  const AutoLibraryEntry({
    required this.id,
    required this.name,
    required this.mediaType,
  });

  bool get isBook => mediaType == 'book';
  bool get isPodcast => mediaType == 'podcast';
}

// ─── Android Auto Service ────────────────────────────────────────────

class AndroidAutoService {
  static final AndroidAutoService _instance = AndroidAutoService._();
  factory AndroidAutoService() => _instance;
  AndroidAutoService._() {
    DownloadService().addListener(_onDownloadsChanged);
  }

  Timer? _downloadsRefreshDebounce;
  String? _downloadsSignature;

  String _currentDownloadsSignature() {
    final entries = DownloadService()
        .downloadedItems
        .map((d) => '${d.itemId}|${d.title ?? ''}|${d.author ?? ''}|'
            '${d.localCoverPath ?? ''}|${d.libraryId ?? ''}')
        .toList()
      ..sort();
    return entries.join('\n');
  }

  void _onDownloadsChanged() {
    final signature = _currentDownloadsSignature();
    if (signature == _downloadsSignature) return;
    _downloadsSignature = signature;

    _downloadsRefreshDebounce?.cancel();
    _downloadsRefreshDebounce = Timer(const Duration(milliseconds: 500), () async {
      await _refreshDownloaded();
      _childrenCache.remove(AutoMediaIds.downloads);
      _childrenCache.remove(AutoMediaIds.root);
      if (Platform.isAndroid) {
        try {
          // ignore: deprecated_member_use
          await AudioServiceBackground.notifyChildrenChanged(AutoMediaIds.downloads);
        } catch (_) {}
      }
      try {
        onServerDataChanged?.call();
      } catch (_) {}
    });
  }

  // ── Cached data ──
  List<AutoBookEntry> _continueListening = [];
  List<AutoBookEntry> _recentlyAdded = [];
  List<AutoBookEntry> _downloaded = [];
  List<AutoLibraryEntry> _libraries = [];

  /// Public read-only access to cached data (used by CarPlayService)
  List<AutoBookEntry> get continueListening => _continueListening;
  List<AutoBookEntry> get recentlyAdded => _recentlyAdded;
  List<AutoBookEntry> get downloaded => _downloaded;
  List<AutoLibraryEntry> get libraries => _libraries;

  DateTime? _lastRefresh;
  bool _isRefreshing = false;

  // Per-parent MediaItem list cache. Returning the same instances on
  // re-requests is what lets AA preserve scroll position when the user goes
  // into an item and presses back. Also dedupes the back-to-back getChildren
  // calls AA fires when it re-renders.
  final Map<String, List<MediaItem>> _childrenCache = {};
  final Map<String, Future<List<MediaItem>>> _childrenInFlight = {};

  /// Clear all cached browse-tree data and force a fresh server fetch
  /// on the next access.  Call when the user switches accounts or logs out.
  void clearCache() {
    _continueListening = [];
    _recentlyAdded = [];
    _downloaded = [];
    _libraries = [];
    _lastRefresh = null;
    _downloadsReady = false;
    _isRefreshing = false;
    _childrenCache.clear();
    _childrenInFlight.clear();
    _groupEntries.clear();
    debugPrint('[AutoBrowse] Cache cleared (user switch/logout)');
  }

  // Top-level parents whose contents change with server refresh. Drilldown
  // children (series/author books, podcast episodes) stay cached until the
  // user explicitly switches accounts so scroll position survives.
  static const _refreshSensitiveParents = {
    AutoMediaIds.root,
    AutoMediaIds.continueListening,
    AutoMediaIds.recentlyAdded,
    AutoMediaIds.library,
    AutoMediaIds.downloads,
  };

  void _invalidateRefreshSensitiveChildren() {
    _childrenCache.removeWhere((k, _) =>
        _refreshSensitiveParents.contains(k) ||
        k.startsWith(AutoMediaIds.libPrefix));
  }

  // ── API helpers ──

  Future<ApiService?> getApi() async {
    final prefs = await SharedPreferences.getInstance();
    final url = prefs.getString('server_url');
    final token = prefs.getString('token');
    final refreshToken = prefs.getString('refresh_token');
    final username = prefs.getString('username');
    if (url == null || token == null) return null;
    Map<String, String> customHeaders = const {};
    final headersJson = prefs.getString('custom_headers');
    if (headersJson != null && headersJson.isNotEmpty) {
      try {
        customHeaders = Map<String, String>.from(jsonDecode(headersJson) as Map);
      } catch (_) {}
    }
    return ApiService.forSession(
      backend: ServerBackend.loadActive(prefs),
      baseUrl: url,
      token: token,
      refreshToken: refreshToken,
      isLegacyToken: refreshToken == null,
      customHeaders: customHeaders,
      loadPersistedTokens: () =>
          UserAccountService().loadPersistedTokens(url, username),
      onTokensRefreshed: (access, refresh) =>
          UserAccountService().persistRefreshedTokens(
            access,
            refresh,
            serverUrl: url,
            username: username,
          ),
    ).withMediaReady();
  }

  Future<String?> getDefaultLibraryId() async {
    // Prefer the user's selected library (set in-app) over the server default
    final selected = await ScopedPrefs.getString('last_selected_library');
    if (selected != null) return selected;
    final prefs = await SharedPreferences.getInstance();
    return prefs.getString('default_library_id');
  }

  // ── Refresh ──

  /// Whether downloads have been populated at least once (synchronous, no server needed).
  bool _downloadsReady = false;

  /// Fire-and-forget server refresh. Downloads are already available;
  /// this populates Continue and Library tabs in the background.
  void _backgroundRefresh() {
    refresh().then((_) {
      debugPrint('[AutoBrowse] Background refresh completed');
    }).catchError((e) {
      debugPrint('[AutoBrowse] Background refresh failed: $e');
    });
  }

  /// Called once the background server-side refresh completes (success or
  /// failure) so listeners can re-render their browse trees with the new
  /// data. CarPlayService sets this in init() to call refreshTemplates();
  /// AndroidAuto uses notifyChildrenChanged below independently.
  static void Function()? onServerDataChanged;

  /// Further listeners for the same moment (Siri's list of books).
  static final List<void Function()> serverDataListeners = [];

  Future<void> refresh({bool force = false}) async {
    // Always populate downloads immediately — no server needed.
    // This ensures Android Auto / CarPlay can show the Downloads tab even
    // if the server is unreachable (e.g. no remote access, offline-only
    // users).
    if (!_downloadsReady || force) {
      await _refreshDownloaded();
      _downloadsReady = true;
    }

    // Provisional Continue shelf from in-progress downloads, so it's useful
    // the moment the head unit queries it. The server fetch below can sit on
    // a 15s timeout when the server is unreachable, and by then the user is
    // already staring at an empty Continue tab. Server data replaces this
    // when (and if) it arrives.
    if (_continueListening.isEmpty) {
      await _buildOfflineContinueFromDownloads();
    }

    if (_isRefreshing) return;
    if (!force && _lastRefresh != null &&
        DateTime.now().difference(_lastRefresh!) < const Duration(seconds: 30)) {
      return;
    }

    _isRefreshing = true;
    debugPrint('[AutoBrowse] Refreshing browse tree...');
    // Kick the server fetch off in the background so callers (CarPlay scene
    // init, Android Auto media browser) don't block on a 15s `getLibraries`
    // timeout when the server is unreachable. The downloads pass above is
    // already populated; that's enough to render a useful browse tree
    // immediately. When the server data arrives (or fails) we fire the
    // listener hook so the UI re-renders with the fresh sections.
    unawaited(_refreshServerInBackground());
  }

  Future<void> _refreshServerInBackground() async {
    try {
      await _refreshDownloaded(); // re-fetch in case downloads changed
      await _refreshFromServer();
      _lastRefresh = DateTime.now();
      debugPrint('[AutoBrowse] Refresh done: '
          '${_continueListening.length} continue, '
          '${_recentlyAdded.length} recent, '
          '${_downloaded.length} downloaded, '
          '${_libraries.length} libraries '
          '(${_libraries.where((l) => l.isBook).length} book, '
          '${_libraries.where((l) => l.isPodcast).length} podcast)');
    } catch (e) {
      // Server unreachable — downloads are still available.
      _lastRefresh = DateTime.now();
      debugPrint('[AutoBrowse] Server refresh failed (downloads still available): $e');
    } finally {
      _isRefreshing = false;
      _invalidateRefreshSensitiveChildren();
      if (Platform.isAndroid) {
        // Notify every refresh-sensitive tab, not just root: the head unit
        // only re-queries nodes it's told about, so a root-only notify left
        // the Continue tab showing its pre-refresh (often empty) contents.
        for (final id in _refreshSensitiveParents) {
          try {
            // ignore: deprecated_member_use
            await AudioServiceBackground.notifyChildrenChanged(id);
          } catch (_) {}
        }
      }
      try {
        onServerDataChanged?.call();
      } catch (e) {
        debugPrint('[AutoBrowse] onServerDataChanged listener threw: $e');
      }
      for (final listener in serverDataListeners) {
        try {
          listener();
        } catch (e) {
          debugPrint('[AutoBrowse] server data listener threw: $e');
        }
      }
    }
  }

  /// Content provider authority for serving local cover images to Android Auto.
  /// Follows the installed package, as the manifest's `${applicationId}.covers`
  /// does, so the dev flavor reaches its own provider.
  static String get _coverAuthority => '${ApiService.packageName}.covers';

  // Per-item updatedAt for cover ?ts= cache busting on AA/CarPlay.
  static final Map<String, int> _itemUpdatedAt = {};

  static int? coverTsFor(String itemId) => _itemUpdatedAt[itemId];

  /// Build a content:// URI for a locally cached cover image.
  /// Android Auto requires content:// URIs, file:// won't work.
  static String localCoverUri(String itemId) {
    final ts = _itemUpdatedAt[itemId];
    final base = 'content://$_coverAuthority/cover/$itemId';
    return ts != null ? '$base?ts=$ts' : base;
  }

  static void notifyItemUpdated(String itemId, int updatedAt) {
    final prev = _itemUpdatedAt[itemId];
    if (prev == updatedAt) return;
    _itemUpdatedAt[itemId] = updatedAt;
    // Children cache holds old cover URIs.
    _instance._childrenCache.clear();
    try {
      onServerDataChanged?.call();
    } catch (e) {
      debugPrint('[AutoBrowse] notifyItemUpdated listener threw: $e');
    }
    if (Platform.isAndroid) {
      // ignore: deprecated_member_use
      unawaited(AudioServiceBackground
          .notifyChildrenChanged(AutoMediaIds.root)
          .catchError((_) {}));
    }
  }

  /// A car sort setting changed, so every cached list may be in the old order.
  static void browseOrderChanged() {
    _instance._childrenCache.clear();
    if (Platform.isAndroid) {
      // ignore: deprecated_member_use
      unawaited(AudioServiceBackground
          .notifyChildrenChanged(AutoMediaIds.root)
          .catchError((_) {}));
    }
  }

  Future<void> _refreshDownloaded() async {
    final ds = DownloadService();
    final items = ds.downloadedItems;
    _downloadsSignature = _currentDownloadsSignature();
    final entries = <AutoBookEntry>[];

    for (final dl in items) {
      double duration = 0;
      List<dynamic> chapters = [];
      if (dl.sessionData != null) {
        try {
          final session = jsonDecode(dl.sessionData!) as Map<String, dynamic>;
          duration = (session['duration'] as num?)?.toDouble() ?? 0;
          chapters = session['chapters'] as List<dynamic>? ?? [];
        } catch (_) {}
      }

      // GH #361: ebook-only books register as downloads with no audio files -
      // nothing to play in the car, so keep them out of the Downloads tab.
      if (dl.localPaths.isEmpty && duration <= 0) continue;

      final localPos = await ProgressSyncService().getSavedPosition(dl.itemId);

      // Detect podcast episode downloads via compound key (showId-episodeId).
      final isEpisode = dl.itemId.length > 36;
      String? showId;
      String? episodeId;
      if (isEpisode) {
        showId = dl.itemId.substring(0, 36);
        episodeId = dl.itemId.substring(37);
      }

      // Podcast episode covers use the show ID so the provider can fall back
      // to /api/items/<showId>/cover.
      final coverKey = isEpisode ? showId! : dl.itemId;
      if (dl.localCoverPath != null && dl.localCoverPath!.isNotEmpty) {
        try {
          final f = File(dl.localCoverPath!);
          if (f.existsSync()) {
            final ms = f.lastModifiedSync().millisecondsSinceEpoch;
            final prev = _itemUpdatedAt[coverKey];
            if (prev == null || ms > prev) _itemUpdatedAt[coverKey] = ms;
          }
        } catch (_) {}
      }
      String coverUrl;
      if (Platform.isIOS && dl.localCoverPath != null && dl.localCoverPath!.isNotEmpty) {
        coverUrl = Uri.file(dl.localCoverPath!).toString();
        final ts = _itemUpdatedAt[coverKey];
        if (ts != null) coverUrl = '$coverUrl?ts=$ts';
      } else {
        coverUrl = localCoverUri(coverKey);
      }

      entries.add(AutoBookEntry(
        id: dl.itemId,
        title: dl.title ?? 'Unknown',
        author: dl.author ?? '',
        duration: duration,
        coverUrl: coverUrl,
        chapters: chapters,
        currentTime: localPos > 0 ? localPos : null,
        episodeId: episodeId,
        showId: showId,
        libraryId: dl.libraryId,
      ));
      debugPrint('[AutoBrowse] Download entry: ${dl.title} cover=$coverUrl');
    }

    _downloaded = entries;
  }

  /// Build the Continue shelf from in-progress downloaded books when the server
  /// is unreachable, so the user can resume in Android Auto / CarPlay without
  /// digging through the Downloads tab (Discord request). Ordered to match the
  /// in-app Continue: items the user is actively absorbing first (persisted
  /// `absorbing_seen_ids`), then most recently played. Relies on `_downloaded`
  /// already being populated (it always is by the time this runs).
  Future<void> _buildOfflineContinueFromDownloads() async {
    if (_downloaded.isEmpty) {
      _continueListening = [];
      return;
    }
    final psync = ProgressSyncService();
    final absorbingOrder = await ScopedPrefs.getStringList('absorbing_seen_ids');
    final absorbingIndex = <String, int>{};
    for (var i = 0; i < absorbingOrder.length; i++) {
      absorbingIndex.putIfAbsent(absorbingOrder[i], () => i);
    }

    // (absorbing order, last-played ms, entry); a download's id is already the
    // same key the absorbing list uses (bookId, or showId-episodeId).
    final ranked = <(int, int, AutoBookEntry)>[];
    for (final entry in _downloaded) {
      final local = await psync.getLocal(entry.id);
      if (local == null) continue;
      final pos = (local['currentTime'] as num?)?.toDouble() ?? 0;
      final finished = local['isFinished'] as bool? ?? false;
      if (finished || pos <= 0) continue; // only books in progress
      final ts = (local['timestamp'] as num?)?.toInt() ?? 0;
      final order = absorbingIndex[entry.id] ?? (1 << 30);
      ranked.add((order, ts, entry));
    }
    ranked.sort((a, b) {
      if (a.$1 != b.$1) return a.$1.compareTo(b.$1);
      return b.$2.compareTo(a.$2);
    });
    _continueListening = ranked.map((e) => e.$3).toList();
    debugPrint(
        '[AutoBrowse] Offline Continue from downloads: ${_continueListening.length} in-progress');
  }

  Future<void> _refreshFromServer() async {
    final api = await getApi();
    if (api == null) return;

    final prefs = await SharedPreferences.getInstance();
    final manualOffline = prefs.getBool('manual_offline_mode') ?? false;
    // Skip the server fetch if we know we're offline. Without this,
    // CarPlay / AndroidAuto sit on a 15s getLibraries timeout every time
    // the user opens the app or connects to the head unit while their
    // server is unreachable.
    if (manualOffline || AudioPlayerService().knownOffline) {
      await _buildOfflineContinueFromDownloads();
      _recentlyAdded = [];
      _libraries = [];
      return;
    }

    try {
      // ── Fetch all libraries (books + podcasts) ──
      final libs = await api.getLibraries();
      if (libs.isEmpty) {
        // ApiService swallows network errors and returns an empty list, so
        // an unreachable server never reaches the catch below. A real ABS
        // account always has at least one library - treat empty as offline
        // and keep the downloads-based Continue shelf instead of wiping it.
        await _buildOfflineContinueFromDownloads();
        _recentlyAdded = [];
        _libraries = [];
        debugPrint('[AutoBrowse] getLibraries empty - treating as offline');
        return;
      }
      // BookOrbit's Book Dock holds files waiting to be filed, nothing to play.
      _libraries = libs.map((l) {
        final m = l as Map<String, dynamic>;
        return AutoLibraryEntry(
          id: m['id'] as String? ?? '',
          name: m['name'] as String? ?? 'Library',
          mediaType: m['mediaType'] as String? ?? 'book',
        );
      }).where((l) => l.id.isNotEmpty &&
              l.id != ApiService.bookDockLibraryId &&
              (l.isBook || l.isPodcast)).toList();

      // ── Personalized shelves merged from all libraries ──
      // Book libraries: continue-listening / continue-series for the Continue
      // tab, recently-added for the New tab.
      // Podcast libraries: continue-listening for the Continue tab. New
      // episodes come from a separate /recent-episodes call below since the
      // personalized endpoint's `episodes-recently-added` shelf gets stripped
      // when a `shelves` filter is passed.
      final clFutures = _libraries.map((lib) => api
          .getPersonalizedView(
            lib.id,
            include: const ['numEpisodesIncomplete'],
            shelves: lib.isPodcast
                ? const ['continue-listening']
                : const ['continue-listening', 'continue-series', 'recently-added'],
            limit: 10,
          )
          .then((sections) => sections ?? const <dynamic>[]));

      // Newly added podcast episodes per podcast library (empty for book libs).
      final episodeFutures = _libraries
          .map((lib) => lib.isPodcast
              ? api.getRecentEpisodes(lib.id, limit: 10)
              : Future.value(const <dynamic>[]))
          .toList();

      final allSections = await Future.wait(clFutures);
      final allRecentEpisodes = await Future.wait(episodeFutures);

      // Continue Listening: collect, dedupe, sort by lastUpdate desc
      final continueSeenIds = <String>{};
      final continueEntities = <Map<String, dynamic>>[];
      // Recently Added: ranked entries with their addedAt for cross-library sort.
      final recentSeenKeys = <String>{};
      final recentRanked = <(double, AutoBookEntry)>[];

      for (var i = 0; i < _libraries.length; i++) {
        final lib = _libraries[i];
        final sections = allSections[i];
        for (final section in sections) {
          final sectionId = section['id'] as String? ?? '';
          final entities = section['entities'] as List<dynamic>? ?? [];
          if (sectionId == 'continue-listening' || sectionId == 'continue-series') {
            for (final entity in entities) {
              if (entity is Map<String, dynamic>) {
                final id = entity['id'] as String? ?? '';
                final ep = entity['recentEpisode'] as Map<String, dynamic>?;
                final key = ep != null ? '$id-${ep['id'] ?? ''}' : id;
                if (key.isNotEmpty && continueSeenIds.add(key)) {
                  continueEntities.add(entity);
                }
              }
            }
          } else if (sectionId == 'recently-added' && lib.isBook) {
            for (final entity in entities) {
              if (entity is! Map<String, dynamic>) continue;
              final id = entity['id'] as String? ?? '';
              if (id.isEmpty || !recentSeenKeys.add(id)) continue;
              final entry = _entityToEntry(entity, api);
              if (entry == null) continue;
              final addedAt = (entity['addedAt'] as num?)?.toDouble() ?? 0;
              recentRanked.add((addedAt, entry));
            }
          }
        }

        // Newly added podcast episodes for this library.
        if (lib.isPodcast) {
          final episodes = allRecentEpisodes[i];
          for (final ep in episodes) {
            if (ep is! Map<String, dynamic>) continue;
            final entry = _recentEpisodeToEntry(ep, lib.id);
            if (entry == null) continue;
            if (!recentSeenKeys.add(entry.id)) continue;
            final addedAt = (ep['addedAt'] as num?)?.toDouble()
                ?? (ep['publishedAt'] as num?)?.toDouble()
                ?? 0;
            recentRanked.add((addedAt, entry));
          }
        }
      }

      // Order Continue to match the in-app Absorbing page: the user's actively
      // absorbing items come first, in that page's order (most recent first).
      // The server's mediaProgress.lastUpdate gets bumped on download/sync, so
      // sorting by it alone looks like "download order" (GH #287); the persisted
      // absorbing list is the real listening order. Items not in that list
      // (e.g. continue-series next books) fall after, by lastUpdate.
      final absorbingOrder =
          await ScopedPrefs.getStringList('absorbing_seen_ids');
      final absorbingIndex = <String, int>{};
      for (var i = 0; i < absorbingOrder.length; i++) {
        absorbingIndex.putIfAbsent(absorbingOrder[i], () => i);
      }
      String continueKey(Map<String, dynamic> e) {
        final id = e['id'] as String? ?? '';
        final ep = e['recentEpisode'] as Map<String, dynamic>?;
        return ep != null ? '$id-${ep['id'] ?? ''}' : id;
      }
      continueEntities.sort((a, b) {
        final ai = absorbingIndex[continueKey(a)] ?? (1 << 30);
        final bi = absorbingIndex[continueKey(b)] ?? (1 << 30);
        if (ai != bi) return ai.compareTo(bi);
        final aTime = ((a['mediaProgress'] as Map<String, dynamic>?)?['lastUpdate'] as num?)?.toDouble() ?? 0;
        final bTime = ((b['mediaProgress'] as Map<String, dynamic>?)?['lastUpdate'] as num?)?.toDouble() ?? 0;
        return bTime.compareTo(aTime);
      });
      _continueListening = continueEntities
          .map((e) => _entityToEntry(e, api))
          .whereType<AutoBookEntry>()
          .toList();

      recentRanked.sort((a, b) => b.$1.compareTo(a.$1));
      _recentlyAdded = recentRanked.map((e) => e.$2).toList();
    } catch (e) {
      // Server unreachable - fall back to in-progress downloads for Continue so
      // the user can still resume offline, and clear the rest.
      await _buildOfflineContinueFromDownloads();
      _recentlyAdded = [];
      _libraries = [];
      debugPrint('[AutoBrowse] Server fetch error: $e');
    }
  }

  // ── Data conversion ──

  List<AutoBookEntry> _resultsToEntries(
      Map<String, dynamic> result, ApiService api) {
    final results = result['results'] as List<dynamic>? ?? [];
    return results
        .whereType<Map<String, dynamic>>()
        .map((item) => _libraryItemToEntry(item, api))
        .whereType<AutoBookEntry>()
        .toList();
  }

  AutoBookEntry? _entityToEntry(Map<String, dynamic> entity, ApiService api) {
    final id = entity['id'] as String?;
    if (id == null) return null;
    // GH #361: ebook-only items can't play in a car - keep them off the
    // Continue and New shelves (CarPlay reuses these lists too).
    if (PlayerSettings.isEbookOnly(entity)) return null;

    final media = entity['media'] as Map<String, dynamic>?;
    final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
    final showTitle = metadata['title'] as String? ?? 'Unknown';
    final author = metadata['authorName'] as String? ?? '';
    final mediaType = entity['mediaType'] as String? ?? 'book';
    final libraryId = entity['libraryId'] as String?;

    final progress = entity['mediaProgress'] as Map<String, dynamic>?;
    final currentTime = (progress?['currentTime'] as num?)?.toDouble();

    // Podcast entities from continue-listening have a recentEpisode field
    final recentEp = entity['recentEpisode'] as Map<String, dynamic>?;
    if (recentEp != null) {
      final episodeId = recentEp['id'] as String?;
      if (episodeId == null) return null;
      final episodeTitle = recentEp['title'] as String? ?? 'Episode';
      final epDuration = (recentEp['duration'] as num?)?.toDouble() ?? 0;
      final chapters = recentEp['chapters'] as List<dynamic>? ?? [];

      return AutoBookEntry(
        id: '$id-$episodeId', // compound key
        title: episodeTitle,
        author: showTitle,    // show name as artist
        duration: epDuration,
        coverUrl: localCoverUri(id), // show ID for cover
        chapters: chapters,
        currentTime: currentTime,
        episodeId: episodeId,
        showId: id,
        mediaType: mediaType,
        libraryId: libraryId,
      );
    }

    // Regular book entity, or recently-added podcast show.
    final duration = (media?['duration'] as num?)?.toDouble() ?? 0;
    final chapters = media?['chapters'] as List<dynamic>? ?? [];

    return AutoBookEntry(
      id: id,
      title: showTitle,
      author: author,
      duration: duration,
      coverUrl: localCoverUri(id),
      chapters: chapters,
      currentTime: currentTime,
      mediaType: mediaType,
      libraryId: libraryId,
    );
  }

  /// Convert an episode object from /api/libraries/:id/recent-episodes into
  /// an AutoBookEntry. Each episode includes the parent show's metadata under
  /// either `podcast.media.metadata` (full library item shape) or
  /// `podcast.metadata` (compact shape).
  AutoBookEntry? _recentEpisodeToEntry(Map<String, dynamic> ep, String libraryId) {
    final episodeId = ep['id'] as String?;
    if (episodeId == null || episodeId.isEmpty) return null;

    final showId = (ep['libraryItemId'] as String?)
        ?? (ep['podcastId'] as String?)
        ?? ((ep['podcast'] as Map<String, dynamic>?)?['id'] as String?);
    if (showId == null || showId.isEmpty) return null;

    final episodeTitle = ep['title'] as String? ?? 'Episode';

    String? showTitle;
    final podcast = ep['podcast'] as Map<String, dynamic>?;
    if (podcast != null) {
      final mediaMeta =
          (podcast['media'] as Map<String, dynamic>?)?['metadata'] as Map<String, dynamic>?;
      showTitle = mediaMeta?['title'] as String?
          ?? (podcast['metadata'] as Map<String, dynamic>?)?['title'] as String?;
    }
    showTitle ??= ep['podcastTitle'] as String? ?? '';

    final duration = (ep['duration'] as num?)?.toDouble()
        ?? ((ep['audioFile'] as Map<String, dynamic>?)?['duration'] as num?)?.toDouble()
        ?? 0;
    final chapters = ep['chapters'] as List<dynamic>? ?? const [];

    return AutoBookEntry(
      id: '$showId-$episodeId',
      title: episodeTitle,
      author: showTitle,
      duration: duration,
      coverUrl: localCoverUri(showId),
      chapters: chapters,
      episodeId: episodeId,
      showId: showId,
      mediaType: 'podcast',
      libraryId: libraryId,
    );
  }

  AutoBookEntry? _libraryItemToEntry(
      Map<String, dynamic> item, ApiService api) {
    final id = item['id'] as String?;
    if (id == null) return null;
    // GH #361: ebook-only items can't play in a car - hide them from the
    // library drilldowns (CarPlay reuses these lists too).
    if (PlayerSettings.isEbookOnly(item)) return null;

    final updatedAt = (item['updatedAt'] as num?)?.toInt();
    if (updatedAt != null) _itemUpdatedAt[id] = updatedAt;

    final media = item['media'] as Map<String, dynamic>?;
    final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
    final title = metadata['title'] as String? ?? 'Unknown';
    final author = metadata['authorName'] as String? ?? '';
    final duration = (media?['duration'] as num?)?.toDouble() ?? 0;
    final chapters = media?['chapters'] as List<dynamic>? ?? [];

    return AutoBookEntry(
      id: id,
      title: title,
      author: author,
      duration: duration,
      coverUrl: localCoverUri(id),
      chapters: chapters,
      libraryId: item['libraryId'] as String?,
      addedAt: (item['addedAt'] as num?)?.toInt(),
    );
  }

  // ─── Browse tree ───────────────────────────────────────────────────

  AppLocalizations? _l() {
    final ctx = rootNavigatorKey.currentContext;
    return ctx != null ? AppLocalizations.of(ctx) : null;
  }

  List<MediaItem> _getRootChildren() {
    // Always show all three tabs so the layout is consistent and doesn't
    // look like a missing 4th button.  Each tab fetches on-demand if its
    // cache is empty (cold start / background refresh pending).
    final l = _l();
    return [
      MediaItem(
        id: AutoMediaIds.continueListening,
        title: l?.androidAutoTabContinue ?? 'Continue',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.recentlyAdded,
        title: 'New',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.library,
        title: l?.androidAutoTabLibrary ?? 'Library',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.downloads,
        title: l?.androidAutoTabDownloads ?? 'Downloads',
        playable: false,
      ),
    ];
  }

  /// Sub-categories for a book library: Books, Series, Authors
  List<MediaItem> _getBookSubCategories(String libraryId) {
    final l = _l();
    return [
      MediaItem(
        id: AutoMediaIds.libBooks(libraryId),
        title: l?.androidAutoCatBooks ?? 'Books',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.libSeries(libraryId),
        title: l?.androidAutoCatSeries ?? 'Series',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.libAuthors(libraryId),
        title: l?.androidAutoCatAuthors ?? 'Authors',
        playable: false,
      ),
      MediaItem(
        id: AutoMediaIds.libCollections(libraryId),
        title: l?.androidAutoCatCollections ?? 'Collections',
        playable: false,
      ),
      if (!ServerBackend.active.isBookOrbit)
        MediaItem(
          id: AutoMediaIds.libPlaylists(libraryId),
          title: l?.androidAutoCatPlaylists ?? 'Playlists',
          playable: false,
        ),
    ];
  }

  /// Main entry point for browse tree. May make API calls for drilldowns.
  Future<List<MediaItem>> getChildrenOf(String parentMediaId) {
    // Android asks for this after the app is gone, to keep a resume card in
    // the quick settings media carousel. Never cached - it has to follow
    // whatever was played last.
    if (parentMediaId == AudioService.recentRootId) return _recentChildren();
    final cached = _childrenCache[parentMediaId];
    if (cached != null) return Future.value(cached);

    final inFlight = _childrenInFlight[parentMediaId];
    if (inFlight != null) return inFlight;

    final future = () async {
      try {
        final children = await _computeChildren(parentMediaId);
        _childrenCache[parentMediaId] = children;
        return children;
      } finally {
        _childrenInFlight.remove(parentMediaId);
      }
    }();
    _childrenInFlight[parentMediaId] = future;
    return future;
  }

  Future<List<MediaItem>> _computeChildren(String parentMediaId) async {
    // Ensure downloads are always populated before returning root.
    // This is instant (no network) so Android Auto never waits on a server.
    if (!_downloadsReady) {
      await _refreshDownloaded();
      _downloadsReady = true;
    }

    // Kick off a full server refresh in the background if we haven't done one.
    // Don't await, return what we have now (downloads at minimum).
    if (_lastRefresh == null && !_isRefreshing) {
      _backgroundRefresh();
    }

    // ── Root ──
    if (parentMediaId == AutoMediaIds.root) {
      return _getRootChildren();
    }

    // ── Top-level tabs ──
    if (parentMediaId == AutoMediaIds.continueListening) {
      // If empty (cold start / background refresh pending), fetch now
      if (_continueListening.isEmpty) {
        try {
          await _refreshFromServer();
        } catch (e) {
          debugPrint('[AutoBrowse] On-demand continue fetch failed: $e');
        }
      }
      return _continueListening.map((e) => e.toMediaItem()).toList();
    }
    if (parentMediaId == AutoMediaIds.recentlyAdded) {
      if (_recentlyAdded.isEmpty) {
        try {
          await _refreshFromServer();
        } catch (e) {
          debugPrint('[AutoBrowse] On-demand recent fetch failed: $e');
        }
      }
      return _recentlyAdded.map((e) => e.toMediaItem()).toList();
    }
    if (parentMediaId == AutoMediaIds.downloads) {
      return _downloaded.map((e) => e.toMediaItem()).toList();
    }

    // ── Library list ──
    if (parentMediaId == AutoMediaIds.library) {
      // If no libraries cached yet (cold start, background refresh pending
      // or failed), fetch synchronously so the user sees real content
      // instead of an empty list.
      if (_libraries.isEmpty) {
        try {
          await _refreshFromServer();
        } catch (e) {
          debugPrint('[AutoBrowse] On-demand library fetch failed: $e');
        }
      }
      // If only one library, skip picker → go straight to its contents
      if (_libraries.length == 1) {
        final lib = _libraries.first;
        if (lib.isPodcast) return _fetchPodcastShows(lib.id);
        return _getBookSubCategories(lib.id);
      }
      return _libraries.map((lib) {
        return MediaItem(
          id: AutoMediaIds.libId(lib.id),
          title: lib.name,
          playable: false,
        );
      }).toList();
    }

    // ── Library drilldowns ──
    if (parentMediaId.startsWith(AutoMediaIds.libPrefix)) {
      final libId = AutoMediaIds.parseLibId(parentMediaId);
      final sub = AutoMediaIds.parseLibSub(parentMediaId);
      if (libId == null) return [];

      if (sub == null) {
        // "lib:<id>" — check if book or podcast library
        final lib = _libraries.cast<AutoLibraryEntry?>().firstWhere(
          (l) => l!.id == libId,
          orElse: () => null,
        );
        if (lib != null && lib.isPodcast) {
          // Podcast library → list shows directly
          return _fetchPodcastShows(libId);
        }
        // Book library → sub-categories
        return _getBookSubCategories(libId);
      }

      if (sub.startsWith('p:')) {
        return _fetchBooksAtPrefix(libId, sub.substring(2));
      }
      switch (sub) {
        case 'books':
          return _fetchBooksAtPrefix(libId, '');
        case 'series':
          return _fetchLibrarySeries(libId);
        case 'authors':
          return _fetchLibraryAuthors(libId);
        case 'collections':
          final collections = await fetchCollectionsData(libId);
          return collections
              .map((c) => MediaItem(
                    id: AutoMediaIds.collectionId(c.id, libId),
                    title: c.name,
                    playable: false,
                  ))
              .toList();
        case 'playlists':
          final playlists = await fetchPlaylistsData(libId);
          return playlists
              .map((p) => MediaItem(
                    id: AutoMediaIds.playlistId(p.id, libId),
                    title: p.name,
                    playable: false,
                  ))
              .toList();
      }
    }

    final collection =
        AutoMediaIds.parseGroup(parentMediaId, AutoMediaIds.collectionPrefix);
    if (collection != null) {
      final books = await fetchCollectionBooksData(collection.id);
      return books.map((e) => e.toMediaItem()).toList();
    }
    final playlist =
        AutoMediaIds.parseGroup(parentMediaId, AutoMediaIds.playlistPrefix);
    if (playlist != null) {
      final items = await fetchPlaylistItemsData(playlist.id);
      return items.map((e) => e.toMediaItem()).toList();
    }

    // ── Show drilldown (podcast episodes) ──
    final show = AutoMediaIds.parseShow(parentMediaId);
    if (show != null) {
      return _fetchShowEpisodes(show.showId, show.libId);
    }

    // ── Series drilldown ──
    final series = AutoMediaIds.parseSeries(parentMediaId);
    if (series != null) {
      return _fetchSeriesBooks(series.seriesId, series.libId);
    }

    // ── Author drilldown ──
    final author = AutoMediaIds.parseAuthor(parentMediaId);
    if (author != null) {
      return _fetchAuthorBooks(author.authorId, author.libId);
    }

    return [];
  }

  // ─── On-demand fetchers ────────────────────────────────────────────

  Future<List<MediaItem>> _fetchLibrarySeries(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      // Fetch all series, paginated, sorted alphabetically
      final allSeries = <MediaItem>[];
      int page = 0;
      const pageSize = 100;

      while (true) {
        final result = await api.getLibrarySeries(
          libraryId, page: page, limit: pageSize, sort: 'name', desc: 0,
        );
        if (result == null) break;

        final seriesList = result['results'] as List<dynamic>? ?? [];
        for (final s in seriesList) {
          final sm = s as Map<String, dynamic>;
          final sId = sm['id'] as String? ?? '';
          final name = sm['name'] as String? ?? 'Unknown';
          if (sId.isEmpty) continue;
          allSeries.add(MediaItem(
            id: AutoMediaIds.seriesId(sId, libraryId),
            title: name,
            playable: false,
          ));
        }

        final total = (result['total'] as num?)?.toInt() ?? 0;
        if (allSeries.length >= total || seriesList.length < pageSize) break;
        page++;
      }

      debugPrint('[AutoBrowse] Fetched ${allSeries.length} series');
      return allSeries;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching series: $e');
    }
    return [];
  }

  Future<List<MediaItem>> _fetchLibraryAuthors(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      final filterData = await api.getLibraryFilterData(libraryId);
      if (filterData != null) {
        final authorsList = filterData['authors'] as List<dynamic>? ?? [];
        final items = authorsList.map((a) {
          final am = a as Map<String, dynamic>;
          final aId = am['id'] as String? ?? '';
          final name = am['name'] as String? ?? 'Unknown';
          if (aId.isEmpty) return null;
          return MediaItem(
            id: AutoMediaIds.authorId(aId, libraryId),
            title: name,
            playable: false,
          );
        }).whereType<MediaItem>().toList();

        items.sort((a, b) => a.title.toLowerCase().compareTo(b.title.toLowerCase()));
        debugPrint('[AutoBrowse] Fetched ${items.length} authors');
        return items;
      }
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching authors: $e');
    }
    return [];
  }

  Future<List<MediaItem>> _fetchSeriesBooks(String seriesId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      final results = await api.getBooksBySeries(libraryId, seriesId);
      return _sortBySeriesSequence(results, seriesId)
          .map((item) => _libraryItemToEntry(item, api))
          .whereType<AutoBookEntry>()
          .map((e) => e.toMediaItem())
          .toList();
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching series books: $e');
      return [];
    }
  }

  /// Sort raw library items by their sequence within the given series.
  /// The server's `sort=media.metadata.series.sequence` param sorts as a
  /// string, so "10" lands before "2". Books missing a sequence go last.
  static final _leadingNumberRe = RegExp(r'^[\d.]+');
  List<Map<String, dynamic>> _sortBySeriesSequence(
      List<dynamic> results, String seriesId) {
    final maps = results.whereType<Map<String, dynamic>>().toList();
    double seqFor(Map<String, dynamic> item) {
      final media = item['media'] as Map<String, dynamic>? ?? const {};
      final metadata = media['metadata'] as Map<String, dynamic>? ?? const {};
      final raw = metadata['series'];
      final seriesList = raw is List
          ? raw.whereType<Map<String, dynamic>>()
          : raw is Map<String, dynamic>
              ? [raw]
              : const <Map<String, dynamic>>[];
      for (final s in seriesList) {
        if (s['id'] != seriesId) continue;
        final match = _leadingNumberRe
            .firstMatch((s['sequence'] ?? '').toString().trim());
        if (match != null) {
          final parsed = double.tryParse(match.group(0)!);
          if (parsed != null) return parsed;
        }
      }
      return double.maxFinite;
    }

    maps.sort((a, b) => seqFor(a).compareTo(seqFor(b)));
    return maps;
  }

  Future<List<MediaItem>> _fetchAuthorBooks(String authorId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      final results = await api.getBooksByAuthor(libraryId, authorId);
      return results
          .whereType<Map<String, dynamic>>()
          .map((item) => _libraryItemToEntry(item, api))
          .whereType<AutoBookEntry>()
          .map((e) => e.toMediaItem())
          .toList();
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching author books: $e');
      return [];
    }
  }

  /// Fetch all podcast shows in a library. Shows are browsable, not playable.
  Future<List<MediaItem>> _fetchPodcastShows(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      const maxItems = 200;
      final allShows = <MediaItem>[];
      int page = 0;
      const pageSize = 100;
      final byAdded = await PlayerSettings.getCarPodcastSort() == 'added';

      while (allShows.length < maxItems) {
        final result = await api.getLibraryItems(
          libraryId, page: page, limit: pageSize,
          sort: byAdded ? 'addedAt' : 'media.metadata.title',
          desc: byAdded ? 1 : 0,
        );
        if (result == null) break;

        final results = result['results'] as List<dynamic>? ?? [];
        for (final item in results) {
          if (item is! Map<String, dynamic>) continue;
          final id = item['id'] as String?;
          if (id == null) continue;
          final media = item['media'] as Map<String, dynamic>?;
          final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
          final title = metadata['title'] as String? ?? 'Unknown';
          final coverUri = Uri.tryParse(localCoverUri(id));

          allShows.add(MediaItem(
            id: AutoMediaIds.showId(id, libraryId),
            title: title,
            artUri: coverUri,
            playable: false,
            extras: coverUri != null ? {'artUri': coverUri.toString()} : null,
          ));
        }

        final total = (result['total'] as num?)?.toInt() ?? 0;
        if (allShows.length >= total || results.length < pageSize) break;
        page++;
      }

      if (allShows.length > maxItems) {
        return allShows.sublist(0, maxItems);
      }

      debugPrint('[AutoBrowse] Fetched ${allShows.length} podcast shows');
      return allShows;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching podcast shows: $e');
    }
    return [];
  }

  /// Fetch episodes for a podcast show. Sorted newest-first.
  Future<List<MediaItem>> _fetchShowEpisodes(String showId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];

    try {
      final fullItem = await api.getLibraryItem(showId);
      if (fullItem == null) return [];

      final media = fullItem['media'] as Map<String, dynamic>?;
      final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
      final showTitle = metadata['title'] as String? ?? 'Podcast';
      final episodes = media?['episodes'] as List<dynamic>? ?? [];

      final sorted = List<dynamic>.from(episodes);
      final oldestFirst = await PlayerSettings.getCarEpisodesOldestFirst();
      sorted.sort((a, b) {
        final aTime = (a['publishedAt'] as num?)?.toInt() ?? 0;
        final bTime = (b['publishedAt'] as num?)?.toInt() ?? 0;
        return oldestFirst ? aTime.compareTo(bTime) : bTime.compareTo(aTime);
      });

      final coverUri = Uri.tryParse(localCoverUri(showId));
      final items = <MediaItem>[];

      for (final ep in sorted) {
        if (ep is! Map<String, dynamic>) continue;
        final epId = ep['id'] as String?;
        if (epId == null) continue;
        final epTitle = ep['title'] as String? ?? 'Episode';
        final epDuration = (ep['duration'] as num?)?.toDouble() ?? 0;

        items.add(MediaItem(
          id: AutoMediaIds.itemId('$showId-$epId'),
          title: epTitle,
          artist: showTitle,
          album: showTitle,
          duration: Duration(seconds: epDuration.round()),
          artUri: coverUri,
          playable: true,
          extras: coverUri != null ? {'artUri': coverUri.toString()} : null,
        ));
      }

      debugPrint('[AutoBrowse] Fetched ${items.length} episodes for "$showTitle"');
      return items;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching show episodes: $e');
    }
    return [];
  }

  // ─── Public data fetchers (used by CarPlayService) ─────────────────

  /// Build an HTTP cover URL for use on iOS (CarPlay).
  /// Android uses content:// URIs via CoverContentProvider; iOS loads HTTP directly.
  Future<String?> getCoverHttpUrl(String itemId) async {
    final api = await getApi();
    if (api == null) return null;
    return api.getCoverUrl(itemId, updatedAt: _itemUpdatedAt[itemId]);
  }

  /// Fetch books for a library, returning raw entries.
  // ─── Alphabetical drilldown (CarPlay + Android Auto) ───────────────
  // Large libraries blow past Android Auto's ~1MB Binder limit and stampede
  // CarPlay's per-item cover loading. We group books by a growing title prefix
  // (the ABS app calls this "alphabetical drawdown"): show buckets when a list
  // exceeds [bucketThreshold], and drill one more character (T -> Th -> The) for
  // any bucket that's still too big - so a huge letter splits rather than being
  // truncated. We also skip characters that don't split (e.g. the space in
  // "The ") so the pile breaks by the real word.
  // 50 keeps final lists short and scannable (more letter drilldown) on both
  // surfaces; CarPlay's memory is handled by the patched plugin image loader,
  // so this is a navigation-feel choice, not a crash guard.
  static const int bucketThreshold = 50;

  // Cached full (title-sorted) book list per library so re-navigating doesn't
  // re-fetch the whole library each time.
  final Map<String, ({DateTime at, List<AutoBookEntry> books})> _allBooksCache = {};
  static const _booksCacheTtl = Duration(minutes: 5);

  /// Uppercased, left-trimmed title for prefix bucketing ('#' when empty).
  static String _normTitle(String title) {
    final t = title.trimLeft();
    return t.isEmpty ? '#' : t.toUpperCase();
  }

  /// The [len]-character uppercased prefix of a title (whole title if shorter).
  static String _prefixOf(String title, int len) {
    final t = _normTitle(title);
    return t.length <= len ? t : t.substring(0, len);
  }

  /// Fetch every book in the library (no cap), title-sorted. Cached for
  /// [_booksCacheTtl]. Shared by CarPlay and Android Auto.
  Future<List<AutoBookEntry>> fetchAllBooks(String libraryId) async {
    final cached = _allBooksCache[libraryId];
    if (cached != null && DateTime.now().difference(cached.at) < _booksCacheTtl) {
      return cached.books;
    }
    final api = await getApi();
    final books = <AutoBookEntry>[];
    if (api == null) return books;
    try {
      var page = 0;
      const pageSize = 100;
      while (true) {
        final result = await api.getLibraryItems(
          libraryId, page: page, limit: pageSize,
          sort: 'media.metadata.title', desc: 0,
        );
        if (result == null) break;
        final entries = _resultsToEntries(result, api);
        books.addAll(entries);
        final serverTotal = (result['total'] as num?)?.toInt() ?? 0;
        if (books.length >= serverTotal || entries.length < pageSize) break;
        page++;
      }
      _allBooksCache[libraryId] = (at: DateTime.now(), books: books);
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching all books: $e');
    }
    return books;
  }

  /// Resolve a browse level for [prefix] (empty = top). Returns either the leaf
  /// list of books to show, or the next set of (deeper) prefix buckets. Buckets
  /// are returned only when the matching list exceeds [bucketThreshold] and a
  /// longer prefix actually splits it; otherwise the matching books are a leaf.
  ({List<AutoBookEntry>? books, List<({String prefix, int count})>? buckets})
      resolveBrowseLevel(List<AutoBookEntry> all, String prefix,
          {String sort = 'title'}) {
    if (sort == 'added') return _resolveRangeLevel(all, prefix);
    final matching = booksForPrefix(all, prefix, sort: sort);
    if (matching.length <= bucketThreshold) {
      return (books: matching, buckets: null);
    }
    // Extend the prefix one character at a time until it actually splits the
    // list (skips non-splitting chars like the space in "The ").
    var depth = prefix.length + 1;
    while (true) {
      final counts = <String, int>{};
      for (final b in matching) {
        final k = _prefixOf(_bucketText(b, sort), depth);
        counts[k] = (counts[k] ?? 0) + 1;
      }
      if (counts.length > 1) {
        final buckets = counts.entries
            .map((e) => (prefix: e.key, count: e.value))
            .toList();
        return (books: null, buckets: buckets);
      }
      // Single bucket: go deeper only while some title is longer than [depth];
      // otherwise these titles are identical and can't be split - show them.
      if (!matching.any((b) => _normTitle(_bucketText(b, sort)).length > depth)) {
        return (books: matching, buckets: null);
      }
      depth++;
    }
  }

  /// What a book is grouped by: its author for the author sort, else its title.
  static String _bucketText(AutoBookEntry b, String sort) =>
      sort == 'author' ? b.author : b.title;

  /// Date Added has no letters to group by, so it splits into numbered runs
  /// ("1-50", "51-100") in sort order. A range too big for one level splits
  /// into bigger runs first, so no level lists more than [bucketThreshold].
  ({List<AutoBookEntry>? books, List<({String prefix, int count})>? buckets})
      _resolveRangeLevel(List<AutoBookEntry> all, String prefix) {
    final range = _parseRange(prefix, all.length);
    final count = range.end - range.start;
    if (count <= bucketThreshold) {
      return (books: all.sublist(range.start, range.end), buckets: null);
    }
    var size = bucketThreshold;
    while ((count / size).ceil() > bucketThreshold) {
      size *= bucketThreshold;
    }
    final buckets = <({String prefix, int count})>[];
    for (var start = range.start; start < range.end; start += size) {
      final end = start + size < range.end ? start + size : range.end;
      buckets.add((prefix: '${start + 1}-$end', count: end - start));
    }
    return (books: null, buckets: buckets);
  }

  /// "51-100" back to list indices; anything else is the whole list.
  static ({int start, int end}) _parseRange(String prefix, int length) {
    final parts = prefix.split('-');
    if (parts.length == 2) {
      final first = int.tryParse(parts[0]);
      final last = int.tryParse(parts[1]);
      if (first != null && last != null && first >= 1 && first <= last) {
        return (
          start: (first - 1).clamp(0, length),
          end: last.clamp(0, length),
        );
      }
    }
    return (start: 0, end: length);
  }

  /// Every book in the library in the order the car sort setting asks for,
  /// plus that sort so the caller groups them to match.
  Future<({List<AutoBookEntry> books, String sort})> fetchSortedBooks(
      String libraryId) async {
    final all = await fetchAllBooks(libraryId);
    final sort = await PlayerSettings.getCarBookSort();
    final reverse = await PlayerSettings.getCarBookSortReverse();
    var books = all;
    if (sort == 'author') {
      books = [...all]
        ..sort((a, b) {
          final byAuthor = _normTitle(a.author).compareTo(_normTitle(b.author));
          return byAuthor != 0
              ? byAuthor
              : _normTitle(a.title).compareTo(_normTitle(b.title));
        });
    } else if (sort == 'added') {
      books = [...all]
        ..sort((a, b) => (b.addedAt ?? 0).compareTo(a.addedAt ?? 0));
    }
    if (reverse) books = books.reversed.toList();
    return (books: books, sort: sort);
  }

  /// Flatten the recursive prefix tree into a single ordered list of LEAF
  /// buckets (each <= [bucketThreshold] books). Used by CarPlay, where the
  /// recursive push drilldown isn't possible: CarPlay caps the navigation
  /// stack (~5 templates), so we show one bucket level then the books instead
  /// of pushing a template per letter the way Android Auto can.
  List<({String prefix, int count})> flattenedBookBuckets(
      List<AutoBookEntry> all,
      {String sort = 'title'}) {
    final out = <({String prefix, int count})>[];
    void walk(String prefix) {
      final level = resolveBrowseLevel(all, prefix, sort: sort);
      if (level.books != null) {
        if (level.books!.isNotEmpty) {
          out.add((prefix: prefix, count: level.books!.length));
        }
        return;
      }
      for (final b in level.buckets!) {
        walk(b.prefix);
      }
    }

    walk('');
    return out;
  }

  /// All books whose title falls under [prefix] (a leaf bucket from
  /// [flattenedBookBuckets]). Empty prefix = the whole library.
  List<AutoBookEntry> booksForPrefix(List<AutoBookEntry> all, String prefix,
      {String sort = 'title'}) {
    if (prefix.isEmpty) return all;
    if (sort == 'added') {
      final range = _parseRange(prefix, all.length);
      return all.sublist(range.start, range.end);
    }
    return all
        .where((b) => _normTitle(_bucketText(b, sort)).startsWith(prefix))
        .toList();
  }

  /// Android Auto children for a books browse level at [prefix] (empty = top).
  Future<List<MediaItem>> _fetchBooksAtPrefix(String libraryId, String prefix) async {
    final sorted = await fetchSortedBooks(libraryId);
    final level = resolveBrowseLevel(sorted.books, prefix, sort: sorted.sort);
    final books = level.books;
    if (books != null) {
      return books.map((e) => e.toMediaItem()).toList();
    }
    return level.buckets!
        .map((b) => MediaItem(
              id: AutoMediaIds.libBookPrefix(libraryId, b.prefix),
              title: b.prefix,
              playable: false,
            ))
        .toList();
  }

  /// Fetch series list for a library, returning id/name pairs.
  Future<List<({String id, String name})>> fetchLibrarySeriesData(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      final allSeries = <({String id, String name})>[];
      int page = 0;
      const pageSize = 100;
      while (true) {
        final result = await api.getLibrarySeries(
          libraryId, page: page, limit: pageSize, sort: 'name', desc: 0,
        );
        if (result == null) break;
        final seriesList = result['results'] as List<dynamic>? ?? [];
        for (final s in seriesList) {
          final sm = s as Map<String, dynamic>;
          final sId = sm['id'] as String? ?? '';
          final name = sm['name'] as String? ?? 'Unknown';
          if (sId.isNotEmpty) allSeries.add((id: sId, name: name));
        }
        final total = (result['total'] as num?)?.toInt() ?? 0;
        if (allSeries.length >= total || seriesList.length < pageSize) break;
        page++;
      }
      return allSeries;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching series data: $e');
      return [];
    }
  }

  /// Fetch authors list for a library, returning id/name pairs.
  Future<List<({String id, String name})>> fetchLibraryAuthorsData(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      final filterData = await api.getLibraryFilterData(libraryId);
      if (filterData != null) {
        final authorsList = filterData['authors'] as List<dynamic>? ?? [];
        final items = authorsList.map((a) {
          final am = a as Map<String, dynamic>;
          final aId = am['id'] as String? ?? '';
          final name = am['name'] as String? ?? 'Unknown';
          return aId.isNotEmpty ? (id: aId, name: name) : null;
        }).whereType<({String id, String name})>().toList();
        items.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));
        return items;
      }
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching authors data: $e');
    }
    return [];
  }

  // Collections and playlists come back with their books already expanded,
  // so the list fetch holds everything a drilldown needs. Keyed 'c:<id>' and
  // 'p:<id>'.
  final Map<String, List<AutoBookEntry>> _groupEntries = {};

  /// Collections in a library, in server order, with how many playable books
  /// each holds.
  Future<List<({String id, String name, int count})>> fetchCollectionsData(
      String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    final list = await api.getLibraryCollections(libraryId) ?? const [];
    final out = <({String id, String name, int count})>[];
    for (final c in list.whereType<Map<String, dynamic>>()) {
      final id = c['id'] as String?;
      if (id == null) continue;
      final books = _collectionEntries(c, api);
      _groupEntries['c:$id'] = books;
      out.add((id: id, name: c['name'] as String? ?? 'Collection', count: books.length));
    }
    return out;
  }

  Future<List<AutoBookEntry>> fetchCollectionBooksData(String collectionId) async {
    final cached = _groupEntries['c:$collectionId'];
    if (cached != null) return cached;
    final api = await getApi();
    if (api == null) return [];
    final collection = await api.getCollection(collectionId);
    if (collection == null) return [];
    return _groupEntries['c:$collectionId'] = _collectionEntries(collection, api);
  }

  List<AutoBookEntry> _collectionEntries(Map<String, dynamic> c, ApiService api) =>
      ((c['books'] as List<dynamic>?) ?? const [])
          .whereType<Map<String, dynamic>>()
          .map((b) => _libraryItemToEntry(b, api))
          .whereType<AutoBookEntry>()
          .toList();

  /// The user's playlists in a library, in server order.
  Future<List<({String id, String name, int count})>> fetchPlaylistsData(
      String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    final list = await api.getLibraryPlaylists(libraryId) ?? const [];
    final out = <({String id, String name, int count})>[];
    for (final p in list.whereType<Map<String, dynamic>>()) {
      final id = p['id'] as String?;
      if (id == null) continue;
      final items = _playlistEntries(p, api);
      _groupEntries['p:$id'] = items;
      out.add((id: id, name: p['name'] as String? ?? 'Playlist', count: items.length));
    }
    return out;
  }

  Future<List<AutoBookEntry>> fetchPlaylistItemsData(String playlistId) async {
    final cached = _groupEntries['p:$playlistId'];
    if (cached != null) return cached;
    final api = await getApi();
    if (api == null) return [];
    final playlist = await api.getPlaylist(playlistId);
    if (playlist == null) return [];
    return _groupEntries['p:$playlistId'] = _playlistEntries(playlist, api);
  }

  /// Playlist entries can be whole books or single podcast episodes.
  List<AutoBookEntry> _playlistEntries(Map<String, dynamic> p, ApiService api) {
    final out = <AutoBookEntry>[];
    for (final item in ((p['items'] as List<dynamic>?) ?? const [])
        .whereType<Map<String, dynamic>>()) {
      final libraryItem = item['libraryItem'] as Map<String, dynamic>?;
      if (libraryItem == null) continue;
      final episode = item['episode'] as Map<String, dynamic>?;
      if (episode == null) {
        final entry = _libraryItemToEntry(libraryItem, api);
        if (entry != null) out.add(entry);
        continue;
      }
      final showId = libraryItem['id'] as String?;
      final episodeId = episode['id'] as String? ?? item['episodeId'] as String?;
      if (showId == null || episodeId == null) continue;
      final media = libraryItem['media'] as Map<String, dynamic>?;
      final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
      final audioFile = episode['audioFile'] as Map<String, dynamic>?;
      out.add(AutoBookEntry(
        id: '$showId-$episodeId',
        title: episode['title'] as String? ?? 'Episode',
        author: metadata['title'] as String? ?? '',
        duration: ((episode['duration'] ?? audioFile?['duration']) as num?)
                ?.toDouble() ??
            0,
        coverUrl: localCoverUri(showId),
        chapters: episode['chapters'] as List<dynamic>? ?? const [],
        episodeId: episodeId,
        showId: showId,
        mediaType: 'podcast',
        libraryId: libraryItem['libraryId'] as String?,
      ));
    }
    return out;
  }

  /// Fetch books in a series, returning raw entries.
  Future<List<AutoBookEntry>> fetchSeriesBooksData(String seriesId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      final results = await api.getBooksBySeries(libraryId, seriesId);
      return _sortBySeriesSequence(results, seriesId)
          .map((item) => _libraryItemToEntry(item, api))
          .whereType<AutoBookEntry>()
          .toList();
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching series books data: $e');
      return [];
    }
  }

  /// Fetch books by an author, returning raw entries.
  Future<List<AutoBookEntry>> fetchAuthorBooksData(String authorId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      final results = await api.getBooksByAuthor(libraryId, authorId);
      return results
          .whereType<Map<String, dynamic>>()
          .map((item) => _libraryItemToEntry(item, api))
          .whereType<AutoBookEntry>()
          .toList();
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching author books data: $e');
      return [];
    }
  }

  /// Fetch podcast shows in a library, returning id/title pairs with cover URLs.
  Future<List<({String id, String title, String? coverUrl})>> fetchPodcastShowsData(String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      const maxItems = 200;
      final allShows = <({String id, String title, String? coverUrl})>[];
      int page = 0;
      const pageSize = 100;
      final byAdded = await PlayerSettings.getCarPodcastSort() == 'added';
      while (allShows.length < maxItems) {
        final result = await api.getLibraryItems(
          libraryId, page: page, limit: pageSize,
          sort: byAdded ? 'addedAt' : 'media.metadata.title',
          desc: byAdded ? 1 : 0,
        );
        if (result == null) break;
        final results = result['results'] as List<dynamic>? ?? [];
        for (final item in results) {
          if (item is! Map<String, dynamic>) continue;
          final id = item['id'] as String?;
          if (id == null) continue;
          final updatedAt = (item['updatedAt'] as num?)?.toInt();
          if (updatedAt != null) _itemUpdatedAt[id] = updatedAt;
          final media = item['media'] as Map<String, dynamic>?;
          final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
          final title = metadata['title'] as String? ?? 'Unknown';
          allShows.add((id: id, title: title, coverUrl: api.getCoverUrl(id, updatedAt: updatedAt)));
        }
        final total = (result['total'] as num?)?.toInt() ?? 0;
        if (allShows.length >= total || results.length < pageSize) break;
        page++;
      }
      return allShows.length > maxItems ? allShows.sublist(0, maxItems) : allShows;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching podcast shows data: $e');
      return [];
    }
  }

  /// Fetch episodes for a podcast show, returning raw entries.
  Future<List<AutoBookEntry>> fetchShowEpisodesData(String showId, String libraryId) async {
    final api = await getApi();
    if (api == null) return [];
    try {
      final fullItem = await api.getLibraryItem(showId);
      if (fullItem == null) return [];
      final showUpdatedAt = (fullItem['updatedAt'] as num?)?.toInt();
      if (showUpdatedAt != null) _itemUpdatedAt[showId] = showUpdatedAt;
      final media = fullItem['media'] as Map<String, dynamic>?;
      final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
      final showTitle = metadata['title'] as String? ?? 'Podcast';
      final episodes = media?['episodes'] as List<dynamic>? ?? [];
      final sorted = List<dynamic>.from(episodes);
      final oldestFirst = await PlayerSettings.getCarEpisodesOldestFirst();
      sorted.sort((a, b) {
        final aTime = (a['publishedAt'] as num?)?.toInt() ?? 0;
        final bTime = (b['publishedAt'] as num?)?.toInt() ?? 0;
        return oldestFirst ? aTime.compareTo(bTime) : bTime.compareTo(aTime);
      });
      final entries = <AutoBookEntry>[];
      for (final ep in sorted) {
        if (ep is! Map<String, dynamic>) continue;
        final epId = ep['id'] as String?;
        if (epId == null) continue;
        entries.add(AutoBookEntry(
          id: '$showId-$epId',
          title: ep['title'] as String? ?? 'Episode',
          author: showTitle,
          duration: (ep['duration'] as num?)?.toDouble() ?? 0,
          coverUrl: api.getCoverUrl(showId, updatedAt: showUpdatedAt),
          chapters: ep['chapters'] as List<dynamic>? ?? [],
          episodeId: epId,
          showId: showId,
          libraryId: fullItem['libraryId'] as String? ?? libraryId,
        ));
      }
      return entries;
    } catch (e) {
      debugPrint('[AutoBrowse] Error fetching show episodes data: $e');
      return [];
    }
  }

  // ─── Search ────────────────────────────────────────────────────────

  Future<List<MediaItem>> search(String query) async {
    final api = await getApi();
    final libId = await getDefaultLibraryId();
    if (api == null || libId == null) return [];
    final trimmedQuery = query.trim();
    if (trimmedQuery.isEmpty) return [];

    try {
      final library = _libraries.cast<AutoLibraryEntry?>().firstWhere(
        (entry) => entry?.id == libId,
        orElse: () => null,
      );
      if (library?.isPodcast != true) {
        final index = BookSearchIndex();
        await index.ensureIndex(api, libId);
        // A truncated index misses the newest items in a huge library, so its
        // hits alone aren't the full answer - fall through to the server
        // search and merge instead of returning early (GH #349).
        if (index.isReady(libId) && !index.isTruncated(libId)) {
          final hits = index
              .search(libId, trimmedQuery, limit: 20)
              .where((hit) => hit.item['mediaType'] != 'podcast')
              .map((hit) => _libraryItemToEntry(hit.item, api)?.toMediaItem())
              .whereType<MediaItem>()
              .toList();
          if (library?.isBook == true || hits.isNotEmpty) return hits;
        }
      }

      final result = await api.searchLibrary(libId, trimmedQuery, limit: 20);
      if (result == null) return [];

      final items = <MediaItem>[];
      // Search book results
      final books = result['book'] as List<dynamic>? ?? [];
      for (final b in books) {
        final bm = b as Map<String, dynamic>;
        final libraryItem = bm['libraryItem'] as Map<String, dynamic>?;
        if (libraryItem != null) {
          final entry = _libraryItemToEntry(libraryItem, api);
          if (entry != null) {
            items.add(entry.toMediaItem());
          }
        }
      }
      // Search podcast results
      final podcasts = result['podcast'] as List<dynamic>? ?? [];
      for (final p in podcasts) {
        final pm = p as Map<String, dynamic>;
        final libraryItem = pm['libraryItem'] as Map<String, dynamic>?;
        if (libraryItem != null) {
          final id = libraryItem['id'] as String?;
          if (id != null) {
            final media = libraryItem['media'] as Map<String, dynamic>?;
            final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};
            final title = metadata['title'] as String? ?? 'Unknown';
            final coverUri = Uri.tryParse(localCoverUri(id));
            items.add(MediaItem(
              id: AutoMediaIds.showId(id, libId),
              title: title,
              artUri: coverUri,
              playable: false,
              extras: coverUri != null ? {'artUri': coverUri.toString()} : null,
            ));
          }
        }
      }
      return items;
    } catch (e) {
      debugPrint('[AutoBrowse] Search error: $e');
      return [];
    }
  }

  /// The last book or episode played, as one playable item, from local data
  /// only so it works with no connection. Same record the cold-start restore
  /// resumes from, so tapping play on the card plays what the card shows.
  Future<List<MediaItem>> _recentChildren() async {
    try {
      final prefs = await SharedPreferences.getInstance();
      final itemId = prefs.getString('widget_item_id');
      if (itemId == null || itemId.isEmpty) return const [];
      final episodeId = prefs.getString('widget_episode_id');
      final key = episodeId != null ? '$itemId-$episodeId' : itemId;

      var title = '';
      var author = '';
      final known = findEntry(key);
      final dl = DownloadService();
      if (known != null) {
        title = known.title;
        author = known.author;
      } else if (dl.isDownloaded(key)) {
        final info = dl.getInfo(key);
        title = info.title ?? '';
        author = info.author ?? '';
      }
      if (title.isEmpty) {
        // The widget keeps "Author · Book" (or "Show · Episode") under the
        // chapter title, which is the best a streamed item leaves behind.
        final subtitle =
            await HomeWidget.getWidgetData<String>('widget_author') ?? '';
        final cut = subtitle.indexOf(' · ');
        if (cut > 0) {
          author = subtitle.substring(0, cut);
          title = subtitle.substring(cut + 3);
        } else {
          title = subtitle;
        }
      }
      if (title.isEmpty) return const [];
      final cover = Uri.tryParse(localCoverUri(itemId));
      debugPrint('[AutoBrowse] Recent for media resumption: $key "$title"');
      return [
        MediaItem(
          id: AutoMediaIds.itemId(key),
          title: title,
          artist: author,
          album: title,
          artUri: cover,
          playable: true,
          extras: cover != null ? {'artUri': cover.toString()} : null,
        ),
      ];
    } catch (e) {
      debugPrint('[AutoBrowse] Recent for media resumption failed: $e');
      return const [];
    }
  }

  // ─── Lookup helpers ────────────────────────────────────────────────

  AutoBookEntry? findEntry(String absItemId) {
    for (final list in [_continueListening, _recentlyAdded, _downloaded]) {
      for (final entry in list) {
        if (entry.id == absItemId) return entry;
      }
    }
    return null;
  }

  MediaItem? getMediaItem(String mediaId) {
    final absId = AutoMediaIds.absItemId(mediaId);
    if (absId == null) return null;
    return findEntry(absId)?.toMediaItem();
  }
}