From 4bf4ec064a4f2231c873f16c9598a26d3c541fdf Mon Sep 17 00:00:00 2001
From: byrongamatos <xasiklas@gmail.com>
Date: Sat, 11 Jul 2026 19:40:21 +0200
Subject: [PATCH] refactor(app): give the <audio> element a module of its own
 (R3a)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

static/js/audio-el.js — one exported const. app.js's diff is 5 lines.
This is a HINGE, not a carve: nothing shrinks, but almost everything left in
app.js is blocked behind it.

WHY. `audio` is `document.getElementById('audio')` with 162 references in app.js
and 173 outside any one cluster. Every remaining cluster measured — settings,
app-updates, count-in (208 fns), exit-confirm (212), library-render (220) — lists
`audio` among its inbound symbols, because they all touch playback and playback
reaches for the element directly. A module that needs it cannot import app.js to
get it (that closes a cycle and fails import-x/no-cycle), so today the only way to
carve any of them would be a host seam — the exact thing #878 had to build and
#880 had to tear out.

WHY IT'S SAFE. `audio` is a `const` and is NEVER reassigned anywhere in core, so a
read-only import binding is exactly right and no state container is needed. The
162 call sites are untouched — the binding keeps its name, it is just imported
instead of declared. (Contrast the reassigned scalars — isPlaying, _avOffsetMs —
which CANNOT be shared this way: an imported binding cannot be written to. Those
still need containers, and that is the next problem, not this one.)

TIMING. app.js is <script type="module">, so it evaluates after the HTML is parsed
and its imports evaluate just before its body — the same moment app.js used to run
this exact lookup. If the element had not been in the document, `audio` would be
null and app.js's top-level `audio.addEventListener(...)` calls would throw and
kill the module. They don't.

VERIFIED WITH REAL PLAYBACK, not a boot check. A/B against origin/main in two
browsers: app alive with zero page errors (which is itself the proof the import
resolved), #audio is an AUDIO element, togglePlay/seekBy live, and playSong() on a
real library song sets audio.src and the element reports a duration — IDENTICAL on
both sides.

pytest 2396, node 1038/1038, ESLint 0 (no-cycle clean), tailwind clean, Codex 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 static/app.js         |  5 ++++-
 static/js/audio-el.js | 17 +++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 static/js/audio-el.js

diff --git a/static/app.js b/static/app.js
index b70ad34c..16595a79 100644
--- a/static/app.js
+++ b/static/app.js
@@ -39,6 +39,7 @@ import {
     exportSettings,
     importSettings,
 } from './js/settings-io.js';
+import { audio } from './js/audio-el.js';
 
 // Demo analytics — real impl set by demo.js; no-op in normal builds
 window.feedBackDemoTrack = window.feedBackDemoTrack ?? null;
@@ -3419,7 +3420,9 @@ function retuneSong(filename, title, tuning, target) {
 }
 
 // ── Player ───────────────────────────────────────────────────────────────
-const audio = document.getElementById('audio');
+// `audio` now lives in ./js/audio-el.js so carved-out modules can reach the
+// player without importing app.js back (which would close a cycle). Same
+// element, same handle, same lookup — just imported instead of declared here.
 let isPlaying = false;
 let _lastSongPositionEventAt = 0;
 
diff --git a/static/js/audio-el.js b/static/js/audio-el.js
new file mode 100644
index 00000000..bfca40df
--- /dev/null
+++ b/static/js/audio-el.js
@@ -0,0 +1,17 @@
+// The one <audio> element the whole app plays through.
+//
+// This exists so that code carved out of app.js can reach the player without
+// importing app.js back — which would close a cycle and fail the import-x/no-cycle
+// gate. It is the same handle app.js has always held (`document.getElementById`
+// on the element in the shell), just given a home of its own.
+//
+// It is deliberately a `const`, and it is never reassigned anywhere in core — so a
+// read-only import binding is exactly right, and no state container is needed.
+// (Contrast the reassigned scalars — isPlaying, _avOffsetMs, … — which cannot be
+// shared this way, because an imported binding cannot be written to.)
+//
+// Module scripts evaluate after the HTML is parsed, so the element is already in
+// the document by the time this runs. app.js is loaded as <script type="module">,
+// and its imports evaluate before its body — the same point at which app.js used
+// to run this exact lookup itself.
+export const audio = document.getElementById('audio');