pluriwave/openspec/changes/app-quality-and-native-alarms/spec.md

# Spec: app-quality-and-native-alarms

Delta requirements for the PluriWave Android alarm reliability, UX parity, runtime
robustness, architecture decomposition, design-system, quality-gate, and streaming
resilience change. Every requirement states what MUST be true after the change is
applied; implementation details are deferred to the design phase.

Verifiability legend:
- **[flutter test]** — unit/widget test exercisable via `flutter test`
- **[flutter analyze]** — static analysis via `flutter analyze`
- **[on-device]** — requires a real build and manual or instrumented verification on Android
  hardware/emulator; `flutter build` is forbidden in this project

---

## S1 — Alarm native reliability

### S1-R1 — Foreground-service alarm type declared (CRITICAL)

The `AndroidManifest.xml` MUST declare `foregroundServiceType="mediaPlayback|alarm"` for
`PluriWaveAlarmService` and MUST include the `FOREGROUND_SERVICE_ALARM` permission, so
that Android 14+ (API 34+) does not throw `ForegroundServiceTypeException` when the
alarm fires.

**[on-device]**

#### Scenario S1-R1-A: alarm fires on Android 14+

```
Given a device running Android 14+ (API 34)
  And an alarm has been scheduled with a future trigger time
When the trigger time is reached
Then PluriWaveAlarmService starts in the foreground without ForegroundServiceTypeException
  And the alarm ringing screen is shown (or the foreground notification is posted)
```

### S1-R2 — Single fire notification per alarm event

On any alarm fire event, exactly one notification SHALL be posted.
`PluriWaveAlarmReceiver` MUST NOT post a duplicate FSI notification when
`PluriWaveAlarmService` is already managing the foreground notification (`NOTIFICATION_ID
92841`). `dismissFireNotification` in `EstadoAlarmas` MUST cancel the single canonical
notification ID.

**[on-device]**

#### Scenario S1-R2-A: no duplicate notification

```
Given an alarm fires and PluriWaveAlarmService posts NOTIFICATION_ID 92841
When the system notification tray is inspected
Then exactly one notification for that alarm is visible
```

#### Scenario S1-R2-B: dismiss cancels the notification

```
Given the fire notification is visible
When the user dismisses the alarm (stop action)
Then the notification is removed from the tray
  And no orphan notification remains
```

### S1-R3 — Channel-level alarm audio attributes

The `pluriwave_alarm_fire` and `pluriwave_alarm_native` notification channels MUST be
created with `setSound(uri, audioAttributes)` where `audioAttributes` use
`AudioAttributes.USAGE_ALARM`, so that Android 8+ honors the alarm ringer stream.

**[on-device]**

#### Scenario S1-R3-A: alarm sound plays on alarm channel

```
Given the fire channels are created at app first-launch
When an alarm fires and produces a notification
Then the notification sound plays on the alarm audio stream
  And respects the device's alarm volume (not media volume)
```

### S1-R4 — Fallback station passed through MethodChannel

When `AlarmaMusical.emisoraFallback` is set, `ServicioAlarmasAndroid.programar` MUST
pass `fallbackStationUrl` in the `scheduleAlarm` MethodChannel payload, and
`NativeAlarmSpec` (Kotlin) MUST carry the field. `PluriWaveAlarmService` MUST attempt
`prepareAsync` on the fallback URL when the primary station fails.

**[on-device]** (native path); **[flutter test]** (Dart MethodChannel payload assertion)

#### Scenario S1-R4-A: fallback attempted natively

```
Given an alarm has emisoraFallback set to a valid URL
  And the primary station stream fails or times out during alarm playback
When the native service handles playback
Then the fallback station URL is attempted via MediaPlayer.prepareAsync
```

#### Scenario S1-R4-B: fallback URL absent → bundled sound

```
Given an alarm has no emisoraFallback
  And the primary station stream fails
When the native service handles playback
Then the bundled fallback WAV is played (existing behavior preserved)
```

### S1-R5 — Battery-optimization exemption request

`_solicitarPermisosNecesariosParaAlarma` MUST request `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`
so that Doze-mode does not suppress alarm delivery on devices where the permission is not
already granted.

**[on-device]**

#### Scenario S1-R5-A: exemption requested at setup

```
Given the user grants alarm scheduling permission for the first time
When permission setup runs
Then the system dialog for REQUEST_IGNORE_BATTERY_OPTIMIZATIONS is presented
  (unless the app is already exempt)
```

### S1-R6 — Native fade-in matching fadeInSegundos

`PluriWaveAlarmService` MUST apply a volume ramp from 0 to target volume over
`fadeInSegundos` seconds when starting alarm audio on the native path, so that fade-in
works even when the ringing screen is not foregrounded.

**[on-device]**

#### Scenario S1-R6-A: native path audio fades in

```
Given an alarm fires while the app is backgrounded/killed
  And the alarm's fadeInSegundos is greater than 0
When the native service starts playing audio
Then audio starts at near-zero volume and ramps to the configured volume over fadeInSegundos seconds
```

---

## S2 — Alarm UX parity (snooze end-to-end)

### S2-R1 — Snooze buttons on PantallaAlarmaSonando

`PantallaAlarmaSonando` MUST display snooze buttons for 3, 5, and 10 minutes, plus one
button showing the alarm's configured `snoozeMinutos` value when it differs from the
fixed options. Tapping any snooze button MUST:

1. Cancel the active `_fadeInTimer`.
2. Stop and dispose the `_fallbackPlayer`.
3. Stop the native alarm service (via the same stop path used by the dismiss button).
4. Call `EstadoAlarmas.posponerAlarma(alarma, minutes)`.
5. Close `PantallaAlarmaSonando`.

**[flutter test]** (widget test for button presence and tap behavior); **[on-device]** (full
native service stop verified manually)

#### Scenario S2-R1-A: snooze button appears

```
Given PantallaAlarmaSonando is displayed for an alarm with snoozeMinutos = 5
When the widget tree is inspected
Then buttons for 3 min, 5 min, and 10 min snooze are present
  And a single "stop" / dismiss button is present
```

#### Scenario S2-R1-B: tapping snooze stops audio and reschedules

```
Given PantallaAlarmaSonando is displayed and audio is playing (fadeInTimer active, fallbackPlayer active)
When the user taps the 5-minute snooze button
Then the fadeInTimer is cancelled
  And the fallbackPlayer is stopped and disposed
  And the native alarm service receives a stop command
  And EstadoAlarmas.posponerAlarma is called with minutes = 5
  And the screen is dismissed/popped
```

#### Scenario S2-R1-C: custom snoozeMinutos displayed

```
Given an alarm has snoozeMinutos = 7
When PantallaAlarmaSonando is displayed
Then a snooze button labeled "7 min" is present in addition to the fixed 3/5/10 options
```

### S2-R2 — Alarm list reflects postponed next-trigger immediately

After snooze is accepted (from the Flutter screen or from the native notification), the
alarm list in `PantallaAlarmas` MUST display the updated `snoozeHasta` as the next-trigger
time without waiting for the 60-second periodic poll.

**[flutter test]** (unit test: posponerAlarma updates notifier synchronously)

#### Scenario S2-R2-A: alarm list updated after snooze

```
Given the alarm list is visible and showing an alarm's next-trigger time T
When the user snoozes the ringing alarm for 5 minutes (from PantallaAlarmaSonando)
Then within the same UI frame after posponerAlarma completes
  the alarm list shows the new next-trigger time T+5 min
  And no manual refresh or navigation is required
```

### S2-R3 — Snooze from native notification while app killed or foregrounded

When the user taps the "Posponer" action on the fire notification while the app is
backgrounded or killed, `AlarmScheduler.snooze(id, minutes)` MUST execute a real
`setAlarmClock` registration for `now + N minutes`. When the app becomes active
(foreground resume), `EstadoAlarmas` MUST reflect the new `snoozeHasta` via the existing
MethodChannel event flow (not waiting for the next 60-second poll).

**[on-device]** (native scheduling verified); **[flutter test]** (Dart event handler updates EstadoAlarmas state)

#### Scenario S2-R3-A: notification snooze schedules real alarm

```
Given the app is killed (not in memory)
  And a fire notification with "Posponer" action is visible
When the user taps "Posponer"
Then AlarmScheduler.snooze executes setAlarmClock for now+snoozeMinutes
  And the alarm appears in the system status-bar alarm icon count
```

#### Scenario S2-R3-B: Flutter state syncs on resume without polling

```
Given snooze was triggered from the native notification while app was backgrounded
When the app is brought to the foreground
Then EstadoAlarmas.alarmas contains the snoozed alarm with snoozeHasta = snooze target time
  And the update happens before the next 60-second poll fires
```

### S2-R4 — Snoozed alarm fires at postponed time

A snoozed alarm MUST fire again at the exact `snoozeHasta` time.
`AlarmScheduler.snooze` MUST call `setAlarmClock` with `snoozeHasta` as the trigger;
the resulting `AlarmClockInfo` MUST be verifiable through the diagnostics channel.

**[on-device]**

#### Scenario S2-R4-A: alarm re-fires after snooze

```
Given an alarm was snoozed for 5 minutes at time T
When time T+5 minutes is reached
Then the alarm fires again (ringing screen shown or notification posted)
  And the alarm's snoozeHasta is cleared after it fires
```

#### Scenario S2-R4-B: diagnostics confirm real setAlarmClock registration

```
Given an alarm has been snoozed
When the alarm diagnostics screen is opened
Then the snoozed alarm entry shows a non-null next-trigger time matching snoozeHasta
  And "exact alarm scheduled" status is shown for that alarm
```

### S2-R5 — Stop during snooze-pending state cancels snooze

If the user stops an alarm (dismiss) before the snoozed occurrence fires,
`EstadoAlarmas.finalizarEjecucion` (or a dedicated cancel path) MUST cancel the native
`setAlarmClock` registration for the snooze occurrence and clear `snoozeHasta` on the
`AlarmaMusical` model.

**[flutter test]** (unit test: finalizarEjecucion clears snoozeHasta and calls android.cancelar); **[on-device]** (alarm does not re-fire)

#### Scenario S2-R5-A: stop cancels pending snooze

```
Given an alarm is in snooze-pending state (snoozeHasta is set, alarm has not re-fired)
When the user opens the alarm list and disables or deletes the alarm
  Or explicitly stops the alarm from any surface
Then ServicioAlarmasAndroid.cancelar is called for that alarm
  And the alarm's snoozeHasta is null in persistent storage
  And the alarm does not re-fire at the snooze time
```

### S2-R6 — Snooze Dart-side unit tests (strict TDD)

The following Dart-side behaviors MUST be covered by `flutter test` unit tests:

- `EstadoAlarmas.posponerAlarma` calls `android.programar` with updated `snoozeHasta`.
- `EstadoAlarmas.posponerAlarma` calls `notifyListeners` after state update.
- `EstadoAlarmas.finalizarEjecucion` clears `snoozeHasta` and calls `android.cancelar` or `android.programar` without `snoozeHasta`.
- `ServicioAlarmas.posponerEjecucion` computes `snoozeHasta = ejecucion + minutos` correctly.
- The MethodChannel payload sent by `ServicioAlarmasAndroid.programar` for a snoozed alarm contains `snoozeUntilMillis` matching the alarm's `snoozeHasta`.

**[flutter test]**

#### Scenario S2-R6-A: posponerAlarma unit test

```
Given a mock PuertoAlarmasAndroid and a mock ServicioAlarmas
  And an alarm with proximaEjecucion = T
When EstadoAlarmas.posponerAlarma(alarma, 10) is called
Then servicio.posponerEjecucion is called with minutos = 10
  And android.programar is called once with the updated alarm carrying snoozeHasta = T+10min
  And notifyListeners was called
```

### S2-R7 — Ringing screen migrated to PluriWaveScaffold with entry animation

`PantallaAlarmaSonando` MUST use `PluriWaveScaffold` instead of a raw `Scaffold` with
a hardcoded `Color(0xFF061722)` background, and MUST include an entry animation on mount
(fade or slide, honoring `MediaQuery.disableAnimations`).

**[flutter test]** (widget test: PluriWaveScaffold present); **[on-device]** (visual)

#### Scenario S2-R7-A: no raw Scaffold with hardcoded color

```
Given PantallaAlarmaSonando is mounted
When the widget tree is inspected
Then no raw Scaffold with backgroundColor = Color(0xFF061722) is found at the root
  And PluriWaveScaffold (or equivalent themed scaffold) wraps the content
```

### S2-R8 — Next-trigger preview in alarm editor

`_EditorAlarmaSheet` MUST display a read-only next-trigger timestamp computed from the
current editor state (schedule type, time, weekdays, one-shot date) so the user can
verify when the alarm will fire before saving.

**[flutter test]** (widget test)

#### Scenario S2-R8-A: next-trigger shown in editor

```
Given the alarm editor is open with a recurring weekday alarm set for Monday/Wednesday at 07:00
When the widget is inspected
Then a text widget shows the next calculated trigger date/time
  And it updates when the user changes the schedule
```

### S2-R9 — Searchable station picker

The station selection in the alarm editor MUST use a searchable bottom-sheet picker
instead of a raw `DropdownButtonFormField`, matching the interaction pattern of the main
station picker.

**[flutter test]** (widget test: bottom sheet opens on tap)

#### Scenario S2-R9-A: search bottom sheet opens

```
Given the alarm editor is open
When the user taps the station selection field
Then a bottom sheet with a search input and station list is presented
  And typing in the search input filters the list
```

### S2-R10 — Configurable snooze duration

The alarm editor MUST allow the user to set a custom snooze duration (stored as
`AlarmaMusical.snoozeMinutos`). The ringing screen snooze buttons MUST use this value as
the labeled default option.

**[flutter test]** (widget test)

### S2-R11 — Volume-slider floor lowered

The alarm volume slider MUST allow values down to 0.0 (from the current floor of 0.25).

**[flutter test]** (widget test: slider min value)

---

## S3 — Audio and runtime robustness (test seams)

### S3-R1 — audio_session integrated for audio focus

The `audio_session` package (`pubspec.yaml:19`) MUST be imported and configured so that
phone calls and other audio-focus events (transient/permanent loss) pause or duck the
radio playback. The existing `audio_session` declaration MUST NOT remain unused.

**[on-device]** (incoming call pauses radio); **[flutter analyze]** (import present)

#### Scenario S3-R1-A: phone call pauses radio

```
Given the radio is playing
When an incoming phone call starts
Then the radio playback is paused or ducked
  And resumes when the call ends (if it was only transient focus loss)
```

### S3-R2 — Injectable StreamController and handler flag

The static `_eventosController` and `_handlerInstalado` fields in `ServicioAlarmasAndroid`
(lines 117-119) MUST be converted to instance fields injectable via constructor or a test
factory, making the class testable without global state side-effects.

**[flutter test]** (unit tests can construct isolated instances)

#### Scenario S3-R2-A: two instances do not share state

```
Given two ServicioAlarmasAndroid instances created independently in a test
When one instance receives an alarm event
Then the other instance's eventosAlarma stream does not emit that event
```

### S3-R3 — configurarLocalizaciones removed from build()

`configurarLocalizaciones(l10n)` MUST NOT be called inside any `build()` method (current
violation: `mini_reproductor.dart:23`). It MUST be called once from the widget lifecycle
(`initState`, `didChangeDependencies`, or the provider consumer's init path).

**[flutter analyze]** (no-ops inside build); **[flutter test]** (verify call count)

#### Scenario S3-R3-A: localization call not in build

```
Given the MiniReproductor widget is mounted and rebuilt 10 times due to state changes
When the call count to configurarLocalizaciones is measured
Then it is called at most once per locale change (not once per rebuild)
```

### S3-R4 — Single cached SharedPreferences instance

A single `SharedPreferences` instance MUST be initialized at app startup (e.g., in
`main.dart`) and injected into all services that currently call
`SharedPreferences.getInstance()` inline (25+ sites). No service MUST call
`SharedPreferences.getInstance()` after app startup.

**[flutter test]** (unit tests use injected mock); **[flutter analyze]** (no getInstance calls in service classes after injection)

#### Scenario S3-R4-A: services receive injected prefs

```
Given the app starts
When ServicioAlarmas, ServicioEcualizador, and ServicioGrabacionRadio are constructed
Then each receives the single SharedPreferences instance (no internal getInstance call)
```

### S3-R5 — recalcularTodas writes guarded by change flag

`recalcularTodas()` in `EstadoAlarmas` (lines 316-323) MUST compare the new schedule to
the existing one before writing to SharedPreferences. If the schedule is unchanged, the
write MUST be skipped.

**[flutter test]**

#### Scenario S3-R5-A: no write on unchanged schedule

```
Given the alarm schedule has not changed since the last write
When recalcularTodas() is called
Then SharedPreferences.setString is NOT called
```

#### Scenario S3-R5-B: write happens on schedule change

```
Given the alarm schedule has changed
When recalcularTodas() is called
Then SharedPreferences.setString IS called exactly once
```

### S3-R6 — Bounded _ejecucionesEmitidas set

`_ejecucionesEmitidas` in `EstadoAlarmas` (line 32) MUST be bounded. Entries that are
older than a configurable retention window (e.g., 24 hours past their scheduled time)
MUST be pruned to prevent unbounded memory growth.

**[flutter test]**

#### Scenario S3-R6-A: old entries pruned

```
Given _ejecucionesEmitidas contains 100 entries all older than 24 hours
When the pruning logic runs (triggered on next alarm event or periodic cleanup)
Then _ejecucionesEmitidas.length is less than or equal to the max expected entries
```

### S3-R7 — In-memory alarm cache in ServicioAlarmas

`ServicioAlarmas` MUST maintain an in-memory cache so that `cargar()` is not called
before every mutation (eliminating the read-modify-write N+1 race at lines 81-108). The
cache MUST be invalidated on any write operation.

**[flutter test]**

#### Scenario S3-R7-A: concurrent mutations use cache

```
Given ServicioAlarmas has loaded alarms into cache
When two mutations are dispatched concurrently
Then only one cargar() call is made (not two), and both mutations are applied correctly
```

---

## S4 — EstadoRadio god-class split

### S4-R1 — EstadoEcualizador extracted

A `EstadoEcualizador extends ChangeNotifier` MUST own all EQ state (preset, bands,
enabled flag) previously in `EstadoRadio`. `EstadoRadio` MUST NOT expose EQ state
directly.

**[flutter test]** (unit test: EstadoEcualizador notifies on preset change); **[flutter analyze]**

#### Scenario S4-R1-A: EQ state owned by EstadoEcualizador

```
Given EstadoEcualizador is registered as a provider
When aplicarPreset is called on EstadoEcualizador
Then EstadoEcualizador notifies its listeners
  And EstadoRadio listeners are NOT rebuilt
```

### S4-R2 — EstadoGrabacion extracted

A `EstadoGrabacion extends ChangeNotifier` MUST own all recording state previously in
`EstadoRadio`. `ServicioGrabacionRadio` MUST be managed by `EstadoGrabacion`.

**[flutter test]**

### S4-R3 — EstadoBusqueda extracted

A `EstadoBusqueda extends ChangeNotifier` MUST own search query, results, and loading
state previously in `EstadoRadio`.

**[flutter test]**

### S4-R4 — ServicioExportImport extracted

A `ServicioExportImport` class MUST own the `jsonEncode`/`jsonDecode` backup and restore
logic currently inlined in `pantalla_ajustes.dart` (1391 lines). `PantallaAjustes` MUST
delegate all JSON serialization to `ServicioExportImport`.

**[flutter test]** (round-trip test: serialize then deserialize produces identical config)

#### Scenario S4-R4-A: export/import round-trip

```
Given a non-trivial app configuration (alarms, favorites, EQ presets)
When ServicioExportImport.exportar() is called and its output is passed to importar()
Then the reconstructed configuration equals the original
```

### S4-R5 — Consuming screens use scoped rebuilds

`PantallaInicio`, `PantallaAjustes`, and `PantallaFavoritos` MUST NOT call
`context.watch<EstadoRadio>()` at the root widget. Each MUST use `context.select` or a
`Consumer` scoped to the specific fields it reads.

**[flutter test]** (widget test: changing EQ preset does not rebuild PantallaInicio)

#### Scenario S4-R5-A: EQ change does not rebuild inicio screen

```
Given PantallaInicio is mounted and displaying station info
When EstadoEcualizador notifies (preset change)
Then PantallaInicio's build method is NOT called
```

---

## S5 — Design system, accessibility, i18n pass

### S5-R1 — Hardcoded color literals replaced by tokens

All 14+ hardcoded `Color(0x...)` literals identified in the explore report (C3) MUST be
replaced by `PluriWaveTokens` or `Theme.of(context).colorScheme` references. No new
hardcoded color literals SHALL be introduced.

**[flutter analyze]** (custom lint or grep); **[flutter test]** (widget test: token resolves correctly)

#### Scenario S5-R1-A: no raw color literals in target files

```
Given the diff for Slice 5 is applied
When flutter analyze runs
Then no instances of Color(0x...) appear in the modified files beyond theme-extension token definitions
```

### S5-R2 — Accessibility semantics on favorite button and alarm image

The mini favorite `InkWell` in `TarjetaEmisora` (line 238-289) MUST be wrapped in a
`Semantics` widget with an appropriate `label` and `button: true`. It MUST have a minimum
touch target of 48 dp. The alarm PNG widget MUST carry a `semanticLabel`.

**[flutter test]**

#### Scenario S5-R2-A: favorite button is accessible

```
Given TarjetaEmisora is mounted
When the accessibility tree is inspected
Then the favorite action node has a non-empty semantic label
  And its size is at least 48x48 dp
```

### S5-R3 — Reduced-motion guard

A `PluriAnimate` extension (or equivalent helper) MUST check `MediaQuery.disableAnimations`
and skip or replace animations when the user has enabled reduced motion in system settings.
All animations in Slices 2 and 5 MUST use this guard.

**[flutter test]** (widget test: animation skipped when disableAnimations = true)

#### Scenario S5-R3-A: animation skipped in reduced-motion mode

```
Given MediaQuery.disableAnimations is true (test override)
When PantallaAlarmaSonando is mounted (entry animation present per S2-R7)
Then no animated position/opacity change is applied on mount
```

### S5-R4 — Locale-aware date formatting

`_fechaCorta` in `PantallaAlarmas` (line 1114) MUST use `intl.DateFormat` with the
current locale rather than a hardcoded DD/MM/YYYY format string.

**[flutter test]**

#### Scenario S5-R4-A: date formatted per locale

```
Given locale is 'en-US'
When _fechaCorta is called with DateTime(2026, 6, 11)
Then the result matches DateFormat.yMd('en-US').format(DateTime(2026, 6, 11))
  And does NOT return "11/06/2026"
```

### S5-R5 — Pluralization for bare counters

`PantallaFavoritos` (line 138) MUST use `AppLocalizations` plural forms for station count
strings (e.g., "1 station" vs "5 stations").

**[flutter test]**

### S5-R6 — Rounded shimmer placeholders

Shimmer placeholders in `TarjetaEmisora` (lines 389-420) MUST use rounded corners
matching the actual content card corners. The `PantallaBuscar` loading state (lines
241-245) MUST use shimmer instead of a spinner.

**[flutter test]** (widget test: shimmer present during loading state)

### S5-R7 — Rounded icon variants consistent

Icon usage in `PantallaAjustes` (lines 985, 1028, 1031) MUST use `_rounded` Material
icon variants to be consistent with the rest of the app.

**[flutter analyze]** (grep for non-rounded icon names at those sites)

### S5-R8 — Brand notification color

The `notificationColor` in `AudioServiceConfig` (`main.dart:23`) MUST be set to the app's
brand color token rather than the M3 default `Color(0xFF6750A4)`.

**[flutter test]** (unit test: config uses brand color)

---

## S6 — Quality gates

### S6-R1 — Hardened analysis_options.yaml

`analysis_options.yaml` MUST enable at minimum the following lint rules:
`cancel_subscriptions`, `close_sinks`, `unawaited_futures`, `prefer_final_locals`,
`avoid_dynamic_calls`.

**[flutter analyze]**

#### Scenario S6-R1-A: new lints pass

```
Given the hardened analysis_options.yaml is applied
When flutter analyze runs on the full lib/ tree
Then no errors are emitted for cancel_subscriptions, close_sinks, unawaited_futures,
  prefer_final_locals, or avoid_dynamic_calls
```

### S6-R2 — Top-5 missing unit tests written

The following test cases MUST exist and pass under `flutter test`:

1. `ServicioAlarmas` concurrent read-modify-write: two simultaneous mutations produce a
   consistent final state with no lost write.
2. Alarm fire dedup across `refrescarProgramacion`: calling `refrescarProgramacion` while
   an alarm is already in `_ejecucionesEmitidas` does not emit a duplicate event.
3. `PluriWaveAudioHandler` rapid source-switch race: switching stations faster than the
   12-second timeout cancels the previous load and does not emit a stale error state.
4. Export/import round-trip (see S4-R4 scenario).
5. `ServicioGrabacionRadio` error recovery: a recording error clears the recording state
   and does not leave open sinks.

**[flutter test]**

#### Scenario S6-R2-A: concurrent mutation test

```
Given two calls to ServicioAlarmas.guardar run concurrently with different alarm payloads
When both futures complete
Then the persisted state contains both alarms without either being lost
```

#### Scenario S6-R2-B: source-switch race test

```
Given PluriWaveAudioHandler has started loading station A
When station B is requested before station A finishes loading
Then the playback state does not transition to error for station A's load failure
  And the final state reflects station B
```

---

## S7 — Streaming resilience

### S7-R1 — Enlarged live-stream buffer

`PluriWaveAudioHandler` (ExoPlayer / just_audio) MUST configure an enlarged live-stream
buffer sufficient to tolerate short network interruptions of up to approximately 15-30
seconds without audible playback interruption. The buffer size MUST be configurable (not
hardcoded to a single magic constant).

**[on-device]** (network drop test); **[flutter test]** (unit test: buffer config applied to player)

#### Scenario S7-R1-A: buffer covers short network drop

```
Given the radio is playing and ExoPlayer has buffered content
When network connectivity is lost for up to 15 seconds
Then audio playback continues without interruption (buffered content plays through)
  And the UI does not show an error state during the buffer window
```

### S7-R2 — Automatic reconnection with bounded exponential backoff

When the live stream stalls or emits a `PlayerException` with a network-related error
code (2xxx range) while the user's intended playback state is "playing" (not user-paused
or user-stopped), `PluriWaveAudioHandler` MUST attempt automatic reconnection using
exponential backoff with a configurable maximum retry count (default: 5) and a configurable
maximum delay (default: 30 seconds). After retries are exhausted, the error MUST be
surfaced to the UI via the `playbackState` error state.

The handler MUST distinguish user-initiated stop/pause (no reconnect) from network stall
(reconnect).

**[flutter test]** (unit test for reconnect decision logic and backoff timing)

#### Scenario S7-R2-A: reconnect on network stall

```
Given the radio is playing and userIntent = playing
When a PlayerException with code 2001 (no internet) is received
Then the handler transitions to a "buffering/reconnecting" processing state
  And schedules a retry after the backoff delay (not an immediate error state)
```

#### Scenario S7-R2-B: no reconnect on user stop

```
Given the radio is playing
When the user calls ServicioAudio.detener()
Then userIntent is set to stopped
  And if a PlayerException subsequently fires (from the stop race)
  Then no reconnection is attempted
```

#### Scenario S7-R2-C: retries exhausted → error surfaced

```
Given the handler has attempted 5 reconnections without success
When the 5th retry also fails
Then playbackState transitions to AudioProcessingState.error with errorMessage set
  And no further retries are attempted
```

#### Scenario S7-R2-D: backoff logic unit test

```
Given a reconnect strategy with maxRetries=5 and baseDelay=1s
When retries 1..5 are simulated
Then the delay sequence is approximately [1s, 2s, 4s, 8s, 16s] capped at maxDelay
  And after retry 5 the strategy returns "exhausted"
```

### S7-R3 — Buffering/reconnecting state surfaced without dialog spam

While the handler is in the reconnecting/buffering phase, the UI MUST show a loading/
buffering indicator (e.g., the existing `EstadoReproduccion.cargando` state) and MUST NOT
show an error dialog or snackbar for each retry attempt. An error MUST only be shown after
retries are exhausted (S7-R2-C).

**[flutter test]** (widget test: no dialog shown during buffering state)

#### Scenario S7-R3-A: no error dialog during reconnect

```
Given the handler is in reconnecting state (attempt 2 of 5)
When the UI observes estadoStream
Then EstadoReproduccion.cargando is emitted (not error)
  And no AlertDialog or SnackBar with error text is visible
```

### S7-R4 — Alarm audio path not regressed

The enlarged buffer and reconnect logic MUST apply only to the user-initiated radio
playback path (`PluriWaveAudioHandler`). The native alarm audio path (`PluriWaveAlarmService`
MediaPlayer) MUST be unchanged by Slice 7. The existing 15-second stream timeout before
falling back to bundled WAV MUST be preserved.

**[on-device]** (alarm still fires with fallback); **[flutter test]** (alarm service not using new buffer config)

#### Scenario S7-R4-A: alarm fallback timing unchanged

```
Given an alarm fires with a station URL that never responds
When 15 seconds elapse
Then the native service falls back to the bundled WAV (behavior unchanged by S7)
```

### S7-R5 — Recording path not regressed

`ServicioGrabacionRadio` uses its own HTTP stream (not `PluriWaveAudioHandler`). Its
error handling MUST NOT be modified by Slice 7 changes.

**[flutter test]** (S6-R2 test #5 still passes after S7 changes)

#### Scenario S7-R5-A: recording error handling unchanged

```
Given ServicioGrabacionRadio is recording from a stream that errors
When the error occurs
Then the recording state is cleared (same behavior as before S7)
  And no backoff or reconnect logic from S7 is triggered
```

### S7-R6 — Sleep-timer fade-out not regressed

The sleep-timer fade-out logic (gradual volume reduction → stop) MUST complete normally
even if the stream enters a buffering state during the fade-out window. The reconnect
logic MUST NOT restart playback after the sleep-timer issues a stop command.

**[flutter test]**

#### Scenario S7-R6-A: sleep timer stop honored during reconnect

```
Given the sleep timer is active and has issued a stop command
When the handler would normally schedule a reconnect attempt
Then the reconnect is suppressed because userIntent = stopped (from sleep timer stop)
  And audio stops as intended
```

### S7-R7 — Reconnection unit tests (strict TDD)

The following MUST be covered by `flutter test` unit tests:

- Backoff delay computation for retries 1 through N with cap at maxDelay.
- `userIntent` transitions: `reproducir()` sets intent to playing; `detener()` and `pausar()` set intent to stopped/paused.
- No reconnect scheduled when `userIntent != playing`.
- Reconnect attempted when `userIntent == playing` and error is network-class.
- Error state emitted after `maxRetries` exhausted.

**[flutter test]**

---

## Cross-cutting requirements

### CC-R1 — No flutter build required

No requirement in this spec SHALL necessitate running `flutter build`. Native correctness
requirements (marked `[on-device]`) are validated by the user via manual device testing.

### CC-R2 — Strict TDD

All Dart-side behavioral logic introduced by Slices 1-7 MUST be covered by `flutter test`
unit tests written before or alongside the implementation code. Slices that introduce
new Dart classes MUST include at least one test file per new class.

### CC-R3 — No regressions to existing flutter test suite

After each slice, `flutter test` MUST pass with no new failures. All 12 existing test
files MUST continue to pass.

**[flutter test]**

### CC-R4 — flutter analyze clean

After each slice, `flutter analyze` MUST report zero errors. Warnings introduced by new
lint rules (S6-R1) MUST be resolved before the slice PR is merged.

**[flutter analyze]**