1 files changed, 38 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-05-28-music-autoplay-design.md b/docs/superpowers/specs/2026-05-28-music-autoplay-design.md
new file mode 100644
index 0000000..d9fc001
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-28-music-autoplay-design.md
@@ -0,0 +1,38 @@
+# Music Autoplay on Startup
+
+## Summary
+
+On page load, immediately attempt `bgm.play()`. If the browser blocks it (autoplay policy), install a one-time `click` listener on `document` that starts the music on the user's first interaction anywhere on the page. The toggle button state (`musicOn`, button icon, label, background) is updated to reflect playing status in both code paths.
+
+## Change
+
+Single location: the music toggle block in `index.html` (~line 737), just after `bgm.volume = 0.2` is set and the toggle button is wired up.
+
+```js
+// attempt immediate autoplay; fall back to first-interaction start
+const track = MUSIC[Aero.getTheme()] || MUSIC.aero;
+bgm.src = track.src;
+bgm.load();
+bgm.play().then(() => {
+  musicOn = true;
+  mtBtn.textContent = '❚❚';
+  mtLabel.textContent = track.label;
+  mtBtn.style.background = 'radial-gradient(circle at 30% 25%,white,oklch(75% 0.14 55) 60%,oklch(55% 0.15 35))';
+}).catch(() => {
+  // autoplay blocked — start on first user gesture
+  document.addEventListener('click', function startOnGesture() {
+    document.removeEventListener('click', startOnGesture);
+    bgm.play().then(() => {
+      musicOn = true;
+      mtBtn.textContent = '❚❚';
+      mtLabel.textContent = (MUSIC[Aero.getTheme()] || MUSIC.aero).label;
+      mtBtn.style.background = 'radial-gradient(circle at 30% 25%,white,oklch(75% 0.14 55) 60%,oklch(55% 0.15 35))';
+    });
+  }, { once: true });
+});
+```
+
+## Error handling
+
+- If `bgm.play()` fails in both paths (e.g., no audio file), it fails silently — no UI disruption.
+- The manual toggle button continues to work normally regardless of autoplay outcome.