pluriwave/openspec/changes/archive/2026-07-19-auto-media-art-quality/tasks.md

Tasks: auto-media-art-quality

Strict TDD active for Dart layers. Behavioral task = RED (failing test) -> GREEN (minimal impl) -> REFACTOR (cleanup, still green). Native/XML/PNG/build.gradle tasks have no flutter test coverage (no Android build env) — marked [static-review-only]; flutter build/flutter run/flutter analyze MUST NOT be executed in this environment (they hang). "Parallel" tasks have no file overlap with concurrently-listed siblings; "Sequential" tasks depend on a prior task's output.

Affected files: lib/servicios/navegacion_auto.dart, android/app/src/main/res/drawable/station_art_aurora.png, android/app/src/main/res/drawable/station_art_cosmic.png, android/app/src/main/res/drawable/station_art_pulse.png, android/app/src/main/res/drawable/station_art_nova.png, android/app/src/main/res/drawable/default_station_art.png (deleted), test/servicios/navegacion_auto_test.dart.

Baseline (verified against live code, not trusted from spec/design prose):

• lib/servicios/navegacion_auto.dart:12-17 — _defaultArtUri const, to be dropped.
• lib/servicios/navegacion_auto.dart:102-108 — itemEmisora(), sets artUri only, no displaySubtitle.
• lib/servicios/navegacion_auto.dart:110-113 — _artUriPara(e): null/empty favicon check only, no URL-shape validation.
• lib/widgets/tarjeta_emisora.dart:361-370 — _fallbackArtFor(seed): [aurora, cosmic, pulse, nova] order, seed.codeUnits.fold<int>(0,(a,b)=>a+b) % arts.length, assets at assets/images/station_art_<name>.png.
• lib/modelos/emisora.dart:60-78 — Emisora.fromMap (SQLite favorites row) assigns favicon: map['favicon'] as String? with no sanitization (unlike Emisora.fromApi:47, which runs _nonEmpty). Confirms design.md's claim: malformed/whitespace favicon values from favorites rows reach the tree unfiltered today.
• android/app/src/main/res/drawable/default_station_art.png exists (only PNG currently in that directory) — to be deleted.
• assets/images/station_art_{aurora,cosmic,pulse,nova}.png exist — source images to copy into android/app/src/main/res/drawable/.
• android/app/build.gradle.kts:34 — applicationId = "es.freetimelab.pluriwave", matches the existing android.resource://es.freetimelab.pluriwave/drawable/... authority used by _defaultArtUri and the design's new station_art_<name> URIs. No manifest/build.gradle change is needed — adding res/drawable PNGs requires no manifest declaration (unlike the parent change's automotive_app_desc.xml meta-data, which pointed at an XML resource).
• test/servicios/navegacion_auto_test.dart:45-63 — existing test asserts fallback to _defaultArtUri on null/empty favicon; must be replaced (not just extended) since _defaultArtUri is retired.
• audio_service-0.18.18 (lib/audio_service.dart:622): MediaItem.displaySubtitle is String? — nullable, safe to pass a nullable subtituloCalidad(e) result directly.

---

Phase 1 — Favicon validity gate (faviconUsable)

1.1 [x] [RED] faviconUsable rejects malformed/non-http(s) favicons, accepts valid http(s) (Sequential — first task, defines the seam)

• Satisfies: Design Decision "Case B detection" (static validity gate); Spec "Playable Item Metadata" / Scenario "Station's logo URL is present but unreachable (Case B)" (malformed subset).
• File: test/servicios/navegacion_auto_test.dart.
• New group('faviconUsable', ...). Table-driven cases, each asserting faviconUsable(input) == expected:
  • null → false
  • '' → false
  • ' ' (whitespace only) → false
  • 'ftp://cdn.example.com/logo.png' (non-http(s) scheme) → false
  • 'cdn.example.com/logo.png' (no scheme, bare host) → false
  • 'http://' (scheme present, no authority) → false
  • '/relative/path/logo.png' (relative, no scheme) → false
  • 'not a url at all $$$ ///' (unparseable/garbage) → false
  • 'http://cdn.example.com/logo.png' → true
  • 'https://cdn.example.com/logo.png' → true
• Run: fails (faviconUsable not implemented / not exported).

1.2 [x] [GREEN] Implement faviconUsable (Sequential — depends on 1.1)

• File: lib/servicios/navegacion_auto.dart.
• Top-level (or static) bool faviconUsable(String? favicon): trim; if null/empty after trim → false. Uri.tryParse(trimmed); if parse fails → false. Require scheme == 'http' || scheme == 'https' AND uri.hasAuthority (non-empty host) → true, else false.
• Run: 1.1 passes.

---

Phase 2 — Rotation parity (indiceArtePara)

2.1 [x] [RED] indiceArtePara matches tarjeta_emisora.dart's _fallbackArtFor formula and order (Sequential — depends on Phase 1 file existing, independent logic)

• Satisfies: Design Decision "Fallback-art selection — port _fallbackArtFor verbatim"; Spec "Fallback art matches phone-UI per-station selection".
• File: test/servicios/navegacion_auto_test.dart.
• New group('indiceArtePara', ...). Assert indiceArtePara(seed) for a handful of sample uuids reproduces seed.codeUnits.fold<int>(0,(a,b)=>a+b) % 4 computed inline in the test (do not hardcode indices without showing the formula), covering at least: an empty string ('' → index 0, since fold over no elements is 0), a short seed, and a real-looking uuid.
• Assert the canonical order constant (or equivalent) used for mapping index→name is exactly ['aurora', 'cosmic', 'pulse', 'nova'], matching tarjeta_emisora.dart:362-367.
• Run: fails.

2.2 [x] [GREEN] Implement indiceArtePara + canonical art-name list (Sequential — depends on 2.1)

• File: lib/servicios/navegacion_auto.dart.
• int indiceArtePara(String seed) => seed.codeUnits.fold<int>(0, (a, b) => a + b) % 4; — verbatim port, same formula as tarjeta_emisora.dart:368.
• Private const _nombresArte = ['aurora', 'cosmic', 'pulse', 'nova'] — same order as tarjeta_emisora.dart:363-366. Add a code comment cross-linking to tarjeta_emisora.dart's _fallbackArtFor to mitigate reorder drift (per design.md's stated mitigation, since there is no structural enforcement of order — see Phase 6 for the added test-level guard).
• Run: 2.1 passes.

---

Phase 3 — artUriPara integration (favicon gate + rotating drawable, retires _defaultArtUri)

3.1 [x] [RED] artUriPara returns the favicon when usable, a rotating station_art_<name> drawable URI otherwise (Sequential — depends on 1.2, 2.2)

• Satisfies: Design Decision 1 (validity gate) + Decision 2 (rotation) combined at the artUriPara seam; Spec "Playable Item Metadata" (all 5 scenarios).
• File: test/servicios/navegacion_auto_test.dart.
• New group('artUriPara', ...):
  • Valid https:// favicon → artUriPara(e) == e.favicon.
  • null favicon → artUriPara(e) == 'android.resource://es.freetimelab.pluriwave/drawable/station_art_<expected-name-for-uuid>' (compute expected name via indiceArtePara(e.uuid) + canonical order in the test, not a hardcoded guess).
  • '' favicon → same rotating-drawable behavior as null.
  • Malformed favicon (e.g. 'ftp://x/y.png', 'not a url') → same rotating-drawable behavior (Case B malformed subset).
  • Two different uuids that hash to different indices → assert their resolved artUriPara values differ (parity smoke check, not full enumeration — that's Phase 6).
  • Same uuid called twice → identical result (determinism).
• Run: fails.

3.2 [x] [GREEN] Implement artUriPara; drop _defaultArtUri and the old _artUriPara (Sequential — depends on 3.1)

• File: lib/servicios/navegacion_auto.dart.
• Replace _artUriPara (lines 110-113) with String artUriPara(Emisora e) => faviconUsable(e.favicon) ? e.favicon! : 'android.resource://es.freetimelab.pluriwave/drawable/station_art_${_nombresArte[indiceArtePara(e.uuid)]}';.
• Delete _defaultArtUri const (lines 12-17) — dead now that rotation is total (design.md Decision 3: uuid always present, empty-uuid → index 0 → aurora, no 5th fallback reachable).
• Update itemEmisora() (line 106) call site from _artUriPara(e) to artUriPara(e).
• Run: 3.1 passes.

3.3 [x] [GREEN] Replace the obsolete default-art test in itemEmisora group (Sequential — depends on 3.2)

• File: test/servicios/navegacion_auto_test.dart.
• Replace the test at lines 45-63 ('cae al arte por defecto cuando el favicon es null o vacío', which asserts the now-deleted _defaultArtUri literal) with an assertion that both null- and empty-favicon cases resolve to the correct rotating station_art_<name> URI per indiceArtePara, consistent with the Phase 3.1 cases.
• Run: full navegacion_auto_test.dart green.

---

Phase 4 — Quality subtitle (subtituloCalidad)

4.1 [x] [RED] subtituloCalidad matrix: both known, codec-only, bitrate-only, both unknown, bitrate<=0 (Sequential — independent of Phase 1-3, same file)

• Satisfies: Design Decision "displaySubtitle quality format"; Spec "Station has known codec and bitrate" / "Station has unknown codec or bitrate".
• File: test/servicios/navegacion_auto_test.dart.
• New group('subtituloCalidad', ...), one case per design.md's table plus the bitrate <= 0 edge (Radio Browser stores 0 for unknown):
  • codec: 'mp3', bitrate: 128 → '128 kbps · MP3' (codec upper-cased; · is U+00B7).
  • codec: null, bitrate: 128 → '128 kbps'.
  • codec: 'mp3', bitrate: null → 'MP3'.
  • codec: 'mp3', bitrate: 0 → 'MP3' (bitrate ≤ 0 treated as unknown).
  • codec: null, bitrate: null → null (not '', not the literal string 'null').
  • codec: null, bitrate: 0 → null.
  • codec: ' ' (whitespace-only codec), bitrate: null → null (whitespace codec counts as unknown per design.md's "empty/whitespace codec count as unknown").
  • codec: ' mp3 ' (whitespace-padded codec), bitrate: 128 → '128 kbps · MP3' (trimmed).
• Explicitly assert none of the outputs contain the substring 'null' (defends the "never render literal null" requirement directly, not just via exact-match).
• Run: fails.

4.2 [x] [GREEN] Implement subtituloCalidad (Sequential — depends on 4.1)

• File: lib/servicios/navegacion_auto.dart.
• String? subtituloCalidad(Emisora e): normalize codec via trim().toUpperCase(), treat empty-after-trim as unknown; treat bitrate == null || bitrate! <= 0 as unknown.
• Both known → '$bitrate kbps · $codecUpper'. Bitrate only → '$bitrate kbps'. Codec only → codecUpper. Both unknown → null (never '', never a string containing 'null').
• Run: 4.1 passes.

---

Phase 5 — itemEmisora wiring (displaySubtitle)

5.1 [x] [RED] itemEmisora sets displaySubtitle from subtituloCalidad; omits it (leaves null) when both unknown (Sequential — depends on 3.2, 4.2)

• Satisfies: Spec "Browsable Media Tree" / Scenario "Station has known codec and bitrate" + "Station has unknown codec or bitrate", applied at the leaf-building integration point.
• File: test/servicios/navegacion_auto_test.dart.
• Extend the existing group('ConstructorArbolAuto.itemEmisora', ...):
  • Emisora with codec: 'mp3', bitrate: 128 → item.displaySubtitle == '128 kbps · MP3'.
  • Emisora with codec: null, bitrate: null → item.displaySubtitle == null.
• Run: fails (current itemEmisora at lines 102-108 never sets displaySubtitle).

5.2 [x] [GREEN] Wire displaySubtitle into itemEmisora (Sequential — depends on 5.1)

• File: lib/servicios/navegacion_auto.dart.
• Add displaySubtitle: subtituloCalidad(e) to the MediaItem(...) construction in itemEmisora (lines 102-108), alongside the existing artUri: Uri.parse(artUriPara(e)).
• Run: 5.1 passes; full itemEmisora group green.

5.3 [x] [REFACTOR] Cleanup pass on navegacion_auto.dart (Sequential — depends on 3.2, 4.2, 5.2 all green)

• Re-read top to bottom: doc-comment faviconUsable/artUriPara/indiceArtePara/subtituloCalidad per the Design "Interfaces / Contracts" signatures; confirm no leftover reference to _defaultArtUri or the old _artUriPara anywhere in the file (grep the file for both identifiers — should return zero matches).
• Full navegacion_auto_test.dart suite stays green.

---

Phase 6 — Downstream coverage & drift guards (favorites sanitization gap, phone/car order parity)

6.1 [x] [RED→GREEN, coverage-only] Test that faviconUsable/artUriPara catches the unsanitized Emisora.fromMap favicon gap (Sequential — depends on 3.2)

• Satisfies: Design Decision 1's explicit callout that Emisora.fromMap (SQLite favorites, lib/modelos/emisora.dart:60-78) does not sanitize favicon (no _nonEmpty, unlike Emisora.fromApi:47) — confirms the validity gate is the correct place to catch this, rather than silently assuming it.
• File: test/servicios/navegacion_auto_test.dart.
• Build an Emisora via Emisora.fromMap({...}) (not the _emisora() test helper) with a malformed/whitespace favicon value in the map (e.g. 'favicon': ' ', or 'favicon': 'not-a-url') that fromMap passes through unsanitized. Assert artUriPara(builtEmisora) resolves to a rotating station_art_<name> URI, not the malformed string.
• This is a regression-style test, not a design-doc gap-fix: it documents the current architecture's division of responsibility (sanitize-at-read-boundary vs sanitize-at-render-boundary) and pins it in place. If it fails, fromMap started sanitizing (fine) or the gate regressed (not fine) — either way the test makes the boundary explicit instead of assumed.
• Run: passes on first run once Phase 3 lands (this is a characterization test of already-implemented behavior, so RED/GREEN collapses to a single assertion pass — still write it before considering Phase 3 "done" in spirit, but there is no separate implementation step).

6.2 [x] [RED→GREEN, coverage-only] Parity guard: phone-UI asset order and Android-Auto drawable order stay identical (Sequential — depends on 2.2)

• Satisfies: Design.md's explicitly flagged risk — "reorder drift" between tarjeta_emisora.dart's _fallbackArtFor asset list and navegacion_auto.dart's _nombresArte list, called out as having "no structural enforcement," mitigated only by a code comment + this test.
• File: test/servicios/navegacion_auto_test.dart.
• New group('parity: phone/auto art order', ...). Since _fallbackArtFor's asset list is private to tarjeta_emisora.dart and returns assets/... paths (not directly importable/comparable in form), this test hardcodes the canonical order ['aurora', 'cosmic', 'pulse', 'nova'] once, with a comment explaining it must be kept in sync with tarjeta_emisora.dart:363-367's literal list, and asserts navegacion_auto.dart's exposed art-name list/mapping matches it element-for-element, in order.
• This does not eliminate drift risk (design.md accepts that — no structural enforcement chosen) but ensures any future reorder in navegacion_auto.dart alone breaks a test immediately; a reorder in tarjeta_emisora.dart alone still requires a human to update this test's hardcoded list (documented limitation, same as design.md's own acknowledgment).
• Run: passes once Phase 2 lands.

---

Phase 7 — Android native drawables (retiring default_station_art.png) [static-review-only — no Android build env, flutter build/flutter run/flutter analyze MUST NOT be executed]

7.1 [x] Add 4 native drawable copies (Parallel with 7.2 — different files within the same directory, no overlapping content)

• Satisfies: Spec "Fallback art matches phone-UI per-station selection" + "Fallback art is on-brand, not the launcher icon"; Design "Native drawables + retire default_station_art.png".
• Files: android/app/src/main/res/drawable/station_art_aurora.png, station_art_cosmic.png, station_art_pulse.png, station_art_nova.png (new binary assets).
• Copy verbatim from assets/images/station_art_{aurora,cosmic,pulse,nova}.png — same technique the parent change used for default_station_art.png (Phase 6.3 there).
• Static review: filenames match exactly (case-sensitive) the names produced by _nombresArte/indiceArtePara in navegacion_auto.dart (station_art_<name>, no extension in the android.resource:// URI), matching the pattern already verified working for default_station_art.

7.2 [x] Delete default_station_art.png (Parallel with 7.1 — different file)

• Satisfies: Design Decision "Native drawables + retire default_station_art.png" — rotation is total (uuid always present, empty-uuid → index 0 → aurora), so this drawable is unreachable dead weight and a byte-for-byte launcher-icon lookalike (parent change's WARNING #2).
• File: android/app/src/main/res/drawable/default_station_art.png (delete).
• Static review: confirm no remaining reference to default_station_art anywhere in the codebase after Phase 3.2 removes the Dart-side const (grep default_station_art across lib/ and android/ — should return zero matches after this task, other than this tasks.md/spec/design history).

7.3 [x] Verify applicationId/authority match for the new drawable URIs (Parallel with 7.1/7.2 — read-only verification, no file changes expected)

• Satisfies: precedent from parent change's WARNING notes (authority/applicationId must match for android.resource:// URIs to resolve).
• Already verified during task planning: android/app/build.gradle.kts:34 sets applicationId = "es.freetimelab.pluriwave", matching the authority segment (es.freetimelab.pluriwave) used in both the retired _defaultArtUri and the new station_art_<name> URIs built in artUriPara (Phase 3.2). No manifest or build.gradle change is required — adding PNGs to res/drawable needs no manifest declaration, unlike the parent change's automotive_app_desc.xml meta-data entry (a res/xml resource that did require a <meta-data> reference).
• Static review only: re-confirm this holds at apply time (applicationId unchanged) before closing Phase 7.

---

Phase 8 — Full regression sweep (Sequential — depends on all prior phases green)

8.1 [x] Run full flutter test suite (or the closest safe equivalent in this environment)

• Satisfies: Design "Testing Strategy" unit rows; Spec-level success criteria across all modified scenarios.
• Run the entire suite to catch cross-file regressions, not just navegacion_auto_test.dart.
• Expected deviation (execution constraint, same as parent change): if a full-suite run is not safely executable in this environment, run targeted files instead — at minimum navegacion_auto_test.dart in full — and record which files were actually exercised. A genuine full-suite run is recommended before merge/CI, same caveat the parent change recorded.

8.2 [x] flutter analyze — DO NOT RUN in this environment

• DEVIATION (execution constraint, same as parent change): flutter analyze hangs in this environment and MUST NOT be executed. Perform manual static review instead: confirm artUriPara, faviconUsable, indiceArtePara, subtituloCalidad are used (no unused-symbol risk), confirm no leftover references to _defaultArtUri/old _artUriPara, confirm all new code compiles implicitly by virtue of the modified file's tests passing in 8.1. A real flutter analyze pass is still recommended before merge/CI.

8.3 [x] flutter build/flutter run — DO NOT RUN in this environment

• DEVIATION (execution constraint, same as parent change): these commands hang in this environment and MUST NOT be executed. Phase 7's native drawable work is static-review-only for this reason; a real Android build (or DHU session) is required before shipping to confirm the 4 new station_art_* drawables resolve correctly via android.resource:// (Design's remaining Open Question).

8.4 [x] Manual DHU verification note (optional, non-blocking, not coded)

• Satisfies: Design "Testing Strategy" manual row; Design "Open Questions" (confirm OS art loader accepts android.resource:// for the 4 new drawables).
• Record in the commit/PR description that a Desktop Head Unit (or real car) session is recommended before shipping to visually confirm: (a) all 4 rotating arts render correctly per station, (b) displaySubtitle quality text renders as expected on the browse row, (c) no stale default_station_art reference lingers anywhere in the built APK's resources.

---

Review Workload Forecast

• Files touched: lib/servicios/navegacion_auto.dart (~40-60 changed/added lines: drop _defaultArtUri (~6 lines removed), add faviconUsable, indiceArtePara, _nombresArte, artUriPara, subtituloCalidad (~35-45 lines added), one-line displaySubtitle wiring in itemEmisora), test/servicios/navegacion_auto_test.dart (~130-170 added/changed lines: 6 new test groups — faviconUsable, indiceArtePara, artUriPara, subtituloCalidad, itemEmisora extension, parity guard — plus replacing the obsolete default-art test), 4 new binary PNGs under android/app/src/main/res/drawable/ (station_art_aurora/cosmic/pulse/nova.png, copied from existing assets/images/, zero text-line cost), 1 binary deletion (default_station_art.png).
• Estimated total changed/added lines (text only, excluding binary PNG bytes): roughly 170-230 lines.
• Chained PRs recommended: No — this is well inside the 400-line single-PR budget even with generous test-heavy estimates. No manifest/build.gradle changes are needed (verified: applicationId already matches, res/drawable PNGs need no manifest declaration), which removes the one file class that made the parent change's Phase 6 riskier.
• 400-line budget risk: Low. Total estimate (~170-230 text lines + 4 binary adds + 1 binary delete) sits comfortably under budget as a single commit/PR.
• Decision needed before apply: No — proceed as a single delivery. The only structural caveat carried over from the parent change is that Phase 7 (native drawables) remains static-review-only (no Android build env here), same constraint class as the parent change's Phase 6, but it does not change file-count or line-count risk enough to warrant chaining.
• Ownership/dependency note: Phase 1 (validity gate) and Phase 2 (rotation) are independent of each other and can proceed in any order — both are prerequisites for Phase 3 (artUriPara integration), which retires _defaultArtUri. Phase 4 (subtitle) is fully independent of Phases 1-3 (different concern, same file) and could be done in parallel by a second contributor without conflict risk beyond normal same-file merge care. Phase 5 depends on both Phase 3 and Phase 4 landing. Phase 6 is coverage-only and depends on Phase 3 (6.1) and Phase 2 (6.2) respectively but not on each other. Phase 7 has zero Dart dependency and may be done anytime in parallel with all Dart phases (mirrors the parent change's Phase 6 independence). Phase 8 is a hard sequential gate depending on everything above.