test(audio): Playwright E2E (3 tests, skip-if-no-browser) + client robustness

E2E asserts in a real headless Chromium: white_noise loads the noise asset,
soundtrack loads the current scale's asset, and Visual=off fades video while
audio keeps playing. Driving it out surfaced + fixed three client issues:
- fadeVolume uses setInterval (rAF stalls when the tab is backgrounded)
- start gesture drops srcless priming (a click grants Chrome autoplay
  document-wide; priming empty <audio> only hung the handler / polluted state)
- applyAudio doesn't await play() (awaiting a srcless/buffering play can hang)
pyproject: [e2e] optional dep (pytest-playwright). Full suite 288 passed, 2 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pyproject.toml

@@ -24,3 +24,9 @@ sim = [
     "uvicorn[standard]>=0.29",
     "httpx>=0.27",
 ]
+# Playwright E2E browser tests (audio spec §9). Install with the browser binary:
+#   pip install -e '.[e2e]' && python -m playwright install chromium
+# The E2E suite skips cleanly when Playwright/Chromium is absent (headless box).
+e2e = [
+    "pytest-playwright>=0.4",
+]

simulator/static/app.js

@@ -908,15 +908,17 @@ let audioReady = false;                 // unlocked after the first user gesture
 const XFADE_MS = 600;                   // ~0.6s gain crossfade — "live", no busy ack (§7)
 
 function fadeVolume(el, to, ms) {
-  const from = el.volume, t0 = performance.now();
+  // setInterval (not requestAnimationFrame): rAF throttles/pauses when the tab is
+  // backgrounded, which would stall the gain ramp; a timer fires regardless.
+  const from = el.volume, steps = Math.max(1, Math.round(ms / 30));
+  let i = 0;
   return new Promise((resolve) => {
-    function tick(now) {
-      const k = Math.min(1, (now - t0) / ms);
-      el.volume = from + (to - from) * k;
-      if (k < 1) requestAnimationFrame(tick);
-      else resolve();
-    }
-    requestAnimationFrame(tick);
+    const iv = setInterval(() => {
+      i += 1;
+      const k = Math.min(1, i / steps);
+      el.volume = Math.min(1, Math.max(0, from + (to - from) * k));
+      if (k >= 1) { clearInterval(iv); resolve(); }
+    }, 30);
   });
 }
 
@@ -936,7 +938,7 @@ async function applyAudio(audio) {
   }
   audIdle.src = mediaUrl(url);          // absolute /media/... passes through mediaUrl
   audIdle.volume = 0;
-  await audIdle.play().catch(() => {});
+  audIdle.play().catch(() => {});       // start (fire-and-forget — awaiting can hang)
   await Promise.all([fadeVolume(audIdle, 1, XFADE_MS), fadeVolume(audActive, 0, XFADE_MS)]);
   audActive.pause();
   [audActive, audIdle] = [audIdle, audActive];   // swap roles
@@ -946,13 +948,15 @@ async function applyAudio(audio) {
 // full-screen by the operator; a one-time tap unlocks audio, then it follows
 // state (audio spec §8 — the documented launch step).
 function showStartGesture() {
+  if (audioReady || document.getElementById("start-gesture")) return;
   const ov = document.createElement("div");
   ov.id = "start-gesture";
   ov.textContent = "▶ tap to start sound";
-  ov.addEventListener("click", async () => {
+  ov.addEventListener("click", () => {
+    // A click anywhere on the page grants Chrome's autoplay permission
+    // document-wide for the session, so later programmatic play() is allowed —
+    // no per-element priming needed (priming srcless elements only pollutes state).
     audioReady = true;
-    // prime both elements within the gesture so later play() calls are allowed
-    for (const el of [audA, audB]) { try { await el.play(); el.pause(); } catch (_) {} }
     ov.remove();
     audUrl = null;                       // force the next applyAudio to (re)load
     update();                            // re-apply current state, now with audio

tests/test_e2e_audio.py

@@ -0,0 +1,98 @@
+"""Playwright E2E for the audio layer (audio spec §9). Skips cleanly when
+Playwright or its browser binary is absent (the headless dev box) — the unit +
+contract tiers cover the logic; this asserts the rendered <audio> element src and
+playback survives a Visual fade. Runs at the PPE stage where a browser exists.
+
+Install:  pip install -e '.[e2e]' && python -m playwright install chromium
+"""
+import socket
+import threading
+import time
+from contextlib import closing
+
+import pytest
+
+# Skip the whole module unless Playwright is importable.
+pytest.importorskip("playwright.sync_api")
+
+
+def _free_port() -> int:
+    with closing(socket.socket()) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def app_url():
+    import uvicorn
+
+    from simulator.app import app
+
+    port = _free_port()
+    config = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="error")
+    server = uvicorn.Server(config)
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+    for _ in range(50):
+        if server.started:
+            break
+        time.sleep(0.1)
+    if not server.started:
+        pytest.skip("uvicorn did not start")
+    yield f"http://127.0.0.1:{port}"
+    server.should_exit = True
+    thread.join(timeout=5)
+
+
+@pytest.fixture
+def page(app_url):
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        try:
+            # Headless Chromium blocks media playback without a real audio device;
+            # this flag lets play() actually start so `paused` is meaningful (the
+            # spec §9 asserts playback via element src/paused, not a waveform).
+            browser = p.chromium.launch(args=["--autoplay-policy=no-user-gesture-required"])
+        except Exception as exc:                       # no browser binary installed
+            pytest.skip(f"chromium not available: {exc}")
+        pg = browser.new_page()
+        pg.goto(app_url)
+        pg.click("#start-gesture")                     # unlock autoplay
+        yield pg
+        browser.close()
+
+
+def test_white_noise_loads_the_noise_asset(page):
+    page.select_option("#audio", "white_noise")
+    page.wait_for_function(
+        "['audA','audB'].some(id => "
+        "document.getElementById(id).src.includes('/media/audio/noise/pink.mp3'))"
+    )
+
+
+def test_soundtrack_loads_the_current_scale_asset(page):
+    # initial altitude is cosmos (index 0) → soundtrack resolves its scale asset,
+    # not the noise bed (the altitude-coupling itself is covered at the API tier)
+    page.select_option("#audio", "soundtrack")
+    page.wait_for_function(
+        "['audA','audB'].some(id => {"
+        "  const s = document.getElementById(id).src;"
+        "  return /\\/media\\/audio\\/.+\\.mp3/.test(s) && !s.includes('noise');"
+        "})"
+    )
+
+
+def test_visual_off_keeps_audio_and_fades_video(page):
+    page.select_option("#audio", "white_noise")
+    page.wait_for_function(
+        "['audA','audB'].some(id => "
+        "document.getElementById(id).src.includes('/media/audio/noise/pink.mp3'))"
+    )
+    page.uncheck("#visual")
+    page.wait_for_selector("#black:not(.hidden)")       # video faded to black
+    playing = page.evaluate(
+        "['audA','audB'].some(id => "
+        "{const a = document.getElementById(id); return !a.paused && !!a.src;})"
+    )
+    assert playing is True                               # audio survives the video fade