From 79eb5dd0387dfc0f0bad9d3ef83f23de9b09534e Mon Sep 17 00:00:00 2001
From: Tobias Gesellchen <tobias@gesellix.de>
Date: Sun, 30 Aug 2026 20:55:35 +0200
Subject: [PATCH] docs(player): restore the async=false rationale and its
 regression test

PR #664 rewrote the comment explaining why the dynamically-inserted
es-module-shims script sets async = false, replacing the actual
execution-order reasoning (it must run before the deferred
type="module" script below, without blocking the parser for browsers
that never reach this branch) with a vaguer, inaccurate description
("inspects module graphs that fail static linking") that doesn't
explain the async choice at all. It also dropped the regression test
asserting .async = false is present, so a future "cleanup" removing
that line would go uncaught -- and the misleading comment no longer
warns against doing so.

The actual .async = false code was untouched by #664; this only
restores the documentation and its test coverage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 pkg/service/soundtouchweb/static/index.html            | 8 ++++----
 pkg/service/soundtouchweb/static_compatibility_test.go | 9 +++++++--
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/pkg/service/soundtouchweb/static/index.html b/pkg/service/soundtouchweb/static/index.html
index 9ddef7a2..94f80daf 100644
--- a/pkg/service/soundtouchweb/static/index.html
+++ b/pkg/service/soundtouchweb/static/index.html
@@ -17,10 +17,10 @@
         that already support import maps natively. Feature-detect instead,
         so only a browser that actually lacks support ever fetches it.
         Inserted via the DOM rather than document.write (deprecated, and
-        subject to browser interventions that can silently drop it).
-        After initialization, es-module-shims inspects module graphs that fail
-        static linking, so browsers without import maps can resolve the bare
-        imports below without penalizing native-capable ones.
+        subject to browser interventions that can silently drop it), with
+        async explicitly set to false so it still executes before the
+        deferred `type="module"` script below runs, without blocking the
+        parser for the vast majority that never reach this branch.
         -->
         <script>
             if (!(window.HTMLScriptElement && HTMLScriptElement.supports && HTMLScriptElement.supports('importmap'))) {
diff --git a/pkg/service/soundtouchweb/static_compatibility_test.go b/pkg/service/soundtouchweb/static_compatibility_test.go
index 9183152d..f52bf2ec 100644
--- a/pkg/service/soundtouchweb/static_compatibility_test.go
+++ b/pkg/service/soundtouchweb/static_compatibility_test.go
@@ -11,8 +11,9 @@ import (
 // (added in Safari 16.4), so the page loaded blank there. es-module-shims
 // polyfills import map resolution for such browsers, but is an ~80KB
 // uncompressed download, so it must be feature-detected and only injected
-// for a browser that actually lacks HTMLScriptElement.supports('importmap') --
-// not loaded unconditionally for every browser.
+// for a browser that actually lacks HTMLScriptElement.supports('importmap'),
+// before the import map is parsed -- not loaded unconditionally for every
+// browser.
 func TestIndexPolyfillsImportMapsForOlderBrowsers(t *testing.T) {
 	index, err := fs.ReadFile(StaticFS, "static/index.html")
 	if err != nil {
@@ -27,6 +28,10 @@ func TestIndexPolyfillsImportMapsForOlderBrowsers(t *testing.T) {
 		t.Fatal("index.html must not call document.write() (deprecated, subject to browser interventions); use DOM insertion instead")
 	}
 
+	if !bytes.Contains(index, []byte(`.async = false`)) {
+		t.Fatal("the dynamically-inserted es-module-shims script must set async = false to preserve execution order")
+	}
+
 	shimIdx := bytes.Index(index, []byte(`esModuleShimsScript.src = '/app/static/lib/es-module-shims.js';`))
 	if shimIdx == -1 {
 		t.Fatal("index.html does not conditionally inject es-module-shims.js")