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/estado/estado_alarmas_gating_test.dart

@@ -0,0 +1,180 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/estado/estado_alarmas.dart';
+import 'package:pluriwave/modelos/alarma_musical.dart';
+import 'package:pluriwave/servicios/servicio_alarmas.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../helpers/fakes_alarmas.dart';
+
+/// Freemium gating (freemium-gating spec, design ADR-3/ADR-5): the 5-alarm
+/// cap for free-tier users, grandfathering of pre-existing alarms, and the
+/// full premium gate on vacation-range creation. `EstadoAlarmas`'s existing
+/// suite constructs it with NO `esPremium` callback and expects unrestricted
+/// behavior — the default therefore stays `() => true` (ungated) so every
+/// one of those tests keeps passing unchanged; only tests here explicitly
+/// inject `esPremium: () => false` to exercise the free tier.
+AlarmaMusical _alarma(String id, {bool activa = true}) => AlarmaMusical(
+  id: id,
+  nombre: 'Alarma $id',
+  hora: 7,
+  minuto: 0,
+  tipoProgramacion: TipoProgramacionAlarma.diaria,
+  diasSemana: const [],
+  activa: activa,
+);
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  setUp(() {
+    SharedPreferences.setMockInitialValues({});
+  });
+
+  EstadoAlarmas construir({required bool premium}) {
+    final android = FakePuertoAlarmasAndroid();
+    final estado = EstadoAlarmas(
+      servicio: ServicioAlarmas(reloj: () => DateTime(2026, 5, 25, 7)),
+      android: android,
+      iniciarAutomaticamente: false,
+      esPremium: () => premium,
+    );
+    addTearDown(estado.dispose);
+    addTearDown(android.dispose);
+    return estado;
+  }
+
+  group('puedeCrearAlarma / cap de 5 (free tier)', () {
+    test('con 4 alarmas puede crear una mas', () async {
+      final estado = construir(premium: false);
+      for (var i = 1; i <= 4; i++) {
+        await estado.guardarAlarma(_alarma('a$i'));
+      }
+
+      expect(estado.puedeCrearAlarma(), isTrue);
+    });
+
+    test(
+      'con 5 alarmas (cualquier estado activa) no puede crear una 6a',
+      () async {
+        final estado = construir(premium: false);
+        for (var i = 1; i <= 4; i++) {
+          await estado.guardarAlarma(_alarma('a$i'));
+        }
+        await estado.guardarAlarma(_alarma('a5', activa: false));
+
+        expect(estado.puedeCrearAlarma(), isFalse);
+      },
+    );
+
+    test('la 6a alarma es bloqueada ANTES de programar en Android', () async {
+      final estado = construir(premium: false);
+      for (var i = 1; i <= 5; i++) {
+        await estado.guardarAlarma(_alarma('a$i'));
+      }
+      final android = estado.android as FakePuertoAlarmasAndroid;
+      final programadasPrevias = android.programadas.length;
+
+      final resultado = await estado.guardarAlarma(_alarma('a6'));
+
+      expect(resultado, ResultadoGuardarAlarma.limiteAlcanzado);
+      expect(estado.alarmas.length, 5);
+      expect(android.programadas.length, programadasPrevias);
+    });
+
+    test('editar una de las 5 alarmas existentes sigue funcionando', () async {
+      final estado = construir(premium: false);
+      for (var i = 1; i <= 5; i++) {
+        await estado.guardarAlarma(_alarma('a$i'));
+      }
+
+      final resultado = await estado.guardarAlarma(
+        _alarma('a3').copyWith(hora: 8),
+      );
+
+      expect(resultado, ResultadoGuardarAlarma.guardada);
+      expect(estado.alarmas.firstWhere((a) => a.id == 'a3').hora, 8);
+    });
+
+    test('usuario premium no tiene tope', () async {
+      final estado = construir(premium: true);
+      for (var i = 1; i <= 5; i++) {
+        await estado.guardarAlarma(_alarma('a$i'));
+      }
+
+      final resultado = await estado.guardarAlarma(_alarma('a6'));
+
+      expect(resultado, ResultadoGuardarAlarma.guardada);
+      expect(estado.alarmas.length, 6);
+      expect(estado.puedeCrearAlarma(), isTrue);
+    });
+
+    test(
+      'grandfathering: 8 alarmas preexistentes siguen funcionando, solo se bloquea la 9a',
+      () async {
+        // Simula alarmas ya persistidas antes de que el gate existiera:
+        // se crean en modo premium (sin tope) y luego se re-evalua en free.
+        final estadoPremium = construir(premium: true);
+        for (var i = 1; i <= 8; i++) {
+          await estadoPremium.guardarAlarma(_alarma('g$i'));
+        }
+        expect(estadoPremium.alarmas.length, 8);
+
+        // Editar una de las 8 preexistentes en free tier sigue funcionando.
+        final estadoFree = EstadoAlarmas(
+          servicio: estadoPremium.servicio,
+          android: estadoPremium.android,
+          iniciarAutomaticamente: false,
+          esPremium: () => false,
+        );
+        addTearDown(estadoFree.dispose);
+        await estadoFree.cargarPersistidasSinRecalcular();
+        expect(estadoFree.alarmas.length, 8);
+
+        final edicion = await estadoFree.guardarAlarma(
+          estadoFree.alarmas.first.copyWith(hora: 9),
+        );
+        expect(edicion, ResultadoGuardarAlarma.guardada);
+        expect(estadoFree.alarmas.length, 8);
+
+        // Una 9a alarma NUEVA sigue bloqueada.
+        final resultado = await estadoFree.guardarAlarma(_alarma('g9'));
+        expect(resultado, ResultadoGuardarAlarma.limiteAlcanzado);
+        expect(estadoFree.alarmas.length, 8);
+      },
+    );
+  });
+
+  group('crearRangoVacaciones — gate completo (freemium-gating)', () {
+    test('free tier: cualquier creacion de vacaciones es bloqueada', () async {
+      final estado = construir(premium: false);
+
+      final creada = await estado.crearRangoVacaciones(
+        RangoVacaciones(
+          id: 'v1',
+          nombre: 'Verano',
+          inicio: DateTime(2026, 7, 1),
+          fin: DateTime(2026, 7, 15),
+        ),
+      );
+
+      expect(creada, isFalse);
+      expect(estado.vacaciones, isEmpty);
+    });
+
+    test('premium: crea vacaciones sin restriccion', () async {
+      final estado = construir(premium: true);
+
+      final creada = await estado.crearRangoVacaciones(
+        RangoVacaciones(
+          id: 'v1',
+          nombre: 'Verano',
+          inicio: DateTime(2026, 7, 1),
+          fin: DateTime(2026, 7, 15),
+        ),
+      );
+
+      expect(creada, isTrue);
+      expect(estado.vacaciones, hasLength(1));
+    });
+  });
+}

test/estado/estado_entitlement_test.dart

@@ -0,0 +1,209 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
+import 'package:pluriwave/servicios/servicio_compras.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// Fake [PuertoCompras] (Design ADR-2): never touches `in_app_purchase`,
+/// lets each test drive [emitir] to simulate the purchase stream.
+class _PuertoComprasFalso implements PuertoCompras {
+  final _eventos = StreamController<EventoCompra>.broadcast();
+  int comprasIntentadas = 0;
+  int restaurosIntentados = 0;
+
+  @override
+  Stream<EventoCompra> get eventos => _eventos.stream;
+
+  @override
+  Future<void> comprar() async {
+    comprasIntentadas++;
+  }
+
+  @override
+  Future<void> restaurar() async {
+    restaurosIntentados++;
+  }
+
+  void emitir(EventoCompra evento) => _eventos.add(evento);
+
+  Future<void> dispose() => _eventos.close();
+}
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  setUp(() {
+    SharedPreferences.setMockInitialValues({});
+  });
+
+  group('EstadoEntitlement', () {
+    test('por defecto es free (sin flag persistida)', () async {
+      final estado = EstadoEntitlement(
+        prefs: await SharedPreferences.getInstance(),
+      );
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isFalse);
+    });
+
+    test('carga premium desde una flag persistida previamente', () async {
+      SharedPreferences.setMockInitialValues({'compra_premium_v1': true});
+      final estado = EstadoEntitlement(
+        prefs: await SharedPreferences.getInstance(),
+      );
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isTrue);
+    });
+
+    test('comprar() con éxito desbloquea premium y persiste', () async {
+      final compras = _PuertoComprasFalso();
+      addTearDown(compras.dispose);
+      final prefs = await SharedPreferences.getInstance();
+      final estado = EstadoEntitlement(prefs: prefs, compras: compras);
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      var notificaciones = 0;
+      estado.addListener(() => notificaciones++);
+
+      unawaited(estado.comprar());
+      await Future<void>.delayed(Duration.zero);
+      compras.emitir(const EventoCompra(TipoEventoCompra.comprada));
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isTrue);
+      expect(estado.compraEnCurso, isFalse);
+      expect(compras.comprasIntentadas, 1);
+      expect(prefs.getBool('compra_premium_v1'), isTrue);
+      expect(notificaciones, greaterThan(0));
+    });
+
+    test('comprar() cancelada deja el tier free sin cargo', () async {
+      final compras = _PuertoComprasFalso();
+      addTearDown(compras.dispose);
+      final estado = EstadoEntitlement(
+        prefs: await SharedPreferences.getInstance(),
+        compras: compras,
+      );
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      unawaited(estado.comprar());
+      await Future<void>.delayed(Duration.zero);
+      compras.emitir(const EventoCompra(TipoEventoCompra.cancelada));
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isFalse);
+      expect(estado.compraEnCurso, isFalse);
+    });
+
+    test(
+      'comprar() ya premium es idempotente: no reintenta la compra',
+      () async {
+        SharedPreferences.setMockInitialValues({'compra_premium_v1': true});
+        final compras = _PuertoComprasFalso();
+        addTearDown(compras.dispose);
+        final estado = EstadoEntitlement(
+          prefs: await SharedPreferences.getInstance(),
+          compras: compras,
+        );
+        addTearDown(estado.dispose);
+        await Future<void>.delayed(Duration.zero);
+
+        await estado.comprar();
+
+        expect(compras.comprasIntentadas, 0);
+        expect(estado.esPremium, isTrue);
+      },
+    );
+
+    test('restaurar() encuentra una compra y desbloquea premium', () async {
+      final compras = _PuertoComprasFalso();
+      addTearDown(compras.dispose);
+      final estado = EstadoEntitlement(
+        prefs: await SharedPreferences.getInstance(),
+        compras: compras,
+      );
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      unawaited(estado.restaurar());
+      await Future<void>.delayed(Duration.zero);
+      compras.emitir(const EventoCompra(TipoEventoCompra.restaurada));
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isTrue);
+      expect(compras.restaurosIntentados, 1);
+    });
+
+    test('restaurar() sin compra previa mantiene free sin error', () async {
+      final compras = _PuertoComprasFalso();
+      addTearDown(compras.dispose);
+      final estado = EstadoEntitlement(
+        prefs: await SharedPreferences.getInstance(),
+        compras: compras,
+      );
+      addTearDown(estado.dispose);
+      await Future<void>.delayed(Duration.zero);
+
+      unawaited(estado.restaurar());
+      await Future<void>.delayed(Duration.zero);
+      compras.emitir(const EventoCompra(TipoEventoCompra.noEncontrada));
+      await Future<void>.delayed(Duration.zero);
+
+      expect(estado.esPremium, isFalse);
+      expect(estado.compraEnCurso, isFalse);
+    });
+
+    test(
+      'un error en el flujo de compra no bloquea al pagador (fail-open)',
+      () async {
+        final compras = _PuertoComprasFalso();
+        addTearDown(compras.dispose);
+        final estado = EstadoEntitlement(
+          prefs: await SharedPreferences.getInstance(),
+          compras: compras,
+        );
+        addTearDown(estado.dispose);
+        await Future<void>.delayed(Duration.zero);
+
+        unawaited(estado.comprar());
+        await Future<void>.delayed(Duration.zero);
+        compras.emitir(const EventoCompra(TipoEventoCompra.error));
+        await Future<void>.delayed(Duration.zero);
+
+        // Fail-open: un error NUNCA escribe `false` sobre una flag ya premium,
+        // y tampoco inventa un `true` para un usuario free.
+        expect(estado.esPremium, isFalse);
+      },
+    );
+  });
+
+  group('esPremiumPersistido (headless, sin BuildContext)', () {
+    test('lee la flag persistida directamente desde prefs', () async {
+      SharedPreferences.setMockInitialValues({'compra_premium_v1': true});
+      final prefs = await SharedPreferences.getInstance();
+
+      expect(await esPremiumPersistido(prefs: prefs), isTrue);
+    });
+
+    test('por defecto (sin flag) resuelve a free', () async {
+      final prefs = await SharedPreferences.getInstance();
+
+      expect(await esPremiumPersistido(prefs: prefs), isFalse);
+    });
+
+    test(
+      'resuelve sin prefs inyectadas (SharedPreferences.getInstance)',
+      () async {
+        SharedPreferences.setMockInitialValues({'compra_premium_v1': true});
+
+        expect(await esPremiumPersistido(), isTrue);
+      },
+    );
+  });
+}

test/estado/estado_grabacion_gating_test.dart

@@ -0,0 +1,95 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/estado/estado_grabacion.dart';
+import 'package:pluriwave/modelos/emisora.dart';
+import 'package:pluriwave/servicios/servicio_grabacion_radio.dart';
+
+import '../helpers/fakes.dart';
+
+/// Freemium gating (freemium-gating spec "Recording Start Gated, Management
+/// Stays Free"): starting a NEW recording requires premium; management of
+/// already-existing recordings (listing/playing/deleting — untouched by
+/// this file) stays free regardless.
+void main() {
+  test(
+    'free tier: iniciar() no llama al servicio y reporta requierePremium',
+    () async {
+      final servicio = _ServicioGrabacionControlado();
+      final emisora = emisoraDemo(uuid: 'rec-1', nombre: 'Grabable');
+      final estado = EstadoGrabacion(
+        servicio: servicio,
+        emisoraActual: () => emisora,
+        esPremium: () => false,
+      );
+      addTearDown(estado.dispose);
+
+      final resultado = await estado.iniciar();
+
+      expect(resultado, ResultadoIniciarGrabacion.requierePremium);
+      expect(servicio.inicios, 0);
+    },
+  );
+
+  test('premium: iniciar() delega en el servicio normalmente', () async {
+    final servicio = _ServicioGrabacionControlado();
+    final emisora = emisoraDemo(uuid: 'rec-2', nombre: 'Grabable');
+    final estado = EstadoGrabacion(
+      servicio: servicio,
+      emisoraActual: () => emisora,
+      esPremium: () => true,
+    );
+    addTearDown(estado.dispose);
+
+    final resultado = await estado.iniciar(
+      duracion: const Duration(minutes: 1),
+    );
+
+    expect(resultado, ResultadoIniciarGrabacion.iniciada);
+    expect(servicio.inicios, 1);
+  });
+
+  test('sin callback de entitlement, el default no bloquea (compat)', () async {
+    final servicio = _ServicioGrabacionControlado();
+    final emisora = emisoraDemo(uuid: 'rec-3', nombre: 'Grabable');
+    final estado = EstadoGrabacion(
+      servicio: servicio,
+      emisoraActual: () => emisora,
+    );
+    addTearDown(estado.dispose);
+
+    final resultado = await estado.iniciar();
+
+    expect(resultado, ResultadoIniciarGrabacion.iniciada);
+    expect(servicio.inicios, 1);
+  });
+}
+
+class _ServicioGrabacionControlado extends ServicioGrabacionRadio {
+  final _controller = StreamController<EstadoGrabacionRadio>.broadcast();
+  final EstadoGrabacionRadio _estadoActual =
+      const EstadoGrabacionRadio.inactiva();
+
+  int inicios = 0;
+
+  @override
+  EstadoGrabacionRadio get estado => _estadoActual;
+
+  @override
+  Stream<EstadoGrabacionRadio> get estadoStream => _controller.stream;
+
+  @override
+  Future<void> inicializar() async {}
+
+  @override
+  Future<void> iniciar(
+    Emisora emisora, {
+    Duration? duracion,
+    String? directorio,
+  }) async {
+    inicios++;
+  }
+
+  @override
+  Future<void> dispose() => _controller.close();
+}

test/l10n/identical_value_allowlist.dart

@@ -276,4 +276,14 @@ const Set<(String locale, String key)> identicalValueAllowlist = {
     'pt',
     'alarmDiagnosticsManufacturerLabel',
   ), // fix/alarmas-fiabilidad new key -- "Fabricante" is identical in pt/es
+  (
+    'pt',
+    'desbloquearPremium',
+  ), // iap-freemium-unlock new key -- "Desbloquear" is identical in pt/es and
+  // "Premium" is an untranslated product tier name in both.
+  (
+    'pt',
+    'restaurarCompras',
+  ), // iap-freemium-unlock new key -- "Restaurar compras" is the standard
+  // Portuguese store wording and coincides with es word for word.
 };

test/pantallas/ajustes/pantalla_ajustes_emisoras_personalizadas_test.dart

@@ -5,6 +5,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
 import 'package:pluriwave/l10n/gen/app_localizations.dart';
 import 'package:pluriwave/pantallas/ajustes/pantalla_ajustes_emisoras_personalizadas.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
 import 'package:pluriwave/widgets/pluri_push_scaffold.dart';
 import 'package:provider/provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -87,8 +88,13 @@ void main() {
   }
 
   Widget buildScreen(EstadoRadio estado) {
-    return ChangeNotifierProvider<EstadoRadio>.value(
-      value: estado,
+    return MultiProvider(
+      providers: [
+        ChangeNotifierProvider<EstadoRadio>.value(value: estado),
+        Provider<ServicioAnuncios>(
+          create: (_) => ServicioAnuncios(esPremium: () => true),
+        ),
+      ],
       child: MaterialApp(
         locale: const Locale('en'),
         localizationsDelegates: AppLocalizations.localizationsDelegates,

test/pantallas/pantalla_ajustes_row_values_test.dart

@@ -4,6 +4,7 @@ import 'dart:io';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_ecualizador.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
 import 'package:pluriwave/estado/estado_grabacion.dart';
 import 'package:pluriwave/estado/estado_idioma.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
@@ -104,6 +105,9 @@ void main() {
         ListenableProvider<EstadoEcualizador>.value(value: estado.ecualizador),
         ListenableProvider<EstadoGrabacion>.value(value: estado.grabacion),
         ChangeNotifierProvider<EstadoIdioma>.value(value: idioma),
+        ChangeNotifierProvider<EstadoEntitlement>(
+          create: (_) => EstadoEntitlement(prefs: null),
+        ),
       ],
       child: MaterialApp(
         locale: const Locale('en'),

test/pantallas/pantalla_ajustes_test.dart

@@ -4,6 +4,7 @@ import 'dart:io';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_ecualizador.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
 import 'package:pluriwave/estado/estado_grabacion.dart';
 import 'package:pluriwave/estado/estado_idioma.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
@@ -50,6 +51,9 @@ void main() {
         ListenableProvider<EstadoEcualizador>.value(value: estado.ecualizador),
         ListenableProvider<EstadoGrabacion>.value(value: estado.grabacion),
         ChangeNotifierProvider<EstadoIdioma>.value(value: estadoIdioma),
+        ChangeNotifierProvider<EstadoEntitlement>(
+          create: (_) => EstadoEntitlement(prefs: null),
+        ),
       ],
       child: MaterialApp(
         locale: const Locale('en'),

test/pantallas/pantalla_alarmas_fecha_test.dart

@@ -9,6 +9,7 @@ import 'package:pluriwave/l10n/gen/app_localizations.dart';
 import 'package:pluriwave/modelos/alarma_musical.dart';
 import 'package:pluriwave/pantallas/pantalla_alarmas.dart';
 import 'package:pluriwave/servicios/servicio_alarmas.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
 import 'package:provider/provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
@@ -78,6 +79,9 @@ void main() {
           providers: [
             ChangeNotifierProvider<EstadoRadio>.value(value: radio),
             ChangeNotifierProvider<EstadoAlarmas>.value(value: estadoAlarmas),
+            Provider<ServicioAnuncios>(
+              create: (_) => ServicioAnuncios(esPremium: () => true),
+            ),
           ],
           child: MaterialApp(
             locale: const Locale('es'),

test/pantallas/pantalla_favoritos_test.dart

@@ -6,6 +6,7 @@ import 'package:pluriwave/estado/estado_radio.dart';
 import 'package:pluriwave/l10n/gen/app_localizations.dart';
 import 'package:pluriwave/pantallas/ajustes/pantalla_ajustes_grupos_favoritos.dart';
 import 'package:pluriwave/pantallas/pantalla_favoritos.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
 import 'package:pluriwave/widgets/fila_emisora_plana.dart';
 import 'package:pluriwave/widgets/pluri_layout.dart';
 import 'package:pluriwave/widgets/pluri_push_scaffold.dart';
@@ -88,8 +89,13 @@ void main() {
     // gives root screens (which construct zero Scaffold themselves, per
     // ADR-2) a Material ancestor. Without it, Material components like
     // ChoiceChip/PopupMenuButton/ActionChip fail to find one.
-    return ChangeNotifierProvider<EstadoRadio>.value(
-      value: estado,
+    return MultiProvider(
+      providers: [
+        ChangeNotifierProvider<EstadoRadio>.value(value: estado),
+        Provider<ServicioAnuncios>(
+          create: (_) => ServicioAnuncios(esPremium: () => true),
+        ),
+      ],
       child: MaterialApp(
         locale: const Locale('en'),
         localizationsDelegates: AppLocalizations.localizationsDelegates,

test/pantallas/pluri_screen_header_retired_test.dart

@@ -5,6 +5,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_alarmas.dart';
 import 'package:pluriwave/estado/estado_busqueda.dart';
 import 'package:pluriwave/estado/estado_ecualizador.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
 import 'package:pluriwave/estado/estado_grabacion.dart';
 import 'package:pluriwave/estado/estado_idioma.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
@@ -14,6 +15,7 @@ import 'package:pluriwave/pantallas/pantalla_alarmas.dart';
 import 'package:pluriwave/pantallas/pantalla_buscar.dart';
 import 'package:pluriwave/pantallas/pantalla_favoritos.dart';
 import 'package:pluriwave/servicios/servicio_alarmas.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
 import 'package:pluriwave/widgets/pluri_root_header.dart';
 import 'package:provider/provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -74,6 +76,12 @@ void main() {
         ListenableProvider<EstadoGrabacion>.value(value: estado.grabacion),
         ListenableProvider<EstadoBusqueda>.value(value: estado.busqueda),
         ChangeNotifierProvider<EstadoIdioma>.value(value: EstadoIdioma()),
+        ChangeNotifierProvider<EstadoEntitlement>(
+          create: (_) => EstadoEntitlement(prefs: null),
+        ),
+        Provider<ServicioAnuncios>(
+          create: (_) => ServicioAnuncios(esPremium: () => true),
+        ),
         if (alarmas != null)
           ChangeNotifierProvider<EstadoAlarmas>.value(value: alarmas),
       ],

test/pantallas/root_header_wiring_test.dart

@@ -5,6 +5,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_alarmas.dart';
 import 'package:pluriwave/estado/estado_busqueda.dart';
 import 'package:pluriwave/estado/estado_ecualizador.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
 import 'package:pluriwave/estado/estado_grabacion.dart';
 import 'package:pluriwave/estado/estado_idioma.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
@@ -15,6 +16,7 @@ import 'package:pluriwave/pantallas/pantalla_buscar.dart';
 import 'package:pluriwave/pantallas/pantalla_favoritos.dart';
 import 'package:pluriwave/pantallas/pantalla_inicio.dart';
 import 'package:pluriwave/servicios/servicio_alarmas.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
 import 'package:pluriwave/widgets/pluri_root_header.dart';
 import 'package:provider/provider.dart';
 import 'package:shared_preferences/shared_preferences.dart';
@@ -72,6 +74,12 @@ void main() {
         ListenableProvider<EstadoGrabacion>.value(value: estado.grabacion),
         ListenableProvider<EstadoBusqueda>.value(value: estado.busqueda),
         ChangeNotifierProvider<EstadoIdioma>.value(value: EstadoIdioma()),
+        ChangeNotifierProvider<EstadoEntitlement>(
+          create: (_) => EstadoEntitlement(prefs: null),
+        ),
+        Provider<ServicioAnuncios>(
+          create: (_) => ServicioAnuncios(esPremium: () => true),
+        ),
         if (alarmas != null)
           ChangeNotifierProvider<EstadoAlarmas>.value(value: alarmas),
       ],

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');
+  });
+}

test/widgets/banner_anuncio_superior_test.dart

@@ -0,0 +1,75 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
+import 'package:pluriwave/servicios/servicio_anuncios.dart';
+import 'package:pluriwave/widgets/banner_anuncio_superior.dart';
+import 'package:provider/provider.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// Ad-display spec "Persistent Top Banner, Never Overlapping Content": the
+/// banner is entitlement-aware and reserves layout via a `Column`
+/// (`SizedBox.shrink()` collapses it to zero footprint) — never a `Stack`
+/// overlay. AdMob's own `BannerAd.load()` cannot reach a real ad server in
+/// `flutter test` (no plugin channel registered), so it always resolves to
+/// "unloaded" here — exactly the same degrade-to-shrink path a genuine
+/// failed load takes in production (never a crash, never a placeholder).
+void main() {
+  setUp(() {
+    SharedPreferences.setMockInitialValues({});
+  });
+
+  Widget construir({required bool premium}) {
+    return MultiProvider(
+      providers: [
+        ChangeNotifierProvider<EstadoEntitlement>(
+          create: (_) {
+            final estado = EstadoEntitlement(prefs: null);
+            return estado;
+          },
+        ),
+        Provider<ServicioAnuncios>(
+          create: (_) => ServicioAnuncios(esPremium: () => premium),
+        ),
+      ],
+      child: MaterialApp(
+        home: Scaffold(
+          body: Column(
+            children: [
+              const BannerAnuncioSuperior(),
+              const Expanded(child: Center(child: Text('contenido'))),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  testWidgets(
+    'usuario free sin anuncio cargado: colapsa a SizedBox.shrink (nunca overlay)',
+    (tester) async {
+      await tester.pumpWidget(construir(premium: false));
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 50));
+
+      final banner = find.byType(BannerAnuncioSuperior);
+      expect(banner, findsOneWidget);
+      // Collapsed to zero footprint (no ad ever loads in a widget test — no
+      // AdMob plugin channel registered) — a `SizedBox.shrink()`, not an
+      // overlay: the Column layout below it stays fully visible.
+      expect(tester.getSize(banner).height, 0);
+      expect(find.text('contenido'), findsOneWidget);
+    },
+  );
+
+  testWidgets('usuario premium: nunca intenta mostrar el banner', (
+    tester,
+  ) async {
+    await tester.pumpWidget(construir(premium: true));
+    await tester.pump();
+    await tester.pump(const Duration(milliseconds: 50));
+
+    final banner = find.byType(BannerAnuncioSuperior);
+    expect(tester.getSize(banner).height, 0);
+    expect(find.text('contenido'), findsOneWidget);
+  });
+}

test/widgets/pluri_push_scaffold_test.dart

@@ -5,6 +5,7 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:pluriwave/estado/estado_alarmas.dart';
 import 'package:pluriwave/estado/estado_busqueda.dart';
 import 'package:pluriwave/estado/estado_ecualizador.dart';
+import 'package:pluriwave/estado/estado_entitlement.dart';
 import 'package:pluriwave/estado/estado_grabacion.dart';
 import 'package:pluriwave/estado/estado_idioma.dart';
 import 'package:pluriwave/estado/estado_radio.dart';
@@ -213,6 +214,9 @@ void main() {
             ),
             ListenableProvider<EstadoGrabacion>.value(value: estado.grabacion),
             ChangeNotifierProvider<EstadoIdioma>.value(value: estadoIdioma),
+            ChangeNotifierProvider<EstadoEntitlement>(
+              create: (_) => EstadoEntitlement(prefs: null),
+            ),
           ],
           child: testApp(const PantallaAjustes()),
         ),