feat(auto): real metadata, quality sort and name buckets for local music [size:exception]

Local tracks now show embedded title/artist/album art (via native
MediaMetadataRetriever, cached through the existing FileProvider)
instead of the raw filename, falling back gracefully when a file
has no usable tags. Adds two navigable entry points per folder: sort
by audio quality (bitrate, capped at 150 tracks per folder to bound
worst-case latency) and alphabetical name buckets -- the closest
realistic form of "filtering" given Android Auto has no text-search
UI in this integration.

Metadata resolves only for the page actually being browsed (same
slice-cheap-then-map discipline as the paging change), backed by a
flat 256-entry LRU session cache that survives across pages. No new
permission, no new pub dependency, no l10n changes (car-tree labels
stay hardcoded Spanish, matching every existing label in the tree).

test/modelos/pista_local_test.dart

@@ -0,0 +1,88 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/modelos/pista_local.dart';
+
+void main() {
+  group('MetadatosPista', () {
+    test('todos los campos null: no lanza, todos los getters devuelven null', () {
+      const metadatos = MetadatosPista(
+        titulo: null,
+        artista: null,
+        artUri: null,
+        bitrate: null,
+        sampleRate: null,
+      );
+
+      expect(metadatos.titulo, isNull);
+      expect(metadatos.artista, isNull);
+      expect(metadatos.artUri, isNull);
+      expect(metadatos.bitrate, isNull);
+      expect(metadatos.sampleRate, isNull);
+    });
+
+    test('const constructor sin argumentos (todos por defecto null)', () {
+      const metadatos = MetadatosPista();
+
+      expect(metadatos.titulo, isNull);
+      expect(metadatos.artista, isNull);
+      expect(metadatos.artUri, isNull);
+      expect(metadatos.bitrate, isNull);
+      expect(metadatos.sampleRate, isNull);
+    });
+
+    test('todos los campos poblados se preservan tal cual', () {
+      const metadatos = MetadatosPista(
+        titulo: 'Cancion Genial',
+        artista: 'Artista X',
+        artUri: 'content://es.freetimelab.pluriwave.fileprovider/cache/pluriwave_art/abc',
+        bitrate: 320000,
+        sampleRate: 44100,
+      );
+
+      expect(metadatos.titulo, 'Cancion Genial');
+      expect(metadatos.artista, 'Artista X');
+      expect(
+        metadatos.artUri,
+        'content://es.freetimelab.pluriwave.fileprovider/cache/pluriwave_art/abc',
+      );
+      expect(metadatos.bitrate, 320000);
+      expect(metadatos.sampleRate, 44100);
+    });
+  });
+
+  group('PistaLocal', () {
+    test('campos extendidos (artista/embeddedArtUri/bitrate/sampleRate) son '
+        'opcionales y por defecto null', () {
+      const pista = PistaLocal(
+        documentId: 'doc1',
+        titulo: 'Titulo',
+        contentUri: 'content://provider/doc1',
+      );
+
+      expect(pista.artista, isNull);
+      expect(pista.embeddedArtUri, isNull);
+      expect(pista.bitrate, isNull);
+      expect(pista.sampleRate, isNull);
+    });
+
+    test('campos extendidos se preservan cuando se proveen', () {
+      const pista = PistaLocal(
+        documentId: 'doc1',
+        titulo: 'Titulo',
+        contentUri: 'content://provider/doc1',
+        artista: 'Artista X',
+        embeddedArtUri:
+            'content://es.freetimelab.pluriwave.fileprovider/cache/pluriwave_art/abc',
+        bitrate: 320000,
+        sampleRate: 44100,
+      );
+
+      expect(pista.artista, 'Artista X');
+      expect(
+        pista.embeddedArtUri,
+        'content://es.freetimelab.pluriwave.fileprovider/cache/pluriwave_art/abc',
+      );
+      expect(pista.bitrate, 320000);
+      expect(pista.sampleRate, 44100);
+    });
+  });
+}

test/servicios/musica_local_auto_test.dart

@@ -1,7 +1,168 @@
+import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/modelos/pista_local.dart';
 import 'package:pluriwave/servicios/musica_local_auto.dart';
+import 'package:shared_preferences/shared_preferences.dart';
 
 void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  group('CacheMetadatosSesion', () {
+    test(
+      'almacena hasta 256 entradas; la entrada 257 desaloja la '
+      'menos-recientemente-ACCEDIDA (no solo la menos recientemente '
+      'insertada)',
+      () {
+        final cache = CacheMetadatosSesion();
+
+        for (var i = 0; i < 256; i++) {
+          cache.guardar('doc-$i', MetadatosPista(titulo: 'T$i'));
+        }
+        expect(cache.obtener('doc-0'), isNotNull);
+
+        // Accede a doc-0 (la más vieja) para refrescar su recencia antes de
+        // insertar la entrada 257 — así doc-1 (no doc-0) debe ser la
+        // desalojada.
+        cache.obtener('doc-0');
+        cache.guardar('doc-256', const MetadatosPista(titulo: 'T256'));
+
+        expect(cache.obtener('doc-0'), isNotNull);
+        expect(cache.obtener('doc-1'), isNull);
+        expect(cache.obtener('doc-256'), isNotNull);
+      },
+    );
+
+    test(
+      'sin refrescar recencia: insertar la entrada 257 desaloja la '
+      'entrada 0 (la menos recientemente insertada Y accedida)',
+      () {
+        final cache = CacheMetadatosSesion();
+
+        for (var i = 0; i < 256; i++) {
+          cache.guardar('doc-$i', MetadatosPista(titulo: 'T$i'));
+        }
+        cache.guardar('doc-256', const MetadatosPista(titulo: 'T256'));
+
+        expect(cache.obtener('doc-0'), isNull);
+        expect(cache.obtener('doc-1'), isNotNull);
+        expect(cache.obtener('doc-256'), isNotNull);
+      },
+    );
+
+    test('obtener() en un miss devuelve null, sin lanzar', () {
+      final cache = CacheMetadatosSesion();
+
+      expect(cache.obtener('doc-inexistente'), isNull);
+    });
+
+    test('guardar() sobre una clave existente actualiza el valor', () {
+      final cache = CacheMetadatosSesion();
+
+      cache.guardar('doc-1', const MetadatosPista(titulo: 'Original'));
+      cache.guardar('doc-1', const MetadatosPista(titulo: 'Actualizado'));
+
+      expect(cache.obtener('doc-1')?.titulo, 'Actualizado');
+    });
+  });
+
+  group('FuenteMusicaLocalAutoImpl.metadatosDe', () {
+    const canal = MethodChannel('pluriwave/file_actions');
+
+    Future<SharedPreferences> prefsConCarpeta() async {
+      SharedPreferences.setMockInitialValues({
+        'musica_local_uri': 'content://tree/primary:Music',
+      });
+      return SharedPreferences.getInstance();
+    }
+
+    tearDown(() {
+      TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+          .setMockMethodCallHandler(canal, null);
+    });
+
+    test(
+      'documentIds vacío devuelve {} sin invocar el canal',
+      () async {
+        var llamadas = 0;
+        TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(canal, (call) async {
+          llamadas++;
+          return <Map<String, Object?>>[];
+        });
+
+        final fuente = FuenteMusicaLocalAutoImpl(prefs: await prefsConCarpeta());
+        final resultado = await fuente.metadatosDe(const []);
+
+        expect(resultado, isEmpty);
+        expect(llamadas, 0);
+      },
+    );
+
+    test(
+      'el canal lanzando una excepción degrada a {} en vez de propagar',
+      () async {
+        TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(canal, (call) async {
+          throw PlatformException(code: 'ERROR');
+        });
+
+        final fuente = FuenteMusicaLocalAutoImpl(prefs: await prefsConCarpeta());
+        final resultado = await fuente.metadatosDe(const ['doc-1']);
+
+        expect(resultado, isEmpty);
+      },
+    );
+
+    test(
+      'una fila nativa con campo null/faltante produce un MetadatosPista '
+      'con ese campo null, sin lanzar',
+      () async {
+        TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(canal, (call) async {
+          expect(call.method, 'readAudioMetadataBatch');
+          return [
+            {
+              'documentId': 'doc-1',
+              'titulo': null,
+              'artista': 'Artista',
+              'bitrate': null,
+              'sampleRate': null,
+              'artUri': null,
+            },
+          ];
+        });
+
+        final fuente = FuenteMusicaLocalAutoImpl(prefs: await prefsConCarpeta());
+        final resultado = await fuente.metadatosDe(const ['doc-1']);
+
+        expect(resultado, hasLength(1));
+        expect(resultado['doc-1']?.titulo, isNull);
+        expect(resultado['doc-1']?.artista, 'Artista');
+        expect(resultado['doc-1']?.bitrate, isNull);
+      },
+    );
+
+    test(
+      'sin carpeta persistida devuelve {} sin invocar el canal',
+      () async {
+        SharedPreferences.setMockInitialValues({});
+        var llamadas = 0;
+        TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+            .setMockMethodCallHandler(canal, (call) async {
+          llamadas++;
+          return <Map<String, Object?>>[];
+        });
+
+        final fuente = FuenteMusicaLocalAutoImpl(
+          prefs: await SharedPreferences.getInstance(),
+        );
+        final resultado = await fuente.metadatosDe(const ['doc-1']);
+
+        expect(resultado, isEmpty);
+        expect(llamadas, 0);
+      },
+    );
+  });
   group('esArchivoAudio', () {
     test('acepta cualquier MIME audio/*, en cualquier capitalización', () {
       expect(esArchivoAudio('audio/mpeg', 'cancion.mp3'), isTrue);