feat(v3): Refresh button + live scan progress on the Songs library

Add a media-server-style "I dropped files in my folder, hit refresh" control to
the Songs toolbar. Refresh triggers an incremental /api/rescan and reuses the
existing /api/scan-status poll for live progress: a 3-state button (idle /
"Scanning..." while listing / "Scanning N/M" once counting) with a title tooltip
showing the current file + percent. A scan already running (the Settings buttons
or a background pass) is reflected on the button too. On completion it emits
library:changed so the grid reloads, and shows an honest, never-punishing
fbNotify toast (bottom-right, suppressed while in a song). No backend change --
same machinery the Settings rescan already drives. The precise "N added" count
is a follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QbexxfTt8q2tAn436MqGWF

plugins/highway_3d/screen.js

@@ -1083,6 +1083,22 @@
     const FOCUS_D = 600 * K;
     const CAM_LERP_BASE = 0.02;
 
+    // Base vertical field of view (deg). THREE's PerspectiveCamera fov is the
+    // VERTICAL angle; horizontal follows from the aspect ratio. At a normal
+    // ~16:9 pane this gives a ~102° horizontal cone. On an ultra-wide pane
+    // (top/bottom 2-player split → full-width/half-height → ~32:9) that
+    // horizontal cone balloons past 130° and squeezes the fixed-width neck into
+    // a central sliver. The optional horizontal-FOV-hold path below counters
+    // that by lowering the effective vertical fov as the pane widens.
+    const BASE_VFOV = 70;
+    // Horizontal-FOV-hold ("Hor+") defaults. At/under HORPLUS_START_ASPECT the
+    // effective vertical fov equals BASE_VFOV (exact no-op); past it the
+    // vertical fov drops to keep the horizontal cone ~constant so the neck
+    // fills a wide pane. HORPLUS_MIN_VFOV floors the result on pathological
+    // aspects. Engaged only via the window.__h3dAspectTune bridge (default off).
+    const HORPLUS_START_ASPECT = 16 / 9;
+    const HORPLUS_MIN_VFOV = 28;
+
     // Zoom-dependent framing — height (h*) and depth (dist*) multipliers
     // applied to cam.position. Interpolated by `dist`:
     //   NEAR = tight view (nut position, span<=4 -> dist~=93*K): lower/closer.
@@ -1591,6 +1607,257 @@
             ss.isCanvasFocused(highwayCanvas));
     }
 
+    // A/B toggle for the wide-pane horizontal-FOV-hold. Flips
+    // window.__h3dAspectTune.enabled so the running app can switch between the
+    // current framing (off, the baseline) and the Hor+ framing (on) with one
+    // keypress, across all panes at once. Registered once per session via a
+    // module-level guard (it toggles a shared global, so per-instance
+    // registration would stack duplicate handlers and cancel itself out); it's
+    // a harmless debug control, so it is never unregistered. No-ops where the
+    // core shortcut API isn't present (older core / borrowed contexts).
+    let _abShortcutRegistered = false;
+    function _registerAspectAbShortcut() {
+        if (_abShortcutRegistered) return;
+        if (typeof window.registerShortcut !== 'function') return;
+        _abShortcutRegistered = true;
+        try {
+            window.registerShortcut({
+                key: 'A',   // uppercase e.key → produced with Shift held (Shift+A)
+                description: '3D Highway: toggle wide-pane framing A/B (Shift+A)',
+                scope: 'player',
+                handler: () => {
+                    const t = _aspectTune();
+                    t.enabled = !t.enabled;
+                    try { console.log('[h3d] wide-pane framing', t.enabled ? 'ON' : 'OFF'); } catch (e) {}
+                    // Surface the live tuner panel whenever the feature is on,
+                    // hide it when off. Built lazily on first use.
+                    _ensureAspectPanel();
+                    _setAspectPanelVisible(t.enabled);
+                    _syncAspectPanel();
+                },
+            });
+        } catch (e) {
+            _abShortcutRegistered = false;   // allow a later retry if it threw
+        }
+    }
+
+    // ── Wide-pane framing: live tuner bridge + panel ──────────────────────────
+    // window.__h3dAspectTune is the single source of truth the renderer reads
+    // each frame (see effectiveVfov + camUpdate). The defaults reproduce the
+    // current framing exactly (enabled:false). Values persist to localStorage so
+    // a tuning session survives reloads; the floating panel (Shift+A) writes the
+    // same object live. All of this is a debug aid — none of it runs unless the
+    // user opts in.
+    // Versioned key: the first iteration shipped a broken default (enabled:true,
+    // baseVfov:30) and may have persisted it. Bumping the key ignores that stale
+    // state so the corrected default-off config actually takes effect.
+    const _ASPECT_LS = 'h3d_aspect_tune2';
+    // Working defaults. Default OFF, so out of the box this is an exact no-op —
+    // every pane renders byte-for-byte as before (effectiveVfov returns
+    // BASE_VFOV and the pose nudges gate off). The config is also coherent when
+    // a tester turns it ON via Shift+A: baseVfov == BASE_VFOV so normal ~16:9
+    // panes (single-player, most 2x2) stay at 70° even enabled, and only panes
+    // wider than startAspect (2.25) engage the Hor+ hold; blend:1 makes that
+    // hold actually take effect; minVfovDeg (28) sits below baseVfov so the floor
+    // is a real floor. The pose nudges are the in-progress wide-pane look a
+    // tester sees once enabled. localStorage overrides all of this per machine.
+    const _ASPECT_DEFAULTS = {
+        enabled: false, baseVfov: BASE_VFOV, startAspect: 2.25, hfovDeg: null,
+        blend: 1, minVfovDeg: HORPLUS_MIN_VFOV, splitOnly: false,
+        heightMul: 0.30, distMul: 0.95, pitchAdd: -1.5, lookDepthMul: 1,
+    };
+    // Slider specs (numeric fields). Checkboxes (enabled/splitOnly) + the hfov
+    // override are handled separately in the panel builder. Ranges are wide on
+    // purpose — this is a tuning aid, the no-op default sits mid-range.
+    const _ASPECT_FIELDS = [
+        { k: 'baseVfov',     label: 'Base vFOV°',   min: 18,  max: 90,  step: 1 },
+        { k: 'startAspect',  label: 'Start aspect', min: 1.0, max: 4.0, step: 0.05 },
+        { k: 'blend',        label: 'Blend',        min: 0,   max: 1,   step: 0.05 },
+        { k: 'minVfovDeg',   label: 'Min vFOV°',    min: 10,  max: 60,  step: 1 },
+        { k: 'heightMul',    label: 'Height ×',     min: 0.1, max: 2.5, step: 0.05 },
+        { k: 'distMul',      label: 'Dolly ×',      min: 0.2, max: 3.0, step: 0.05 },
+        { k: 'pitchAdd',     label: 'Pitch +',      min: -40, max: 40,  step: 0.5 },
+        // Aims the camera further down the neck (>1) or pulls the aim back (<1).
+        // This is the lever that flattens the mid-distance "hump" toward a
+        // straight gradual recede.
+        { k: 'lookDepthMul', label: 'Look depth',   min: 0.2, max: 3.0, step: 0.05 },
+    ];
+    let _aspectPanelEl = null;        // the floating panel root (built once)
+    let _aspectPanelRO = null;        // readout <div>
+    let _aspectPanelRAF = 0;          // readout poll handle
+
+    // Get-or-create the live bridge object, seeded from defaults + localStorage.
+    function _aspectTune() {
+        let t = window.__h3dAspectTune;
+        if (!t || typeof t !== 'object') {
+            t = Object.assign({}, _ASPECT_DEFAULTS);
+            try {
+                const raw = localStorage.getItem(_ASPECT_LS);
+                if (raw) Object.assign(t, JSON.parse(raw));
+            } catch (e) {}
+            window.__h3dAspectTune = t;
+        }
+        return t;
+    }
+    function _aspectPersist() {
+        try {
+            const t = _aspectTune(), out = {};
+            Object.keys(_ASPECT_DEFAULTS).forEach((k) => { out[k] = t[k]; });
+            localStorage.setItem(_ASPECT_LS, JSON.stringify(out));
+        } catch (e) {}
+    }
+
+    function _ensureAspectPanel() {
+        if (_aspectPanelEl || typeof document === 'undefined') return;
+        const t = _aspectTune();
+        const wrap = document.createElement('div');
+        wrap.id = 'h3d-aspect-tuner';
+        wrap.style.cssText = [
+            'position:fixed', 'top:64px', 'right:12px', 'z-index:99999',
+            'width:230px', 'padding:10px 12px', 'border-radius:8px',
+            'background:rgba(12,18,28,0.92)', 'border:1px solid rgba(120,150,200,0.35)',
+            'box-shadow:0 6px 24px rgba(0,0,0,0.5)', 'color:#cfe0f5',
+            'font:11px/1.35 system-ui,sans-serif', 'user-select:none',
+            'pointer-events:auto',
+        ].join(';');
+
+        const title = document.createElement('div');
+        title.textContent = 'Wide-pane framing (A/B)';
+        title.style.cssText = 'font-weight:700;margin-bottom:6px;color:#e8c040;';
+        wrap.appendChild(title);
+
+        // enabled + splitOnly checkboxes
+        [['enabled', 'Enabled (Shift+A)'], ['splitOnly', 'Split panes only']].forEach(([k, lbl]) => {
+            const row = document.createElement('label');
+            row.style.cssText = 'display:flex;align-items:center;gap:6px;margin:2px 0;cursor:pointer;';
+            const cb = document.createElement('input');
+            cb.type = 'checkbox'; cb.checked = !!t[k]; cb.dataset.k = k;
+            cb.addEventListener('change', () => {
+                _aspectTune()[k] = cb.checked; _aspectPersist();
+                if (k === 'enabled') _setAspectPanelVisible(cb.checked);
+            });
+            const span = document.createElement('span'); span.textContent = lbl;
+            row.appendChild(cb); row.appendChild(span); wrap.appendChild(row);
+        });
+
+        // numeric sliders
+        _ASPECT_FIELDS.forEach((f) => {
+            const row = document.createElement('div');
+            row.style.cssText = 'margin:5px 0;';
+            const head = document.createElement('div');
+            head.style.cssText = 'display:flex;justify-content:space-between;';
+            const lab = document.createElement('span'); lab.textContent = f.label;
+            const val = document.createElement('span');
+            val.style.cssText = 'color:#8fb6ff;font-variant-numeric:tabular-nums;';
+            head.appendChild(lab); head.appendChild(val); row.appendChild(head);
+            const sl = document.createElement('input');
+            sl.type = 'range'; sl.min = f.min; sl.max = f.max; sl.step = f.step;
+            sl.value = Number.isFinite(t[f.k]) ? t[f.k] : _ASPECT_DEFAULTS[f.k];
+            sl.dataset.k = f.k;
+            sl.style.cssText = 'width:100%;';
+            const show = () => { val.textContent = (+sl.value).toFixed(f.step < 1 ? 2 : 0); };
+            show();
+            sl.addEventListener('input', () => {
+                _aspectTune()[f.k] = parseFloat(sl.value); show(); _aspectPersist();
+            });
+            row.appendChild(sl); wrap.appendChild(row);
+        });
+
+        // hfov override (checkbox enables a slider; off → hfovDeg=null = auto)
+        {
+            const row = document.createElement('div'); row.style.cssText = 'margin:5px 0;';
+            const head = document.createElement('label');
+            head.style.cssText = 'display:flex;align-items:center;gap:6px;cursor:pointer;';
+            const cb = document.createElement('input');
+            cb.type = 'checkbox'; cb.checked = Number.isFinite(t.hfovDeg);
+            const lbl = document.createElement('span'); lbl.textContent = 'Override held hFOV°';
+            head.appendChild(cb); head.appendChild(lbl); row.appendChild(head);
+            const sl = document.createElement('input');
+            sl.type = 'range'; sl.min = 40; sl.max = 160; sl.step = 1;
+            sl.value = Number.isFinite(t.hfovDeg) ? t.hfovDeg : 102;
+            sl.disabled = !cb.checked;
+            sl.style.cssText = 'width:100%;';
+            cb.addEventListener('change', () => {
+                sl.disabled = !cb.checked;
+                _aspectTune().hfovDeg = cb.checked ? parseFloat(sl.value) : null;
+                _aspectPersist();
+            });
+            sl.addEventListener('input', () => {
+                if (cb.checked) { _aspectTune().hfovDeg = parseFloat(sl.value); _aspectPersist(); }
+            });
+            row.appendChild(sl); wrap.appendChild(row);
+        }
+
+        // live readout
+        _aspectPanelRO = document.createElement('div');
+        _aspectPanelRO.style.cssText = 'margin-top:6px;padding-top:6px;border-top:1px solid rgba(120,150,200,0.25);color:#9fb;font-variant-numeric:tabular-nums;';
+        _aspectPanelRO.textContent = 'aspect — · vFOV —';
+        wrap.appendChild(_aspectPanelRO);
+
+        // buttons
+        const btnRow = document.createElement('div');
+        btnRow.style.cssText = 'display:flex;gap:6px;margin-top:8px;';
+        const mkBtn = (txt, fn) => {
+            const b = document.createElement('button');
+            b.textContent = txt;
+            b.style.cssText = 'flex:1;padding:4px 0;border-radius:5px;border:1px solid rgba(120,150,200,0.4);background:rgba(40,60,90,0.6);color:#cfe0f5;cursor:pointer;font:11px system-ui;';
+            b.addEventListener('click', fn);
+            return b;
+        };
+        btnRow.appendChild(mkBtn('Reset', () => {
+            const t2 = _aspectTune();
+            Object.keys(_ASPECT_DEFAULTS).forEach((k) => { t2[k] = _ASPECT_DEFAULTS[k]; });
+            t2.enabled = true;            // keep panel up after reset
+            _aspectPersist(); _syncAspectPanel();
+        }));
+        btnRow.appendChild(mkBtn('Copy', () => {
+            const t2 = _aspectTune(), out = {};
+            Object.keys(_ASPECT_DEFAULTS).forEach((k) => { out[k] = t2[k]; });
+            const json = JSON.stringify(out, null, 2);
+            try { console.log('[h3d] wide-pane framing values:\n' + json); } catch (e) {}
+            try { if (navigator.clipboard) navigator.clipboard.writeText(json); } catch (e) {}
+        }));
+        wrap.appendChild(btnRow);
+
+        document.body.appendChild(wrap);
+        _aspectPanelEl = wrap;
+        _aspectPanelEl.style.display = 'none';
+    }
+
+    // Push current bridge values back into the panel controls (after Reset or an
+    // external edit). Cheap; only runs on demand.
+    function _syncAspectPanel() {
+        if (!_aspectPanelEl) return;
+        const t = _aspectTune();
+        _aspectPanelEl.querySelectorAll('input[type=checkbox][data-k]').forEach((cb) => {
+            cb.checked = !!t[cb.dataset.k];
+        });
+        _aspectPanelEl.querySelectorAll('input[type=range][data-k]').forEach((sl) => {
+            const k = sl.dataset.k;
+            if (Number.isFinite(t[k])) sl.value = t[k];
+            sl.dispatchEvent(new Event('input'));   // refresh the value label
+        });
+    }
+
+    function _setAspectPanelVisible(on) {
+        _ensureAspectPanel();
+        if (!_aspectPanelEl) return;
+        _aspectPanelEl.style.display = on ? 'block' : 'none';
+        window.__h3dAspectPanelOpen = !!on;        // gates the per-frame readout publish
+        if (on && !_aspectPanelRAF) {
+            const tick = () => {
+                if (!window.__h3dAspectPanelOpen) { _aspectPanelRAF = 0; return; }
+                const ro = window.__h3dAspectReadout;
+                if (_aspectPanelRO && ro && Number.isFinite(ro.aspect)) {
+                    _aspectPanelRO.textContent =
+                        'aspect ' + ro.aspect.toFixed(2) + ' · vFOV ' + ro.vfov.toFixed(1) + '°';
+                }
+                _aspectPanelRAF = requestAnimationFrame(tick);
+            };
+            _aspectPanelRAF = requestAnimationFrame(tick);
+        }
+    }
+
     /* ======================================================================
      *  Background animations (issue #13)
      *
@@ -3498,6 +3765,11 @@
         // that CSS-box drift and re-frame, instead of the user having to
         // un/re-maximize the window.
         let _appliedW = 0, _appliedH = 0;
+        // Last pane aspect (w/h) handed to the camera, cached so camUpdate can
+        // recompute the horizontal-FOV-hold each frame (and react to live
+        // __h3dAspectTune edits) without waiting for a resize. 0 until first
+        // applySize().
+        let _paneAspect = 0;
         // True once applySize() has pinned the .h3d-wrap overlay to the
         // highway canvas's offset box. Stays false while the canvas has no
         // layout yet (init() can run before #highway has a real box, where
@@ -5976,7 +6248,7 @@
             scene = new T.Scene();
             scene.fog = new T.Fog(0x101820, FOG_START * 0.8, FOG_END * 1.2);
 
-            cam = new T.PerspectiveCamera(70, 1, 0.01, FOG_END * 3);
+            cam = new T.PerspectiveCamera(BASE_VFOV, 1, 0.01, FOG_END * 3);
 
             ambLight = new T.AmbientLight(0xffffff, 0.85);
             scene.add(ambLight);
@@ -13915,11 +14187,77 @@
             ctx.restore();
         }
 
+        // Horizontal-FOV-hold ("Hor+"). Returns the vertical fov (deg) the
+        // camera should use for the given pane aspect. With the bridge off (or
+        // absent), or at/under the start aspect, it returns the base vertical
+        // fov unchanged — an exact no-op, so normal panes render identically to
+        // before. Past the start aspect it lowers the vertical fov to keep the
+        // horizontal cone ~constant, so the neck fills an ultra-wide pane
+        // instead of collapsing into a central sliver. Pure + finite-guarded.
+        function effectiveVfov(aspect, tune) {
+            const base = (tune && Number.isFinite(tune.baseVfov)) ? tune.baseVfov : BASE_VFOV;
+            if (!tune || !tune.enabled || !Number.isFinite(aspect) || aspect <= 0) return base;
+            const start = (Number.isFinite(tune.startAspect) && tune.startAspect > 0)
+                ? tune.startAspect : HORPLUS_START_ASPECT;
+            if (aspect <= start) return base;
+            const floor = Number.isFinite(tune.minVfovDeg) ? tune.minVfovDeg : HORPLUS_MIN_VFOV;
+            const DEG = Math.PI / 180;
+            // Held horizontal fov: explicit hfovDeg if given, else the horizontal
+            // cone the base vertical fov produces at the start aspect.
+            const hfov = (Number.isFinite(tune.hfovDeg) && tune.hfovDeg > 0)
+                ? tune.hfovDeg * DEG
+                : 2 * Math.atan(Math.tan(base * DEG / 2) * start);
+            // Vertical fov that reproduces that horizontal cone at this aspect.
+            let vfov = 2 * Math.atan(Math.tan(hfov / 2) / aspect) / DEG;
+            const blend = Number.isFinite(tune.blend) ? Math.max(0, Math.min(1, tune.blend)) : 1;
+            vfov = base + (vfov - base) * blend;            // 0 = base, 1 = full Hor+
+            if (!Number.isFinite(vfov)) return base;
+            return Math.max(floor, Math.min(base, vfov));
+        }
+
         /* ── Camera smooth lerp ──────────────────────────────────────────── */
         function camUpdate(bundle) {
             const bpm = computeBPM(bundle.beats, bundle.currentTime);
             const lerp = CAM_LERP_BASE * Math.max(bpm, 60) / 120;
 
+            // ── Horizontal-FOV-hold + optional wide-pane pose nudges ──
+            // Driven by window.__h3dAspectTune (default off → exact no-op).
+            // _aspectTune() returns the live bridge object, seeded from defaults
+            // + localStorage on first read so a persisted tuning session applies
+            // on load without opening the panel. Every field is finite-coerced.
+            // When disabled (or splitOnly and not in a split) the tune is treated
+            // as null, so effectiveVfov returns the base vertical fov and cam.fov
+            // is restored to it. The fov write is guarded on an actual change so
+            // a steady pane costs nothing.
+            const _aspTune = _aspectTune();
+            const _aspActive = !!(_aspTune && _aspTune.enabled
+                && !(_aspTune.splitOnly && !_ssActive()));
+            const _tune = _aspActive ? _aspTune : null;
+            const _vfov = effectiveVfov(_paneAspect, _tune);
+            if (Number.isFinite(_vfov) && Math.abs(_vfov - cam.fov) > 1e-4) {
+                cam.fov = _vfov;
+                cam.updateProjectionMatrix();
+            }
+            // Publish a live readout for the tuner panel (only while it's open,
+            // so the steady path stays allocation-free). Last pane to render wins
+            // the slot — fine, all panes share the same aspect in a split layout.
+            if (window.__h3dAspectPanelOpen) {
+                const _ro = window.__h3dAspectReadout || (window.__h3dAspectReadout = {});
+                _ro.aspect = _paneAspect; _ro.vfov = _vfov;
+            }
+            // Optional pose nudges (height / dolly / pitch) to chase a low-flat
+            // wide-pane look if fov alone isn't enough. Gated to wide panes and
+            // suppressed while the Camera Director owns the view (it wins).
+            const _startAspect = (_tune && Number.isFinite(_tune.startAspect) && _tune.startAspect > 0)
+                ? _tune.startAspect : HORPLUS_START_ASPECT;
+            const _dirActive = !!(window.__h3dCamCtl && window.__h3dCamCtl.enabled);
+            const _wide = !!(_tune && _paneAspect > _startAspect) && !_dirActive;
+            const _poseHMul = (_wide && Number.isFinite(_tune.heightMul)) ? _tune.heightMul : 1;
+            const _poseDMul = (_wide && Number.isFinite(_tune.distMul)) ? _tune.distMul : 1;
+            const _poseLookYAdd = (_wide && Number.isFinite(_tune.pitchAdd)) ? _tune.pitchAdd * K : 0;
+            const _poseLookZMul = (_wide && Number.isFinite(_tune.lookDepthMul) && _tune.lookDepthMul > 0)
+                ? _tune.lookDepthMul : 1;
+
             curX += (tgtX - curX) * lerp;
             // The fret-row fit guard (end of camUpdate) may dolly the camera back
             // via _fretRowFitBoost; the span-driven tgtDist still owns zooming IN.
@@ -13935,6 +14273,9 @@
             const _dMul = CAM_FRAME_D_NEAR + (CAM_FRAME_D_FAR - CAM_FRAME_D_NEAR) * _zt;
             const shoulderOffset = (_leftyCached ? -1 : 1) * 10 * K;
             let _camX = curX + shoulderOffset, _camY = h * _hMul, _camZ = dist * _dMul;
+            // Optional wide-pane pose nudges (default identity → no-op).
+            if (_poseHMul !== 1) _camY *= _poseHMul;
+            if (_poseDMul !== 1) _camZ *= _poseDMul;
             // ── Free-camera user tweaks (orbit / height / zoom / pan) ──
             // Driven by the Camera Director plugin via window.__h3dCamCtl.
             // Layered ON TOP of the auto-framing so note tracking still works.
@@ -13943,7 +14284,7 @@
             // finite number before use so a malformed object can never feed NaN
             // into cam.position / cam.lookAt.
             const _freeCam = window.__h3dCamCtl;
-            const _lookAtZ = -FOCUS_D * 0.35;
+            const _lookAtZ = -FOCUS_D * 0.35 * _poseLookZMul;
             if (_freeCam && _freeCam.enabled) {
                 const _distMul = Number.isFinite(_freeCam.distMul) ? _freeCam.distMul : 1;
                 const _heightMul = Number.isFinite(_freeCam.heightMul) ? _freeCam.heightMul : 1;
@@ -13964,7 +14305,7 @@
             // This lets the camera adapt to any panel aspect ratio automatically.
             const fretMidY = (sY(0) + sY(nStr - 1)) / 2;
             _probe.set(curX, fretMidY, 0);                  // play-line fretboard centre
-            cam.lookAt(curX, curLookY, -FOCUS_D * 0.35);    // tentative look — needed for project()
+            cam.lookAt(curX, curLookY + _poseLookYAdd, _lookAtZ);    // tentative look — needed for project()
             cam.updateMatrixWorld();
             _probe.project(cam);                             // _probe.y → NDC in [-1, 1]
 
@@ -13993,7 +14334,7 @@
                 const _pitch = Number.isFinite(_freeCam.pitch) ? _freeCam.pitch : 0;
                 cam.lookAt(curX + _panX * K, curLookY + (_pitch + _panY) * K, _lookAtZ);
             } else {
-                cam.lookAt(curX, curLookY, _lookAtZ);
+                cam.lookAt(curX, curLookY + _poseLookYAdd, _lookAtZ);
             }
 
             // ── Fret-row fit guard ────────────────────────────────────────────
@@ -14090,6 +14431,10 @@
             cam.aspect = w / h;
             cam.updateProjectionMatrix();
             aspectScale = Math.max(1, REF_ASPECT / Math.max(cam.aspect, 0.5));
+            // Cache the pane aspect for the horizontal-FOV-hold in camUpdate.
+            // cam.fov itself is owned by camUpdate (not set here) so live
+            // __h3dAspectTune edits apply every frame without a resize.
+            _paneAspect = cam.aspect;
             _appliedW = w; _appliedH = h;
         }
 
@@ -14333,6 +14678,7 @@
                 }
                 _destroyed = _isReady = false;
                 _isFocused = true;
+                _registerAspectAbShortcut();   // session-global A/B toggle (self-guarded)
                 const myToken = ++_initToken;
                 highwayCanvas = canvas;
                 _invertedCached = !!(bundle && bundle.inverted);
@@ -14751,6 +15097,8 @@
                 _destroyed = true; _isReady = false; _diagChord = null; _diagPrev = null; _diagLastKey = null; _diagRenderCache.clear();
                 _lastHwW = 0; _lastHwH = 0;
                 _appliedW = 0; _appliedH = 0;
+                _paneAspect = 0;
+                if (cam && cam.fov !== BASE_VFOV) { cam.fov = BASE_VFOV; cam.updateProjectionMatrix(); }
                 _wrapPinned = false;
                 _unsubscribeFocus(); teardown();
                 highwayCanvas = null;

static/v3/index.html

@@ -855,9 +855,12 @@
                     <div id="v3-live-performance-state" class="v3-live-performance-state" aria-hidden="true"></div>
                 </div>
                 <div id="v3-upnext" class="v3-upnext hidden">
-                    <span class="text-gray-400">Up Next:</span>
-                    <span id="v3-upnext-name" class="v3-upnext-name"></span>
-                    <span id="v3-upnext-eta" class="text-gray-400 text-xs"></span>
+                    <div class="v3-upnext-row">
+                        <span class="text-gray-400">Up Next:</span>
+                        <span id="v3-upnext-name" class="v3-upnext-name"></span>
+                        <span id="v3-upnext-eta" class="text-gray-400 text-xs"></span>
+                    </div>
+                    <div class="v3-upnext-bar"><div id="v3-upnext-bar-fill" class="v3-upnext-bar-fill"></div></div>
                 </div>
             </div>
         </div>
@@ -923,6 +926,15 @@
                         <option value="0.5">Low</option>
                     </select>
                 </div>
+                <div class="v3-pop-row">
+                    <span class="v3-pop-label" id="min-scale-label">Min res</span>
+                    <select id="min-scale-select" onchange="highway.setMinRenderScale && highway.setMinRenderScale(parseFloat(this.value))" class="v3-pop-select" aria-labelledby="min-scale-label" title="Minimum auto resolution — how far the highway may lower its resolution to hold the frame rate on heavy scenes. 'Full' disables auto-downscaling, but the Quality selector still caps the maximum (so it's only full resolution at Quality = HD).">
+                        <option value="0.25">25%</option>
+                        <option value="0.5">50%</option>
+                        <option value="0.75">75%</option>
+                        <option value="1">Full</option>
+                    </select>
+                </div>
                 <div class="v3-pop-row">
                     <span class="v3-pop-label" id="scoreboard-label">Scoreboard</span>
                     <select id="scoreboard-select" onchange="setScoreboard(this.value)" class="v3-pop-select" aria-labelledby="scoreboard-label" title="Highway scoreboard">

static/v3/player-chrome.js

@@ -187,6 +187,19 @@
         const nm = $('v3-upnext-name'), eta = $('v3-upnext-eta');
         if (nm) nm.textContent = next.name || '—';
         if (eta) eta.textContent = 'in ' + dt.toFixed(1) + 's';
+        // Progress bar: fraction of the current section elapsed toward `next`.
+        // Previous boundary is the last section at/before now (else song start).
+        const fill = $('v3-upnext-bar-fill');
+        if (fill) {
+            let prevT = 0;
+            for (let i = 0; i < secs.length; i++) {
+                if (typeof secs[i].time === 'number' && secs[i].time <= t) prevT = secs[i].time;
+                else break;
+            }
+            const span = next.time - prevT;
+            const prog = span > 0 ? Math.max(0, Math.min(1, (t - prevT) / span)) : 0;
+            fill.style.width = (prog * 100).toFixed(1) + '%';
+        }
         pill.classList.remove('hidden');
     }
 

static/v3/songs.js

@@ -1567,6 +1567,7 @@
             '<select id="v3-songs-format" class="' + ctrl + '">' + opt(FORMATS, state.format) + '</select>' +
             '<button id="v3-songs-filters" class="relative ' + ctrl + ' flex items-center gap-2">Filters<span id="v3-songs-filter-count" class="hidden bg-fb-primary text-white text-xs rounded-full px-1.5">0</span></button>' +
             '<button id="v3-songs-select" class="' + ctrl + (state.selectMode ? ' bg-fb-primary text-white' : '') + '">Select</button>' +
+            '<button id="v3-songs-refresh" title="Refresh library (scan for new songs)" class="' + ctrl + '">⟳ Refresh</button>' +
             '<button id="v3-songs-upload" class="' + ctrl + '">Upload</button>' +
             '</div></div></div>' +
             // Practice-aware library home: a repertoire progress meter + a
@@ -1624,6 +1625,16 @@
             if (legacy) { legacy.click(); watchUploadScan(); }
         });
         byId('v3-songs-select').addEventListener('click', () => setSelectMode(!state.selectMode));
+        byId('v3-songs-refresh')?.addEventListener('click', refreshLibrary);
+        // Reflect a scan already in progress (Settings button or a background
+        // pass) on the Refresh button, so its state isn't just tied to clicks here.
+        (async () => {
+            try {
+                const r = await fetch('/api/scan-status');
+                const sd = r.ok ? await r.json() : null;
+                if (sd && sd.running) { _setRefreshState(sd); _watchScan({ announce: false }); }
+            } catch (e) { /* */ }
+        })();
 
         // Bulletproof multi-select: in select mode, a capture-phase click on the
         // grid toggles the card and STOPS the event, so nothing (a per-card
@@ -1753,6 +1764,73 @@
     // legacy screens, so without this newly-uploaded songs wouldn't appear in
     // v3 until a manual refresh. Bounded so a no-op upload can't poll forever.
     let _uploadScanTimer = null;
+    // ── Library refresh (rescan) from the Songs toolbar ───────────────────────
+    // The tester ask: a media-server-style "I dropped files in my folder, hit
+    // refresh" button, with live progress. Reuses the SAME machinery the Settings
+    // Rescan buttons drive (/api/rescan + /api/scan-status) and emits
+    // library:changed so the grid reloads. A scan already running (Settings or a
+    // background pass) is reflected on the button too.
+    let _refreshPoll = null;
+    function _setRefreshState(sd) {
+        const btn = document.getElementById('v3-songs-refresh');
+        if (!btn) return;
+        if (sd && sd.running) {
+            // Determinate count only exists in the 'scanning' stage; 'listing' is
+            // indeterminate (total 0), so show a plain "Scanning…" then.
+            const det = (sd.stage === 'scanning' && sd.total) ? ' ' + sd.done + '/' + sd.total : '';
+            btn.textContent = '⟳ Scanning' + det + '…';
+            btn.disabled = true;
+            btn.classList.add('opacity-70');
+            const pct = sd.total ? Math.round((sd.done / sd.total) * 100) + '% · ' : '';
+            btn.title = 'Scanning new/changed songs… ' + pct + (sd.current || '');
+        } else {
+            btn.textContent = '⟳ Refresh';
+            btn.disabled = false;
+            btn.classList.remove('opacity-70');
+            btn.title = 'Refresh library (scan for new songs)';
+        }
+    }
+    // Show a completion toast (reuses the shared fbNotify surface), suppressed
+    // while in a song. Honest + never-punishing copy; the precise "N added" count
+    // arrives with the background-scan delta work — until then this is a generic,
+    // truthful confirmation.
+    function _scanCompleteToast(sd) {
+        if (document.querySelector('.screen.active') && document.querySelector('.screen.active').id === 'player') return;
+        if (!window.fbNotify) return;
+        const msg = (sd && sd.error) ? 'Scan finished with an error' : 'Your library is up to date';
+        try { window.fbNotify.show({ title: 'Library scan complete', message: msg, icon: '🔄', accent: '#22C55E' }); } catch (e) { /* */ }
+    }
+    // Poll scan-status until the scan finishes, driving the button state. On
+    // completion, emit library:changed (grid reloads via the listener below) and,
+    // for a user-initiated refresh (announce), show the toast. announce:false is
+    // used when we only attached to a scan we didn't start.
+    function _watchScan(opts) {
+        if (_refreshPoll) return;
+        const announce = !opts || opts.announce !== false;
+        let sawRunning = false, ticks = 0;
+        _refreshPoll = setInterval(async () => {
+            ticks++;
+            let sd = null;
+            try { const r = await fetch('/api/scan-status'); if (r.ok) sd = await r.json(); } catch (e) { /* */ }
+            _setRefreshState(sd);
+            if (sd && sd.running) sawRunning = true;
+            // A user-initiated refresh that never saw a running scan = nothing to
+            // do (already up to date); give prompt feedback instead of waiting.
+            const noopDone = announce && !sawRunning && ticks >= 3;
+            if ((sawRunning && sd && !sd.running) || noopDone || ticks >= 180) {
+                clearInterval(_refreshPoll); _refreshPoll = null;
+                _setRefreshState(null);
+                if (sawRunning && window.feedBack) { try { window.feedBack.emit('library:changed', { reason: 'rescan' }); } catch (e) { /* */ } }
+                if (announce) _scanCompleteToast(sd);
+            }
+        }, 1000);
+    }
+    async function refreshLibrary() {
+        if (_refreshPoll) return;                 // a scan is already in progress
+        try { await fetch('/api/rescan', { method: 'POST' }); } catch (e) { /* */ }
+        _watchScan({ announce: true });
+    }
+
     function watchUploadScan() {
         if (_uploadScanTimer) clearInterval(_uploadScanTimer);
         let sawRunning = false, ticks = 0;

static/v3/v3.css

@@ -340,8 +340,9 @@ input, textarea, select,
 /* — Up Next pill (top-right, persistent) — */
 #player-hud .v3-upnext {
     display: flex;
-    align-items: center;
-    gap: .5rem;
+    flex-direction: column;
+    align-items: stretch;
+    gap: .35rem;
     padding: .45rem .9rem;
     border-radius: .75rem;
     background: rgba(15, 23, 42, .7);
@@ -351,6 +352,26 @@ input, textarea, select,
     pointer-events: auto;
 }
 #player-hud .v3-upnext.hidden { display: none; }
+/* Text row keeps the original inline layout untouched. */
+#player-hud .v3-upnext .v3-upnext-row {
+    display: flex;
+    align-items: center;
+    gap: .5rem;
+}
+/* Progress bar under the text — fills as the current section elapses. */
+#player-hud .v3-upnext .v3-upnext-bar {
+    height: 4px;
+    border-radius: 999px;
+    background: rgba(148, 163, 184, .25);
+    overflow: hidden;
+}
+#player-hud .v3-upnext .v3-upnext-bar-fill {
+    height: 100%;
+    width: 0%;
+    border-radius: inherit;
+    background: linear-gradient(90deg, #22d3ee, #a855f7, #f472b6);
+    transition: width .12s linear;
+}
 
 /* — Live performance HUD (top-right, read-only) — */
 .v3-live-performance-hud {

tests/js/highway_3d_wide_fov.test.js

@@ -0,0 +1,174 @@
+// Pins the wide-pane horizontal-FOV-hold ("Hor+") framing in
+// plugins/highway_3d/screen.js.
+//
+// What it guards: ultra-wide panes (top/bottom 2-player split → full-width /
+// half-height → ~32:9) used to render the neck as a thin central sliver because
+// THREE's PerspectiveCamera fov is VERTICAL and was locked at 70°, ballooning
+// the horizontal cone past 130°. The fix lets camUpdate lower the effective
+// vertical fov as the pane widens (holding the horizontal cone ~constant) so the
+// neck fills the pane. It is gated behind window.__h3dAspectTune (default off →
+// byte-for-byte the prior behaviour) for live A/B comparison.
+//
+// A refactor that re-hardcodes the camera fov, drops the change-guarded cam.fov
+// write, stops caching the pane aspect, or removes the no-op-at-startAspect
+// guarantee would silently regress the feature (or worse, change normal-pane
+// framing). These are source-level pins — same strategy as the other
+// tests/js/ files (no DOM / WebGL in CI).
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'highway_3d', 'screen.js');
+const src = fs.readFileSync(SCREEN_JS, 'utf8');
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+test('BASE_VFOV is a named constant (not a literal in the camera ctor)', () => {
+    assert.match(
+        src,
+        /const\s+BASE_VFOV\s*=\s*70\s*;/,
+        'BASE_VFOV must be declared as a constant',
+    );
+});
+
+test('the camera is constructed with BASE_VFOV, not a bare 70', () => {
+    assert.match(
+        src,
+        /new\s+T\.PerspectiveCamera\(\s*BASE_VFOV\s*,/,
+        'PerspectiveCamera must take BASE_VFOV as its vertical fov',
+    );
+});
+
+test('the Hor+ start-aspect and min-vfov defaults exist', () => {
+    assert.match(src, /const\s+HORPLUS_START_ASPECT\s*=\s*16\s*\/\s*9\s*;/,
+        'HORPLUS_START_ASPECT must default to 16/9 (no-op at/under the reference aspect)');
+    assert.match(src, /const\s+HORPLUS_MIN_VFOV\s*=\s*\d+\s*;/,
+        'HORPLUS_MIN_VFOV floor must be declared');
+});
+
+// ── effectiveVfov: no-op guarantees ──────────────────────────────────────────
+
+test('effectiveVfov returns the base fov when the bridge is off/absent', () => {
+    // The disabled / malformed-input guard returns `base` before any Hor+ math,
+    // so normal panes are unaffected when __h3dAspectTune is missing or off.
+    assert.match(
+        src,
+        /function\s+effectiveVfov\s*\(\s*aspect\s*,\s*tune\s*\)\s*\{[\s\S]*?if\s*\(\s*!tune\s*\|\|\s*!tune\.enabled[\s\S]*?return\s+base\s*;/,
+        'effectiveVfov must short-circuit to the base fov when disabled',
+    );
+});
+
+test('effectiveVfov is a no-op at/under the start aspect', () => {
+    assert.match(
+        src,
+        /if\s*\(\s*aspect\s*<=\s*start\s*\)\s*return\s+base\s*;/,
+        'effectiveVfov must return base when aspect <= start (no-op for normal/2x2 panes)',
+    );
+});
+
+// ── shipped defaults: off + coherent ─────────────────────────────────────────
+// The "default off → byte-for-byte prior behaviour" contract only holds if the
+// shipped _ASPECT_DEFAULTS actually ship disabled with a base that matches the
+// camera's constructed fov. A previous revision shipped enabled:true with
+// baseVfov:30 (and blend:0), which forced every pane's fov to 30/36 and
+// silently re-framed normal single-player panes. These pin against that.
+
+test('_ASPECT_DEFAULTS ships disabled (no-op out of the box)', () => {
+    assert.match(
+        src,
+        /const\s+_ASPECT_DEFAULTS\s*=\s*\{[\s\S]*?\benabled\s*:\s*false\b/,
+        '_ASPECT_DEFAULTS.enabled must default to false so the feature is opt-in',
+    );
+});
+
+test('the default base fov matches BASE_VFOV (enabling is still a no-op on normal panes)', () => {
+    // baseVfov === BASE_VFOV means even with the feature ON, a <=startAspect pane
+    // returns the unchanged 70° — the effect is confined to genuinely wide panes.
+    assert.match(
+        src,
+        /const\s+_ASPECT_DEFAULTS\s*=\s*\{[\s\S]*?\bbaseVfov\s*:\s*BASE_VFOV\b/,
+        '_ASPECT_DEFAULTS.baseVfov must default to BASE_VFOV, not a divergent literal',
+    );
+});
+
+test('the default blend engages the hold and the floor sits below the base', () => {
+    // blend:1 means turning the feature on actually holds the horizontal cone
+    // (blend:0 would collapse effectiveVfov back to base = feature inert), and
+    // minVfovDeg:HORPLUS_MIN_VFOV keeps the floor below baseVfov (a real floor,
+    // not one that clamps the base upward).
+    assert.match(
+        src,
+        /const\s+_ASPECT_DEFAULTS\s*=\s*\{[\s\S]*?\bblend\s*:\s*1\b/,
+        '_ASPECT_DEFAULTS.blend must default to 1 so the Hor+ hold actually applies when enabled',
+    );
+    assert.match(
+        src,
+        /const\s+_ASPECT_DEFAULTS\s*=\s*\{[\s\S]*?\bminVfovDeg\s*:\s*HORPLUS_MIN_VFOV\b/,
+        '_ASPECT_DEFAULTS.minVfovDeg must default to HORPLUS_MIN_VFOV (a floor below baseVfov)',
+    );
+});
+
+// ── camUpdate: change-guarded fov write + cached aspect ───────────────────────
+
+test('applySize caches the pane aspect for camUpdate', () => {
+    assert.match(
+        src,
+        /_paneAspect\s*=\s*cam\.aspect\s*;/,
+        'applySize must cache cam.aspect into _paneAspect',
+    );
+});
+
+test('camUpdate reads the live tune bridge and respects splitOnly', () => {
+    assert.match(
+        src,
+        /const\s+_aspTune\s*=\s*_aspectTune\(\)\s*;[\s\S]*?_aspTune\.splitOnly\s*&&\s*!_ssActive\(\)/,
+        'camUpdate must read the bridge via _aspectTune() and gate splitOnly on _ssActive()',
+    );
+});
+
+test('the tune bridge seeds from localStorage (persisted sessions apply on load)', () => {
+    assert.match(
+        src,
+        /function\s+_aspectTune\s*\(\)[\s\S]*?localStorage\.getItem\(\s*_ASPECT_LS\s*\)/,
+        '_aspectTune() must seed the bridge from localStorage',
+    );
+});
+
+test('a floating tuner panel is built and toggled with the A/B state', () => {
+    assert.match(src, /function\s+_ensureAspectPanel\s*\(\)/,
+        '_ensureAspectPanel() must exist to build the live panel');
+    assert.match(src, /function\s+_setAspectPanelVisible\s*\(/,
+        '_setAspectPanelVisible() must show/hide the panel with the feature');
+});
+
+test('camUpdate only writes cam.fov when it actually changes', () => {
+    // Guarding the write avoids a per-frame updateProjectionMatrix on a steady
+    // pane and keeps the disabled path free.
+    assert.match(
+        src,
+        /Math\.abs\(\s*_vfov\s*-\s*cam\.fov\s*\)\s*>\s*1e-4[\s\S]*?cam\.fov\s*=\s*_vfov\s*;[\s\S]*?cam\.updateProjectionMatrix\(\)/,
+        'camUpdate must guard the cam.fov write behind a change check',
+    );
+});
+
+// ── A/B toggle + lifecycle reset ──────────────────────────────────────────────
+
+test('an A/B toggle shortcut flips the tune enabled flag', () => {
+    assert.match(
+        src,
+        /registerShortcut\(\{[\s\S]*?const\s+t\s*=\s*_aspectTune\(\)\s*;[\s\S]*?t\.enabled\s*=\s*!\s*t\.enabled/,
+        'a registerShortcut handler must toggle the bridge enabled flag',
+    );
+});
+
+test('destroy() resets the pane aspect and restores the base fov', () => {
+    assert.match(src, /_paneAspect\s*=\s*0\s*;/,
+        'destroy() must reset _paneAspect to 0');
+    assert.match(
+        src,
+        /cam\.fov\s*!==\s*BASE_VFOV[\s\S]*?cam\.fov\s*=\s*BASE_VFOV\s*;\s*cam\.updateProjectionMatrix\(\)/,
+        'destroy() must restore cam.fov to BASE_VFOV for instance reuse',
+    );
+});