fix(nav): nobody may monkey-patch window.showScreen — add screen:changing, make the shell listen (#924) (#925)

* fix(nav): the library sometimes showed the legacy screen — map 'home' inside showScreen

Testers: "randomly, when moving to the library from another menu option, the library shows the
old interface — never when a song ends."

━━━ WHAT WAS ACTUALLY HAPPENING ━━━

#home is the PRE-V3 library screen. The v3 shell replaced it with #v3-songs, and the mapping DID
exist — but only inside WRAPPERS on window.showScreen, and only for callers that go through
`window`. THREE independent parties monkey-patch it, each capturing whatever happens to be there
at the time:

    app.js publishes the raw function
      -> shell.js wraps it, adding the home -> v3-songs mapping
      -> the stems plugin wraps it AGAIN (src/main.js:1029), capturing the current value

Plugins load ASYNCHRONOUSLY. The chain links up in whatever order the race settles, and any
capture taken before shell.js installs — or any re-assignment after it — silently drops the
mapping. Hence "randomly".

AND THE INTERNAL CALLERS NEVER TOUCHED window.showScreen AT ALL. closeCurrentSong and the
Esc-from-settings shortcut call the IMPORTED showScreen, which no wrapper ever sees. Reproduced
in a browser: the unwrapped function with 'home' lands on the dead legacy screen EVERY time.

"Never when a song ends" is the tell, and it is what identified the mechanism: closeCurrentSong
resolves its target through _resolvePlayerOrigin(), which ALREADY applies this mapping. That one
path was fine — which is exactly why the bug looked random rather than total.

PRE-EXISTING, not a regression from the module carve: the onclick="showScreen('home')" links and
the wrapper-only mapping both date to 2026-06-22.

━━━ THE FIX ━━━

The guard lives inside showScreen now: ONE place, in the function every caller routes through,
instead of a chain of monkey-patches that must each remember. Wrapper order stops mattering, and
the module-internal callers are covered for the first time.

Verified in a browser: the raw, unwrapped showScreen('home') — which reproduced as #home — now
lands on #v3-songs, and cannot be undone by any wrapper order.

━━━ AND A [P1] I INTRODUCED, WHICH CODEX CAUGHT ━━━

My first cut mapped BOTH 'home' and 'v3-home', copied straight from _resolvePlayerOrigin.

That is correct THERE and wrong HERE. _resolvePlayerOrigin computes where to RETURN TO after a
song, and landing on the Songs list from the dashboard is the right behaviour. But #v3-home is
the v3 DASHBOARD — a real screen that the shell's Home nav, the onboarding tour and the dashboard
re-render listener all target. Redirecting it would have made Home unreachable.

A LEGACY ALIAS IS NOT THE SAME THING AS A RETURN TARGET. Only 'home' is mapped now, and a test
pins that: re-adding 'v3-home' to the guard fails it.

4 tests, bite-tested both ways.

node 1049, pytest 2425, ESLint 0, Codex 0.

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

* fix(nav): nobody may monkey-patch window.showScreen — add screen:changing, make the shell listen (#924)

window.showScreen was wrapped by THREE independent parties, each capturing whatever happened to be
there at the time:

    app.js publishes the raw function
      -> static/v3/shell.js wrapped it (to call syncActive, and to map home -> v3-songs)
      -> the stems plugin wrapped it AGAIN (to tear down on leaving the player)

Plugins load ASYNCHRONOUSLY, so the chain linked up in whatever order the race settled. A capture
taken before shell.js installed silently dropped the mapping it carried — and the library opened on
the dead legacy #home screen. Testers saw that as "randomly, the library shows the old interface"
(#923).

#923 fixed the symptom by moving the mapping inside showScreen. This removes the CAUSE: neither
wrapper ever needed to be one.

━━━ TWO EVENTS, AND THE DISTINCTION IS THE WHOLE POINT ━━━

    screen:changing  emitted BEFORE anything happens. "I am leaving `from`." Teardown/cancel here.
    screen:changed   emitted after the DOM and data settle. "I am on `id`." Now carries `from`.

screen:changing is new, and it exists because Codex caught me collapsing the two. The stems plugin
tore down its audio graph BEFORE showScreen did anything; screen:changed fires at the very END,
after core awaits library and provider loads — so moving the plugin onto it would have delayed
teardown behind a slow fetch, or skipped it entirely if that fetch threw, and stems would keep
playing on a non-player screen. A test pins the ordering: screen:changing must precede the first
await.

shell.js is a plain screen:changed listener now, like app.js, audio-mixer.js and tour-engine.js
already were. window.showScreen is an unwrapped function again, and tests/js/
no_showscreen_monkeypatch.test.js fails CI if anything in static/ ever assigns to it again — so the
hazard is structurally impossible rather than merely avoided.

━━━ AND A FALLBACK THAT COULD NEVER FIRE ━━━

My retry-if-the-bus-is-late path listened for `slopsmith:capabilities:ready`. Core dispatches
`feedBack:capabilities:ready` (capabilities.js:1536) — the slopsmith: name is the PRE-DMCA event
and nothing has emitted it since the rename. Codex caught it. A guard that cannot fire is worse
than no guard: it reads as protection and is decoration.

(The same dead-event bug turned out to be sitting in THREE of the stems plugin's fallbacks, where
it has silently disabled its lifecycle wiring whenever the bus was late. Fixed in
feedback-plugin-stems#38.)

VERIFIED. A/B against origin/main: the nav highlight and topbar title follow IDENTICALLY with
shell.js as a listener; screen:changing -> screen:changed fire in order with the right {id, from};
window.showScreen is unwrapped; and showScreen('home') still lands on v3-songs.

node 1053, pytest 2425, ESLint 0, Codex 0.

Closes #924

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

---------

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

static/v3/shell.js

@@ -318,22 +318,49 @@
         }
     }
 
-    // ── showScreen wrapper (idempotent rehydration — design/05 §Rehydration) ─
+    // ── Stay in sync with the active screen (idempotent rehydration — design/05) ─
+    //
+    // This USED to monkey-patch window.showScreen. It doesn't any more, and that is the point.
+    //
+    // Three parties were wrapping that one global — app.js publishes it, this wrapped it, and the
+    // stems plugin wrapped it again — each capturing whatever happened to be there at the time.
+    // Plugins load ASYNCHRONOUSLY, so the chain linked up in whatever order the race settled, and
+    // a capture taken before this installed silently dropped the home -> v3-songs mapping this
+    // wrapper carried. That is why the library intermittently showed the legacy screen (#923).
+    //
+    // The mapping lives inside showScreen() now, where no wrapper can lose it. And everything
+    // left here is just "the screen changed" — which showScreen already EMITS, and which app.js,
+    // audio-mixer.js and tour-engine.js have always listened for rather than patching.
+    //
+    // So: be a listener, like everyone else. window.showScreen is a plain function again.
     function installShowScreenHook() {
         const hooks = window.__feedBackV3ShellHooks || (window.__feedBackV3ShellHooks = {});
-        hooks.syncActive = syncActive; // always point at the latest impl
+        hooks.syncActive = syncActive;   // always point at the latest impl
         if (hooks.installed) return;
         hooks.installed = true;
-        hooks.baseShowScreen = window.showScreen;
-        window.showScreen = function (id) {
-            // Route every "go to the library" navigation to the v3 native Songs
-            // screen instead of the legacy #home library, so player-close,
-            // settings-back, the hidden legacy navbar, etc. all stay in v3.
-            const target = (id === 'home') ? 'v3-songs' : id;
-            const r = hooks.baseShowScreen ? hooks.baseShowScreen.call(this, target) : undefined;
-            try { hooks.syncActive && hooks.syncActive(target); } catch (e) { /* non-fatal */ }
-            return r;
+
+        // RETRY IF THE BUS IS LATE. The old wrapper didn't need window.feedBack to exist; a
+        // listener does. Bailing out when it isn't ready yet would silently leave the sidebar
+        // highlight and topbar title frozen forever — a dead nav, with nothing thrown. (Codex
+        // caught the identical hole in the stems plugin's version of this.)
+        const wire = () => {
+            const bus = window.feedBack;
+            if (!bus || typeof bus.on !== 'function') {
+                // `feedBack:capabilities:ready` — capabilities.js:1536. NOT the slopsmith: name:
+                // that was the pre-DMCA event and NOTHING dispatches it any more, so a fallback
+                // keyed on it can never fire. Codex caught exactly that here. (The old alias is
+                // kept too, in case an older capabilities build is in play.)
+                window.addEventListener('feedBack:capabilities:ready', wire, { once: true });
+                window.addEventListener('slopsmith:capabilities:ready', wire, { once: true });
+                return;
+            }
+            bus.on('screen:changed', (ev) => {
+                const id = ev && ev.detail && ev.detail.id;
+                if (!id) return;
+                try { hooks.syncActive && hooks.syncActive(id); } catch (e) { /* non-fatal */ }
+            });
         };
+        wire();
     }
 
     // ── Boot ────────────────────────────────────────────────────────────────