refactor(app): carve the DOM/modal primitives out of app.js (R3a)

static/js/dom.js (203 lines) — esc, _escAttr, _isElementVisible, _trapFocusInModal,
_confirmDialog, uiPrompt. Bodies VERBATIM. app.js 10,593 → 10,414.

A GATHER, not a slice — the six lived in six different places (108, 635, 659,
2617, 2623, 8892). They belong together because they are the BOTTOM of the UI
stack: `esc` alone has 25 call sites and `_escAttr` 23, and every later carve that
renders HTML will need them.

That is the actual point of doing this one now. Give them a home and the next
carve imports them; leave them in app.js and the next carve that renders HTML has
to invent a host seam to reach back into app.js — exactly the trap the
plugin-loader carve had to work around until the viz layer became a module. This
is the cheapest possible way to stop that recurring.

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

Zero imports. Six exports (every one is used outside the cluster).

VERIFIED BY DRIVING THE MODALS, not just booting — they are interactive, so a
green suite says little. A/B against origin/main in two browsers:
  * window.uiPrompt / _confirmDialog / _trapFocusInModal all resolve
  * uiPrompt() mounts its modal, accepts typed input, and resolves with the typed
    value ('typed') — IDENTICAL on both
  * _confirmDialog() mounts and resolves true on confirm — IDENTICAL
  * zero console/page errors either side

pytest 2396, node 1038/1038, ESLint 0, tailwind-fresh clean, Codex 0.

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

static/js/diagnostics-export.js

@@ -0,0 +1,280 @@
+// The diagnostics-bundle export — the Settings "Export diagnostics" flow.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+// It snapshots the browser-only state (console ring buffer, hardware probe,
+// localStorage, ua) via window.feedBack.diagnostics, POSTs it to
+// /api/diagnostics/export with the user's include/redact toggles, and streams the
+// returned zip to disk. Bundle layout + schemas: docs/diagnostics-bundle-spec.md.
+//
+// Everything except the two entry points is module-private — the preview
+// renderer, the file-label table, and the byte/HTML formatters are used nowhere
+// else in core.
+
+//
+// Companion to Settings export but for troubleshooting bug reports.
+// Bundle layout + schemas: docs/diagnostics-bundle-spec.md.
+//
+// Frontend's job is to:
+//   1. Snapshot the browser-only state (console ring buffer, hardware
+//      probe, localStorage, ua) via window.feedBack.diagnostics.
+//   2. POST it to /api/diagnostics/export with the user's include /
+//      redact toggles.
+//   3. Stream the returned zip to disk.
+
+function _diagIncludeFromUI() {
+    const v = (id) => document.getElementById(id)?.checked !== false;
+    return {
+        system: v('diag-incl-system'),
+        hardware: v('diag-incl-hardware'),
+        logs: v('diag-incl-logs'),
+        console: v('diag-incl-console'),
+        plugins: v('diag-incl-plugins'),
+    };
+}
+
+function _diagRedactFromUI() {
+    const el = document.getElementById('diag-redact');
+    return el ? !!el.checked : true;
+}
+
+// Map raw file paths inside the bundle to plain-English labels +
+// descriptions for the preview UI. Only paths that show up in
+// previews need entries — unknown paths fall back to the path itself.
+const _DIAG_FILE_LABELS = {
+    'system/version.json':   { label: 'App version',    desc: 'FeedBack version, Python, OS' },
+    'system/env.json':       { label: 'Environment',    desc: 'Allowlisted env vars (LOG_LEVEL, etc.). No secrets.' },
+    'system/hardware.json':  { label: 'Hardware (server-side)', desc: 'CPU, RAM, GPU. In Docker this reflects the container, not the host.' },
+    'system/plugins.json':   { label: 'Plugins',        desc: 'Loaded plugins + git commit + orphan detection.' },
+    'logs/server.log':       { label: 'Server log',     desc: 'Tail of LOG_FILE (last ~5 MB).' },
+    'logs/server.log.meta.json': { label: 'Log metadata', desc: 'Log file path, size, rotation info.' },
+    'client/console.json':   { label: 'Browser console', desc: 'console.log/warn/error transcript + window errors.' },
+    'client/hardware.json':  { label: 'Hardware (browser)', desc: 'WebGL/WebGPU adapter, host OS via userAgent.' },
+    'client/local_storage.json': { label: 'Browser storage', desc: 'localStorage contents (preferences).' },
+    'client/ua.json':        { label: 'User agent',     desc: 'Browser, screen, page URL.' },
+};
+
+function _formatBytes(n) {
+    if (!n || n < 1024) return (n || 0) + ' B';
+    if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
+    return (n / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+function _escapeHtml(s) {
+    return String(s || '').replace(/[&<>"']/g, c => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+}
+
+function _renderDiagPreview(data) {
+    const m = data.manifest || {};
+    const files = m.files || [];
+    const groups = { system: [], logs: [], client: [], plugins: [], other: [] };
+    for (const f of files) {
+        const top = (f.path || '').split('/')[0];
+        (groups[top] || groups.other).push(f);
+    }
+    const totalBytes = files.reduce((s, f) => s + (f.size || 0), 0);
+    const include = _diagIncludeFromUI();
+    const redact = _diagRedactFromUI();
+
+    const sections = [];
+    // Per-file `summary` (server-derived) → human one-liner.
+    function _summaryLine(path, summary) {
+        if (!summary || typeof summary !== 'object') return '';
+        if (path === 'system/plugins.json') {
+            const loaded = summary.loaded_count || 0;
+            const orphans = summary.orphan_count || 0;
+            const orphPart = orphans ? ` · <span class="text-amber-400">${orphans} orphan${orphans === 1 ? '' : 's'}</span>` : '';
+            return `${loaded} plugin${loaded === 1 ? '' : 's'} loaded${orphPart}`;
+        }
+        if (path === 'client/console.json') {
+            const total = summary.entry_count || 0;
+            const lvl = summary.by_level || {};
+            const parts = [];
+            for (const k of ['error','warn','info','log','debug']) {
+                if (lvl[k]) parts.push(`${lvl[k]} ${k}`);
+            }
+            return `${total} entries${parts.length ? ' (' + parts.join(', ') + ')' : ''}`;
+        }
+        if (path === 'system/hardware.json') {
+            const bits = [];
+            if (summary.cpu_brand) bits.push(summary.cpu_brand);
+            if (summary.cores_logical) bits.push(`${summary.cores_logical} cores`);
+            if (summary.gpu_count) bits.push(`${summary.gpu_count} GPU`);
+            if (summary.runtime) bits.push(`runtime: ${summary.runtime}`);
+            return bits.join(' · ');
+        }
+        if (path === 'client/hardware.json') {
+            const bits = [];
+            if (summary.runtime) bits.push(summary.runtime);
+            if (summary.webgl_renderer) bits.push(summary.webgl_renderer);
+            return bits.join(' · ');
+        }
+        if (path === 'client/local_storage.json') {
+            return `${summary.key_count || 0} keys`;
+        }
+        if (path === 'system/version.json') {
+            const bits = [];
+            if (summary.feedBack) bits.push(`feedBack ${summary.feedBack}`);
+            if (summary.python) bits.push(`python ${summary.python}`);
+            if (summary.os) bits.push(summary.os);
+            return bits.join(' · ');
+        }
+        return '';
+    }
+
+    function pushSection(title, list, emptyHint) {
+        if (!list.length) {
+            if (emptyHint) {
+                sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">${_escapeHtml(title)}</div><div class="text-gray-500">${_escapeHtml(emptyHint)}</div></div>`);
+            }
+            return;
+        }
+        const rows = list.map(f => {
+            const meta = _DIAG_FILE_LABELS[f.path] || { label: f.path, desc: '' };
+            const summary = _summaryLine(f.path, f.summary);
+            const summaryHtml = summary
+                ? `<div class="text-accent-light text-[10px] mt-0.5">${summary}</div>`
+                : '';
+            return `<div class="flex justify-between gap-4 py-1 border-b border-dark-600 last:border-0">
+                <div class="min-w-0">
+                    <div class="text-gray-200">${_escapeHtml(meta.label)}</div>
+                    <div class="text-gray-500 text-[10px]">${_escapeHtml(meta.desc)}</div>
+                    ${summaryHtml}
+                </div>
+                <div class="text-gray-400 text-right whitespace-nowrap">${_escapeHtml(_formatBytes(f.size))}</div>
+            </div>`;
+        }).join('');
+        sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">${_escapeHtml(title)}</div>${rows}</div>`);
+    }
+
+    pushSection('System', groups.system, include.system ? '' : 'Skipped (toggle off)');
+    pushSection('Server logs', groups.logs, include.logs
+        ? 'No log file configured — set LOG_FILE env var to include server logs.'
+        : 'Skipped (toggle off)');
+    pushSection('Plugin diagnostics', groups.plugins, include.plugins
+        ? 'No plugins have opted in to diagnostics.'
+        : 'Skipped (toggle off)');
+
+    // Client section preview is a server-side estimate only — actual
+    // client/* payloads are added at Export time after the browser
+    // snapshots. Show what WILL be added, not file sizes.
+    const clientLines = [];
+    if (include.console) clientLines.push({ label: 'Browser console', desc: 'console.log/warn/error transcript + window errors.' });
+    if (include.hardware) clientLines.push({ label: 'Hardware (browser)', desc: 'WebGL/WebGPU adapter, host OS via userAgent.' });
+    clientLines.push({ label: 'Browser storage', desc: 'localStorage contents (preferences).' });
+    clientLines.push({ label: 'User agent', desc: 'Browser, screen, page URL.' });
+    const clientHtml = clientLines.map(c => `<div class="flex justify-between gap-4 py-1 border-b border-dark-600 last:border-0">
+        <div><div class="text-gray-200">${_escapeHtml(c.label)}</div><div class="text-gray-500 text-[10px]">${_escapeHtml(c.desc)}</div></div>
+        <div class="text-gray-500 text-right whitespace-nowrap">added on export</div>
+    </div>`).join('');
+    sections.push(`<div class="mb-3"><div class="text-gray-300 font-semibold mb-1">Browser data</div>${clientHtml}</div>`);
+
+    const notesHtml = (m.notes || []).length
+        ? `<div class="mb-3 bg-dark-600 border border-amber-500/30 rounded-lg p-2">
+              <div class="text-amber-400 text-[10px] font-semibold uppercase mb-1">Notes</div>
+              ${(m.notes).map(n => `<div class="text-gray-300 text-[11px]">• ${_escapeHtml(n)}</div>`).join('')}
+           </div>`
+        : '';
+
+    const privacyHtml = redact
+        ? `<div class="text-emerald-400 text-[11px]">🔒 Redaction enabled — paths, song names, IPs, and secrets will be replaced with stable hash tokens.</div>`
+        : `<div class="text-amber-400 text-[11px]">⚠ Redaction OFF — bundle will contain raw paths, song names, and IPs. Only share with people you trust.</div>`;
+
+    return `
+        <div class="text-[11px]">
+            <div class="flex justify-between items-baseline mb-2">
+                <div class="text-gray-200 font-semibold">${_escapeHtml(data.filename)}</div>
+                <div class="text-gray-400">${_escapeHtml(_formatBytes(totalBytes))}<span class="text-gray-600"> server-side</span></div>
+            </div>
+            <div class="text-gray-500 text-[10px] mb-3">runtime: ${_escapeHtml(m.runtime || 'unknown')} · exported_at: ${_escapeHtml(m.exported_at || '')}</div>
+            ${notesHtml}
+            ${sections.join('')}
+            ${privacyHtml}
+        </div>`;
+}
+
+export async function previewDiagnostics() {
+    const status = document.getElementById('diag-status');
+    const preview = document.getElementById('diag-preview');
+    if (!status || !preview) return;
+    status.textContent = 'Building preview…';
+    preview.classList.add('hidden');
+    const include = _diagIncludeFromUI();
+    const params = new URLSearchParams({
+        redact: String(_diagRedactFromUI()),
+        system: String(include.system),
+        hardware: String(include.hardware),
+        logs: String(include.logs),
+        console: String(include.console),
+        plugins: String(include.plugins),
+    });
+    try {
+        const resp = await fetch(`/api/diagnostics/preview?${params.toString()}`);
+        if (!resp.ok) {
+            status.textContent = `Preview failed (HTTP ${resp.status})`;
+            return;
+        }
+        const data = await resp.json();
+        preview.innerHTML = _renderDiagPreview(data);
+        preview.classList.remove('hidden');
+        status.textContent = 'Preview ready.';
+    } catch (e) {
+        status.textContent = `Preview failed: ${e.message}`;
+    }
+}
+
+export async function exportDiagnostics() {
+    const status = document.getElementById('diag-status');
+    if (!status) return;
+    status.textContent = 'Building bundle…';
+    const include = _diagIncludeFromUI();
+    const redact = _diagRedactFromUI();
+
+    const diag = window.feedBack && window.feedBack.diagnostics;
+    const body = {
+        redact,
+        include,
+        client_console: include.console && diag ? diag.snapshotConsole() : null,
+        client_hardware: include.hardware && diag ? await diag.snapshotHardware() : null,
+        client_ua: diag ? diag.snapshotUa() : null,
+        local_storage: diag ? diag.snapshotLocalStorage() : null,
+        client_contributions: diag ? diag.snapshotContributions() : null,
+    };
+
+    let resp;
+    try {
+        resp = await fetch('/api/diagnostics/export', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    } catch (e) {
+        status.textContent = `Export failed: ${e.message}`;
+        return;
+    }
+    if (!resp.ok) {
+        status.textContent = `Export failed (HTTP ${resp.status})`;
+        return;
+    }
+    let filename = 'feedBack-diag.zip';
+    const disp = resp.headers.get('Content-Disposition');
+    if (disp) {
+        const m = /filename="([^"]+)"/.exec(disp);
+        if (m) filename = m[1];
+    }
+    try {
+        const blob = await resp.blob();
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+        status.textContent = `Exported ${filename}`;
+    } catch (e) {
+        status.textContent = `Export failed during download: ${e.message}`;
+    }
+}

static/js/dom.js

@@ -0,0 +1,203 @@
+// DOM + HTML-escaping primitives, and the modal dialogs built on them.
+//
+// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+//
+// This one is a GATHER, not a slice — the six lived in six different places in
+// app.js. They belong together because they are the bottom of the UI stack:
+// `esc` / `_escAttr` alone have ~48 call sites, and every later carve that
+// renders HTML will need them. Giving them a home NOW means those carves can
+// import them instead of inventing a host seam to reach back into app.js —
+// which is exactly the trap the plugin-loader carve had to work around before
+// the viz layer became a module.
+
+export function _isElementVisible(el) {
+    // Walk ancestors looking for display:none. Handles collapsed
+    // `.album-body` / `.artist-body` subtrees (hidden via CSS class
+    // rules). Using a DOM walk rather than `offsetParent` avoids the
+    // false-negative for `position:fixed` elements whose offsetParent
+    // is null even when they are perfectly visible.
+    if (!el) return false;
+    let node = el;
+    while (node && node !== document.body) {
+        if (getComputedStyle(node).display === 'none') return false;
+        node = node.parentElement;
+    }
+    return true;
+}
+
+// Focus trap: keep Tab / Shift+Tab cycling inside `modal` so focus
+// can't escape to the content underneath while the overlay is open.
+// Call this once after the modal is in the DOM and initial focus is set.
+export function _trapFocusInModal(modal) {
+    const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    modal.addEventListener('keydown', (e) => {
+        if (e.key !== 'Tab') return;
+        const els = Array.from(modal.querySelectorAll(FOCUSABLE)).filter(el => {
+            if (!_isElementVisible(el)) return false;
+            if (getComputedStyle(el).visibility === 'hidden') return false;
+            if (el.disabled) return false;
+            return true;
+        });
+        if (!els.length) return;
+        const first = els[0];
+        const last = els[els.length - 1];
+        if (e.shiftKey) {
+            if (document.activeElement === first) { e.preventDefault(); last.focus(); }
+        } else {
+            if (document.activeElement === last) { e.preventDefault(); first.focus(); }
+        }
+    });
+}
+
+// Styled async confirm dialog. Returns a Promise<boolean>. For destructive
+// prompts pass `danger: true` — confirm button turns red and Cancel gets
+// initial focus so an accidental Enter won't fire the action. `body` is
+// inserted as HTML so callers can use formatting; callers are responsible
+// for escaping any user-supplied content in it (use _escAttr).
+export function _confirmDialog({ title, body = '', confirmText = 'Confirm', cancelText = 'Cancel', danger = false } = {}) {
+    return new Promise((resolve) => {
+        const previouslyFocused = document.activeElement;
+        const modal = document.createElement('div');
+        modal.className = 'feedBack-modal fixed inset-0 z-[250] flex items-center justify-center bg-black/70 backdrop-blur-sm';
+        modal.setAttribute('role', 'alertdialog');
+        modal.setAttribute('aria-modal', 'true');
+        modal.setAttribute('aria-label', title || 'Confirm');
+        const confirmClass = danger
+            ? 'flex-1 bg-red-600 hover:bg-red-500 px-4 py-2 rounded-xl text-sm font-semibold text-white transition focus:outline-none focus:ring-2 focus:ring-red-400/60'
+            : 'flex-1 bg-accent hover:bg-accent-light px-4 py-2 rounded-xl text-sm font-semibold text-white transition focus:outline-none focus:ring-2 focus:ring-accent/60';
+        modal.innerHTML = `
+            <div class="bg-dark-700 border border-gray-700 rounded-2xl p-6 w-full max-w-sm mx-4 shadow-2xl">
+                <h3 class="text-lg font-bold text-white mb-3">${_escAttr(title || '')}</h3>
+                <div class="mb-5">${body}</div>
+                <div class="flex gap-3">
+                    <button type="button" data-confirm class="${confirmClass}">${_escAttr(confirmText)}</button>
+                    <button type="button" data-cancel class="px-4 py-2 bg-dark-600 hover:bg-dark-500 rounded-xl text-sm text-gray-300 transition focus:outline-none focus:ring-2 focus:ring-gray-500/40">${_escAttr(cancelText)}</button>
+                </div>
+            </div>`;
+        document.body.appendChild(modal);
+
+        function finish(result) {
+            modal.remove();
+            document.removeEventListener('keydown', onKey, true);
+            if (previouslyFocused && document.body.contains(previouslyFocused)) {
+                try { previouslyFocused.focus({ preventScroll: true }); } catch {}
+            }
+            resolve(result);
+        }
+        function onKey(e) {
+            if (e.key === 'Escape') { e.preventDefault(); e.stopImmediatePropagation(); finish(false); }
+            else if (e.key === 'Enter' && document.activeElement === modal.querySelector('[data-confirm]')) {
+                e.preventDefault(); finish(true);
+            }
+        }
+        modal.addEventListener('click', (e) => {
+            if (e.target === modal) finish(false);
+            else if (e.target.closest('[data-confirm]')) finish(true);
+            else if (e.target.closest('[data-cancel]')) finish(false);
+        });
+        document.addEventListener('keydown', onKey, true);
+        _trapFocusInModal(modal);
+        // Focus Cancel by default for destructive prompts so an accidental
+        // Enter / Space won't fire the dangerous action; otherwise focus
+        // the confirm button so Enter accepts.
+        const focusTarget = modal.querySelector(danger ? '[data-cancel]' : '[data-confirm]');
+        if (focusTarget) focusTarget.focus({ preventScroll: true });
+    });
+}
+
+export function esc(s) {
+    const d = document.createElement('div');
+    d.textContent = s;
+    return d.innerHTML;
+}
+
+// `esc()` escapes the HTML-content metacharacters (<, >, &) but not
+// quotes — fine for text-node interpolation but unsafe when the
+// result is used as an attribute value, where a literal `"` ends the
+// attribute early. Use `_escAttr` for any `attr="${...}"` site.
+export function _escAttr(s) {
+    return esc(s == null ? '' : String(s))
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+// In-app text prompt — replaces window.prompt(), which Electron does NOT
+// implement (it logs "prompt() is and will not be supported" and returns null),
+// so any prompt()-based flow is a silent no-op on desktop. Returns the entered
+// string, or null if cancelled (Esc / Cancel / backdrop). Styled to match the
+// edit modal; role=dialog so the global keyboard shortcuts ignore typing here.
+// Injection-safe: all caller text is set via textContent / value, never innerHTML.
+export function uiPrompt({ title = '', label = '', value = '', okLabel = 'Save', placeholder = '' } = {}) {
+    return new Promise((resolve) => {
+        const modal = document.createElement('div');
+        modal.className = 'feedBack-modal fixed inset-0 z-[200] flex items-center justify-center bg-black/70 backdrop-blur-sm';
+        modal.setAttribute('role', 'dialog');
+        modal.setAttribute('aria-modal', 'true');
+        if (title) modal.setAttribute('aria-label', title);
+        modal.innerHTML = `
+            <form class="bg-dark-700 border border-gray-700 rounded-2xl p-6 w-full max-w-sm mx-4 shadow-2xl">
+                <h3 class="text-lg font-bold text-white mb-4" data-ui-prompt-title hidden></h3>
+                <label class="text-xs text-gray-400 mb-1 block" data-ui-prompt-label hidden></label>
+                <input type="text" data-ui-prompt-input autocomplete="off"
+                    class="w-full bg-dark-600 border border-gray-700 rounded-lg px-3 py-2 text-sm text-gray-200 outline-none focus:border-accent/50">
+                <div class="flex gap-3 mt-5">
+                    <button type="submit"
+                        class="flex-1 bg-accent hover:bg-accent-light px-4 py-2 rounded-xl text-sm font-semibold text-white transition" data-ui-prompt-ok></button>
+                    <button type="button" data-ui-prompt-cancel
+                        class="px-4 py-2 bg-dark-600 hover:bg-dark-500 rounded-xl text-sm text-gray-300 transition">Cancel</button>
+                </div>
+            </form>`;
+        const titleEl = modal.querySelector('[data-ui-prompt-title]');
+        const labelEl = modal.querySelector('[data-ui-prompt-label]');
+        const input = modal.querySelector('[data-ui-prompt-input]');
+        const okEl = modal.querySelector('[data-ui-prompt-ok]');
+        if (title) { titleEl.textContent = title; titleEl.hidden = false; }
+        if (label) { labelEl.textContent = label; labelEl.hidden = false; }
+        okEl.textContent = okLabel;
+        input.value = value;
+        if (placeholder) input.placeholder = placeholder;
+
+        // Restore focus to wherever it was when we're done (matches the edit
+        // modal's behavior so keyboard users aren't dumped at the page top).
+        const previousActiveElement = document.activeElement;
+        const focusables = () => Array.from(
+            modal.querySelectorAll('input, button, [tabindex]:not([tabindex="-1"])'),
+        ).filter((el) => !el.disabled && el.offsetParent !== null);
+
+        let settled = false;
+        const close = (result) => {
+            if (settled) return;
+            settled = true;
+            document.removeEventListener('keydown', onKey, true);
+            modal.remove();
+            if (previousActiveElement && typeof previousActiveElement.focus === 'function') {
+                previousActiveElement.focus();
+            }
+            resolve(result);
+        };
+        const onKey = (e) => {
+            if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); close(null); return; }
+            // Trap Tab inside the modal so focus can't wander to the page behind it.
+            if (e.key === 'Tab') {
+                const items = focusables();
+                if (!items.length) return;
+                const first = items[0];
+                const last = items[items.length - 1];
+                const active = document.activeElement;
+                if (e.shiftKey && (active === first || !modal.contains(active))) {
+                    e.preventDefault(); last.focus();
+                } else if (!e.shiftKey && (active === last || !modal.contains(active))) {
+                    e.preventDefault(); first.focus();
+                }
+            }
+        };
+        modal.querySelector('form').addEventListener('submit', (e) => { e.preventDefault(); close(input.value); });
+        modal.querySelector('[data-ui-prompt-cancel]').addEventListener('click', () => close(null));
+        // Backdrop (overlay itself, not the panel) cancels.
+        modal.addEventListener('mousedown', (e) => { if (e.target === modal) close(null); });
+        document.addEventListener('keydown', onKey, true);
+        document.body.appendChild(modal);
+        input.focus();
+        input.select();
+    });
+}

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

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'}).`
+        );
+    });
+}
+

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);

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\)/);
 });

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'/);
 });