refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a) (#871)

* refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a)

Deletes `static/index.html`, the `/v2` route, and the `FEEDBACK_UI` v2/legacy
opt-out. `/` and `/v3` both serve `static/v3/index.html`, which has been the
default since 0.3.0.

This is step 0 of the core-frontend ES-module migration (R3a). Both shells load
the same `static/app.js`, so every later step of that migration — exposing the
window contract, the `defer` ordering fix, the `type="module"` flips — would
otherwise have to be made and verified twice. Removing the fallback now halves
that surface before any of it is touched.

Incidentally fixes a latent bug in `index()`: its guard read
`if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy")`,
whose left operand is truthy for *any* non-empty value — so `FEEDBACK_UI=v3`
actually served the **v2** shell.

- `static/tailwind.min.css` regenerated: the content globs scanned the deleted
  file, so v2-only utility classes are now purged (CI's tailwind-fresh job
  rebuilds and diffs it).
- Constitution amended to 1.3.0 — Principle II's frontend file list now names
  `static/v3/index.html`.
- Tests: 4 suites read the v2 shell (3 via a constructed `path.join` that a
  literal grep misses). Their v2 halves are paired duplicates of v3 tests that
  stay, so they are dropped; `alpha_warning_banner` and the capability-registry
  script-order test retarget to `static/v3/index.html`.

BREAKING CHANGE: `FEEDBACK_UI=v2` / `=legacy` and the `/v2` route are gone.
Unset the variable and use `/`. No chart, settings, or plugin data changes, and
no plugin API changes — v3 reuses the same engine.

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

* docs: drop the stale '/ is v2' plugin-verification guidance (CodeRabbit)

The v3-only rewrite updated the intro paragraphs but left three lines that
still instructed plugin authors to verify in 'both / (v2) and /v3' — now the
same shell. Historical 'in v2 it was X' contrasts are kept: they still orient
authors whose plugins also ship to users on older cores.

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

---------

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

.specify/memory/constitution.md

@@ -34,7 +34,7 @@ but not the primary supported path.
 
 ### II. Vanilla Frontend — No Frameworks
 
-The frontend (`static/app.js`, `static/highway.js`, `static/index.html`,
+The frontend (`static/app.js`, `static/highway.js`, `static/v3/index.html`,
 `static/style.css`) is plain JavaScript with the `fetch` API, direct DOM
 manipulation, and the Canvas 2D / WebGL2 APIs. The only style framework
 is Tailwind CSS, served as a prebuilt static stylesheet
@@ -284,4 +284,4 @@ no `..`, no absolute paths).
   higher-numbered principle's escape hatch is to live in a plugin
   with its own bundled assets.
 
-**Version**: 1.2.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-08
+**Version**: 1.3.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-11

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+- **The classic v2 UI shell is gone — v3 is the only UI (R3a).** `static/index.html`, the
+  `/v2` route, and the `FEEDBACK_UI` v2/legacy opt-out are deleted; `/` and `/v3` both serve
+  `static/v3/index.html`, which has been the default since 0.3.0. This is the first step of
+  the core-frontend ES-module migration (R3a): both shells load the same `static/app.js`, so
+  every subsequent step of that migration would otherwise have to be made, and verified,
+  twice. Removing the fallback now halves that surface before any of it is touched.
+  Incidentally fixes a latent bug in the old `index()` route — its guard read
+  `if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy")`,
+  whose left operand is truthy for *any* non-empty value, so `FEEDBACK_UI=v3` actually served
+  the **v2** shell. `static/tailwind.min.css` is regenerated (the content globs scanned the
+  deleted file, so v2-only utility classes are now purged). Constitution amended to 1.3.0:
+  Principle II's frontend file list now names `static/v3/index.html`.
+  **Migration notes:** if you set `FEEDBACK_UI=v2` (or `=legacy`), or bookmarked `/v2`, there
+  is no longer a classic shell to fall back to — unset the variable and use `/`. The env var
+  itself is no longer read; the `SLOPSMITH_*`→`FEEDBACK_*` compat shim is unaffected. No
+  chart, settings, or plugin data changes, and no plugin API changes: v3 reuses the same
+  engine (`app.js`, `highway.js`, `playSong`, `showScreen`, the capability registry).
+
 ### Fixed
 - **The packaged desktop app could not start (`ModuleNotFoundError: No module named
   'appstate'`).** feedback-desktop's `scripts/bundle-slopsmith.sh` copies a *hardcoded

CLAUDE.md

@@ -125,13 +125,13 @@ Notes:
 
 ### v3 UI (fee[dB]ack v0.3.0) — player-chrome contract
 
-v0.3.0 ships a redesigned UI behind a flag (`FEEDBACK_UI=v3` or the `/v3` route);
+v0.3.0's redesigned UI is **the only UI** — the classic v2 shell and its
-the classic UI (v2) stays the default until 0.3.0 ships, so **plugins must work in
+`FEEDBACK_UI` / `/v2` opt-outs are gone, so there is no second shell to support.
-both**. v3 reuses the same engine (`server.py`, `app.js`, `highway.js`, `playSong`,
+v3 reuses the same engine (`server.py`, `app.js`, `highway.js`, `playSong`,
 `showScreen`, capabilities, library providers, the `window.feedBackViz_<id>` /
 `setRenderer` contract), so a plugin's **backend, capabilities, `nav`/`screen`,
 visualization renderers, diagnostics, and settings export work unchanged** — v3
-surfaces `nav` in its sidebar and mounts screens exactly as v2 does.
+surfaces `nav` in its sidebar and mounts screens as before.
 
 **The only thing that changed is the player chrome.** If your plugin injects a
 control into it, you must adapt:
@@ -157,7 +157,7 @@ control into it, you must adapt:
   popovers 40).
 
 Full guide + the canonical snippet: **[docs/plugin-v3-ui.md](docs/plugin-v3-ui.md)**.
-Verify any player-injecting plugin in **both** `/` (v2) and `/v3`.
+Verify any player-injecting plugin at `/` — it and `/v3` serve the same v3 shell.
 
 ### Performance — never run DOM queries on a per-frame path
 
@@ -566,7 +566,7 @@ a local pointer + code map.
 - **Storage** — `localStorage` for all user preferences
 - **Styling** — Tailwind CSS utility classes, dark theme (`bg-dark-600`, `text-gray-300`, accent `#4080e0`, gold `#e8c040`). Tailwind is served as a **prebuilt** stylesheet (`static/tailwind.min.css`, regenerated by `bash scripts/build-tailwind.sh`), **never** the runtime Play CDN — the CDN's on-the-fly JIT rescanned the DOM on the main thread and dropped ~26% of frames with the 3D highway (feedBack-desktop#110). The committed CSS only contains classes the build scanner saw, so CI (`tailwind-fresh`) rebuilds and diffs it; run the build script and commit when you add new classes. A plugin that uses classes not guaranteed in core (notably arbitrary values like `w-[37px]`) MUST ship its own compiled stylesheet via the `styles` manifest key, built with `corePlugins.preflight = false` (utilities only — core ships the one base reset). Plugins MUST NOT load the Tailwind Play CDN or any runtime CSS JIT. See constitution Principle II.
 - **Naming** — camelCase for JS functions, kebab-case for CSS classes, snake_case for plugin IDs
-- **Text selection (v3)** — the v3 UI defaults to `user-select: none` on `html` (in `static/v3/v3.css`) so accidental drag/double-click selection of chrome never looks broken. Form fields are always re-enabled, and a **plugin's mounted screen subtree (`.screen[id^="plugin-"]`) stays selectable by default**, so a plugin's copy-worthy text (lyrics, chord names, results, diagnostics) is unaffected — *unless your plugin renders copyable content OUTSIDE its `plugin-<id>` screen* (e.g. injected into the player chrome / a HUD overlay), which inherits the non-select default. Opt such content back in with the core-served **`.fb-selectable`** class (it sets `user-select: text` on the element + descendants; works for runtime-installed plugins since it's hand-authored in core CSS, not a scanned Tailwind utility). Never use a `* { user-select: none }` rule (breaks input carets/IME), and never use `user-select: none` to "lock" text — keep errors, IDs, paths, versions, and metadata selectable. (v2 is unchanged.)
+- **Text selection (v3)** — the v3 UI defaults to `user-select: none` on `html` (in `static/v3/v3.css`) so accidental drag/double-click selection of chrome never looks broken. Form fields are always re-enabled, and a **plugin's mounted screen subtree (`.screen[id^="plugin-"]`) stays selectable by default**, so a plugin's copy-worthy text (lyrics, chord names, results, diagnostics) is unaffected — *unless your plugin renders copyable content OUTSIDE its `plugin-<id>` screen* (e.g. injected into the player chrome / a HUD overlay), which inherits the non-select default. Opt such content back in with the core-served **`.fb-selectable`** class (it sets `user-select: text` on the element + descendants; works for runtime-installed plugins since it's hand-authored in core CSS, not a scanned Tailwind utility). Never use a `* { user-select: none }` rule (breaks input carets/IME), and never use `user-select: none` to "lock" text — keep errors, IDs, paths, versions, and metadata selectable.
 - **Player layout** — `#player` is `display:flex; flex-direction:column; position:fixed; inset:0`. `#highway` is `flex:1`. `#player-controls` sits at the bottom. Hiding the highway collapses the layout — use `margin-top: auto` on controls if you need to hide it.
 
 ## Backend Conventions

docs/plugin-styles.md

@@ -1,9 +1,9 @@
 # Plugin styling — the `styles` capability
 
-> Building for the redesigned **v3 UI** (`FEEDBACK_UI=v3` / `/v3`)? v3 uses `fb-*`
+> The **v3 UI** is the only UI — it uses `fb-*` design tokens and a restructured
-> design tokens and a restructured player chrome with a dedicated plugin-control
+> player chrome with a dedicated plugin-control slot. See
-> slot. See **[plugin-v3-ui.md](plugin-v3-ui.md)** for the player-chrome contract
+> **[plugin-v3-ui.md](plugin-v3-ui.md)** for the player-chrome contract plugins
-> plugins must follow in v3.
+> must follow.
 
 FeedBack serves Tailwind as a **prebuilt** stylesheet
 (`static/tailwind.min.css`), never the runtime Play CDN. The CDN's on-the-fly

docs/plugin-v3-ui.md

@@ -1,16 +1,16 @@
 # Building plugins for the v3 UI (fee[dB]ack v0.3.0)
 
-v0.3.0 ("fee[dB]ack") ships a redesigned UI **behind a flag** — `FEEDBACK_UI=v3`
+v0.3.0 ("fee[dB]ack") ships a redesigned UI. It is **the only UI** — the classic v2
-or the `/v3` route. The classic UI (v2) remains the default until 0.3.0 ships, so
+shell and its `FEEDBACK_UI` / `/v2` opt-outs have been removed, so there is no
-plugins must work in **both**.
+longer a second shell to support.
 
-The good news: v3 **reuses the same engine** as v2 — same `server.py`, `app.js`,
+The good news: v3 **reuses the same engine** the classic UI did — same `server.py`,
-`highway.js`, `playSong`, `showScreen`, capability registry, library providers,
+`app.js`, `highway.js`, `playSong`, `showScreen`, capability registry, library
-and the `window.feedBackViz_<id>` / `setRenderer` visualization contract. So your
+providers, and the `window.feedBackViz_<id>` / `setRenderer` visualization contract.
-plugin's **backend, capabilities, library providers, `nav`/`screen`, visualization
+So your plugin's **backend, capabilities, library providers, `nav`/`screen`,
-renderers, diagnostics, and settings export all work unchanged in v3.** v3 surfaces
+visualization renderers, diagnostics, and settings export all work unchanged.** v3
-your `nav` entry in the new sidebar (via `shell.js` `renderPluginNav`) and your
+surfaces your `nav` entry in the new sidebar (via `shell.js` `renderPluginNav`) and
-screen mounts exactly as before.
+your screen mounts exactly as before.
 
 **The one thing that changed is the player chrome** — and only if your plugin
 injects controls into it.
@@ -188,4 +188,4 @@ out of the capability graph.
 - [ ] Dropdowns positioned via `getBoundingClientRect()`, not `#player-controls`.
 - [ ] `#player` overlays keep `z-index` ≤ the chrome layers (transport/HUD 20,
       rail 30, popovers 40).
-- [ ] Verify in **both** `/` (v2) and `/v3`.
+- [ ] Verify at `/` — it and `/v3` serve the same (and only) v3 shell.

server.py

@@ -2391,24 +2391,10 @@ app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
 
 @app.get("/")
 def index():
-    # fee[dB]ack v0.3.0: the v3 shell is now the DEFAULT at `/`. The classic v2
-    # UI remains fully available as a fallback — opt back in with
-    # FEEDBACK_UI=v2 (or =legacy), or hit the dedicated /v2 route below (which
-    # serves it regardless of the env var).
-    if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy"):
-        return FileResponse(str(STATIC_DIR / "index.html"))
     return FileResponse(str(STATIC_DIR / "v3" / "index.html"))
 
 
 @app.get("/v3")
 def index_v3():
-    # Always serve the v0.3.0 shell, independent of the env var (kept for
+    # Retained as a back-compat alias for links minted while v3 was opt-in.
-    # explicit/back-compat links even though `/` now defaults to v3).
     return FileResponse(str(STATIC_DIR / "v3" / "index.html"))
-
-
-@app.get("/v2")
-def index_v2():
-    # Always serve the classic v2 UI, independent of the env var, so the
-    # fallback is reachable without flipping FEEDBACK_UI.
-    return FileResponse(str(STATIC_DIR / "index.html"))

static/app.js

@@ -9181,7 +9181,7 @@ function _ensureSectionPracticeDom() {
     ctrl.appendChild(bar);
     // Mount OUTSIDE #player-controls (in #player-footer, or as its sibling) so
     // the popover's chip <button>s can't be matched by a plugin injector that
-    // anchors on `#player-controls > button:last-of-type` (see static/index.html).
+    // anchors on `#player-controls > button:last-of-type` (see static/v3/index.html).
     _mountSectionPracticeControlSafe(ctrl);
     _placeSectionPracticeControlForChrome();
     return bar;

static/highway.js

@@ -282,7 +282,7 @@ function createHighway() {
     // it's only "full resolution" when Quality is HD; otherwise it pins at the
     // chosen Quality. Read once here; live changes come through
     // api.setMinRenderScale(), surfaced as the "Min res" control next to Quality
-    // in the player controls (static/index.html).
+    // in the player controls (static/v3/index.html).
     hwState._autoScaleMin = (function () {
         const v = parseFloat(localStorage.getItem('highwayMinRenderScale'));
         return Number.isFinite(v) ? Math.max(_AUTO_SCALE_MIN, Math.min(1, v)) : _AUTO_SCALE_MIN;

static/index.html

@@ -1,621 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" class="scroll-smooth">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>FeedBack</title>
-    <!-- Placeholder favicon — emoji SVG data URI. Swap for a real logo later. See #55. -->
-    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ctext y='14' font-size='14'%3E%F0%9F%8E%B8%3C/text%3E%3C/svg%3E">
-    <!-- Tailwind utility classes are served from a prebuilt static
-         stylesheet (regenerated by scripts/build-tailwind.sh). The old
-         Play CDN (cdn.tailwindcss.com) JIT scanned the DOM ~1.8x/sec
-         on the main thread, dropping ~26% of frames with the 3D
-         highway running — see feedBack-desktop#110. Theme extensions
-         (dark/accent/gold colors, Inter font) live in tailwind.config.js. -->
-    <link rel="stylesheet" href="/static/tailwind.min.css">
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
-    <link rel="stylesheet" href="/static/style.css">
-    <link rel="stylesheet" href="/static/vendor/shepherd.css">
-    <link rel="stylesheet" href="/static/tour-engine.css">
-    <!-- Diagnostics console capture must wrap console.* before any other
-         script logs anything; load it as early as possible. See
-         docs/diagnostics-bundle-spec.md (feedBack#166). -->
-    <script src="/static/diagnostics.js"></script>
-    <script src="/static/capabilities.js"></script>
-    <script src="/static/capabilities/library.js"></script>
-    <script src="/static/capabilities/tuning.js"></script>
-    <script src="/static/capabilities/working-tuning.js"></script>
-    <script src="/static/capabilities/audio-session.js"></script>
-    <script src="/static/capabilities/audio-effects.js"></script>
-    <script src="/static/capabilities/playback.js"></script>
-    <!-- fee[dB]ack v0.3.0: ui.library-card-injection capability (plugin card actions). -->
-    <script src="/static/capabilities/library-card-actions.js"></script>
-    <script src="/static/capabilities/visualization.js"></script>
-    <script src="/static/capabilities/note-detection.js"></script>
-    <script src="/static/capabilities/midi-input.js"></script>
-</head>
-<body class="bg-dark-900 text-gray-200 font-display">
-
-    <!-- Navigation -->
-    <nav id="navbar" class="fixed top-0 w-full z-50 transition-all duration-300">
-        <div class="max-w-7xl mx-auto px-6 h-16 flex items-center justify-between">
-            <div class="flex items-end gap-1.5">
-                <a href="#" onclick="showScreen('home');return false" class="text-xl font-bold bg-gradient-to-r from-accent-light to-purple-400 bg-clip-text text-transparent">
-                    FeedBack
-                </a>
-                <span id="app-version" class="text-xs text-gray-600 mb-0.5"></span>
-            </div>
-            <div class="hidden md:flex items-center gap-8">
-                <a href="#" onclick="showScreen('home');return false" class="text-sm text-gray-400 hover:text-white transition">Library</a>
-                <a href="#" onclick="showScreen('favorites');return false" class="text-sm text-gray-400 hover:text-white transition">Favorites</a>
-                <a href="#" onclick="document.getElementById('upload-songs-file').click();return false" class="text-sm text-gray-400 hover:text-white transition">Upload</a>
-                <span id="nav-plugins" class="contents"></span>
-                <a href="#" onclick="showScreen('settings');return false" class="text-sm text-gray-400 hover:text-white transition">Settings</a>
-            </div>
-            <!-- Mobile menu -->
-            <button onclick="document.getElementById('mobile-menu').classList.toggle('hidden')" class="md:hidden text-gray-400">
-                <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"/></svg>
-            </button>
-        </div>
-        <div id="mobile-menu" class="hidden md:hidden bg-dark-800/95 backdrop-blur border-t border-gray-800">
-            <div class="px-6 py-4 flex flex-col gap-3">
-                <a href="#" onclick="showScreen('home');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Library</a>
-                <a href="#" onclick="showScreen('favorites');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Favorites</a>
-                <a href="#" onclick="document.getElementById('upload-songs-file').click();this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Upload</a>
-                <span id="mobile-nav-plugins" class="flex flex-col gap-2 border-t border-b border-gray-800 py-2 my-1">
-                    <span class="text-xs text-gray-600 uppercase tracking-wider">Plugins</span>
-                </span>
-                <a href="#" onclick="showScreen('settings');this.parentElement.parentElement.classList.add('hidden');return false" class="text-gray-400 hover:text-white">Settings</a>
-            </div>
-        </div>
-    </nav>
-
-    <!-- Hidden file input shared by the navbar "Upload" link. Kept at body
-         level so it stays reachable regardless of which screen is active. -->
-    <input type="file" id="upload-songs-file" accept=".feedpak,.sloppak" multiple class="hidden" onchange="uploadSongs(this.files); this.value=''">
-
-    <!-- ══ HOME (Hero + Library) ══════════════════════════════════════════ -->
-    <div id="home" class="screen active">
-        <!-- Library -->
-        <section id="library-section" class="max-w-7xl mx-auto px-6 pt-24 pb-16">
-            <div id="alpha-warning-banner" class="hidden mb-6 px-4 py-3 bg-amber-900/30 border border-amber-500/30 rounded-xl flex items-start gap-3" role="status">
-                <span class="text-amber-400 text-lg leading-none mt-0.5" aria-hidden="true">⚠</span>
-                <div class="text-sm text-amber-100">
-                    <strong class="text-amber-300">Heads up — this is an alpha build.</strong>
-                    Some things may be broken or change without warning. If you hit a bug, please file an issue. Thanks for trying it out!
-                </div>
-            </div>
-            <div class="flex flex-col md:flex-row md:items-center justify-between gap-4 mb-10">
-                <div>
-                    <h2 id="lib-title" class="text-3xl font-bold text-white">Your Library</h2>
-                    <p class="text-gray-500 mt-1" id="lib-count"></p>
-                </div>
-                <div class="flex gap-3 w-full md:w-auto flex-wrap">
-                    <select id="lib-provider" onchange="setLibraryProvider(this.value)"
-                        aria-label="Library source"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none" title="Library source">
-                        <option value="local">My Library</option>
-                    </select>
-                    <!-- View toggle -->
-                    <div class="flex bg-dark-700 border border-gray-800 rounded-xl overflow-hidden">
-                        <button id="view-grid-btn" onclick="setLibView('grid')" class="px-3 py-2.5 text-sm transition" title="Grid view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="6" height="6" rx="1"/><rect x="9" y="1" width="6" height="6" rx="1"/><rect x="1" y="9" width="6" height="6" rx="1"/><rect x="9" y="9" width="6" height="6" rx="1"/></svg>
-                        </button>
-                        <button id="view-tree-btn" onclick="setLibView('tree')" class="px-3 py-2.5 text-sm transition" title="Artist/Album view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="14" height="3" rx="1"/><rect x="3" y="6" width="12" height="3" rx="1"/><rect x="3" y="11" width="12" height="3" rx="1"/></svg>
-                        </button>
-                            <button id="view-folder-btn" onclick="setLibView('folder')" class="px-3 py-2.5 text-sm transition" title="Folder view">
-                                <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg>
-                            </button>
-                    </div>
-                    <!-- Grid controls -->
-                    <select id="lib-sort" onchange="sortLibrary()"
-                        class="lib-nontree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                        <option value="artist">Artist A-Z</option>
-                        <option value="artist-desc">Artist Z-A</option>
-                        <option value="title">Title A-Z</option>
-                        <option value="title-desc">Title Z-A</option>
-                        <option value="recent">Recently Added</option>
-                        <option value="year-desc">Year (newest)</option>
-                        <option value="year">Year (oldest)</option>
-                        <option value="tuning">Tuning</option>
-                        <option value="difficulty">Difficulty (easiest first)</option>
-                        <option value="difficulty-desc">Difficulty (hardest first)</option>
-                    </select>
-                    <!-- Format filter (shared) -->
-                    <select id="lib-format" onchange="sortLibrary()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none" title="Filter by format">
-                        <option value="">All formats</option>
-                        <option value="sloppak">Feedpak</option>
-                        <option value="loose">Folder</option>
-                    </select>
-                    <!-- Tree controls -->
-                    <button onclick="toggleAllArtists(true)" class="lib-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Expand All</button>
-                    <button onclick="toggleAllArtists(false)" class="lib-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Collapse All</button>
-                    <!-- Filters drawer toggle (feedBack#129) -->
-                    <button onclick="toggleLibFilters()" id="btn-lib-filters"
-                        class="bg-dark-700 border border-gray-800 hover:border-accent/40 rounded-xl px-4 py-2.5 text-sm text-gray-300 transition flex items-center gap-2"
-                        title="Filter by parts, tuning, lyrics">
-                        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 4h18M6 12h12M10 20h4"/></svg>
-                        <span>Filters</span>
-                        <span id="lib-filters-count" class="hidden bg-accent/30 text-accent-light text-xs font-semibold rounded-full px-1.5 py-0.5 min-w-[1.25rem] text-center">0</span>
-                    </button>
-                    <!-- Shared -->
-                    <input type="text" id="lib-filter" placeholder="Search songs..." oninput="filterLibrary()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 focus:ring-1 focus:ring-accent/30 outline-none flex-1 md:w-60 transition">
-                </div>
-            </div>
-            <!-- Active-filter chip row (only visible when filters are set, feedBack#129) -->
-            <div id="lib-filter-chips" class="hidden flex flex-wrap gap-2 mb-5"></div>
-            <div id="lib-grid" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-5">
-                <!-- Cards populated by JS -->
-            </div>
-            <div id="lib-tree" class="space-y-2 hidden">
-                <!-- Tree populated by JS -->
-            </div>
-            <div id="lib-folder-tree" class="space-y-1 hidden">
-                <!-- Folder tree populated by JS when Folders source is active -->
-            </div>
-        </section>
-
-        <!-- ══ Filters drawer (feedBack#129/#69/#22) ═════════════════════ -->
-        <div id="lib-filter-overlay" class="fixed inset-0 bg-black/40 z-40 hidden"
-             onclick="toggleLibFilters(false)"></div>
-        <aside id="lib-filter-drawer"
-               class="fixed top-0 right-0 h-full w-full sm:w-96 bg-dark-800 border-l border-gray-800 z-50 transform translate-x-full transition-transform duration-200 overflow-y-auto">
-            <div class="p-6 space-y-6">
-                <div class="flex items-center justify-between">
-                    <h3 class="text-lg font-semibold text-white">Filters</h3>
-                    <button onclick="toggleLibFilters(false)" class="text-gray-500 hover:text-white" title="Close">
-                        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/></svg>
-                    </button>
-                </div>
-
-                <section>
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Arrangements</div>
-                    <p class="text-xs text-gray-600 mb-3">Click cycles: any → require → exclude</p>
-                    <div id="filter-arrangements" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section id="filter-stems-section">
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Stems <span class="text-gray-600 normal-case font-normal">(sloppak)</span></div>
-                    <p class="text-xs text-gray-600 mb-3">Click cycles: any → require → exclude</p>
-                    <div id="filter-stems" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section>
-                    <div class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">Lyrics</div>
-                    <div id="filter-lyrics" class="flex flex-wrap gap-2"></div>
-                </section>
-
-                <section>
-                    <details>
-                        <summary class="cursor-pointer flex items-center justify-between text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">
-                            <span>Tuning</span>
-                            <span id="filter-tunings-summary" class="text-gray-600 normal-case font-normal text-xs">All tunings</span>
-                        </summary>
-                        <div id="filter-tunings" class="mt-3 space-y-1 max-h-64 overflow-y-auto pr-1"></div>
-                    </details>
-                </section>
-
-                <div class="flex items-center justify-between pt-4 border-t border-gray-800">
-                    <button onclick="clearLibFilters()" class="text-sm text-gray-400 hover:text-white transition">Clear all</button>
-                    <button onclick="toggleLibFilters(false)" class="bg-accent hover:bg-accent-light px-4 py-2 rounded-lg text-sm font-medium text-white transition">Done</button>
-                </div>
-            </div>
-        </aside>
-    </div>
-
-    <!-- ══ FAVORITES ════════════════════════════════════════════════════ -->
-    <div id="favorites" class="screen">
-        <section class="max-w-7xl mx-auto px-6 pt-24 pb-16">
-            <div class="flex flex-col md:flex-row md:items-center justify-between gap-4 mb-10">
-                <div>
-                    <h2 class="text-3xl font-bold text-white">Favorites</h2>
-                    <p class="text-gray-500 mt-1" id="fav-count"></p>
-                </div>
-                <div class="flex gap-3 w-full md:w-auto flex-wrap">
-                    <div class="flex bg-dark-700 border border-gray-800 rounded-xl overflow-hidden">
-                        <button id="fav-view-grid-btn" onclick="setFavView('grid')" class="px-3 py-2.5 text-sm transition" title="Grid view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="6" height="6" rx="1"/><rect x="9" y="1" width="6" height="6" rx="1"/><rect x="1" y="9" width="6" height="6" rx="1"/><rect x="9" y="9" width="6" height="6" rx="1"/></svg>
-                        </button>
-                        <button id="fav-view-tree-btn" onclick="setFavView('tree')" class="px-3 py-2.5 text-sm transition" title="Artist/Album view">
-                            <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 16 16"><rect x="1" y="1" width="14" height="3" rx="1"/><rect x="3" y="6" width="12" height="3" rx="1"/><rect x="3" y="11" width="12" height="3" rx="1"/></svg>
-                        </button>
-                    </div>
-                    <select id="fav-sort" onchange="sortFavorites()"
-                        class="fav-grid-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                        <option value="artist">Artist A-Z</option>
-                        <option value="artist-desc">Artist Z-A</option>
-                        <option value="title">Title A-Z</option>
-                        <option value="title-desc">Title Z-A</option>
-                        <option value="recent">Recently Added</option>
-                        <option value="tuning">Tuning</option>
-                    </select>
-                    <button onclick="toggleAllFavoriteArtists(true)" class="fav-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Expand All</button>
-                    <button onclick="toggleAllFavoriteArtists(false)" class="fav-tree-ctrl bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-400 hover:text-white transition">Collapse All</button>
-                    <input type="text" id="fav-filter" placeholder="Search favorites..." oninput="filterFavorites()"
-                        class="bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 focus:ring-1 focus:ring-accent/30 outline-none flex-1 md:w-60 transition">
-                </div>
-            </div>
-            <div id="fav-grid" class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-5">
-            </div>
-            <div id="fav-tree" class="space-y-2 hidden">
-            </div>
-        </section>
-    </div>
-
-    <!-- ══ Plugin screens injected dynamically by loadPlugins() ══════════ -->
-
-    <!-- ══ SETTINGS ═══════════════════════════════════════════════════════ -->
-    <div id="settings" class="screen">
-        <div class="max-w-2xl mx-auto px-6 pt-24 pb-16">
-            <button onclick="showScreen('home')" class="text-gray-500 hover:text-white text-sm mb-6 flex items-center gap-1">
-                <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7"/></svg> Back
-            </button>
-            <h2 class="text-3xl font-bold text-white mb-8">Settings</h2>
-
-            <div class="space-y-10">
-                <!-- App Updates — Velopack auto-update, desktop only. Stays
-                     hidden in the plain web app; setupAppUpdates() unhides
-                     this block when window.feedBackDesktop.update exists,
-                     and shows a disabled "not available on Linux" fallback
-                     when running on Linux. -->
-                <div id="app-updates-block" class="hidden border border-gray-800 rounded-xl bg-dark-800/40 p-5">
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">App Updates</h3>
-                    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block" for="app-update-channel">Update channel</label>
-                            <select id="app-update-channel"
-                                class="w-full bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="stable">Stable</option>
-                                <option value="rc">Release candidate</option>
-                                <option value="beta">Beta</option>
-                                <option value="alpha">Alpha</option>
-                            </select>
-                        </div>
-                        <div class="flex items-end">
-                            <button id="app-update-check-now"
-                                class="bg-accent hover:bg-accent-light px-4 py-2.5 rounded-xl text-sm font-medium text-white transition disabled:opacity-50">
-                                Check for updates
-                            </button>
-                        </div>
-                    </div>
-                    <p id="app-update-status" class="text-xs text-gray-500 mt-3">Loading updater status…</p>
-                    <p id="app-update-linux-note" class="hidden text-xs text-yellow-300 mt-2">
-                        Auto-update is not available on Linux —
-                        <a href="https://github.com/got-feedback/feedBack-desktop/releases" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">download new versions from GitHub Releases</a>.
-                    </p>
-                </div>
-
-                <!-- ── Core FeedBack settings ─────────────────────────────── -->
-                <section>
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">FeedBack</h3>
-                    <div class="space-y-6">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Library Folder Path</label>
-                            <div class="flex gap-3">
-                                <input type="text" id="dlc-path" placeholder="/path/to/your/library"
-                                    class="flex-1 bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 outline-none">
-                                <button onclick="pickDlcFolder()" id="btn-pick-dlc" class="hidden bg-dark-600 hover:bg-dark-500 px-4 py-2.5 rounded-xl text-sm text-gray-300 transition whitespace-nowrap">📂 Browse</button>
-                                <button onclick="saveSettings()" class="bg-accent hover:bg-accent-light px-6 py-2.5 rounded-xl text-sm font-semibold text-white transition">Save</button>
-                            </div>
-                        </div>
-                        <div>
-                            <label class="flex items-center gap-3 cursor-pointer select-none">
-                                <input type="checkbox" id="setting-lefty" onchange="highway.setLefty(this.checked)"
-                                    class="rounded border-gray-600 bg-dark-700 text-accent focus:ring-accent/40">
-                                <span class="text-sm text-gray-300">Left-handed <span class="text-gray-500">(invert frets on the note highway)</span></span>
-                            </label>
-                        </div>
-                        <div>
-                            <label class="flex items-center gap-3 cursor-pointer select-none">
-                                <input type="checkbox" id="setting-autoplay-exit" checked onchange="setAutoplayExit(this.checked)"
-                                    class="rounded border-gray-600 bg-dark-700 text-accent focus:ring-accent/40">
-                                <span class="text-sm text-gray-300">Autoplay &amp; auto-exit <span class="text-gray-500">(start songs/lessons automatically and return to the menu when the score screen closes)</span></span>
-                            </label>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Default Arrangement</label>
-                            <select id="default-arrangement"
-                                onchange="persistSetting('default_arrangement', this.value)"
-                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="">Most notes (auto)</option>
-                                <option value="Lead">Lead</option>
-                                <option value="Rhythm">Rhythm</option>
-                                <option value="Bass">Bass</option>
-                            </select>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Arrangement Names</label>
-                            <select id="arrangement-naming-mode"
-                                onchange="_onNamingModeChange(this.value)"
-                                class="bg-dark-700 border border-gray-800 rounded-xl px-3 py-2.5 text-sm text-gray-300 outline-none">
-                                <option value="smart">Smart (Lead, Alt. Lead, Rhythm, Bass…)</option>
-                                <option value="legacy">Legacy (Combo, Bass)</option>
-                            </select>
-                        </div>
-                        <div>
-                            <label for="setting-av-offset" class="text-sm font-medium text-gray-400 mb-2 block">
-                                A/V Sync Offset: <span id="setting-av-offset-val">0</span> ms
-                            </label>
-                            <input type="range" id="setting-av-offset" min="-1000" max="1000" step="1" value="0"
-                                oninput="setAvOffsetMs(this.value)"
-                                class="w-full slider-input">
-                            <p class="text-xs text-gray-600 mt-1">Positive = audio plays ahead of visual notes; raise this value to catch the highway up. Adjust live with the [ and ] keys (Shift for ±50 ms). Auto-saves on every change.</p>
-                        </div>
-                        <div>
-                            <label for="demucs-server-url" class="text-sm font-medium text-gray-400 mb-2 block">Demucs Server (for stem separation)</label>
-                            <div class="flex gap-3">
-                                <input type="text" id="demucs-server-url" placeholder="http://192.168.1.100:7865"
-                                    class="flex-1 bg-dark-700 border border-gray-800 rounded-xl px-4 py-2.5 text-sm text-gray-300 placeholder-gray-600 focus:border-accent/50 outline-none">
-                                <button onclick="saveSettings()" class="bg-accent hover:bg-accent-light px-6 py-2.5 rounded-xl text-sm font-semibold text-white transition">Save</button>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Optional. Run <a href="https://github.com/got-feedBack/feedBack-demucs-server" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">feedBack-demucs-server</a> on a machine with a GPU to offload stem splitting and avoid resource exhaustion on the host running FeedBack.</p>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Library</label>
-                            <div class="flex items-center gap-3">
-                                <button onclick="rescanLibrary()" id="btn-rescan" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Rescan Library</button>
-                                <button onclick="fullRescanLibrary()" id="btn-full-rescan" class="bg-dark-600 hover:bg-red-900/30 px-5 py-2.5 rounded-xl text-sm text-gray-400 transition">Full Rescan</button>
-                                <span id="rescan-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Rescan checks for new songs. Full Rescan clears the cache and re-imports everything.</p>
-                        </div>
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Backup</label>
-                            <div class="flex items-center gap-3">
-                                <button onclick="exportSettings()" id="btn-export-settings" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Export Settings</button>
-                                <button onclick="document.getElementById('import-settings-file').click()" id="btn-import-settings" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Import Settings</button>
-                                <input type="file" id="import-settings-file" accept="application/json,.json" class="hidden" onchange="importSettings(this.files[0]); this.value=''">
-                                <span id="backup-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Export bundles server config, browser preferences, and opted-in plugin data into one JSON file. Import overwrites current settings and reloads.</p>
-                        </div>
-                        <!-- ── Diagnostics (feedBack#166) ────────────────────── -->
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Diagnostics</label>
-                            <div class="grid grid-cols-2 gap-2 mb-3 text-xs text-gray-400">
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-system" checked class="rounded border-gray-600 bg-dark-700 text-accent"> System info</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-hardware" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Hardware (CPU/GPU/RAM)</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-logs" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Server logs (last 5 MB)</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-console" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Browser console + errors</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-incl-plugins" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Plugin diagnostics</label>
-                                <label class="flex items-center gap-2"><input type="checkbox" id="diag-redact" checked class="rounded border-gray-600 bg-dark-700 text-accent"> Redact paths &amp; song names</label>
-                            </div>
-                            <div class="flex items-center gap-3">
-                                <button onclick="previewDiagnostics()" id="btn-diag-preview" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Preview Bundle</button>
-                                <button onclick="exportDiagnostics()" id="btn-diag-export" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Export Diagnostics</button>
-                                <span id="diag-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <p class="text-xs text-gray-600 mt-1">Bundles server logs, hardware info, plugin inventory, and the browser console transcript into one zip for bug reports. Redaction strips DLC paths, song filenames, and IP addresses by default. Attach to GitHub issues; AI agents can parse the included <code>manifest.json</code>.</p>
-                            <div id="diag-preview" class="hidden mt-3 bg-dark-700 border border-gray-800 rounded-xl p-3 text-xs text-gray-400 max-h-96 overflow-auto"></div>
-                        </div>
-                        <div id="settings-status" class="text-sm text-gray-500"></div>
-                    </div>
-                </section>
-
-                <!-- ── Plugin settings ─────────────────────────────────────── -->
-                <section id="plugin-settings-area" class="hidden">
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">Plugins</h3>
-                    <div class="space-y-6">
-                        <div>
-                            <label class="text-sm font-medium text-gray-400 mb-2 block">Plugin Updates</label>
-                            <div class="flex items-center gap-3 mb-2">
-                                <button onclick="checkPluginUpdates()" id="btn-check-updates" class="bg-dark-600 hover:bg-dark-500 px-5 py-2.5 rounded-xl text-sm text-gray-300 transition">Check for Updates</button>
-                                <span id="updates-status" class="text-xs text-gray-500"></span>
-                            </div>
-                            <div id="plugin-updates-list" class="space-y-2"></div>
-                        </div>
-                        <!-- Per-plugin collapsible sections injected here -->
-                        <div id="plugin-settings" class="space-y-3"></div>
-                    </div>
-                </section>
-
-                <!-- ── About / Source / License (AGPL §13 disclosure) ──────── -->
-                <section>
-                    <h3 class="text-xs font-semibold uppercase tracking-wider text-gray-500 mb-4">About</h3>
-                    <div class="space-y-2 text-sm text-gray-400">
-                        <div>FeedBack <span id="app-version-about" class="text-gray-500"></span></div>
-                        <div>Licensed under <a id="about-license-link" href="https://github.com/got-feedback/feedBack/blob/main/LICENSE" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">GNU AGPL v3.0</a>.</div>
-                        <div><a id="about-source-link" href="https://github.com/got-feedback/feedBack" target="_blank" rel="noopener" class="text-accent hover:text-accent-light underline">Source code repository</a></div>
-                        <p class="text-xs text-gray-600 mt-2">FeedBack is free software. You can redistribute it and modify it under the terms of the AGPL. If you run a modified version that interacts with users over a network, you must make the modified source available to those users.</p>
-                    </div>
-                </section>
-            </div>
-        </div>
-    </div>
-
-    <!-- Global audio element (outside player so it's always accessible) -->
-    <audio id="audio" preload="auto"></audio>
-    <script>
-    // Web Audio API fallback for iOS WKWebView which can't play WAV via <audio>
-    (function() {
-        var _waCtx = null, _waSource = null, _waStartTime = 0, _waBuffer = null, _waPlaying = false, _waLoading = false;
-        var audioEl = document.getElementById('audio');
-
-        window._webAudioFallback = {
-            load: function(url, cb) {
-                if (!url || _waLoading) return;
-                _waLoading = true;
-                if (!_waCtx) _waCtx = new (window.AudioContext || window.webkitAudioContext)();
-                console.log('[WebAudio] Loading: ' + url);
-                var xhr = new XMLHttpRequest();
-                xhr.open('GET', url, true);
-                xhr.responseType = 'arraybuffer';
-                xhr.onload = function() {
-                    _waCtx.decodeAudioData(xhr.response, function(decoded) {
-                        _waBuffer = decoded;
-                        _waLoading = false;
-                        console.log('[WebAudio] Decoded: ' + decoded.duration.toFixed(1) + 's');
-                        if (cb) cb();
-                    }, function(e) {
-                        _waLoading = false;
-                        console.error('[WebAudio] Decode error:', e);
-                    });
-                };
-                xhr.onerror = function() { _waLoading = false; };
-                xhr.send();
-            },
-            play: function() {
-                if (!_waBuffer || !_waCtx) return false;
-                this.stop();
-                if (_waCtx.state === 'suspended') _waCtx.resume();
-                _waSource = _waCtx.createBufferSource();
-                _waSource.buffer = _waBuffer;
-                // AudioBufferSourceNode has no preservesPitch equivalent so changing playbackRate here also changes pitch
-                _waSource.playbackRate.value = audioEl.playbackRate || 1;
-                _waSource.connect(_waCtx.destination);
-                _waStartTime = _waCtx.currentTime;
-                _waSource.start(0);
-                _waPlaying = true;
-                console.log('[WebAudio] Playing');
-                return true;
-            },
-            stop: function() {
-                if (_waSource) { try { _waSource.stop(); } catch(e){} _waSource = null; }
-                _waPlaying = false;
-            },
-            getTime: function() {
-                if (!_waPlaying || !_waCtx) return 0;
-                return _waCtx.currentTime - _waStartTime;
-            },
-            isActive: function() { return _waPlaying; },
-            isReady: function() { return !!_waBuffer; },
-            getDuration: function() { return _waBuffer ? _waBuffer.duration : 0; }
-        };
-    })();
-    </script>
-
-    <!-- ══ PLAYER ═════════════════════════════════════════════════════════ -->
-    <div id="player" class="screen">
-        <canvas id="highway"></canvas>
-        <div id="player-hud" class="absolute top-0 left-0 right-0 flex justify-between px-4 py-3 pointer-events-none z-10">
-            <div class="text-sm">
-                <span id="hud-artist" class="text-gray-300"></span> — <span id="hud-title" class="text-white font-semibold"></span>
-                <br><span id="hud-arrangement" class="text-gray-500 text-xs"></span>
-                <br><span id="hud-tuning" class="text-gray-500 text-xs"></span>
-                <br><span id="hud-tuning-targets" class="text-gray-500 text-xs"></span>
-            </div>
-            <div class="text-right">
-                <div id="hud-time" class="text-sm text-gray-400"></div>
-                <div id="hud-avoffset" class="text-xs text-gray-500 tabular-nums hidden" title="A/V offset — [ and ] to adjust, Shift for ±50 ms">A/V 0 ms</div>
-            </div>
-        </div>
-        <!-- #section-practice-bar lives OUTSIDE #player-controls on purpose: its
-             nested chip <button>s would otherwise be matched by plugins' legacy
-             `#player-controls`-scoped `button:last-child` injector anchor, making
-             insertBefore throw (the node isn't a direct child) and aborting the
-             shared playSong wrapper chain. The #player-footer wrapper keeps it
-             visually directly above the transport row; margin-top:auto moves here
-             from #player-controls so the whole footer still pins to the bottom. -->
-        <div id="player-footer">
-        <!-- Section Practice is collapsed behind a single pill; the multi-row bar
-             is a popover opened from the pill (toggleSectionPracticePopover). The
-             pill + popover live in #player-footer (NOT #player-controls) so the
-             popover's nested chip <button>s can't be matched by a plugin's
-             `#player-controls > button:last-child` injector anchor. -->
-        <div id="section-practice-control" class="section-practice-control section-practice-control--hidden">
-            <button type="button" id="section-practice-pill" class="section-practice-pill"
-                    aria-haspopup="dialog" aria-expanded="false" aria-controls="section-practice-bar"
-                    aria-label="Section practice"
-                    onclick="toggleSectionPracticePopover()" title="Section practice">
-                <span class="section-practice-pill-icon" aria-hidden="true">🎯</span>
-                <span class="section-practice-pill-text">Practice</span>
-                <span class="section-practice-pill-caret" aria-hidden="true">▾</span>
-            </button>
-            <div id="section-practice-bar" class="section-practice-bar" role="dialog" aria-label="Section practice">
-                <div class="section-practice-row">
-                    <label class="section-practice-mode-wrap" title="Loop the selected section until turned off">
-                        <input type="checkbox" id="section-practice-mode" onchange="onSectionPracticeModeChange()">
-                        <span class="section-practice-mode-text">Practice Section</span>
-                    </label>
-                    <span class="section-practice-label">Sections:</span>
-                    <div id="section-practice-scroll" class="section-practice-scroll" role="toolbar" aria-label="Section selection"></div>
-                </div>
-            </div>
-        </div>
-        <div id="player-controls" class="flex items-center gap-2 px-4 py-2.5 bg-dark-800 border-t border-gray-800/50 flex-wrap">
-            <button onclick="seekBy(-5)" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Seek Back 5s" aria-label="Seek Back 5s"><img src="/static/svg/rw.svg" class="button-icon-svg" alt="" aria-hidden="true" /> 5s</button>
-            <button type="button" onclick="restartCurrentSong()" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Restart song" aria-label="Restart song">↺</button>
-            <button onclick="togglePlay()" id="btn-play" class="px-4 py-1.5 bg-accent hover:bg-accent-light rounded-lg text-xs font-semibold text-white transition" aria-label="Play" title="Play" aria-pressed="false"><img src="/static/svg/play.svg" class="button-icon-svg" alt="" aria-hidden="true" /></button>
-            <button onclick="seekBy(5)" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Seek Forward 5s" aria-label="Seek Forward 5s">5s <img src="/static/svg/ff.svg" class="button-icon-svg" alt="" aria-hidden="true" /></button>
-            <select id="arr-select" onchange="changeArrangement(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none max-w-[130px]"></select>
-            <button id="arr-default-pin" type="button" onclick="pinCurrentArrangementDefault()" aria-pressed="false" aria-label="Select an arrangement to make it the default" class="w-8 h-8 inline-flex items-center justify-center bg-dark-600 border border-gray-700 hover:bg-dark-500 rounded-lg text-xs text-gray-400 transition" title="Select an arrangement to make it the default">☆</button>
-            <input type="range" id="speed-slider" min="15" max="150" value="100" step="5" oninput="setSpeed(this.value/100)" class="w-20 accent-accent slider-input">
-            <span id="speed-label" class="text-xs text-gray-500 w-10">1.0x</span>
-            <span id="mastery-slider-label" class="text-xs text-gray-500 ml-1">Difficulty</span>
-            <input type="range" id="mastery-slider" min="0" max="100" value="100" step="5" oninput="setMastery(this.value)" class="w-20 accent-accent slider-input" title="Master difficulty — low = simpler chart, high = full" aria-labelledby="mastery-slider-label">
-            <span id="mastery-label" class="text-xs text-gray-500 w-10">100%</span>
-            <span id="player-av-offset-slider-label" class="text-xs text-gray-500 ml-1">A/V sync offset (ms)</span>
-            <input type="range" id="player-av-offset-slider" min="-1000" max="1000" value="0" step="1" oninput="setAvOffsetMs(this.value)" class="w-20 accent-accent slider-input" title="A/V sync offset (ms) — positive = audio plays ahead of visuals. [ and ] adjust ±10 ms (Shift = ±50). Double-click to reset." ondblclick="setAvOffsetMs(0)" aria-labelledby="player-av-offset-slider-label">
-            <span id="player-av-offset-label" class="text-xs text-gray-500 w-12 tabular-nums">+0ms</span>
-            <div id="mixer-control">
-                <div id="mixer-anchor" class="relative">
-                    <button id="btn-mixer" type="button" onclick="window.feedBack.audio.toggleMixer()" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" aria-haspopup="true" aria-expanded="false" aria-controls="mixer-popover" title="Audio mixer">Mixer ▾</button>
-                    <div id="mixer-popover" class="hidden absolute right-0 bottom-full mb-2 z-50 bg-dark-700 border border-gray-800 rounded-xl shadow-xl" role="group" aria-label="Audio mixer"></div>
-                </div>
-            </div>
-            <button onclick="highway.toggleLyrics()" id="btn-lyrics" class="px-3 py-1.5 bg-purple-900/40 hover:bg-purple-900/60 rounded-lg text-xs text-purple-300 transition">Lyrics ✓</button>
-            <select id="quality-select" onchange="highway.setRenderScale(parseFloat(this.value))" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none">
-                <option value="1">HD</option>
-                <option value="0.75">Medium</option>
-                <option value="0.5">Low</option>
-            </select>
-            <select id="min-scale-select" aria-label="Minimum auto resolution" onchange="highway.setMinRenderScale && highway.setMinRenderScale(parseFloat(this.value))" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none" 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">Min res: 25%</option>
-                <option value="0.5">Min res: 50%</option>
-                <option value="0.75">Min res: 75%</option>
-                <option value="1">Min res: Full</option>
-            </select>
-            <span id="viz-picker-label" class="text-xs text-gray-500 ml-1 sr-only">Visualization</span>
-            <select id="viz-picker" onchange="setViz(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none" aria-labelledby="viz-picker-label" title="Visualization">
-                <option value="auto">Auto (match arrangement)</option>
-                <option value="default">Classic 2D Highway</option>
-                <!-- Additional entries populated on load from /api/plugins (feedBack#36).
-                     The bundled 3D Highway plugin (plugins/highway_3d/) registers as
-                     `highway_3d` and is the default selection on fresh installs — see
-                     _populateVizPicker() in app.js. -->
-            </select>
-            <span class="text-gray-700 mx-1">|</span>
-            <button onclick="setLoopStart()" id="btn-loop-a" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Set loop start at current time">A</button>
-            <button onclick="setLoopEnd()" id="btn-loop-b" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition" title="Set loop end at current time">B</button>
-            <button onclick="saveCurrentLoop()" id="btn-loop-save" class="px-3 py-1.5 bg-dark-600 hover:bg-green-900/50 rounded-lg text-xs text-gray-300 transition hidden" title="Save this loop">Save</button>
-            <button onclick="clearLoop()" id="btn-loop-clear" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-500 transition hidden" title="Clear loop">✕</button>
-            <span id="loop-label" class="text-xs text-gray-600"></span>
-            <select id="saved-loops" onchange="loadSavedLoop(this.value)" class="bg-dark-600 border border-gray-700 rounded-lg px-2 py-1.5 text-xs text-gray-300 outline-none max-w-[160px] hidden">
-                <option value="">Saved Loops</option>
-            </select>
-            <button onclick="deleteSelectedLoop()" id="btn-loop-delete" class="px-2 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-500 hover:text-red-400 transition hidden" title="Delete selected loop">✕</button>
-            <!-- Editor ⇄ 3D Highway round-trip. "Edit region" opens the Song Editor
-                 scrolled to the active loop (or the section at the playhead).
-                 "↩ Editor" returns to the editing position you came from; it only
-                 appears after a Loop-in-3D handoff. Both are hidden when the editor
-                 plugin isn't loaded (state managed by _updateEditRegionBtn). -->
-            <button onclick="editRegionInEditor()" id="btn-edit-region" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Edit this region in the Song Editor">✎ Edit region</button>
-            <button onclick="returnToEditorFromHighway()" id="btn-return-editor" class="px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition hidden" title="Return to the editor where you left off">↩ Editor</button>
-            <button onclick="showScreen('home')" class="ml-auto px-3 py-1.5 bg-dark-600 hover:bg-red-900/50 rounded-lg text-xs text-gray-400 hover:text-red-400 transition">✕ Close</button>
-        </div>
-        </div>
-    </div>
-
-    <script src="/static/highway.js"></script>
-    <script src="/static/vendor/lottie.min.js"></script>
-    <script src="/static/lottie-api.js"></script>
-    <script src="/static/app.js"></script>
-    <script src="/static/audio-mixer.js"></script>
-    <script src="/static/vendor/shepherd.min.js"></script>
-    <script src="/static/tour-engine.js"></script>
-    <script>
-        // Navbar scroll effect
-        window.addEventListener('scroll', () => {
-            const nav = document.getElementById('navbar');
-            if (window.scrollY > 50) {
-                nav.classList.add('bg-dark-900/80', 'backdrop-blur-lg', 'border-b', 'border-gray-800/50');
-            } else {
-                nav.classList.remove('bg-dark-900/80', 'backdrop-blur-lg', 'border-b', 'border-gray-800/50');
-            }
-        });
-    </script>
-</body>
-</html>

static/v3/index.html

@@ -1,14 +1,15 @@
 <!DOCTYPE html>
 <!--
-  fee[dB]ack v0.3.0 shell (FEEDBACK_UI=v3 / GET /v3).
+  fee[dB]ack v0.3.0 shell — the app's only UI, served at `/` (and `/v3`, a
+  back-compat alias). The classic v2 shell it was forked from is deleted.
 
-  This is a re-chromed copy of the legacy static/index.html: the v0.3.0
+  Originally a re-chromed copy of that shell: the v0.3.0 sidebar + topbar
-  sidebar + topbar replace the (hidden) legacy navbar, new #v3-* screens are
+  replace the (hidden) legacy navbar, new #v3-* screens are added, and all the
-  added, and all the legacy screens (#home library, #favorites, #settings,
+  legacy screens (#home library, #favorites, #settings, #player, #audio, plugin
-  #player, #audio, plugin nav containers) are kept verbatim so static/app.js
+  nav containers) are kept verbatim so static/app.js boots UNMODIFIED and the
-  boots UNMODIFIED and the whole engine — player/highway, plugin loader,
+  whole engine — player/highway, plugin loader, capabilities, audio, library,
-  capabilities, audio, library, settings — is reused as-is. Navigation is the
+  settings — is reused as-is. Navigation is the shared window.showScreen across
-  shared window.showScreen across both #v3-* and legacy/#plugin-* screens.
+  both #v3-* and legacy/#plugin-* screens.
   See ~/Repositories/feedBack-feedback-v030/prompts/12-app-shell.md.
 -->
 <html lang="en" class="dark scroll-smooth">

tailwind.config.js

@@ -13,9 +13,9 @@
 module.exports = {
     content: [
         './static/**/*.{html,js}',
-        // fee[dB]ack v0.3.0 shell + screens (additive, behind FEEDBACK_UI=v3).
+        // fee[dB]ack v0.3.0 shell + screens — the only UI since the classic v2
-        // Subsumed by the recursive ./static/** glob above, but listed
+        // shell was removed. Subsumed by the recursive ./static/** glob above,
-        // explicitly so the v3 tree's Tailwind coverage is obvious.
+        // but listed explicitly so the v3 tree's Tailwind coverage is obvious.
         './static/v3/**/*.{html,js}',
         // One recursive plugin glob subsumes the previous four narrow ones
         // (static/**, screen.js, settings.html, *.html) and additionally

tests/js/alpha_warning_banner.test.js

@@ -1,5 +1,5 @@
 // Verify the alpha-build heads-up banner: markup is present in
-// static/index.html and `_updateAlphaWarningBanner(version)` in
+// static/v3/index.html and `_updateAlphaWarningBanner(version)` in
 // static/app.js toggles its visibility correctly per the version string.
 
 const { test } = require('node:test');
@@ -8,7 +8,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const vm = require('node:vm');
 
-const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
+const INDEX_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 
 test('index.html ships the alpha-warning banner inside the library section', () => {

tests/js/song_restart.test.js

@@ -14,7 +14,6 @@ const { extractFunction } = require('./test_utils');
 
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
-const V2_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
 
 function buildSandbox({ loopA = null, loopB = null, isPlaying = false } = {}) {
     const sandbox = {
@@ -138,10 +137,3 @@ test('V3 transport restart button exists with correct attributes', () => {
     assert.match(html, /title="Restart song"/);
     assert.match(html, /aria-label="Restart song"/);
 });
-
-test('V2 transport restart button exists with correct attributes', () => {
-    const html = fs.readFileSync(V2_HTML, 'utf8');
-    assert.match(html, /#player-controls|player-controls[\s\S]*onclick="restartCurrentSong\(\)"/);
-    assert.match(html, /title="Restart song"/);
-    assert.match(html, /aria-label="Restart song"/);
-});

tests/js/tuning_display.test.js

@@ -9,7 +9,6 @@ const vm = require('node:vm');
 const APP_JS = path.join(__dirname, '..', '..', 'static', 'app.js');
 const HIGHWAY_JS = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
-const V2_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
 
 function extractBlock(src, startMarker) {
     const start = src.indexOf(startMarker);
@@ -97,11 +96,6 @@ test('V3 index.html defines hud-tuning', () => {
     assert.match(html, /id="hud-tuning"/);
 });
 
-test('V2 index.html defines hud-tuning', () => {
-    const html = fs.readFileSync(V2_HTML, 'utf8');
-    assert.match(html, /id="hud-tuning"/);
-});
-
 test('highway.js updates hud-tuning from song_info tuning offsets', () => {
     const src = fs.readFileSync(HIGHWAY_JS, 'utf8');
     assert.match(src, /getElementById\('hud-tuning'\)/);

tests/js/tuning_targets.test.js

@@ -11,7 +11,6 @@ const HIGHWAY_JS = path.join(__dirname, '..', '..', 'static', 'highway.js');
 const TUNER_UI_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'utils', 'ui.js');
 const TUNER_SCREEN_JS = path.join(__dirname, '..', '..', 'plugins', 'tuner', 'screen.js');
 const V3_HTML = path.join(__dirname, '..', '..', 'static', 'v3', 'index.html');
-const V2_HTML = path.join(__dirname, '..', '..', 'static', 'index.html');
 
 function loadTuningHelpers() {
     const src = fs.readFileSync(APP_JS, 'utf8');

tests/test_env_compat.py

@@ -4,22 +4,22 @@ from env_compat import getenv_compat, env_flag_compat
 
 
 def test_canonical_wins_over_legacy(monkeypatch):
-    monkeypatch.setenv("FEEDBACK_UI", "v3")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "canonical")
-    monkeypatch.setenv("SLOPSMITH_UI", "v2")
+    monkeypatch.setenv("SLOPSMITH_DEMO_MODE", "legacy")
-    assert getenv_compat("FEEDBACK_UI") == "v3"
+    assert getenv_compat("FEEDBACK_DEMO_MODE") == "canonical"
 
 
 def test_legacy_fallback_when_canonical_unset(monkeypatch):
-    monkeypatch.delenv("FEEDBACK_UI", raising=False)
+    monkeypatch.delenv("FEEDBACK_DEMO_MODE", raising=False)
-    monkeypatch.setenv("SLOPSMITH_UI", "v2")
+    monkeypatch.setenv("SLOPSMITH_DEMO_MODE", "legacy")
-    assert getenv_compat("FEEDBACK_UI") == "v2"
+    assert getenv_compat("FEEDBACK_DEMO_MODE") == "legacy"
 
 
 def test_default_when_neither_set(monkeypatch):
-    monkeypatch.delenv("FEEDBACK_UI", raising=False)
+    monkeypatch.delenv("FEEDBACK_DEMO_MODE", raising=False)
-    monkeypatch.delenv("SLOPSMITH_UI", raising=False)
+    monkeypatch.delenv("SLOPSMITH_DEMO_MODE", raising=False)
-    assert getenv_compat("FEEDBACK_UI", "default") == "default"
+    assert getenv_compat("FEEDBACK_DEMO_MODE", "default") == "default"
-    assert getenv_compat("FEEDBACK_UI") is None
+    assert getenv_compat("FEEDBACK_DEMO_MODE") is None
 
 
 def test_non_feedback_names_have_no_fallback(monkeypatch):
@@ -31,9 +31,9 @@ def test_non_feedback_names_have_no_fallback(monkeypatch):
 
 def test_empty_canonical_is_respected_not_overridden(monkeypatch):
     # An explicitly-empty canonical value is still "set" and wins.
-    monkeypatch.setenv("FEEDBACK_UI", "")
+    monkeypatch.setenv("FEEDBACK_DEMO_MODE", "")
-    monkeypatch.setenv("SLOPSMITH_UI", "v2")
+    monkeypatch.setenv("SLOPSMITH_DEMO_MODE", "legacy")
-    assert getenv_compat("FEEDBACK_UI") == ""
+    assert getenv_compat("FEEDBACK_DEMO_MODE") == ""
 
 
 def test_flag_parses_true_values(monkeypatch):

tests/test_plugin_runtime_idempotence.py

@@ -69,7 +69,7 @@ def test_capability_visualizer_waits_for_registry_instead_of_hard_error():
 
 
 def test_app_shell_loads_capability_registry_before_app_runtime():
-    source = (ROOT / "static" / "index.html").read_text(encoding="utf-8")
+    source = (ROOT / "static" / "v3" / "index.html").read_text(encoding="utf-8")
 
     assert '<script src="/static/capabilities.js"></script>' in source
     assert '<script src="/static/capabilities/library.js"></script>' in source