Add MP3Quran streaming to the device-local UI

[eirabie]

Summary

Owners can choose a reciter, recording edition and surah from MP3Quran in the device-local UI and play one surah on the speaker, including after closing the browser. Athan takes priority; interrupted Quran never automatically resumes. Catalog search coalesces busy edits, ignores obsolete results and restarts changed-query pagination at zero.

Play requires the current transient playback token. Stop, physical cancellation, Athan and reboot invalidate older tokens before a delayed Play can alter audio or allocate work. Stop remains reachable from Today, Settings and Quran during pending or unconfirmed Play. The browser tracks playback intent separately from catalog loading and reads fresh status after each current Play/Stop outcome. Earlier polls and obsolete callbacks cannot undo that observation or issue a corrective Stop against a newly due Athan. Uncertain Play never repeats automatically; unchanged-token idle keeps another Play blocked until fresh state or Stop resolves it.

A bounded background task resolves numeric selections outside the portable scheduler. The existing announcement pipeline uses certificate-verified HTTPS with validated provider hosts and redirects. Accepted starts reserve ownership and drain earlier speaker commands/pipelines before replacement. The pinned ESPHome mirrors differ only in the documented network-reader and guarded speaker-observation files.

Hardware impact

• No new required hardware
• Adds optional hardware
• Changes the required reference BOM

Existing Atom and Waveshare audio adapters expose the optional streaming capability. Displays remain optional.

Standalone impact

Stored Athan, calculations, settings and scheduling retain local operation and Home Assistant independence. Quran requires Wi-Fi and a valid clock. The development Play API immediately requires expected_playback_token; missing/stale tokens receive HTTP 409 and older cached pages must reload. /api/stop remains unchanged. Tokens are transient; browser storage remembers selection IDs only. Durable settings, prayer history and shared recordings retain their existing contract.

Testing

All 12 GitHub Actions checks passed on final head ef49735, including all 532 browser cases with the final gated fixture. Current-head CI run.

Automated validation: 18/18 UBSan CTests, 113/113 pinned Python tests without skips, 266/266 Chromium and 266/266 WebKit cases, 82/82 focused browser regressions plus 28/28 final ordering-fixture cases, all 13 ESPHome configuration checks, production Quran worker/HTTPS and production/isolated API checks, the pinned installer contract for both profiles, and resolved ESP-IDF request-line/header transmission checks.

New regressions cover Stop before delayed Play, the five-second idle poll before acknowledgement, late pre-command reads, obsolete successful replies, malformed/lost responses, incomplete/failed readback, reconnect, another client's or simulated physical Stop, reboot and Athan priority. They assert visible controls/feedback and final state, with no repeat Play or extra Stop. Prayer-occurrence tests explicitly gate Stop readback before releasing older Skip/Restore replies. Both original race scenarios fail against preserved baseline UI assets in Chromium and WebKit with the original three-ID API simulated.

All ten matched before/after firmware pairs pass the actual OTA capacity checks. Against pre-race-fix head aebc1d0, Quran-enabled images grow by 2,208–2,464 bytes; generic scheduler images are unchanged. The smallest remaining application budget is 198,096 bytes against the retained 1,572,864-byte limit. Both 2 MiB application slots and separate 3.5 MiB audio storage remain unchanged. Static RAM grows by 24 bytes on affected variants; runtime memory remains unqualified.

The validation report records measured source 7e1d505, matched sizes and historical comparisons. The streaming contract documents the API and qualification steps.

Hardware validation: no device access or firmware installation. Physical streaming, audible output, real device TLS/decoding, long-surah behavior, physical Stop/Athan interruption and concurrent heap/PSRAM/stack measurements remain release gates. Existing Athan evidence does not qualify Quran streaming.

Licensing/media

• No new third-party media or dependency licensing concerns
• Licensing/attribution details are documented in this PR

The ESPHome mirrors retain upstream licenses and attribution: GPLv3 for the C++ runtime; MIT for Python and other material. The UI credits MP3Quran, and the contract links its API/developer-use policy. No Quran recording is bundled or rehosted; future redistribution needs its own rights verification. These race fixes add no dependency or media.