From 611955732f4ce4696ffe09e241e6edad76cf64ca Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:15:07 -0600
Subject: [PATCH 1/6] fix: hide mode-inappropriate buttons, dedupe lyrics
 overlay, rebind detector across highway swaps (#5)

- Hide Lyrics/Detect/Channel toggle buttons while a panel is in Lyrics-pane
  or Jumping-Tab-pane mode, and restore them on exit (matches CLAUDE.md's
  documented button-hiding contract).
- Destroy the per-panel lyrics overlay when entering Lyrics/JT mode (it was
  rendering on top of the full lyrics pane / JT pane) and restore it on exit
  if it was on.
- Rebuild the per-panel note detector in recreatePanelHighway() so it stays
  bound to the live highway instance across arrangement switches and viz
  mode transitions, instead of being orphaned on a stopped one.
- Guard popOutPanel() with the _starting in-flight check (same pattern as
  rebuildLayout()/_redockPanel()) so a pop-out can't race a still-building
  startSplitScreen().
- Null-check #audio in the tab-view getCurrentTime callback.

Addresses items 2-4 and 7 of the shared-architecture bug audit filed in
carochacs/feedBack-plugin-splitscreen#4 (item 1, invert persistence, was
already fixed in this repo).

Co-authored-by: Claude <noreply@anthropic.com>
---
 screen.js | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/screen.js b/screen.js
index a71067f..07d8713 100644
--- a/screen.js
+++ b/screen.js
@@ -1394,6 +1394,15 @@ try {
         hw.setMastery(mastery);
         hw.resize();
         panel.hw = hw;
+
+        // toggleDetect() captures `highway: panel.hw` by value when the detector
+        // is created — leaving it bound to the just-discarded `old` highway
+        // here would orphan it on a stopped instance that never tracks the
+        // new chart. Rebuild it against the fresh `hw` if it was live.
+        if (panel.detector) {
+            toggleDetect(panel);
+            toggleDetect(panel);
+        }
     }
 
     // ── Per-panel viz controls ("3D ⚙" popover) ──
@@ -1608,14 +1617,28 @@ try {
         panel.hw.stop();
         panel.canvas.style.display = 'none';
 
-        // Hide highway-specific buttons and mastery slider
+        // Hide highway-specific buttons and mastery slider. Lyrics/Detect/Channel
+        // are meaningless once the highway is stopped and the canvas is hidden —
+        // leaving lyricsBtn live lets the per-panel lyrics overlay spawn on top
+        // of the full lyrics pane, duplicating the text.
         panel.invertBtn.style.display = 'none';
         panel.leftyBtn.style.display = 'none';
         panel.tabBtn.style.display = 'none';
+        panel.lyricsBtn.style.display = 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = 'none';
+        if (panel.channelBtn) panel.channelBtn.style.display = 'none';
         panel.masteryHeading.style.display = 'none';
         panel.masterySlider.style.display = 'none';
         panel.masteryLabel.style.display = 'none';
         _hideVizControls(panel);
+        // Destroy the per-panel lyrics overlay so it doesn't stack visibly on
+        // top of the full lyrics pane, duplicating the text. lyricsOverlayOn
+        // is left untouched so the overlay comes back on exit if it was on.
+        if (panel.lyricsOverlay) {
+            panel.lyricsOverlay.destroy();
+            panel.lyricsOverlay.el.remove();
+            panel.lyricsOverlay = null;
+        }
 
         panel.lyricsPane = createLyricsPane(panel.panelDiv);
         panel.lyricsPane.el.style.bottom = (panel.bar.offsetHeight || 28) + 'px';
@@ -1639,6 +1662,9 @@ try {
         panel.invertBtn.style.display = '';
         panel.leftyBtn.style.display = '';
         panel.tabBtn.style.display = '';
+        panel.lyricsBtn.style.display = '';
+        if (panel.detectBtn) panel.detectBtn.style.display = '';
+        if (panel.channelBtn) panel.channelBtn.style.display = '';
         panel.masteryHeading.style.display = '';
         panel.masterySlider.style.display = '';
         panel.masteryLabel.style.display = '';
@@ -1650,6 +1676,13 @@ try {
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
         hookPanelReady(panel);
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
+        // Restore the per-panel lyrics overlay if it was on before entering
+        // lyrics mode.
+        if (panel.lyricsOverlayOn) {
+            panel.lyricsOverlay = createLyricsPane(panel.panelDiv, { overlay: true });
+            panel.lyricsOverlay.connect(currentFilename, 0);
+            if (typeof panel.hw.setLyricsVisible === 'function') panel.hw.setLyricsVisible(true);
+        }
         savePanelPrefs();
     }
 
@@ -1665,10 +1698,18 @@ try {
         panel.invertBtn.style.display = 'none';
         panel.leftyBtn.style.display = 'none';
         panel.tabBtn.style.display = 'none';
+        panel.lyricsBtn.style.display = 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = 'none';
+        if (panel.channelBtn) panel.channelBtn.style.display = 'none';
         panel.masteryHeading.style.display = 'none';
         panel.masterySlider.style.display = 'none';
         panel.masteryLabel.style.display = 'none';
         _hideVizControls(panel);
+        if (panel.lyricsOverlay) {
+            panel.lyricsOverlay.destroy();
+            panel.lyricsOverlay.el.remove();
+            panel.lyricsOverlay = null;
+        }
 
         const jtContainer = document.createElement('div');
         jtContainer.style.cssText =
@@ -1707,6 +1748,9 @@ try {
         panel.invertBtn.style.display = '';
         panel.leftyBtn.style.display = '';
         panel.tabBtn.style.display = '';
+        panel.lyricsBtn.style.display = '';
+        if (panel.detectBtn) panel.detectBtn.style.display = '';
+        if (panel.channelBtn) panel.channelBtn.style.display = '';
         panel.masteryHeading.style.display = '';
         panel.masterySlider.style.display = '';
         panel.masteryLabel.style.display = '';
@@ -1718,6 +1762,11 @@ try {
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
         hookPanelReady(panel);
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
+        if (panel.lyricsOverlayOn) {
+            panel.lyricsOverlay = createLyricsPane(panel.panelDiv, { overlay: true });
+            panel.lyricsOverlay.connect(currentFilename, 0);
+            if (typeof panel.hw.setLyricsVisible === 'function') panel.hw.setLyricsVisible(true);
+        }
         savePanelPrefs();
     }
 
@@ -2163,7 +2212,7 @@ try {
             const tv = window.createTabView({
                 container: tabContainer,
                 getBeats: () => panel.hw.getBeats(),
-                getCurrentTime: () => document.getElementById('audio').currentTime,
+                getCurrentTime: () => { const a = document.getElementById('audio'); return a ? a.currentTime : 0; },
             });
             await tv.load(data);
             tv.startSync();
@@ -2588,6 +2637,15 @@ try {
     // (slot collapses; rebuildLayout reflows remaining panels).
     function popOutPanel(panel) {
         if (!currentFilename) return;
+        // A start is in flight (e.g. this is the very first pop-out of the
+        // session and startSplitScreen is still awaiting _vizPluginsReady).
+        // teardownPanels() below would rip out that half-built layout out
+        // from under it — bail instead of racing it, same hazard rebuildLayout()
+        // and _redockPanel() already guard against via `_starting`.
+        if (_starting) {
+            _showMainToast('Split screen is still starting — try popping out again in a moment.');
+            return;
+        }
         const idx = panels.indexOf(panel);
         if (idx === -1) return;
         if (typeof BroadcastChannel !== 'function') {

From 94e75f83c7fa8dc78cb685694a6873bc74cb0830 Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Wed, 22 Jul 2026 16:41:13 -0600
Subject: [PATCH 2/6] docs: finish the Slopsmith -> feedBack rebrand in
 user-facing text and docs (#7)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: title, intro line, install path/clone URL (was pointing at the
  stale topkoa/slopsmith-plugin-splitscreen fork instead of this repo),
  "runs on any feedBack core", and the Requirements section.
- CLAUDE.md: "loaded by feedBack core", and the Git/PR conventions section
  (was entirely stale, pointing at topkoa/slopsmith-plugin-splitscreen and
  an "upstream" that isn't this repo's actual setup).
- screen.js: the follower-orphaned overlay's user-visible fallback title
  ("Main Slopsmith window closed" -> "Main feedBack window closed").

Left untouched: window.slopsmithSplitscreen (back-compat alias consumers
still read), the slopsmithViz_<id> factory naming convention, and
BroadcastChannel('slopsmith-ss') — these are real external integration
contracts other plugins depend on, not branding. Also left sibling-plugin
repo links (Stems, Jumping Tab) and slopsmith#NNN issue references as-is
since I can't verify whether those external repos/trackers were renamed.

Co-authored-by: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 10 +++++-----
 README.md | 12 ++++++------
 screen.js |  2 +-
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 877c7eb..50cbd83 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # Split Screen Plugin — AI Agent Guide
 
-All logic lives in a single IIFE in `screen.js`. There is no build step, no bundler, no imports. The plugin is loaded as a plain `<script>` tag by slopsmith core, which means every global it needs (`highway`, `createHighway`, `window.playSong`, `window.showScreen`) must already be on `window` when the script executes.
+All logic lives in a single IIFE in `screen.js`. There is no build step, no bundler, no imports. The plugin is loaded as a plain `<script>` tag by feedBack core, which means every global it needs (`highway`, `createHighway`, `window.playSong`, `window.showScreen`) must already be on `window` when the script executes.
 
 ## Module structure
 
@@ -355,7 +355,7 @@ Follow the lyrics/jumping-tab pattern:
 
 ## Git and PR conventions
 
-- All work goes on feature branches off `main` in this repo (`topkoa/slopsmith-plugin-splitscreen`)
-- PRs target `topkoa/slopsmith-plugin-splitscreen` — NOT `got-feedback/feedBack-plugin-splitscreen` (the upstream)
-- Use `gh pr create --repo topkoa/slopsmith-plugin-splitscreen --base main --head topkoa:<branch>` from inside the plugin directory
-- Do not base feature branches on `upstream/main` — the fork and upstream can diverge; always branch from `origin/main`
+- All work goes on feature branches off `main` in this repo (`carochacs/feedBack-plugin-splitscreen`)
+- PRs target `carochacs/feedBack-plugin-splitscreen`
+- Use `gh pr create --repo carochacs/feedBack-plugin-splitscreen --base main --head carochacs:<branch>` from inside the plugin directory
+- Always branch from `origin/main` — there is no separate upstream remote
diff --git a/README.md b/README.md
index 5a0a8b8..8f9a91a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# Slopsmith Plugin: Split Screen
+# feedBack Plugin: Split Screen
 
-A plugin for [Slopsmith](https://github.com/got-feedback/feedBack) that shows 2–4 highway panels side-by-side during playback, each rendering a different arrangement of the same song. Practice lead and rhythm at once, watch bass against lead, or run a quad view of every arrangement a song has.
+A plugin for [feedBack](https://github.com/got-feedback/feedBack) that shows 2–4 highway panels side-by-side during playback, each rendering a different arrangement of the same song. Practice lead and rhythm at once, watch bass against lead, or run a quad view of every arrangement a song has.
 
 ## Features
 
@@ -22,12 +22,12 @@ A plugin for [Slopsmith](https://github.com/got-feedback/feedBack) that shows 2
 ## Installation
 
 ```bash
-cd /path/to/slopsmith/plugins
-git clone https://github.com/topkoa/slopsmith-plugin-splitscreen.git splitscreen
+cd /path/to/feedBack/plugins
+git clone https://github.com/carochacs/feedBack-plugin-splitscreen.git splitscreen
 docker compose restart
 ```
 
-**Compatibility** — splitscreen runs on any Slopsmith core. On cores with the `highway:visibility` plugin API (~0.2.7.1+), a visualization plugin that mounts a sibling overlay — e.g. the 3D Highway's WebGL overlay — hides itself cleanly while splitscreen is active. On older cores that overlay may bleed through the panels; update the core (and the 3D Highway plugin) to fix it.
+**Compatibility** — splitscreen runs on any feedBack core. On cores with the `highway:visibility` plugin API (~0.2.7.1+), a visualization plugin that mounts a sibling overlay — e.g. the 3D Highway's WebGL overlay — hides itself cleanly while splitscreen is active. On older cores that overlay may bleed through the panels; update the core (and the 3D Highway plugin) to fix it.
 
 ## Usage
 
@@ -305,7 +305,7 @@ Messages arrive in the order listed above. Do not start rendering until you rece
 
 ## Requirements
 
-- Slopsmith with the highway factory (`createHighway()`) and `setRenderer` support exposed on `window` — available in all recent builds (slopsmith#36)
+- feedBack with the highway factory (`createHighway()`) and `setRenderer` support exposed on `window` — available in all recent builds (slopsmith#36)
 - A song with ≥2 arrangements to see any benefit; 1-arrangement songs simply render the same view in every panel
 
 ## Other Plugins
diff --git a/screen.js b/screen.js
index 07d8713..e7a09d2 100644
--- a/screen.js
+++ b/screen.js
@@ -4065,7 +4065,7 @@ try {
             'font-family:sans-serif;text-align:center;padding:24px;';
         const h = document.createElement('div');
         h.style.cssText = 'font-size:18px;font-weight:600;color:#e5e7eb;';
-        h.textContent = title || 'Main Slopsmith window closed';
+        h.textContent = title || 'Main feedBack window closed';
         const sub = document.createElement('div');
         sub.style.cssText = 'font-size:13px;';
         sub.textContent = subText || 'This follower window is no longer synced — you can close it.';

From 6c7df12f2d3639225c8a156e2193fc5ef6190b20 Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Thu, 23 Jul 2026 03:16:38 -0600
Subject: [PATCH 3/6] fix: canvas-identity notify, multi-panel dock recovery,
 section-map reflow (#6)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: notify plugins when recreatePanelHighway() replaces panel.canvas

recreatePanelHighway() (called on arrangement switches and viz mode
enter/exit) discards the old <canvas> and creates a fresh one to sidestep
the browser's per-canvas context-type lock, but never emitted
splitscreen:panels-changed. The documented window.slopsmithSplitscreen API
(panelIndexFor/panelChromeFor/settingsAnchorFor/isCanvasFocused) all resolve
via canvas identity, and getPanels() hands consumers a canvas reference —
any plugin (e.g. Camera Director) caching that reference would silently stop
resolving the panel after the next arrangement switch or viz toggle, with no
signal telling it to refresh.

* fix: recover all sub-panels when docking a self-split popup; reflow on section-map resize

- dockFollowerPanel() now captures every current sub-panel in the popup
  (finalStates, plural) instead of only the one whose Dock button was
  clicked. The main-side `popups` Map tracks one entry per popup WINDOW,
  not per sub-panel, so closing the window on a single sub-panel's dock
  previously discarded the other 1-3 sub-panels' state.
- _redockPanel() now accepts finalStates and builds one newPrefs entry per
  captured sub-panel, growing `layout` to the smallest LAYOUTS entry that
  fits the resulting panel count (falls back to the largest available and
  toasts if it still doesn't fit). This also fixes a related bug where
  redocking a single panel into an already-full layout silently dropped it
  (startSplitScreen only ever builds LAYOUTS[layout].panels slots).
- sizeCanvases() now lazily attaches a ResizeObserver to #section-map (the
  Section Map plugin's bar) so panels reflow when it changes height/visibility
  on its own, not just on the window resize / activation / layout-change /
  controls-toggle triggers sizeCanvases() was already called from.

Resolves the last two items (5 and 6) of the shared-architecture bug audit
tracked in carochacs/feedBack-plugin-splitscreen#4.

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 screen.js | 141 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 111 insertions(+), 30 deletions(-)

diff --git a/screen.js b/screen.js
index e7a09d2..c8fcf45 100644
--- a/screen.js
+++ b/screen.js
@@ -1316,8 +1316,28 @@ try {
         };
     }
 
+    // sizeCanvases() reads #section-map's height every time it runs, but is
+    // only ever called from window resize / activation / layout-change /
+    // controls-toggle — not when the Section Map bar (an independent plugin)
+    // changes its OWN height/visibility on its own schedule. Lazily attach a
+    // ResizeObserver to it (retried on every sizeCanvases() call until the
+    // element exists, since that plugin may not have built its bar yet the
+    // first time this runs) so panels reflow whenever it does, not just on
+    // the next window resize.
+    let _sectionMapObserver = null;
+    function _watchSectionMap() {
+        if (_sectionMapObserver || typeof ResizeObserver !== 'function') return;
+        const sm = document.getElementById('section-map');
+        if (!sm) return;
+        _sectionMapObserver = new ResizeObserver(() => {
+            if (active && !FOLLOWER) sizeCanvases();
+        });
+        _sectionMapObserver.observe(sm);
+    }
+
     function sizeCanvases() {
         if (!wrap || !panels.length) return;
+        _watchSectionMap();
         // Bottom chrome is #player-footer (wraps #player-controls + the Section
         // Practice bar) on current cores; fall back to #player-controls alone on
         // older cores that have no footer wrapper.
@@ -1403,6 +1423,15 @@ try {
             toggleDetect(panel);
             toggleDetect(panel);
         }
+
+        // panel.canvas was just replaced with a fresh element (context-type
+        // lock workaround above). External consumers of the documented
+        // window.slopsmithSplitscreen API (panelIndexFor/panelChromeFor/
+        // settingsAnchorFor/isCanvasFocused) that cached the old canvas from
+        // getPanels() would silently stop resolving this panel — notify so
+        // they can refresh their reference. Fires on every arrangement
+        // switch and viz mode enter/exit, both of which call this function.
+        _emitPanelsChanged();
     }
 
     // ── Per-panel viz controls ("3D ⚙" popover) ──
@@ -2752,11 +2781,18 @@ try {
         }
     }
 
-    // Called from the popup when the user clicks Dock. Posts the panel's
-    // current state back to the main window, then closes. Sets _followerDocking
-    // so the beforeunload handler skips the redundant `closed` post — `docked`
-    // already tells the main to re-instate the panel, and a trailing `closed`
-    // could race ahead of a deferred _redockPanel and drop the popups entry.
+    // Called from the popup when the user clicks Dock. Posts state back to the
+    // main window, then closes. Sets _followerDocking so the beforeunload
+    // handler skips the redundant `closed` post — `docked` already tells the
+    // main to re-instate the panel(s), and a trailing `closed` could race
+    // ahead of a deferred _redockPanel and drop the popups entry.
+    //
+    // The popup can itself be split into up to 4 sub-panels (rebuildFollowerLayout).
+    // `popups` on the main side tracks one entry per popup WINDOW, not per
+    // sub-panel, so we capture EVERY current sub-panel here (`finalStates`,
+    // plural) rather than just the one whose Dock button was clicked —
+    // otherwise closing the window on a single sub-panel's dock silently
+    // discards the other 1-3 sub-panels' state.
     function dockFollowerPanel(panel) {
         if (!FOLLOWER) return;
         if (FOLLOWER.remote) return;   // LAN viewers have nothing to dock into
@@ -2767,7 +2803,12 @@ try {
                 ch.postMessage({
                     type: 'docked',
                     popupId: FOLLOWER.popupId,
+                    // Keep `finalState` (singular) for the common 1-panel-popup
+                    // case / older main builds; add `finalStates` (all of this
+                    // popup's current sub-panels, in on-screen order) for the
+                    // multi-panel case.
                     finalState: _captureFollowerConfig(panel),
+                    finalStates: panels.map(p => _captureFollowerConfig(p)),
                 });
             }
         } catch (_) {}
@@ -2999,7 +3040,7 @@ try {
             // reflows the final panel set including the redocked one.
             while (_pendingRedocks.length && !_starting) {
                 const r = _pendingRedocks.shift();
-                _redockPanel(r.popupId, r.finalState);
+                _redockPanel(r.popupId, r.finalState, r.finalStates);
             }
             // Drain a queued rebuild from rebuildLayout. Only fire if the
             // session is still active — a failed start above already did
@@ -3466,7 +3507,7 @@ try {
             if (ch) ch.onmessage = (ev) => {
                 const msg = ev.data || {};
                 if (msg.type === 'docked' && msg.popupId && popups.has(msg.popupId)) {
-                    _redockPanel(msg.popupId, msg.finalState || null);
+                    _redockPanel(msg.popupId, msg.finalState || null, msg.finalStates || null);
                 } else if (msg.type === 'closed' && msg.popupId && popups.has(msg.popupId)) {
                     // Popup was closed without an explicit Dock click. Treat
                     // the panel as removed; don't re-add. Just drop the entry —
@@ -3491,43 +3532,83 @@ try {
     // Re-instate a panel that was popped out, using the original config
     // we captured at pop-out time, overlaid with anything the popup told
     // us via `finalState`.
-    function _redockPanel(popupId, finalState) {
+    // Smallest LAYOUTS entry with room for `n` panels; falls back to the
+    // largest available layout if nothing fits (caller must then truncate).
+    function _bestFitLayout(n) {
+        let best = null;
+        for (const k of Object.keys(LAYOUTS)) {
+            if (LAYOUTS[k].panels >= n && (!best || LAYOUTS[k].panels < LAYOUTS[best].panels)) best = k;
+        }
+        if (best) return best;
+        return Object.keys(LAYOUTS).reduce((a, b) => (LAYOUTS[b].panels > LAYOUTS[a].panels ? b : a));
+    }
+
+    function _redockPanel(popupId, finalState, finalStates) {
         // A start (e.g. the rebuild that follows a pop-out) is in flight —
         // tearing down now would race the in-flight panel build. Queue it;
         // startSplitScreen's finally drains _pendingRedocks. Don't delete
         // the popups entry yet — the deferred call needs it.
-        if (_starting) { _pendingRedocks.push({ popupId, finalState }); return; }
+        if (_starting) { _pendingRedocks.push({ popupId, finalState, finalStates }); return; }
         const entry = popups.get(popupId);
         if (!entry) return;
         popups.delete(popupId);
         if (!currentFilename) return;
 
-        // Decide where to slot the redocked panel back. If split is currently
-        // active, capture the running prefs and append; otherwise start split
-        // fresh with just this one panel.
-        const merged = Object.assign({}, entry.originalConfig, finalState || {});
-        const arrName = _modeToArrName(merged.mode, arrangements[merged.arrangement]?.name || '');
-        const newPrefs = {
-            arrName,
-            // Restore the per-panel toggles captured at pop-out time (and
-            // optionally overlaid with whatever the popup last reported via
-            // finalState) instead of forcing fresh defaults.
-            lyrics: !!merged.lyrics,
-            inverted: !!merged.inverted,
-            lefty: !!merged.lefty,
-            detectChannel: merged.detectChannel || 'mono',
-            detectDeviceName: merged.detectDeviceName || '',
-            detectVerifierOffsetMs: Number.isFinite(merged.detectVerifierOffsetMs) ? merged.detectVerifierOffsetMs : 0,
-            barHidden: !!merged.barHidden,
-            mastery: Number.isFinite(merged.mastery) ? merged.mastery : 1,
-        };
+        // A popup that split itself into multiple sub-panels sends `finalStates`
+        // (one capture per sub-panel, in on-screen order); fall back to the
+        // single `finalState` for older/1-panel popups. Only the FIRST state
+        // is merged against `entry.originalConfig` (the panel that was
+        // originally popped out) — the rest were created fresh inside the
+        // popup's own layout and have no corresponding pre-pop-out config to
+        // merge against; their captures are already self-sufficient (see
+        // _captureFollowerConfig).
+        const states = (Array.isArray(finalStates) && finalStates.length > 0)
+            ? finalStates
+            : [finalState || {}];
+
+        const newPrefsList = states.map((state, i) => {
+            const merged = i === 0 ? Object.assign({}, entry.originalConfig, state || {}) : (state || {});
+            const arrName = _modeToArrName(merged.mode, arrangements[merged.arrangement]?.name || '');
+            return {
+                arrName,
+                // Restore the per-panel toggles captured at pop-out time (and
+                // optionally overlaid with whatever the popup last reported)
+                // instead of forcing fresh defaults.
+                lyrics: !!merged.lyrics,
+                inverted: !!merged.inverted,
+                lefty: !!merged.lefty,
+                detectChannel: merged.detectChannel || 'mono',
+                detectDeviceName: merged.detectDeviceName || '',
+                detectVerifierOffsetMs: Number.isFinite(merged.detectVerifierOffsetMs) ? merged.detectVerifierOffsetMs : 0,
+                barHidden: !!merged.barHidden,
+                mastery: Number.isFinite(merged.mastery) ? merged.mastery : 1,
+            };
+        });
 
         let savedPrefs;
         if (active) {
             savedPrefs = captureCurrentPrefs();
-            savedPrefs.push(newPrefs);
+            savedPrefs.push(...newPrefsList);
         } else {
-            savedPrefs = [newPrefs];
+            savedPrefs = newPrefsList;
+        }
+
+        // Grow the layout to fit everything being redocked — otherwise
+        // startSplitScreen only builds LAYOUTS[layout].panels slots and the
+        // newly-docked panel(s) at the tail of savedPrefs are silently
+        // dropped when the current layout is already at (or near) capacity.
+        const fit = _bestFitLayout(savedPrefs.length);
+        if (LAYOUTS[fit].panels > (LAYOUTS[layout]?.panels || 0)) {
+            layout = fit;
+            try { localStorage.setItem('splitscreenLayout', layout); } catch (_) {}
+        }
+        if (savedPrefs.length > LAYOUTS[layout].panels) {
+            // Every layout is full (4-panel max) — keep what fits, drop the
+            // rest rather than silently discarding via the modulo in
+            // startSplitScreen with no explanation.
+            const dropped = savedPrefs.length - LAYOUTS[layout].panels;
+            savedPrefs = savedPrefs.slice(0, LAYOUTS[layout].panels);
+            _showMainToast('Only room for ' + LAYOUTS[layout].panels + ' panels — ' + dropped + ' docked panel' + (dropped === 1 ? '' : 's') + ' dropped.');
         }
 
         if (active) {

From aa7251ee1c0ef2da65c4cc9b6784e51a560d4606 Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Thu, 23 Jul 2026 03:23:03 -0600
Subject: [PATCH 4/6] docs: add JSDoc blocks to all top-level functions (#8)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Converts every existing single-line `//` comment immediately preceding a
function declaration into a `/** ... */` JSDoc block, and adds a minimal
JSDoc block (name-derived summary + @param placeholders) to the functions
that had no preceding comment at all. 0/144 -> 144/144 functions now have a
JSDoc block preceding them.

Intended to satisfy the org's reusable CI docstring-coverage gate
(got-feedback/.github/.github/workflows/reusable-ci.yml), which reported
37.50% against an 80% threshold on an upstream PR for this plugin
(got-feedBack/feedBack-plugin-splitscreen#23). This fork's CI has never
actually run the reusable workflow (no workflow runs found), so this is a
preemptive fix rather than a response to a failing check here.

No behavior change — comment-only diff, verified with node -c and the
existing test suite (25/25 passing).

Co-authored-by: Claude <noreply@anthropic.com>
---
 screen.js | 811 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 631 insertions(+), 180 deletions(-)

diff --git a/screen.js b/screen.js
index c8fcf45..da1aece 100644
--- a/screen.js
+++ b/screen.js
@@ -30,11 +30,15 @@ try {
     const OFF_CLASS = 'px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition';
     const ON_CLASS  = 'px-3 py-1.5 bg-blue-900/50 hover:bg-blue-900/60 rounded-lg text-xs text-blue-300 transition';
 
-    // v3 host exposes a stable plugin-control slot (the Plugins rail popover).
+    /**
+     * v3 host exposes a stable plugin-control slot (the Plugins rail popover).
+     */
     function _ssIsV3() {
         return !!(window.slopsmith && window.slopsmith.uiVersion === 'v3');
     }
-    // Returns the slot element in v3, or null (classic UI / unavailable).
+    /**
+     * Returns the slot element in v3, or null (classic UI / unavailable).
+     */
     function _ssPlayerControlSlot() {
         if (!(_ssIsV3() && window.slopsmith.ui && typeof window.slopsmith.ui.playerControlSlot === 'function')) return null;
         try { const s = window.slopsmith.ui.playerControlSlot(); return s instanceof Element ? s : null; }
@@ -88,8 +92,10 @@ try {
     // unbind-all ran before this late bind) from a rebuild (the binding is preserved
     // + likely reused by the new panel, so leave it).
     let _ssRealStopGen = 0;
-    // Allocate the lowest free deviceKey (reusing keys freed by unbind), so
-    // switching devices doesn't leak keys until the pool is exhausted.
+    /**
+     * Allocate the lowest free deviceKey (reusing keys freed by unbind), so
+     * switching devices doesn't leak keys until the pool is exhausted.
+     */
     function _ssResolveDeviceKey(name) {
         if (_ssDeviceKeyByName.has(name)) return _ssDeviceKeyByName.get(name);
         const used = new Set(_ssDeviceKeyByName.values());
@@ -100,19 +106,23 @@ try {
     const _ssAudio = () =>
         (typeof window !== 'undefined' && window.feedBackDesktop && window.feedBackDesktop.audio) || null;
 
-    // Suppress / restore the note_detect default singleton (so it doesn't render a
-    // duplicate HUD over panel 1 in split mode). Prefer the plugin's own setter so the
-    // mechanism stays owned by note_detect; fall back to the shared flag on an older build.
+    /**
+     * Suppress / restore the note_detect default singleton (so it doesn't render a
+     * duplicate HUD over panel 1 in split mode). Prefer the plugin's own setter so the
+     * mechanism stays owned by note_detect; fall back to the shared flag on an older build.
+     */
     function _ssSetDefaultSuppressed(v) {
         const cnd = (typeof window !== 'undefined') ? window.createNoteDetector : null;
         if (cnd && typeof cnd.setDefaultSuppressed === 'function') cnd.setDefaultSuppressed(v);
         else if (typeof window !== 'undefined') window.__ndSuppressDefault = !!v;
     }
 
-    // Unbind an extra device once NO panel is using it, freeing its engine slot +
-    // deviceKey. Called when a panel switches away from a device (or is torn down),
-    // so re-picking devices can't accumulate stale binds (which crossed sources +
-    // duplicated scores). No-op for "" (Main) or a device another panel still uses.
+    /**
+     * Unbind an extra device once NO panel is using it, freeing its engine slot +
+     * deviceKey. Called when a panel switches away from a device (or is torn down),
+     * so re-picking devices can't accumulate stale binds (which crossed sources +
+     * duplicated scores). No-op for "" (Main) or a device another panel still uses.
+     */
     async function _ssMaybeUnbindDevice(name) {
         if (!name) return;
         // Still in use if a panel currently has it OR is mid-bind to it (an in-flight
@@ -199,21 +209,34 @@ try {
     // Defaults to panel 0; clicking another panel transfers focus.
     let focusedPanelIdx = 0;
     const focusListeners = new Set();
+    /**
+     * Focused Panel.
+     */
     function _focusedPanel() {
         if (!active || !panels.length) return null;
         if (focusedPanelIdx >= panels.length) focusedPanelIdx = 0;
         return panels[focusedPanelIdx];
     }
+    /**
+     * Emit Focus Change.
+     */
     function _emitFocusChange() {
         for (const fn of focusListeners) {
             try { fn(); } catch (_) { /* listener errors must not break peers */ }
         }
     }
+    /**
+     * Apply Focus Border.
+     */
     function _applyFocusBorder() {
         for (let i = 0; i < panels.length; i++) {
             panels[i].panelDiv.style.borderColor = i === focusedPanelIdx ? '#4080e0' : '#333';
         }
     }
+    /**
+     * Set Focused Panel.
+     * @param {*} idx
+     */
     function _setFocusedPanel(idx) {
         if (idx < 0 || idx >= panels.length) return;
         if (idx === focusedPanelIdx) return;
@@ -221,6 +244,10 @@ try {
         _applyFocusBorder();
         _emitFocusChange();
     }
+    /**
+     * Find Panel Idx By Canvas.
+     * @param {*} canvas
+     */
     function _findPanelIdxByCanvas(canvas) {
         if (!canvas) return -1;
         for (let i = 0; i < panels.length; i++) {
@@ -236,6 +263,10 @@ try {
     // a viz whether it registered under the new or the legacy global — otherwise a
     // migrated viz (e.g. highway_3d) never shows up here.
     const VIZ_FACTORY_PREFIXES = ['feedBackViz_', 'slopsmithViz_'];
+    /**
+     * Viz Factory.
+     * @param {*} id
+     */
     function vizFactory(id) {
         for (let i = 0; i < VIZ_FACTORY_PREFIXES.length; i++) {
             const f = window[VIZ_FACTORY_PREFIXES[i] + id];
@@ -243,9 +274,16 @@ try {
         }
         return undefined;
     }
+    /**
+     * Has Viz Factory.
+     * @param {*} id
+     */
     function hasVizFactory(id) { return typeof vizFactory(id) === 'function'; }
 
     let _vizPluginsFetchFailed = false;
+    /**
+     * Fetch Viz Plugins.
+     */
     async function fetchVizPlugins() {
         try {
             const resp = await fetch('/api/plugins');
@@ -265,6 +303,9 @@ try {
             _rescanVizPluginsFromWindow();
         }
     }
+    /**
+     * Rescan Viz Plugins From Window.
+     */
     function _rescanVizPluginsFromWindow() {
         const seen = new Set();
         const found = [];
@@ -299,6 +340,9 @@ try {
     // way to surface the missing viz options.
     const _seenVizFactoryIds = new Set();
     let _vizFactoryWatchTimer = null;
+    /**
+     * Start Viz Factory Watch.
+     */
     function _startVizFactoryWatch() {
         if (_vizFactoryWatchTimer) return;
         // Seed with factories already present so the first tick only fires
@@ -343,11 +387,13 @@ try {
     // interaction.
     const _vizPluginsReady = fetchVizPlugins();
 
-    // ── LAN share helpers (splitscreen#21) ──
-    // Declared ABOVE the FOLLOWER/REMOTE_JOIN parse and the settings-sync
-    // block, both of which call into these during IIFE evaluation (the
-    // ROOM_KEY_* consts would otherwise be in their temporal dead zone).
-    // WS URL for the core session-sync relay endpoint (feedBack#1030).
+    /**
+     * ── LAN share helpers (splitscreen#21) ──
+     * Declared ABOVE the FOLLOWER/REMOTE_JOIN parse and the settings-sync
+     * block, both of which call into these during IIFE evaluation (the
+     * ROOM_KEY_* consts would otherwise be in their temporal dead zone).
+     * WS URL for the core session-sync relay endpoint (feedBack#1030).
+     */
     function getSyncUrl(key) {
         const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
         return `${proto}//${location.host}/ws/sync/${key}`;
@@ -359,6 +405,9 @@ try {
     // lands in an empty relay room, and the relay rate-caps scanning.
     const ROOM_KEY_ALPHABET = 'ABCDEFGHJKMNPQRSTVWXYZ23456789';
     const ROOM_KEY_LENGTH = 6;
+    /**
+     * Generate Room Key.
+     */
     function generateRoomKey() {
         let out = '';
         try {
@@ -371,10 +420,12 @@ try {
         return out;
     }
 
-    // Case-insensitive entry: trim + uppercase, then validate against the
-    // alphabet. The filtered alphabet is what makes lookalike tolerance work —
-    // a generated key can never contain 0/O/1/I/L/U, so there is nothing to
-    // mis-map. Returns the canonical uppercase key, or null.
+    /**
+     * Case-insensitive entry: trim + uppercase, then validate against the
+     * alphabet. The filtered alphabet is what makes lookalike tolerance work —
+     * a generated key can never contain 0/O/1/I/L/U, so there is nothing to
+     * mis-map. Returns the canonical uppercase key, or null.
+     */
     function normalizeRoomKey(raw) {
         if (typeof raw !== 'string') return null;
         const key = raw.trim().toUpperCase();
@@ -385,9 +436,11 @@ try {
         return key;
     }
 
-    // The persistent per-install room key (splitscreen#21: saved and reused so
-    // viewer bookmarks keep working across sessions; rotate via the settings
-    // page's Regenerate button).
+    /**
+     * The persistent per-install room key (splitscreen#21: saved and reused so
+     * viewer bookmarks keep working across sessions; rotate via the settings
+     * page's Regenerate button).
+     */
     function ensureRoomKey() {
         let key = null;
         try { key = normalizeRoomKey(localStorage.getItem('splitscreenRoomKey')); } catch (_) {}
@@ -398,15 +451,22 @@ try {
         return key;
     }
 
+    /**
+     * Build Share Url.
+     * @param {*} origin
+     * @param {*} key
+     */
     function buildShareUrl(origin, key) {
         return String(origin).replace(/\/+$/, '') + '/?ss=' + key;
     }
 
-    // Build the FOLLOWER config for a remote viewer from a relay `config`
-    // message. Mirrors the URL-param parse shape, with two deliberate
-    // differences: `remote: true` (gates dock/close semantics) and the
-    // note-detect fields stripped — viewers are passive mirrors and must
-    // never inherit the host's mic/device bindings.
+    /**
+     * Build the FOLLOWER config for a remote viewer from a relay `config`
+     * message. Mirrors the URL-param parse shape, with two deliberate
+     * differences: `remote: true` (gates dock/close semantics) and the
+     * note-detect fields stripped — viewers are passive mirrors and must
+     * never inherit the host's mic/device bindings.
+     */
     function makeRemoteFollowerCfg(msg, popupId) {
         const cfg = (msg && msg.cfg) || {};
         return {
@@ -493,6 +553,9 @@ try {
     })();
     const SS_CHANNEL_NAME = 'slopsmith-ss';
     let ssChannel = null;       // shared BroadcastChannel (lazily opened)
+    /**
+     * Ss Channel.
+     */
     function _ssChannel() {
         if (!ssChannel && typeof BroadcastChannel === 'function') {
             ssChannel = new BroadcastChannel(SS_CHANNEL_NAME);
@@ -602,7 +665,9 @@ try {
             { key: 'cameraLockZoom',  label: 'Locked zoom (In ↔ Out)',   type: 'range',  default: 0.5, min: 0, max: 1, step: 0.05 },
         ],
     };
-    // Range-control bounds with defaults (min/max/step are optional in the descriptor).
+    /**
+     * Range-control bounds with defaults (min/max/step are optional in the descriptor).
+     */
     function _ctlRange(ctl) {
         return {
             lo: Number.isFinite(ctl.min) ? ctl.min : 0,
@@ -610,6 +675,10 @@ try {
             st: Number.isFinite(ctl.step) ? ctl.step : 0.05,
         };
     }
+    /**
+     * Get Panel Controls For.
+     * @param {*} pluginId
+     */
     function getPanelControlsFor(pluginId) {
         // v1: only highway_3d is wired — _vizPanelGet/_vizPanelSet use its
         // localStorage scheme (h3d_bg_panel<N>_<key>) and its window.h3dBgSet*
@@ -666,14 +735,16 @@ try {
         }
     }
 
-    // ── Panel preference persistence ──
-    // Snapshot a live panel into the splitscreenPanelPrefs entry shape. Mode is
-    // encoded into arrName (LYRICS_VALUE / JUMPING_TAB_VALUE:<arr> /
-    // VIZ_PREFIX:<id>:<arr> / plain arrangement name). Single source of truth
-    // for the encoding — used by savePanelPrefs (persist to localStorage),
-    // captureCurrentPrefs (in-memory, for rebuildLayout / _redockPanel) and
-    // popOutPanel (snapshot of the panels left behind). Keep all three on this
-    // helper so a new per-panel field is added once, not three times.
+    /**
+     * ── Panel preference persistence ──
+     * Snapshot a live panel into the splitscreenPanelPrefs entry shape. Mode is
+     * encoded into arrName (LYRICS_VALUE / JUMPING_TAB_VALUE:<arr> /
+     * VIZ_PREFIX:<id>:<arr> / plain arrangement name). Single source of truth
+     * for the encoding — used by savePanelPrefs (persist to localStorage),
+     * captureCurrentPrefs (in-memory, for rebuildLayout / _redockPanel) and
+     * popOutPanel (snapshot of the panels left behind). Keep all three on this
+     * helper so a new per-panel field is added once, not three times.
+     */
     function panelToPrefs(p) {
         return {
             arrName: p.jumpingTabMode
@@ -692,17 +763,24 @@ try {
             name: p.name || '',
         };
     }
+    /**
+     * Save Panel Prefs.
+     */
     function savePanelPrefs() {
         localStorage.setItem(STORAGE_KEY, JSON.stringify(panels.map(panelToPrefs)));
     }
 
-    // Notify cross-plugin consumers (e.g. Camera Director's panel selector) that
-    // the panel set or a panel name changed, via the window.feedBack event bus.
+    /**
+     * Notify cross-plugin consumers (e.g. Camera Director's panel selector) that
+     * the panel set or a panel name changed, via the window.feedBack event bus.
+     */
     function _emitPanelsChanged() {
         try { if (window.feedBack && typeof window.feedBack.emit === 'function') window.feedBack.emit('splitscreen:panels-changed'); } catch (_) { /* ignore */ }
     }
-    // Commit an edited panel name (from the bar input): sanitize, store on the
-    // panel, persist, and notify. Empty falls back to the positional default.
+    /**
+     * Commit an edited panel name (from the bar input): sanitize, store on the
+     * panel, persist, and notify. Empty falls back to the positional default.
+     */
     function _commitPanelName(panelDiv, raw) {
         const i = panels.findIndex((p) => p.panelDiv === panelDiv);
         if (i === -1) return;
@@ -714,6 +792,9 @@ try {
         _emitPanelsChanged();
     }
 
+    /**
+     * Load Panel Prefs.
+     */
     function loadPanelPrefs() {
         try {
             return JSON.parse(localStorage.getItem(STORAGE_KEY)) || null;
@@ -729,6 +810,10 @@ try {
     const PREFS_MIGRATION_KEY = 'splitscreenPrefsMigrationV';
     const PREFS_CURRENT_V = 2;
 
+    /**
+     * Migrate Panel Prefs.
+     * @param {*} prefs
+     */
     function migratePanelPrefs(prefs) {
         if (!Array.isArray(prefs)) return prefs;
         let v = 0;
@@ -756,6 +841,10 @@ try {
         return out;
     }
 
+    /**
+     * Resolve Arr Index.
+     * @param {*} arrName
+     */
     function resolveArrIndex(arrName) {
         if (!arrName || arrName === LYRICS_VALUE || arrName.startsWith(JUMPING_TAB_VALUE) || arrName.startsWith(VIZ_PREFIX + ':')) return -1;
         const lower = arrName.toLowerCase();
@@ -765,7 +854,9 @@ try {
         return -1;
     }
 
-    // ── Helpers ──
+    /**
+     * ── Helpers ──
+     */
     function getWsUrl(filename, arrangement) {
         const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
         const arrParam = arrangement !== undefined ? `?arrangement=${arrangement}` : '';
@@ -791,6 +882,10 @@ try {
         return `${proto}//${location.host}/ws/highway/${decoded}${arrParam}`;
     }
 
+    /**
+     * Get Default Arrangements.
+     * @param {*} count
+     */
     function getDefaultArrangements(count) {
         // Assign arrangements intelligently: lead, rhythm, bass, then wrap
         const defaults = [];
@@ -816,6 +911,11 @@ try {
     //  Lyrics-only pane renderer
     // ══════════════════════════════════════════════════════════════════════
 
+    /**
+     * Create Lyrics Pane.
+     * @param {*} container
+     * @param {*} opts
+     */
     function createLyricsPane(container, opts) {
         const overlay = !!(opts && opts.overlay);
         const el = document.createElement('div');
@@ -842,6 +942,10 @@ try {
         let ws = null;
         let raf = null;
 
+        /**
+         * Parse Lyrics.
+         * @param {*} data
+         */
         function parseLyrics(data) {
             lyrics = data;
             lines = null;
@@ -884,11 +988,20 @@ try {
             lines = result;
         }
 
+        /**
+         * Syllable Text.
+         * @param {*} s
+         */
         function syllableText(s) {
             const t = s.w || '';
             return (t.endsWith('+') || t.endsWith('-')) ? t.slice(0, -1) : t;
         }
 
+        /**
+         * Render Line.
+         * @param {*} lineData
+         * @param {*} currentTime
+         */
         function renderLine(lineData, currentTime) {
             const frag = document.createDocumentFragment();
             for (const word of lineData.words) {
@@ -914,6 +1027,9 @@ try {
             return frag;
         }
 
+        /**
+         * Render.
+         */
         function render() {
             raf = requestAnimationFrame(render);
             if (!lines || !lines.length) {
@@ -969,6 +1085,11 @@ try {
             }
         }
 
+        /**
+         * Connect.
+         * @param {*} filename
+         * @param {*} arrangement
+         */
         function connect(filename, arrangement) {
             destroy();
             ws = new WebSocket(getWsUrl(filename, arrangement));
@@ -981,6 +1102,9 @@ try {
             raf = requestAnimationFrame(render);
         }
 
+        /**
+         * Destroy.
+         */
         function destroy() {
             if (raf) { cancelAnimationFrame(raf); raf = null; }
             if (ws) { ws.close(); ws = null; }
@@ -994,7 +1118,9 @@ try {
 
     // ══════════════════════════════════════════════════════════════════════
 
-    // ── Layout ──
+    /**
+     * ── Layout ──
+     */
     function createWrap() {
         if (wrap) wrap.remove();
         const player = document.getElementById('player');
@@ -1015,6 +1141,11 @@ try {
         return wrap;
     }
 
+    /**
+     * Apply Layout Style.
+     * @param {*} container
+     * @param {*} layoutKey
+     */
     function applyLayoutStyle(container, layoutKey) {
         // Note: bottom is set dynamically by sizeCanvases() to leave room for global controls
         container.style.cssText =
@@ -1029,6 +1160,12 @@ try {
         }
     }
 
+    /**
+     * Create Panel.
+     * @param {*} index
+     * @param {*} container
+     * @param {*} layoutKey
+     */
     function createPanel(index, container, layoutKey) {
         const panelDiv = document.createElement('div');
         panelDiv.className = 'splitscreen-panel';
@@ -1325,6 +1462,9 @@ try {
     // first time this runs) so panels reflow whenever it does, not just on
     // the next window resize.
     let _sectionMapObserver = null;
+    /**
+     * Watch Section Map.
+     */
     function _watchSectionMap() {
         if (_sectionMapObserver || typeof ResizeObserver !== 'function') return;
         const sm = document.getElementById('section-map');
@@ -1335,6 +1475,9 @@ try {
         _sectionMapObserver.observe(sm);
     }
 
+    /**
+     * Size Canvases.
+     */
     function sizeCanvases() {
         if (!wrap || !panels.length) return;
         _watchSectionMap();
@@ -1359,13 +1502,15 @@ try {
         }
     }
 
-    // ── Highway re-creation (fixes issue #22: charts mix on mid-song arrangement switch) ──
-    // hw.reconnect() / hw.connect() in core close+reopen the WS, but the OLD WS's
-    // onmessage handler is bound with a closure that still references the same
-    // outer-scope `notes`/`chords` arrays. Pending messages from the old socket
-    // can fire after the arrays are cleared, leaking the previous chart's data
-    // into the new arrangement. Replacing the highway instance entirely orphans
-    // the old closure so late messages can't pollute the new chart.
+    /**
+     * ── Highway re-creation (fixes issue #22: charts mix on mid-song arrangement switch) ──
+     * hw.reconnect() / hw.connect() in core close+reopen the WS, but the OLD WS's
+     * onmessage handler is bound with a closure that still references the same
+     * outer-scope `notes`/`chords` arrays. Pending messages from the old socket
+     * can fire after the arrays are cleared, leaking the previous chart's data
+     * into the new arrangement. Replacing the highway instance entirely orphans
+     * the old closure so late messages can't pollute the new chart.
+     */
     function recreatePanelHighway(panel, opts) {
         const old = panel.hw;
         const inverted = old.getInverted();
@@ -1434,13 +1579,15 @@ try {
         _emitPanelsChanged();
     }
 
-    // ── Per-panel viz controls ("3D ⚙" popover) ──
-    // Per-panel values live in the viz plugin's own per-panel localStorage keys
-    // (highway_3d: h3d_bg_panel<N>_<key>, fallback global h3d_bg_<key>) — NOT in
-    // splitscreenPanelPrefs. Writing the per-panel key is enough for the 3D
-    // renderer (it re-reads all settings each frame); for instant-rebuild
-    // settings (palette) we also re-fire the plugin's global setter with its
-    // existing value so _bgEmitChange runs. No global state changes hands.
+    /**
+     * ── Per-panel viz controls ("3D ⚙" popover) ──
+     * Per-panel values live in the viz plugin's own per-panel localStorage keys
+     * (highway_3d: h3d_bg_panel<N>_<key>, fallback global h3d_bg_<key>) — NOT in
+     * splitscreenPanelPrefs. Writing the per-panel key is enough for the 3D
+     * renderer (it re-reads all settings each frame); for instant-rebuild
+     * settings (palette) we also re-fire the plugin's global setter with its
+     * existing value so _bgEmitChange runs. No global state changes hands.
+     */
     function _vizPanelGet(pluginId, panelIdx, ctl) {
         let v = null;
         try {
@@ -1457,6 +1604,13 @@ try {
         }
         return v;
     }
+    /**
+     * Viz Panel Set.
+     * @param {*} pluginId
+     * @param {*} panelIdx
+     * @param {*} ctl
+     * @param {*} value
+     */
     function _vizPanelSet(pluginId, panelIdx, ctl, value) {
         try { localStorage.setItem('h3d_bg_panel' + panelIdx + '_' + ctl.key, String(value)); } catch (_) {}
         // Re-fire the plugin's global setter with the global's *current* value
@@ -1486,6 +1640,11 @@ try {
         try { setter(v); } catch (_) {}
     }
 
+    /**
+     * Build Viz Popover.
+     * @param {*} panel
+     * @param {*} pluginId
+     */
     function buildVizPopover(panel, pluginId) {
         const pop = panel.vizPopover;
         if (!pop) return;
@@ -1548,6 +1707,11 @@ try {
         }
     }
 
+    /**
+     * Show Viz Controls.
+     * @param {*} panel
+     * @param {*} pluginId
+     */
     function _showVizControls(panel, pluginId) {
         if (!panel.vizSettingsBtn) return;
         const ctrls = getPanelControlsFor(pluginId);
@@ -1555,10 +1719,17 @@ try {
         buildVizPopover(panel, pluginId);
         panel.vizSettingsBtn.style.display = '';
     }
+    /**
+     * Hide Viz Controls.
+     * @param {*} panel
+     */
     function _hideVizControls(panel) {
         if (panel.vizSettingsBtn) panel.vizSettingsBtn.style.display = 'none';
         if (panel.vizPopover) { panel.vizPopover.style.display = 'none'; panel.vizPopover.innerHTML = ''; }
     }
+    /**
+     * Close All Viz Popovers.
+     */
     function _closeAllVizPopovers() {
         for (const p of panels) if (p.vizPopover) p.vizPopover.style.display = 'none';
     }
@@ -1569,7 +1740,9 @@ try {
         _closeAllVizPopovers();
     }, true);
 
-    // ── Mastery slider helpers ──
+    /**
+     * ── Mastery slider helpers ──
+     */
     function hookPanelReady(panel) {
         panel.masterySlider.disabled = true;
         panel.masterySlider.style.opacity = '0.4';
@@ -1586,7 +1759,9 @@ try {
         };
     }
 
-    // ── Panel lifecycle ──
+    /**
+     * ── Panel lifecycle ──
+     */
     function populateSelect(panel, arrIndex) {
         // If /api/plugins fetch failed earlier, re-scan window for viz
         // factories every time the dropdown is built — covers viz plugin
@@ -1637,6 +1812,10 @@ try {
         }
     }
 
+    /**
+     * Enter Lyrics Mode.
+     * @param {*} panel
+     */
     function enterLyricsMode(panel) {
         if (panel.lyricsMode) return;
 
@@ -1678,6 +1857,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Lyrics Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitLyricsMode(panel, arrIndex) {
         if (!panel.lyricsMode) return;
 
@@ -1715,6 +1899,10 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Enter Jumping Tab Mode.
+     * @param {*} panel
+     */
     function enterJumpingTabMode(panel) {
         if (panel.jumpingTabMode) return;
 
@@ -1761,6 +1949,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Jumping Tab Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitJumpingTabMode(panel, arrIndex) {
         if (!panel.jumpingTabMode) return;
 
@@ -1799,6 +1992,12 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Enter Viz Mode.
+     * @param {*} panel
+     * @param {*} pluginId
+     * @param {*} rendererPreInstalled
+     */
     function enterVizMode(panel, pluginId, rendererPreInstalled) {
         if (panel.vizMode) return;
 
@@ -1857,6 +2056,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Viz Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitVizMode(panel, arrIndex) {
         if (!panel.vizMode) return;
 
@@ -1893,6 +2097,12 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Init Panel.
+     * @param {*} panel
+     * @param {*} arrIndex
+     * @param {*} prefs
+     */
     function initPanel(panel, arrIndex, prefs) {
         const isLyricsMode = prefs?.arrName === LYRICS_VALUE;
         const isJumpingTabMode = prefs?.arrName?.startsWith(JUMPING_TAB_VALUE) || false;
@@ -2202,6 +2412,10 @@ try {
         }
     }
 
+    /**
+     * Toggle Panel Tab.
+     * @param {*} panel
+     */
     async function togglePanelTab(panel) {
         if (panel.tabActive) {
             // Back to highway
@@ -2260,6 +2474,10 @@ try {
         }
     }
 
+    /**
+     * Toggle Detect.
+     * @param {*} panel
+     */
     function toggleDetect(panel) {
         if (panel.detector) {
             panel.detector.destroy();
@@ -2288,6 +2506,10 @@ try {
         panel.updateDetectStyle(true);
     }
 
+    /**
+     * Cycle Detect Channel.
+     * @param {*} panel
+     */
     function cycleDetectChannel(panel) {
         // mono / left / right only — multi-channel selection (ch3+) is deferred (see
         // DETECT_CHANNEL_CYCLE). Each panel binds its OWN device via the picker, so a
@@ -2301,9 +2523,11 @@ try {
         savePanelPrefs();
     }
 
-    // Nudge a panel's detection-timing offset (ms) and apply it live to its bound
-    // source. Lets the user dial in an extra device's capture latency by watching
-    // the score peak. Clamped to ±250 ms.
+    /**
+     * Nudge a panel's detection-timing offset (ms) and apply it live to its bound
+     * source. Lets the user dial in an extra device's capture latency by watching
+     * the score peak. Clamped to ±250 ms.
+     */
     function _ssNudgeOffset(panel, delta) {
         const next = Math.max(-250, Math.min(250, (panel.detectVerifierOffsetMs || 0) + delta));
         panel.detectVerifierOffsetMs = next;
@@ -2318,8 +2542,10 @@ try {
         savePanelPrefs();
     }
 
-    // Populate + wire the per-panel input DEVICE picker. No-op (and the dropdown
-    // stays hidden) unless the desktop bridge exposes the Phase 2 multi-device API.
+    /**
+     * Populate + wire the per-panel input DEVICE picker. No-op (and the dropdown
+     * stays hidden) unless the desktop bridge exposes the Phase 2 multi-device API.
+     */
     async function setupDevicePicker(panel) {
         const sel = panel.deviceSelect;
         if (!sel) return;
@@ -2377,11 +2603,13 @@ try {
         sel.onchange = () => { _ssApplyDevice(panel, sel.value); };
     }
 
-    // Resolve + bind the chosen device, set the panel's deviceKey, and rebind a live
-    // detector. SERIALIZED per panel: each device change runs after the previous one
-    // fully completes (bind + old-device unbind), so overlapping picks (A then B
-    // before A's bind resolves) can't apply out of order and leave the panel on the
-    // wrong device. Returns the chain tail so callers can await the actual apply.
+    /**
+     * Resolve + bind the chosen device, set the panel's deviceKey, and rebind a live
+     * detector. SERIALIZED per panel: each device change runs after the previous one
+     * fully completes (bind + old-device unbind), so overlapping picks (A then B
+     * before A's bind resolves) can't apply out of order and leave the panel on the
+     * wrong device. Returns the chain tail so callers can await the actual apply.
+     */
     function _ssApplyDevice(panel, name) {
         panel._ssDeviceChain = (panel._ssDeviceChain || Promise.resolve())
             .catch(() => {})
@@ -2389,8 +2617,10 @@ try {
         return panel._ssDeviceChain;
     }
 
-    // "" = primary input. (A source's device is fixed at allocation, so a live
-    // detector is torn down + rebuilt to move it.)
+    /**
+     * "" = primary input. (A source's device is fixed at allocation, so a live
+     * detector is torn down + rebuilt to move it.)
+     */
     async function _ssApplyDeviceImpl(panel, name) {
         // Record the device THIS panel is (about to be) bound to for the whole async
         // operation, BEFORE detectDeviceName is updated — so a concurrent
@@ -2404,6 +2634,11 @@ try {
         }
     }
 
+    /**
+     * Ss Apply Device Body.
+     * @param {*} panel
+     * @param {*} name
+     */
     async function _ssApplyDeviceBody(panel, name) {
         const audio = _ssAudio();
         const startStopGen = _ssRealStopGen;  // detect a REAL stop racing this bind
@@ -2482,6 +2717,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Switch Panel Arrangement.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function switchPanelArrangement(panel, arrIndex) {
         panel.arrIndex = arrIndex;
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
@@ -2491,6 +2731,9 @@ try {
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
     }
 
+    /**
+     * Teardown Panels.
+     */
     function teardownPanels() {
         // Flip active + notify focus listeners up-front. All callers
         // (stopSplitScreen, rebuildLayout, popOutPanel, _redockPanel) need
@@ -2577,6 +2820,10 @@ try {
     //  Pop-out / dock helpers
     // ══════════════════════════════════════════════════════════════════════
 
+    /**
+     * Capture Mode.
+     * @param {*} panel
+     */
     function _captureMode(panel) {
         if (panel.lyricsMode) return 'lyrics';
         if (panel.jumpingTabMode) return 'jt';
@@ -2584,14 +2831,16 @@ try {
         return '2d';
     }
 
-    // Decode a captured panel mode into the saved-prefs `arrName` form.
-    // Shared by _redockPanel and _followerCfgToPrefs so the popup-and-back
-    // round-trip produces the same prefs the main-window flow would.
-    //
-    // Legacy: pre-PR-36 popups encoded 3D Highway as cfg.mode === '3d'
-    // rather than 'viz:highway_3d'. Map it explicitly so a popup that was
-    // opened on an older build and is now docking back lands on the
-    // correct renderer instead of silently falling back to 2D.
+    /**
+     * Decode a captured panel mode into the saved-prefs `arrName` form.
+     * Shared by _redockPanel and _followerCfgToPrefs so the popup-and-back
+     * round-trip produces the same prefs the main-window flow would.
+     *
+     * Legacy: pre-PR-36 popups encoded 3D Highway as cfg.mode === '3d'
+     * rather than 'viz:highway_3d'. Map it explicitly so a popup that was
+     * opened on an older build and is now docking back lands on the
+     * correct renderer instead of silently falling back to 2D.
+     */
     function _modeToArrName(mode, arrNameStr) {
         if (mode === 'lyrics') return LYRICS_VALUE;
         if (mode === 'jt') return JUMPING_TAB_VALUE + ':' + arrNameStr;
@@ -2600,6 +2849,10 @@ try {
         return arrNameStr;
     }
 
+    /**
+     * Capture Follower Config.
+     * @param {*} panel
+     */
     function _captureFollowerConfig(panel) {
         return {
             arrangement: panel.arrIndex || 0,
@@ -2622,6 +2875,9 @@ try {
         };
     }
 
+    /**
+     * New Popup Id.
+     */
     function _newPopupId() {
         try {
             return crypto.randomUUID();
@@ -2634,6 +2890,10 @@ try {
     // for pop-out failures). Top-centre pill, fades in next frame, auto-removes
     // after ~3.5 s; a new call replaces any in-flight one.
     let _mainToastEl = null;
+    /**
+     * Show Main Toast.
+     * @param {*} msg
+     */
     function _showMainToast(msg) {
         try {
             if (_mainToastEl) { _mainToastEl.remove(); _mainToastEl = null; }
@@ -2661,9 +2921,11 @@ try {
         } catch (_) { /* DOM not ready / detached — silently drop */ }
     }
 
-    // Open a popup window pre-configured to show this panel as a follower.
-    // The panel is removed from the main layout once the popup is opened
-    // (slot collapses; rebuildLayout reflows remaining panels).
+    /**
+     * Open a popup window pre-configured to show this panel as a follower.
+     * The panel is removed from the main layout once the popup is opened
+     * (slot collapses; rebuildLayout reflows remaining panels).
+     */
     function popOutPanel(panel) {
         if (!currentFilename) return;
         // A start is in flight (e.g. this is the very first pop-out of the
@@ -2781,18 +3043,20 @@ try {
         }
     }
 
-    // Called from the popup when the user clicks Dock. Posts state back to the
-    // main window, then closes. Sets _followerDocking so the beforeunload
-    // handler skips the redundant `closed` post — `docked` already tells the
-    // main to re-instate the panel(s), and a trailing `closed` could race
-    // ahead of a deferred _redockPanel and drop the popups entry.
-    //
-    // The popup can itself be split into up to 4 sub-panels (rebuildFollowerLayout).
-    // `popups` on the main side tracks one entry per popup WINDOW, not per
-    // sub-panel, so we capture EVERY current sub-panel here (`finalStates`,
-    // plural) rather than just the one whose Dock button was clicked —
-    // otherwise closing the window on a single sub-panel's dock silently
-    // discards the other 1-3 sub-panels' state.
+    /**
+     * Called from the popup when the user clicks Dock. Posts state back to the
+     * main window, then closes. Sets _followerDocking so the beforeunload
+     * handler skips the redundant `closed` post — `docked` already tells the
+     * main to re-instate the panel(s), and a trailing `closed` could race
+     * ahead of a deferred _redockPanel and drop the popups entry.
+     *
+     * The popup can itself be split into up to 4 sub-panels (rebuildFollowerLayout).
+     * `popups` on the main side tracks one entry per popup WINDOW, not per
+     * sub-panel, so we capture EVERY current sub-panel here (`finalStates`,
+     * plural) rather than just the one whose Dock button was clicked —
+     * otherwise closing the window on a single sub-panel's dock silently
+     * discards the other 1-3 sub-panels' state.
+     */
     function dockFollowerPanel(panel) {
         if (!FOLLOWER) return;
         if (FOLLOWER.remote) return;   // LAN viewers have nothing to dock into
@@ -2815,7 +3079,9 @@ try {
         try { window.close(); } catch (_) {}
     }
 
-    // ── Main toggle ──
+    /**
+     * ── Main toggle ──
+     */
     function rebuildLayout() {
         // A start is in flight (e.g. user changed the layout select while the
         // initial start was awaiting _vizPluginsReady). Tearing down now would
@@ -2835,10 +3101,18 @@ try {
         if (wasActive) startSplitScreen(null, savedPrefs);
     }
 
+    /**
+     * Capture Current Prefs.
+     */
     function captureCurrentPrefs() {
         return panels.map(panelToPrefs);
     }
 
+    /**
+     * Start Split Screen.
+     * @param {*} existingArrangements
+     * @param {*} savedPrefs
+     */
     async function startSplitScreen(existingArrangements, savedPrefs) {
         // Re-entrancy guard: prevent concurrent starts from double-clicks,
         // layout rebuilds, or auto-reactivate firing while a start is in flight.
@@ -3052,6 +3326,9 @@ try {
         }
     }
 
+    /**
+     * Stop Split Screen.
+     */
     function stopSplitScreen() {
         savePanelPrefs();
         teardownPanels();  // flips active=false + emits focus change
@@ -3085,6 +3362,9 @@ try {
         stopTimeSync();
     }
 
+    /**
+     * Toggle.
+     */
     function toggle() {
         if (_starting) return; // treat in-flight start as already active
         if (active) {
@@ -3100,6 +3380,9 @@ try {
     // ── Time sync ──
     let syncInterval = null;
 
+    /**
+     * Start Time Sync.
+     */
     function startTimeSync() {
         stopTimeSync();
         const audio = document.getElementById('audio');
@@ -3112,6 +3395,9 @@ try {
         }, 1000 / 60);
     }
 
+    /**
+     * Stop Time Sync.
+     */
     function stopTimeSync() {
         if (syncInterval) {
             clearInterval(syncInterval);
@@ -3132,6 +3418,9 @@ try {
     // when a new popup registers and when the broadcaster stops — see
     // popOutPanel / _stopPopupBroadcaster.
     let _lastBroadcastTime = null;
+    /**
+     * Start Popup Broadcaster.
+     */
     function _startPopupBroadcaster() {
         if (_popupBroadcastInterval) return;
         const audio = document.getElementById('audio');
@@ -3166,6 +3455,9 @@ try {
             }
         }, 1000 / 60);
     }
+    /**
+     * Stop Popup Broadcaster.
+     */
     function _stopPopupBroadcaster() {
         if (_popupBroadcastInterval) {
             clearInterval(_popupBroadcastInterval);
@@ -3200,6 +3492,10 @@ try {
     // indistinguishable while cutting relay traffic to a third.
     const LAN_TIME_MIN_INTERVAL_MS = 50;
 
+    /**
+     * Lan Send.
+     * @param {*} msg
+     */
     function _lanSend(msg) {
         const ws = _lanShare && _lanShare.ws;
         if (!ws || ws.readyState !== 1) return;
@@ -3211,8 +3507,10 @@ try {
         try { ws.send(JSON.stringify(msg)); } catch (_) {}
     }
 
-    // Answer a viewer's `hello`. No song loaded yet → answer nothing; the
-    // viewer hello-polls until a config with a filename can be produced.
+    /**
+     * Answer a viewer's `hello`. No song loaded yet → answer nothing; the
+     * viewer hello-polls until a config with a filename can be produced.
+     */
     function _lanHelloResponse(popupId) {
         if (!_lanShare || !currentFilename) return null;
         const audio = document.getElementById('audio');
@@ -3226,6 +3524,9 @@ try {
         };
     }
 
+    /**
+     * Lan Connect.
+     */
     function _lanConnect() {
         if (!_lanShare || _lanShare.ws) return;
         let ws;
@@ -3249,6 +3550,9 @@ try {
         ws.onerror = () => { try { ws.close(); } catch (_) {} };
     }
 
+    /**
+     * Lan Schedule Reconnect.
+     */
     function _lanScheduleReconnect() {
         if (!_lanShare || _lanShare.retryTimer) return;
         const delay = _lanShare.backoffMs || 1000;
@@ -3260,14 +3564,20 @@ try {
         }, delay);
     }
 
-    // Capture `panel` as the shared config — with the note-detect fields
-    // stripped (viewers are passive mirrors; never forward mic bindings).
+    /**
+     * Capture `panel` as the shared config — with the note-detect fields
+     * stripped (viewers are passive mirrors; never forward mic bindings).
+     */
     function _lanCaptureCfg(panel) {
         return Object.assign(_captureFollowerConfig(panel), {
             detectChannel: 'mono', detectDeviceName: '', detectVerifierOffsetMs: 0,
         });
     }
 
+    /**
+     * Start Lan Share.
+     * @param {*} panel
+     */
     function startLanShare(panel) {
         if (typeof WebSocket !== 'function') {
             _showMainToast('LAN sharing requires WebSocket support.');
@@ -3286,6 +3596,9 @@ try {
         return true;
     }
 
+    /**
+     * Stop Lan Share.
+     */
     function stopLanShare() {
         if (!_lanShare) return;
         _lanSend({ type: 'share-ended' });   // terminal for viewers — before teardown
@@ -3299,9 +3612,11 @@ try {
         } catch (_) {}
     }
 
-    // Re-arm a share that was active when this window last unloaded (crash,
-    // reload, app relaunch) so viewers left open on other devices recover
-    // without any interaction — the crash-recovery contract (splitscreen#21).
+    /**
+     * Re-arm a share that was active when this window last unloaded (crash,
+     * reload, app relaunch) so viewers left open on other devices recover
+     * without any interaction — the crash-recovery contract (splitscreen#21).
+     */
     function _maybeResumeLanShare() {
         if (FOLLOWER || REMOTE_JOIN || _lanShare) return;
         if (typeof WebSocket !== 'function') return;
@@ -3316,10 +3631,12 @@ try {
         } catch (_) {}
     }
 
-    // Copy with a non-secure-context fallback. LAN hosts are frequently plain
-    // http (e.g. a Docker session at http://192.168.x.x), where
-    // navigator.clipboard does not exist — fall back to the classic
-    // hidden-textarea + execCommand('copy') path. Resolves true on success.
+    /**
+     * Copy with a non-secure-context fallback. LAN hosts are frequently plain
+     * http (e.g. a Docker session at http://192.168.x.x), where
+     * navigator.clipboard does not exist — fall back to the classic
+     * hidden-textarea + execCommand('copy') path. Resolves true on success.
+     */
     function _copyTextToClipboard(text) {
         return new Promise((resolve) => {
             try {
@@ -3333,6 +3650,10 @@ try {
             resolve(_copyViaExecCommand(text));
         });
     }
+    /**
+     * Copy Via Exec Command.
+     * @param {*} text
+     */
     function _copyViaExecCommand(text) {
         try {
             const ta = document.createElement('textarea');
@@ -3356,9 +3677,15 @@ try {
     // Docker session, location.origin is already the address the viewer needs.
     let _lanShareModalEl = null;
     let _lanShareModalSeq = 0;   // invocation nonce — see the await note below
+    /**
+     * Close Lan Share Modal.
+     */
     function _closeLanShareModal() {
         if (_lanShareModalEl) { try { _lanShareModalEl.remove(); } catch (_) {} _lanShareModalEl = null; }
     }
+    /**
+     * Show Lan Share Modal.
+     */
     async function _showLanShareModal() {
         // The getLanAccess() await below yields: a second invocation entering
         // meanwhile would otherwise stack a second overlay on top of this
@@ -3475,11 +3802,13 @@ try {
     // ══════════════════════════════════════════════════════════════════════
     let _mainChannelListenerAttached = false;
     let _mainAudioListenersEl = null;   // the <audio> the play/pause listeners are bound to
-    // Broadcast the current play/pause state to any popups so they can pause
-    // their time extrapolation precisely (instead of relying solely on the
-    // "audio time stopped advancing" heuristic + backstop). Best-effort: in
-    // JUCE mode the <audio> element's play/pause events may not fire — the
-    // follower's heuristic still covers that case.
+    /**
+     * Broadcast the current play/pause state to any popups so they can pause
+     * their time extrapolation precisely (instead of relying solely on the
+     * "audio time stopped advancing" heuristic + backstop). Best-effort: in
+     * JUCE mode the <audio> element's play/pause events may not fire — the
+     * follower's heuristic still covers that case.
+     */
     function _broadcastMainPlayState() {
         try {
             const ch = _ssChannel();
@@ -3490,6 +3819,9 @@ try {
             _lanSend(msg);
         } catch (_) {}
     }
+    /**
+     * Ensure Main Broadcaster And Listener.
+     */
     function _ensureMainBroadcasterAndListener() {
         if (FOLLOWER) return;            // never run in popup
         // Two independently-guarded halves. The channel handler is once-ever;
@@ -3529,11 +3861,13 @@ try {
         }
     }
 
-    // Re-instate a panel that was popped out, using the original config
-    // we captured at pop-out time, overlaid with anything the popup told
-    // us via `finalState`.
-    // Smallest LAYOUTS entry with room for `n` panels; falls back to the
-    // largest available layout if nothing fits (caller must then truncate).
+    /**
+     * Re-instate a panel that was popped out, using the original config
+     * we captured at pop-out time, overlaid with anything the popup told
+     * us via `finalState`.
+     * Smallest LAYOUTS entry with room for `n` panels; falls back to the
+     * largest available layout if nothing fits (caller must then truncate).
+     */
     function _bestFitLayout(n) {
         let best = null;
         for (const k of Object.keys(LAYOUTS)) {
@@ -3543,6 +3877,12 @@ try {
         return Object.keys(LAYOUTS).reduce((a, b) => (LAYOUTS[b].panels > LAYOUTS[a].panels ? b : a));
     }
 
+    /**
+     * Redock Panel.
+     * @param {*} popupId
+     * @param {*} finalState
+     * @param {*} finalStates
+     */
     function _redockPanel(popupId, finalState, finalStates) {
         // A start (e.g. the rebuild that follows a pop-out) is in flight —
         // tearing down now would race the in-flight panel build. Queue it;
@@ -3626,6 +3966,9 @@ try {
     // ── Layout cycle button ──
     let layoutBtn = null;
 
+    /**
+     * Create Layout Btn.
+     */
     function createLayoutBtn() {
         if (layoutBtn) return layoutBtn;
         const slot = _ssPlayerControlSlot();
@@ -3662,7 +4005,9 @@ try {
         return layoutBtn;
     }
 
-    // ── Player HUD fade (top-left song title fades out once playback begins) ──
+    /**
+     * ── Player HUD fade (top-left song title fades out once playback begins) ──
+     */
     function showHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3670,6 +4015,9 @@ try {
         hud.style.opacity = '1';
     }
 
+    /**
+     * Fade Out Hud.
+     */
     function fadeOutHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3677,6 +4025,9 @@ try {
         hud.style.opacity = '0';
     }
 
+    /**
+     * Restore Hud.
+     */
     function restoreHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3684,6 +4035,9 @@ try {
         hud.style.opacity = '';
     }
 
+    /**
+     * On Audio Play.
+     */
     function onAudioPlay() {
         if (active) fadeOutHud();
     }
@@ -3703,6 +4057,10 @@ try {
         'viz-picker',
     ];
 
+    /**
+     * Set Redundant Controls Hidden.
+     * @param {*} hide
+     */
     function setRedundantControlsHidden(hide) {
         for (const id of REDUNDANT_CONTROL_IDS) {
             const el = document.getElementById(id);
@@ -3714,6 +4072,9 @@ try {
     let hideBtn = null;
     let floatBtn = null;
 
+    /**
+     * Create Hide Btn.
+     */
     function createHideBtn() {
         if (hideBtn) return hideBtn;
         const slot = _ssPlayerControlSlot();
@@ -3740,6 +4101,9 @@ try {
         return hideBtn;
     }
 
+    /**
+     * Create Floating Show Btn.
+     */
     function createFloatingShowBtn() {
         if (floatBtn) return floatBtn;
         const player = document.getElementById('player');
@@ -3757,6 +4121,10 @@ try {
         return floatBtn;
     }
 
+    /**
+     * Toggle Panel Bar.
+     * @param {*} panel
+     */
     function togglePanelBar(panel) {
         const hiding = panel.bar.style.display !== 'none';
         panel.bar.style.display = hiding ? 'none' : '';
@@ -3786,6 +4154,9 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Toggle Controls Visibility.
+     */
     function toggleControlsVisibility() {
         controlsHidden = !controlsHidden;
         localStorage.setItem('splitscreenControlsHidden', controlsHidden);
@@ -3795,7 +4166,9 @@ try {
         updateBtn();
     }
 
-    // ── Toggle button ──
+    /**
+     * ── Toggle button ──
+     */
     function updateBtn() {
         const btn = document.getElementById('btn-splitscreen');
         if (btn) btn.className = active ? ON_CLASS : OFF_CLASS;
@@ -3807,6 +4180,9 @@ try {
         if (floatBtn) floatBtn.style.display = (active && controlsHidden) ? '' : 'none';
     }
 
+    /**
+     * Inject Btn.
+     */
     function injectBtn() {
         // v3: mount split-screen controls into the host's stable plugin-control
         // slot (Plugins rail popover). In v3 the slot is always present, so the
@@ -3991,6 +4367,10 @@ try {
     // backstop in case a `playstate:false` (pause) message is dropped.
     const _FOLLOWER_MAX_EXTRAP_S = 2.0;
 
+    /**
+     * Install Follower Audio Shim.
+     * @param {*} audio
+     */
     function _installFollowerAudioShim(audio) {
         if (!audio) return;
         try {
@@ -4017,9 +4397,11 @@ try {
     // song change — doesn't stack listeners; also covers a hypothetical
     // element swap).
     let _followerPlayGuardEl = null;
-    // Keep the popup's <audio> paused — and re-pause it whenever anything
-    // calls .play() (autoplay, a src swap on song change). Mute alone leaves
-    // it decoding the stream for nothing.
+    /**
+     * Keep the popup's <audio> paused — and re-pause it whenever anything
+     * calls .play() (autoplay, a src swap on song change). Mute alone leaves
+     * it decoding the stream for nothing.
+     */
     function _silenceFollowerAudio(audio) {
         if (!audio) return;
         audio.muted = true;
@@ -4031,9 +4413,11 @@ try {
         }
     }
 
-    // rAF loop that advances _followerCurrentTime between `time` broadcasts
-    // while the main window reports playback. Idempotent; cancelled on
-    // orphan / unload.
+    /**
+     * rAF loop that advances _followerCurrentTime between `time` broadcasts
+     * while the main window reports playback. Idempotent; cancelled on
+     * orphan / unload.
+     */
     function _startFollowerInterp() {
         if (_followerInterpRaf != null) return;
         const tick = () => {
@@ -4049,21 +4433,26 @@ try {
         };
         _followerInterpRaf = requestAnimationFrame(tick);
     }
+    /**
+     * Stop Follower Interp.
+     */
     function _stopFollowerInterp() {
         if (_followerInterpRaf != null) { cancelAnimationFrame(_followerInterpRaf); _followerInterpRaf = null; }
     }
 
-    // Handle a `time` broadcast: derive playback rate vs wall-time, re-anchor,
-    // fan the value out to every panel highway.
-    //
-    // The most reliable "is it playing" signal is observing the broadcast
-    // clock itself advance in real time (dT/dWall ≈ playbackRate) — that works
-    // regardless of whether the main window's <audio>.paused is meaningful
-    // (it isn't, in JUCE mode). The optional `playing` flag on the message is
-    // only used to STOP extrapolating when the clock has also stalled: it lets
-    // us tell "main paused" from "main tab throttled to ~1 Hz" within the gap
-    // between messages, which the clock alone can't. The 2 s extrapolation
-    // backstop covers the case where the flag is absent/unreliable.
+    /**
+     * Handle a `time` broadcast: derive playback rate vs wall-time, re-anchor,
+     * fan the value out to every panel highway.
+     *
+     * The most reliable "is it playing" signal is observing the broadcast
+     * clock itself advance in real time (dT/dWall ≈ playbackRate) — that works
+     * regardless of whether the main window's <audio>.paused is meaningful
+     * (it isn't, in JUCE mode). The optional `playing` flag on the message is
+     * only used to STOP extrapolating when the clock has also stalled: it lets
+     * us tell "main paused" from "main tab throttled to ~1 Hz" within the gap
+     * between messages, which the clock alone can't. The 2 s extrapolation
+     * backstop covers the case where the flag is absent/unreliable.
+     */
     function _onFollowerTimeMessage(t, playing) {
         const nowP = performance.now();
         let advancedInRealtime = false;
@@ -4103,7 +4492,9 @@ try {
         _maybeDismissFollowerToastOnPlay(t);
     }
 
-    // Handle an explicit play/pause notice from the main window.
+    /**
+     * Handle an explicit play/pause notice from the main window.
+     */
     function _onFollowerPlayState(playing) {
         _followerPlaying = playing;
         if (playing) {
@@ -4118,8 +4509,10 @@ try {
         }
     }
 
-    // The main window is closing — stop syncing, tear the panels down, and
-    // tell the user. Idempotent.
+    /**
+     * The main window is closing — stop syncing, tear the panels down, and
+     * tell the user. Idempotent.
+     */
     function _onFollowerOrphaned(title, subText) {
         if (_followerOrphaned) return;
         _followerOrphaned = true;
@@ -4155,9 +4548,11 @@ try {
         document.body.appendChild(o);
     }
 
-    // Shared message dispatch for both follower transports: the local
-    // BroadcastChannel (popup windows) and the LAN relay WebSocket (remote
-    // viewers). Reads live module state, so it survives layout rebuilds.
+    /**
+     * Shared message dispatch for both follower transports: the local
+     * BroadcastChannel (popup windows) and the LAN relay WebSocket (remote
+     * viewers). Reads live module state, so it survives layout rebuilds.
+     */
     function _followerBusHandler(msg) {
         if (_followerOrphaned || !msg) return;
         const remote = !!(FOLLOWER && FOLLOWER.remote);
@@ -4207,6 +4602,9 @@ try {
     // handler can re-assert mute/pause + re-shim without re-querying.
     let _followerAudio = null;
 
+    /**
+     * Boot Follower Mode.
+     */
     function bootFollowerMode() {
         // Hide non-panel chrome with a single CSS rule so we don't have to
         // chase every element id slopsmith renders. The follower wrap covers
@@ -4300,12 +4698,14 @@ try {
         });
     }
 
-    // Load `filename` in the popup, wait for it to be ready, then build the
-    // follower panels from `cfgs`. Used both on initial bootstrap
-    // (cfgs = [FOLLOWER]) and on song-change (cfgs = current panel states).
-    // The popup's main highway is shared across all panels for time / song
-    // info purposes; per-panel arrangement is set inside each panel's own
-    // WebSocket via initPanel.
+    /**
+     * Load `filename` in the popup, wait for it to be ready, then build the
+     * follower panels from `cfgs`. Used both on initial bootstrap
+     * (cfgs = [FOLLOWER]) and on song-change (cfgs = current panel states).
+     * The popup's main highway is shared across all panels for time / song
+     * info purposes; per-panel arrangement is set inside each panel's own
+     * WebSocket via initPanel.
+     */
     async function loadSongInFollower(filename, cfgs) {
         const firstArr = (cfgs[0] && cfgs[0].arrangement) || 0;
         try {
@@ -4343,6 +4743,9 @@ try {
         _buildFollowerToolbar();
     }
 
+    /**
+     * Wait For Highway Ready.
+     */
     function waitForHighwayReady() {
         return new Promise(resolve => {
             const info = highway.getSongInfo();
@@ -4384,8 +4787,10 @@ try {
     let _followerLayoutKey = 'follower';
     const FOLLOWER_TOOLBAR_H = 32;
 
-    // Convert a captured panel config (cfg) and arrIdx into the prefs
-    // shape that initPanel expects.
+    /**
+     * Convert a captured panel config (cfg) and arrIdx into the prefs
+     * shape that initPanel expects.
+     */
     function _followerCfgToPrefs(cfg, arrIdx) {
         const arrName = _modeToArrName(cfg.mode, arrangements[arrIdx]?.name || '');
         return {
@@ -4405,10 +4810,12 @@ try {
         };
     }
 
-    // Build N panels per `layoutKey` into the wrap div. `cfgs` is an array
-    // of panel configs (one per slot); slots beyond cfgs.length get smart
-    // defaults via getDefaultArrangements. Replaces the older single-panel
-    // buildFollowerPanel so the popup can host any of the standard layouts.
+    /**
+     * Build N panels per `layoutKey` into the wrap div. `cfgs` is an array
+     * of panel configs (one per slot); slots beyond cfgs.length get smart
+     * defaults via getDefaultArrangements. Replaces the older single-panel
+     * buildFollowerPanel so the popup can host any of the standard layouts.
+     */
     function buildFollowerLayout(cfgs, layoutKey) {
         layoutKey = FOLLOWER_LAYOUT_PANELS[layoutKey] ? layoutKey : 'follower';
         _followerLayoutKey = layoutKey;
@@ -4537,6 +4944,9 @@ try {
     // Built once per popup, the layout selector triggers rebuild of the
     // panel grid.
     let _followerToolbar = null;
+    /**
+     * Build Follower Toolbar.
+     */
     function _buildFollowerToolbar() {
         if (_followerToolbar) return _followerToolbar;
         const bar = document.createElement('div');
@@ -4578,9 +4988,11 @@ try {
         return bar;
     }
 
-    // Rebuild the popup's panel grid into a new layout. Captures the
-    // current panels' configs so existing slots survive the change; new
-    // slots fill with smart defaults via getDefaultArrangements.
+    /**
+     * Rebuild the popup's panel grid into a new layout. Captures the
+     * current panels' configs so existing slots survive the change; new
+     * slots fill with smart defaults via getDefaultArrangements.
+     */
     function rebuildFollowerLayout(newLayoutKey) {
         if (!FOLLOWER_LAYOUT_PANELS[newLayoutKey]) return;
         if (_followerRebuildBusy) {
@@ -4602,19 +5014,23 @@ try {
         buildFollowerLayout(cfgs, newLayoutKey);
     }
 
-    // Capture every popup panel's current state into an array of cfgs,
-    // suitable for handing back to loadSongInFollower / buildFollowerLayout.
-    // Reads from the live panels so any user changes since pop-out or
-    // last layout change are honoured.
+    /**
+     * Capture every popup panel's current state into an array of cfgs,
+     * suitable for handing back to loadSongInFollower / buildFollowerLayout.
+     * Reads from the live panels so any user changes since pop-out or
+     * last layout change are honoured.
+     */
     function _captureAllFollowerConfigs() {
         return panels.map(p => _captureFollowerConfig(p));
     }
 
-    // Rebuild the follower panels for a new song while preserving the
-    // user's layout + per-panel mode + arrangement choices. Triggered by
-    // the main window's `song-changed` broadcast. Single-flight: a change
-    // arriving while one is in progress is coalesced — only the latest
-    // pending filename runs after the current rebuild finishes.
+    /**
+     * Rebuild the follower panels for a new song while preserving the
+     * user's layout + per-panel mode + arrangement choices. Triggered by
+     * the main window's `song-changed` broadcast. Single-flight: a change
+     * arriving while one is in progress is coalesced — only the latest
+     * pending filename runs after the current rebuild finishes.
+     */
     async function _handleFollowerSongChange(newFilename) {
         if (_followerOrphaned) return;
         if (_followerRebuildBusy) { _followerPendingFilename = newFilename; return; }
@@ -4660,11 +5076,13 @@ try {
     let _followerToast = null;
     let _followerToastBaselineTime = 0;
 
-    // Common-tuning name resolver. Order-agnostic — works whether the
-    // tuning array is high-to-low or low-to-high (we test both ends for
-    // the drop pattern). Returns null for anything that isn't a flat
-    // uniform offset or a one-string drop variant; the caller falls
-    // back to displaying raw offsets in that case.
+    /**
+     * Common-tuning name resolver. Order-agnostic — works whether the
+     * tuning array is high-to-low or low-to-high (we test both ends for
+     * the drop pattern). Returns null for anything that isn't a flat
+     * uniform offset or a one-string drop variant; the caller falls
+     * back to displaying raw offsets in that case.
+     */
     function _resolveFollowerTuningName(tuning) {
         if (!Array.isArray(tuning) || tuning.length === 0) return null;
         const STANDARD_NAMES = {
@@ -4699,6 +5117,9 @@ try {
         return null;
     }
 
+    /**
+     * Dismiss Follower Toast.
+     */
     function _dismissFollowerToast() {
         if (!_followerToast) return;
         const toast = _followerToast;
@@ -4710,11 +5131,13 @@ try {
         }, FOLLOWER_TOAST_FADE_MS);
     }
 
-    // Called from the time-broadcast handler. Dismisses the toast the
-    // first time the main window's audio.currentTime advances past the
-    // baseline captured at toast-creation — i.e. play has actually
-    // started. While main is paused at the new song's start (t = 0),
-    // every broadcast carries the same t and the toast stays visible.
+    /**
+     * Called from the time-broadcast handler. Dismisses the toast the
+     * first time the main window's audio.currentTime advances past the
+     * baseline captured at toast-creation — i.e. play has actually
+     * started. While main is paused at the new song's start (t = 0),
+     * every broadcast carries the same t and the toast stays visible.
+     */
     function _maybeDismissFollowerToastOnPlay(t) {
         if (!_followerToast) return;
         if (t > _followerToastBaselineTime + FOLLOWER_TOAST_PLAY_THRESHOLD_S) {
@@ -4722,6 +5145,10 @@ try {
         }
     }
 
+    /**
+     * Show Follower Song Toast.
+     * @param {*} info
+     */
     function _showFollowerSongToast(info) {
         if (!info) return;
         // Replace any existing toast (rapid song-change sequence).
@@ -4823,11 +5250,13 @@ try {
     let _remoteWaitingEl = null;
     let _remoteWaitingShown = false;
 
-    // Hello-poll: runs pre-boot (host may not be sharing / have a song yet)
-    // AND while the waiting overlay is up after a host restart — a relaunched
-    // host that sits paused emits nothing on its own, so polling is what
-    // fetches the config that dismisses the overlay and re-syncs the song.
-    // Self-stops once booted and not waiting.
+    /**
+     * Hello-poll: runs pre-boot (host may not be sharing / have a song yet)
+     * AND while the waiting overlay is up after a host restart — a relaunched
+     * host that sits paused emits nothing on its own, so polling is what
+     * fetches the config that dismisses the overlay and re-syncs the song.
+     * Self-stops once booted and not waiting.
+     */
     function _remoteStartHelloPoll() {
         if (_remoteHelloTimer != null) return;
         _remoteHelloTimer = setInterval(() => {
@@ -4835,6 +5264,9 @@ try {
             _remoteSendHello();
         }, 3000);
     }
+    /**
+     * Remote Stop Hello Poll.
+     */
     function _remoteStopHelloPoll() {
         if (_remoteHelloTimer != null) {
             clearInterval(_remoteHelloTimer);
@@ -4842,6 +5274,10 @@ try {
         }
     }
 
+    /**
+     * Show Remote Waiting.
+     * @param {*} text
+     */
     function _showRemoteWaiting(text) {
         if (_followerOrphaned) return;
         _remoteWaitingShown = true;
@@ -4868,17 +5304,26 @@ try {
         if (t) t.textContent = text || 'Connecting…';
         _remoteWaitingEl.style.display = 'flex';
     }
+    /**
+     * Hide Remote Waiting.
+     */
     function _hideRemoteWaiting() {
         _remoteWaitingShown = false;   // hello-poll self-stops on its next tick
         if (_remoteWaitingEl) _remoteWaitingEl.style.display = 'none';
     }
 
+    /**
+     * Remote Send Hello.
+     */
     function _remoteSendHello() {
         if (_remoteWs && _remoteWs.readyState === 1) {
             try { _remoteWs.send(JSON.stringify({ type: 'hello', popupId: _remotePopupId })); } catch (_) {}
         }
     }
 
+    /**
+     * Remote Connect.
+     */
     function _remoteConnect() {
         if (_followerOrphaned) return;
         let ws;
@@ -4922,6 +5367,9 @@ try {
         ws.onerror = () => { try { ws.close(); } catch (_) {} };
     }
 
+    /**
+     * Remote Schedule Reconnect.
+     */
     function _remoteScheduleReconnect() {
         if (_followerOrphaned) return;
         const delay = _remoteBackoffMs;
@@ -4931,6 +5379,9 @@ try {
         }, delay);
     }
 
+    /**
+     * Boot Remote Join.
+     */
     function bootRemoteJoin() {
         _remotePopupId = 'lan-' + _newPopupId();
         _showRemoteWaiting('Connecting to host…');

From 749265baf4f641540fcf1dd892991e4e45798d1d Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Thu, 23 Jul 2026 03:46:10 -0600
Subject: [PATCH 5/6] fix: destroy live note detector when entering
 Lyrics/Jumping-Tab mode (#9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: destroy live note detector when entering Lyrics/Jumping-Tab mode

enterLyricsMode()/enterJumpingTabMode() hide detectBtn/channelBtn (fixed in
#5) because they're meaningless once the highway is stopped and the canvas
hidden, but a detector already running when the user switches into one of
these modes kept running silently — hiding its only on/off control left no
way to stop it from the UI, and detect on/off isn't persisted in prefs (only
channel/device/offset are), so it's purely an in-session toggle with no
other place tracking "should this still be on".

Now toggleDetect(panel) runs (destroying it) whenever a live detector exists
at mode entry, matching the button hide. Viz mode is unaffected — it keeps
the highway alive and detectBtn/channelBtn visible by design.

* fix: stop detector before the highway/controls in Lyrics/JT mode entry

Addresses CodeRabbit review on #9: toggleDetect(panel) ran after
panel.hw.stop() and after detectBtn was hidden, leaving the detector briefly
bound to an already-stopped highway and updating button style after the
button was already hidden. Moved the detector teardown up to run first,
before the highway stops and its controls hide.
---
 screen.js | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/screen.js b/screen.js
index da1aece..66c4d25 100644
--- a/screen.js
+++ b/screen.js
@@ -1822,6 +1822,13 @@ try {
         if (panel.vizMode) exitVizMode(panel, panel.arrIndex);
         if (panel.jumpingTabMode) exitJumpingTabMode(panel, panel.arrIndex);
         if (panel.tabActive) togglePanelTab(panel);
+        // Detect on/off isn't persisted in prefs (only channel/device/offset
+        // are) — it's a purely in-session toggle. With detectBtn about to be
+        // hidden the user would have no way to stop a live detector while in
+        // this mode, so turn it off (before the highway stops and the button
+        // hides) rather than leave it scoring against an already-stopped
+        // highway with an inaccessible control.
+        if (panel.detector) toggleDetect(panel);
         panel.hw.stop();
         panel.canvas.style.display = 'none';
 
@@ -1909,6 +1916,13 @@ try {
         if (panel.vizMode) exitVizMode(panel, panel.arrIndex);
         if (panel.lyricsMode) exitLyricsMode(panel, panel.arrIndex);
         if (panel.tabActive) togglePanelTab(panel);
+        // Detect on/off isn't persisted in prefs (only channel/device/offset
+        // are) — it's a purely in-session toggle. With detectBtn about to be
+        // hidden the user would have no way to stop a live detector while in
+        // this mode, so turn it off (before the highway stops and the button
+        // hides) rather than leave it scoring against an already-stopped
+        // highway with an inaccessible control.
+        if (panel.detector) toggleDetect(panel);
         panel.hw.stop();
         panel.canvas.style.display = 'none';
 

From 261011dd90c42d19f0337d2303d70ed18f105257 Mon Sep 17 00:00:00 2001
From: Carolina <79524656+carochacs@users.noreply.github.com>
Date: Thu, 23 Jul 2026 08:23:38 -0600
Subject: [PATCH 6/6] fix: notify user when redocking a panel with no song
 loaded (#10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_redockPanel() deleted the popups entry and bailed silently when
currentFilename was empty, dropping the popped-out panel's state with
no feedback — unlike the overflow-drop path a few lines down, which
already toasts. Addresses a CodeRabbit review comment on upstream
got-feedBack/feedBack-plugin-splitscreen#23.

Co-authored-by: Claude <noreply@anthropic.com>
---
 screen.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/screen.js b/screen.js
index 66c4d25..9599cbf 100644
--- a/screen.js
+++ b/screen.js
@@ -3906,7 +3906,10 @@ try {
         const entry = popups.get(popupId);
         if (!entry) return;
         popups.delete(popupId);
-        if (!currentFilename) return;
+        if (!currentFilename) {
+            _showMainToast('Could not dock panel — no song is currently loaded.');
+            return;
+        }
 
         // A popup that split itself into multiple sub-panels sends `finalStates`
         // (one capture per sub-panel, in on-screen order); fall back to the