From 625d32c0f3538c6b04e4aa2ee25accbcb8d324fa Mon Sep 17 00:00:00 2001
From: BenStullsBets <ben@benbetson.us>
Date: Fri, 26 Jun 2026 13:28:17 -0700
Subject: [PATCH] diag(audio): live audio-status readout + native test player;
 stop swallowing play errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three blind fixes failed because headless browsers relax autoplay (can't reproduce)
and play() errors were swallowed. Instrument instead:
- #audio-status: live readout (playing/paused/blocked/media-error) under the toggle
- surface the play() rejection reason + element error (was .catch(()=>{}))
- 'Audio check' fieldset with a native <audio controls> on the soundtrack file, to
  test the file directly with zero app code in the path
Diagnostic only — no behavior change. 37 tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 simulator/static/app.js     | 27 ++++++++++++++++++++++++++-
 simulator/static/index.html |  9 +++++++++
 simulator/static/style.css  |  4 ++++
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/simulator/static/app.js b/simulator/static/app.js
index dca6b71..7cba5a1 100644
--- a/simulator/static/app.js
+++ b/simulator/static/app.js
@@ -920,8 +920,29 @@ function devLiveReload() {
 // (e.g. on an altitude change). audio on = the current scale's soundtrack.
 const aud = $("aud");
 let audUrl = null;                      // soundtrack url currently loaded (null = silent)
+let audLastErr = "";                    // last play() rejection / element error (for the readout)
 const FADE_MS = 500;
 
+// --- Live audio status readout (diagnostic) — so a "no sound" report is legible ---
+const AUD_ERR = ["", "aborted", "network", "decode", "format-not-supported"];
+function audioStatusText() {
+  if (!$("audio").checked) return "audio: off";
+  if (aud.error) return `audio: MEDIA ERROR ${aud.error.code} (${AUD_ERR[aud.error.code] || "?"})`;
+  if (audLastErr) return "audio: " + audLastErr;
+  if (aud.paused) return `audio: on, PAUSED (readyState ${aud.readyState})`;
+  return `audio: ▶ playing ${aud.currentTime.toFixed(1)}s · vol ${Math.round(aud.volume * 100)}% · rs ${aud.readyState}`;
+}
+function updateAudioStatus() {
+  const el = $("audio-status");
+  if (!el) return;
+  el.textContent = audioStatusText();
+  const playing = $("audio").checked && !aud.paused && !aud.error && !audLastErr;
+  el.classList.toggle("playing", playing);
+  el.classList.toggle("blocked", !!aud.error || !!audLastErr);
+}
+aud.addEventListener("error", () => { audLastErr = ""; updateAudioStatus(); });
+setInterval(updateAudioStatus, 400);
+
 function fadeVolume(el, to, ms, done) {
   // setInterval (not requestAnimationFrame): rAF throttles/pauses when the tab is
   // backgrounded, which would stall the gain ramp; a timer fires regardless.
@@ -947,8 +968,12 @@ function soundtrackUrl() {
 function playUrl(url) {
   aud.src = mediaUrl(url);
   aud.volume = 0;
+  audLastErr = "";
   const pr = aud.play();
-  if (pr) pr.catch(() => {});
+  if (pr) {
+    pr.then(() => { audLastErr = ""; updateAudioStatus(); })
+      .catch((e) => { audLastErr = "play BLOCKED: " + ((e && e.name) || e); updateAudioStatus(); });
+  }
   fadeVolume(aud, 1, FADE_MS);
 }
 
diff --git a/simulator/static/index.html b/simulator/static/index.html
index 974f3e1..7f33646 100644
--- a/simulator/static/index.html
+++ b/simulator/static/index.html
@@ -40,6 +40,15 @@
           <span class="dev-switch-track"><span class="dev-switch-thumb"></span></span>
           <span class="dev-switch-label">Audio</span>
         </label>
+        <div id="audio-status" class="audio-status">audio: off</div>
+      </fieldset>
+
+      <fieldset>
+        <legend>Audio check (diagnostic)</legend>
+        <p class="hint">Press play below to test the soundtrack file directly in the
+          browser's own player — this bypasses all app code. If you hear it here but
+          not from the Audio toggle, the file is fine and it's a code/autoplay issue.</p>
+        <audio id="aud-test" controls preload="auto" src="/media/audio/cosmos/pillars.loop.mp3" style="width:100%"></audio>
       </fieldset>
 
       <fieldset>
diff --git a/simulator/static/style.css b/simulator/static/style.css
index 35d47cc..6c96e27 100644
--- a/simulator/static/style.css
+++ b/simulator/static/style.css
@@ -49,6 +49,10 @@ main { display: flex; gap: 1rem; padding: 1rem; flex-wrap: wrap; align-items: fl
 .hidden { display: none; }
 /* Stack the two Output toggles (Video / Audio) with a little breathing room. */
 .dev-switch + .dev-switch { margin-top: 0.45rem; }
+/* Live audio status readout (diagnostic) — turns green when actually playing. */
+.audio-status { margin-top: 0.5rem; font: 11px/1.4 monospace; color: #9ab; }
+.audio-status.playing { color: #4e9; }
+.audio-status.blocked { color: #f97; }
 .panel { flex: 0 0 280px; display: flex; flex-direction: column; gap: 0.8rem;
          max-height: calc(100vh - 2rem); overflow-y: auto;
          position: sticky; top: 1rem; }