From a222b45c0228e501e2863cb50adf636535bc0ef6 Mon Sep 17 00:00:00 2001
From: Byron Gamatos <xasiklas@gmail.com>
Date: Sat, 11 Jul 2026 18:41:52 +0200
Subject: [PATCH] =?UTF-8?q?refactor(app):=20carve=20the=20viz=20layer=20ou?=
 =?UTF-8?q?t=20of=20app.js=20=E2=80=94=20and=20delete=20the=20loader=20sea?=
 =?UTF-8?q?m=20(R3a)=20(#880)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

static/js/viz.js (770 lines) — the viz picker, renderer selection, Auto-match,
the WebGL2 probe, the 3D-promotion nag, the notation hints. Bodies VERBATIM.
app.js 11,603 → 10,857.

THE SEAM IS GONE. #878's plugin-loader needed configurePluginLoader({
populateVizPicker }) purely because _populateVizPicker lived in app.js and
importing app.js would have closed a cycle. viz.js is a LEAF — it imports NOTHING
— so plugin-loader now imports _populateVizPicker straight from it. The _host
object, the configure function, its loud-default guard, and the wiring line in
app.js are all deleted. The second carve simplifies the first.

  app.js -> { plugin-loader, viz }
  plugin-loader -> viz
  viz -> (nothing)

NOT A PURE MOVE — one listener block had to be SPLIT. app.js had a single
top-level `if (window.feedBack) { … }` registering four handlers, and only two
were viz. song:loaded / arrangement:changed / song:ready (the mastery slider)
stay in app.js and now call the imported _autoMatchViz / _maybeShowNotationViewHint.
The viz:reverted handler MOVES, because it REASSIGNS _cancelPendingAutoLabel and
an imported binding is read-only — `_cancelPendingAutoLabel = null` would throw if
the listener stayed behind while the state moved.

ORDER CHECKED, NOT ASSUMED: viz.js's song:ready listener now registers BEFORE
app.js's own (imports evaluate first). Safe — _pendingPromotionNag is only ever
set inside _populateVizPicker, which runs at boot/plugin-refresh, never from
inside the other song:ready handler, so the two are independent.

VERIFIED — the listeners are the risk here, so they were DRIVEN, not just booted.
A/B against origin/main in two browsers:
  * viz picker: 6 options (auto|default|venue|drum_highway_3d|keys_highway_3d|
    highway_3d), selected highway_3d, Auto label — IDENTICAL. This alone proves
    plugin-loader's direct import of viz.js works.
  * emit('viz:reverted') -> picker resets to default, localStorage resets to
    default, the warning logs — IDENTICAL. The MOVED listener fires.
  * emit('song:ready') -> mastery slider enables, no throw — IDENTICAL. The SPLIT
    listener still does both halves.
  * plugin screens, module injections, 37 capability participants — IDENTICAL.
  * zero console/page errors on both.

pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean. no-cycle re-bitten on
the 3-module graph (viz -> plugin-loader fails).

Codex preflight raised a [P2] claiming viz.js's top-level bus guards would be
false because "app.js only creates the event bus later" — FALSE POSITIVE. app.js
does not create the bus; capabilities.js does, from its own <script type="module">
at index.html:122, and module scripts execute in document order, so the bus exists
long before app.js's import graph evaluates. Instrumented the setter: by viz.js's
turn `window.feedBack.on` is already a function, and the viz:reverted listener is
provably attached (firing it resets the picker). The ordering is also enforced by
test_app_shell_loads_capability_registry_before_app_runtime.

Harnesses: 5 tests retargeted to viz.js across legacy_shim_hits, venue_scene_3d,
venue_viz (each SPLIT — their non-viz tests still read app.js).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 static/app.js                     | 758 +----------------------------
 static/js/plugin-loader.js        |  43 +-
 static/js/viz.js                  | 770 ++++++++++++++++++++++++++++++
 tests/js/legacy_shim_hits.test.js |   4 +-
 tests/js/venue_scene_3d.test.js   |   7 +-
 tests/js/venue_viz.test.js        |  14 +-
 6 files changed, 801 insertions(+), 795 deletions(-)
 create mode 100644 static/js/viz.js

diff --git a/static/app.js b/static/app.js
index d5a376e..8e75e02 100644
--- a/static/app.js
+++ b/static/app.js
@@ -1,8 +1,13 @@
 import {
     bootstrapPluginsAndUi,
-    configurePluginLoader,
     loadPlugins,
 } from './js/plugin-loader.js';
+import {
+    _autoMatchViz,
+    _maybeShowNotationViewHint,
+    _populateVizPicker,
+    setViz,
+} from './js/viz.js';
 
 // Demo analytics — real impl set by demo.js; no-op in normal builds
 window.feedBackDemoTrack = window.feedBackDemoTrack ?? null;
@@ -7669,756 +7674,8 @@ if (window.feedBack) {
             _maybeShowNotationViewHint(sel.value);
         }
     });
-    // Highway signals when it's auto-reverted to the default renderer
-    // after a broken plugin (init failure or repeated draw failures).
-    // Sync the picker + persisted selection so the UI stops advertising
-    // the broken choice and the user doesn't hit the same failure on
-    // next reload.
-    window.feedBack.on('viz:reverted', (e) => {
-        const sel = document.getElementById('viz-picker');
-        if (sel) sel.value = 'default';
-        // Cancel any pending viz:renderer:ready label listener — the renderer
-        // that was queued never became (or stayed) active.
-        if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
-        // Clear any Auto-resolved label — the renderer that was advertised
-        // never became (or stayed) active.
-        _setAutoVizLabel(null);
-        try { localStorage.setItem('vizSelection', 'default'); } catch (_) {}
-        console.warn(
-            `viz picker: reverted to default renderer (${e.detail?.reason || 'unknown'}).`
-        );
-    });
 }
 
-// ── Visualization picker (feedBack#36) ─────────────────────────────────
-//
-// Discovers viz plugins via /api/plugins and adds them to the #viz-picker
-// dropdown. A viz plugin declares itself by setting `"type": "visualization"`
-// in its plugin.json AND exposing a factory function on
-// window.feedBackViz_<id> that returns an object matching the setRenderer
-// contract ({init, draw, resize, destroy}).
-//
-// The "default" option in the dropdown is the built-in 2D highway that
-// lives inside createHighway(); selecting it calls setRenderer(null) which
-// restores the default renderer. The bundled 3D Highway plugin
-// (plugins/highway_3d/) registers as id `highway_3d` and is the new
-// fresh-install default per feedBack#160 PR 3.
-
-// ── WebGL2 detection (one-shot probe) ────────────────────────────────────
-// 3D Highway requires WebGL2. On environments where it's unavailable
-// (older browsers, some embedded webviews, software-only contexts), we
-// silently fall back to the Classic 2D Highway and flash a single toast
-// so the user knows why their highway looks different. Cached so we don't
-// thrash the GPU with repeat throwaway-canvas creations.
-let _webgl2Probe = null;
-function _canRun3D() {
-    if (_webgl2Probe !== null) return _webgl2Probe;
-    try {
-        const c = document.createElement('canvas');
-        const gl = c.getContext('webgl2');
-        _webgl2Probe = !!gl;
-        // Lose the context immediately — the probe canvas is never reused.
-        if (gl && gl.getExtension) {
-            const ext = gl.getExtension('WEBGL_lose_context');
-            if (ext && ext.loseContext) ext.loseContext();
-        }
-    } catch (_) { _webgl2Probe = false; }
-    return _webgl2Probe;
-}
-
-// ── Migration / nag flags ────────────────────────────────────────────────
-// `feedBack_3d_promoted_v1` is set the first time we auto-flip an existing
-// `vizSelection='default'` user to `'highway_3d'`. Persistence ensures we
-// don't re-nag on every reload — and ensures the WebGL2 fallback path
-// doesn't ping-pong (one fallback toast, not one per page load).
-const _3D_PROMOTED_FLAG_KEY = 'feedBack_3d_promoted_v1';
-function _markPromoted() {
-    try { localStorage.setItem(_3D_PROMOTED_FLAG_KEY, '1'); } catch (_) {}
-}
-function _hasPromotedFlag() {
-    try { return localStorage.getItem(_3D_PROMOTED_FLAG_KEY) === '1'; }
-    catch (_) { return false; }
-}
-
-// Pending nag: queued during _populateVizPicker, fired on the first
-// `song:ready` (so the toast lands when the user actually opens the
-// player, not at page load when they're still in the library).
-// `song:ready` is emitted by highway.js via window.feedBack.emit(), so
-// subscribe through the same EventTarget. window.feedBack is created in
-// this same file before _populateVizPicker is reachable, so the global
-// is guaranteed to exist by the time this listener registers — but guard
-// anyway in case this module is ever loaded standalone for tests.
-let _pendingPromotionNag = false;
-if (window.feedBack && typeof window.feedBack.on === 'function') {
-    window.feedBack.on('song:ready', () => {
-        if (!_pendingPromotionNag) return;
-        _pendingPromotionNag = false;
-        _showPromotionNag();
-    });
-}
-
-function _showPromotionNag() {
-    // Lightweight toast — no dependency on a generic toast helper, since
-    // app.js doesn't currently have one. Fixed bottom-center, dismissed
-    // by clicking either action button or the × close.
-    const existing = document.getElementById('feedBack-3d-nag');
-    if (existing) existing.remove();
-    const wrap = document.createElement('div');
-    wrap.id = 'feedBack-3d-nag';
-    wrap.setAttribute('role', 'dialog');
-    wrap.setAttribute('aria-modal', 'false');
-    wrap.setAttribute('aria-label', '3D Highway upgrade notification');
-    wrap.style.cssText = `
-        position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
-        background: linear-gradient(145deg, #1a1a30 0%, #0d0d18 100%);
-        border: 1px solid rgba(64,128,224,0.4);
-        border-radius: 12px; padding: 12px 16px;
-        box-shadow: 0 12px 40px rgba(0,0,0,0.5), 0 0 0 1px rgba(64,128,224,0.15);
-        font-size: 13px; color: #e2e8f0; z-index: 10000;
-        max-width: 480px; display: flex; align-items: center; gap: 12px;
-    `;
-    wrap.innerHTML = `
-        <span aria-live="polite" style="flex:1;">Your highway was upgraded to <strong>3D</strong>.</span>
-        <button type="button" data-act="tour" style="background:rgba(64,128,224,0.25);color:#e2e8f0;border:1px solid rgba(64,128,224,0.5);padding:6px 12px;border-radius:8px;font-size:12px;cursor:pointer;">Try the tour</button>
-        <button type="button" data-act="back" style="background:transparent;color:#cbd5e1;border:1px solid rgba(255,255,255,0.1);padding:6px 12px;border-radius:8px;font-size:12px;cursor:pointer;">Switch back to 2D</button>
-        <button type="button" data-act="dismiss" aria-label="Dismiss" style="background:transparent;color:#6b7280;border:none;font-size:18px;cursor:pointer;padding:0 4px;line-height:1;">×</button>
-    `;
-    wrap.addEventListener('click', (ev) => {
-        const btn = ev.target.closest('button[data-act]');
-        if (!btn) return;
-        const act = btn.dataset.act;
-        if (act === 'tour') {
-            try {
-                if (window.feedBackTour && typeof window.feedBackTour.start === 'function') {
-                    window.feedBackTour.start('highway_3d');
-                }
-            } catch (_) {}
-        } else if (act === 'back') {
-            setViz('default');
-        }
-        wrap.remove();
-    });
-    document.body.appendChild(wrap);
-}
-
-function _showWebGL2FallbackToast() {
-    // One-time fallback notice. Same lightweight DOM as the nag, simpler
-    // copy and only a dismiss button.
-    if (document.getElementById('feedBack-3d-fallback')) return;
-    const wrap = document.createElement('div');
-    wrap.id = 'feedBack-3d-fallback';
-    wrap.setAttribute('role', 'dialog');
-    wrap.setAttribute('aria-modal', 'false');
-    wrap.setAttribute('aria-label', 'WebGL2 not available');
-    wrap.style.cssText = `
-        position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
-        background: #181830; border: 1px solid rgba(255,180,80,0.4);
-        border-radius: 12px; padding: 10px 14px;
-        font-size: 12px; color: #e2e8f0; z-index: 10000;
-        display: flex; align-items: center; gap: 10px;
-    `;
-    wrap.innerHTML = `
-        <span aria-live="polite">3D Highway needs WebGL2 — falling back to Classic 2D.</span>
-        <button type="button" data-act="dismiss" aria-label="Dismiss" style="background:transparent;color:#6b7280;border:none;font-size:16px;cursor:pointer;padding:0 4px;line-height:1;">×</button>
-    `;
-    wrap.addEventListener('click', (ev) => {
-        if (ev.target.closest('button[data-act]')) wrap.remove();
-    });
-    document.body.appendChild(wrap);
-    setTimeout(() => { try { wrap.remove(); } catch (_) {} }, 8000);
-}
-
-// The "default" option in the dropdown is the built-in 2D highway that
-// lives inside createHighway(); selecting it calls setRenderer(null) which
-// restores the default renderer.
-function _ensureVenueVizOption(sel) {
-    if (!sel) return;
-    if (Array.from(sel.options).some(opt => opt.value === 'venue')) return;
-    if (!Array.from(sel.options).some(opt => opt.value === 'highway_3d')) return;
-    const h3dOpt = Array.from(sel.options).find(opt => opt.value === 'highway_3d');
-    const opt = document.createElement('option');
-    opt.value = 'venue';
-    opt.textContent = 'Venue';
-    if (h3dOpt && h3dOpt.nextSibling) sel.insertBefore(opt, h3dOpt.nextSibling);
-    else sel.appendChild(opt);
-}
-
-function _syncVenueVizPlayerClass(vizId) {
-    if (window.v3VenueViz && typeof window.v3VenueViz.setSelectedVizId === 'function') {
-        window.v3VenueViz.setSelectedVizId(vizId);
-        return;
-    }
-    if (window.v3VenueViz && typeof window.v3VenueViz.syncPlayerVizClass === 'function') {
-        window.v3VenueViz.syncPlayerVizClass(vizId);
-        return;
-    }
-    const player = document.getElementById('player');
-    if (player) player.classList.toggle('is-venue-visualization', vizId === 'venue');
-}
-
-async function _populateVizPicker(plugins) {
-    const sel = document.getElementById('viz-picker');
-    if (!sel) return;
-    // Clear any previously-appended plugin options so calling this
-    // function more than once (e.g. from DevTools, or a hot-reloaded
-    // plugin) doesn't produce duplicates. The built-in "auto" and
-    // "default" options are static markup — preserve them.
-    const BUILTIN_OPT_VALUES = new Set(['auto', 'default', 'venue']);
-    Array.from(sel.options).forEach(opt => {
-        if (!BUILTIN_OPT_VALUES.has(opt.value)) sel.removeChild(opt);
-    });
-    // Accept a pre-fetched plugins array (normal startup path reuses
-    // loadPlugins' fetch). Fall back to our own fetch if called
-    // standalone — e.g. from the DevTools console for debugging.
-    if (!Array.isArray(plugins)) {
-        plugins = [];
-        try {
-            const resp = await fetch('/api/plugins');
-            if (resp.ok) plugins = await resp.json();
-        } catch (e) {
-            console.warn('viz picker: /api/plugins fetch failed', e);
-        }
-    }
-    const vizPlugins = plugins.filter(p => p && p.type === 'visualization');
-    // "default" is reserved for the built-in 2D renderer option and
-    // "auto" is reserved for the Auto-mode entry — both already in the
-    // <select>. A plugin with either id would collide: the
-    // restore-from-localStorage lookup would find the built-in entry,
-    // dragging the plugin into never-selected land silently. Fail
-    // loudly instead.
-    const RESERVED_IDS = new Set(['default', 'auto']);
-    for (const p of vizPlugins) {
-        if (RESERVED_IDS.has(p.id)) {
-            console.error(`viz picker: plugin id '${p.id}' collides with a reserved built-in picker entry ('auto' = Auto mode, 'default' = built-in 2D highway); rename the plugin's id in plugin.json to include it in the picker.`);
-            continue;
-        }
-        // Skip entries where the plugin script hasn't exposed a factory —
-        // likely means the script failed to load, or the plugin declared
-        // itself as a viz without shipping the factory yet.
-        const factoryName = 'feedBackViz_' + p.id;
-        if (typeof window[factoryName] !== 'function') {
-            console.warn(`viz picker: plugin '${p.id}' has type=visualization but ${factoryName} is not a function; skipping`);
-            continue;
-        }
-        const opt = document.createElement('option');
-        opt.value = p.id;
-        opt.textContent = p.name || p.id;
-        sel.appendChild(opt);
-    }
-    _ensureVenueVizOption(sel);
-    // Refresh the visualization capability domain's provider registry from
-    // the picker entries just built (the domain host introspects each
-    // factory global for contextType / predicate metadata).
-    if (window.feedBack.vizDomain && typeof window.feedBack.vizDomain.refreshProviders === 'function') {
-        try {
-            // The host reads manifest-declared per-instance settings
-            // (capabilities.visualization.settings, feedBack#849) from the
-            // registered capability participant by id — no need to pass them
-            // through the picker here.
-            window.feedBack.vizDomain.refreshProviders(
-                Array.from(sel.options)
-                    .filter(opt => !BUILTIN_OPT_VALUES.has(opt.value))
-                    .map(opt => ({ id: opt.value, label: opt.text }))
-            );
-        } catch (e) { console.warn('viz picker: capability provider refresh failed', e); }
-    }
-    // Restore previous selection if still available. Direct option
-    // scan instead of a CSS-selector lookup so we don't depend on
-    // CSS.escape (missing in some test environments / older runtimes)
-    // and so a weird saved string (e.g. with a quote) can't throw.
-    // localStorage.getItem can itself throw when storage is blocked
-    // (private mode, sandboxed iframes, some strict test runners);
-    // fall back to null so the startup chain doesn't abort.
-    let saved = null;
-    try { saved = localStorage.getItem('vizSelection'); }
-    catch (e) { console.warn('viz picker: unable to read vizSelection', e); }
-
-    // ── 3D promotion migration (feedBack#160 PR 3) ──────────────────────
-    // Existing users with `vizSelection='default'` (the old built-in 2D
-    // highway) are auto-flipped to the bundled 3D Highway exactly once,
-    // and a non-modal nag toast offers them "Try the tour" / "Switch
-    // back to 2D" the first time they open the player. Users on `auto`
-    // are left alone (auto-pick semantics unchanged). Users on a custom
-    // viz plugin are left alone. WebGL2 absence falls back via setViz.
-    if (saved === 'default' && !_hasPromotedFlag()) {
-        const has3D = Array.from(sel.options).some(o => o.value === 'highway_3d');
-        if (has3D && _canRun3D()) {
-            saved = 'highway_3d';
-            try { localStorage.setItem('vizSelection', 'highway_3d'); } catch (_) {}
-            _markPromoted();
-            _pendingPromotionNag = true;
-            // Race guard: if song:ready already fired before _populateVizPicker
-            // ran (e.g. a deeplink or a fast-loading song), getSongInfo() will
-            // already be non-empty and we'll never receive another song:ready
-            // in this session. Show the nag immediately in that case.
-            const _si = window.highway && window.highway.getSongInfo();
-            if (_si && _si.title) {
-                _pendingPromotionNag = false;
-                _showPromotionNag();
-            }
-        } else if (has3D && !_canRun3D()) {
-            // 3D registered but WebGL2 absent — promote in name but
-            // immediately fall back so we don't ping-pong on every load.
-            // Set the flag so we don't try again next reload.
-            _markPromoted();
-            _showWebGL2FallbackToast();
-        }
-        // No `highway_3d` option (plugin unloaded?) → leave saved as
-        // 'default'. We'll retry the migration once the plugin is back.
-    }
-
-    const savedMatches = saved && Array.from(sel.options).some(opt => opt.value === saved);
-    if (savedMatches) {
-        sel.value = saved;
-        // 'default' needs no setViz — the highway already starts with
-        // the built-in renderer. 'auto' runs setViz so _autoMatchViz
-        // fires, though it's a no-op before the first song_info frame.
-        if (saved !== 'default') setViz(saved);
-    } else if (saved) {
-        // Saved selection references an option that no longer exists —
-        // plugin uninstalled since last session, renamed, or the plugin
-        // script failed to register its factory this time. Clear the
-        // stale value so we don't keep trying the same missing viz on
-        // every reload, and fall through to the fresh-install default
-        // below.
-        try { localStorage.removeItem('vizSelection'); }
-        catch (_) { /* storage blocked; ignore */ }
-        saved = null;
-    }
-    if (!saved) {
-        // Fresh install (or post-cleanup fallthrough): default to the
-        // bundled 3D Highway when available + WebGL2-capable, falling
-        // back to Auto otherwise so the arrangement-matching plugins
-        // (piano on Keys songs, drums on Drums songs, ...) still take
-        // over for non-3D arrangements.
-        const has3D = Array.from(sel.options).some(o => o.value === 'highway_3d');
-        if (has3D && _canRun3D()) {
-            sel.value = 'highway_3d';
-            try { localStorage.setItem('vizSelection', 'highway_3d'); } catch (_) {}
-            setViz('highway_3d');
-        } else {
-            sel.value = 'auto';
-            try { localStorage.setItem('vizSelection', 'auto'); } catch (_) {}
-            if (has3D && !_canRun3D()) { _markPromoted(); _showWebGL2FallbackToast(); }
-        }
-    }
-    // Close a startup race: if playback began before loadPlugins
-    // finished, song:ready already fired while the picker had no
-    // plugin options — _autoMatchViz saw no candidates and left the
-    // default active. Now that plugins are registered, re-evaluate
-    // against whatever song is currently loaded (a no-op when no song
-    // has been loaded yet, since highway.getSongInfo() returns {}).
-    if (sel.value === 'auto') _autoMatchViz();
-}
-
-function _tagVizRenderer(renderer, id) {
-    if (!renderer || !id) return renderer;
-    try {
-        if (!renderer.pluginId) renderer.pluginId = id;
-        if (!renderer.source) renderer.source = id;
-    } catch (_) {}
-    return renderer;
-}
-
-// Attribution hooks into the visualization capability domain (cap:6).
-// Guarded no-ops when the domain host isn't loaded (minimal/test pages).
-function _notifyVizDomain(id, source) {
-    const domain = window.feedBack && window.feedBack.vizDomain;
-    if (domain && typeof domain.notifyRendererChanged === 'function') {
-        try { domain.notifyRendererChanged(id, source); } catch (_) {}
-    }
-}
-
-function _noteVizAutoMatch(id, matched) {
-    const domain = window.feedBack && window.feedBack.vizDomain;
-    if (domain && typeof domain.noteAutoMatch === 'function') {
-        try { domain.noteAutoMatch(id, matched); } catch (_) {}
-    }
-}
-
-function _installVizRenderer(renderer, id, source = 'user-select') {
-    highway.setRenderer(_tagVizRenderer(renderer, id));
-    // Drop any stale notation-view hint now that we have a resolved renderer id.
-    // This is also the path used by _autoMatchViz() after it resolves 'auto' to
-    // a real plugin id, so the null passed at evaluation start is corrected here.
-    _dropStaleNotationHint(id);
-    _notifyVizDomain(id, source);
-    if (window.v3VenueViz && typeof window.v3VenueViz.notifyRendererInstalled === 'function') {
-        window.v3VenueViz.notifyRendererInstalled(id);
-    }
-}
-
-function setViz(id) {
-    // Helper: reset the UI and persisted selection to the built-in
-    // "default" entry. Called whenever the requested viz can't be
-    // applied (missing factory, factory threw, factory returned a
-    // non-conforming renderer) so the picker, localStorage, and the
-    // highway's active renderer stay in sync.
-    const fallbackToDefault = () => {
-        try { localStorage.setItem('vizSelection', 'default'); } catch (_) {}
-        const sel = document.getElementById('viz-picker');
-        if (sel) sel.value = 'default';
-        highway.setRenderer(null);
-        _syncVenueVizPlayerClass('default');
-        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
-            window.v3VenueScene3d.syncViz('default');
-        }
-        _notifyVizDomain('default', 'fallback');
-        _maybeShowNotationViewHint('default');
-    };
-
-    // When switching away from Auto, reset the closed-state label so the
-    // Auto option shows base text the next time the user opens the dropdown.
-    // Also cancel any pending viz:renderer:ready listener from the previous
-    // Auto match cycle so it can't set a stale label after we've moved on.
-    if (id !== 'auto') {
-        if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
-        _setAutoVizLabel(null);
-    }
-
-    if (id === 'default' || !id) {
-        try { localStorage.setItem('vizSelection', id || 'default'); } catch (_) {}
-        const _sel = document.getElementById('viz-picker');
-        if (_sel) _sel.value = 'default';
-        highway.setRenderer(null);
-        _syncVenueVizPlayerClass('default');
-        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
-            window.v3VenueScene3d.syncViz('default');
-        }
-        _notifyVizDomain('default', 'user-select');
-        _maybeShowNotationViewHint('default');
-        return;
-    }
-    if (id === 'auto') {
-        try { localStorage.setItem('vizSelection', 'auto'); } catch (_) {}
-        _syncVenueVizPlayerClass('auto');
-        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
-            window.v3VenueScene3d.syncViz('auto');
-        }
-        _autoMatchViz();
-        return;
-    }
-    if (id === 'venue') {
-        if (!_canRun3D()) {
-            console.warn('viz picker: WebGL2 unavailable, falling back to Classic 2D Highway');
-            _markPromoted();
-            _showWebGL2FallbackToast();
-            fallbackToDefault();
-            return;
-        }
-        const venueFactory = window['feedBackViz_highway_3d'];
-        if (typeof venueFactory !== 'function') {
-            console.error('viz picker: venue requires feedBackViz_highway_3d');
-            fallbackToDefault();
-            return;
-        }
-        let venueRenderer;
-        try { venueRenderer = venueFactory(); }
-        catch (e) {
-            console.error('viz picker: feedBackViz_highway_3d threw for venue mode', e);
-            fallbackToDefault();
-            return;
-        }
-        if (!venueRenderer || typeof venueRenderer.draw !== 'function') {
-            console.error('viz picker: feedBackViz_highway_3d returned an invalid renderer for venue mode');
-            fallbackToDefault();
-            return;
-        }
-        try { localStorage.setItem('vizSelection', 'venue'); } catch (_) {}
-        const _venueSel = document.getElementById('viz-picker');
-        if (_venueSel) _venueSel.value = 'venue';
-        _installVizRenderer(venueRenderer, 'highway_3d');
-        _syncVenueVizPlayerClass('venue');
-        console.info('[venue-viz] selected venue -> renderer highway_3d, venueClass=true');
-        if (window.v3VenueMoodFx && typeof window.v3VenueMoodFx.onVenueVisualizationSelected === 'function') {
-            window.v3VenueMoodFx.onVenueVisualizationSelected();
-        }
-        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
-            window.v3VenueScene3d.syncViz('venue');
-        }
-        _maybeShowNotationViewHint('highway_3d');
-        return;
-    }
-    // 3D Highway specifically gates on WebGL2. Any future WebGL viz
-    // plugin should declare its own probe — for now the bundled 3D
-    // Highway is the only viz with this requirement, so the gate is
-    // hardcoded. Falling back to 'default' (Classic 2D) keeps the
-    // picker in sync; toast informs the user.
-    if (id === 'highway_3d' && !_canRun3D()) {
-        console.warn('viz picker: WebGL2 unavailable, falling back to Classic 2D Highway');
-        _markPromoted();
-        _showWebGL2FallbackToast();
-        fallbackToDefault();
-        return;
-    }
-    const factory = window['feedBackViz_' + id];
-    if (typeof factory !== 'function') {
-        console.error(`viz picker: factory feedBackViz_${id} not available`);
-        fallbackToDefault();
-        return;
-    }
-    let renderer;
-    try { renderer = factory(); }
-    catch (e) {
-        console.error(`viz picker: factory feedBackViz_${id} threw`, e);
-        fallbackToDefault();
-        return;
-    }
-    // Validate shape — highway.setRenderer will itself fall back to
-    // default on a bad renderer, but without this check the UI and
-    // localStorage would still advertise the broken selection.
-    if (!renderer || typeof renderer.draw !== 'function') {
-        console.error(`viz picker: factory feedBackViz_${id} returned an invalid renderer (missing draw)`);
-        fallbackToDefault();
-        return;
-    }
-    // Persist only once we know the renderer is valid.
-    try { localStorage.setItem('vizSelection', id); } catch (_) {}
-    _installVizRenderer(renderer, id);
-    _syncVenueVizPlayerClass(id);
-    if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
-        window.v3VenueScene3d.syncViz(id);
-    }
-    _maybeShowNotationViewHint(id);
-}
-
-// Auto mode: evaluate each registered viz factory's static
-// `matchesArrangement(songInfo)` predicate and install the first
-// matching renderer. No match → fall back to the built-in 2D highway.
-//
-// vizSelection stays 'auto' across invocations so the next song:ready
-// re-evaluates. An explicit picker choice overrides Auto by persisting
-// a different vizSelection.
-//
-// Enumerates viz plugins by walking the picker's own <option> list —
-// that's the canonical set built by _populateVizPicker above and keeps
-// us from needing a second module-level registry.
-// Helper: update the closed-state label of the Auto option to show what was resolved.
-// Resets to the base label when called with no argument (at evaluation start).
-// _autoVizBaseLabel is captured from the DOM on first call so the reset text
-// always matches the initial markup rather than a hardcoded duplicate.
-let _autoVizBaseLabel = null;
-function _setAutoVizLabel(resolvedText) {
-    const opt = document.querySelector('#viz-picker option[value="auto"]');
-    if (!opt) return;
-    if (_autoVizBaseLabel === null) _autoVizBaseLabel = opt.text;
-    opt.text = resolvedText != null ? `Auto \u2192 ${resolvedText}` : _autoVizBaseLabel;
-}
-
-// Holds a cleanup function for the pending viz:renderer:ready listener
-// registered by _autoMatchViz(). Called at the start of each new evaluation
-// to remove any listener left over from the previous match cycle.
-let _cancelPendingAutoLabel = null;
-
-// One-shot (per song) hint shown when a notation-only arrangement falls back
-// to the built-in 2D highway. Such arrangements carry no wire notes
-// (sloppak-spec §5.3: `file:` may be omitted when `notation:` is present), so
-// the default renderer draws an empty board — without this the user is left
-// staring at a silently blank highway. Core ships no notation view; point at
-// the viz picker instead.
-let _notationHintShownFor = null;
-function _showNotationViewHint(arrangementIndex, activeVizId) {
-    const filename = (window.feedBack && window.feedBack.currentSong
-        && window.feedBack.currentSong.filename) || '';
-    if (_notationHintShownFor === filename) return;
-    _notationHintShownFor = filename;
-    const player = document.getElementById('player');
-    if (!player) return;
-    const prev = document.getElementById('notation-view-hint');
-    if (prev) prev.remove();
-    const el = document.createElement('div');
-    el.id = 'notation-view-hint';
-    el.className = 'notation-view-hint';
-    el.dataset.filename = filename;
-    if (arrangementIndex != null) el.dataset.arrangementIndex = String(arrangementIndex);
-    if (activeVizId) el.dataset.vizId = String(activeVizId);
-    el.textContent = 'This arrangement is notation-only — the built-in highway has nothing to draw. '
-        + 'Install a notation view plugin (e.g. Staff View or Keys Highway 3D) and select it in the visualization picker.';
-    const close = document.createElement('button');
-    close.className = 'notation-view-hint-close';
-    close.setAttribute('aria-label', 'Dismiss');
-    close.textContent = '×';
-    close.addEventListener('click', () => el.remove());
-    el.appendChild(close);
-    player.appendChild(el);
-    setTimeout(() => { el.remove(); }, 15000);
-}
-
-// Decide whether the active song needs the notation-view hint: the song is
-// notation-only (has_notation + zero wire notes on the active arrangement)
-// AND the given viz doesn't claim it via matchesArrangement. Covers both the
-// Auto fallthrough (activeVizId='default') and explicit selections, where the
-// renderer persists across songs — e.g. the fresh-install default highway_3d
-// would otherwise show a silently empty 3D board on a notation-only song.
-// Returns true when the hint was shown.
-// A hint left over from a previous song refers to the wrong arrangement —
-// drop it whenever the viz evaluation runs for a different filename, a
-// different arrangement index, or a different active viz.
-function _dropStaleNotationHint(activeVizId) {
-    const stale = document.getElementById('notation-view-hint');
-    if (!stale) return;
-    const curFilename = (window.feedBack && window.feedBack.currentSong
-        && window.feedBack.currentSong.filename) || '';
-    if (stale.dataset.filename !== curFilename) { stale.remove(); return; }
-    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
-        ? (highway.getSongInfo() || {}) : {};
-    const curArrIdx = songInfo.arrangement_index != null ? String(songInfo.arrangement_index) : null;
-    if (curArrIdx !== null && stale.dataset.arrangementIndex !== undefined
-            && stale.dataset.arrangementIndex !== curArrIdx) {
-        stale.remove(); return;
-    }
-    if (activeVizId && stale.dataset.vizId !== undefined && stale.dataset.vizId !== String(activeVizId)) {
-        stale.remove();
-    }
-}
-
-function _maybeShowNotationViewHint(activeVizId) {
-    _dropStaleNotationHint(activeVizId);
-    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
-        ? (highway.getSongInfo() || {}) : {};
-    const activeArr = Array.isArray(songInfo.arrangements)
-        ? songInfo.arrangements.find(a => a.index === songInfo.arrangement_index)
-        : null;
-    if (!(songInfo.has_notation && activeArr && activeArr.notes === 0)) {
-        // Condition no longer holds (arrangement switched to one with notes, or
-        // notation flag cleared) — remove any residual hint so it doesn't
-        // linger and contradict current state.
-        const existing = document.getElementById('notation-view-hint');
-        if (existing) existing.remove();
-        return false;
-    }
-    if (activeVizId && activeVizId !== 'default' && activeVizId !== 'auto') {
-        const factory = window['feedBackViz_' + activeVizId];
-        let claimed = false;
-        try {
-            claimed = typeof factory === 'function'
-                && typeof factory.matchesArrangement === 'function'
-                && !!factory.matchesArrangement(songInfo);
-        } catch (_) { /* predicate threw — treat as unclaimed */ }
-        if (claimed) {
-            // Renderer now claims notation — drop any existing hint.
-            const existing = document.getElementById('notation-view-hint');
-            if (existing) existing.remove();
-            return false;
-        }
-    }
-    _showNotationViewHint(songInfo.arrangement_index, activeVizId);
-    return true;
-}
-
-function _autoMatchViz() {
-    const sel = document.getElementById('viz-picker');
-    if (!sel) return;
-    // Pass null here: sel.value is 'auto', which is never a valid viz-id hint
-    // key. Passing 'auto' would incorrectly drop hints whose data-viz-id is
-    // 'default' (the resolved renderer after a no-match pass), making the
-    // hint unshowable for the rest of the song. Drop using the resolved id
-    // happens later inside _installVizRenderer once the id is known.
-    _dropStaleNotationHint(null);
-    // Cancel any pending viz:renderer:ready listener from a previous match
-    // cycle. The song may change before the previous renderer's async init
-    // settles; we don't want that stale listener to clobber the new label.
-    if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
-    // Reset label at evaluation start so a stale resolved label never persists
-    // if the song changes or the picker re-evaluates with a different outcome.
-    _setAutoVizLabel(null);
-    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
-        ? (highway.getSongInfo() || {}) : {};
-    // Only update the label when a real song is loaded. Before the first
-    // song_info frame, getSongInfo() returns {} — leaving the reset state
-    // ("Auto (match arrangement)") is correct; we haven't evaluated yet.
-    const hasSong = Object.keys(songInfo).length > 0;
-    // Options are stable in DOM order, which matches what users see in
-    // the picker. The underlying order comes from /api/plugins →
-    // _populateVizPicker, and /api/plugins reflects the order the
-    // plugin loader discovered plugins in — plugins/__init__.py walks
-    // `sorted(plugins_base_dir.iterdir())`, i.e. sorted by the on-disk
-    // PLUGIN DIRECTORY name (e.g. "feedBack-plugin-drums" sorts
-    // before "feedBack-plugin-piano"), not by the plugin id declared
-    // in plugin.json. Two consequences worth noting:
-    //   1. First match wins among registered viz plugins — keep each
-    //      plugin's matchesArrangement predicate narrow to avoid
-    //      stealing songs from more specialized viz.
-    //   2. If you need a strict priority when multiple plugins match
-    //      the same song, name the higher-priority plugin's directory
-    //      earlier alphabetically. The picker dropdown reveals the
-    //      actual tiebreaker at a glance.
-    const candidateIds = Array.from(sel.options)
-        .map(o => o.value)
-        .filter(v => v !== 'auto' && v !== 'default');
-    for (const id of candidateIds) {
-        const factory = window['feedBackViz_' + id];
-        if (typeof factory !== 'function') continue;
-        // If the factory statically declares contextType='webgl2', gate on
-        // WebGL2 availability so a match never installs a renderer that'll
-        // fail at init. This is the generic version of the old hard-coded
-        // highway_3d check — any future WebGL2 viz gets the same protection
-        // for free without needing a special-case here.
-        const factoryCtxType = typeof factory.contextType === 'string' ? factory.contextType : '2d';
-        if (factoryCtxType === 'webgl2' && !_canRun3D()) continue;
-        const predicate = factory.matchesArrangement;
-        if (typeof predicate !== 'function') continue;
-        let matched = false;
-        try { matched = !!predicate(songInfo); }
-        catch (err) {
-            console.error(`viz auto: matchesArrangement for ${id} threw`, err);
-            continue;
-        }
-        if (!matched) continue;
-        let renderer;
-        try { renderer = factory(); }
-        catch (err) {
-            console.error(`viz auto: factory feedBackViz_${id} threw`, err);
-            continue;
-        }
-        if (!renderer || typeof renderer.draw !== 'function') {
-            console.error(`viz auto: factory feedBackViz_${id} returned an invalid renderer (missing draw)`);
-            continue;
-        }
-        // Deliberately NOT persisting id — vizSelection stays 'auto' so
-        // the next song:ready re-evaluates against the new arrangement.
-        //
-        // Register the viz:renderer:ready listener BEFORE setRenderer() so we
-        // don't miss the event for sync renderers (no readyPromise), which emit
-        // it immediately inside setRenderer(). The _onReady guard still checks
-        // sel.value so a sync init failure (viz:reverted → sel.value='default')
-        // that fires during setRenderer() is handled correctly — the listener
-        // fires but finds sel.value !== 'auto' and skips the label update.
-        if (hasSong) {
-            const matchedOpt = Array.from(sel.options).find(o => o.value === id);
-            const labelText = matchedOpt ? matchedOpt.text : id;
-            function _onReady() { if (sel.value === 'auto') _setAutoVizLabel(labelText); }
-            window.feedBack.on('viz:renderer:ready', _onReady, { once: true });
-            _cancelPendingAutoLabel = () => window.feedBack.off('viz:renderer:ready', _onReady);
-        }
-        _installVizRenderer(renderer, id, 'auto-match');
-        _noteVizAutoMatch(id, true);
-        return;
-    }
-    // No match — restore the built-in 2D highway. setRenderer(null) is
-    // a no-op when the default is already active. If the previous Auto
-    // pick was a WebGL renderer, highway.setRenderer() handles the
-    // context-type change by replacing the canvas element (cloneNode +
-    // replaceWith) so the default 2D renderer's getContext('2d') always
-    // succeeds — no canvas-lock limitation here.
-    highway.setRenderer(null);
-    _notifyVizDomain('default', 'auto-match');
-    _noteVizAutoMatch('default', false);
-    // Update the label so the user can see Auto resolved to the built-in
-    // highway. Read from the DOM rather than hard-coding the name so a
-    // future rename of the default entry is automatically reflected.
-    if (hasSong) {
-        const defaultOpt = Array.from(sel.options).find(o => o.value === 'default');
-        // Notation-only arrangement falling through to the default renderer:
-        // there are no wire notes, so the board would be silently empty.
-        // Flag it in the Auto label and show the one-shot install hint.
-        if (_maybeShowNotationViewHint('default')) {
-            _setAutoVizLabel('no notation view installed');
-        } else {
-            _setAutoVizLabel(defaultOpt ? defaultOpt.text : null);
-        }
-    }
-}
 
 function formatTime(s) { return `${Math.floor(s/60)}:${String(Math.floor(s%60)).padStart(2,'0')}`; }
 
@@ -11485,9 +10742,6 @@ async function checkScanAndLoad() {
     try { _wireSpeedPresetsOnce(); } catch (e) { console.warn('_wireSpeedPresetsOnce failed:', e); }
     checkScanAndLoad();
 
-    // The loader lives in ./js/plugin-loader.js and must not import app.js
-    // (no-cycle), so hand it the one host function it needs.
-    configurePluginLoader({ populateVizPicker: _populateVizPicker });
     const plugins = await bootstrapPluginsAndUi();
     await loadLibraryProviders({ restoreSaved: true, reloadOnChange: true });
     // Viz picker depends on plugin scripts having loaded (to find
diff --git a/static/js/plugin-loader.js b/static/js/plugin-loader.js
index 8d94959..be4af3b 100644
--- a/static/js/plugin-loader.js
+++ b/static/js/plugin-loader.js
@@ -7,40 +7,15 @@
 // breaks, every plugin breaks — so every change here ends with a real plugin
 // booted against a local uvicorn, not just a green test run.
 //
-// Two things it needs from app.js, and why neither is an import:
-//   * window.showScreen — already the public host contract (constitution II),
-//     so it is called through `window` rather than re-coupled as an import.
-//   * _populateVizPicker — app.js's viz-picker UI, which must run after plugin
-//     scripts have loaded (it looks for window.feedBackViz_<id> factories).
-//     It is injected once at boot via configurePluginLoader() instead of
-//     imported, so this module never imports app.js and the graph stays acyclic
-//     (the import-x/no-cycle gate).
-
-// The injected host seam. Populated once, by app.js, at boot.
+// The one thing it still needs from app.js is `window.showScreen` — already the
+// public host contract (constitution II), so it is called through `window` rather
+// than re-coupled as an import.
 //
-// The default is NOISY on purpose. A silent no-op stub is the classic failure
-// mode for this pattern: if the wiring call in app.js is ever dropped or drifts,
-// the loader keeps working, the viz picker just quietly stops refreshing, and
-// nothing — no test, no boot check — says a word. Failing loudly means the
-// smoke harness (which treats console errors as failures) catches it.
-const _host = {
-    populateVizPicker: () => {
-        console.error(
-            '[plugin-loader] host seam not configured — app.js must call '
-            + 'configurePluginLoader({ populateVizPicker }) before plugins load.',
-        );
-    },
-};
-
-/**
- * Wire the host functions this module needs. Called once from app.js at boot,
- * before any plugin is loaded.
- */
-export function configurePluginLoader(hooks) {
-    if (hooks && typeof hooks.populateVizPicker === 'function') {
-        _host.populateVizPicker = hooks.populateVizPicker;
-    }
-}
+// `_populateVizPicker` used to arrive through a configurePluginLoader() host seam:
+// it lived in app.js, and importing app.js from here would have closed a cycle.
+// The viz layer is now its own leaf module, so the seam is GONE — this imports it
+// directly, and the graph stays acyclic without any injection.
+import { _populateVizPicker } from './viz.js';
 
 let _loadPluginsInFlight = false;
 const _pluginUiContributions = new Map();
@@ -731,7 +706,7 @@ function _refreshPluginsSoon() {
     _pluginRefreshTimer = setTimeout(async () => {
         const plugins = await loadPlugins();
         if (plugins) {
-            _host.populateVizPicker(plugins);
+            _populateVizPicker(plugins);
         } else {
             // loadPlugins() returned null because a refetch was already in
             // flight, so this status change would otherwise be dropped. Re-arm
diff --git a/static/js/viz.js b/static/js/viz.js
new file mode 100644
index 0000000..74ae111
--- /dev/null
+++ b/static/js/viz.js
@@ -0,0 +1,770 @@
+// The visualization layer — the viz picker, renderer selection, and Auto-match.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: it imports NOTHING,
+// which is what lets static/js/plugin-loader.js take _populateVizPicker straight
+// from here and drop the configurePluginLoader() host seam it needed while this
+// code still lived in app.js.
+//
+// It owns the state behind those decisions (the one-shot WebGL2 probe, the
+// 3D-promotion flag, the Auto label, the notation-hint memo) — all
+// module-private, because nothing outside reads them.
+
+// ── Visualization picker (feedBack#36) ─────────────────────────────────
+//
+// Discovers viz plugins via /api/plugins and adds them to the #viz-picker
+// dropdown. A viz plugin declares itself by setting `"type": "visualization"`
+// in its plugin.json AND exposing a factory function on
+// window.feedBackViz_<id> that returns an object matching the setRenderer
+// contract ({init, draw, resize, destroy}).
+//
+// The "default" option in the dropdown is the built-in 2D highway that
+// lives inside createHighway(); selecting it calls setRenderer(null) which
+// restores the default renderer. The bundled 3D Highway plugin
+// (plugins/highway_3d/) registers as id `highway_3d` and is the new
+// fresh-install default per feedBack#160 PR 3.
+
+// ── WebGL2 detection (one-shot probe) ────────────────────────────────────
+// 3D Highway requires WebGL2. On environments where it's unavailable
+// (older browsers, some embedded webviews, software-only contexts), we
+// silently fall back to the Classic 2D Highway and flash a single toast
+// so the user knows why their highway looks different. Cached so we don't
+// thrash the GPU with repeat throwaway-canvas creations.
+let _webgl2Probe = null;
+function _canRun3D() {
+    if (_webgl2Probe !== null) return _webgl2Probe;
+    try {
+        const c = document.createElement('canvas');
+        const gl = c.getContext('webgl2');
+        _webgl2Probe = !!gl;
+        // Lose the context immediately — the probe canvas is never reused.
+        if (gl && gl.getExtension) {
+            const ext = gl.getExtension('WEBGL_lose_context');
+            if (ext && ext.loseContext) ext.loseContext();
+        }
+    } catch (_) { _webgl2Probe = false; }
+    return _webgl2Probe;
+}
+
+// ── Migration / nag flags ────────────────────────────────────────────────
+// `feedBack_3d_promoted_v1` is set the first time we auto-flip an existing
+// `vizSelection='default'` user to `'highway_3d'`. Persistence ensures we
+// don't re-nag on every reload — and ensures the WebGL2 fallback path
+// doesn't ping-pong (one fallback toast, not one per page load).
+const _3D_PROMOTED_FLAG_KEY = 'feedBack_3d_promoted_v1';
+function _markPromoted() {
+    try { localStorage.setItem(_3D_PROMOTED_FLAG_KEY, '1'); } catch (_) {}
+}
+function _hasPromotedFlag() {
+    try { return localStorage.getItem(_3D_PROMOTED_FLAG_KEY) === '1'; }
+    catch (_) { return false; }
+}
+
+// Pending nag: queued during _populateVizPicker, fired on the first
+// `song:ready` (so the toast lands when the user actually opens the
+// player, not at page load when they're still in the library).
+// `song:ready` is emitted by highway.js via window.feedBack.emit(), so
+// subscribe through the same EventTarget. window.feedBack is created in
+// this same file before _populateVizPicker is reachable, so the global
+// is guaranteed to exist by the time this listener registers — but guard
+// anyway in case this module is ever loaded standalone for tests.
+let _pendingPromotionNag = false;
+if (window.feedBack && typeof window.feedBack.on === 'function') {
+    window.feedBack.on('song:ready', () => {
+        if (!_pendingPromotionNag) return;
+        _pendingPromotionNag = false;
+        _showPromotionNag();
+    });
+}
+
+function _showPromotionNag() {
+    // Lightweight toast — no dependency on a generic toast helper, since
+    // app.js doesn't currently have one. Fixed bottom-center, dismissed
+    // by clicking either action button or the × close.
+    const existing = document.getElementById('feedBack-3d-nag');
+    if (existing) existing.remove();
+    const wrap = document.createElement('div');
+    wrap.id = 'feedBack-3d-nag';
+    wrap.setAttribute('role', 'dialog');
+    wrap.setAttribute('aria-modal', 'false');
+    wrap.setAttribute('aria-label', '3D Highway upgrade notification');
+    wrap.style.cssText = `
+        position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
+        background: linear-gradient(145deg, #1a1a30 0%, #0d0d18 100%);
+        border: 1px solid rgba(64,128,224,0.4);
+        border-radius: 12px; padding: 12px 16px;
+        box-shadow: 0 12px 40px rgba(0,0,0,0.5), 0 0 0 1px rgba(64,128,224,0.15);
+        font-size: 13px; color: #e2e8f0; z-index: 10000;
+        max-width: 480px; display: flex; align-items: center; gap: 12px;
+    `;
+    wrap.innerHTML = `
+        <span aria-live="polite" style="flex:1;">Your highway was upgraded to <strong>3D</strong>.</span>
+        <button type="button" data-act="tour" style="background:rgba(64,128,224,0.25);color:#e2e8f0;border:1px solid rgba(64,128,224,0.5);padding:6px 12px;border-radius:8px;font-size:12px;cursor:pointer;">Try the tour</button>
+        <button type="button" data-act="back" style="background:transparent;color:#cbd5e1;border:1px solid rgba(255,255,255,0.1);padding:6px 12px;border-radius:8px;font-size:12px;cursor:pointer;">Switch back to 2D</button>
+        <button type="button" data-act="dismiss" aria-label="Dismiss" style="background:transparent;color:#6b7280;border:none;font-size:18px;cursor:pointer;padding:0 4px;line-height:1;">×</button>
+    `;
+    wrap.addEventListener('click', (ev) => {
+        const btn = ev.target.closest('button[data-act]');
+        if (!btn) return;
+        const act = btn.dataset.act;
+        if (act === 'tour') {
+            try {
+                if (window.feedBackTour && typeof window.feedBackTour.start === 'function') {
+                    window.feedBackTour.start('highway_3d');
+                }
+            } catch (_) {}
+        } else if (act === 'back') {
+            setViz('default');
+        }
+        wrap.remove();
+    });
+    document.body.appendChild(wrap);
+}
+
+function _showWebGL2FallbackToast() {
+    // One-time fallback notice. Same lightweight DOM as the nag, simpler
+    // copy and only a dismiss button.
+    if (document.getElementById('feedBack-3d-fallback')) return;
+    const wrap = document.createElement('div');
+    wrap.id = 'feedBack-3d-fallback';
+    wrap.setAttribute('role', 'dialog');
+    wrap.setAttribute('aria-modal', 'false');
+    wrap.setAttribute('aria-label', 'WebGL2 not available');
+    wrap.style.cssText = `
+        position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
+        background: #181830; border: 1px solid rgba(255,180,80,0.4);
+        border-radius: 12px; padding: 10px 14px;
+        font-size: 12px; color: #e2e8f0; z-index: 10000;
+        display: flex; align-items: center; gap: 10px;
+    `;
+    wrap.innerHTML = `
+        <span aria-live="polite">3D Highway needs WebGL2 — falling back to Classic 2D.</span>
+        <button type="button" data-act="dismiss" aria-label="Dismiss" style="background:transparent;color:#6b7280;border:none;font-size:16px;cursor:pointer;padding:0 4px;line-height:1;">×</button>
+    `;
+    wrap.addEventListener('click', (ev) => {
+        if (ev.target.closest('button[data-act]')) wrap.remove();
+    });
+    document.body.appendChild(wrap);
+    setTimeout(() => { try { wrap.remove(); } catch (_) {} }, 8000);
+}
+
+// The "default" option in the dropdown is the built-in 2D highway that
+// lives inside createHighway(); selecting it calls setRenderer(null) which
+// restores the default renderer.
+function _ensureVenueVizOption(sel) {
+    if (!sel) return;
+    if (Array.from(sel.options).some(opt => opt.value === 'venue')) return;
+    if (!Array.from(sel.options).some(opt => opt.value === 'highway_3d')) return;
+    const h3dOpt = Array.from(sel.options).find(opt => opt.value === 'highway_3d');
+    const opt = document.createElement('option');
+    opt.value = 'venue';
+    opt.textContent = 'Venue';
+    if (h3dOpt && h3dOpt.nextSibling) sel.insertBefore(opt, h3dOpt.nextSibling);
+    else sel.appendChild(opt);
+}
+
+function _syncVenueVizPlayerClass(vizId) {
+    if (window.v3VenueViz && typeof window.v3VenueViz.setSelectedVizId === 'function') {
+        window.v3VenueViz.setSelectedVizId(vizId);
+        return;
+    }
+    if (window.v3VenueViz && typeof window.v3VenueViz.syncPlayerVizClass === 'function') {
+        window.v3VenueViz.syncPlayerVizClass(vizId);
+        return;
+    }
+    const player = document.getElementById('player');
+    if (player) player.classList.toggle('is-venue-visualization', vizId === 'venue');
+}
+
+export async function _populateVizPicker(plugins) {
+    const sel = document.getElementById('viz-picker');
+    if (!sel) return;
+    // Clear any previously-appended plugin options so calling this
+    // function more than once (e.g. from DevTools, or a hot-reloaded
+    // plugin) doesn't produce duplicates. The built-in "auto" and
+    // "default" options are static markup — preserve them.
+    const BUILTIN_OPT_VALUES = new Set(['auto', 'default', 'venue']);
+    Array.from(sel.options).forEach(opt => {
+        if (!BUILTIN_OPT_VALUES.has(opt.value)) sel.removeChild(opt);
+    });
+    // Accept a pre-fetched plugins array (normal startup path reuses
+    // loadPlugins' fetch). Fall back to our own fetch if called
+    // standalone — e.g. from the DevTools console for debugging.
+    if (!Array.isArray(plugins)) {
+        plugins = [];
+        try {
+            const resp = await fetch('/api/plugins');
+            if (resp.ok) plugins = await resp.json();
+        } catch (e) {
+            console.warn('viz picker: /api/plugins fetch failed', e);
+        }
+    }
+    const vizPlugins = plugins.filter(p => p && p.type === 'visualization');
+    // "default" is reserved for the built-in 2D renderer option and
+    // "auto" is reserved for the Auto-mode entry — both already in the
+    // <select>. A plugin with either id would collide: the
+    // restore-from-localStorage lookup would find the built-in entry,
+    // dragging the plugin into never-selected land silently. Fail
+    // loudly instead.
+    const RESERVED_IDS = new Set(['default', 'auto']);
+    for (const p of vizPlugins) {
+        if (RESERVED_IDS.has(p.id)) {
+            console.error(`viz picker: plugin id '${p.id}' collides with a reserved built-in picker entry ('auto' = Auto mode, 'default' = built-in 2D highway); rename the plugin's id in plugin.json to include it in the picker.`);
+            continue;
+        }
+        // Skip entries where the plugin script hasn't exposed a factory —
+        // likely means the script failed to load, or the plugin declared
+        // itself as a viz without shipping the factory yet.
+        const factoryName = 'feedBackViz_' + p.id;
+        if (typeof window[factoryName] !== 'function') {
+            console.warn(`viz picker: plugin '${p.id}' has type=visualization but ${factoryName} is not a function; skipping`);
+            continue;
+        }
+        const opt = document.createElement('option');
+        opt.value = p.id;
+        opt.textContent = p.name || p.id;
+        sel.appendChild(opt);
+    }
+    _ensureVenueVizOption(sel);
+    // Refresh the visualization capability domain's provider registry from
+    // the picker entries just built (the domain host introspects each
+    // factory global for contextType / predicate metadata).
+    if (window.feedBack.vizDomain && typeof window.feedBack.vizDomain.refreshProviders === 'function') {
+        try {
+            // The host reads manifest-declared per-instance settings
+            // (capabilities.visualization.settings, feedBack#849) from the
+            // registered capability participant by id — no need to pass them
+            // through the picker here.
+            window.feedBack.vizDomain.refreshProviders(
+                Array.from(sel.options)
+                    .filter(opt => !BUILTIN_OPT_VALUES.has(opt.value))
+                    .map(opt => ({ id: opt.value, label: opt.text }))
+            );
+        } catch (e) { console.warn('viz picker: capability provider refresh failed', e); }
+    }
+    // Restore previous selection if still available. Direct option
+    // scan instead of a CSS-selector lookup so we don't depend on
+    // CSS.escape (missing in some test environments / older runtimes)
+    // and so a weird saved string (e.g. with a quote) can't throw.
+    // localStorage.getItem can itself throw when storage is blocked
+    // (private mode, sandboxed iframes, some strict test runners);
+    // fall back to null so the startup chain doesn't abort.
+    let saved = null;
+    try { saved = localStorage.getItem('vizSelection'); }
+    catch (e) { console.warn('viz picker: unable to read vizSelection', e); }
+
+    // ── 3D promotion migration (feedBack#160 PR 3) ──────────────────────
+    // Existing users with `vizSelection='default'` (the old built-in 2D
+    // highway) are auto-flipped to the bundled 3D Highway exactly once,
+    // and a non-modal nag toast offers them "Try the tour" / "Switch
+    // back to 2D" the first time they open the player. Users on `auto`
+    // are left alone (auto-pick semantics unchanged). Users on a custom
+    // viz plugin are left alone. WebGL2 absence falls back via setViz.
+    if (saved === 'default' && !_hasPromotedFlag()) {
+        const has3D = Array.from(sel.options).some(o => o.value === 'highway_3d');
+        if (has3D && _canRun3D()) {
+            saved = 'highway_3d';
+            try { localStorage.setItem('vizSelection', 'highway_3d'); } catch (_) {}
+            _markPromoted();
+            _pendingPromotionNag = true;
+            // Race guard: if song:ready already fired before _populateVizPicker
+            // ran (e.g. a deeplink or a fast-loading song), getSongInfo() will
+            // already be non-empty and we'll never receive another song:ready
+            // in this session. Show the nag immediately in that case.
+            const _si = window.highway && window.highway.getSongInfo();
+            if (_si && _si.title) {
+                _pendingPromotionNag = false;
+                _showPromotionNag();
+            }
+        } else if (has3D && !_canRun3D()) {
+            // 3D registered but WebGL2 absent — promote in name but
+            // immediately fall back so we don't ping-pong on every load.
+            // Set the flag so we don't try again next reload.
+            _markPromoted();
+            _showWebGL2FallbackToast();
+        }
+        // No `highway_3d` option (plugin unloaded?) → leave saved as
+        // 'default'. We'll retry the migration once the plugin is back.
+    }
+
+    const savedMatches = saved && Array.from(sel.options).some(opt => opt.value === saved);
+    if (savedMatches) {
+        sel.value = saved;
+        // 'default' needs no setViz — the highway already starts with
+        // the built-in renderer. 'auto' runs setViz so _autoMatchViz
+        // fires, though it's a no-op before the first song_info frame.
+        if (saved !== 'default') setViz(saved);
+    } else if (saved) {
+        // Saved selection references an option that no longer exists —
+        // plugin uninstalled since last session, renamed, or the plugin
+        // script failed to register its factory this time. Clear the
+        // stale value so we don't keep trying the same missing viz on
+        // every reload, and fall through to the fresh-install default
+        // below.
+        try { localStorage.removeItem('vizSelection'); }
+        catch (_) { /* storage blocked; ignore */ }
+        saved = null;
+    }
+    if (!saved) {
+        // Fresh install (or post-cleanup fallthrough): default to the
+        // bundled 3D Highway when available + WebGL2-capable, falling
+        // back to Auto otherwise so the arrangement-matching plugins
+        // (piano on Keys songs, drums on Drums songs, ...) still take
+        // over for non-3D arrangements.
+        const has3D = Array.from(sel.options).some(o => o.value === 'highway_3d');
+        if (has3D && _canRun3D()) {
+            sel.value = 'highway_3d';
+            try { localStorage.setItem('vizSelection', 'highway_3d'); } catch (_) {}
+            setViz('highway_3d');
+        } else {
+            sel.value = 'auto';
+            try { localStorage.setItem('vizSelection', 'auto'); } catch (_) {}
+            if (has3D && !_canRun3D()) { _markPromoted(); _showWebGL2FallbackToast(); }
+        }
+    }
+    // Close a startup race: if playback began before loadPlugins
+    // finished, song:ready already fired while the picker had no
+    // plugin options — _autoMatchViz saw no candidates and left the
+    // default active. Now that plugins are registered, re-evaluate
+    // against whatever song is currently loaded (a no-op when no song
+    // has been loaded yet, since highway.getSongInfo() returns {}).
+    if (sel.value === 'auto') _autoMatchViz();
+}
+
+function _tagVizRenderer(renderer, id) {
+    if (!renderer || !id) return renderer;
+    try {
+        if (!renderer.pluginId) renderer.pluginId = id;
+        if (!renderer.source) renderer.source = id;
+    } catch (_) {}
+    return renderer;
+}
+
+// Attribution hooks into the visualization capability domain (cap:6).
+// Guarded no-ops when the domain host isn't loaded (minimal/test pages).
+function _notifyVizDomain(id, source) {
+    const domain = window.feedBack && window.feedBack.vizDomain;
+    if (domain && typeof domain.notifyRendererChanged === 'function') {
+        try { domain.notifyRendererChanged(id, source); } catch (_) {}
+    }
+}
+
+function _noteVizAutoMatch(id, matched) {
+    const domain = window.feedBack && window.feedBack.vizDomain;
+    if (domain && typeof domain.noteAutoMatch === 'function') {
+        try { domain.noteAutoMatch(id, matched); } catch (_) {}
+    }
+}
+
+function _installVizRenderer(renderer, id, source = 'user-select') {
+    highway.setRenderer(_tagVizRenderer(renderer, id));
+    // Drop any stale notation-view hint now that we have a resolved renderer id.
+    // This is also the path used by _autoMatchViz() after it resolves 'auto' to
+    // a real plugin id, so the null passed at evaluation start is corrected here.
+    _dropStaleNotationHint(id);
+    _notifyVizDomain(id, source);
+    if (window.v3VenueViz && typeof window.v3VenueViz.notifyRendererInstalled === 'function') {
+        window.v3VenueViz.notifyRendererInstalled(id);
+    }
+}
+
+export function setViz(id) {
+    // Helper: reset the UI and persisted selection to the built-in
+    // "default" entry. Called whenever the requested viz can't be
+    // applied (missing factory, factory threw, factory returned a
+    // non-conforming renderer) so the picker, localStorage, and the
+    // highway's active renderer stay in sync.
+    const fallbackToDefault = () => {
+        try { localStorage.setItem('vizSelection', 'default'); } catch (_) {}
+        const sel = document.getElementById('viz-picker');
+        if (sel) sel.value = 'default';
+        highway.setRenderer(null);
+        _syncVenueVizPlayerClass('default');
+        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
+            window.v3VenueScene3d.syncViz('default');
+        }
+        _notifyVizDomain('default', 'fallback');
+        _maybeShowNotationViewHint('default');
+    };
+
+    // When switching away from Auto, reset the closed-state label so the
+    // Auto option shows base text the next time the user opens the dropdown.
+    // Also cancel any pending viz:renderer:ready listener from the previous
+    // Auto match cycle so it can't set a stale label after we've moved on.
+    if (id !== 'auto') {
+        if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
+        _setAutoVizLabel(null);
+    }
+
+    if (id === 'default' || !id) {
+        try { localStorage.setItem('vizSelection', id || 'default'); } catch (_) {}
+        const _sel = document.getElementById('viz-picker');
+        if (_sel) _sel.value = 'default';
+        highway.setRenderer(null);
+        _syncVenueVizPlayerClass('default');
+        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
+            window.v3VenueScene3d.syncViz('default');
+        }
+        _notifyVizDomain('default', 'user-select');
+        _maybeShowNotationViewHint('default');
+        return;
+    }
+    if (id === 'auto') {
+        try { localStorage.setItem('vizSelection', 'auto'); } catch (_) {}
+        _syncVenueVizPlayerClass('auto');
+        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
+            window.v3VenueScene3d.syncViz('auto');
+        }
+        _autoMatchViz();
+        return;
+    }
+    if (id === 'venue') {
+        if (!_canRun3D()) {
+            console.warn('viz picker: WebGL2 unavailable, falling back to Classic 2D Highway');
+            _markPromoted();
+            _showWebGL2FallbackToast();
+            fallbackToDefault();
+            return;
+        }
+        const venueFactory = window['feedBackViz_highway_3d'];
+        if (typeof venueFactory !== 'function') {
+            console.error('viz picker: venue requires feedBackViz_highway_3d');
+            fallbackToDefault();
+            return;
+        }
+        let venueRenderer;
+        try { venueRenderer = venueFactory(); }
+        catch (e) {
+            console.error('viz picker: feedBackViz_highway_3d threw for venue mode', e);
+            fallbackToDefault();
+            return;
+        }
+        if (!venueRenderer || typeof venueRenderer.draw !== 'function') {
+            console.error('viz picker: feedBackViz_highway_3d returned an invalid renderer for venue mode');
+            fallbackToDefault();
+            return;
+        }
+        try { localStorage.setItem('vizSelection', 'venue'); } catch (_) {}
+        const _venueSel = document.getElementById('viz-picker');
+        if (_venueSel) _venueSel.value = 'venue';
+        _installVizRenderer(venueRenderer, 'highway_3d');
+        _syncVenueVizPlayerClass('venue');
+        console.info('[venue-viz] selected venue -> renderer highway_3d, venueClass=true');
+        if (window.v3VenueMoodFx && typeof window.v3VenueMoodFx.onVenueVisualizationSelected === 'function') {
+            window.v3VenueMoodFx.onVenueVisualizationSelected();
+        }
+        if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
+            window.v3VenueScene3d.syncViz('venue');
+        }
+        _maybeShowNotationViewHint('highway_3d');
+        return;
+    }
+    // 3D Highway specifically gates on WebGL2. Any future WebGL viz
+    // plugin should declare its own probe — for now the bundled 3D
+    // Highway is the only viz with this requirement, so the gate is
+    // hardcoded. Falling back to 'default' (Classic 2D) keeps the
+    // picker in sync; toast informs the user.
+    if (id === 'highway_3d' && !_canRun3D()) {
+        console.warn('viz picker: WebGL2 unavailable, falling back to Classic 2D Highway');
+        _markPromoted();
+        _showWebGL2FallbackToast();
+        fallbackToDefault();
+        return;
+    }
+    const factory = window['feedBackViz_' + id];
+    if (typeof factory !== 'function') {
+        console.error(`viz picker: factory feedBackViz_${id} not available`);
+        fallbackToDefault();
+        return;
+    }
+    let renderer;
+    try { renderer = factory(); }
+    catch (e) {
+        console.error(`viz picker: factory feedBackViz_${id} threw`, e);
+        fallbackToDefault();
+        return;
+    }
+    // Validate shape — highway.setRenderer will itself fall back to
+    // default on a bad renderer, but without this check the UI and
+    // localStorage would still advertise the broken selection.
+    if (!renderer || typeof renderer.draw !== 'function') {
+        console.error(`viz picker: factory feedBackViz_${id} returned an invalid renderer (missing draw)`);
+        fallbackToDefault();
+        return;
+    }
+    // Persist only once we know the renderer is valid.
+    try { localStorage.setItem('vizSelection', id); } catch (_) {}
+    _installVizRenderer(renderer, id);
+    _syncVenueVizPlayerClass(id);
+    if (window.v3VenueScene3d && typeof window.v3VenueScene3d.syncViz === 'function') {
+        window.v3VenueScene3d.syncViz(id);
+    }
+    _maybeShowNotationViewHint(id);
+}
+
+// Auto mode: evaluate each registered viz factory's static
+// `matchesArrangement(songInfo)` predicate and install the first
+// matching renderer. No match → fall back to the built-in 2D highway.
+//
+// vizSelection stays 'auto' across invocations so the next song:ready
+// re-evaluates. An explicit picker choice overrides Auto by persisting
+// a different vizSelection.
+//
+// Enumerates viz plugins by walking the picker's own <option> list —
+// that's the canonical set built by _populateVizPicker above and keeps
+// us from needing a second module-level registry.
+// Helper: update the closed-state label of the Auto option to show what was resolved.
+// Resets to the base label when called with no argument (at evaluation start).
+// _autoVizBaseLabel is captured from the DOM on first call so the reset text
+// always matches the initial markup rather than a hardcoded duplicate.
+let _autoVizBaseLabel = null;
+function _setAutoVizLabel(resolvedText) {
+    const opt = document.querySelector('#viz-picker option[value="auto"]');
+    if (!opt) return;
+    if (_autoVizBaseLabel === null) _autoVizBaseLabel = opt.text;
+    opt.text = resolvedText != null ? `Auto \u2192 ${resolvedText}` : _autoVizBaseLabel;
+}
+
+// Holds a cleanup function for the pending viz:renderer:ready listener
+// registered by _autoMatchViz(). Called at the start of each new evaluation
+// to remove any listener left over from the previous match cycle.
+let _cancelPendingAutoLabel = null;
+
+// One-shot (per song) hint shown when a notation-only arrangement falls back
+// to the built-in 2D highway. Such arrangements carry no wire notes
+// (sloppak-spec §5.3: `file:` may be omitted when `notation:` is present), so
+// the default renderer draws an empty board — without this the user is left
+// staring at a silently blank highway. Core ships no notation view; point at
+// the viz picker instead.
+let _notationHintShownFor = null;
+function _showNotationViewHint(arrangementIndex, activeVizId) {
+    const filename = (window.feedBack && window.feedBack.currentSong
+        && window.feedBack.currentSong.filename) || '';
+    if (_notationHintShownFor === filename) return;
+    _notationHintShownFor = filename;
+    const player = document.getElementById('player');
+    if (!player) return;
+    const prev = document.getElementById('notation-view-hint');
+    if (prev) prev.remove();
+    const el = document.createElement('div');
+    el.id = 'notation-view-hint';
+    el.className = 'notation-view-hint';
+    el.dataset.filename = filename;
+    if (arrangementIndex != null) el.dataset.arrangementIndex = String(arrangementIndex);
+    if (activeVizId) el.dataset.vizId = String(activeVizId);
+    el.textContent = 'This arrangement is notation-only — the built-in highway has nothing to draw. '
+        + 'Install a notation view plugin (e.g. Staff View or Keys Highway 3D) and select it in the visualization picker.';
+    const close = document.createElement('button');
+    close.className = 'notation-view-hint-close';
+    close.setAttribute('aria-label', 'Dismiss');
+    close.textContent = '×';
+    close.addEventListener('click', () => el.remove());
+    el.appendChild(close);
+    player.appendChild(el);
+    setTimeout(() => { el.remove(); }, 15000);
+}
+
+// Decide whether the active song needs the notation-view hint: the song is
+// notation-only (has_notation + zero wire notes on the active arrangement)
+// AND the given viz doesn't claim it via matchesArrangement. Covers both the
+// Auto fallthrough (activeVizId='default') and explicit selections, where the
+// renderer persists across songs — e.g. the fresh-install default highway_3d
+// would otherwise show a silently empty 3D board on a notation-only song.
+// Returns true when the hint was shown.
+// A hint left over from a previous song refers to the wrong arrangement —
+// drop it whenever the viz evaluation runs for a different filename, a
+// different arrangement index, or a different active viz.
+function _dropStaleNotationHint(activeVizId) {
+    const stale = document.getElementById('notation-view-hint');
+    if (!stale) return;
+    const curFilename = (window.feedBack && window.feedBack.currentSong
+        && window.feedBack.currentSong.filename) || '';
+    if (stale.dataset.filename !== curFilename) { stale.remove(); return; }
+    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
+        ? (highway.getSongInfo() || {}) : {};
+    const curArrIdx = songInfo.arrangement_index != null ? String(songInfo.arrangement_index) : null;
+    if (curArrIdx !== null && stale.dataset.arrangementIndex !== undefined
+            && stale.dataset.arrangementIndex !== curArrIdx) {
+        stale.remove(); return;
+    }
+    if (activeVizId && stale.dataset.vizId !== undefined && stale.dataset.vizId !== String(activeVizId)) {
+        stale.remove();
+    }
+}
+
+export function _maybeShowNotationViewHint(activeVizId) {
+    _dropStaleNotationHint(activeVizId);
+    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
+        ? (highway.getSongInfo() || {}) : {};
+    const activeArr = Array.isArray(songInfo.arrangements)
+        ? songInfo.arrangements.find(a => a.index === songInfo.arrangement_index)
+        : null;
+    if (!(songInfo.has_notation && activeArr && activeArr.notes === 0)) {
+        // Condition no longer holds (arrangement switched to one with notes, or
+        // notation flag cleared) — remove any residual hint so it doesn't
+        // linger and contradict current state.
+        const existing = document.getElementById('notation-view-hint');
+        if (existing) existing.remove();
+        return false;
+    }
+    if (activeVizId && activeVizId !== 'default' && activeVizId !== 'auto') {
+        const factory = window['feedBackViz_' + activeVizId];
+        let claimed = false;
+        try {
+            claimed = typeof factory === 'function'
+                && typeof factory.matchesArrangement === 'function'
+                && !!factory.matchesArrangement(songInfo);
+        } catch (_) { /* predicate threw — treat as unclaimed */ }
+        if (claimed) {
+            // Renderer now claims notation — drop any existing hint.
+            const existing = document.getElementById('notation-view-hint');
+            if (existing) existing.remove();
+            return false;
+        }
+    }
+    _showNotationViewHint(songInfo.arrangement_index, activeVizId);
+    return true;
+}
+
+export function _autoMatchViz() {
+    const sel = document.getElementById('viz-picker');
+    if (!sel) return;
+    // Pass null here: sel.value is 'auto', which is never a valid viz-id hint
+    // key. Passing 'auto' would incorrectly drop hints whose data-viz-id is
+    // 'default' (the resolved renderer after a no-match pass), making the
+    // hint unshowable for the rest of the song. Drop using the resolved id
+    // happens later inside _installVizRenderer once the id is known.
+    _dropStaleNotationHint(null);
+    // Cancel any pending viz:renderer:ready listener from a previous match
+    // cycle. The song may change before the previous renderer's async init
+    // settles; we don't want that stale listener to clobber the new label.
+    if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
+    // Reset label at evaluation start so a stale resolved label never persists
+    // if the song changes or the picker re-evaluates with a different outcome.
+    _setAutoVizLabel(null);
+    const songInfo = (typeof highway !== 'undefined' && typeof highway.getSongInfo === 'function')
+        ? (highway.getSongInfo() || {}) : {};
+    // Only update the label when a real song is loaded. Before the first
+    // song_info frame, getSongInfo() returns {} — leaving the reset state
+    // ("Auto (match arrangement)") is correct; we haven't evaluated yet.
+    const hasSong = Object.keys(songInfo).length > 0;
+    // Options are stable in DOM order, which matches what users see in
+    // the picker. The underlying order comes from /api/plugins →
+    // _populateVizPicker, and /api/plugins reflects the order the
+    // plugin loader discovered plugins in — plugins/__init__.py walks
+    // `sorted(plugins_base_dir.iterdir())`, i.e. sorted by the on-disk
+    // PLUGIN DIRECTORY name (e.g. "feedBack-plugin-drums" sorts
+    // before "feedBack-plugin-piano"), not by the plugin id declared
+    // in plugin.json. Two consequences worth noting:
+    //   1. First match wins among registered viz plugins — keep each
+    //      plugin's matchesArrangement predicate narrow to avoid
+    //      stealing songs from more specialized viz.
+    //   2. If you need a strict priority when multiple plugins match
+    //      the same song, name the higher-priority plugin's directory
+    //      earlier alphabetically. The picker dropdown reveals the
+    //      actual tiebreaker at a glance.
+    const candidateIds = Array.from(sel.options)
+        .map(o => o.value)
+        .filter(v => v !== 'auto' && v !== 'default');
+    for (const id of candidateIds) {
+        const factory = window['feedBackViz_' + id];
+        if (typeof factory !== 'function') continue;
+        // If the factory statically declares contextType='webgl2', gate on
+        // WebGL2 availability so a match never installs a renderer that'll
+        // fail at init. This is the generic version of the old hard-coded
+        // highway_3d check — any future WebGL2 viz gets the same protection
+        // for free without needing a special-case here.
+        const factoryCtxType = typeof factory.contextType === 'string' ? factory.contextType : '2d';
+        if (factoryCtxType === 'webgl2' && !_canRun3D()) continue;
+        const predicate = factory.matchesArrangement;
+        if (typeof predicate !== 'function') continue;
+        let matched = false;
+        try { matched = !!predicate(songInfo); }
+        catch (err) {
+            console.error(`viz auto: matchesArrangement for ${id} threw`, err);
+            continue;
+        }
+        if (!matched) continue;
+        let renderer;
+        try { renderer = factory(); }
+        catch (err) {
+            console.error(`viz auto: factory feedBackViz_${id} threw`, err);
+            continue;
+        }
+        if (!renderer || typeof renderer.draw !== 'function') {
+            console.error(`viz auto: factory feedBackViz_${id} returned an invalid renderer (missing draw)`);
+            continue;
+        }
+        // Deliberately NOT persisting id — vizSelection stays 'auto' so
+        // the next song:ready re-evaluates against the new arrangement.
+        //
+        // Register the viz:renderer:ready listener BEFORE setRenderer() so we
+        // don't miss the event for sync renderers (no readyPromise), which emit
+        // it immediately inside setRenderer(). The _onReady guard still checks
+        // sel.value so a sync init failure (viz:reverted → sel.value='default')
+        // that fires during setRenderer() is handled correctly — the listener
+        // fires but finds sel.value !== 'auto' and skips the label update.
+        if (hasSong) {
+            const matchedOpt = Array.from(sel.options).find(o => o.value === id);
+            const labelText = matchedOpt ? matchedOpt.text : id;
+            function _onReady() { if (sel.value === 'auto') _setAutoVizLabel(labelText); }
+            window.feedBack.on('viz:renderer:ready', _onReady, { once: true });
+            _cancelPendingAutoLabel = () => window.feedBack.off('viz:renderer:ready', _onReady);
+        }
+        _installVizRenderer(renderer, id, 'auto-match');
+        _noteVizAutoMatch(id, true);
+        return;
+    }
+    // No match — restore the built-in 2D highway. setRenderer(null) is
+    // a no-op when the default is already active. If the previous Auto
+    // pick was a WebGL renderer, highway.setRenderer() handles the
+    // context-type change by replacing the canvas element (cloneNode +
+    // replaceWith) so the default 2D renderer's getContext('2d') always
+    // succeeds — no canvas-lock limitation here.
+    highway.setRenderer(null);
+    _notifyVizDomain('default', 'auto-match');
+    _noteVizAutoMatch('default', false);
+    // Update the label so the user can see Auto resolved to the built-in
+    // highway. Read from the DOM rather than hard-coding the name so a
+    // future rename of the default entry is automatically reflected.
+    if (hasSong) {
+        const defaultOpt = Array.from(sel.options).find(o => o.value === 'default');
+        // Notation-only arrangement falling through to the default renderer:
+        // there are no wire notes, so the board would be silently empty.
+        // Flag it in the Auto label and show the one-shot install hint.
+        if (_maybeShowNotationViewHint('default')) {
+            _setAutoVizLabel('no notation view installed');
+        } else {
+            _setAutoVizLabel(defaultOpt ? defaultOpt.text : null);
+        }
+    }
+}
+
+// ── viz:reverted ────────────────────────────────────────────────────────
+// Lifted out of a top-level listener block in app.js that it shared with the
+// non-viz song:loaded / arrangement:changed / song:ready handlers (those stay).
+//
+// It has to move WITH the state: it REASSIGNS `_cancelPendingAutoLabel`, and an
+// imported binding is read-only — `_cancelPendingAutoLabel = null` would throw if
+// this listener stayed behind in app.js. Same guard as the block it came from.
+if (window.feedBack && typeof window.feedBack.on === 'function') {
+    // Highway signals when it's auto-reverted to the default renderer
+    // after a broken plugin (init failure or repeated draw failures).
+    // Sync the picker + persisted selection so the UI stops advertising
+    // the broken choice and the user doesn't hit the same failure on
+    // next reload.
+    window.feedBack.on('viz:reverted', (e) => {
+        const sel = document.getElementById('viz-picker');
+        if (sel) sel.value = 'default';
+        // Cancel any pending viz:renderer:ready label listener — the renderer
+        // that was queued never became (or stayed) active.
+        if (_cancelPendingAutoLabel) { _cancelPendingAutoLabel(); _cancelPendingAutoLabel = null; }
+        // Clear any Auto-resolved label — the renderer that was advertised
+        // never became (or stayed) active.
+        _setAutoVizLabel(null);
+        try { localStorage.setItem('vizSelection', 'default'); } catch (_) {}
+        console.warn(
+            `viz picker: reverted to default renderer (${e.detail?.reason || 'unknown'}).`
+        );
+    });
+}
+
diff --git a/tests/js/legacy_shim_hits.test.js b/tests/js/legacy_shim_hits.test.js
index 71c5e37..db7e9c3 100644
--- a/tests/js/legacy_shim_hits.test.js
+++ b/tests/js/legacy_shim_hits.test.js
@@ -74,6 +74,8 @@ const APP_JS = path.join(ROOT, 'static', 'app.js');
 // The plugin loader was carved out of app.js into its own module (R3a); the
 // library-provider code below still lives in app.js.
 const PLUGIN_LOADER_JS = path.join(ROOT, 'static', 'js', 'plugin-loader.js');
+// The viz layer was carved out of app.js too (R3a).
+const VIZ_JS = path.join(ROOT, 'static', 'js', 'viz.js');
 const LIBRARY_JS = path.join(ROOT, 'static', 'capabilities', 'library.js');
 
 function source(file) {
@@ -116,7 +118,7 @@ test('library providers route through native library capability', () => {
 });
 
 test('visualization renderer installs preserve plugin attribution', () => {
-    const src = source(APP_JS);
+    const src = source(VIZ_JS);
     const tagger = region(src, 'function _tagVizRenderer(renderer, id)', 700);
     const setViz = region(src, 'function setViz(id)', 3600);
     const autoViz = region(src, 'function _autoMatchViz()', 5200);
diff --git a/tests/js/venue_scene_3d.test.js b/tests/js/venue_scene_3d.test.js
index fed8389..69272d7 100644
--- a/tests/js/venue_scene_3d.test.js
+++ b/tests/js/venue_scene_3d.test.js
@@ -9,6 +9,9 @@ const venueScene = require('../../static/v3/venue-scene-3d.js');
 const venueViz = require('../../static/v3/venue-viz.js');
 const pov = require('../../static/v3/venue-instrument-pov.js');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The viz layer (setViz / the venue option / the picker) was carved out of
+// app.js into its own module (R3a).
+const VIZ_JS = path.join(__dirname, '..', '..', 'static', 'js', 'viz.js');
 const H3D_JS = path.join(__dirname, '..', '..', 'plugins', 'highway_3d', 'screen.js');
 const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 const ASSET_DIR = path.join(__dirname, '..', '..', 'static', 'assets', 'venue', 'themes', 'small-club');
@@ -185,8 +188,8 @@ test('venue-scene-3d exports bg plate asset ids', () => {
     assert.equal(venueScene.ASSET_BASE, '/static/assets/venue/themes/small-club/');
 });
 
-test('app.js syncs venue 3D scene on viz changes', () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+test('viz.js syncs venue 3D scene on viz changes', () => {
+    const src = fs.readFileSync(VIZ_JS, 'utf8');
     assert.match(src, /v3VenueScene3d\.syncViz\('venue'\)/);
     assert.match(src, /v3VenueScene3d\.syncViz\(id\)/);
 });
diff --git a/tests/js/venue_viz.test.js b/tests/js/venue_viz.test.js
index e31ca38..e695fcd 100644
--- a/tests/js/venue_viz.test.js
+++ b/tests/js/venue_viz.test.js
@@ -8,6 +8,8 @@ const path = require('node:path');
 const venueViz = require('../../static/v3/venue-viz.js');
 const venue = require('../../static/v3/venue-mood-fx.js');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
+// The viz layer was carved out of app.js into its own module (R3a).
+const VIZ_JS = path.join(__dirname, '..', '..', 'static', 'js', 'viz.js');
 const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 const V3_CSS = path.join(__dirname, '..', '..', 'static', 'v3', 'v3.css');
 
@@ -139,8 +141,8 @@ test('index.html contains in-player venue placeholder markup', () => {
     assert.match(html, /id="v3-venue-scene-wash"/);
 });
 
-test('app.js adds Venue visualization option and adapter', () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+test('viz.js adds Venue visualization option and adapter', () => {
+    const src = fs.readFileSync(VIZ_JS, 'utf8');
     assert.match(src, /function _ensureVenueVizOption/);
     assert.match(src, /opt\.value = 'venue'/);
     assert.match(src, /opt\.textContent = 'Venue'/);
@@ -210,15 +212,15 @@ test('venue mood source documents strip overlay disabled', () => {
     assert.match(source, /v3-venue-mode-badge/);
 });
 
-test('app.js preserves plugin viz population for drum/tab/piano highways', () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+test('viz.js preserves plugin viz population for drum/tab/piano highways', () => {
+    const src = fs.readFileSync(VIZ_JS, 'utf8');
     assert.match(src, /p\.type === 'visualization'/);
     assert.match(src, /feedBackViz_/);
     assert.match(src, /BUILTIN_OPT_VALUES/);
 });
 
-test('venue option remains distinct from highway_3d in app adapter', () => {
-    const src = fs.readFileSync(APP_JS, 'utf8');
+test('venue option remains distinct from highway_3d in viz adapter', () => {
+    const src = fs.readFileSync(VIZ_JS, 'utf8');
     assert.match(src, /if \(id === 'venue'\)/);
     assert.doesNotMatch(src, /if \(id === 'venue'\)[\s\S]{0,400}sel\.value = 'highway_3d'/);
 });