feat(iap): add freemium unlock via one-time in-app purchase

Adds a permanent, non-consumable premium unlock (EstadoEntitlement +
PuertoCompras/ServicioComprasPlayBilling) that removes ads and unlocks
alarm vacations, alarms past a 5-alarm free cap, recording start, and
full Android Auto browsing. The phone equalizer stays free for everyone.

- Entitlement is prefs-backed (compra_premium_v1), fail-open, and
  resolvable headlessly via esPremiumPersistido() for the Android Auto
  audio handler, which registers before runApp.
- Android Auto reduced mode keeps the real root folder labels for free
  users; browsing into any of them (and playFromMediaId/playFromSearch/
  skipToNext/skipToPrevious) is blocked at the getChildren/servicio_audio
  choke points, with a locked "Función Premium" item as the backstop.
  Current-station play/pause/stop stays untouched. A free -> premium
  transition actively invalidates the head unit's cached browse tree.
- Ads (top banner + capped interstitial before adding a station or an
  alarm) are gated behind entitlement via ServicioAnuncios, using
  official Google test ad unit IDs pending AdMob provisioning.
- Alarm cap UX shows an explanatory message with a secondary unlock
  action rather than a bare paywall jump; existing data is grandfathered.
- 4 new localization keys translated across all 13 supported locales.

Co-located tests use strict TDD (RED test before implementation) for
every new pure-logic unit; full existing suite passes unchanged.

test/servicios/navegacion_auto_gating_test.dart

@@ -0,0 +1,106 @@
+import 'package:audio_service/audio_service.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/servicios/navegacion_auto.dart';
+
+/// Android Auto entitlement gating (android-auto-media spec "Free-Tier
+/// Reduced Root Browse" + "Free-Tier Browse Never Leaks Real Content",
+/// design.md ADR-4). All pure — no handler instantiation needed
+/// (`PluriWaveAudioHandler` cannot be constructed in a unit test).
+void main() {
+  group('raiz(premium:) — root keeps its labels for every tier', () {
+    test('premium: identical to today\'s tree (regression guard)', () {
+      final constructor = ConstructorArbolAuto();
+
+      final premiumConLocal = constructor.raiz(
+        incluirMusicaLocal: true,
+        premium: true,
+      );
+      final premiumSinLocal = constructor.raiz(
+        incluirMusicaLocal: false,
+        premium: true,
+      );
+
+      expect(premiumConLocal.map((m) => m.id), [
+        ConstructorArbolAuto.idFavoritos,
+        ConstructorArbolAuto.idTodas,
+        ConstructorArbolAuto.idMisEmisoras,
+        ConstructorArbolAuto.idMusicaLocal,
+      ]);
+      expect(premiumConLocal.every((m) => m.playable == false), isTrue);
+      expect(premiumConLocal.every((m) => m.displaySubtitle == null), isTrue);
+      expect(premiumSinLocal.map((m) => m.id), [
+        ConstructorArbolAuto.idFavoritos,
+        ConstructorArbolAuto.idTodas,
+        ConstructorArbolAuto.idMisEmisoras,
+      ]);
+    });
+
+    test('free: same folder ids/titles, non-blank, never playable', () {
+      final constructor = ConstructorArbolAuto();
+
+      final libre = constructor.raiz(incluirMusicaLocal: true, premium: false);
+
+      expect(libre, isNotEmpty);
+      expect(libre.map((m) => m.id), [
+        ConstructorArbolAuto.idFavoritos,
+        ConstructorArbolAuto.idTodas,
+        ConstructorArbolAuto.idMisEmisoras,
+        ConstructorArbolAuto.idMusicaLocal,
+      ]);
+      expect(libre.every((m) => m.playable == false), isTrue);
+    });
+  });
+
+  test(
+    'itemPremiumBloqueado(): id fijo, no reproducible, etiqueta premium',
+    () {
+      final item = ConstructorArbolAuto().itemPremiumBloqueado();
+
+      expect(item.id, 'premium:info');
+      expect(item.playable, isFalse);
+      expect(item.title, isNotEmpty);
+    },
+  );
+
+  group('respuestaBloqueadaPorEntitlement — backstop de navegacion', () {
+    test('root nunca es bloqueada (root siempre resuelve via raiz)', () {
+      final respuesta = respuestaBloqueadaPorEntitlement(
+        parentMediaId: AudioService.browsableRootId,
+        premium: false,
+      );
+
+      expect(respuesta, isNull);
+    });
+
+    test('cualquier id no-root, en free, retorna SOLO el item bloqueado', () {
+      for (final id in [
+        ConstructorArbolAuto.idFavoritos,
+        ConstructorArbolAuto.idTodas,
+        ConstructorArbolAuto.idMisEmisoras,
+        ConstructorArbolAuto.idMusicaLocal,
+        ConstructorArbolAuto.idEcualizador,
+        // Stale/deep-linked id from before a downgrade — the backstop must
+        // not special-case known ids (Spec "Stale folder id bypass
+        // attempt").
+        'emisora:algun-uuid-viejo',
+        'grupo:algo',
+      ]) {
+        final respuesta = respuestaBloqueadaPorEntitlement(
+          parentMediaId: id,
+          premium: false,
+        );
+        expect(respuesta, hasLength(1));
+        expect(respuesta!.single.id, 'premium:info');
+      }
+    });
+
+    test('cualquier id no-root, en premium, no es bloqueada', () {
+      final respuesta = respuestaBloqueadaPorEntitlement(
+        parentMediaId: ConstructorArbolAuto.idFavoritos,
+        premium: true,
+      );
+
+      expect(respuesta, isNull);
+    });
+  });
+}

test/servicios/navegacion_auto_test.dart

@@ -240,7 +240,10 @@ void main() {
   group('ConstructorArbolAuto.raiz', () {
     test('con incluirMusicaLocal: true devuelve exactamente 4 carpetas no '
         'reproducibles con los ids esperados', () {
-      final raiz = ConstructorArbolAuto().raiz(incluirMusicaLocal: true);
+      final raiz = ConstructorArbolAuto().raiz(
+        incluirMusicaLocal: true,
+        premium: true,
+      );
 
       expect(raiz, hasLength(4));
       final ids = raiz.map((item) => item.id).toSet();
@@ -262,7 +265,10 @@ void main() {
 
     test('con incluirMusicaLocal: false devuelve exactamente 3 carpetas — '
         'Música Local queda OCULTA, no vacía', () {
-      final raiz = ConstructorArbolAuto().raiz(incluirMusicaLocal: false);
+      final raiz = ConstructorArbolAuto().raiz(
+        incluirMusicaLocal: false,
+        premium: true,
+      );
 
       expect(raiz, hasLength(3));
       final ids = raiz.map((item) => item.id).toSet();
@@ -286,7 +292,7 @@ void main() {
         'segunda vuelta de la misma decisión con evidencia real de uso', () {
       final ids =
           ConstructorArbolAuto()
-              .raiz(incluirMusicaLocal: true)
+              .raiz(incluirMusicaLocal: true, premium: true)
               .map((item) => item.id)
               .toList();
 

test/servicios/servicio_anuncios_test.dart

@@ -0,0 +1,107 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
+
+/// Ad-display spec: session-scoped interstitial frequency cap (max 2 per
+/// process lifetime, >=3 min apart), suppressed entirely for premium, and
+/// never shown when the caller reports the alarm-cap message took
+/// precedence for this same tap.
+void main() {
+  ServicioAnuncios construir({
+    required DateTime Function() ahora,
+    required bool premium,
+    Future<bool> Function()? mostrarInterstitialImpl,
+  }) => ServicioAnuncios(
+    ahora: ahora,
+    esPremium: () => premium,
+    mostrarInterstitialImpl: mostrarInterstitialImpl ?? (() async => true),
+  );
+
+  group('intentarInterstitial — cap de frecuencia', () {
+    test('primeros 2 intentos en la sesion se muestran', () async {
+      var ahora = DateTime(2026, 1, 1, 10, 0);
+      final servicio = construir(ahora: () => ahora, premium: false);
+
+      expect(await servicio.intentarInterstitial(), isTrue);
+      ahora = ahora.add(const Duration(minutes: 5));
+      expect(await servicio.intentarInterstitial(), isTrue);
+    });
+
+    test('un 3er intento en la misma sesion no se muestra (cap 2)', () async {
+      var ahora = DateTime(2026, 1, 1, 10, 0);
+      final servicio = construir(ahora: () => ahora, premium: false);
+
+      await servicio.intentarInterstitial();
+      ahora = ahora.add(const Duration(minutes: 5));
+      await servicio.intentarInterstitial();
+      ahora = ahora.add(const Duration(minutes: 5));
+
+      expect(await servicio.intentarInterstitial(), isFalse);
+    });
+
+    test('menos de 3 minutos desde el ultimo: no se muestra', () async {
+      var ahora = DateTime(2026, 1, 1, 10, 0);
+      final servicio = construir(ahora: () => ahora, premium: false);
+
+      await servicio.intentarInterstitial();
+      ahora = ahora.add(const Duration(minutes: 1));
+
+      expect(await servicio.intentarInterstitial(), isFalse);
+    });
+
+    test('exactamente 3 minutos despues si se muestra', () async {
+      var ahora = DateTime(2026, 1, 1, 10, 0);
+      final servicio = construir(ahora: () => ahora, premium: false);
+
+      await servicio.intentarInterstitial();
+      ahora = ahora.add(const Duration(minutes: 3));
+
+      expect(await servicio.intentarInterstitial(), isTrue);
+    });
+
+    test('premium: nunca muestra interstitial', () async {
+      final servicio = construir(
+        ahora: () => DateTime(2026, 1, 1, 10, 0),
+        premium: true,
+      );
+
+      expect(await servicio.intentarInterstitial(), isFalse);
+    });
+
+    test(
+      'el conteo/temporizador solo avanza si el ad realmente se muestra',
+      () async {
+        final ahora = DateTime(2026, 1, 1, 10, 0);
+        final servicio = construir(
+          ahora: () => ahora,
+          premium: false,
+          mostrarInterstitialImpl: () async => false,
+        );
+
+        final mostrado = await servicio.intentarInterstitial();
+
+        expect(mostrado, isFalse);
+        // Un fallo de carga (mostrarInterstitialImpl -> false) no debe
+        // consumir el cupo de la sesion.
+        expect(await servicio.intentarInterstitial(), isFalse);
+      },
+    );
+  });
+
+  group('debeMostrarBanner', () {
+    test('free: true', () {
+      final servicio = construir(
+        ahora: () => DateTime(2026, 1, 1),
+        premium: false,
+      );
+      expect(servicio.debeMostrarBanner, isTrue);
+    });
+
+    test('premium: false', () {
+      final servicio = construir(
+        ahora: () => DateTime(2026, 1, 1),
+        premium: true,
+      );
+      expect(servicio.debeMostrarBanner, isFalse);
+    });
+  });
+}

test/servicios/servicio_audio_gating_test.dart

@@ -0,0 +1,38 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/servicios/servicio_audio.dart';
+
+/// Android Auto play-path backstop (design.md ADR-4, android-auto-media
+/// spec "Free-Tier Browse Never Leaks Real Content" + "Current-Station
+/// Playback Unaffected By Free Tier"): `playFromMediaId`, `playFromSearch`,
+/// `skipToNext`, `skipToPrevious` must ALL no-op for a free-tier user,
+/// regardless of the target id — gating `getChildren` alone is
+/// insufficient because a head unit caches browse trees, so a stale
+/// `emisora:<uuid>` tap could otherwise bypass browsing entirely. Pure —
+/// `PluriWaveAudioHandler` cannot be instantiated in a unit test (needs a
+/// real platform `AudioPlayer`), so this is the extracted decision the
+/// handler's dispatch methods delegate to (mirrors `mapearEstadoProceso`
+/// and every other pure helper in this file).
+void main() {
+  test('free tier: bloquea cualquier cambio de emisora/salto', () {
+    expect(debeBloquearCambioDeEmisora(premium: false), isTrue);
+  });
+
+  test('premium: nunca bloquea', () {
+    expect(debeBloquearCambioDeEmisora(premium: true), isFalse);
+  });
+
+  group('notificarDesbloqueoAuto / registrarNotificacionDesbloqueoAuto', () {
+    test('sin hook registrado, es un no-op seguro', () {
+      expect(() => notificarDesbloqueoAuto(), returnsNormally);
+    });
+
+    test('invoca el hook registrado exactamente una vez por llamada', () {
+      var llamadas = 0;
+      registrarNotificacionDesbloqueoAuto(() => llamadas++);
+
+      notificarDesbloqueoAuto();
+
+      expect(llamadas, 1);
+    });
+  });
+}

test/servicios/servicio_compras_test.dart

@@ -0,0 +1,56 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:in_app_purchase/in_app_purchase.dart';
+import 'package:pluriwave/servicios/servicio_compras.dart';
+
+/// Pure port-boundary tests (Design ADR-2 "keeps Strict TDD viable with zero
+/// plugin channels in unit tests"): [eventoDesdeEstadoCompra] is the ONLY
+/// piece of `ServicioComprasPlayBilling` that is unit-testable without a
+/// real `in_app_purchase` platform channel — [ServicioComprasPlayBilling]
+/// itself is the sole call site (Design ADR-2), exercised instead through
+/// `EstadoEntitlement` + a fake `PuertoCompras`
+/// (`estado_entitlement_test.dart`).
+void main() {
+  group('eventoDesdeEstadoCompra', () {
+    test('purchased -> comprada', () {
+      expect(
+        eventoDesdeEstadoCompra(PurchaseStatus.purchased).tipo,
+        TipoEventoCompra.comprada,
+      );
+    });
+
+    test('restored -> restaurada', () {
+      expect(
+        eventoDesdeEstadoCompra(PurchaseStatus.restored).tipo,
+        TipoEventoCompra.restaurada,
+      );
+    });
+
+    test('canceled -> cancelada', () {
+      expect(
+        eventoDesdeEstadoCompra(PurchaseStatus.canceled).tipo,
+        TipoEventoCompra.cancelada,
+      );
+    });
+
+    test('pending -> pendiente', () {
+      expect(
+        eventoDesdeEstadoCompra(PurchaseStatus.pending).tipo,
+        TipoEventoCompra.pendiente,
+      );
+    });
+
+    test('error conserva el mensaje diagnostico', () {
+      final evento = eventoDesdeEstadoCompra(
+        PurchaseStatus.error,
+        mensaje: 'BILLING_UNAVAILABLE',
+      );
+
+      expect(evento.tipo, TipoEventoCompra.error);
+      expect(evento.mensaje, 'BILLING_UNAVAILABLE');
+    });
+  });
+
+  test('idProducto es el identificador unico no-consumible', () {
+    expect(ServicioComprasPlayBilling.idProducto, 'pluriwave_premium');
+  });
+}