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

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

Raise PluriWave to native-Android-Clock alarm reliability and UX, then pay down the architecture, accessibility, and quality debt that surfaced around it. The custom native alarm stack is the right design and is KEPT; this change closes its gaps and hardens the app around it. Work ships as six chained, PR-sized slices, each under 400 changed lines, ordered by user-facing risk.

## Intent

**Problem.** The alarm feature can fail silently on Android 14+ (missing foreground-service type), posts duplicate fire notifications, ignores the configured alarm sound at the channel level, drops the fallback station on the native path, and offers no snooze on its own ringing screen. Around it, the app carries runtime debt: a declared-but-unused `audio_session` (so calls do not pause the radio), a `build()`-time localization call firing dozens of times per second, untestable statics, a 1121-line god-class, and unguarded per-minute SharedPreferences writes. UI/UX has 14+ hardcoded colors, missing accessibility semantics, no reduced-motion handling, and locale-breaking date formatting.

**Why now.** Android 14+ already makes the foreground-service gap a silent production failure (CRITICAL). The alarm is the highest-trust feature in the app — when a user sets an alarm they expect to wake up — so reliability cannot wait. The architecture debt directly amplifies alarm risk (state divergence, races, swallowed errors), so fixing it is part of the same arc, not a separate cleanup.

**Success looks like.** Alarms fire reliably on Android 14+, present a single notification, sound with the configured alarm audio, honor the fallback station and fade-in natively, and offer snooze that stays consistent with `EstadoAlarmas`. The radio pauses for phone calls. No localization call runs inside `build()`. `EstadoRadio` is decomposed into focused notifiers. The design system, accessibility, i18n, and lint gates close the highlighted gaps, backed by the top-5 missing tests under strict TDD.

## Scope (in scope)

- Android native alarm reliability: foreground-service type + permission, notification dedup, channel-level alarm sound, fallback station over the MethodChannel, battery-optimization exemption request, native fade-in.
- Alarm UX parity: snooze on the ringing screen, scaffold/animation migration, next-trigger preview, searchable station picker, configurable snooze duration, volume floor adjustment.
- Runtime robustness: integrate `audio_session` for audio focus, remove untestable statics, move localization out of `build()`, inject a single cached SharedPreferences, guard per-minute writes, prune the unbounded set, add an in-memory alarm cache.
- `EstadoRadio` decomposition into focused `ChangeNotifier`s + an export/import service, with `context.select`/`Consumer` scoping at the consuming screens.
- Design-system / accessibility / i18n pass: color tokens, semantics, reduced-motion guard, locale-aware dates, pluralization, shimmer/icon consistency, brand notification color.
- Quality gates: hardened `analysis_options.yaml` and the top-5 missing tests.

## Out of scope

- Light theme / theming beyond the existing dark design (explicitly out unless requested).
- iOS reliable-alarm parity (Android-first, unchanged from `alarm-clock-module`).
- Replacing the native alarm stack with any plugin (`alarm`, `android_alarm_manager_plus` + `flutter_local_notifications`, `awesome_notifications`) — evaluated and rejected.
- Cloud sync of alarms or preferences.
- New alarm capabilities (dismiss challenges, multi-fallback chains, smart/adaptive alarms).
- Full rewrite of `pantalla_ajustes.dart` beyond extracting the backup/import logic.
- Running `flutter build` (project constraint); the user runs builds to validate the Kotlin layer.

## Approach and rationale

1. **Reliability before everything.** Slice 1 ships the native fixes that prevent silent failure and state divergence. Highest user trust, smallest safe footprint, no dependency on later refactors.
2. **UX parity next, on the now-reliable base.** Slice 2 adds snooze and editor improvements once the underlying behavior is correct, so UI never papers over a broken native path.
3. **Robustness third.** Slice 3 introduces test seams (injected SharedPreferences, instance fields, audio session) that later slices and tests depend on. It deliberately precedes the god-class split so the split lands on testable foundations.
4. **Decomposition fourth.** Slice 4 is the largest and riskiest refactor; it runs only after seams exist and reliability/UX are stable, minimizing blast radius.
5. **Polish fifth.** Slice 5 is low-risk, parallelizable design/a11y/i18n work that benefits from the settled structure.
6. **Gates last.** Slice 6 hardens lints and writes the top-5 tests, locking in the prior slices and catching regressions. Strict TDD means tests in Slice 6 (and seams from Slice 3) drive behavior, not follow it.

Chaining: slices are sequential PRs. Each PR targets the previous slice's branch (or main per the cached chain strategy) and stays under 400 changed lines so reviewers verify one unit of work at a time.

## Work breakdown — chained PR-sized slices

### Slice 1 — Alarm native reliability (CRITICAL, ship first)

Risk: CRITICAL. Effort: M. Est. < 350 lines (Kotlin + manifest + Dart bridge).

- Add `alarm` to `foregroundServiceType` (`mediaPlayback|alarm`) and the `FOREGROUND_SERVICE_ALARM` permission (fixes Android 14+ silent failure) — `AndroidManifest.xml`, `PluriWaveAlarmService.kt`.
- Deduplicate fire notifications: keep the service FSI (`NOTIFICATION_ID 92841`) as the single source; stop the receiver from posting its own — `PluriWaveAlarmReceiver.kt`, `PluriWaveAlarmService.kt`.
- Set channel-level sound with alarm `AudioAttributes` on the fire channels at creation — native channel setup.
- Pass `emisoraFallback` through the MethodChannel into the Kotlin `NativeAlarmSpec`; attempt a second `prepareAsync` on the fallback — `servicio_alarmas_android.dart`, `NativeAlarmSpec`.
- Request battery-optimization exemption inside `_solicitarPermisosNecesariosParaAlarma`.
- Native-side fade-in matching Dart `fadeInSegundos`.

### Slice 2 — Alarm UX parity with native Android Clock

Risk: HIGH. Effort: M. Est. < 380 lines.

> **Snooze correctness is in full scope.** This slice audits the entire native snooze
> path (AlarmScheduler.snooze → setAlarmClock registration, notification "Posponer"
> action while app killed, Flutter state sync on resume via MethodChannel event — not
> waiting for the 60-second poll). The goal is end-to-end correctness, not just adding
> UI buttons.

- Snooze buttons (3/5/10 + configured default) on `PantallaAlarmaSonando` wired to `EstadoAlarmas.posponerAlarma`, coordinating `_fadeInTimer` cancel and `_fallbackPlayer` stop, native service stop, and screen dismiss — `pantalla_alarma_sonando.dart:168-212`.
- Migrate the ringing screen to `PluriWaveScaffold` with an entry animation.
- Next-trigger preview inside `_EditorAlarmaSheet`.
- Replace the station `DropdownButtonFormField` with a searchable bottom-sheet picker.
- Configurable snooze duration.
- Lower the volume-slider floor from 0.25 toward 0.

### Slice 3 — Audio / runtime robustness (test seams)

Risk: HIGH. Effort: M-L. Est. < 400 lines.

- Integrate `audio_session` for audio-focus handling so calls pause the radio (`pubspec.yaml:19`, currently never imported).
- Replace static `StreamController` + `_handlerInstalado` with injectable instance fields — `servicio_alarmas_android.dart:117-119`.
- Move `configurarLocalizaciones` out of `MiniReproductor.build()` — `mini_reproductor.dart:23`.
- Inject a single cached `SharedPreferences` at startup (replaces 25+ `getInstance()` calls).
- Guard `recalcularTodas()` writes behind a change flag — `estado_alarmas.dart:316-323`.
- Prune the unbounded `_ejecucionesEmitidas` set — `estado_alarmas.dart:32`.
- Add an in-memory cache to `ServicioAlarmas` to kill the read-modify-write N+1 race — `servicio_alarmas.dart:81-108`.

### Slice 4 — EstadoRadio god-class split (LARGE)

Risk: HIGH (broad surface). Effort: L. May split into 4a/4b if forecast exceeds 400 lines.

- Extract `EstadoEcualizador`, `EstadoGrabacion`, `EstadoBusqueda` `ChangeNotifier`s + a `ServicioExportImport` from the 1121-line `estado_radio.dart`.
- Replace root `context.watch<EstadoRadio>()` in `PantallaInicio` / `Ajustes` / `Favoritos` with `context.select` / `Consumer` scopes — `pantalla_inicio.dart:43` and 6 sites in `pantalla_ajustes`.
- Move backup/import `jsonDecode`/`jsonEncode` logic out of `pantalla_ajustes.dart` (1391 lines) into `ServicioExportImport`.

### Slice 5 — Design system, a11y, i18n pass

Risk: LOW. Effort: M. Parallelizable internally; est. < 350 lines.

- Replace 14+ hardcoded `Color(0x...)` literals with tokens — see explore C3 sites.
- `Semantics` on the grid favorite button + `semanticLabel` on `_AssetIcon` / alarm images — `tarjeta_emisora.dart:238-289`.
- Central reduced-motion guard (`PluriAnimate` extension honoring `MediaQuery.disableAnimations`).
- Locale-aware `_fechaCorta` via `intl` `DateFormat` — `pantalla_alarmas.dart:1114`.
- Pluralization for bare counters — `pantalla_favoritos.dart:138`.
- Rounded shimmer placeholders + shimmer in `PantallaBuscar` — `tarjeta_emisora.dart:389-420`, `pantalla_buscar.dart:241-245`.
- Icon variant consistency (`_rounded`) — `pantalla_ajustes.dart:985,1028,1031`.
- Brand `notificationColor` — `main.dart:23`.

### Slice 6 — Quality gates

Risk: LOW. Effort: M. Est. < 350 lines (mostly tests).

- Harden `analysis_options.yaml`: `cancel_subscriptions`, `close_sinks`, `unawaited_futures`, `prefer_final_locals`, `avoid_dynamic_calls`.
- New tests (strict TDD, `flutter test`): `ServicioAlarmas` concurrent read-modify-write, alarm fire dedup across `refrescarProgramacion`, `PluriWaveAudioHandler` rapid source-switch race, export/import round-trip, `ServicioGrabacionRadio` error recovery.

### Slice 7 — Streaming resilience

Risk: MEDIUM. Effort: M. Est. < 380 lines (Dart only — no Kotlin changes).

The app uses `just_audio` (ExoPlayer on Android) via `PluriWaveAudioHandler`
(`lib/servicios/servicio_audio.dart`). The current implementation creates a fresh
`AudioPlayer` on every source switch (`_recrearPlayer`) and surfaces errors immediately
to the UI without any retry logic. A short network hiccup (a few seconds) therefore
causes an immediate error state and requires the user to manually re-tap play.

- Configure an enlarged ExoPlayer live-stream buffer (targeting ~15-30 s of buffered
  content) so brief network drops do not interrupt audible playback.
- Introduce `userIntent` tracking in `PluriWaveAudioHandler` to distinguish user-initiated
  pause/stop from network stalls.
- Add bounded exponential-backoff reconnection for network-class errors (`PlayerException`
  codes 2xxx) when `userIntent == playing`. Default: 5 retries, base 1 s, max 30 s.
- Surface `EstadoReproduccion.cargando` during reconnect attempts; surface the error only
  after retries are exhausted — no dialog spam for transient drops.
- Must not regress: alarm audio path (native `PluriWaveAlarmService`), recording
  (`ServicioGrabacionRadio` manages its own stream), sleep-timer fade-out.
- Unit tests required (strict TDD): backoff delay computation, `userIntent` transitions,
  reconnect suppressed on user stop, error emitted after max retries.

## Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Kotlin layer has never been compiled (`flutter build` never run per `alarm-clock-module` apply-progress). Slice 1/3 native edits may not compile. | HIGH | Keep native edits surgical; ask the user to run `flutter build` after Slice 1 before chaining further; do not run build ourselves (project constraint). |
| Android 14+ foreground-service behavior is version- and OEM-sensitive. | HIGH | Pair the `alarm` type with the matching permission exactly; verify against API 34 docs in design phase. |
| Channel sound is locked at channel creation; changing it may require recreating channels and could reset user notification settings. | MEDIUM | Design the channel-id/versioning strategy in the design phase; document the migration. |
| `EstadoRadio` split (Slice 4) has broad blast radius across screens. | HIGH | Land only after Slice 3 seams exist; keep backward-compatible getters; split into 4a/4b if the forecast exceeds 400 lines. |
| Injecting SharedPreferences touches many constructors. | MEDIUM | Provide backward-compatible defaults; introduce the injection in Slice 3 with tests. |
| Hero transition with `BackdropFilter` can flicker without a `HeroFlightShuttleBuilder`. | MEDIUM | Treat Hero work carefully in Slice 2/5; provide an explicit shuttle builder. |
| `alarm-clock-module` state drift (`tasks-ready` vs. existing apply-progress). | LOW | Reconcile at this change's archive time; out of scope to fix mid-flight. |

## Rollback plan

- Each slice is an independent PR; revert the slice's commit/branch to roll back without touching others.
- Slice 1 native changes are additive (manifest attributes/permission, channel config, an extra MethodChannel field); reverting restores the prior — but Android-14-broken — behavior, so prefer fixing forward.
- Slice 3 SharedPreferences injection uses backward-compatible defaults, so a partial revert leaves the app functional.
- Slice 4 keeps backward-compatible `EstadoRadio` getters during extraction; if a screen regresses, revert that screen's scoping commit independently.

## Success criteria

- [ ] Alarm fires on Android 14+ without `ForegroundServiceTypeException` (manual user build verification).
- [ ] Exactly one fire notification is posted per alarm event.
- [ ] Fire channels sound with alarm `AudioAttributes`; fallback station is used when the primary fails on the native path.
- [ ] Ringing screen offers 3/5/10 snooze that stays consistent with `EstadoAlarmas` (no divergence after sync). Snooze from the native notification while app killed also reschedules via `setAlarmClock` and syncs Flutter state on resume without waiting for the 60-second poll.
- [ ] Phone calls / other audio-focus events pause the radio.
- [ ] No localization call runs inside any `build()`.
- [ ] `EstadoRadio` no longer owns EQ / recording / search state; consuming screens use scoped rebuilds.
- [ ] All highlighted hardcoded colors replaced by tokens; favorite button and alarm images expose semantics; reduced-motion respected.
- [ ] Hardened lint set passes `flutter analyze`; the top-5 tests pass `flutter test`.
- [ ] Brief network drops (up to ~15-30 s) do not interrupt radio playback; automatic reconnection with bounded backoff recovers silently; alarm audio, recording, and sleep-timer paths are unaffected.