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

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

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

CHANGELOG.md

@@ -47,8 +47,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **v3 library: exact artist/album filters + scroll/page-depth restore** (feedBack#857). The v3 Songs toolbar gains Artist and Album dropdowns (Album populates from the selected artist and stays disabled until one is chosen), backed by new exact, case-insensitive (`COLLATE NOCASE`) `artist` / `album` query params threaded through `MetadataDB._build_where` → `query_page` / `query_artists` / `query_stats` and the `/api/library`, `/api/library/artists`, `/api/library/stats` endpoints (the free-text `q` search stays fuzzy and composes with the exact filters). The artist/album catalog is fetched independently of the active artist/album selection so the dropdowns always list the full set for the current provider/search. The toolbar is now sticky so filter controls stay reachable when browsing deep libraries, and returning from the player restores the previous scroll position **and** the loaded infinite-scroll page depth via a `sessionStorage` snapshot keyed by a filter/sort/view state hash (invalidated whenever those change, so a filter change still resets to the top). Tests: `tests/test_library_filters.py` (backend artist/album filters), `tests/js/v3_songs_scroll.test.js` (state-hash + snapshot helpers).
 
 ### Fixed
+- **v3 player: opening another rail popover now closes the Section Practice popover (no more two stacked popovers).** Opening the **Practice** pill's popover and then clicking a different player-rail icon (e.g. **Plugins**) left the Practice popover open underneath the new one — looked broken (reported on macOS, 0.3.0 / 2026-06-28). The rail icons call `e.stopPropagation()` in their click handler (`static/v3/player-chrome.js`), which killed bubbling before it reached the Practice popover's outside-click dismiss bound on `document`. The dismiss (`_installSectionPracticeDismiss` in `static/app.js`) now binds in the **capture phase**, which runs before the target's handler so a descendant's `stopPropagation()` can't swallow it — mirroring how the audio-mixer popover already dismisses. Esc handling stays bubble-phase (the player's Escape-to-exit ordering is unchanged). v2 shares `app.js` and is only hardened (no rail `stopPropagation` there). Tests: `tests/js/section_practice_dismiss.test.js`.
+- **v3 UI no longer lets you accidentally text-select the chrome.** Dragging or double-clicking across the interface used to marquee-highlight buttons, labels, the sidebar, the transport, and the note-highway HUD — which looks broken (reported on Mac + Windows). The v3 shell now defaults to `user-select: none` on `html` (`static/v3/v3.css`), then opts *content* back in — so chrome is non-selectable but the text you actually copy still works. Decided by a 4-lens panel (UX / accessibility / dev-ops / plugin-ecosystem); the guardrails are deliberate: **form fields are always re-enabled** (never break the caret / IME — no `* { user-select:none }`, which trips a WebKit input bug); **plugin screens (`.screen[id^="plugin-"]`) stay selectable by default** so a plugin's copyable text (lyrics, chord names, results) — including community plugins that don't know about this — isn't silently locked; and **core read-only content opts back in by container** via a new hand-authored **`.fb-selectable`** class — applied to the whole **Settings** panel (paths, device names, version, diagnostics, About — answering "is settings still copyable?": yes), the **now-playing song metadata** (with `pointer-events` re-enabled so the HUD text is actually reachable), and the focused **modals / dialogs / toasts / scan banner** that carry copyable errors, IDs, paths, and file names. It's cosmetic only (it protects nothing) and never used to lock copy-worthy text — errors, IDs, paths, versions, and metadata stay selectable per WCAG 2.2 (copy-paste as a permitted mechanism). Dense card lists (library grid, dashboard, profile) stay non-selectable by design — making them selectable would reintroduce the marquee-mess across cards. **v3-only** (v2 unchanged); plain CSS, no Tailwind rebuild; no desktop changes (standard OS-framed window). Plugin authors: `.fb-selectable` is documented in `CLAUDE.md` for re-enabling copyable content rendered outside a plugin screen. Tests: `tests/js/v3_user_select_policy.test.js`.
 - **Input-setup wizard no longer collapses an audio device's driver-type variants into one entry.** On Windows the desktop engine enumerates the same interface once per host API (ASIO / Windows Audio / DirectSound), and the wizard's audio picker (`plugins/input_setup/screen.js`) de-duped the source list by display **label** — so the variants (which share a name) collapsed to a single choice, silently keeping whichever sorted first (often *not* the low-latency ASIO one the player wants). The audio-input capability already collapses true duplicates by `logicalSourceKey` (`_visibleInputSources` in `static/capabilities/audio-session.js`), and the variants each have a **distinct** key, so the wizard's extra label-collapse was redundant for real dupes and destructive for these — it also could drop the variant that was actually `selected`. Removed it; the picker now lists every selectable input. Pairs with feedBack-desktop's change to label each source with its driver type (e.g. "Focusrite (ASIO)") so the now-distinct entries are legible.
 - **3D Highway FPS counter no longer hides behind the v3 "Up Next" pill.** The on-highway FPS readout (Settings → Graphics → 3D Highway → Show FPS counter) is pinned to the top-right of the highway overlay — the same corner the v3 player chrome stacks its persistent **Up Next** pill and live-performance HUD into, on a higher layer that paints over the canvas. So the readout sat *behind* that chrome and couldn't be read — precisely when a tester had turned it on to judge performance (it also made the separate "Up Next won't turn off" complaint worse, since the default-on pill covered the counter regardless). The counter now stays top-right but drops just **below** whichever of that chrome is showing: `highway_3d`'s `screen.js` measures the lowest visible top-right v3 HUD element (`#v3-upnext` / `#v3-live-performance-hud` / `#hud-time`) and floors the FPS box's Y beneath it. Element refs are resolved once and cached (no per-frame `querySelector`, per the plugin perf rules) and only consulted while the counter is actually drawn; gated on `window.feedBack.uiVersion === 'v3'` so the classic (v2) UI is byte-for-byte unaffected. `plugins/highway_3d/plugin.json` version → `3.30.1` (cache-buster). (For reading raw perf numbers unobstructed, the core perf HUD — `localStorage.highwayPerfHud='1'` — still renders above all chrome and additionally shows the adaptive render-scale.)
+- **3D Highway fret-number row no longer clips off the bottom edge when the camera zooms in on a centred span.** The heat-coloured fret-number row is drawn as a band *below* the board (`sY(lowest) − S_GAP*1.4`), but the camera's self-correcting framing only anchors the board **centre** to the lower third of the screen — it reserved no headroom for that row. So a tight zoom on a centred active span (worst around mid-neck; fine when the span sits at either end of the neck, which is why testers saw it "only when centered" and "not every song") dropped the numbers past the bottom edge. Tilt can't fix it there (it would only trade a bottom clip for a top clip), so `camUpdate()` now **dollies the camera back just enough to bring the row back into frame**: it projects the row band with the final camera and, when it falls below a safe NDC line (`FRET_ROW_FIT_NDC_MIN`), raises a capped, hysteretic `_fretRowFitBoost` applied to the `curDist` lerp target (the span-driven zoom still owns zooming *in*). The boost rises promptly (proportional to the deficit), relaxes lazily past a deadband, and is capped (`FRET_ROW_FIT_BOOST_MAX`, +60%) so the zoom can't pop or hunt; it cooperates with the tilt loop (pull-back shrinks the scene, tilt keeps the centre anchored) and yields entirely to the Camera Director free-cam. Surgical: passages where the row is already visible never trigger it, so framing is unchanged everywhere it already worked. `plugins/highway_3d/plugin.json` version → `3.30.2` (cache-buster). Tests: `tests/js/highway_3d_camera_framing.test.js` (guard constants, the boosted `curDist` lerp, the projected-row hysteresis, free-cam yield).
 - **v3 Songs grid now refreshes after a Settings rescan / DLC-folder change — no app restart needed.** On a fresh install, pointing at a DLC folder in Settings and running a scan left the Songs section empty until a restart (the scan *did* populate the library — `_background_scan` re-reads `config.json` fresh — but the v3 grid never reloaded). The Settings **Rescan / Full Rescan** handlers only refreshed the classic (v2) library via `loadLibrary()`; the v3 grid (`static/v3/songs.js`) had no listener for a scan it didn't start itself (only its own upload path self-refreshed via `watchUploadScan`), so its cached, pre-DLC (empty) DOM/snapshot survived a sidebar return until a full reload. The rescan handlers now emit a **`library:changed`** event (`static/app.js`); the v3 grid listens and **reloads if it's the active screen, else marks itself dirty** so the next entry does a full re-fetch instead of restoring the stale snapshot (a `_libraryDirty` short-circuit ahead of every cached-DOM fast-path in `onV3SongsScreenEnter`). Tests: `tests/js/v3_library_refresh.test.js` (the emit + the reload/dirty wiring).
 - **Edit Metadata modal: the Year is now editable.** You could set a year when authoring a pak but the Songs → Edit Metadata modal had no Year field, so it could never be changed afterward. The backend (`POST /api/song/<f>/meta`) already accepted and normalized `year` (writes it into the file via `songmeta`, survives a rescan) — only the UI omitted it. Added a **Year** input to `openEditModal()` (populated from the song's existing year) and included `year` in `saveEditModal()`'s POST body (`static/app.js`). Both the v3 card menu and the legacy edit button already pass the year through, so both surfaces get the field.
 - **Edit Metadata modal no longer closes when a click-drag is released on the backdrop.** Selecting text inside a field and releasing the mouse past the modal's edge dismissed the form without warning (the `click` event's target resolved to the backdrop), discarding the edit. Backdrop dismissal now requires the **mousedown to have started on the backdrop** too — tracked per-modal and decided by a new pure `_editModalShouldClose(clickTarget, modalEl, downOnBackdrop)` helper (`static/app.js`). Cancel / ✕ still close on a normal click. Tests: `tests/js/edit_metadata_modal.test.js` (year in the POST body + the backdrop-close decision table).

CLAUDE.md

@@ -552,6 +552,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.)
 - **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/host-theme-contract.md

@@ -0,0 +1,246 @@
+# Host Theme Contract — design proposal
+
+**Status:** proposal (charrette output, 2026-06-29) · **Owner area:** core v3 + plugin UI
+**Trigger:** a plugin UI feature accidentally "carved itself into a single theme."
+
+## 1. Problem
+
+A results-card feature in the `note_detect` plugin (a glow-ring hero button + a
+gradient-filled accuracy number) was built and visually verified against **only the
+default skin** ("neon"). On the other skins it broke: on "esports" — a deliberately
+glow-less, near-monochrome design language — the glow ring and the colour gradient
+simply **vanished**. The colours adapted (everything used CSS custom-property tokens),
+but the **visual devices themselves did not port**, because nothing in the system says
+"this theme does / doesn't do glow rings."
+
+### Root cause (three findings)
+
+1. **Themes are design *languages*, not palettes.** neon = glow + animation + gradients;
+   esports = no-glow, square, near-monochrome amber; metal = brushed steel + hard bevels +
+   drop-shadows. Tokens made *colour* portable; they never made a *device* portable.
+2. **Tokens are named by *device*, not *intent*.** e.g. `--nd-glow-*` holds a glow in neon
+   but a **hard drop-shadow** in metal — the metal skin is already repurposing a
+   device-named slot to express a different language. The cure is to finish that move:
+   name slots by intent, with "off" (`none`) a legal value.
+3. **No "text-legible-on-accent" role.** White-on-accent was hardcoded in several places;
+   on esports' amber accent that's a contrast failure. And `--nd-accent2` was
+   **double-booked** (gradient-end *and* S-grade colour), so the hero gradient resolved
+   amber→near-white and washed out.
+
+A process gap compounds it: **verification covered one skin**, so the regression was
+invisible until a user switched themes. And this recurs ecosystem-wide — other plugins
+ship their own independent skin systems too.
+
+## 2. Current state (two disconnected systems)
+
+| System | What it is | Limits |
+| --- | --- | --- |
+| **Host themes** (`static/v3/theme-core.js`, `html[data-fb-theme]`) | Cosmetic "shop" themes that recolour `fb-*` Tailwind tokens (surfaces/text/borders). | Apply-only & recolour-only. `--fbv-*` vars exist **only while a theme is equipped** (nothing to read in the default state). No read API, no capability signal, no normalized `theme:changed` event. Comment explicitly says it *leaves decorative accents (rings/shadows) at defaults* → **devices are an ownerless gap.** |
+| **Plugin skins** (e.g. `note_detect` `data-nd-skin`) | Full per-plugin design languages (neon/esports/metal) as CSS-var blocks. | Each plugin reinvents the wheel; disconnected from host themes; a feature can't see both. |
+
+## 3. Goals / non-goals
+
+- **Goal:** a feature, authored once, renders correctly in **any** theme — including ones not
+  yet invented — and degrades **intentionally** (neon ring → esports border), never accidentally.
+- **Goal:** the host owns a canonical contract so plugins consume instead of reinventing.
+- **Non-goal:** forcing every plugin skin to become a host theme. Skins stay plugin-local but
+  **implement** the contract.
+- **Non-goal:** backward-compat with pre-v3 hosts. Everything here is additive + feature-detected.
+
+## 4. The contract — three layers
+
+### Layer 1 — Semantic colour **roles** (always present)
+
+The host writes default `--fb-*` role tokens on `:root` **unconditionally** (not only under
+`[data-fb-theme]`), seeded from the canonical `fb` palette, so `var(--fb-accent, …)` always
+resolves — themed or not. Roles:
+
+**Namespace (normative).** The public contract lives under one prefix, **`--fb-*`**, written on
+`:root` by a host-owned *contract stylesheet* (see §6 / §8) so it is present **themed or not**.
+The existing `--fbv-*` vars stay **internal plumbing** — `theme-core.js` uses them only to
+recolour the Tailwind `.bg-fb-*/.text-fb-*/.border-fb-*` utilities under `html[data-fb-theme]`;
+they are **not** part of this contract and plugins must not read them. (Implementation may seed
+`--fb-*` from the same source the `--fbv-*` overrides use, so an equipped theme moves both.)
+
+**Value grammar (normative).** Colour roles are a **space-separated `r g b` triplet** (matching
+today's `--fbv-*` and the Tailwind utilities), consumed as `rgb(var(--fb-accent))` with optional
+alpha `rgb(var(--fb-accent) / .5)`. Recipe slots (Layer 2) hold **full CSS values** for their
+device (a `box-shadow`, a `border` shorthand, a length, a paint), with `none` legal **except**
+where noted.
+
+**Normative role tokens** (all `--fb-*`, all always present):
+
+| Role | Token | Notes |
+| --- | --- | --- |
+| surface / card / border | `--fb-surface` `--fb-card` `--fb-border` | structural |
+| text / dim | `--fb-text` `--fb-text-dim` | |
+| accent / second hue | `--fb-accent` `--fb-accent-2` | `accent-2` is **just a second hue** — never an assumed gradient end |
+| status | `--fb-good` `--fb-warn` `--fb-bad` | maps onto today's palette `good / mid / low` (mid→warn, low→bad) — implementation aliases both |
+| **on-fill (new)** | `--fb-on-accent` `--fb-on-good` `--fb-on-warn` `--fb-on-bad` | **Rule: every role used as a fill behind text gets a paired `--fb-on-*`** (fixes white-on-amber). Required + contrast-linted (§6). |
+| **focus (new)** | `--fb-focus-ring` | focus indicator independent of `accent`, so focus stays visible when `accent ≈ surface` |
+
+### Layer 2 — Capability **recipes** (intent-named slots; "off" is legal)
+
+A theme declares its design *language* by filling intent-named slots (all `--fb-*`-prefixed,
+same namespace as the roles). A feature applies the slot bundle **unconditionally**; it never
+branches on "is this theme glowy?". Atomic slots (renames-by-intent of today's tokens):
+`--fb-corner-radius`, `--fb-corner-clip`, `--fb-panel-shadow`, `--fb-text-emph-shadow`,
+`--fb-panel-texture`, `--fb-motion-decorative` (reduced-motion-gated). For these, `none` is legal.
+
+Two **composite recipes** carry the load:
+
+- **EMPHASIS** — how this theme makes a primary action special:
+  `--fb-emph-fill / --fb-emph-border / --fb-emph-halo / --fb-emph-on`.
+  neon → halo (glow ring); esports → border (solid accent); metal → fill + drop-shadow.
+  Any individual slot may be `none` — but a theme **must** emphasise *somehow* (at least one of
+  fill/border/halo non-`none`), so a primary action is never visually flat.
+- **ACCENT-TEXT** — how this theme fills a big accent number: `--fb-acc-text-fill`
+  (decoupled from `accent-2`). neon/metal → a gradient; esports → a solid accent.
+  **`--fb-acc-text-fill` is the one slot where `none` is illegal** — it is always a valid paint
+  (solid colour or gradient), defaulting to `rgb(var(--fb-accent))`. Reason: the number is
+  rendered with `background-clip: text` + transparent text-fill, so a `none` paint would make
+  the digits **invisible** (transparent fill, nothing to clip) — which would violate the DoD
+  "a device stays legible when its slot resolves to `none`". The feature also feature-detects
+  `background-clip: text` and keeps a solid `color` base (see §5), so the digits are legible
+  even where clip-text is unsupported.
+
+> These generalize the interim per-skin tokens already shipped in `note_detect`
+> (`--nd-hero-ring-idle/on`, `--nd-hero-border`, `--nd-acc-fill`).
+
+### Layer 3 — JS read API + reconciliation
+
+**The JS API is only for renderers that can't use CSS (canvas / WebGL), never for DOM/CSS
+consumers** — those use the tokens and slots directly (§5). Critically, it exposes *resolved
+token values*, **not** theme-style booleans: a `glow:false` flag can't tell a canvas whether to
+draw a border, a bevel, a drop-shadow, or flat text, so there is **no** `capabilities()` of
+booleans. On the existing `window.feedBack` bus:
+
+- `feedBack.theme.get()` → `{ id, isThemed, tokens }` where `tokens` is the **resolved** map of
+  every `--fb-*` role + recipe slot (the computed values, so a canvas reads the actual device,
+  e.g. the gradient stops for `--fb-acc-text-fill`, not a boolean).
+- `feedBack.theme.prefersReducedMotion()` → boolean (host wraps `matchMedia` once). **This is the
+  single approved JS reduced-motion gate going forward** — existing direct `matchMedia` callers
+  (`venue-mood-fx.js`, `pedal-cables.js`) migrate to it; `--fb-motion-decorative` covers the
+  CSS-authored decorative motion.
+- `theme:changed` event → `{ id, tokens }`.
+
+**Lifecycle (normative).** `get()` always returns the **current effective theme synchronously**
+and is valid at any time — before any theme is applied it returns the default/unthemed roles
+(which always exist on `:root`). Theme application is async (it follows a `/api/profile` refresh);
+`theme:changed` fires **only after** the DOM vars/classes are committed, and **once on initial
+hydration** so a late-mounting plugin isn't stuck on stale state. **Plugin rule:** read `get()`
+on mount, then subscribe to `theme:changed` — never assume an order between your mount and the
+first theme apply.
+
+**Reconciliation rule (ends the two-disconnected-systems problem):** a plugin skin
+**derives surface/text/border from host tokens** (`--nd-bg: rgb(var(--fb-card))`, etc.) and
+**owns only its accent + its devices**, selecting the device via the recipe. A host theme then
+pulls plugin chrome along (one truth for surfaces), while the plugin layers identity on top and
+never imposes a device the active theme neutralizes.
+
+**Propagation scope (normative).** The contract is **same-document light-DOM**: `:root` `--fb-*`
+inheritance and the central focus/motion rules (§6) reach any normal plugin screen. A plugin that
+renders into a **shadow root or iframe** is responsible for bridging — copy the resolved
+`get().tokens` into its sub-root and re-subscribe to `theme:changed` (host `:root` vars don't
+cross those boundaries).
+
+## 5. Consumption pattern (the rule for feature authors)
+
+> **A feature may reference a colour *role* or a recipe *slot*. It may never write a raw
+> device — no literal glow `box-shadow`, no literal `linear-gradient`, no hex.** Devices live
+> in slots; the theme owns the slots.
+
+```css
+.hero-cta {
+  background: var(--fb-emph-fill);
+  border:     var(--fb-emph-border);
+  box-shadow: var(--fb-emph-halo);   /* neon→ring · esports→none · metal→drop-shadow */
+  color:      var(--fb-emph-on);     /* never hardcoded #fff again */
+  border-radius: var(--fb-corner-radius);
+}
+.accuracy-number {
+  /* Always-legible solid base; survives no-clip-text support too. */
+  color: rgb(var(--fb-accent));
+}
+/* Apply the clipped paint ONLY where supported — and --fb-acc-text-fill is
+   guaranteed a real paint (never `none`, per Layer 2), so the digits can't go
+   invisible. */
+@supports ((background-clip: text) or (-webkit-background-clip: text)) {
+  .accuracy-number {
+    background: var(--fb-acc-text-fill);
+    -webkit-background-clip: text; background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+}
+```
+
+**Where the contract physically lives.** A **host-owned static contract stylesheet** (e.g.
+`static/v3/theme-contract.css`, hand-authored, linked from `static/v3/index.html`) holds the
+always-present `:root --fb-*` defaults **plus** the two central a11y rules below. It is **not** a
+Tailwind file, so it never touches the prebuilt `static/tailwind.min.css` artifact the
+`tailwind-fresh` CI check diffs (and it's independent of `theme-core.js`, which keeps
+runtime-injecting only the `--fbv-*` utility overrides under `[data-fb-theme]`).
+
+- **Reduced motion:** `--fb-motion-decorative` is the *only* place CSS decorative animation is
+  named; one central rule in the contract sheet sets it to `none` under
+  `@media (prefers-reduced-motion: reduce)`, so no theme can forget the gate. (JS-driven motion
+  uses `feedBack.theme.prefersReducedMotion()` — §4.3.)
+- **Focus parity:** one contract-level `:focus-visible { outline: 2px solid rgb(var(--fb-focus-ring)) }`
+  for contract consumers; themes recolour `--fb-focus-ring` but may not author their own focus
+  styling. *Migration:* v3 already ships component-specific focus + reduced-motion rules in
+  `v3.css`; those are reconciled onto the contract token (not magically replaced) as a tracked
+  cleanup — "one rule" describes the end state, not day one.
+- **On-fill contrast:** every `--fb-on-*` is required and **lintable**
+  (`contrast(on-X, X) ≥ 4.5:1`, 3:1 large) for each fill role (`accent / good / warn / bad`).
+  Contrast is the theme's job, computed once — not re-judged per feature.
+
+## 7. Verification gate (prevent recurrence)
+
+- A committed **render-matrix** tool, driven off the runtime skin list, that renders the key
+  surfaces (hero CTA, accent number, **and the canvas share-image card**) across **every skin ×
+  key states** (rest / hover / focus / reduced-motion).
+- The gate is **computed-style invariant assertions** (deterministic, CI-safe) — e.g. "emphasis
+  present and text legible in each theme" — **not** pixel-snapshot diffing (the animated ring +
+  fonts + AA make snapshots flaky); a contact-sheet montage is the human backstop.
+- Triggered on the version bump that CSS changes already require; skins enumerated at runtime +
+  a guard test so the matrix can't silently go stale.
+
+**Definition-of-done for any theme-touching UI change** (the few items that would have caught this):
+expressed via tokens not hardcoded values · rendered across all skins · **a new visual *device*
+stays legible when its slot resolves to `none`** · reduced-motion + focus parity · on-accent contrast.
+
+## 8. Back-compat & rollout
+
+All additive: the new always-present `--fb-*` tokens (in the contract sheet, §6) + a new
+`feedBack.theme` namespace + a new event with no current listeners. Existing plugins (those
+reading `fb-*` Tailwind utility classes, or shipping their own skins) are untouched unless they
+opt in. On a host too old to ship the contract sheet, a consumer still degrades cleanly: the
+two-arg fallback `rgb(var(--fb-accent, 224 128 32))` resolves to the literal, and
+`window.feedBack?.theme?.get?.()` is feature-detected — so older hosts behave exactly as today.
+
+**Workstream (sub-tasks):**
+1. **Host minimal surface** — the contract stylesheet's always-present default `--fb-*` tokens + `feedBack.theme.{get, prefersReducedMotion}` (`get().tokens` = resolved values; no boolean `capabilities()`) + `theme:changed`. *(the smallest thing that would have prevented the incident)*
+2. **note_detect refactor** — rename device tokens by intent (EMPHASIS + ACCENT-TEXT recipes), add `on-accent` + `focus-ring`, derive surfaces from host tokens.
+3. **Verification gate** — commit the render-matrix + DoD checklist; add the canvas share-card surface.
+4. **Ecosystem migration guide** — document the contract + the consumption rule for community plugin authors.
+
+## 9. Cross-apply status (already done)
+
+- `note_detect` results-card hero + accuracy number — fixed via per-skin device tokens
+  (the Layer-2 prototype) and verified across neon/esports/metal.
+- The **canvas share-image card** — re-checked across all three skins: **theme-robust**
+  (reads per-skin colour tokens via computed style, draws skin-neutral solid devices). Minor
+  fidelity gap only: it uses flat `--nd-bg` and skips metal's brushed-steel *texture*.
+
+## 10. Open questions
+
+- Should plugin skins eventually become *selectable host themes* (one picker), or stay
+  plugin-local forever? (This proposal assumes plugin-local + contract-implementing.)
+- Component-recipe **bundles** (per named component) are the richer end-state; intent-named
+  slots are the right seed. When/whether to graduate.
+
+*(Resolved during review and folded into the sections above: the token namespace + value grammar
+and normative role table (§4.1); the `none`-is-illegal carve-out for `--fb-acc-text-fill` (§4.2);
+JS exposes resolved tokens, not booleans (§4.3); `theme:changed` lifecycle + shadow/iframe
+propagation (§4.3); the physical home of the role tokens + central focus/motion rules — a
+host-owned contract stylesheet outside Tailwind (§6).)*

plugins/highway_3d/plugin.json

@@ -1,7 +1,7 @@
 {
     "id": "highway_3d",
     "name": "3D Highway",
-    "version": "3.30.1",
+    "version": "3.30.2",
     "type": "visualization",
     "bundled": true,
     "script": "screen.js",

plugins/highway_3d/screen.js

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

plugins/tuner/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "tuner",
   "name": "Guitar/Bass Tuner",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "bundled": true,
   "private": false,
   "script": "screen.js",

plugins/tuner/visualization/analogue-gauge.js

@@ -18,6 +18,8 @@
     // ── Constants ─────────────────────────────────────────────────────
     var _TUNER_LABEL_H = 12;           // px height of each drum label
     var _TUNER_NEEDLE_HALF_SWEEP = 90; // degrees — ±50 cents = horizontal (180° apart)
+    var _SETTLE_A = 0.05;              // deg — needle "settled" threshold (sub-visible)
+    var _SETTLE_Y = 0.1;               // px — drum-strip "settled" threshold
     var _TUNER_IN_TUNE_THRESHOLD = 2;
     var _TUNER_STRIP_START_MIDI = 14;  // ~18 Hz — covers 20 Hz minimum
     var _TUNER_STRIP_END_MIDI = 84;    // ~1047 Hz C6
@@ -321,9 +323,34 @@
             currentAngle += (targetAngle - currentAngle) * lf;
             _setNeedle(currentAngle);
 
+            // Stop once the needle has settled on its target — a static needle
+            // needs no repaint. update() re-kicks the loop when a new reading
+            // moves the target, so this idles the always-on tuner (no signal /
+            // steady pitch) instead of pinning a core at 60 fps forever.
+            if (Math.abs(targetDrumY - currentDrumY) <= _SETTLE_Y
+                    && Math.abs(targetAngle - currentAngle) <= _SETTLE_A) {
+                currentDrumY = targetDrumY; currentAngle = targetAngle;
+                freqStrip.style.transform = 'translateY(' + currentDrumY + 'px)';
+                noteStrip.style.transform = 'translateY(' + currentDrumY + 'px)';
+                _setNeedle(currentAngle);
+                rafId = null;
+                return;
+            }
             rafId = requestAnimationFrame(_animate);
         }
 
+        // Restart the loop only when there's actually something to animate toward
+        // (a new target). Reset lastTime so the first frame after an idle gap
+        // doesn't take one big easing step.
+        function _kick() {
+            if (rafId === null
+                    && (Math.abs(targetDrumY - currentDrumY) > _SETTLE_Y
+                        || Math.abs(targetAngle - currentAngle) > _SETTLE_A)) {
+                lastTime = performance.now();
+                rafId = requestAnimationFrame(_animate);
+            }
+        }
+
         rafId = requestAnimationFrame(_animate);
 
         // ── Public API ────────────────────────────────────────────────
@@ -360,6 +387,7 @@
                 bulbEl.style.backgroundColor = '#2a1010';
                 bulbEl.style.border = '2px solid #4a2020';
                 bulbEl.style.boxShadow = 'none';
+                _kick();   // animate back to rest, then the loop self-stops
                 return;
             }
 
@@ -376,6 +404,7 @@
                 bulbEl.style.border = '2px solid #4a2020';
                 bulbEl.style.boxShadow = 'none';
             }
+            _kick();   // a new reading moved the target → run until it settles
         }
 
         function destroy() {

plugins/tuner/visualization/chef-mt3.js

@@ -620,8 +620,20 @@
             if (_mt3Mode === 'strobe') { _computeStrobeStates(); }
 
             _applyTickStates();
+
+            // No signal and both the glow and strobe drift have fully settled →
+            // idle the loop. update() re-kicks it on the next note.
+            if (!_mt3HasSignal && _mt3GlowOpacity < 0.004
+                    && Math.abs(_mt3SmoothedCents) <= 0.1) {
+                _mt3RafId = null;
+                _mt3LastTime = null;
+                return;
+            }
             _mt3RafId = requestAnimationFrame(_animateStrobe);
         }
+        function _kick() {
+            if (_mt3RafId === null) { _mt3LastTime = null; _mt3RafId = requestAnimationFrame(_animateStrobe); }
+        }
         _mt3RafId = requestAnimationFrame(_animateStrobe);
 
         // ── MODE button ───────────────────────────────────────────────
@@ -677,6 +689,7 @@
                 _renderNote(' ');
                 _applyAccidental();
             }
+            if (hasNote) { _kick(); }   // new signal → restart the strobe loop if idled
         }
 
         // ── Public: destroy ───────────────────────────────────────────

plugins/tuner/visualization/mace-fx-iii.js

@@ -354,10 +354,19 @@
                 if (_smoothedCents > 0) { speed = -speed; }
                 _strobeOffset = ((_strobeOffset + speed * dt) % _totalDash + _totalDash) % _totalDash;
                 arcPath.setAttribute('stroke-dashoffset', String(_strobeOffset));
+            } else if (_currentCents === 0) {
+                // Fully decelerated and no live signal → idle the loop instead of
+                // rescheduling forever. update() re-kicks it on the next note.
+                _rafId = null;
+                _lastTime = null;
+                return;
             }
 
             _rafId = requestAnimationFrame(_animateStrobe);
         }
+        function _kick() {
+            if (_rafId === null) { _lastTime = null; _rafId = requestAnimationFrame(_animateStrobe); }
+        }
         _rafId = requestAnimationFrame(_animateStrobe);
 
         // ── Helper: derive octave number from frequency ───────────────
@@ -439,6 +448,7 @@
 
             // Strobe state — smoothed animation decelerates naturally when _currentCents → 0
             _currentCents = hasNote ? cents : 0;
+            if (hasNote) { _kick(); }   // new signal → restart the decel loop if idled
         }
 
         // ── Public: destroy ───────────────────────────────────────────

plugins/tuner/visualization/strobe.js

@@ -142,9 +142,20 @@ window._tunerViz_strobe = function (container) {
             strobeEl.style.opacity = '0';
         }
 
+        // Idle the loop when there's no live signal — the strobe only needs to
+        // paint while a note is sounding. update() re-kicks it on the next note,
+        // so a silent tuner stops repainting instead of spinning at 60 fps.
+        if (!strobeActive) { rafId = null; return; }
         rafId = requestAnimationFrame(_animate);
     }
 
+    function _kick() {
+        if (rafId === null) {
+            lastAnimateTime = performance.now();
+            rafId = requestAnimationFrame(_animate);
+        }
+    }
+
     rafId = requestAnimationFrame(_animate);
 
     // ── Public API ────────────────────────────────────────────────────
@@ -188,6 +199,7 @@ window._tunerViz_strobe = function (container) {
         const inTune = Math.abs(cents) < 5;
         strobeEl.style.opacity = inTune ? '1' : '0.6';
         strobeEl.style.filter = inTune ? _STROBE_GLOW_IN_TUNE : _STROBE_GLOW_OUT;
+        _kick();
     }
 
     function destroy() {

plugins/tuner/visualization/toilet-tuner.js

@@ -122,6 +122,26 @@
             plungerEl.style.left = _leftPct.toFixed(2) + '%';
             plungerEl.style.top  = _topPct.toFixed(2)  + '%';
 
+            // No live signal and the plunger has eased back to its resting centre
+            // → idle the loop. update() re-kicks it on the next note.
+            if (_currentNote === null && !_plungerDipped
+                    && Math.abs(targetLeft - _leftPct) < 0.05) {
+                _leftPct = targetLeft;
+                plungerEl.style.left = _leftPct.toFixed(2) + '%';
+                _rafId = null;
+                _lastTime = null;
+                return;
+            }
+
+            _rafId = requestAnimationFrame(_animate);
+        }
+
+        function _kick() {
+            if (_rafId !== null) return;
+            // Already parked at rest with no signal → nothing to animate, stay idle.
+            if (_currentNote === null && !_plungerDipped
+                    && Math.abs(_TUNER_TT_CENTRE_PCT - _leftPct) < 0.05) return;
+            _lastTime = null;
             _rafId = requestAnimationFrame(_animate);
         }
 
@@ -130,6 +150,7 @@
             _currentNote  = note;
             _currentCents = note === null ? 0 : cents;
             if (!_plungerDipped) { noteEl.textContent = note || '–'; }
+            _kick();   // a new reading may move the plunger → ensure the loop runs
         }
 
         function destroy() {

static/app.js

@@ -8714,12 +8714,24 @@ function _installSectionPracticeDismiss() {
     // inside #section-practice-control so it never self-closes. Listeners added
     // mid-dispatch don't fire for the opening click, so there's no immediate
     // close race.
+    //
+    // The click listener uses the CAPTURE phase: the v3 player rail's icon
+    // buttons call e.stopPropagation() in their click handler (player-chrome.js
+    // wireRail), which kills bubbling before it reaches document. A bubble-phase
+    // outside-click dismiss would therefore never fire when the user clicks a
+    // rail icon (Plugins, Audio, …) to open another popover, leaving this
+    // popover stranded open on top of it. Capture runs before the target's
+    // handler, so the stopPropagation can't swallow it. This mirrors the audio
+    // mixer popover (audio-mixer.js), which dismisses outside-clicks the same
+    // way. (Esc stays bubble-phase — no rail handler stops keydown propagation,
+    // so it already reaches us, and capturing it would reorder it ahead of the
+    // player's Escape-to-exit handling.)
     document.addEventListener('click', (e) => {
         if (!_sectionPracticePopoverOpen()) return;
         const ctrl = document.getElementById('section-practice-control');
         if (ctrl && ctrl.contains(e.target)) return;
         _closeSectionPracticePopover();
-    });
+    }, true);
     document.addEventListener('keydown', (e) => {
         if (e.key === 'Escape' && _sectionPracticePopoverOpen()) _closeSectionPracticePopover();
     });

static/v3/index.html

@@ -343,7 +343,10 @@
 
     <!-- ══ SETTINGS ═══════════════════════════════════════════════════════ -->
     <div id="settings" class="screen">
-        <div class="fb-settings">
+        <!-- fb-selectable: Settings is read-only content (paths, device names,
+             version, diagnostics, About) the user copies — opt the whole panel
+             back in under the v3 non-select default. See static/v3/v3.css. -->
+        <div class="fb-settings fb-selectable">
             <button onclick="showScreen('home')" class="fb-settings-back">
                 <svg 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> Home
             </button>
@@ -825,7 +828,13 @@
 
         <!-- Top HUD — persistent (song info, time, Up Next) -->
         <div id="player-hud" class="absolute top-0 left-0 right-0 flex justify-between items-start px-5 py-4 pointer-events-none z-20">
-            <div class="text-sm leading-tight">
+            <!-- fb-selectable: now-playing song metadata (title / artist /
+                 arrangement / tuning) is copy-worthy content, not chrome.
+                 pointer-events-auto: the #player-hud parent is pointer-events-none
+                 (so the HUD doesn't eat clicks meant for the highway), which would
+                 also block the mouse from reaching this text to select it — opt
+                 just this block back into hit-testing. -->
+            <div class="text-sm leading-tight fb-selectable pointer-events-auto">
                 <div><span id="hud-artist" class="text-gray-300"></span> — <span id="hud-title" class="text-white font-semibold"></span></div>
                 <div id="hud-arrangement" class="text-gray-500 text-xs mt-0.5"></div>
                 <div id="hud-tuning" class="text-gray-500 text-xs mt-0.5"></div>
@@ -846,9 +855,12 @@
                     <div id="v3-live-performance-state" class="v3-live-performance-state" aria-hidden="true"></div>
                 </div>
                 <div id="v3-upnext" class="v3-upnext hidden">
-                    <span class="text-gray-400">Up Next:</span>
-                    <span id="v3-upnext-name" class="v3-upnext-name"></span>
-                    <span id="v3-upnext-eta" class="text-gray-400 text-xs"></span>
+                    <div class="v3-upnext-row">
+                        <span class="text-gray-400">Up Next:</span>
+                        <span id="v3-upnext-name" class="v3-upnext-name"></span>
+                        <span id="v3-upnext-eta" class="text-gray-400 text-xs"></span>
+                    </div>
+                    <div class="v3-upnext-bar"><div id="v3-upnext-bar-fill" class="v3-upnext-bar-fill"></div></div>
                 </div>
             </div>
         </div>
@@ -914,6 +926,15 @@
                         <option value="0.5">Low</option>
                     </select>
                 </div>
+                <div class="v3-pop-row">
+                    <span class="v3-pop-label" id="min-scale-label">Min res</span>
+                    <select id="min-scale-select" onchange="highway.setMinRenderScale && highway.setMinRenderScale(parseFloat(this.value))" class="v3-pop-select" aria-labelledby="min-scale-label" title="Minimum auto resolution — how far the highway may lower its resolution to hold the frame rate on heavy scenes. 'Full' disables auto-downscaling, but the Quality selector still caps the maximum (so it's only full resolution at Quality = HD).">
+                        <option value="0.25">25%</option>
+                        <option value="0.5">50%</option>
+                        <option value="0.75">75%</option>
+                        <option value="1">Full</option>
+                    </select>
+                </div>
                 <div class="v3-pop-row">
                     <span class="v3-pop-label" id="scoreboard-label">Scoreboard</span>
                     <select id="scoreboard-select" onchange="setScoreboard(this.value)" class="v3-pop-select" aria-labelledby="scoreboard-label" title="Highway scoreboard">

static/v3/player-chrome.js

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

static/v3/songs.js

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

static/v3/v3.css

@@ -4,6 +4,62 @@
  * `fb` palette in tailwind.config.js.
  */
 
+/* ── Text-selection policy (v3) ──────────────────────────────────────────────
+   Accidental drag/double-click selection of app chrome (sidebar, transport, the
+   note highway/HUD, buttons, labels) makes the UI look broken and is never
+   useful — so default the interface to non-selectable, then opt *content* back
+   in. v3-only: this sheet loads only on /v3 (v2 is unchanged). The panel's
+   guardrails are baked in:
+   - NEVER a `* { user-select:none }` rule — it breaks input carets / IME
+     composition on WebKit (bug 82692); we scope to `html` and re-enable below.
+   - This is cosmetic only; it protects nothing (DevTools defeats it) and must
+     never be used to "lock" copy-worthy text away (a11y: keep errors, IDs,
+     paths, versions, metadata, lyrics selectable — incl. in modals/toasts). */
+html { -webkit-user-select: none; user-select: none; }
+
+/* Form fields are ALWAYS selectable/editable — protects the caret + IME
+   (including CJK / dead-key composition). The default must never swallow typing.
+   `.fb-selectable *` forces descendants so a child element's own non-select
+   can't strand copy-worthy text inside a content island. */
+input, textarea, select,
+[contenteditable]:not([contenteditable="false"]),
+[contenteditable]:not([contenteditable="false"]) * {
+    -webkit-user-select: text; user-select: text;
+}
+
+/* Plugin screens are content surfaces (editor, tabview, lyrics, theory, chord
+   text, …). Re-enable their mounted subtree by INHERITANCE (no `*`) so the host
+   policy can't silently make a plugin's copyable text un-selectable — including
+   community / out-of-tree plugins that never adopt `.fb-selectable`. A plugin
+   that wants its own chrome non-selectable still wins via its own element rule
+   (which this inherited value doesn't override). */
+.screen[id^="plugin-"] { -webkit-user-select: text; user-select: text; }
+
+/* Core read-only content opts back in by CONTAINER (lower-drift than tagging
+   each value — a new setting added later inherits "selectable" for free):
+   the Settings panel (values, paths, device names, version, diagnostics,
+   About) and the now-playing song metadata (both tagged `.fb-selectable`).
+   Plugins re-enable their own copyable regions with this same class
+   (documented in CLAUDE.md).
+
+   The focused, transient surfaces below ALWAYS carry copy-worthy text (errors,
+   IDs, file paths, device/version strings) per the a11y guardrail, so they're
+   blanket-opted-in by selector rather than hand-tagged — they're single focused
+   panels, not dense card lists, so re-enabling selection there can't recreate
+   the across-cards marquee mess the policy prevents:
+   - modals / dialogs: `.feedBack-modal`, `[role="dialog"]` (confirm, edit-meta,
+     retune result/error, calibration, filter drawer);
+   - toasts: `#fb-notify-stack`, `#v3-fb-toast`;
+   - the library scan banner (`#scan-banner` — shows the current file path).
+   (Dense card lists — the library grid, dashboard, profile — are intentionally
+   left non-selectable; copy their text from the now-playing HUD / Settings.) */
+.fb-selectable, .fb-selectable *,
+.feedBack-modal, .feedBack-modal *,
+[role="dialog"], [role="dialog"] *,
+#fb-notify-stack, #fb-notify-stack *,
+#v3-fb-toast, #v3-fb-toast *,
+#scan-banner, #scan-banner * { -webkit-user-select: text; user-select: text; }
+
 /* The v3 tuner card replaces the tuner plugin's floating launcher — hide it. */
 #tuner-toggle-btn { display: none !important; }
 
@@ -284,8 +340,9 @@
 /* — Up Next pill (top-right, persistent) — */
 #player-hud .v3-upnext {
     display: flex;
-    align-items: center;
-    gap: .5rem;
+    flex-direction: column;
+    align-items: stretch;
+    gap: .35rem;
     padding: .45rem .9rem;
     border-radius: .75rem;
     background: rgba(15, 23, 42, .7);
@@ -295,6 +352,26 @@
     pointer-events: auto;
 }
 #player-hud .v3-upnext.hidden { display: none; }
+/* Text row keeps the original inline layout untouched. */
+#player-hud .v3-upnext .v3-upnext-row {
+    display: flex;
+    align-items: center;
+    gap: .5rem;
+}
+/* Progress bar under the text — fills as the current section elapses. */
+#player-hud .v3-upnext .v3-upnext-bar {
+    height: 4px;
+    border-radius: 999px;
+    background: rgba(148, 163, 184, .25);
+    overflow: hidden;
+}
+#player-hud .v3-upnext .v3-upnext-bar-fill {
+    height: 100%;
+    width: 0%;
+    border-radius: inherit;
+    background: linear-gradient(90deg, #22d3ee, #a855f7, #f472b6);
+    transition: width .12s linear;
+}
 
 /* — Live performance HUD (top-right, read-only) — */
 .v3-live-performance-hud {

tests/js/highway_3d_camera_framing.test.js

@@ -130,6 +130,59 @@ test('measure-start cache is invalidated on song change', () => {
     );
 });
 
+// ── Fret-row fit guard ──────────────────────────────────────────────────────
+// Keeps the heat-coloured fret-number row from clipping off the bottom edge
+// when a tight, centred zoom (worst mid-neck) drops it below the lower-third
+// framing. camUpdate dollies the camera back via a capped, hysteretic boost.
+
+test('fret-row fit guard constants are defined', () => {
+    for (const name of [
+        'FRET_ROW_FIT_NDC_MIN', 'FRET_ROW_FIT_DEADBAND', 'FRET_ROW_FIT_BOOST_MAX',
+    ]) {
+        assert.match(src, new RegExp('const\\s+' + name + '\\s*='),
+            `${name} must be declared as a fit-guard constant`);
+    }
+});
+
+test('the curDist lerp target applies the fit-guard dolly boost', () => {
+    // The span-driven tgtDist still owns zooming in; the boost only pulls back.
+    assert.match(
+        src,
+        /curDist\s*\+=\s*\(\s*tgtDist\s*\*\s*_fretRowFitBoost\s*-\s*curDist\s*\)\s*\*\s*lerp/,
+        'curDist must lerp toward tgtDist * _fretRowFitBoost',
+    );
+});
+
+test('the guard projects the fret-row band and adjusts the boost with hysteresis', () => {
+    // Row band Y mirrors the render position (sY(lowest) - S_GAP * 1.4).
+    assert.match(
+        src,
+        /Math\.min\(\s*sY\(0\)\s*,\s*sY\(nStr\s*-\s*1\)\s*\)\s*-\s*S_GAP\s*\*\s*1\.4/,
+        'the guard must probe the same row band the fret-number row is drawn at',
+    );
+    // Prompt pull-back when below the min, capped at BOOST_MAX.
+    assert.match(
+        src,
+        /_rowNdcY\s*<\s*FRET_ROW_FIT_NDC_MIN[\s\S]*?Math\.min\(\s*FRET_ROW_FIT_BOOST_MAX/,
+        'below the min NDC the boost rises, capped at FRET_ROW_FIT_BOOST_MAX',
+    );
+    // Lazy relax only once past the deadband, floored at 1.
+    assert.match(
+        src,
+        /_rowNdcY\s*>\s*FRET_ROW_FIT_NDC_MIN\s*\+\s*FRET_ROW_FIT_DEADBAND[\s\S]*?Math\.max\(\s*1\s*,\s*_fretRowFitBoost/,
+        'past the deadband the boost relaxes back toward 1',
+    );
+});
+
+test('the fit guard yields to the free-cam (Camera Director)', () => {
+    // When the free-cam owns the view the auto dolly must reset to 1, not fight it.
+    assert.match(
+        src,
+        /if\s*\(\s*_freeCam\s*&&\s*_freeCam\.enabled\s*\)\s*\{\s*if\s*\(\s*_fretRowFitBoost\s*!==\s*1\s*\)\s*_fretRowFitBoost\s*=\s*1/,
+        'with the free-cam enabled the guard must drop any auto dolly back to 1',
+    );
+});
+
 // ── Debug hook stayed removed ───────────────────────────────────────────────
 
 test('temporary camera debug hook is not present', () => {

tests/js/highway_3d_wide_fov.test.js

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

tests/js/section_practice_dismiss.test.js

@@ -0,0 +1,43 @@
+// Guards the Section Practice popover's outside-click dismiss in static/app.js
+// (_installSectionPracticeDismiss). The v3 player-rail icon buttons call
+// e.stopPropagation() in their click handler (static/v3/player-chrome.js
+// wireRail), so a BUBBLE-phase document dismiss never fires when the user clicks
+// a different rail icon (Plugins, Audio, …) — leaving the Practice popover
+// stranded open under the newly-opened one (feedBack#638). The dismiss must bind
+// in the CAPTURE phase (runs before the target's stopPropagation can swallow it).
+// Esc must stay bubble-phase so it doesn't reorder ahead of the player's
+// Escape-to-exit handling. A revert to bubble-phase should fail here.
+//
+// Source-level only — same strategy as the other tests/js/ files.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'app.js'), 'utf8');
+const m = src.match(/function _installSectionPracticeDismiss\s*\(\)\s*\{[\s\S]*?\n\}/);
+assert.ok(m, '_installSectionPracticeDismiss() not found in static/app.js');
+const body = m[0];
+
+test('the outside-click dismiss binds in the CAPTURE phase', () => {
+    assert.match(
+        body,
+        /addEventListener\(\s*['"]click['"][\s\S]*?,\s*true\s*\)/,
+        'the click dismiss must pass the capture flag (`, true`) so a rail icon\'s '
+        + 'stopPropagation() cannot swallow it',
+    );
+});
+
+test('only the click listener is capture (Escape keydown stays bubble-phase)', () => {
+    // Exactly one capture binding in the installer — the click. The keydown
+    // (Escape) listener must NOT be capture.
+    const captureBinds = body.match(/,\s*true\s*\)/g) || [];
+    assert.equal(captureBinds.length, 1, 'expected exactly one capture-phase binding (the click)');
+});
+
+test('the dismiss ignores clicks inside the control (no self-close)', () => {
+    assert.match(body, /section-practice-control/, 'must scope to #section-practice-control');
+    assert.match(body, /ctrl\s*&&\s*ctrl\.contains\(e\.target\)\)\s*return/,
+        'a click inside the control (incl. the pill) must not dismiss the popover');
+});

tests/js/v3_user_select_policy.test.js

@@ -0,0 +1,80 @@
+// Guards the v3 text-selection policy (static/v3/v3.css + static/v3/index.html):
+// the UI defaults to non-selectable so accidental chrome selection can't look
+// broken, while form fields, plugin screens, and core content opt back in. A
+// future global reset clobbering the rule — or the content containers losing
+// their .fb-selectable opt-in — should fail here.
+//
+// Source-level only — same strategy as the other tests/js/ files.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const root = path.join(__dirname, '..', '..');
+// Strip block comments so the policy's own explanatory prose (which quotes the
+// `* { user-select:none }` anti-pattern as a warning) can't trip the assertions.
+const css = fs.readFileSync(path.join(root, 'static', 'v3', 'v3.css'), 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '');
+const html = fs.readFileSync(path.join(root, 'static', 'v3', 'index.html'), 'utf8');
+
+test('v3 defaults to non-selectable on html (not a universal `*` rule)', () => {
+    assert.match(css, /html\s*\{[^}]*user-select:\s*none/,
+        'html must default user-select: none');
+    // The `* { user-select: none }` anti-pattern breaks input carets / IME — must not exist.
+    assert.doesNotMatch(css, /\*\s*\{[^}]*user-select:\s*none/,
+        'must NOT use a universal `*` user-select:none rule');
+});
+
+test('form fields are always re-enabled (caret / IME safe)', () => {
+    assert.match(
+        css,
+        /input,\s*textarea,\s*select[\s\S]*?contenteditable[\s\S]*?user-select:\s*text/,
+        'input/textarea/select/[contenteditable] must be re-enabled to user-select: text',
+    );
+});
+
+test('plugin screen subtree stays selectable by inheritance (no `*`, respects plugin opt-outs)', () => {
+    assert.match(
+        css,
+        /\.screen\[id\^="plugin-"\]\s*\{[^}]*user-select:\s*text/,
+        'plugin screens must be re-enabled so plugin content is not silently un-copyable',
+    );
+    assert.doesNotMatch(
+        css,
+        /\.screen\[id\^="plugin-"\]\s*\*/,
+        'the plugin carve must NOT use `*` (would override a plugin\'s own non-select chrome)',
+    );
+});
+
+// The rule that re-enables selection on copyable content. Find the single
+// declaration block whose body sets `user-select: text`, then assert each
+// required selector is one of its selectors — order/format independent.
+const selectableRule = (css.match(/([^{}]*)\{[^}]*user-select:\s*text[^}]*\}/g) || [])
+    .join('\n');
+
+test('core content opts back in via .fb-selectable (element + descendants)', () => {
+    assert.match(selectableRule, /\.fb-selectable\b/, '.fb-selectable must set user-select: text');
+    assert.match(selectableRule, /\.fb-selectable\s*\*/, '...and its descendants (.fb-selectable *)');
+});
+
+test('focused copyable surfaces (modals/toasts/scan banner) opt back in', () => {
+    // The PR\'s a11y guardrail keeps copyable text selectable "incl. in
+    // modals/toasts" — these carry errors / IDs / paths the user copies.
+    assert.match(selectableRule, /\.feedBack-modal\b/, 'modals (.feedBack-modal) must be selectable');
+    assert.match(selectableRule, /\[role="dialog"\]/, 'dialogs ([role="dialog"]) must be selectable');
+    assert.match(selectableRule, /#fb-notify-stack\b/, 'toasts (#fb-notify-stack) must be selectable');
+    assert.match(selectableRule, /#scan-banner\b/, 'the scan banner (#scan-banner) must be selectable');
+});
+
+// Match a class="" attribute that contains ALL given tokens in any order.
+const hasClasses = (...tokens) => new RegExp(
+    'class="' + tokens.map((t) => '(?=[^"]*\\b' + t + '\\b)').join('') + '[^"]*"');
+
+test('the Settings panel and now-playing metadata carry .fb-selectable', () => {
+    assert.match(html, hasClasses('fb-settings', 'fb-selectable'),
+        'the Settings panel must opt back in (paths / version / diagnostics / About)');
+    assert.match(html, hasClasses('fb-selectable', 'pointer-events-auto'),
+        'the now-playing metadata must opt back in AND re-enable pointer-events '
+        + '(its #player-hud parent is pointer-events-none, which would block mouse selection)');
+});