fix(tunings): extended-range bass was named as a guitar

Reported by a 6-string bassist: a Sleep Token chart tuned A0 D1 G1 C2 F2
A#2 (standard 6-string bass, whole step down) imported and displayed as
"6 string D Standard". They called it A standard and they were right.

Root cause: `tuning_name()` gated its naming ladder on
`len(offsets) == 6`, treating six offsets as proof of a 6-string GUITAR.
A 6-string BASS also has six offsets, but its lowest string is B, not E
— so the guitar ladder mislabels the whole family: an all-zeros bass
read "E Standard" (it is Standard/B) and a whole-step-down bass read
"D Standard" (it is A Standard). The function's own comment warned about
exactly this error for 7-string guitars; nobody guarded the bass axis.
The stored value feeds the library's Tuning filter, so every 5/6-string
bass song in every library was filed under a guitar name.

- `tuning_name(offsets, *, is_bass=False)`: bass 5/6 use the low-B
  ladder (Standard / Bb / A / G# / G) and bass 4 keeps the E ladder it
  shares with guitar. Drop names come off the resulting low string.
  Default stays guitar, so existing callers are unaffected.
- `sloppak._tuning_for_meta_kind()` reports WHICH kind supplied the
  tuning; `extract_meta` emits `tuning_is_bass` and scan_worker passes
  it through. Guitar-first selection for the library index is unchanged
  — a pack with a guitar part still indexes by the guitar.
- `TUNING_PRESET_MIDIS` bass-5/bass-6 renamed to match, with
  `TUNING_PRESET_ALIASES` so `_valid_tuning_for_key` MIGRATES a saved
  profile carrying an old name instead of rejecting it (it refuses names
  belonging to another key's built-ins, and "D Standard" still exists
  for guitar-6/bass-4 — so a rename alone would have invalidated those
  profiles). Pitches are untouched; only labels change.

Convention confirmed by the bass- and guitar-pedagogy seats: name
extended range off the ACTUAL lowest string, which is what the 7-string
guitar presets already do. The old names came from the band-level habit
of saying "we're in D standard" — true of the guitars, while the bassist
in that band is in A standard. Right answer, wrong scope. The bass table
was also internally inconsistent: its Drop A was already named off the
low string while its standards were not.

Tests: bass ladders for 4/5/6 strings, the reported chart pinned both
ways (is_bass=True -> "A Standard", same offsets as guitar -> "D
Standard"), bass drop naming, a table-wide invariant that every bass
preset name matches the note its low string sounds, and alias migration
(incl. not leaking into guitar-6/bass-4). The existing legacy-flat-bass
migration test now asserts the corrected label — same pitches, right
name. Suite: 1735 passed vs 1720 on main, with the same 99 pre-existing
env failures.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01929LgKdJMyPGLf8N1WpEVW
Signed-off-by: ChrisBeWithYou <christian.a.cowan@gmail.com>

CHANGELOG.md

@@ -7,7 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Gold tier (career passports)** — an earned badge turns **gold** when
+  Virtuoso verifies an improvised jam in the passport's style (the
+  `gold_improv` artifact relays with the drill snapshot; a genre inherits its
+  family's style, gained-only, and gold never substitutes for the badge bar
+  itself). Gold gets its own ceremony, stamp slam, foil chip, and gold ink on
+  the shelf cover, profile wall, and passport card; the bronze page's "Gold
+  rung coming" preview becomes a live invitation to jam it.
+- **Gigs (the career verb, frontend)** — book a gig from any opened passport:
+  a gig poster proposes the setlist (re-roll for a different bill; save or
+  copy the poster as a PNG), "Play the gig" hands the set to the play queue
+  with the venue on stage, a floating strip tracks the set, and finishing it
+  logs dated entries with per-song accuracies in the passport book — with an
+  encore celebration (crowd eruption + confetti) when the whole set clears
+  the bar, and a summary poster to share. Quitting mid-set simply abandons
+  it: no log, no fail state.
+- **Career on the Profile and Home pages** — the Profile gains a passport
+  wall (earned-badge covers per instrument, hours, gig count; absent until a
+  passport exists), injected through the same mount-point + rendered-event
+  seam the achievements plugin uses (now documented in docs/plugin-v3-ui.md).
+  The home page's plugin-count stat tile becomes a career trading card
+  (badges, hours, the closest stamp ask, foil shine) with the old stat as the
+  built-in fallback when career has no state. Earned passports gain **Save
+  card / Copy card** — a natively-drawn PNG passport card, downloadable or
+  copied straight to the clipboard for pasting outside the app (shared
+  `blob-io` helpers replace the download idiom previously duplicated in
+  settings-io and diagnostics-export).
+- **Gigs (backend)** — career mode gains its verb: `POST
+  /api/plugins/career/gigs/propose` builds a playable setlist for an
+  instrument+genre (your qualifying songs plus a couple of stakes songs near
+  the bar; a young passport fills from unplayed genre songs — the first gig
+  is how stubs start; re-roll by calling again), naming the room your stars
+  can book. `POST /gigs` logs a **completed** set — per-song accuracies read
+  from the set's own freshly-recorded stats, an encore flag at the
+  data-driven bar (avg ≥ 75%) — into the career state; abandoned sets never
+  log (no fail state: the gig you finished is the gig you played). Passports
+  carry their gig log; instruments their gig count.
+
 ### Changed
+- **`GET /api/song/{f}?stems=1`** (new, opt-in) — returns the pack's playable stem
+  list (`[{id, url, default}]` + `full_mix_url`), the same list the highway's WS
+  `ready` sends. The stems plugin could only learn it from that WS message, which
+  arrives once the highway is already on screen — so it decoded and then copied the
+  whole song's PCM to its audio worklet with the player visible: over half a gigabyte
+  of memcpy in one frame for a 6-stem pack, a measured 698 ms freeze right as the
+  song-credits card appeared. With the list available at `song:loading` the plugin
+  does all of it before the highway is drawn. Built by calling `load_song` itself, so
+  it cannot drift from what the WS sends. Opt-in, so the library's metadata calls pay
+  nothing.
+- **Folder library renders only the songs on screen** (#965) — a song list used to
+  render *every* song it held. On a flat 50,944-song library that was one `<div>`
+  with 50,938 children and ~1.3 **million** DOM nodes (~4.2 GB of renderer memory),
+  built even while another screen was showing. A document that size also punishes
+  unrelated code: any `document.querySelector` that misses has to walk the whole
+  tree — which is how the song-preview menu check ended up eating ~50% of the
+  renderer and dropping the app to 2.7 fps. Lists longer than 200 songs are now
+  windowed (25–31 rows in the DOM instead of 50,000); shorter lists are unchanged.
 - **The full mix is a stem** (#933) — core no longer depends on `original_audio:`, a
   top-level manifest key this repo invented (#583) that the feedpak spec never had.
   The format already carried the pre-separation mixdown as a stem; feedpak 1.15.0
@@ -156,6 +212,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   engine (`app.js`, `highway.js`, `playSong`, `showScreen`, the capability registry).
 
 ### Fixed
+- **3D Highway: the lane stops at the hit line** (#991) — the highway lane, its
+  dividers, and the fret boundary extension lines ran `BEHIND` seconds *past* the
+  hit line toward the player. Nothing is ever drawn in that strip (notes and chord
+  frames clamp to `Math.min(0, dZ(dt))`), so it read as lane with no notes on it.
+  The floor geometry now ends at the hit line; its far edge is unchanged, still
+  `-AHEAD*TS` at the note horizon.
 - **Career passports review polish** — the passport tabs and book overlay carry
   proper ARIA semantics (`aria-selected`/`aria-controls`/`tabpanel`;
   `role="dialog"` + `aria-modal` with focus moved to the close button on open

docs/plugin-v3-ui.md

@@ -189,3 +189,23 @@ out of the capability graph.
 - [ ] `#player` overlays keep `z-index` ≤ the chrome layers (transport/HUD 20,
       rail 30, popovers 40).
 - [ ] Verify at `/` — it and `/v3` serve the same (and only) v3 shell.
+
+## Injecting into core shells (profile, dashboard)
+
+Core screens that accept plugin sections render **mount points** — usually
+empty, sometimes holding core's own **fallback content** (the Dashboard's
+career slot ships the plugin-count stat) — and announce each (re)build with a
+DOM event, because their `innerHTML` swap wipes anything previously injected.
+A plugin listens for the event and **replaces the mount's content** (never
+append — a fallback may be present) by id — the same seam every time:
+
+| Shell | Event | Mounts |
+| --- | --- | --- |
+| Profile | `v3:profile-rendered` | `#v3-profile-passports-mount` (career wall), `#v3-profile-feats-slot`, `#v3-profile-achievements-mount` |
+| Dashboard | `v3:dashboard-rendered` | `#v3-dash-career-slot` (career card; core's plugin-count stat is the fallback content a plugin may replace) |
+| Settings | `v3:settings-rendered` | per-plugin `settings.html` panels |
+
+Rules: inject on every event (the mount is fresh), keep the section
+**absent-not-empty** (no state → leave the mount alone / empty), and guard
+re-wired listeners with a `dataset` flag when your own refresh path can run
+against an unwiped mount.

docs/size-exemptions.md

@@ -61,6 +61,8 @@ extractions and twenty-two `routers/` modules, plus lib/library_registry.py for
 and is a monolith in its own right, to be split per-table once the router train
 lands) · `static/v3/songs.js` (4,134) · `static/capabilities/audio-session.js`
 (2,974) · `plugins/highway_3d/screen.js` (15,656) · `plugins/keys_highway_3d/screen.js`
-(3,780) · `plugins/drum_highway_3d/screen.js` (3,597) — and every monolith with a PR
+(3,780) · `plugins/drum_highway_3d/screen.js` (3,597) · `plugins/career/screen.js`
+(1,530 — career v3 gigs + gold pushed it over; split plan: carve the gig block into a
+`scriptType: module` file when career work next touches it) — and every monolith with a PR
 train in the refactor plan. Test files (e.g. `tests/test_plugins.py`) are out of scope
 by policy — the norm governs source files.

lib/dlc_paths.py

@@ -14,6 +14,7 @@ import os
 from pathlib import Path
 
 import appstate
+from safepath import resolved_root
 
 
 def _get_dlc_dir(cfg: dict | None = None) -> Path | None:
@@ -86,7 +87,14 @@ def _resolve_dlc_path(dlc: Path, filename: str) -> Path | None:
             or PureWindowsPath(safe).drive):
         return None
     try:
-        root = dlc.resolve()
+        # The library root is fixed for the life of the process, but this
+        # function runs once per song / art fetch / scanned row — and
+        # `.resolve()` lstats every path component. Re-resolving here was
+        # ~23,500 stat calls/sec on a 50,944-song library, which pins a core
+        # when the library sits on a FUSE mount (NTFS-3G, SMB, sshfs) where each
+        # stat is a userspace round trip. Resolve the root once; see
+        # safepath.resolved_root for the caching contract.
+        root = resolved_root(dlc)
         # normpath collapses `.`/`..`/duplicate separators purely lexically —
         # it never touches the filesystem, so an in-library junction component
         # is preserved (allowed) while `..`/absolute segments still escape and

lib/library_registry.py

@@ -17,7 +17,12 @@ import threading
 from typing import ClassVar
 
 import appstate
-from metadata_db import MetadataDB, _tuning_group_key_sql
+from metadata_db import (
+    MetadataDB, _effective_tuning_cols_sql, _perspective_is_inferred_sql,
+    _tuning_group_key_sql,
+)
+import tunings as tunings_mod
+from tunings import DEFAULT_PERSPECTIVE, PERSPECTIVES
 from routers import art as art_router
 
 import logging
@@ -39,9 +44,6 @@ def _safe_art_redirect_url(url: str) -> str | None:
         return None
 
 
-_TUNING_GROUP_KEY_SQL = _tuning_group_key_sql("songs")
-
-
 class LocalLibraryProvider:
     id = "local"
     label = "My Library"
@@ -69,28 +71,43 @@ class LocalLibraryProvider:
     def query_stats(self, **kwargs) -> dict:
         return self._db.query_stats(**kwargs)
 
-    def tuning_names(self) -> dict:
+    def tuning_names(self, instrument: str = DEFAULT_PERSPECTIVE) -> dict:
         # Group custom tunings on their raw offsets so distinct ones stay
         # distinct (tuning_name collapses them all to "Custom Tuning"); named
         # tunings keep grouping by name (stable across the rescan boundary, no
         # offsets/name split). `key` is the value the client sends back as the
         # filter selector — equal to the name for named tunings, the offsets
         # string for customs; offsets also feed the client's custom-pill label.
+        #
+        # `instrument=bass` swaps every column for its effective bass-facing
+        # expression (bass arrangement's tuning, guitar fallback) — the SAME
+        # expressions _build_intrinsic_where filters on, so a facet entry
+        # always selects exactly the songs it counted.
+        name_sql, offsets_sql, sort_sql = _effective_tuning_cols_sql("songs", instrument)
+        gkey_sql = _tuning_group_key_sql("songs", instrument)
+        # How many of a row's songs are showing an INFERRED tuning — i.e. have
+        # no bass chart of their own and are falling back to the guitar-derived
+        # one. Reported per entry so the UI can be honest about it instead of
+        # presenting a borrowed tuning as a measured one. Always 0 for guitar.
+        inferred_sql = f"SUM({_perspective_is_inferred_sql('songs', instrument)})"
         with self._db._lock:
             rows = self._db.conn.execute(
-                f"SELECT tuning_name, {_TUNING_GROUP_KEY_SQL} AS gkey, "
-                "MIN(tuning_sort_key), COUNT(*), MIN(tuning_offsets) "
-                "FROM songs WHERE title != '' AND COALESCE(tuning_name, '') != '' "
+                f"SELECT {name_sql}, {gkey_sql} AS gkey, "
+                f"MIN({sort_sql}), COUNT(*), MIN({offsets_sql}), {inferred_sql} "
+                f"FROM songs WHERE title != '' AND COALESCE({name_sql}, '') != '' "
                 "GROUP BY gkey COLLATE NOCASE "
-                "ORDER BY ABS(COALESCE(MIN(tuning_sort_key), 0)), "
-                "COALESCE(MIN(tuning_sort_key), 0) ASC, "
-                "tuning_name COLLATE NOCASE"
+                f"ORDER BY ABS(COALESCE(MIN({sort_sql}), 0)), "
+                f"COALESCE(MIN({sort_sql}), 0) ASC, "
+                f"{name_sql} COLLATE NOCASE"
             ).fetchall()
         return {
+            "instrument": instrument,
             "tunings": [
                 {"name": name, "key": gkey, "offsets": offs or "",
-                 "sort_key": int(sk or 0), "count": count}
-                for name, gkey, sk, count, offs in rows
+                 "sort_key": int(sk or 0), "count": count,
+                 # Portion of `count` borrowed from the guitar chart.
+                 "inferred_count": int(inferred or 0)}
+                for name, gkey, sk, count, offs, inferred in rows
             ],
         }
 
@@ -330,9 +347,16 @@ class SmartCollectionProvider:
         # have been hand-edited; never let a bad value reach a query.
         self._rules = _sanitize_collection_rules(collection.get("rules") or {})
 
-    def _filter_kwargs(self) -> dict:
-        return _library_filter_args(**{k: v for k, v in self._rules.items()
+    def _filter_kwargs(self, instrument: str = "", playable_from_pitch=None) -> dict:
+        # `instrument` is the CALLER's play perspective (rides every request),
+        # never part of the saved rules — a collection saved by a guitarist
+        # must still read in bass tunings for a bass player, and vice versa.
+        args = _library_filter_args(**{k: v for k, v in self._rules.items()
                                        if k in _LIBRARY_FILTER_PARAM_KEYS})
+        args["instrument"] = _normalize_instrument(instrument)
+        # The caller's CURRENT tuning is likewise per-request, never a saved rule.
+        args["playable_from_pitch"] = playable_from_pitch
+        return args
 
     def _sort(self, fallback: str) -> str:
         # A collection may pin its own sort (e.g. "recently added"); query_page
@@ -340,28 +364,31 @@ class SmartCollectionProvider:
         return self._rules.get("sort") or fallback
 
     def query_page(self, *, page=0, size=24, sort="artist", direction="asc",
-                   naming_mode="legacy", **_ignore):
+                   naming_mode="legacy", instrument="", playable_from_pitch=None, **_ignore):
         return self._local._db.query_page(
             page=page, size=size, sort=self._sort(sort), direction=direction,
-            naming_mode=naming_mode, **self._filter_kwargs())
+            naming_mode=naming_mode, **self._filter_kwargs(instrument, playable_from_pitch))
 
-    def query_artists(self, *, letter="", page=0, size=50, naming_mode="legacy", **_ignore):
+    def query_artists(self, *, letter="", page=0, size=50, naming_mode="legacy",
+                      instrument="", playable_from_pitch=None, **_ignore):
         return self._local._db.query_artists(
             letter=letter, page=page, size=size, naming_mode=naming_mode,
-            **self._filter_kwargs())
+            **self._filter_kwargs(instrument, playable_from_pitch))
 
-    def query_albums(self, *, page=0, size=120, naming_mode="legacy", **_ignore):
+    def query_albums(self, *, page=0, size=120, naming_mode="legacy",
+                     instrument="", playable_from_pitch=None, **_ignore):
         return self._local._db.query_albums(
-            page=page, size=size, naming_mode=naming_mode, **self._filter_kwargs())
+            page=page, size=size, naming_mode=naming_mode,
+            **self._filter_kwargs(instrument, playable_from_pitch))
 
     def query_stats(self, *, sort="artist", want_sort_letters=False,
-                    naming_mode="legacy", **_ignore):
+                    naming_mode="legacy", instrument="", playable_from_pitch=None, **_ignore):
         return self._local._db.query_stats(
             sort=self._sort(sort), want_sort_letters=want_sort_letters,
-            naming_mode=naming_mode, **self._filter_kwargs())
+            naming_mode=naming_mode, **self._filter_kwargs(instrument, playable_from_pitch))
 
-    def tuning_names(self):
-        return self._local.tuning_names()
+    def tuning_names(self, instrument: str = "guitar"):
+        return self._local.tuning_names(instrument=_normalize_instrument(instrument))
 
     async def get_art(self, song_id: str):
         return await self._local.get_art(song_id)
@@ -390,7 +417,10 @@ def _library_filter_args(q: str = "", favorites: int = 0, format: str = "",
                          artist: str = "", album: str = "",
                          arrangements_has: str = "", arrangements_lacks: str = "",
                          stems_has: str = "", stems_lacks: str = "",
-                         has_lyrics: str = "", tunings: str = "") -> dict:
+                         has_lyrics: str = "", tunings: str = "",
+                         instrument: str = "", tuning_match: str = "",
+                         playable_offsets: str = "", playable_instrument: str = "",
+                         playable_string_count: str = "") -> dict:
     fmt = format if format in ("archive", "sloppak", "loose") else ""
     return {
         "q": q,
@@ -404,9 +434,58 @@ def _library_filter_args(q: str = "", favorites: int = 0, format: str = "",
         "stems_lacks": _split_csv(stems_lacks),
         "has_lyrics": _parse_has_lyrics(has_lyrics),
         "tunings": _split_csv(tunings),
+        # Which perspective the tuning facet/filter/sort speaks for (the
+        # caller's play role, NOT a saved rule — see _sanitize_collection_rules).
+        "instrument": _normalize_instrument(instrument),
+        # "Playable without retuning" mode: the caller's CURRENT tuning,
+        # resolved to the one number the comparison needs. None = exact-match
+        # mode (the default), so the tuning pills behave exactly as before.
+        "playable_from_pitch": (
+            _playable_from_pitch(playable_offsets, playable_instrument,
+                                 playable_string_count)
+            if tuning_match == "playable" else None),
     }
 
 
+def _playable_from_pitch(offsets_csv: str, instrument: str, string_count: str):
+    """Lowest open-string MIDI pitch of the CALLER's current tuning.
+
+    The client sends its live working tuning (offsets + instrument + string
+    count) rather than a precomputed pitch, so the pitch tables stay in one
+    place (lib/tunings.py) instead of being duplicated in JS.
+
+    Returns None for anything unusable — the caller then applies NO playable
+    filter at all. That is the neutral state, not a claim: a malformed tuning
+    must not silently assert that everything is playable OR that nothing is.
+    """
+    try:
+        offsets = [int(x) for x in _split_csv(offsets_csv)]
+    except (TypeError, ValueError):
+        return None
+    if not offsets:
+        return None
+    inst = "bass" if instrument == "bass" else "guitar"
+    try:
+        sc = int(string_count)
+    except (TypeError, ValueError):
+        sc = len(offsets)
+    key = tunings_mod.instrument_key(inst, sc)
+    if key not in tunings_mod.STANDARD_OPEN_MIDIS or len(offsets) != sc:
+        return None
+    midis = tunings_mod.tuning_midis_from_offsets(key, offsets)
+    return min(midis) if midis else None
+
+
+def _normalize_instrument(raw: str) -> str:
+    """Resolve a tuning PERSPECTIVE id (guitar-lead | guitar-rhythm | bass).
+
+    Tolerates the legacy two-valued vocabulary ("guitar" -> guitar-lead) and
+    falls back to the default for anything unknown — an unrecognised value
+    must never silently change filter semantics."""
+    return raw if raw in PERSPECTIVES else (
+        DEFAULT_PERSPECTIVE if raw != "bass" else "bass")
+
+
 def _sync_collection_provider(collection: dict) -> None:
     """Register (or replace) the provider for one collection."""
     appstate.library_providers.register(

lib/loosefolder.py

@@ -225,13 +225,18 @@ def _detect_arrangements(path: Path) -> tuple[list[dict], dict]:
     Returns (arrangements_list, shared_meta).
     shared_meta contains title/artist/album/year/duration/tuning_offsets
     sourced from the highest-priority arrangement (lead > combo > rhythm >
-    bass) — picking the guitar tuning when both bass and lead are present.
+    bass) — picking the guitar tuning when both bass and lead are present —
+    plus `bass_tuning_offsets` from the first bass arrangement (None when the
+    folder has none), so the index can carry both tunings.
     """
     arrangements = []
     # Track which arrangement priority sourced shared_meta so a later,
     # higher-priority arrangement (lead < bass in sort order) overrides.
     shared_meta = {}
     shared_priority = None
+    # First tuning seen per arrangement ROLE, kept alongside the guitar-first
+    # song tuning so the library can answer for the part a player plays.
+    role_tunings: dict[str, list[int] | None] = {"bass": None, "rhythm": None}
 
     for xml in sorted(_iter_local_xmls(path)):
         # Trust the XML root over the filename — a custom named
@@ -269,6 +274,10 @@ def _detect_arrangements(path: Path) -> tuple[list[dict], dict]:
                             "duration", "tuning_offsets")}
             shared_priority = priority
 
+        if (arr_type in role_tunings and role_tunings[arr_type] is None
+                and meta.get("tuning_offsets")):
+            role_tunings[arr_type] = list(meta["tuning_offsets"])
+
         arrangements.append({
             "type":     arr_type,
             "name":     arr_name,
@@ -281,6 +290,8 @@ def _detect_arrangements(path: Path) -> tuple[list[dict], dict]:
         a["index"] = i
         del a["priority"]
 
+    for role, offs in role_tunings.items():
+        shared_meta[f"{role}_tuning_offsets"] = offs
     return arrangements, shared_meta
 
 
@@ -412,6 +423,14 @@ def extract_meta(path: Path, dlc_root: Path | None = None) -> dict:
                                 xml_meta.get("duration", 0))
     tuning_offsets = _coerce_tuning_offsets(manifest.get("tuning_offsets"),
                                             xml_meta.get("tuning_offsets"))
+    # Per-role tunings: XML-derived only. A manifest `tuning_offsets` overrides
+    # the SONG tuning (above) but says nothing about WHICH chart it describes,
+    # so it must never be mistaken for a specific part's tuning.
+    role_tunings = {}
+    for role in ("bass", "rhythm"):
+        offs = xml_meta.get(f"{role}_tuning_offsets")
+        role_tunings[f"{role}_tuning_offsets"] = (
+            offs if isinstance(offs, list) and offs else None)
 
     manifest_arr = _validate_manifest_arrangements(manifest.get("arrangements"))
     if manifest_arr is not None:
@@ -427,6 +446,7 @@ def extract_meta(path: Path, dlc_root: Path | None = None) -> dict:
         "year":           year,
         "duration":       duration,
         "tuning_offsets": tuning_offsets,
+        **role_tunings,   # None = no arrangement in that role
         "arrangements":   arrangements,
         "audio_path":     str(audio) if audio else None,
         "art_path":       str(art)   if art   else None,

lib/lyrics_transcribe.py

@@ -23,9 +23,18 @@ Engine selection
 Two transcription paths share a common output:
 
 * `transcribe_vocals_remote(path, server_url, ...)` — POST the vocal
-  stem to the `/align` endpoint on a feedBack-demucs-server (got-feedBack's
-  reference server already hosts WhisperX alongside Demucs at the same
-  URL).
+  stem to the `/transcribe` endpoint on a feedBack-demucs-server
+  (got-feedBack's reference server already hosts WhisperX alongside
+  Demucs at the same URL).
+
+  It used to POST to `/align`, which is *forced alignment* — "here are
+  the lyrics, tell me when each word is sung". Its `text` field is
+  required and we have no lyrics (transcribing them is the point), so
+  the server answered 422 from FastAPI's validation layer before its
+  handler ran, and remote transcription never worked for anyone
+  (feedBack-plugin-stem-splitter#17). `/transcribe` takes only audio.
+  Requires feedBack-demucs-server ≥ the revision adding that endpoint;
+  an older server answers 404 and the error says so.
 
 * `transcribe_vocals_local(path, ...)` — load WhisperX in-process. Heavy
   (~3 GB of model weights for `large-v2` + the wav2vec2 aligner) and
@@ -416,6 +425,38 @@ def transcribe_vocals_local(
 
 # ── Remote transcription ────────────────────────────────────────────────────
 
+_MAX_ERR_BODY = 4000
+
+
+def _err_body(resp) -> str:
+    """The server's error body, whole if it plausibly is one, and marked when it isn't.
+
+    This was capped at 300 chars, which is enough for "Internal Server Error" and not much else.
+    The bodies carrying the most diagnosis are the long ones — a FastAPI validation body naming
+    the field it rejected, a 500 whose traceback answers on its LAST line — and those are exactly
+    the ones a 300-char cap decapitates. The cap survives so a server answering with a 2 MB HTML
+    error page can't dump a novel into a log line.
+    """
+    # Strip FIRST, then measure: a body that is 300 chars of JSON and 3900 of trailing whitespace
+    # is not a long body, and truncating it would cut real content to make room for blanks.
+    text = (getattr(resp, "text", "") or "").strip()
+    if len(text) <= _MAX_ERR_BODY:
+        return text
+
+    # Keep the HEAD **and the TAIL**. Head-only truncation throws away the exception line — and
+    # on a traceback the exception line is the answer. This docstring said as much while the code
+    # did the opposite: it cut off precisely the part it exists to preserve, which is the same
+    # mistake, one level up, as the 300-char cap it replaced.
+    #
+    # The marker sits inside the bound, not past it: otherwise _MAX_ERR_BODY is a suggestion, and
+    # the callers who trust it (a log line, a job record persisted to disk) are the ones surprised.
+    marker = f"\n… [truncated, {len(text)} chars total] …\n"
+    budget = max(0, _MAX_ERR_BODY - len(marker))
+    head = budget * 2 // 3          # context: what was being attempted
+    tail = budget - head            # verdict: what actually went wrong
+    return text[:head].rstrip() + marker + text[len(text) - tail:].lstrip()
+
+
 def transcribe_vocals_remote(
     vocals_path: Path,
     server_url: str,
@@ -426,7 +467,17 @@ def transcribe_vocals_remote(
     min_word_score: float = 0.35,
     progress_cb: ProgressCB = None,
 ) -> list[dict]:
-    """POST the vocal stem to `{server_url}/align` and parse the response.
+    """POST the vocal stem to `{server_url}/transcribe` and parse the response.
+
+    NOT `/align` — that endpoint is forced alignment ("here are the lyrics,
+    tell me when each word is sung") and its `text` field is required. We
+    have no lyrics; producing them is the point. Posting there returned a
+    422 from FastAPI's validation layer before the server's handler ran, so
+    remote transcription never worked at all
+    (feedBack-plugin-stem-splitter#17).
+
+    Requires a feedBack-demucs-server carrying `/transcribe`; an older one
+    answers 404 and the raised error says so.
 
     Expects the server to respond with a JSON object carrying a `words` (or
     `segments`) field in WhisperX's native shape; `_whisperx_to_sloppak`
@@ -454,21 +505,53 @@ def transcribe_vocals_remote(
     if api_key:
         headers["Authorization"] = f"Bearer {api_key}"
 
-    params: dict[str, str] = {}
+    # POST to /transcribe, not /align.
+    #
+    # /align is FORCED ALIGNMENT: "here are the lyrics, tell me when each word is sung". Its
+    # `text` field is required, and we have no lyrics — transcription is the whole point. So the
+    # server rejected every request with a 422 in FastAPI's validation layer, before its handler
+    # ever ran, and remote transcription has never worked for anyone. /transcribe answers the
+    # question we are actually asking and takes only the audio.
+    # (feedBack-plugin-stem-splitter#17; endpoint added in feedBack-demucs-server#14.)
+    #
+    # `language` goes in the FORM BODY, not the query string: the server reads it with
+    # Form(""), and a query param would be silently ignored — so an explicit language hint would
+    # do nothing and Whisper's auto-detection would quietly decide instead, which is exactly the
+    # kind of "it works but it's wrong" that hides for months.
+    form: dict[str, str] = {}
     if language:
-        params["language"] = language
+        form["language"] = language
 
-    with open(vocals_path, "rb") as f:
-        resp = requests.post(
-            f"{server_url}/align",
-            files={"file": (vocals_path.name, f, "audio/ogg")},
-            params=params,
-            headers=headers or None,
-            timeout=timeout,
+    # Everything that can go wrong out here comes back as RuntimeError, which is what the
+    # docstring promises and what the caller catches. A DNS failure, a timeout, a reset
+    # connection or an unreadable stem file would otherwise surface as requests.RequestException
+    # or OSError and escape the one handler written to log-and-continue — turning "this song's
+    # lyrics failed" into "the whole batch died".
+    try:
+        with open(vocals_path, "rb") as f:
+            resp = requests.post(
+                f"{server_url}/transcribe",
+                files={"file": (vocals_path.name, f, "audio/ogg")},
+                data=form or None,
+                headers=headers or None,
+                timeout=timeout,
+            )
+    except requests.RequestException as e:
+        raise RuntimeError(f"could not reach the WhisperX server at {server_url}: {e}") from e
+    except OSError as e:
+        raise RuntimeError(f"could not read the vocal stem {vocals_path.name}: {e}") from e
+
+    if resp.status_code == 404:
+        # The endpoint isn't there. Say what that means, because "404" on its own sends someone
+        # hunting for a typo in their URL when the real answer is that their server predates the
+        # feature. (feedBack-demucs-server#14 added /transcribe.)
+        raise RuntimeError(
+            f"the WhisperX server at {server_url} has no /transcribe endpoint (404) — it "
+            f"predates remote transcription support. Update the server, or use 'Check for "
+            f"update' if it is the plugin-managed one."
         )
-
     if resp.status_code != 200:
-        raise RuntimeError(f"WhisperX server error ({resp.status_code}): {resp.text[:300]}")
+        raise RuntimeError(f"WhisperX server error ({resp.status_code}): {_err_body(resp)}")
 
     data = resp.json()
 

lib/metadata_db.py

@@ -25,6 +25,8 @@ import time
 from pathlib import Path
 
 from song import compute_smart_names
+from tunings import DEFAULT_PERSPECTIVE, ROLE_PERSPECTIVES
+from tunings import perspective as _perspective
 
 log = logging.getLogger("feedBack.server")
 
@@ -34,13 +36,91 @@ log = logging.getLogger("feedBack.server")
 # raw offsets so distinct customs stay distinct, while named tunings keep
 # grouping by name (stable across the offsets-column migration). Used by both
 # the tuning-names listing and the filter WHERE so the contract matches.
-def _tuning_group_key_sql(alias: str) -> str:
-    """The tuning grouping key (name for named tunings, raw offsets for
-    customs) against an explicit table alias — the grouped filter law (§7.1)
-    evaluates chart-intrinsic predicates inside a member subquery, where bare
-    column names would resolve against the wrong scope."""
-    return (f"CASE WHEN {alias}.tuning_name = 'Custom Tuning' AND COALESCE({alias}.tuning_offsets, '') != '' "
-            f"THEN {alias}.tuning_offsets ELSE {alias}.tuning_name END")
+#
+# A non-default PERSPECTIVE (guitar-rhythm / bass) swaps every tuning column
+# for its EFFECTIVE expression: that role's indexed tuning when the song has
+# such an arrangement, falling back to the guitar-derived song tuning
+# otherwise — so a song with no rhythm/bass chart (or a row that predates the
+# columns, NULL there) still groups/filters/sorts instead of disappearing.
+# guitar-lead reads the original unprefixed columns, so it is byte-identical
+# to the historical behaviour.
+def _effective_tuning_cols_sql(alias: str, perspective: str = DEFAULT_PERSPECTIVE) -> tuple[str, str, str]:
+    """(name_sql, offsets_sql, sort_key_sql) for the given perspective."""
+    persp = _perspective(perspective)
+    if not persp.column_prefix:
+        return (f"{alias}.tuning_name", f"{alias}.tuning_offsets", f"{alias}.tuning_sort_key")
+    has_own = f"COALESCE({alias}.{persp.column('name')}, '') != ''"
+    return (
+        f"COALESCE(NULLIF({alias}.{persp.column('name')}, ''), {alias}.tuning_name)",
+        f"CASE WHEN {has_own} THEN {alias}.{persp.column('offsets')} ELSE {alias}.tuning_offsets END",
+        f"CASE WHEN {has_own} THEN {alias}.{persp.column('sort_key')} ELSE {alias}.tuning_sort_key END",
+    )
+
+
+def _effective_low_pitch_sql(alias: str, perspective: str = DEFAULT_PERSPECTIVE) -> str:
+    """Lowest open-string MIDI pitch under this perspective, with the same
+    fallback as the tuning columns — the "playable without retuning"
+    comparison reads it (see tunings.chart_is_playable_in)."""
+    persp = _perspective(perspective)
+    if not persp.column_prefix:
+        return f"{alias}.tuning_low_pitch"
+    has_own = f"COALESCE({alias}.{persp.column('name')}, '') != ''"
+    return (f"CASE WHEN {has_own} THEN {alias}.{persp.column('low_pitch')} "
+            f"ELSE {alias}.tuning_low_pitch END")
+
+
+def _perspective_is_inferred_sql(alias: str, perspective: str) -> str:
+    """1 when this row is BORROWING the guitar-derived song tuning because it
+    has no chart in the perspective's role. Always 0 for guitar-lead, which is
+    never a fallback."""
+    persp = _perspective(perspective)
+    if not persp.column_prefix:
+        return "0"
+    return f"(CASE WHEN COALESCE({alias}.{persp.column('name')}, '') = '' THEN 1 ELSE 0 END)"
+
+
+# ── The custom-tuning group key ──────────────────────────────────────────────
+#
+# Named tunings group by NAME, which is already serialization-agnostic. Custom
+# tunings group on a raw offsets STRING, which is not: the same physical bass
+# tuning stored as "-2 0 0 0" and "-2 0 0 0 0 0" would fragment into two facet
+# rows with split counts.
+#
+# For BASS we therefore group customs on `bass_tuning_key` — the tuning's
+# absolute open-string PITCHES, computed once at scan time
+# (tunings.bass_tuning_key) after the padded tail is truncated away. Pitch is
+# the identity that matters musically and it is serialization-independent, so
+# one physical tuning is one entry however it was authored. Guitar keeps the
+# offsets string (unchanged; six-element guitar arrays are not padded).
+#
+# The key is built HERE, once, and read by the facet listing, the filter WHERE
+# and the grouped member-match alike — a facet row that selected a different
+# set than it counted is exactly the bug this shared expression prevents.
+def _tuning_group_key_sql(alias: str, perspective: str = DEFAULT_PERSPECTIVE) -> str:
+    """The tuning grouping key (name for named tunings, canonical pitches or
+    raw offsets for customs) against an explicit table alias — the grouped
+    filter law (§7.1) evaluates chart-intrinsic predicates inside a member
+    subquery, where bare column names would resolve against the wrong scope."""
+    persp = _perspective(perspective)
+    name_sql, offsets_sql, _ = _effective_tuning_cols_sql(alias, perspective)
+    if persp.column_prefix:
+        # Fall back to the offsets string when the canonical key is absent
+        # (a fallback row borrowing the guitar tuning, or a row scanned before
+        # the key column existed) so a custom never groups under an empty key.
+        offsets_sql = (f"COALESCE(NULLIF({alias}.{persp.column('key')}, ''), "
+                       f"{offsets_sql})")
+    return (f"CASE WHEN {name_sql} = 'Custom Tuning' AND COALESCE({offsets_sql}, '') != '' "
+            f"THEN {offsets_sql} ELSE {name_sql} END")
+
+
+def _put_perspective_value(meta: dict, col: str):
+    """Value to store for one per-perspective column on a freshly-scanned row."""
+    if col.endswith("_low_pitch"):
+        val = meta.get(col)
+        return int(val) if isinstance(val, int) else None
+    if col.endswith("_sort_key"):
+        return int(meta.get(col, 0) or 0)
+    return meta.get(col, "") or ""
 
 
 # ── SQLite metadata cache ─────────────────────────────────────────────────────
@@ -381,7 +461,18 @@ class MetadataDB:
                 tuning_offsets TEXT DEFAULT '',
                 genre TEXT DEFAULT '',
                 track_number INTEGER,
-                disc INTEGER
+                disc INTEGER,
+                bass_tuning_name TEXT,
+                bass_tuning_sort_key INTEGER,
+                bass_tuning_offsets TEXT,
+                bass_tuning_key TEXT,
+                bass_tuning_low_pitch INTEGER,
+                rhythm_tuning_name TEXT,
+                rhythm_tuning_sort_key INTEGER,
+                rhythm_tuning_offsets TEXT,
+                rhythm_tuning_key TEXT,
+                rhythm_tuning_low_pitch INTEGER,
+                tuning_low_pitch INTEGER
             )
         """)
         # Idempotent migrations for installs that predate each column.
@@ -408,6 +499,32 @@ class MetadataDB:
             # falls back to title order. Cache; repopulated on rescan.
             "ALTER TABLE songs ADD COLUMN track_number INTEGER",
             "ALTER TABLE songs ADD COLUMN disc INTEGER",
+            # Bass-arrangement tuning (the KwasimodoZAZA report): the song-level
+            # tuning columns above are guitar-first, so the library filter lied
+            # to bass players when the bass chart is tuned differently. Caches;
+            # repopulated on rescan. NULL (no literal default) is deliberate —
+            # it marks a pre-migration row the scanner must re-extract, while
+            # '' means "extracted, song has no bass arrangement" (see scan.py).
+            "ALTER TABLE songs ADD COLUMN bass_tuning_name TEXT",
+            "ALTER TABLE songs ADD COLUMN bass_tuning_sort_key INTEGER",
+            "ALTER TABLE songs ADD COLUMN bass_tuning_offsets TEXT",
+            # Canonical grouping key: the bass tuning's absolute open-string
+            # pitches. Keyed on PITCH, not the serialization-dependent offsets
+            # string, so one physical tuning is one facet entry however it was
+            # stored. See tunings.bass_tuning_key.
+            "ALTER TABLE songs ADD COLUMN bass_tuning_key TEXT",
+            # Lowest open-string MIDI pitch per perspective — the "playable
+            # without retuning" comparison (tunings.chart_is_playable_in).
+            "ALTER TABLE songs ADD COLUMN bass_tuning_low_pitch INTEGER",
+            "ALTER TABLE songs ADD COLUMN tuning_low_pitch INTEGER",
+            # The RHYTHM chart's own tuning: lead and rhythm arrangements can
+            # be tuned differently, which is the same bug a bassist hit,
+            # inside guitar. Same NULL-vs-'' contract as the bass family.
+            "ALTER TABLE songs ADD COLUMN rhythm_tuning_name TEXT",
+            "ALTER TABLE songs ADD COLUMN rhythm_tuning_sort_key INTEGER",
+            "ALTER TABLE songs ADD COLUMN rhythm_tuning_offsets TEXT",
+            "ALTER TABLE songs ADD COLUMN rhythm_tuning_key TEXT",
+            "ALTER TABLE songs ADD COLUMN rhythm_tuning_low_pitch INTEGER",
         ):
             try:
                 self.conn.execute(ddl)
@@ -2810,16 +2927,39 @@ class MetadataDB:
     def favorite_set(self) -> set[str]:
         return {r[0] for r in self.conn.execute("SELECT filename FROM favorites").fetchall()}
 
+    # Every per-perspective column, in one place, so the SELECT, the INSERT and
+    # the scanner's "was this ever extracted?" check can never drift apart.
+    # NULL is meaningful on `name`/`key`/`low_pitch`: it marks a row written
+    # before the column existed, which the scanner re-extracts (see
+    # scan._has_unextracted_columns). '' / 0 means "extracted, no such chart".
+    _PERSPECTIVE_COLS = tuple(
+        p.column(suffix)
+        for p in ROLE_PERSPECTIVES
+        for suffix in ("name", "sort_key", "offsets", "key", "low_pitch")
+    ) + ("tuning_low_pitch",)
+    # Columns whose NULL means "never extracted" rather than "no such chart".
+    #
+    # low_pitch is deliberately NOT a marker: a song with no chart in that role
+    # legitimately has NULL there (nothing to compute a pitch from), so keying
+    # re-extraction on it would re-scan those rows on every single pass and
+    # never converge. `name` and `key` carry the signal instead — they are ''
+    # when extracted-but-absent, NULL only when the column predates the row.
+    _EXTRACTION_MARKER_COLS = tuple(
+        p.column(suffix) for p in ROLE_PERSPECTIVES for suffix in ("name", "key")
+    )
+
     def get(self, filename: str, mtime: float, size: int) -> dict | None:
         cache_key = str(filename)
+        pcols = ", ".join(self._PERSPECTIVE_COLS)
         with self._lock:
             row = self.conn.execute(
                 "SELECT mtime, size, title, artist, album, year, duration, tuning, arrangements, has_lyrics, "
-                "format, stem_count, stem_ids, tuning_name, tuning_sort_key, tuning_offsets "
+                "format, stem_count, stem_ids, tuning_name, tuning_sort_key, tuning_offsets, "
+                f"{pcols} "
                 "FROM songs WHERE filename = ?", (cache_key,)
             ).fetchone()
         if row and row[0] == mtime and row[1] == size and row[2]:
-            return {
+            out = {
                 "title": row[2], "artist": row[3], "album": row[4],
                 "year": row[5], "duration": row[6], "tuning": row[7],
                 "arrangements": json.loads(row[8]) if row[8] else [],
@@ -2831,6 +2971,15 @@ class MetadataDB:
                 "tuning_sort_key": int(row[14] or 0),
                 "tuning_offsets": row[15] or "",
             }
+            for i, col in enumerate(self._PERSPECTIVE_COLS, start=16):
+                val = row[i]
+                if col in self._EXTRACTION_MARKER_COLS:
+                    out[col] = val          # NULL preserved — drives re-extraction
+                elif col.endswith("_sort_key"):
+                    out[col] = int(val or 0)
+                else:
+                    out[col] = val or ""
+            return out
         return None
 
     def put(self, filename: str, mtime: float, size: int, meta: dict):
@@ -2838,8 +2987,9 @@ class MetadataDB:
             self.conn.execute(
                 "INSERT OR REPLACE INTO songs "
                 "(filename, mtime, size, title, artist, album, year, duration, tuning, arrangements, "
-                "has_lyrics, format, stem_count, stem_ids, tuning_name, tuning_sort_key, tuning_offsets, genre, track_number, disc) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                "has_lyrics, format, stem_count, stem_ids, tuning_name, tuning_sort_key, tuning_offsets, genre, track_number, disc, "
+                + ", ".join(self._PERSPECTIVE_COLS) + ") "
+                "VALUES (" + ", ".join(["?"] * (20 + len(self._PERSPECTIVE_COLS))) + ")",
                 (filename, mtime, size, meta.get("title", ""), meta.get("artist", ""),
                  meta.get("album", ""), meta.get("year", ""), meta.get("duration", 0),
                  meta.get("tuning", ""), json.dumps(meta.get("arrangements", [])),
@@ -2852,7 +3002,14 @@ class MetadataDB:
                  meta.get("tuning_offsets", "") or "",
                  meta.get("genre", "") or "",
                  meta.get("track_number"),
-                 meta.get("disc")),
+                 meta.get("disc"),
+                 # A put() row is by definition freshly extracted, so the
+                 # marker columns must never be written NULL — that state is
+                 # reserved for rows predating the column, which re-extract.
+                 # low_pitch is the exception: NULL there means "this tuning
+                 # has no computable pitch" (unusable offsets), and the
+                 # playable filter treats unknown as not-playable.
+                 *[_put_perspective_value(meta, col) for col in self._PERSPECTIVE_COLS]),
             )
             self.conn.commit()
             # A song's identity may have changed → the grouping read-model is stale.
@@ -3332,6 +3489,8 @@ class MetadataDB:
                      match_states: list[str] | None = None,
                      genre: list[str] | None = None,
                      naming_mode: str = "legacy",
+                     instrument: str = DEFAULT_PERSPECTIVE,
+                     playable_from_pitch: int | None = None,
                      include_intrinsic: bool = True) -> tuple[str, list]:
         """Shared WHERE-clause builder for query_page / query_artists /
         query_stats. Returns (where_sql, params). Leading 'WHERE' is
@@ -3438,7 +3597,8 @@ class MetadataDB:
                 "songs", format_filter=format_filter,
                 arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
                 stems_has=stems_has, stems_lacks=stems_lacks,
-                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode)
+                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode,
+                instrument=instrument, playable_from_pitch=playable_from_pitch)
             where += ifrag
             params += iparams
         return where, params
@@ -3450,7 +3610,9 @@ class MetadataDB:
                                stems_lacks: list[str] | None = None,
                                has_lyrics: int | None = None,
                                tunings: list[str] | None = None,
-                               naming_mode: str = "legacy") -> tuple[str, list]:
+                               naming_mode: str = "legacy",
+                               instrument: str = DEFAULT_PERSPECTIVE,
+                               playable_from_pitch: int | None = None) -> tuple[str, list]:
         """CHART-INTRINSIC predicates (format / arrangements / stems / lyrics /
         tuning) as ' AND …' fragments against an explicit table alias. Flat
         queries apply them to `songs` directly; grouped queries evaluate them
@@ -3593,10 +3755,32 @@ class MetadataDB:
                 placeholders = ",".join(["?"] * len(tn))
                 # Match the same grouping key tuning_names() returns so a single
                 # "Custom Tuning" pill selects exactly its offset set while named
-                # tunings still match by name.
-                where += (f" AND {_tuning_group_key_sql(alias)} "
+                # tunings still match by name. `instrument` swaps in the
+                # effective bass tuning key (guitar fallback) — the facet and
+                # this WHERE must use the same expression or they disagree.
+                where += (f" AND {_tuning_group_key_sql(alias, instrument)} "
                           f"COLLATE NOCASE IN ({placeholders})")
                 params += tn
+        if playable_from_pitch is not None:
+            # "Playable without retuning" — the mode the tester actually wants
+            # ("don't make me retune"), offered ALONGSIDE exact match, not
+            # instead of it. A chart needs no retune when its lowest required
+            # pitch is reachable, and every pitch above your lowest open string
+            # is reachable by fretting, so the comparison is:
+            #
+            #     your lowest open pitch <= the chart's lowest open pitch
+            #
+            # That is why a 5-string bass (low B) covers every 4-string
+            # standard AND every drop-D chart untouched.
+            #
+            # CONSERVATIVE BY CONSTRUCTION: a chart whose low pitch we could
+            # not compute (NULL) is EXCLUDED rather than assumed playable —
+            # wrongly claiming playability costs a mid-practice retune, which
+            # is the failure this whole feature exists to prevent. See
+            # tunings.chart_is_playable_in for the full reasoning + limits.
+            low_sql = _effective_low_pitch_sql(alias, instrument)
+            where += f" AND {low_sql} IS NOT NULL AND {low_sql} >= ?"
+            params.append(int(playable_from_pitch))
         return where, params
 
     # Under group=1, chart-intrinsic filters match if ANY member of the work
@@ -3864,7 +4048,9 @@ class MetadataDB:
                    genre: list[str] | None = None,
                    after: str | None = None,
                    group: bool = False,
-                   naming_mode: str = "legacy") -> tuple[list[dict], int]:
+                   naming_mode: str = "legacy",
+                   instrument: str = DEFAULT_PERSPECTIVE,
+                   playable_from_pitch: int | None = None) -> tuple[list[dict], int]:
         """Server-side paginated search. Returns (songs, total_count).
 
         `after` is an opaque keyset cursor (the last row of the previous page).
@@ -3893,7 +4079,9 @@ class MetadataDB:
             has_lyrics=has_lyrics, tunings=tunings, mastery=mastery,
             tags_has=tags_has, user_difficulty_in=user_difficulty_in,
             match_states=match_states, genre=genre,
-            naming_mode=naming_mode, include_intrinsic=not group,
+            naming_mode=naming_mode, instrument=instrument,
+            playable_from_pitch=playable_from_pitch,
+            include_intrinsic=not group,
         )
         ifrag, iparams = "", []
         if group:
@@ -3902,12 +4090,14 @@ class MetadataDB:
                 "m", format_filter=format_filter,
                 arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
                 stems_has=stems_has, stems_lacks=stems_lacks,
-                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode)
+                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode,
+                instrument=instrument, playable_from_pitch=playable_from_pitch)
             mfrag, mparams = self._grouped_member_match(ifrag, iparams)
             where += mfrag
             params += mparams
             where += self._GROUP_REP_PREDICATE
 
+        _eff_tuning_name, _, _eff_tuning_sort = _effective_tuning_cols_sql("songs", instrument)
         sort_map = {
             # Artist sorts order WITHIN an artist by title (the tree view's
             # artist -> album -> title feel) instead of raw filename — the
@@ -3941,11 +4131,15 @@ class MetadataDB:
             # behind, and a NULL `tuning_name` in `(tuning_name = '')`
             # evaluates to NULL itself (which sorts ahead of 0 in
             # ASC), defeating the push-to-bottom intent.
+            #
+            # Under `instrument=bass` the effective expressions swap in
+            # the bass arrangement's tuning (guitar fallback) so a bass
+            # player's tuning sort orders by the tuning they'd play.
             "tuning": (
-                "(COALESCE(tuning_name, '') = '') ASC, "
-                "ABS(COALESCE(tuning_sort_key, 0)), "
-                "COALESCE(tuning_sort_key, 0) ASC, "
-                "COALESCE(tuning_name, '') COLLATE NOCASE"
+                f"(COALESCE({_eff_tuning_name}, '') = '') ASC, "
+                f"ABS(COALESCE({_eff_tuning_sort}, 0)), "
+                f"COALESCE({_eff_tuning_sort}, 0) ASC, "
+                f"COALESCE({_eff_tuning_name}, '') COLLATE NOCASE"
             ),
             # Year sort (feedBack#128). Empty-year rows pushed to the
             # bottom for both directions; otherwise CAST so '2010' >
@@ -4038,7 +4232,9 @@ class MetadataDB:
 
             cols = ("SELECT filename, title, artist, album, year, duration, tuning, "
                     "arrangements, has_lyrics, mtime, format, stem_count, stem_ids, "
-                    "tuning_name, tuning_offsets FROM songs ")
+                    "tuning_name, tuning_offsets, bass_tuning_name, bass_tuning_offsets, "
+                    "rhythm_tuning_name, rhythm_tuning_offsets "
+                    "FROM songs ")
             cursor = _decode_cursor(after) if after else None
             eff_sort = _effective_keyset_sort(sort, direction)
             if cursor and eff_sort in _KEYSET_SORTS:
@@ -4071,8 +4267,30 @@ class MetadataDB:
                 "stem_ids": json.loads(r[12]) if r[12] else [],
                 "tuning_name": r[13] or "",
                 "tuning_offsets": r[14] or "",
+                # '' when the song has no bass arrangement (or the row predates
+                # '' when the song has no such chart (or the row predates the
+                # columns) — clients fall back to tuning_name.
+                "bass_tuning_name": r[15] or "",
+                "bass_tuning_offsets": r[16] or "",
+                "rhythm_tuning_name": r[17] or "",
+                "rhythm_tuning_offsets": r[18] or "",
                 "has_estd": r[0] in estd, "favorite": r[0] in favs,
             })
+        # PROVENANCE (non-default perspectives): a row shown to a bass or
+        # rhythm player either carries that chart's own tuning (native) or is
+        # borrowing the guitar-derived song tuning (inferred). The fallback is
+        # deliberate — a third of a real library has no bass chart and
+        # excluding it would be worse — but it must never be SILENT, or we
+        # reproduce the original bug in a new place. The client marks inferred
+        # rows; it can't infer this itself without duplicating the COALESCE.
+        #
+        # guitar-lead adds NOTHING here, so the default payload is unchanged.
+        _persp = _perspective(instrument)
+        if _persp.column_prefix:
+            _name_key = _persp.column("name")
+            for s in songs:
+                s["tuning_perspective"] = _persp.id
+                s["tuning_inferred"] = not s.get(_name_key)
         # Personal layer (difficulty + tags) rides along like `favorite`, so a
         # card can badge it without a second request. Notes stay OUT of the list
         # payload (they can be long) — fetch per-song via /user-meta. Batched to
@@ -4169,7 +4387,7 @@ class MetadataDB:
         rows = self.conn.execute(
             "SELECT mw.effective_work_key, m.filename, m.title, m.duration, m.tuning, "
             "m.arrangements, m.has_lyrics, m.mtime, m.format, m.stem_count, m.stem_ids, "
-            "m.tuning_name, m.tuning_offsets "
+            "m.tuning_name, m.tuning_offsets, m.bass_tuning_name, m.bass_tuning_offsets "
             "FROM songs m JOIN work_display mw ON mw.filename = m.filename "
             f"WHERE mw.effective_work_key IN ({ph}){intrinsic_frag} "
             "ORDER BY mw.is_group_representative DESC, m.mtime DESC, m.filename",
@@ -4190,6 +4408,7 @@ class MetadataDB:
                 "stem_count": int(m[9] or 0),
                 "stem_ids": json.loads(m[10]) if m[10] else [],
                 "tuning_name": m[11] or "", "tuning_offsets": m[12] or "",
+                "bass_tuning_name": m[13] or "", "bass_tuning_offsets": m[14] or "",
             }
 
     def query_artists(self, letter: str = "", q: str = "",
@@ -4204,7 +4423,9 @@ class MetadataDB:
                       stems_lacks: list[str] | None = None,
                       has_lyrics: int | None = None,
                       tunings: list[str] | None = None,
-                      naming_mode: str = "legacy") -> tuple[list[dict], int]:
+                      naming_mode: str = "legacy",
+                      instrument: str = DEFAULT_PERSPECTIVE,
+                      playable_from_pitch: int | None = None) -> tuple[list[dict], int]:
         """Get artists grouped by letter with their albums and songs. Returns (artists, total_artists)."""
         where, params = self._build_where(
             q=q, favorites_only=favorites_only, format_filter=format_filter,
@@ -4212,6 +4433,7 @@ class MetadataDB:
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
             has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode,
+            instrument=instrument, playable_from_pitch=playable_from_pitch,
         )
         # Canonicalize artists at display when aliases exist (P4): dedupe / group /
         # letter / order on the EFFECTIVE artist so "ACDC" + "AC/DC" list as one
@@ -4247,7 +4469,7 @@ class MetadataDB:
 
         rows = self.conn.execute(
             f"SELECT filename, title, ({art_expr}) as artist, album, year, duration, tuning, arrangements, has_lyrics, "
-            f"format, stem_count, stem_ids, tuning_name "
+            f"format, stem_count, stem_ids, tuning_name, bass_tuning_name "
             f"FROM songs {song_where} ORDER BY ({art_expr}) COLLATE NOCASE, album COLLATE NOCASE, title COLLATE NOCASE",
             song_params
         ).fetchall()
@@ -4280,6 +4502,7 @@ class MetadataDB:
                 "stem_count": int(r[10] or 0),
                 "stem_ids": json.loads(r[11]) if r[11] else [],
                 "tuning_name": r[12] or "",
+                "bass_tuning_name": r[13] or "",
                 "has_estd": r[0] in estd,
                 "favorite": r[0] in favs,
                 "user_difficulty": udm.get(r[0]),
@@ -4301,7 +4524,8 @@ class MetadataDB:
                      stems_has=None, stems_lacks=None,
                      has_lyrics=None, tunings=None, mastery=None,
                      match_states=None, genre=None,
-                     naming_mode="legacy", page=0, size=120):
+                     naming_mode="legacy", instrument=DEFAULT_PERSPECTIVE,
+                     playable_from_pitch=None, page=0, size=120):
         """Distinct (artist, album) groups with a track count + a representative
         cover song, for the album-condensed browse (paged by album). Rows with no
         album name are excluded -- they can't form an album card. Same filters as
@@ -4313,7 +4537,8 @@ class MetadataDB:
             stems_has=stems_has, stems_lacks=stems_lacks,
             has_lyrics=has_lyrics, tunings=tunings, mastery=mastery,
             match_states=match_states, genre=genre,
-            naming_mode=naming_mode,
+            naming_mode=naming_mode, instrument=instrument,
+            playable_from_pitch=playable_from_pitch,
         )
         awhere = where + " AND album IS NOT NULL AND album != ''"
         total = self.conn.execute(
@@ -4344,7 +4569,9 @@ class MetadataDB:
                     sort: str = "artist",
                     want_sort_letters: bool = False,
                     group: bool = False,
-                    naming_mode: str = "legacy") -> dict:
+                    naming_mode: str = "legacy",
+                    instrument: str = DEFAULT_PERSPECTIVE,
+                    playable_from_pitch: int | None = None) -> dict:
         """Aggregate stats for the letter bar. Accepts the same filter
         params as query_page so the letter counts stay synchronized
         with the grid when filters are active.
@@ -4371,7 +4598,8 @@ class MetadataDB:
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
             has_lyrics=has_lyrics, tunings=tunings, match_states=match_states,
-            naming_mode=naming_mode,
+            naming_mode=naming_mode, instrument=instrument,
+            playable_from_pitch=playable_from_pitch,
             include_intrinsic=not group,
         )
         if group:
@@ -4383,7 +4611,8 @@ class MetadataDB:
                 "m", format_filter=format_filter,
                 arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
                 stems_has=stems_has, stems_lacks=stems_lacks,
-                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode)
+                has_lyrics=has_lyrics, tunings=tunings, naming_mode=naming_mode,
+                instrument=instrument, playable_from_pitch=playable_from_pitch)
             mfrag, mparams = self._grouped_member_match(ifrag, iparams)
             where += mfrag
             params += mparams

lib/routers/library.py

@@ -19,7 +19,7 @@ from starlette.concurrency import run_in_threadpool
 
 import appstate
 from library_registry import (
-    _library_filter_args, _sanitize_collection_rules,
+    _library_filter_args, _normalize_instrument, _sanitize_collection_rules,
     _safe_art_redirect_url, _split_csv, _sync_collection_provider,
     _unregister_collection_provider,
 )
@@ -52,7 +52,8 @@ def _require_library_provider_capability(provider: object, capability: str) -> N
 
 
 _OPTIONAL_NEW_PROVIDER_KWARGS = ("naming_mode", "sort", "want_sort_letters", "after",
-                                 "mastery", "match_states")
+                                 "mastery", "match_states", "instrument",
+                                 "playable_from_pitch")
 
 
 def _filter_provider_kwargs(method: object, kwargs: dict) -> dict:
@@ -235,9 +236,20 @@ async def list_library(q: str = "", page: int = 0, size: int = 24, sort: str = "
                        has_lyrics: str = "", tunings: str = "", provider: str = "local",
                        mastery: str = "", tags: str = "", user_difficulty: str = "",
                        match: str = "", genre: str = "", after: str = "", group: int = 0,
-                       naming_mode: str = "legacy"):
+                       naming_mode: str = "legacy", instrument: str = "",
+                       tuning_match: str = "", playable_offsets: str = "",
+                       playable_instrument: str = "", playable_string_count: str = ""):
     """Paginated library search through the selected library provider.
 
+    `instrument` is the tuning PERSPECTIVE ("guitar-lead" default |
+    "guitar-rhythm" | "bass"): which arrangement's tuning the tuning
+    filter/sort speaks for, with a guitar fallback when a song has no chart in
+    that role.
+
+    `tuning_match=playable` switches the tuning filter from exact-match to
+    "playable without retuning" against the caller's current tuning
+    (`playable_offsets` + `playable_instrument` + `playable_string_count`).
+
     `after` is an opaque keyset cursor (feedBack#636 item 3): pass back the
     `next_cursor` from the previous response to fetch the next page with a
     WHERE-seek instead of OFFSET. Providers that don't support it ignore it and
@@ -270,7 +282,10 @@ async def list_library(q: str = "", page: int = 0, size: int = 24, sort: str = "
             artist=artist, album=album,
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
-            has_lyrics=has_lyrics, tunings=tunings,
+            has_lyrics=has_lyrics, tunings=tunings, instrument=instrument,
+            tuning_match=tuning_match, playable_offsets=playable_offsets,
+            playable_instrument=playable_instrument,
+            playable_string_count=playable_string_count,
         ),
     )
     # The cursor to resume after this page (effective sort folds in dir=desc).
@@ -292,7 +307,7 @@ async def list_library_albums(q: str = "", page: int = 0, size: int = 120,
                               stems_has: str = "", stems_lacks: str = "",
                               has_lyrics: str = "", tunings: str = "", mastery: str = "",
                               match: str = "", genre: str = "",
-                              provider: str = "local"):
+                              provider: str = "local", instrument: str = ""):
     """Album-condensed browse: distinct (artist, album) groups with a track count
     and a representative cover song. Paged by album. Same filters as /api/library."""
     size = min(size, 500)
@@ -306,7 +321,7 @@ async def list_library_albums(q: str = "", page: int = 0, size: int = 120,
             q=q, favorites=favorites, format=format, artist=artist, album=album,
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
-            has_lyrics=has_lyrics, tunings=tunings,
+            has_lyrics=has_lyrics, tunings=tunings, instrument=instrument,
         ),
     )
     return {"albums": albums, "total": total, "page": page, "size": size}
@@ -319,7 +334,9 @@ async def list_artists(letter: str = "", q: str = "", favorites: int = 0, page:
                        arrangements_has: str = "", arrangements_lacks: str = "",
                        stems_has: str = "", stems_lacks: str = "",
                        has_lyrics: str = "", tunings: str = "", provider: str = "local",
-                       naming_mode: str = "legacy"):
+                       naming_mode: str = "legacy", instrument: str = "",
+                       tuning_match: str = "", playable_offsets: str = "",
+                       playable_instrument: str = "", playable_string_count: str = ""):
     """Get artists grouped by letter with albums and songs (for tree view)."""
     size = min(size, 100)
     library_provider = _get_library_provider(provider)
@@ -336,7 +353,7 @@ async def list_artists(letter: str = "", q: str = "", favorites: int = 0, page:
             artist=artist, album=album,
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
-            has_lyrics=has_lyrics, tunings=tunings,
+            has_lyrics=has_lyrics, tunings=tunings, instrument=instrument,
         ),
     )
     return {"artists": artists, "total_artists": total, "page": page, "size": size}
@@ -350,7 +367,10 @@ async def library_stats(favorites: int = 0, q: str = "", format: str = "",
                         has_lyrics: str = "", tunings: str = "", provider: str = "local",
                         match: str = "",
                         sort: str = "artist", sort_letters: int = 0,
-                        group: int = 0, naming_mode: str = "legacy"):
+                        group: int = 0, naming_mode: str = "legacy",
+                        instrument: str = "", tuning_match: str = "",
+                        playable_offsets: str = "", playable_instrument: str = "",
+                        playable_string_count: str = ""):
     """Aggregate stats for the UI. Accepts the same filter params as
     /api/library so the letter bar mirrors the active grid filter set.
     `sort` selects the column the jump rail's `sort_letters` keys on;
@@ -375,7 +395,10 @@ async def library_stats(favorites: int = 0, q: str = "", format: str = "",
             artist=artist, album=album,
             arrangements_has=arrangements_has, arrangements_lacks=arrangements_lacks,
             stems_has=stems_has, stems_lacks=stems_lacks,
-            has_lyrics=has_lyrics, tunings=tunings,
+            has_lyrics=has_lyrics, tunings=tunings, instrument=instrument,
+            tuning_match=tuning_match, playable_offsets=playable_offsets,
+            playable_instrument=playable_instrument,
+            playable_string_count=playable_string_count,
         ),
     )
 
@@ -407,14 +430,20 @@ def library_genres(provider: str = "local"):
 
 
 @router.get("/api/library/tuning-names")
-async def list_tuning_names(provider: str = "local"):
+async def list_tuning_names(provider: str = "local", instrument: str = ""):
     """Distinct tuning names present in the library, with per-tuning
     counts. Powers the tuning multi-select. Sorted by `tuning_sort_key`
     so names appear in the same musical order the sort uses
-    (feedBack#22) — E Standard first, then nearest neighbors."""
+    (feedBack#22) — E Standard first, then nearest neighbors.
+
+    `instrument=bass` groups by each song's bass-arrangement tuning
+    (guitar-derived fallback for songs without a bass chart) so bass
+    players see the tunings they'd actually play. Providers that predate
+    the kwarg simply don't receive it (signature-filtered)."""
     library_provider = _get_library_provider(provider)
     _require_library_provider_capability(library_provider, "library.read")
-    return await _call_library_provider_async(library_provider, "tuning_names")
+    return await _call_library_provider_async(
+        library_provider, "tuning_names", instrument=_normalize_instrument(instrument))
 
 
 @router.get("/api/library/practice-suggestions")

lib/routers/song.py

@@ -829,9 +829,60 @@ def post_song_gap_fill(filename: str, data: dict):
     return {"ok": True, "written": additions, "skipped": skipped}
 
 
+def _playable_stems_payload(filename: str, dlc) -> dict:
+    """The playable stems (id/url/default) + full-mix URL for a sloppak.
+
+    Why it exists: the stems plugin could only learn its stem list from the
+    highway's WS `ready`, which arrives once the highway is already up. So it
+    decoded, and then copied the whole song's PCM to its worklet, with the player
+    on screen — half a gigabyte of memcpy in one frame, ~700 ms, freezing the
+    venue video. Given the list at `song:loading` it can do all of that BEFORE the
+    highway appears, behind the loading overlay where a stall costs nothing.
+
+    The list MUST be the same one the WS sends a moment later. If it is not, the
+    plugin preloads a graph and then throws it away and rebuilds — strictly worse
+    than not preloading. So this does not reimplement the WS's construction, it
+    calls THE SAME FUNCTION: load_song, whose LoadedSloppak already carries the
+    partitioned stems and the resolved full mix, and then builds the URLs exactly
+    as ws_highway does. Drift is impossible by construction rather than by
+    agreement — which matters, because `full_mix` in particular is not simply the
+    `full` stem: load_song falls back to the deprecated `original_audio:` key for
+    every pack written before feedpak 1.15.0, and reimplementing that (I did, at
+    first) silently dropped the pristine full mix for most real libraries.
+
+    Opt-in (`?stems=1`) so the library's own metadata calls — the hot path — pay
+    nothing for it. Non-sloppak sources (archives, loose folders) have no stems
+    to preload: load_song raises and we return the empty list.
+    """
+    from urllib.parse import quote
+
+    try:
+        loaded = sloppak_mod.load_song(filename, dlc, appstate.sloppak_cache_dir)
+    except Exception:
+        return {"stems": [], "full_mix_url": None}
+
+    q_fn = quote(filename, safe="")
+
+    def _url(rel: str) -> str:
+        return f"/api/sloppak/{q_fn}/file/{quote(rel)}"
+
+    return {
+        "stems": [
+            {"id": s["id"], "url": _url(s["file"]), "default": s["default"]}
+            for s in loaded.stems
+        ],
+        "full_mix_url": _url(loaded.full_mix) if loaded.full_mix else None,
+    }
+
+
 @router.get("/api/song/{filename:path}")
-async def get_song_info(filename: str):
-    """Return song metadata, from cache or by extracting it from the song source."""
+async def get_song_info(filename: str, stems: int = 0):
+    """Return song metadata, from cache or by extracting it from the song source.
+
+    `?stems=1` additionally returns the playable stem list with URLs, so the
+    stems plugin can start fetching/decoding on `song:loading` instead of waiting
+    for the highway's WS `ready` (see _playable_stems_payload).
+    """
     import asyncio
     dlc = _get_dlc_dir()
     if not dlc:
@@ -854,8 +905,21 @@ async def get_song_info(filename: str):
 
     mtime, size = appstate.stat_for_cache(song_path)
     cached = appstate.meta_db.get(cache_key, mtime, size)
+    loop = asyncio.get_event_loop()
+
+    # The stem list is NOT stored in the metadata cache: that is a fixed-column
+    # table, and widening it would mean a migration plus a stale row for every
+    # song already scanned. It is cheap to read on demand (the pack is unpacked
+    # by then, so this is a plain manifest read), and only the opt-in caller pays.
+    async def _with_stems(meta: dict) -> dict:
+        if not stems:
+            return meta
+        extra = await loop.run_in_executor(
+            None, _playable_stems_payload, filename, dlc)
+        return {**meta, **extra}
+
     if cached:
-        return cached
+        return await _with_stems(cached)
 
     # Extract in thread pool
     def _extract():
@@ -863,5 +927,5 @@ async def get_song_info(filename: str):
         appstate.meta_db.put(cache_key, mtime, size, meta)
         return meta
 
-    meta = await asyncio.get_event_loop().run_in_executor(None, _extract)
-    return meta
+    meta = await loop.run_in_executor(None, _extract)
+    return await _with_stems(meta)

lib/safepath.py

@@ -4,9 +4,34 @@ under a server-owned root.
 
 from __future__ import annotations
 
+from functools import lru_cache
 from pathlib import Path
 
 
+@lru_cache(maxsize=16)
+def resolved_root(root: Path) -> Path:
+    """Canonical (link-resolved) form of a server-owned root directory.
+
+    ``Path.resolve()`` is a filesystem call: it lstats every component of the
+    path. The roots we join against — the DLC library, a plugin's asset dir —
+    are fixed for the life of the process, but the containment helpers below
+    (and ``dlc_paths._resolve_dlc_path``) were re-resolving them on EVERY call,
+    and those are called once per song, per art fetch, per scanned row.
+
+    On a real 50,944-song library that cost ~23,500 stat/lstat calls per second,
+    pinning a core. It is brutal when the library lives on a FUSE mount
+    (NTFS-3G, SMB, sshfs), where every stat is a userspace round trip: the same
+    three parent directories were being walked over and over.
+
+    Cached because a root is a constant here, not because resolution is cheap.
+    Consequence: if a root's symlink/junction is re-pointed at a NEW target
+    while the server is running, the old target stays in effect until restart.
+    That is fine for a library path fixed at startup, and the cache is keyed on
+    the Path, so switching to a different library dir is a different key.
+    """
+    return root.resolve()
+
+
 def safe_join(root: Path, name: str) -> Path | None:
     """Resolve ``name`` under ``root`` and return the resolved Path, or
     ``None`` if it would escape ``root`` or is unrepresentable.
@@ -35,9 +60,12 @@ def safe_join(root: Path, name: str) -> Path | None:
         return None
     safe = name.replace("\\", "/")
     try:
-        root_resolved = root.resolve()
-        candidate = (root_resolved / safe).resolve()
-        if not candidate.is_relative_to(root_resolved):
+        # The ROOT is a constant — resolve it once (see resolved_root). The
+        # CANDIDATE must still be resolved on every call: following its symlinks
+        # is exactly the zip-slip / traversal defence, so it is never cached.
+        root_res = resolved_root(root)
+        candidate = (root_res / safe).resolve()
+        if not candidate.is_relative_to(root_res):
             return None
     except (ValueError, OSError):
         return None

lib/scan.py

@@ -51,6 +51,120 @@ from scan_worker import _relpath, _scan_one
 
 log = logging.getLogger("feedBack.scan")
 
+import json
+
+
+# ── Directory-signature fast path ─────────────────────────────────────────────
+#
+# A startup scan globs the whole library twice (*.feedpak, *.wem) and stats every
+# file to detect what changed. On a 50k-song library that lives on a slow mount
+# (an NTFS-3G FUSE volume here) it is ~100k filesystem round trips every launch —
+# the "big drive churns on every startup" report.
+#
+# But adds / removes / renames of songs all bump the mtime of the DIRECTORY that
+# holds them (verified on the target NTFS-3G mount), and so does the addition of
+# a subdirectory (a new entry in its parent). So after a scan we record every
+# library directory and its mtime; on the next scan we re-stat ONLY those
+# directories (a handful, vs 100k file ops). If none changed, the file set is
+# unchanged and the whole listing/stat pass is skipped.
+#
+# The one thing this cannot see is a file edited IN PLACE under the same name —
+# that bumps the file's mtime but not its directory's. That is rare for a song
+# library (you add and remove packs, you don't rewrite them under the same name),
+# and the manual Refresh forces a full scan (force=True) for exactly that case.
+def _dir_signature_file() -> Path:
+    return appstate.config_dir / "scan_dir_signature.json"
+
+
+def _load_dir_signature() -> dict | None:
+    try:
+        data = json.loads(_dir_signature_file().read_text(encoding="utf-8"))
+        if isinstance(data, dict) and isinstance(data.get("dirs"), dict):
+            return data
+    except (OSError, ValueError):
+        pass
+    return None
+
+
+def _save_dir_signature(dlc: Path, dirs: dict[str, int]) -> None:
+    # Keyed by the DLC path so switching libraries never matches a stale
+    # signature. Best-effort: a failed write just means the next scan is a full
+    # one, never a wrong one.
+    try:
+        _dir_signature_file().write_text(
+            json.dumps({"dlc": str(dlc), "dirs": dirs}), encoding="utf-8")
+    except OSError as e:
+        log.debug("scan: could not persist dir signature: %s", e)
+
+
+def _library_dirs(all_songs, dlc: Path) -> set[str]:
+    """Every directory whose mtime reflects an add/remove of a library song:
+    each song's containing directory and all of its ancestors up to the DLC
+    root (the root itself always included, as "."). Derived from the already-
+    listed songs — no extra filesystem walk. The builtin carve-outs
+    (tutorials-builtin / minigames-builtin) are absent because the caller
+    already excluded them from `all_songs`, so a minigame writing a drill there
+    never invalidates the fast path.
+
+    Directory-form songs (loose-song folders, directory sloppak bundles) also
+    record their OWN directory: a file added/removed/replaced INSIDE the folder
+    bumps that folder's mtime but not its parent's, so tracking only the parent
+    would miss an in-place change to such a song. File-form sloppaks (a single
+    .feedpak zip) aren't dirs, so they add nothing here — the flat file library
+    stays at a handful of dir stats."""
+    rels = {"."}
+    for f in all_songs:
+        rel = Path(_relpath(f, dlc))
+        if f.is_dir():
+            rels.add(rel.as_posix())
+        parent = rel.parent
+        rels.add(parent.as_posix())
+        for anc in parent.parents:
+            rels.add(anc.as_posix())
+    return rels
+
+
+def _has_unextracted_columns() -> bool:
+    """True while any `songs` row still carries NULL in a column added by an
+    additive migration — i.e. metadata the current extractor would fill but
+    that no existing row has yet (currently `bass_tuning_name`).
+
+    The tree-signature fast path only asks "did the file set change"; on a
+    settled library the answer is no forever, so a schema addition would never
+    reach extraction. This one-row probe forces the full pass exactly until the
+    backfill completes — `put()` writes '' rather than NULL, so it self-clears
+    after the rescan instead of disabling the fast path permanently."""
+    try:
+        from metadata_db import MetadataDB
+        cond = " OR ".join(f"{c} IS NULL" for c in MetadataDB._EXTRACTION_MARKER_COLS)
+        row = appstate.meta_db.conn.execute(
+            f"SELECT 1 FROM songs WHERE {cond} LIMIT 1").fetchone()
+    except Exception as e:
+        # A probe failure must not take the scan down; falling back to the fast
+        # path costs at most a delayed backfill.
+        log.debug("scan: unextracted-column probe failed: %s", e)
+        return False
+    return row is not None
+
+
+def _record_dir_signature(all_songs, dlc: Path) -> None:
+    sig = _stat_dirs(dlc, _library_dirs(all_songs, dlc))
+    if sig is not None:   # a dir vanished mid-scan → skip; next scan is full
+        _save_dir_signature(dlc, sig)
+
+
+def _stat_dirs(dlc: Path, rels) -> dict[str, int] | None:
+    """{reldir: mtime_ns} for the given library dirs, or None if any is gone or
+    unreadable — a vanished recorded dir means the tree changed, so fail to a
+    full scan rather than a false match."""
+    out: dict[str, int] = {}
+    for rel in rels:
+        try:
+            out[rel] = (dlc if rel == "." else dlc / rel).stat().st_mtime_ns
+        except OSError:
+            return None
+    return out
+
 
 _SCAN_STATUS_INIT = {"running": False, "stage": "idle", "total": 0, "done": 0, "current": "", "error": None, "is_first_scan": False, "added": 0, "removed": 0}
 
@@ -99,9 +213,12 @@ def _make_scan_executor():
     )
 
 
-def background_scan():
+def background_scan(force: bool = False):
     """Scan the library and cache song metadata on startup. Uses a process pool to bypass the GIL for CPU-bound metadata parsing.
 
+    `force` skips the directory-signature fast path and always does the full
+    listing/stat pass — the manual Refresh sets it (see _dir_signature_file).
+
     Never sets `_scan_status["running"] = False` — ownership of that flag
     lives in `_scan_runner` so a `kick_scan()` racing this function's
     terminal write cannot observe a stale False and start a second runner.
@@ -121,6 +238,22 @@ def background_scan():
     builtin_content.seed_builtin_diagnostic_sloppaks(appstate.server_root, dlc)
     builtin_content.seed_builtin_starter_content(appstate.server_root, dlc)
 
+    # Fast path: if every library directory recorded by the last scan still has
+    # the same mtime, nothing was added, removed, or renamed, so the whole
+    # glob-and-stat pass below can be skipped (see the signature comment above).
+    # `force` (manual Refresh) always does the full pass. Seeding above is
+    # idempotent — it only writes when a builtin is missing — so it does not
+    # perturb the mtimes on a settled library.
+    if not force and not _has_unextracted_columns():
+        stored = _load_dir_signature()
+        if stored is not None and stored.get("dlc") == str(dlc):
+            current = _stat_dirs(dlc, stored["dirs"].keys())
+            if current is not None and current == stored["dirs"]:
+                _scan_status = {**_SCAN_STATUS_INIT, "running": True, "stage": "complete"}
+                log.info("Scan: library tree unchanged (%d dirs) — skipped the full listing/stat pass",
+                         len(current))
+                return
+
     # Listing can fail on macOS without Full Disk Access, or on Docker if the
     # path isn't shared. Report the failure explicitly rather than silently
     # appearing to scan nothing.
@@ -209,6 +342,15 @@ def background_scan():
             cached = None
         if not cached:
             to_scan.append((f, mtime, size, dlc))
+        elif any(cached.get(c) is None for c in appstate.meta_db._EXTRACTION_MARKER_COLS):
+            # Row predates one of the per-perspective tuning columns (NULL
+            # from the additive migration), so that perspective's tuning was
+            # never extracted for it. Without this
+            # re-queue an existing library would keep every bass column empty
+            # forever — mtime/size still match, so nothing else would ever
+            # bring the row back through extraction. Converges: put() always
+            # writes '' (never NULL), so a rescanned row is never re-queued.
+            to_scan.append((f, mtime, size, dlc))
         elif cached.get("arrangements") and any(
             "smart_name" not in a for a in cached["arrangements"]
         ):
@@ -223,6 +365,9 @@ def background_scan():
             to_scan.append((f, mtime, size, dlc))
 
     if not to_scan:
+        # Full pass completed with the DB already up to date — record the tree
+        # signature so the next startup can take the fast path.
+        _record_dir_signature(all_songs, dlc)
         _scan_status = {**_SCAN_STATUS_INIT, "running": True, "stage": "complete", "added": added, "removed": removed}
         log.info("Scan: nothing new to scan (%d songs, all cached)", len(all_songs))
         return
@@ -247,6 +392,9 @@ def background_scan():
             _scan_status["done"] += 1
             _scan_status["current"] = fname
 
+    # Record the tree signature after a completed full pass so the next startup
+    # can skip it when nothing has changed.
+    _record_dir_signature(all_songs, dlc)
     log.info("Scan complete: %d songs cached", len(to_scan))
     _scan_status = {**_SCAN_STATUS_INIT, "running": True, "stage": "complete", "added": added, "removed": removed}
 
@@ -255,6 +403,9 @@ _scan_kick_lock = threading.Lock()
 
 
 _scan_rescan_pending = False
+# Set by kick_scan(force=True); consumed by _scan_runner for the next pass so a
+# manual Refresh bypasses the directory-signature fast path.
+_scan_force_next = False
 
 
 # Handles to the running scan / enrichment worker threads. Both use the shared
@@ -265,9 +416,15 @@ _scan_rescan_pending = False
 _scan_thread: threading.Thread | None = None
 
 
-def kick_scan() -> bool:
+def kick_scan(force: bool = False) -> bool:
     """Request a library rescan, single-flight + coalescing.
 
+    `force` skips the directory-signature fast path for the resulting pass (the
+    manual Refresh uses it so an in-place same-name edit — the one thing the
+    fast path can't see — is always picked up). A forced request that coalesces
+    onto a running or queued scan keeps the force intent: the pass is forced if
+    ANY pending request asked for it.
+
     Returns True if a new scan thread was started, False if one was already
     running. In the latter case a follow-up pass is queued and runs as soon
     as the current scan finishes so files landing mid-scan (e.g. an upload
@@ -275,8 +432,10 @@ def kick_scan() -> bool:
     until the next periodic pass. Multiple late-arriving requests coalesce
     into a single follow-up.
     """
-    global _scan_rescan_pending, _scan_thread
+    global _scan_rescan_pending, _scan_thread, _scan_force_next
     with _scan_kick_lock:
+        if force:
+            _scan_force_next = True
         if _scan_status["running"]:
             _scan_rescan_pending = True
             return False
@@ -290,10 +449,15 @@ def kick_scan() -> bool:
 
 def _scan_runner():
     """Run _background_scan, then re-run if requests arrived mid-scan."""
-    global _scan_rescan_pending
+    global _scan_rescan_pending, _scan_force_next
     while True:
+        # Consume the force flag for THIS pass; a forced request queued mid-scan
+        # sets it again for the follow-up.
+        with _scan_kick_lock:
+            forced = _scan_force_next
+            _scan_force_next = False
         try:
-            background_scan()
+            background_scan(force=forced)
         except Exception:
             log.exception("background scan failed unexpectedly")
 

lib/scan_worker.py

@@ -27,7 +27,11 @@ import logging
 from pathlib import Path
 
 from song import compute_smart_names
-from tunings import tuning_name
+from tunings import (
+    DEFAULT_PERSPECTIVE, PERSPECTIVES, ROLE_PERSPECTIVES, normalize_offsets,
+    perspective_low_pitch, perspective_tuning_key, perspective_tuning_name,
+    tuning_name,
+)
 import sloppak as sloppak_mod
 import loosefolder as loosefolder_mod
 
@@ -43,15 +47,69 @@ def _relpath(f: Path, dlc: Path) -> str:
         return f.name
 
 
+def _apply_role_tunings(meta: dict) -> None:
+    """Derive each ROLE perspective's tuning columns from the raw offsets the
+    extractor emitted (currently bass + rhythm; guitar-lead reads the
+    song-level columns the scanner has always written).
+
+    The domain rules live in `tunings` (see the PERSPECTIVES table and the
+    block above it for the evidence behind each):
+
+    1. NORMALIZE FIRST. Stored bass arrays are commonly six elements whose
+       last two slots are padding, so bass truncates to four strings before
+       anything looks at them — padding must never reach the namer or the
+       grouping key. Guitar does NOT truncate (a 7-string array is real).
+    2. Refuse to name data the perspective distrusts (bass up-tuning), so the
+       library can't send a player off to a tuning nobody plays.
+    3. Group on CANONICAL PITCHES, not the raw offsets string — the same
+       physical tuning serialized two ways must be ONE facet entry.
+
+    A song with no arrangement in that role gets EMPTY strings / 0, not NULL:
+    '' is the indexed "we looked, there is no such chart" state the library's
+    fallback keys on, while NULL means "never extracted" and re-scans.
+    """
+    for persp in ROLE_PERSPECTIVES:
+        raw = meta.pop(f"{persp.role}_tuning_offsets", None)
+        offsets = normalize_offsets(raw, persp)
+        if offsets is None:
+            meta[persp.column("name")] = ""
+            meta[persp.column("sort_key")] = 0
+            meta[persp.column("offsets")] = ""
+            meta[persp.column("key")] = ""
+            meta[persp.column("low_pitch")] = None
+            continue
+        meta[persp.column("name")] = perspective_tuning_name(offsets, persp)
+        meta[persp.column("sort_key")] = sum(offsets)
+        # The NORMALIZED offsets are what we store: padding is not data, and a
+        # client rendering target notes must not print phantom strings.
+        meta[persp.column("offsets")] = " ".join(str(o) for o in offsets)
+        meta[persp.column("key")] = perspective_tuning_key(offsets, persp)
+        meta[persp.column("low_pitch")] = perspective_low_pitch(offsets, persp)
+
+
+def _apply_song_low_pitch(meta: dict, offsets: list[int]) -> None:
+    """Lowest open-string pitch of the SONG-level (guitar-lead) tuning, for
+    the "playable without retuning" comparison. Indexed here, on the existing
+    manifest-only pass — never by reopening chart JSON."""
+    persp = PERSPECTIVES[DEFAULT_PERSPECTIVE]
+    norm = normalize_offsets(offsets, persp)
+    meta["tuning_low_pitch"] = (
+        perspective_low_pitch(norm, persp) if norm is not None else None)
+
+
 def _extract_meta_sloppak(path: Path) -> dict:
     """Extract metadata for a sloppak (file or directory)."""
     meta = sloppak_mod.extract_meta(path)
     offsets = meta.pop("tuning_offsets", None) or [0] * 6
-    name = tuning_name(offsets)
+    # Naming needs the instrument: six offsets could be a guitar OR a
+    # 6-string bass, whose lowest string is B rather than E.
+    name = tuning_name(offsets, is_bass=bool(meta.pop("tuning_is_bass", False)))
     meta["tuning"] = name
     meta["tuning_name"] = name
     meta["tuning_sort_key"] = sum(offsets)
     meta["tuning_offsets"] = " ".join(str(o) for o in offsets)
+    _apply_song_low_pitch(meta, offsets)
+    _apply_role_tunings(meta)
     meta["format"] = "sloppak"
     # `extract_meta` already populates `stem_ids` (feedBack#129);
     # default to empty for older callers / mocks.
@@ -81,11 +139,15 @@ def _extract_meta_loosefolder(path: Path, dlc_root: Path | None) -> dict:
     # inside DLC_DIR.
     meta = loosefolder_mod.extract_meta(path, dlc_root=dlc_root)
     offsets = meta.pop("tuning_offsets", None) or [0] * 6
-    name = tuning_name(offsets)
+    # Naming needs the instrument: six offsets could be a guitar OR a
+    # 6-string bass, whose lowest string is B rather than E.
+    name = tuning_name(offsets, is_bass=bool(meta.pop("tuning_is_bass", False)))
     meta["tuning"] = name
     meta["tuning_name"] = name
     meta["tuning_sort_key"] = sum(offsets)
     meta["tuning_offsets"] = " ".join(str(o) for o in offsets)
+    _apply_song_low_pitch(meta, offsets)
+    _apply_role_tunings(meta)
     meta["format"] = "loose"
     meta.setdefault("stem_ids", [])
     # The library helper exposes absolute filesystem paths for audio/art

lib/sloppak.py

@@ -80,6 +80,20 @@ def find_full_mix(stems: list[dict]) -> dict | None:
     )
 
 
+def stem_default_on(raw) -> bool:
+    """Whether a manifest stem entry plays by default.
+
+    Absent means on. A string is honoured so a hand-written manifest can say
+    `default: off`. Extracted so the WS `ready` payload and the REST song-info
+    payload cannot drift: the stems plugin now preloads from REST and then has
+    to agree with what the WS says a moment later, or it would rebuild the whole
+    graph for nothing.
+    """
+    if isinstance(raw, str):
+        return raw.lower() not in ("off", "false", "0", "no")
+    return bool(raw)
+
+
 def partition_stems(stems: list[dict]) -> tuple[dict | None, list[dict]]:
     """Split stem descriptors into (mixdown, instrument_stems) for PLAYBACK.
 
@@ -1100,12 +1114,11 @@ def load_song(
         sfile = str(s.get("file", ""))
         if not sid or not sfile:
             continue
-        default_val = s.get("default", True)
-        if isinstance(default_val, str):
-            default_on = default_val.lower() not in ("off", "false", "0", "no")
-        else:
-            default_on = bool(default_val)
-        stems.append({"id": sid, "file": sfile, "default": default_on})
+        stems.append({
+            "id": sid,
+            "file": sfile,
+            "default": stem_default_on(s.get("default", True)),
+        })
 
     # The complete mixdown is a stem (spec §5.3), but it is not a *layer*: lift
     # it out so that no consumer of `stems` — the mixer, the library's stem
@@ -1214,17 +1227,54 @@ def load_song(
 
 def _tuning_for_meta(arrangements_manifest: list[dict]) -> list[int]:
     """Best-effort guitar-first tuning for the library index."""
+    offsets, _ = _tuning_for_meta_kind(arrangements_manifest)
+    return offsets
+
+
+def _tuning_for_meta_kind(
+    arrangements_manifest: list[dict],
+) -> tuple[list[int], bool]:
+    """`_tuning_for_meta` plus whether the tuning came from a BASS part.
+
+    The caller names the tuning, and naming needs the instrument: a
+    6-string bass has six offsets exactly like a 6-string guitar but its
+    lowest string is B, so the guitar ladder mislabels it (all-zeros reads
+    "E Standard" when it is Standard/B; a whole step down reads "D
+    Standard" when it is A Standard). Guitar parts still win the tuning
+    itself — this only reports which kind supplied it.
+    """
     for entry in arrangements_manifest:
         name = str(entry.get("name", "")).lower()
         tun = entry.get("tuning")
         if tun and isinstance(tun, list) and name in ("lead", "rhythm", "combo"):
-            return list(tun)
+            return list(tun), False
     # Fallback: first arrangement with a tuning
     for entry in arrangements_manifest:
         tun = entry.get("tuning")
         if tun and isinstance(tun, list):
-            return list(tun)
-    return [0] * 6
+            return list(tun), "bass" in str(entry.get("name", "")).lower()
+    return [0] * 6, False
+
+
+def _role_tuning_for_meta(arrangements_manifest: list[dict], role: str) -> list[int] | None:
+    """Per-ROLE companion to _tuning_for_meta: the tuning of the arrangement
+    playing `role` ("bass" / "rhythm"), or None when the pack has no such
+    arrangement with a tuning — the index then leaves that perspective's
+    columns empty and the library falls back to the song (guitar-first)
+    tuning, marking the row inferred.
+
+    Exact name first, then a looser containment pass so an alt/bonus chart
+    ("Bass 2", "Alt Rhythm") still beats pretending the part is in the lead
+    guitar's tuning."""
+    for match_exact in (True, False):
+        for entry in arrangements_manifest:
+            name = str(entry.get("name", "")).lower()
+            tun = entry.get("tuning")
+            if not (tun and isinstance(tun, list)):
+                continue
+            if name == role if match_exact else role in name:
+                return list(tun)
+    return None
 
 
 def extract_meta(path: Path) -> dict:
@@ -1248,7 +1298,10 @@ def extract_meta(path: Path) -> dict:
         a["index"] = i
 
     has_lyrics = bool(manifest.get("lyrics"))
-    tuning_offsets = _tuning_for_meta(arr_list)
+    tuning_offsets, tuning_is_bass = _tuning_for_meta_kind(arr_list)
+    # Per-role tunings alongside the song-level one.
+    role_tunings = {f"{role}_tuning_offsets": _role_tuning_for_meta(arr_list, role)
+                    for role in ("bass", "rhythm")}
 
     stems_list = manifest.get("stems", []) or []
     valid_stems: list[dict] = []
@@ -1287,6 +1340,10 @@ def extract_meta(path: Path) -> dict:
         "disc": (lambda v: int(v) if str(v if v is not None else "").strip().isdigit() else None)(manifest.get("disc")),
         "duration": float(manifest.get("duration", 0) or 0),
         "tuning_offsets": tuning_offsets,  # caller maps to a name via tunings.tuning_name
+        # None = the pack has no arrangement in that role.
+        **role_tunings,
+        # Song-level naming also needs the instrument for bass-only packs.
+        "tuning_is_bass": tuning_is_bass,
         "arrangements": arrangements,
         "has_lyrics": has_lyrics,
         "stem_count": stem_count,

lib/tunings.py

@@ -69,21 +69,49 @@ TUNING_PRESET_MIDIS: dict[str, dict[str, list[int]]] = {
         "Drop C": [24, 31, 36, 41],
         "BEAD": [23, 28, 33, 38],
     },
+    # 5- and 6-string basses are named off their ACTUAL lowest string (the low
+    # B), exactly like the 7-string guitar table above — not off the 4-string
+    # core. The old names (Eb/D/C#/C Standard) came from the band-level habit
+    # of saying "we're in D standard" (which describes the guitars); the
+    # bassist in that band is in A standard. They survive as aliases below so
+    # saved profiles migrate instead of being rejected.
     "bass-5": {
         "Standard": [23, 28, 33, 38, 43],
         "High C": [28, 33, 38, 43, 48],
-        "Eb Standard": [22, 27, 32, 37, 42],
-        "D Standard": [21, 26, 31, 36, 41],
-        "C# Standard": [20, 25, 30, 35, 40],
-        "C Standard": [19, 24, 29, 34, 39],
+        "Bb Standard": [22, 27, 32, 37, 42],
+        "A Standard": [21, 26, 31, 36, 41],
+        "G# Standard": [20, 25, 30, 35, 40],
+        "G Standard": [19, 24, 29, 34, 39],
         "Drop A": [21, 28, 33, 38, 43],
     },
     "bass-6": {
         "Standard": [23, 28, 33, 38, 43, 48],
-        "Eb Standard": [22, 27, 32, 37, 42, 47],
-        "D Standard": [21, 26, 31, 36, 41, 46],
-        "C# Standard": [20, 25, 30, 35, 40, 45],
-        "C Standard": [19, 24, 29, 34, 39, 44],
+        "Bb Standard": [22, 27, 32, 37, 42, 47],
+        "A Standard": [21, 26, 31, 36, 41, 46],
+        "G# Standard": [20, 25, 30, 35, 40, 45],
+        "G Standard": [19, 24, 29, 34, 39, 44],
+    },
+}
+
+# Superseded preset names, per key → current name. The 5/6-string bass rows
+# were originally named off the 4-string core (so a whole-step-down 6-string,
+# whose lowest string is A, read "D Standard"). Renaming alone would make
+# `_valid_tuning_for_key` REJECT a saved profile carrying the old name — it
+# refuses names that belong to a different key's built-ins, and "D Standard"
+# still exists for guitar-6/bass-4. These aliases keep those profiles valid
+# and migrate them to the corrected name.
+TUNING_PRESET_ALIASES: dict[str, dict[str, str]] = {
+    "bass-5": {
+        "Eb Standard": "Bb Standard",
+        "D Standard": "A Standard",
+        "C# Standard": "G# Standard",
+        "C Standard": "G Standard",
+    },
+    "bass-6": {
+        "Eb Standard": "Bb Standard",
+        "D Standard": "A Standard",
+        "C# Standard": "G# Standard",
+        "C Standard": "G Standard",
     },
 }
 
@@ -229,6 +257,12 @@ def _valid_tuning_for_key(key: str, tuning):
             return None
         if tuning in TUNING_PRESET_MIDIS.get(key, {}):
             return tuning
+        # A superseded name for THIS key migrates to its current spelling
+        # (the 5/6-string bass rename). Checked before the cross-key
+        # rejection below, which would otherwise refuse it.
+        renamed = TUNING_PRESET_ALIASES.get(key, {}).get(tuning)
+        if renamed:
+            return renamed
         # A name that IS a built-in preset for a different key is a misapplied
         # built-in (e.g. "Drop D" on a 5-string bass, whose low string is B) —
         # reject it. A name unknown to every built-in table is a provider/custom
@@ -416,21 +450,308 @@ def apply_flat_instrument_patch_to_profiles(cfg: dict, updates: dict) -> dict:
     })
     return out
 
-def tuning_name(offsets: list[int]) -> str:
-    # All three pattern checks below are gated on `len(offsets) == 6`. The
-    # naming conventions here are 6-string-specific — e.g. a 7-string all-zeros
-    # tuning has a low B, not an E, so labeling it "E Standard" would be wrong.
-    # 7+-string community content falls through to the numeric fallback. See #43.
+# ── Bass tuning normalization (library indexing) ─────────────────────────────
+#
+# Bass charts in the wild store SIX-element tuning arrays even when the chart is
+# a 4-string part: slots 4-5 are PADDING. Confirmed by inspecting the charts
+# themselves — across every pack whose bass and guitar tunings diverge, no bass
+# note ever references string index 4 or 5 (the deepest reach is index 3).
+#
+# The feedpak spec carries NO string-count field (manifest `arrangement.tuning`
+# is an untyped integer array, `minItems: 1`), and counting strings for real
+# would mean parsing the 600KB-1.2MB arrangement JSON of every song on the
+# manifest-only fast scan path — unacceptable for scan time. So we DEFAULT BASS
+# TO 4 STRINGS and truncate.
+#
+# Five-element arrays are unambiguously extended-range. Six elements remain
+# ambiguous because legacy four-string charts are padded to six; preserve that
+# legacy interpretation except for a uniform non-zero down-tuning, which cannot
+# be padding (the padded tail would be zero) and is the common extended-range
+# case that motivated the fix. Ambiguous all-zero and drop-shaped six-element
+# arrays stay conservative until the manifest carries an explicit string count.
+BASS_DEFAULT_STRING_COUNT = 4
 
-    # Standard tunings (all six strings same offset)
-    standard = {
+# Bassists tune DOWN, essentially never up: a whole-instrument up-tune fights
+# string tension. Anything above +1 semitone across the board is data we do not
+# trust, not a tuning a human plays (the real-world example that motivated this
+# is a bass array of [5,5,5,5,4,4] — "all four strings up a perfect fourth" —
+# on a song whose guitar chart is dead standard and whose own note content is
+# consistent with standard tuning; the offsets were almost certainly computed
+# against a 6-string-bass reference with an uninitialised tail).
+#
+# Such a tuning MUST NOT be named: printing "A Standard" would send a player
+# off to retune to something nobody plays. It degrades to the custom path,
+# where it stays visible and distinct but makes no pitch claim.
+BASS_MAX_PLAUSIBLE_OFFSET = 1
+
+
+# ── Tuning PERSPECTIVES ──────────────────────────────────────────────────────
+#
+# The library's tuning facet/filter/sort always answers for ONE arrangement
+# role. There are three, matching `active_instrument_profile`:
+#
+#   guitar-lead    the song-level (guitar-first) tuning — the historical
+#                  default. Its columns are the original unprefixed
+#                  `tuning_*` family, so today's behaviour is byte-identical.
+#   guitar-rhythm  the RHYTHM chart's own tuning. Lead and rhythm charts can
+#                  disagree (the same bug a bassist hit, inside guitar).
+#   bass           the BASS chart's own tuning.
+#
+# One table drives extraction, the derived columns, the SQL, and the labels —
+# rather than three near-identical column families maintained in parallel.
+class TuningPerspective:
+    __slots__ = ("id", "role", "instrument", "string_count", "column_prefix",
+                 "truncate", "guard_up_tuning", "label")
+
+    def __init__(self, id, role, instrument, string_count, column_prefix,
+                 truncate, guard_up_tuning, label):
+        self.id = id
+        self.role = role                    # arrangement name to look for ('' = song-level)
+        self.instrument = instrument
+        self.string_count = string_count
+        self.column_prefix = column_prefix  # '' | 'rhythm_' | 'bass_'
+        self.truncate = truncate
+        self.guard_up_tuning = guard_up_tuning
+        self.label = label
+
+    @property
+    def instrument_key(self) -> str:
+        return instrument_key(self.instrument, self.string_count)
+
+    def column(self, suffix: str) -> str:
+        return f"{self.column_prefix}tuning_{suffix}"
+
+
+PERSPECTIVES: dict[str, TuningPerspective] = {
+    "guitar-lead": TuningPerspective(
+        "guitar-lead", "", "guitar", 6, "", False, False, "lead"),
+    "guitar-rhythm": TuningPerspective(
+        "guitar-rhythm", "rhythm", "guitar", 6, "rhythm_", False, False, "rhythm"),
+    # Bass alone truncates (padded arrays) and guards against up-tuned data —
+    # both are bass-specific findings, see the block above.
+    "bass": TuningPerspective(
+        "bass", "bass", "bass", BASS_DEFAULT_STRING_COUNT, "bass_", True, True, "bass"),
+}
+
+DEFAULT_PERSPECTIVE = "guitar-lead"
+
+# Perspectives that carry their OWN indexed columns (guitar-lead reads the
+# song-level ones, which the scanner has always written).
+ROLE_PERSPECTIVES = tuple(p for p in PERSPECTIVES.values() if p.column_prefix)
+
+
+def perspective(perspective_id) -> TuningPerspective:
+    """Resolve a perspective id, tolerating the legacy two-valued vocabulary
+    ('guitar' -> guitar-lead) and anything unknown (-> the default). An
+    unrecognised value must never change filter semantics."""
+    if perspective_id in PERSPECTIVES:
+        return PERSPECTIVES[perspective_id]
+    if perspective_id == "guitar":
+        return PERSPECTIVES[DEFAULT_PERSPECTIVE]
+    return PERSPECTIVES[DEFAULT_PERSPECTIVE]
+
+
+def normalize_offsets(offsets, persp: TuningPerspective) -> list[int] | None:
+    """Coerce a stored tuning array to the strings the perspective's
+    instrument actually has. Returns None for anything unusable (empty /
+    non-integer / too short), so callers leave the index empty rather than
+    record a guess."""
+    if not isinstance(offsets, list) or not offsets:
+        return None
+    if any(isinstance(o, bool) for o in offsets):
+        return None
+    try:
+        vals = [int(o) for o in offsets]
+    except (TypeError, ValueError):
+        return None
+    if len(vals) < persp.string_count:
+        return None
+    # Only bass can be padded. Five entries are unambiguously extended-range.
+    # Six are ambiguous: legacy four-string data pads with zeroes, while a
+    # uniform non-zero down-tuning across all six strings proves the tail is
+    # authored. Keep every other six-element shape conservative at four.
+    if persp.truncate:
+        if len(vals) == 5:
+            return vals
+        if len(vals) == 6 and vals[0] != 0 and len(set(vals)) == 1:
+            return vals
+        return vals[:persp.string_count]
+    return vals
+
+
+def offsets_are_plausible(offsets: list[int], persp: TuningPerspective) -> bool:
+    """False for data the perspective refuses to trust — currently only the
+    bass up-tuning guard (see BASS_MAX_PLAUSIBLE_OFFSET)."""
+    if not persp.guard_up_tuning:
+        return True
+    return all(o <= BASS_MAX_PLAUSIBLE_OFFSET for o in offsets)
+
+
+def perspective_tuning_name(offsets: list[int], persp: TuningPerspective) -> str:
+    """Name a NORMALIZED tuning for this perspective, refusing to name data the
+    perspective distrusts — that becomes "Custom Tuning", which stays distinct
+    by its canonical pitches without asserting a tuning anyone plays."""
+    if not offsets_are_plausible(offsets, persp):
+        return "Custom Tuning"
+    return tuning_name(offsets, is_bass=persp.instrument == "bass")
+
+
+def _perspective_instrument_key(
+    offsets: list[int], persp: TuningPerspective,
+) -> str:
+    """Instrument key matching the normalized tuning's proven string count."""
+    if persp.instrument == "bass" and f"bass-{len(offsets)}" in STANDARD_OPEN_MIDIS:
+        return f"bass-{len(offsets)}"
+    return persp.instrument_key
+
+
+def perspective_tuning_key(offsets: list[int], persp: TuningPerspective) -> str:
+    """CANONICAL grouping key: the tuning's absolute open-string pitches, so
+    the same physical tuning groups as ONE facet entry no matter how it was
+    serialized. Keyed on pitch rather than the raw offsets string, which is
+    serialization-dependent and fragments.
+
+    Joined with ':' and NOT ',' — this key travels back as a `tunings` filter
+    selector, and that query param is a COMMA-separated list, so a comma here
+    would be split into meaningless fragments and match nothing.
+    """
+    midis = tuning_midis_from_offsets(_perspective_instrument_key(offsets, persp), offsets)
+    if not midis:
+        return ""
+    return persp.id + ":" + ":".join(str(m) for m in midis)
+
+
+def perspective_low_pitch(offsets: list[int], persp: TuningPerspective) -> int | None:
+    """Absolute MIDI pitch of the tuning's LOWEST open string — the value the
+    "playable without retuning" comparison is built on (see
+    `chart_is_playable_in`)."""
+    midis = tuning_midis_from_offsets(_perspective_instrument_key(offsets, persp), offsets)
+    if not midis:
+        return None
+    return min(midis)
+
+
+# ── "Playable without retuning" ──────────────────────────────────────────────
+#
+# What the player actually wants is "don't make me retune", not "match this
+# label". A chart is playable as-is when every pitch it needs is reachable on
+# the instrument as currently tuned.
+#
+# WHAT WE CAN HONESTLY COMPUTE. We index open-string TUNINGS, not the notes a
+# chart plays — note data lives in the 600KB-1.2MB arrangement JSON, and the
+# library scan is deliberately manifest-only, so we do not read it (indexing a
+# per-song lowest note would mean opening every chart on every scan).
+#
+# So the comparison is on OPEN-STRING PITCH, with a conservative assumption:
+# a chart may require its own lowest open string. That gives
+#
+#     playable  <=>  your lowest open pitch  <=  the chart's lowest open pitch
+#
+# On a fretted instrument every pitch ABOVE your lowest open string is
+# reachable by fretting (strings sit within an octave of each other and the
+# neck gives ~2 octaves), so the low end is the binding constraint. This is
+# exactly the dominant real case: a 5-string bass (low B) plays every 4-string
+# standard chart AND every drop-D chart untouched, because the low D is just
+# fretted on the B string.
+#
+# DELIBERATE LIMITATIONS, both erring toward NOT claiming playability:
+#   * A chart that never actually touches its lowest open string is excluded
+#     anyway. Conservative: excluding a playable chart costs a scroll;
+#     including an unplayable one costs a mid-practice retune, which is the
+#     failure this feature exists to prevent.
+#   * The UPPER bound is not checked — a chart tuned far above you could in
+#     principle exceed your neck. Checking it needs the note range we do not
+#     have. It is the rare direction (and the guard above already refuses
+#     up-tuned bass data), but it is a real gap, not an oversight.
+def chart_is_playable_in(chart_low_pitch, your_low_pitch) -> bool:
+    """True when a chart whose lowest open string is `chart_low_pitch` needs no
+    retune for a player tuned to `your_low_pitch`. Unknown chart pitch => False
+    (never claim playability we cannot support)."""
+    if chart_low_pitch is None or your_low_pitch is None:
+        return False
+    return int(your_low_pitch) <= int(chart_low_pitch)
+
+
+# Back-compat wrappers over the generic helpers — bass was the first
+# perspective and reads better spelled out at bass-specific call sites.
+def normalize_bass_offsets(offsets) -> list[int] | None:
+    return normalize_offsets(offsets, PERSPECTIVES["bass"])
+
+
+def bass_offsets_are_plausible(offsets: list[int]) -> bool:
+    return offsets_are_plausible(offsets, PERSPECTIVES["bass"])
+
+
+def bass_tuning_name(offsets: list[int]) -> str:
+    return perspective_tuning_name(offsets, PERSPECTIVES["bass"])
+
+
+def bass_tuning_key(offsets: list[int]) -> str:
+    return perspective_tuning_key(offsets, PERSPECTIVES["bass"])
+
+
+def tuning_name(offsets: list[int], *, is_bass: bool = False) -> str:
+    """Display name for a set of per-string offsets.
+
+    `is_bass` is load-bearing, not cosmetic: string COUNT alone cannot
+    identify the instrument. A 6-string BASS has six offsets just like a
+    6-string guitar, but its lowest string is B, not E — so the guitar
+    ladder labels an all-zeros bass "E Standard" (it is B/Standard) and a
+    whole-step-down bass "D Standard" (it is A Standard). That is exactly
+    the error the 7-string comment below warned about, on the axis nobody
+    guarded. Callers that know the instrument must say so; the default
+    stays guitar for backward compatibility.
+
+    All the pattern checks are gated on the expected string count. The
+    guitar conventions are 6-string-specific — e.g. a 7-string all-zeros
+    tuning has a low B, not an E, so labeling it "E Standard" would be
+    wrong. 7+-string guitar content falls through to the numeric
+    fallback. See #43.
+    """
+    # Standard tunings (all strings same offset), named off the LOWEST
+    # string. Bass 4-string sits on the E ladder like a guitar; bass 5/6
+    # add a low B, so they sit on the B ladder — the same convention the
+    # 7-string guitar presets use.
+    guitar_standard = {
         0: "E Standard", -1: "Eb Standard", -2: "D Standard",
         -3: "C# Standard", -4: "C Standard", -5: "B Standard",
         -6: "Bb Standard", -7: "A Standard",
         1: "F Standard", 2: "F# Standard",
     }
+    bass_low_b_standard = {
+        0: "Standard", -1: "Bb Standard", -2: "A Standard",
+        -3: "G# Standard", -4: "G Standard", -5: "F# Standard",
+        1: "C Standard", 2: "C# Standard",
+    }
+    # A four-offset array is unambiguously a bass tuning; preserve the
+    # historical one-argument behavior used by the library perspective.
+    if len(offsets) == 4:
+        is_bass = True
+
+    if is_bass:
+        # 4-string bass is E-A-D-G — the guitar ladder's low four, so it
+        # keeps the E-based names. 5/6-string add the low B.
+        table = guitar_standard if len(offsets) == 4 else bass_low_b_standard
+        if len(offsets) in (4, 5, 6) and all(o == offsets[0] for o in offsets):
+            name = table.get(offsets[0])
+            if name:
+                return name
+        # Drop tunings: the lowest string alone goes down 2 semitones.
+        if (len(offsets) in (4, 5, 6)
+                and offsets[0] == offsets[1] - 2
+                and all(o == offsets[1] for o in offsets[1:])):
+            base = STANDARD_OPEN_MIDIS.get(f"bass-{len(offsets)}")
+            if base:
+                low = base[0] + offsets[0]
+                names = ["C", "C#", "D", "Eb", "E", "F",
+                         "F#", "G", "Ab", "A", "Bb", "B"]
+                return f"Drop {names[low % 12]}"
+        if not offsets:
+            return "Unknown"
+        return "Custom Tuning"
+
     if len(offsets) == 6 and all(o == offsets[0] for o in offsets):
-        name = standard.get(offsets[0])
+        name = guitar_standard.get(offsets[0])
         if name:
             return name
 

plugins/career/assets/career.css

@@ -99,7 +99,8 @@
 .pp-inst-plus { color: #6b7280; }
 
 /* Leather covers — per-instrument hue, embossed with layered shadows and a
-   subtle grain gradient (no image assets). */
+   subtle grain gradient (no image assets). Keep the hex pairs in sync with
+   PP_LEATHER_HEX in screen.js (the canvas card draws the same leather). */
 .pp-leather-guitar { background: linear-gradient(160deg, #5c2321, #401412); }
 .pp-leather-bass { background: linear-gradient(160deg, #1f3252, #131f36); }
 .pp-leather-keys { background: linear-gradient(160deg, #1e4034, #122a21); }
@@ -524,7 +525,18 @@
     pointer-events: none;
 }
 
-/* Gold foil preview — honest "coming", never earnable-looking. */
+/* Gold ink — a REAL gold badge (comb-verified improv). */
+.pp-stamp-gold {
+    border-color: #b8860b;
+    color: #a97b1b;
+    box-shadow: inset 0 0 0 3px #f3e8c8, inset 0 0 0 4px #b8860b;
+}
+.pp-stamp-mini.pp-stamp-gold {
+    color: #f0c75e;
+    border-color: #f0c75e;
+    box-shadow: none;
+}
+/* Gold foil chip — rendered only alongside an earned gold stamp. */
 .pp-gold-foil {
     position: relative;
     overflow: hidden;
@@ -534,8 +546,8 @@
     margin-top: 0.9rem;
     padding: 0.28rem 0.85rem;
     border-radius: 999px;
-    border: 2px dashed #c8b273;
-    color: #a8946d;
+    border: 2px solid #d9a253;
+    color: #c89040;
     font-size: 0.58rem;
     font-weight: 700;
     letter-spacing: 0.32em;
@@ -559,3 +571,221 @@
     /* The hover glint is motion theatrics too — not just the JS tilt. */
     .pp-tilt::after { display: none; }
 }
+
+/* Practice invitations — closest stamps + bring-these-up */
+.pp-closest {
+    border: 1px solid rgba(75, 85, 99, 0.45);
+    border-radius: 0.6rem;
+    background: linear-gradient(165deg, rgba(45, 55, 72, 0.4), rgba(31, 41, 55, 0.4));
+    padding: 0.6rem 0.75rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.3rem;
+}
+.pp-closest-head {
+    font-size: 0.62rem;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: #9ca3af;
+}
+.pp-closest-row {
+    display: flex;
+    align-items: baseline;
+    gap: 0.75rem;
+    text-align: left;
+    font-size: 0.8rem;
+    padding: 0.15rem 0.25rem;
+    border-radius: 0.35rem;
+}
+.pp-closest-row:hover { background: rgba(55, 65, 81, 0.5); }
+.pp-closest-genre { color: #e5e7eb; font-weight: 600; white-space: nowrap; }
+.pp-closest-ask { color: #9ca3af; font-size: 0.72rem; }
+.pp-closest-ask em { color: #cbd5e1; font-style: italic; }
+
+.pp-nearest { margin-top: 0.6rem; border-top: 1px dashed rgba(138, 122, 94, 0.4); padding-top: 0.5rem; }
+.pp-nearest-head {
+    font-size: 0.58rem;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: #8a7a5e;
+    margin-bottom: 0.25rem;
+}
+.pp-nearest-row { font-size: 0.7rem; color: #6d5d40; padding: 0.1rem 0; }
+.pp-nearest-row em { color: #3f3428; }
+/* ── Career surfaces outside the plugin: profile wall + home card ───────── */
+
+.pp-wall { display: flex; flex-direction: column; gap: 0.6rem; }
+.pp-wall-head {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    font-weight: 600;
+    color: #e5e7eb;
+    font-size: 0.9rem;
+}
+.pp-wall-meta { color: #9ca3af; font-size: 0.7rem; font-weight: 400; }
+.pp-wall-shelf {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    padding: 0.35rem 0;
+    border-bottom: 1px solid rgba(75, 85, 99, 0.25);
+}
+.pp-wall-inst {
+    font-size: 0.62rem;
+    letter-spacing: 0.18em;
+    text-transform: uppercase;
+    color: #6b7280;
+    min-width: 3.6rem;
+}
+.pp-wall-cover {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 0.1rem;
+    width: 4.2rem;
+    height: 5.6rem;
+    border-radius: 0.3rem 0.45rem 0.45rem 0.3rem;
+    box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.07),
+        inset 0.25rem 0 0.4rem -0.25rem rgba(0, 0, 0, 0.8),
+        0 3px 8px rgba(0, 0, 0, 0.4);
+    padding: 0.3rem;
+    transition: transform 0.15s ease;
+}
+.pp-wall-cover:hover { transform: translateY(-3px); }
+.pp-wall-cover span {
+    font-size: 0.5rem;
+    font-weight: 700;
+    letter-spacing: 0.1em;
+    color: rgba(240, 226, 195, 0.9);
+    overflow-wrap: anywhere;
+    text-align: center;
+}
+.pp-wall-cover em {
+    font-size: 0.42rem;
+    letter-spacing: 0.22em;
+    font-style: normal;
+    color: #d9a253;
+}
+.pp-wall-none { font-size: 0.7rem; color: #6b7280; font-style: italic; }
+.pp-wall-link {
+    align-self: flex-end;
+    font-size: 0.72rem;
+    color: #22d3ee;
+    padding: 0.15rem 0.3rem;
+}
+.pp-wall-link:hover { text-decoration: underline; }
+
+/* The home-page career card — a trading card among stat tiles. */
+.pp-dash-card {
+    position: relative;
+    overflow: hidden;
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    gap: 0.2rem;
+    text-align: left;
+    padding: 1rem;
+    border-radius: 0.5rem;
+    border: 1px solid rgba(217, 162, 83, 0.35);
+    background:
+        linear-gradient(135deg, rgba(92, 35, 33, 0.85), rgba(30, 27, 34, 0.92)),
+        linear-gradient(160deg, #2b1414, #17111c);
+    box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.05), 0 4px 14px rgba(0, 0, 0, 0.35);
+    transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+.pp-dash-card:hover { transform: translateY(-2px); box-shadow: 0 8px 20px rgba(0, 0, 0, 0.5); }
+.pp-dash-shine {
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(105deg, transparent 42%, rgba(255, 223, 128, 0.18) 50%, transparent 58%);
+    transform: translateX(-130%);
+    pointer-events: none;
+}
+.pp-dash-card:hover .pp-dash-shine { animation: pp-foil 1.4s ease-out; }
+.pp-dash-head {
+    font-size: 0.58rem;
+    letter-spacing: 0.3em;
+    text-transform: uppercase;
+    color: #d9a253;
+}
+.pp-dash-badges { color: #f3ead2; font-size: 1.05rem; }
+.pp-dash-badges b { font-weight: 700; margin: 0 0.25rem 0 0.35rem; }
+.pp-dash-meta { color: #b5a488; font-size: 0.72rem; }
+.pp-dash-ask { color: #8d9aa8; font-size: 0.66rem; }
+.pp-dash-ask em { color: #cbd5e1; }
+
+.pp-card-actions { display: flex; gap: 0.5rem; margin-top: 0.9rem; }
+
+@media (prefers-reduced-motion: reduce) {
+    .pp-dash-card:hover .pp-dash-shine { animation: none; }
+    .pp-wall-cover, .pp-dash-card { transition: none; }
+}
+
+/* ── Gigs: poster, runner strip, summary, log ───────────────────────────── */
+
+.pp-poster {
+    position: relative;
+    width: min(92vw, 420px);
+    padding: 2rem 1.6rem 1.4rem;
+    border-radius: 0.5rem;
+    background: linear-gradient(180deg, #141019, #241318);
+    border: 2px solid rgba(217, 162, 83, 0.45);
+    box-shadow: 0 10px 32px rgba(0, 0, 0, 0.6);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.35rem;
+    text-align: center;
+}
+.pp-poster-venue { color: rgba(240, 226, 195, 0.7); font-size: 0.95rem; letter-spacing: 0.08em; }
+.pp-poster-presents { color: rgba(240, 226, 195, 0.4); font-size: 0.58rem; letter-spacing: 0.4em; text-transform: uppercase; }
+.pp-poster-title {
+    color: #d9a253;
+    font-size: 1.7rem;
+    font-weight: 800;
+    letter-spacing: 0.1em;
+    line-height: 1.15;
+    overflow-wrap: anywhere;
+}
+.pp-poster-inst { color: rgba(240, 226, 195, 0.5); font-size: 0.68rem; letter-spacing: 0.2em; text-transform: uppercase; }
+.pp-poster-bill { margin: 0.9rem 0 0.5rem; display: flex; flex-direction: column; gap: 0.35rem; width: 100%; }
+.pp-poster-line { color: rgba(240, 226, 195, 0.85); font-size: 0.85rem; }
+.pp-poster-line span { color: rgba(217, 162, 83, 0.7); margin-right: 0.35rem; }
+.pp-poster-line em { color: rgba(240, 226, 195, 0.5); font-style: italic; font-size: 0.72rem; }
+.pp-poster-line b { color: #f3d179; margin-left: 0.3rem; }
+.pp-poster-actions { display: flex; flex-wrap: wrap; gap: 0.5rem; justify-content: center; margin-top: 0.6rem; }
+.pp-poster-summary { cursor: default; }
+
+.pp-gig-strip {
+    position: fixed;
+    top: 0.5rem;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 35; /* above the rail (30), under popovers (40) — the chrome invariant */
+    background: rgba(10, 8, 14, 0.85);
+    border: 1px solid rgba(217, 162, 83, 0.4);
+    border-radius: 999px;
+    color: rgba(240, 226, 195, 0.85);
+    font-size: 0.72rem;
+    padding: 0.3rem 0.9rem;
+    pointer-events: none;
+    backdrop-filter: blur(2px);
+}
+.pp-gig-strip b { color: #d9a253; letter-spacing: 0.2em; }
+.pp-gig-strip em { color: #f3ead2; font-style: italic; }
+
+.pp-giglog { margin-top: 0.6rem; border-top: 1px dashed rgba(138, 122, 94, 0.4); padding-top: 0.5rem; }
+.pp-giglog-head {
+    font-size: 0.58rem;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: #8a7a5e;
+    margin-bottom: 0.25rem;
+}
+.pp-giglog-row { font-size: 0.7rem; color: #6d5d40; padding: 0.1rem 0; }
+.pp-giglog-row b { color: #9a5b16; letter-spacing: 0.06em; }

plugins/career/passports.json

@@ -3,6 +3,19 @@
         "songs": 5,
         "min_stars": 2
     },
+    "gig": {
+        "min_songs": 3,
+        "max_songs": 5,
+        "stakes_songs": 2,
+        "encore_accuracy": 0.75
+    },
+    "families": [
+        { "key": "metal", "match": ["metal", "djent", "grindcore", "thrash", "doom"] },
+        { "key": "blues", "match": ["blues"] },
+        { "key": "jazz", "match": ["jazz", "bebop", "swing", "bossa"] },
+        { "key": "funk", "match": ["funk", "disco"] },
+        { "key": "rock", "match": ["rock", "punk", "grunge", "shoegaze"] }
+    ],
     "genres": {
         "blues": { "virtuoso_nodes": { "guitar": ["blues_shuffle"] } },
         "rock": { "virtuoso_nodes": { "guitar": ["rock_power_backbeat"] } },

plugins/career/routes.py

@@ -26,11 +26,14 @@ Endpoints (all under /api/plugins/career/):
   POST   /passports/commit            commit to an instrument (the wax seal, Stage 0)
   POST   /passports/open              open a genre passport for an instrument
   POST   /drill-state                 relayed virtuoso.progress snapshot (drill intake)
+  POST   /gigs/propose                build a playable setlist for a genre gig
+  POST   /gigs                        log a COMPLETED gig (abandoned sets never log)
 """
 
 import hashlib
 import json
 import logging
+import random
 import re
 import shutil
 import tempfile
@@ -43,6 +46,8 @@ from pathlib import Path
 from fastapi import Body, HTTPException
 from fastapi.responses import FileResponse
 
+import sloppak
+from dlc_paths import _resolve_dlc_path
 from progression import instrument_for_arrangement
 
 PLUGIN_ID = "career"
@@ -50,6 +55,9 @@ VENUE_ID_RE = re.compile(r"^[a-z0-9_-]{1,40}$")
 PACK_FILENAME_RE = re.compile(r"^[a-z0-9_-]{1,64}\.(mp4|webm|mp3|json)$")
 REQUIRED_LOOPS = ("bored", "neutral", "engaged", "ecstatic")
 DOWNLOAD_CHUNK = 1024 * 256
+# A setlist is a handful of songs; this endpoint unpacks zips, so cap the work an
+# arbitrary caller can ask for.
+MAX_GIG_SONGS = 32
 
 _lock = threading.Lock()
 _state = {
@@ -114,10 +122,9 @@ def _stars():
     detail = []
     for filename, acc, title, artist in rows:
         acc = acc or 0.0
-        stars = sum(1 for t in thresholds if acc >= t)
+        stars, next_at = _star_progress(acc, thresholds)
         if stars:
             per_song[filename] = stars
-        next_at = next((t for t in thresholds if acc < t), None)
         detail.append({
             "filename": filename,
             "title": title or filename,
@@ -249,10 +256,18 @@ def _played_by_instrument_genre():
         for stub in stubs.values():
             acc = stub["best_accuracy"]
             stub["best_accuracy"] = round(acc, 4)
-            stub["stars"] = sum(1 for t in thresholds if acc >= t)
+            stub["stars"], stub["next_star_at"] = _star_progress(acc, thresholds)
     return out, seconds
 
 
+def _star_progress(acc, thresholds):
+    """(stars, next_star_at) — the one place the ascending-thresholds
+    assumption lives; _stars() and the passport stubs both use it."""
+    stars = sum(1 for t in thresholds if acc >= t)
+    next_at = next((t for t in thresholds if acc < t), None)
+    return stars, next_at
+
+
 def _library_genres():
     """Distinct effective genres across the live library (the brochure rack)."""
     db = _state["meta_db"]
@@ -276,12 +291,33 @@ def _library_genres():
                   key=lambda r: (-r["songs_in_library"], r["genre_key"]))
 
 
+def _genre_family(gkey):
+    """First family whose keyword appears in the genre key (substring — MB's
+    vocabulary is open: 'metalcore' must hit the 'metal' family without an
+    exact alias). List order decides ambiguity: families are checked top to
+    bottom, so 'blues rock' lands on whichever of blues/rock is listed first."""
+    for fam in _state["passports_content"].get("families") or []:
+        if not isinstance(fam, dict):
+            continue
+        for kw in fam.get("match") or []:
+            if isinstance(kw, str) and kw and kw in gkey:
+                return fam.get("key")
+    return None
+
+
 def _badge_requirement(gkey, instrument="guitar"):
     cfg = _state["passports_content"]
     req = dict(cfg.get("badge_requirement") or {})
     req.setdefault("songs", 5)
     req.setdefault("min_stars", 2)
-    override = (cfg.get("genres") or {}).get(gkey)
+    # Exact per-genre override wins; otherwise the genre inherits its FAMILY's
+    # requirement — so 'death metal' / 'metalcore' passports carry the metal
+    # drill without curating every MB sub-genre by hand.
+    genres_cfg = cfg.get("genres") or {}
+    override = genres_cfg.get(gkey)
+    if not isinstance(override, dict):
+        family = _genre_family(gkey)
+        override = genres_cfg.get(family) if family else None
     if isinstance(override, dict):
         req.update(override)
     # virtuoso_nodes: {instrument: [node_ids]} — a passport only carries its
@@ -299,10 +335,11 @@ def _badge_requirement(gkey, instrument="guitar"):
 def _drill_by_node():
     doc = _load_json(_drill_file(), {})
     if not isinstance(doc, dict):
-        return None, {}
+        return None, {}, {}
     snapshot = doc.get("snapshot") if isinstance(doc.get("snapshot"), dict) else {}
     by_node = snapshot.get("byNode") if isinstance(snapshot.get("byNode"), dict) else {}
-    return doc.get("received_at"), by_node
+    gold = snapshot.get("goldImprov") if isinstance(snapshot.get("goldImprov"), dict) else {}
+    return doc.get("received_at"), by_node, gold
 
 
 def _merge_drill_nodes(old, new):
@@ -336,6 +373,16 @@ def _merge_drill_nodes(old, new):
     return out
 
 
+def _merge_gold(old, new):
+    """Gained-only merge of goldImprov artifacts: a minted style never
+    un-mints via a stale relay; the FIRST artifact per style is kept."""
+    out = dict(old)
+    for style_id, art in (new or {}).items():
+        if isinstance(art, dict) and style_id not in out:
+            out[style_id] = art
+    return out
+
+
 def _node_cleared(by_node, node_id):
     """A drill counts as cleared on real completion evidence: mastered, any
     depth rung flipped true, or a key cleared (a top-tier clean pass in one
@@ -355,8 +402,9 @@ def _passports_view():
     cfg = _state["passports_content"]
     graded = set(cfg.get("graded_instruments") or [])
     st = _career_state()
+    all_gigs = st.get("gigs") if isinstance(st.get("gigs"), list) else []
     played, played_seconds = _played_by_instrument_genre()
-    received_at, by_node = _drill_by_node()
+    received_at, by_node, gold_improv = _drill_by_node()
     instruments = {}
     for inst in cfg.get("instruments") or []:
         committed_at = (st["instruments"].get(inst) or {}).get("committed_at")
@@ -382,9 +430,33 @@ def _passports_view():
                 # false badge denial — the doc's shown-not-judged rule.
                 badge = "shown_not_judged"
             elif qualifying >= req["songs"] and len(cleared) == len(required):
-                badge = "earned"
+                # Bronze is earned; GOLD upgrades it when a verified improv
+                # artifact exists for this genre's jam style. Virtuoso mints
+                # under raw STYLE_PALETTES ids ('punk', 'djent', 'disco', ...),
+                # which are mostly NOT family keys — so match in family space:
+                # the same keyword bucketing genres get ('punk' and 'punk
+                # rock' both bucket to 'rock'), with the exact key as a direct
+                # hit. Bronze remains a standalone win; gold never becomes an
+                # obligation.
+                fam = _genre_family(gkey)
+                gold = any(
+                    s == gkey or (fam is not None and _genre_family(s) == fam)
+                    for s in gold_improv
+                )
+                badge = "gold" if gold else "earned"
             else:
                 badge = "in_progress"
+            # Practice invitation: the non-qualifying songs closest to the
+            # QUALIFYING bar (the badge ask), nearest first — invitation
+            # data, the UI voices it without meters.
+            thresholds = _state["content"]["star_accuracy_thresholds"]
+            bar = (thresholds[req["min_stars"] - 1]
+                   if 0 < req["min_stars"] <= len(thresholds) else None)
+            nearest = [] if bar is None else sorted(
+                (s for s in songs if not s["qualifies"]),
+                key=lambda s: bar - s["best_accuracy"])[:3]
+            for s in nearest:
+                s["bar_at"] = bar
             passports.append({
                 "genre_key": gkey,
                 "genre": meta.get("genre") or gkey,
@@ -393,13 +465,18 @@ def _passports_view():
                 "graded": is_graded,
                 "songs": songs,
                 "qualifying_count": qualifying,
+                "nearest": nearest,
                 # Honest hours odometer (Stage 5 post-cap): a true fact that
                 # only grows — never a target, never a meter.
                 "seconds_total": round(played_seconds.get((inst, gkey), 0.0), 1),
                 "drills": {"required": required, "cleared": cleared},
                 "badge": badge,
             })
-        instruments[inst] = {"committed_at": committed_at, "passports": passports}
+        inst_gigs = [g for g in all_gigs if g.get("instrument") == inst]
+        for p in passports:
+            p["gigs"] = [g for g in inst_gigs if g.get("genre_key") == p["genre_key"]][-20:][::-1]
+        instruments[inst] = {"committed_at": committed_at, "passports": passports,
+                             "gig_count": len(inst_gigs)}
     return {
         "config": {
             "badge_requirement": cfg.get("badge_requirement") or {},
@@ -414,6 +491,72 @@ def _passports_view():
     }
 
 
+def _gig_config():
+    cfg = _state["passports_content"].get("gig")
+    cfg = cfg if isinstance(cfg, dict) else {}
+
+    def _num(key, default, cast):
+        # Tuning data, not code: junk falls back instead of 500ing both gig
+        # endpoints, and a legitimate 0 (stakes_songs: 0) is respected.
+        val = cfg.get(key)
+        if isinstance(val, bool) or not isinstance(val, (int, float)):
+            return default
+        return cast(val)
+
+    return {
+        "min_songs": max(1, _num("min_songs", 3, int)),
+        "max_songs": max(1, _num("max_songs", 5, int)),
+        "stakes_songs": max(0, _num("stakes_songs", 2, int)),
+        "encore_accuracy": _num("encore_accuracy", 0.75, float),
+    }
+
+
+def _current_venue():
+    """Highest unlocked venue (the room you can book today)."""
+    stars_total, _, _ = _stars()
+    best = None
+    for v in _state["content"]["venues"]:
+        if stars_total >= v["star_threshold"]:
+            if best is None or v["star_threshold"] >= best["star_threshold"]:
+                best = v
+    return best
+
+
+def _fill_genre_songs(gkey, exclude, limit):
+    """Library songs of a genre to round out a gig — ANY song of the genre the
+    set hasn't already picked.
+
+    Was `_unplayed_genre_songs`, restricted to `filename NOT IN song_stats`.
+    That restriction created a hole: a song you'd played on a DIFFERENT
+    instrument's arrangement has a stats row, so it was excluded here — and it
+    lives in the played bucket for THAT instrument, not this passport's, so it
+    was excluded there too. It could never be gigged. A player with 137 metalcore
+    songs, all played on another instrument, got a 404 (reproduced). The player's
+    library is the pool; whether a song has stats on some other instrument has no
+    bearing on whether it can be in THIS gig.
+
+    Shuffled, so re-roll actually changes the set. The old version returned the
+    library's first N in table order every time, so re-roll was a no-op for any
+    set drawn from the filler (reproduced).
+
+    ponytail: full genre scan + python-side match + shuffle (a few ms at 7k
+    songs, single-user); push into SQL if propose ever feels slow.
+    """
+    db = _state["meta_db"]
+    if db is None:
+        return []
+    rows = db.conn.execute(
+        f"SELECT filename, title, artist, {_genre_expr(db)} AS g FROM songs"
+    ).fetchall()
+    pool = [
+        {"filename": filename, "title": title or filename, "artist": artist or ""}
+        for filename, title, artist, genre in rows
+        if _genre_key(genre) == gkey and filename not in exclude
+    ]
+    random.shuffle(pool)   # re-roll must vary; free per call
+    return pool[:limit]
+
+
 def _validate_pack_dir(pack_dir: Path):
     """Raise ValueError unless pack_dir holds a complete venue pack."""
     manifest_path = pack_dir / "manifest.json"
@@ -585,16 +728,206 @@ def setup(app, context):
         # drops junk entries, which must not become a size-guard bypass.
         if len(json.dumps(body["byNode"])) > DRILL_SNAPSHOT_MAX_BYTES:
             raise HTTPException(413, "Snapshot too large.")
+        gold_in = body.get("goldImprov", {})
+        if not isinstance(gold_in, dict):
+            # A relay bug must be LOUD, not a silent 200 that drops gold.
+            raise HTTPException(400, "goldImprov must be an object keyed by style id.")
+        # Keep only plausible artifacts: a dict that names its verifier —
+        # an empty {} must not mint an evidence-free gold.
+        gold_in = {k: v for k, v in gold_in.items()
+                   if isinstance(v, dict) and v.get("verifier")}
+        # Same pre-merge bound byNode gets: the gained-only merge dropping
+        # junk must not become a size-guard bypass (nor lock-held CPU burn).
+        if len(json.dumps(gold_in)) > DRILL_SNAPSHOT_MAX_BYTES:
+            raise HTTPException(413, "Snapshot too large.")
         with _lock:
-            _, existing = _drill_by_node()
+            _, existing, existing_gold = _drill_by_node()
             snapshot = {"mode": body.get("mode"), "xp": body.get("xp"),
-                        "byNode": _merge_drill_nodes(existing, body["byNode"])}
+                        "byNode": _merge_drill_nodes(existing, body["byNode"]),
+                        "goldImprov": _merge_gold(existing_gold, gold_in)}
             if len(json.dumps(snapshot)) > DRILL_SNAPSHOT_MAX_BYTES:
                 raise HTTPException(413, "Snapshot too large.")
             _save_json(_drill_file(), {"received_at": _now_iso(),
                                        "snapshot": snapshot})
         return {"ok": True}
 
+    @app.post(f"/api/plugins/{PLUGIN_ID}/gigs/prepare")
+    def prepare_gig(body: dict = Body(...)):
+        """Unpack every song of the set BEFORE the gig starts.
+
+        A feedpak is a zip: the first play of one pays for its extraction into
+        sloppak_cache. Inside a set that cost landed BETWEEN songs — the player
+        finished a number and then sat waiting for the next one to unpack, mid-
+        gig. A set is a known list up front, so extract it all while the player
+        is still looking at the poster.
+
+        Idempotent and cheap on a warm cache: resolve_source_dir() returns the
+        already-unpacked dir without rewriting it. Best-effort per song — one
+        bad feedpak must not block the set from starting (the play itself will
+        surface the error, exactly as it does outside a gig).
+        """
+        raw = (body or {}).get("songs")
+        # A str is iterable: without the list check, "abc" would prepare three
+        # one-character "songs". Cap the count too — this endpoint unpacks zips,
+        # so an oversized list is real work, and a setlist is a handful of songs.
+        if not isinstance(raw, list):
+            return {"ok": True, "prepared": 0, "failed": []}
+        files = [f for f in raw if isinstance(f, str) and f.strip()][:MAX_GIG_SONGS]
+        if not files:
+            return {"ok": True, "prepared": 0, "failed": []}
+
+        # .get, not []: a host that doesn't hand us the resolvers (or has no
+        # library configured) must degrade to "extract lazily, as before" — this
+        # is an optimisation, and it is never allowed to be the thing that stops
+        # a gig from starting.
+        get_dlc = context.get("get_dlc_dir")
+        get_cache = context.get("get_sloppak_cache_dir")
+        dlc_root = get_dlc() if callable(get_dlc) else None
+        cache_root = get_cache() if callable(get_cache) else None
+        if dlc_root is None or cache_root is None:
+            return {"ok": False, "prepared": 0, "failed": files, "error": "no library"}
+
+        root = Path(dlc_root)
+        prepared, failed = 0, []
+        for fn in files:
+            # CONTAINMENT FIRST. resolve_source_dir() does a bare
+            # `dlc_root / filename` with no guard, so a crafted `../..` would
+            # walk straight out of the library. Every other filename-bound
+            # handler validates through _resolve_dlc_path; so does this one.
+            safe = _resolve_dlc_path(root, fn)
+            if safe is None:
+                _state["log"].warning("career: gig pre-extract rejected unsafe path %r", fn)
+                failed.append(fn)
+                continue
+            try:
+                sloppak.resolve_source_dir(fn, root, Path(cache_root))
+                prepared += 1
+            except Exception as exc:   # noqa: BLE001 — one bad pak can't sink the set
+                _state["log"].warning("career: gig pre-extract failed for %s: %s", fn, exc)
+                failed.append(fn)
+        return {"ok": True, "prepared": prepared, "failed": failed}
+
+    @app.post(f"/api/plugins/{PLUGIN_ID}/gigs/propose")
+    def propose_gig(body: dict = Body(...)):
+        inst = str((body or {}).get("instrument") or "")
+        genre = _genre_display((body or {}).get("genre"))
+        gkey = genre.lower()
+        if inst not in (_state["passports_content"].get("instruments") or []):
+            raise HTTPException(400, "Unknown instrument.")
+        if not gkey or len(genre) > GENRE_MAX_LEN:
+            raise HTTPException(400, "Provide a genre.")
+        cfg = _gig_config()
+        try:
+            size = int((body or {}).get("size") or 4)
+        except (TypeError, ValueError):
+            raise HTTPException(400, "size must be a number.")
+        size = max(cfg["min_songs"], min(cfg["max_songs"], size))
+        played, _seconds = _played_by_instrument_genre()
+        stubs = list(played.get((inst, gkey), {}).values())
+        req = _badge_requirement(gkey, inst)
+        qualifying = [s for s in stubs if s["stars"] >= req["min_stars"]]
+        rest = [s for s in stubs if s["stars"] < req["min_stars"]]
+        # The set: mostly songs you own, plus a couple of stakes songs near
+        # the bar; a young passport fills from unplayed genre songs so the
+        # first gig is how stubs start. random per call = free re-roll.
+        random.shuffle(qualifying)
+        rest.sort(key=lambda s: -s["best_accuracy"])
+        qtaken = max(1, size - cfg["stakes_songs"])
+        picks = qualifying[:qtaken]
+        for s in rest:
+            if len(picks) >= size:
+                break
+            picks.append(s)
+        # Surplus qualifying songs backfill a short set — a mature passport
+        # with no near-bar songs left must still fill the bill. Offset by how
+        # many QUALIFYING songs were taken, not len(picks): rest's stakes
+        # additions would otherwise skip eligible qualifying songs entirely.
+        for s in qualifying[qtaken:]:
+            if len(picks) >= size:
+                break
+            picks.append(s)
+        if len(picks) < size:
+            exclude = {s["filename"] for s in picks}
+            picks.extend(_fill_genre_songs(gkey, exclude, size - len(picks)))
+        if not picks:
+            raise HTTPException(404, "No songs of this genre in the library.")
+        venue = _current_venue()
+        return {
+            "instrument": inst,
+            "genre": genre,
+            "genre_key": gkey,
+            "venue_id": venue["id"] if venue else None,
+            "venue_name": venue["name"] if venue else "",
+            "songs": [{"filename": s["filename"], "title": s.get("title") or s["filename"],
+                       "artist": s.get("artist") or ""} for s in picks[:size]],
+        }
+
+    @app.post(f"/api/plugins/{PLUGIN_ID}/gigs")
+    def log_gig(body: dict = Body(...)):
+        # Called by the runner ONLY when the set completed — an abandoned set
+        # never logs (no fail state; the gig you finished is the gig you
+        # played). Accuracies come from song_stats, freshly written by the
+        # set's own plays.
+        inst = str((body or {}).get("instrument") or "")
+        genre = _genre_display((body or {}).get("genre"))
+        gkey = genre.lower()
+        venue_id = str((body or {}).get("venue_id") or "")
+        songs = (body or {}).get("songs")
+        if inst not in (_state["passports_content"].get("instruments") or []):
+            raise HTTPException(400, "Unknown instrument.")
+        if not gkey or len(genre) > GENRE_MAX_LEN:
+            raise HTTPException(400, "Provide a genre.")
+        if venue_id and (not VENUE_ID_RE.fullmatch(venue_id) or _venue(venue_id) is None):
+            raise HTTPException(400, "Unknown venue.")
+        if (not isinstance(songs, list) or not songs or len(songs) > 8
+                or not all(isinstance(f, str) and f.strip() for f in songs)):
+            raise HTTPException(400, "songs must be 1-8 filenames.")
+        db = _state["meta_db"]
+        entries = []
+        accuracies = []
+        for filename in songs:
+            title = filename
+            accuracy = None
+            if db is not None:
+                # The NEWEST row is the set's own just-recorded play — a
+                # MAX(last_accuracy) across arrangements would happily log a
+                # stale higher score from another instrument's old session.
+                row = db.conn.execute(
+                    "SELECT last_accuracy FROM song_stats WHERE filename = ? "
+                    "ORDER BY last_played_at DESC LIMIT 1",
+                    (filename,)).fetchone()
+                if row and row[0] is not None:
+                    accuracy = round(float(row[0]), 4)
+                    accuracies.append(accuracy)
+                trow = db.conn.execute(
+                    "SELECT title FROM songs WHERE filename = ?", (filename,)).fetchone()
+                if trow and trow[0]:
+                    title = trow[0]
+            entries.append({"filename": filename, "title": title, "accuracy": accuracy})
+        # Encore needs the WHOLE set scored at the bar — one scored song must
+        # not earn an encore for a set that was 4/5 unheard.
+        encore = (len(accuracies) == len(songs) and
+                  sum(accuracies) / len(accuracies) >= _gig_config()["encore_accuracy"])
+        gig = {
+            "at": _now_iso(),
+            "venue_id": venue_id or None,
+            "instrument": inst,
+            "genre": genre,
+            "genre_key": gkey,
+            "songs": entries,
+            "encore": encore,
+        }
+        with _lock:
+            st = _career_state()
+            if not isinstance(st.get("gigs"), list):
+                st["gigs"] = []
+            st["gigs"].append(gig)
+            # ponytail: hard cap — nothing reads past the last 20 per
+            # passport; the state file must not grow (and export) forever.
+            st["gigs"] = st["gigs"][-500:]
+            _save_json(_state_file(), st)
+        return {"ok": True, "gig": gig}
+
     @app.post(f"/api/plugins/{PLUGIN_ID}/packs/{{venue_id}}/download")
     def start_download(venue_id: str):
         venue = _venue(venue_id) if VENUE_ID_RE.fullmatch(venue_id) else None

plugins/career/screen.html

@@ -29,6 +29,7 @@
     <div id="career-tab-passports" class="hidden" role="tabpanel" aria-labelledby="career-tab-btn-passports">
         <p class="text-sm text-gray-400 mb-4">Commit to an instrument, pick a genre, and stamp your way to its badge — five ★★ songs mint a Bronze. Your passport wall is who you are as a musician.</p>
         <div id="pp-instruments" class="pp-instruments"></div>
+        <div id="pp-closest" class="mt-4"></div>
         <div id="pp-shelf-wrap" class="mt-5">
             <div id="pp-shelf" class="pp-shelf"></div>
         </div>

plugins/career/screen.js

@@ -12,6 +12,10 @@
     'use strict';
 
     const API = '/api/plugins/career';
+    // Unpacking a setlist is real work (zips, possibly on a slow/network drive),
+    // so this is generous — but it is a CEILING, not a wait. Past it we start the
+    // gig and let the first play extract lazily, as it always did.
+    const PREPARE_TIMEOUT_MS = 60000;
     const VENUE_OVERRIDE_KEY = 'feedBack-career-venue';
     const NO_VENUE = '__none__';
     const PREV_VIZ_KEY = 'feedBack-career-prev-viz';
@@ -38,6 +42,8 @@
     let _ppCeremonyActive = false;
     let _ppBootstrapped = false;
     let _ppNotified = {};        // badges chimed this session (slam still pending)
+    let _ppGigProposal = null;   // the booking poster's proposal, while open
+    let _ppGigRun = null;        // {songs, venue_id, genre, genre_key, instrument, idx} mid-set
 
     function $(id) { return document.getElementById(id); }
 
@@ -302,11 +308,15 @@
         } catch (_) { return {}; }
     }
 
-    function badgeId(inst, gkey) { return inst + '/' + gkey; }
+    // Bronze keeps the legacy un-suffixed id, so badges seen before the Gold
+    // tier existed stay seen; gold is a distinct moment with its own id.
+    function badgeId(inst, gkey, tier) { return inst + '/' + gkey + (tier === 'gold' ? '@gold' : ''); }
 
-    function markBadgeSeen(inst, gkey) {
+    function markBadgeSeen(inst, gkey, tier) {
         const seen = seenBadges();
-        seen[badgeId(inst, gkey)] = 1;
+        seen[badgeId(inst, gkey, tier)] = 1;
+        // A gold slam covers the bronze moment too — never queue both.
+        if (tier === 'gold') seen[badgeId(inst, gkey)] = 1;
         lsSet(PP_SEEN_KEY, JSON.stringify(seen));
     }
 
@@ -318,15 +328,19 @@
         const seen = seenBadges();
         for (const inst of Object.keys(view.instruments || {})) {
             for (const p of (view.instruments[inst].passports || [])) {
-                const id = badgeId(inst, p.genre_key);
-                if (p.badge !== 'earned' || seen[id] || _ppNotified[id]) continue;
+                if (p.badge !== 'earned' && p.badge !== 'gold') continue;
+                const gold = p.badge === 'gold';
+                const id = badgeId(inst, p.genre_key, p.badge);
+                if (seen[id] || _ppNotified[id]) continue;
                 _ppNotified[id] = true;
                 sfx('chime');
                 if (window.fbNotify && typeof window.fbNotify.show === 'function') {
                     window.fbNotify.show({
-                        big: true, icon: '🛂', accent: '#b45309',
-                        title: 'Badge earned!',
-                        message: `${p.genre} — Bronze, ready to stamp into your ${ppLabel(inst)} passport.`,
+                        big: true, icon: gold ? '🏅' : '🛂', accent: gold ? '#d9a253' : '#b45309',
+                        title: gold ? 'Gold — a verified improv!' : 'Badge earned!',
+                        message: gold
+                            ? `${p.genre} — your ${ppLabel(inst)} badge turns gold.`
+                            : `${p.genre} — Bronze, ready to stamp into your ${ppLabel(inst)} passport.`,
                     });
                 }
                 badgeCeremony(inst, p);
@@ -375,11 +389,11 @@
         el.innerHTML = `
             <canvas class="pp-confetti"></canvas>
             <div class="pp-ceremony-card">
-                <div class="pp-stamp pp-stamp-page pp-ceremony-stamp" style="--pp-rot:${ppJitter(p.genre_key, 7).toFixed(1)}deg">
+                <div class="pp-stamp pp-stamp-page pp-ceremony-stamp${p.badge === 'gold' ? ' pp-stamp-gold' : ''}" style="--pp-rot:${ppJitter(p.genre_key, 7).toFixed(1)}deg">
                     <span class="pp-stamp-genre">${esc(p.genre.toUpperCase())}</span>
-                    <span class="pp-stamp-tier">BRONZE</span>
+                    <span class="pp-stamp-tier">${p.badge === 'gold' ? 'GOLD' : 'BRONZE'}</span>
                 </div>
-                <div class="pp-ceremony-title">Badge earned</div>
+                <div class="pp-ceremony-title">${p.badge === 'gold' ? 'Gold — a verified improv' : 'Badge earned'}</div>
                 <div class="pp-ceremony-sub">${esc(p.genre)} — ${esc(ppLabel(inst))} passport</div>
             </div>`;
         let timer = 0;
@@ -443,7 +457,11 @@
             fetch(`${API}/drill-state`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ mode: snap.mode, xp: snap.xp, byNode: snap.byNode }),
+                body: JSON.stringify({
+                    mode: snap.mode, xp: snap.xp, byNode: snap.byNode,
+                    ...(snap.goldImprov && typeof snap.goldImprov === 'object' && !Array.isArray(snap.goldImprov)
+                        ? { goldImprov: snap.goldImprov } : {}),
+                }),
             }).then(() => refreshPassports()).catch(() => { /* next event retries */ });
         }, 1500);
     }
@@ -458,6 +476,8 @@
         _pp = view;
         detectNewBadges(view);
         renderPassports();
+        renderProfileWall();
+        renderDashCard();
         if (!_ppBootstrapped) {
             _ppBootstrapped = true;
             // Sync the local drill snapshot once per session — drill progress
@@ -479,9 +499,9 @@
 
     function ppCoverHTML(inst, p) {
         const rot = ppJitter(inst + p.genre_key, 1.6).toFixed(2);
-        const earned = p.badge === 'earned';
+        const earned = p.badge === 'earned' || p.badge === 'gold';
         const stamp = earned
-            ? `<span class="pp-stamp pp-stamp-mini" style="--pp-rot:${ppJitter(p.genre_key, 8).toFixed(1)}deg">BRONZE</span>`
+            ? `<span class="pp-stamp pp-stamp-mini${p.badge === 'gold' ? ' pp-stamp-gold' : ''}" style="--pp-rot:${ppJitter(p.genre_key, 8).toFixed(1)}deg">${p.badge === 'gold' ? 'GOLD' : 'BRONZE'}</span>`
             : '';
         const stubs = p.qualifying_count === 1 ? '1 stub' : `${p.qualifying_count} stubs`;
         const hours = fmtHours(p.seconds_total);
@@ -497,6 +517,56 @@
         </button>`;
     }
 
+    // Practice invitations: which stamps are closest, and what would bring
+    // them home. Invitations only — no meters, no obligations.
+
+    // Floor, never round: 74.9% must not display as the already-met "75%".
+    function pct(frac) { return Math.floor((Number(frac) || 0) * 100); }
+
+    function ppNeed(p) {
+        return Math.max(0, ((p.requirement || {}).songs || 0) - (p.qualifying_count || 0));
+    }
+
+    // The one blocker phrase — shared by the Closest-stamps strip and the
+    // passport book's invite line so they can never contradict each other.
+    function ppAskHTML(p, withHint) {
+        const req = p.requirement || {};
+        const need = ppNeed(p);
+        const starGl = '★'.repeat(req.min_stars || 0);
+        if (need > 0) {
+            const near = withHint ? (p.nearest || [])[0] : null;
+            const hint = near
+                ? ` · nearest: <em>${esc(near.title)}</em> at ${pct(near.best_accuracy)}%`
+                : '';
+            return `${need === 1 ? `one more ${starGl} song` : `${need} more ${starGl} songs`}${hint}`;
+        }
+        const labels = ((_pp && _pp.config) || {}).drill_labels || {};
+        const drills = p.drills || {};
+        const pending = (drills.required || []).filter((n) => !(drills.cleared || []).includes(n));
+        return `clear ${pending.map((n) => esc(labels[n] || n)).join(', ') || 'the genre drill'} in Virtuoso`;
+    }
+
+    function closestLineHTML(p) {
+        return `<button class="pp-closest-row" data-pp-open="${esc(p.genre_key)}">
+            <span class="pp-closest-genre">${esc(p.genre)}</span>
+            <span class="pp-closest-ask">${ppAskHTML(p, true)}</span>
+        </button>`;
+    }
+
+    function renderClosest(inst, data) {
+        const host = $('pp-closest');
+        if (!host) return;
+        const candidates = (data.passports || [])
+            .filter((p) => p.badge === 'in_progress')
+            .sort((a, b) => ppNeed(a) - ppNeed(b))
+            .slice(0, 3);
+        if (!candidates.length) { host.innerHTML = ''; return; }
+        host.innerHTML = `<div class="pp-closest">
+            <div class="pp-closest-head">Closest stamps</div>
+            ${candidates.map(closestLineHTML).join('')}
+        </div>`;
+    }
+
     function renderShelf(inst, data) {
         const shelf = $('pp-shelf');
         if (!shelf) return;
@@ -545,12 +615,13 @@
         const data = (_pp.instruments || {})[inst] || { passports: [] };
         host.innerHTML = ((_pp.config || {}).instruments || []).map((i) => {
             const d = (_pp.instruments || {})[i] || {};
-            const earned = (d.passports || []).filter((p) => p.badge === 'earned').length;
+            const earned = (d.passports || []).filter((p) => p.badge === 'earned' || p.badge === 'gold').length;
             const committed = !!d.committed_at;
             return `<button class="pp-inst${i === inst ? ' active' : ''}${committed ? '' : ' uncommitted'}" data-pp-inst="${esc(i)}">
                 ${esc(ppLabel(i))}${earned ? ` <span class="pp-inst-badges">⚡${earned}</span>` : ''}${committed ? '' : ' <span class="pp-inst-plus">+</span>'}
             </button>`;
         }).join('');
+        renderClosest(inst, data);
         renderShelf(inst, data);
         renderRack(inst, data);
     }
@@ -576,39 +647,36 @@
 
     function ppBookHTML(inst, p, pendingSlam) {
         const req = p.requirement || {};
-        const need = Math.max(0, (req.songs || 0) - p.qualifying_count);
         const starGl = '★'.repeat(req.min_stars || 0);
         const reqNodes = (p.drills || {}).required || [];
         const clearedNodes = new Set((p.drills || {}).cleared || []);
         const labels = ((_pp && _pp.config) || {}).drill_labels || {};
-        const pendingDrills = reqNodes.filter((n) => !clearedNodes.has(n));
-        // The invite names what actually blocks the stamp: songs first, then
-        // the genre drill once the song bar is met.
-        let invite;
-        if (need > 0) {
-            invite = need === 1 ? `One more ${starGl} song mints this stamp.`
-                : `${need} more ${starGl} songs mint this stamp.`;
-        } else {
-            const names = pendingDrills.map((n) => labels[n] || n).join(', ');
-            invite = `Clear ${names || 'the genre drill'} in Virtuoso to mint this stamp.`;
-        }
+        // The invite names what actually blocks the stamp — same shared
+        // phrase as the Closest-stamps strip, so they can't contradict.
+        const invite = `${ppAskHTML(p, false)} mints this stamp.`;
         let badgeArea = '';
         if (p.badge === 'shown_not_judged') {
             badgeArea = `<div class="pp-snj">Shown, not judged — your ${esc(ppLabel(inst).toLowerCase())} repertoire speaks for itself.</div>`;
-        } else if (p.badge === 'earned') {
-            badgeArea = `<div class="pp-stamp pp-stamp-page${pendingSlam ? ' pp-stamp-hidden' : ' pp-tilt'}" style="--pp-rot:${ppJitter(p.genre_key, 7).toFixed(1)}deg">
+        } else if (p.badge === 'earned' || p.badge === 'gold') {
+            const gold = p.badge === 'gold';
+            badgeArea = `<div class="pp-stamp pp-stamp-page${pendingSlam ? ' pp-stamp-hidden' : ' pp-tilt'}${gold ? ' pp-stamp-gold' : ''}" style="--pp-rot:${ppJitter(p.genre_key, 7).toFixed(1)}deg">
                 <span class="pp-stamp-genre">${esc(p.genre.toUpperCase())}</span>
-                <span class="pp-stamp-tier">BRONZE</span>
+                <span class="pp-stamp-tier">${gold ? 'GOLD' : 'BRONZE'}</span>
             </div>
-            <div class="pp-gold-foil" aria-hidden="true">GOLD</div>
-            <div class="pp-gold-note">Gold rung coming — improvise it, verified.</div>`;
+            ${gold
+        ? '<div class="pp-gold-foil" aria-hidden="true">GOLD</div><div class="pp-gold-note">A verified improv — the comb heard it live.</div>'
+        : '<div class="pp-gold-note">Gold rung: improvise over this style in a Virtuoso jam — verified, not self-reported.</div>'}
+            <div class="pp-card-actions">
+                <button class="career-btn career-btn-ghost" data-pp-card="save">Save card</button>
+                <button class="career-btn career-btn-ghost" data-pp-card="copy">Copy card</button>
+            </div>`;
         } else {
             const fill = (ppFillFraction(p) * 100).toFixed(0);
             badgeArea = `<div class="pp-stamp pp-stamp-page pp-stamp-ghost" style="--pp-rot:${ppJitter(p.genre_key, 7).toFixed(1)}deg; --pp-fill:${fill}%">
                 <span class="pp-stamp-genre">${esc(p.genre.toUpperCase())}</span>
                 <span class="pp-stamp-tier">BRONZE</span>
             </div>
-            <div class="pp-invite">${esc(invite)}</div>`;
+            <div class="pp-invite">${invite.charAt(0).toUpperCase()}${invite.slice(1)}</div>`;
         }
         const hours = fmtHours(p.seconds_total);
         const odometer = hours
@@ -628,15 +696,34 @@
             : `Play ${esc(p.genre)} songs at ${starGl} to collect ticket stubs.`;
         const stubsHTML = stubs.length ? stubs.map(ppStubHTML).join('')
             : `<div class="pp-stub-empty">${emptyLine}</div>`;
+        // Bring-these-up: nearest-to-the-bar songs (graded, unearned only —
+        // an earned page is memorabilia, not homework).
+        let nearest = '';
+        if (p.badge === 'in_progress' && (p.nearest || []).length) {
+            nearest = `<div class="pp-nearest">
+                <div class="pp-nearest-head">Bring these up</div>
+                ${p.nearest.map((s) =>
+                    `<div class="pp-nearest-row"><em>${esc(s.title)}</em> — best ${pct(s.best_accuracy)}%, ${starGl} at ${pct(s.bar_at)}%</div>`).join('')}
+            </div>`;
+        }
+        let gigLog = '';
+        if ((p.gigs || []).length) {
+            gigLog = `<div class="pp-giglog">
+                <div class="pp-giglog-head">Gigs played</div>
+                ${p.gigs.slice(0, 6).map((g) =>
+                    `<div class="pp-giglog-row">${esc((g.at || '').slice(0, 10))} · ${esc(_venueName(g.venue_id))}${g.encore ? ' · <b>encore</b>' : ''}</div>`).join('')}
+            </div>`;
+        }
         return `<div class="pp-book-wrap" data-pp-close-bg="1" role="dialog" aria-modal="true" aria-label="${esc(p.genre)} ${esc(ppLabel(inst))} passport">
             <div class="pp-book">
                 <div class="pp-page pp-page-left">
                     <div class="pp-page-head">${esc(p.genre)} — ${esc(ppLabel(inst))}</div>
                     ${badgeArea}${odometer}${drills}
+                    <button class="career-btn career-btn-primary pp-gig-book" data-pp-gig="${esc(p.genre_key)}">Book a gig</button>
                 </div>
                 <div class="pp-page pp-page-right">
                     <div class="pp-page-head">Ticket stubs</div>
-                    <div class="pp-stubs">${stubsHTML}</div>
+                    <div class="pp-stubs">${stubsHTML}${nearest}${gigLog}</div>
                 </div>
                 <div class="pp-book-cover pp-leather-${esc(inst)}">
                     <span class="pp-cover-title">${esc(p.genre.toUpperCase())}</span>
@@ -655,7 +742,8 @@
         if (!p || !overlay) return;
         _ppBook = { inst, gkey };
         _ppReturnFocus = document.activeElement;
-        const pending = p.badge === 'earned' && !seenBadges()[badgeId(inst, gkey)];
+        const pending = (p.badge === 'earned' || p.badge === 'gold')
+            && !seenBadges()[badgeId(inst, gkey, p.badge)];
         overlay.innerHTML = ppBookHTML(inst, p, pending);
         overlay.classList.remove('hidden');
         const close = overlay.querySelector('.pp-book-close');
@@ -677,7 +765,7 @@
                 stamp.classList.add('pp-tilt'); // freshly slammed = trading card too
                 if (book) book.classList.add('pp-shake');
                 sfx('stamp');
-                markBadgeSeen(inst, gkey);
+                markBadgeSeen(inst, gkey, p.badge);
                 renderPassports(); // the shelf cover gains its mini-stamp
             }, 950);
         }
@@ -685,6 +773,7 @@
 
     function closeBook() {
         _ppBook = null;
+        _ppGigProposal = null;   // a dismissed poster is a dismissed booking
         const overlay = $('pp-overlay');
         if (overlay) { overlay.classList.add('hidden'); overlay.innerHTML = ''; }
         if (_ppReturnFocus && typeof _ppReturnFocus.focus === 'function' &&
@@ -771,6 +860,579 @@
         if (_tiltEl) { resetTilt(_tiltEl); _tiltEl = null; }
     }
 
+    // ── Shareable passport card (canvas → PNG, save or clipboard) ─────────
+    // Keep in sync with the .pp-leather-* gradients in assets/career.css —
+    // canvas can't consume a CSS class, so the pairs live twice on purpose.
+    const PP_LEATHER_HEX = {
+        guitar: ['#5c2321', '#401412'],
+        bass: ['#1f3252', '#131f36'],
+        keys: ['#1e4034', '#122a21'],
+        drums: ['#3f3f46', '#26262b'],
+    };
+
+    function drawPassportCard(inst, p) {
+        const W = 480;
+        const H = 640;
+        const canvas = document.createElement('canvas');
+        canvas.width = W;
+        canvas.height = H;
+        const ctx = canvas.getContext('2d');
+        const [c1, c2] = PP_LEATHER_HEX[inst] || PP_LEATHER_HEX.guitar;
+        const bg = ctx.createLinearGradient(0, 0, W, H);
+        bg.addColorStop(0, c1);
+        bg.addColorStop(1, c2);
+        ctx.fillStyle = bg;
+        ctx.fillRect(0, 0, W, H);
+        // Emboss frame
+        ctx.strokeStyle = 'rgba(240,226,195,0.35)';
+        ctx.lineWidth = 3;
+        ctx.strokeRect(18, 18, W - 36, H - 36);
+        // Genre title
+        ctx.fillStyle = 'rgba(240,226,195,0.95)';
+        ctx.textAlign = 'center';
+        ctx.font = '700 34px Georgia, serif';
+        ctx.fillText(p.genre.toUpperCase(), W / 2, 92, W - 80);
+        ctx.font = '400 15px Georgia, serif';
+        ctx.fillStyle = 'rgba(240,226,195,0.55)';
+        ctx.fillText(`${ppLabel(inst).toUpperCase()} PASSPORT`, W / 2, 122);
+        // Stamp ring
+        const gold = p.badge === 'gold';
+        const ink = gold ? '#d9a253' : '#b06a2a';
+        const cy = 330;
+        ctx.strokeStyle = ink;
+        ctx.lineWidth = 6;
+        ctx.beginPath();
+        ctx.arc(W / 2, cy, 118, 0, Math.PI * 2);
+        ctx.stroke();
+        ctx.lineWidth = 2;
+        ctx.beginPath();
+        ctx.arc(W / 2, cy, 106, 0, Math.PI * 2);
+        ctx.stroke();
+        ctx.fillStyle = ink;
+        ctx.font = '800 26px Georgia, serif';
+        ctx.fillText(p.genre.toUpperCase(), W / 2, cy - 6, 190);
+        ctx.font = '600 16px Georgia, serif';
+        ctx.fillText(gold ? 'G O L D' : 'B R O N Z E', W / 2, cy + 28);
+        // Facts
+        const stubCount = (p.songs || []).filter((sng) => sng.qualifies).length;
+        const hours = fmtHours(p.seconds_total);
+        ctx.fillStyle = 'rgba(240,226,195,0.75)';
+        ctx.font = '400 17px Georgia, serif';
+        ctx.fillText(`${stubCount} ticket stub${stubCount === 1 ? '' : 's'}${hours ? ` · ${hours} played` : ''}`, W / 2, 512);
+        ctx.fillStyle = 'rgba(240,226,195,0.4)';
+        ctx.font = '400 13px Georgia, serif';
+        ctx.fillText('fee[dB]ack · career passport', W / 2, H - 44);
+        return canvas;
+    }
+
+    // One export path for every canvas artifact: copy (with download
+    // fallback + notice) or save, failures audible.
+    function exportCanvasPng(canvas, filename, mode, noun) {
+        canvas.toBlob(async (blob) => {
+            const fail = (why) => {
+                if (window.fbNotify) window.fbNotify.show({ icon: '⚠️', title: `${noun} export failed`, message: why });
+            };
+            if (!blob) { fail('The canvas produced no image.'); return; }
+            try {
+                const io = await import('/static/js/blob-io.js');
+                if (mode === 'copy') {
+                    const ok = await io.copyImageBlob(blob);
+                    if (ok) {
+                        if (window.fbNotify) window.fbNotify.show({ icon: '📋', title: `${noun} copied`, message: 'Paste it anywhere.' });
+                        return;
+                    }
+                    if (window.fbNotify) window.fbNotify.show({ icon: '💾', title: 'Clipboard unavailable', message: `Saved the ${noun.toLowerCase()} instead.` });
+                }
+                io.downloadBlob(blob, filename);
+            } catch (e) { fail('Export helper unavailable.'); }
+        }, 'image/png');
+    }
+
+    function exportPassportCard(mode) {
+        if (!_ppBook || !_pp) return;
+        const { inst, gkey } = _ppBook;
+        const p = (((_pp.instruments || {})[inst] || {}).passports || [])
+            .find((x) => x.genre_key === gkey);
+        if (!p) return;
+        const canvas = drawPassportCard(inst, p);
+        exportCanvasPng(canvas, `passport-${inst}-${gkey.replace(/[^a-z0-9-]+/g, '-')}.png`, mode, 'Card');
+    }
+
+    // ── Career surfaces outside the plugin screen ─────────────────────────
+    // Profile passport wall + the home-page career card. Both inject into
+    // core-owned mounts announced by v3:profile-rendered /
+    // v3:dashboard-rendered (the achievements seam). Absent-not-empty: with
+    // no committed instrument they render nothing and the dashboard keeps
+    // its built-in fallback stat.
+
+    function careerTotals() {
+        if (!_pp) return null;
+        let badges = 0;
+        let seconds = 0;
+        let gigs = 0;
+        const walls = [];
+        for (const inst of (_pp.config || {}).instruments || []) {
+            const d = (_pp.instruments || {})[inst];
+            // A commitment with no opened passport isn't a wall yet — the
+            // external surfaces (profile, home card) stay ABSENT until a
+            // passport exists (absent-not-empty).
+            if (!d || !d.committed_at || !(d.passports || []).length) continue;
+            const earned = (d.passports || []).filter((p) => p.badge === 'earned' || p.badge === 'gold');
+            badges += earned.length;
+            seconds += (d.passports || []).reduce((t, p) => t + (p.seconds_total || 0), 0);
+            gigs += d.gig_count || 0;
+            walls.push({ inst, earned, opened: d.passports.length });
+        }
+        if (!walls.length) return null;
+        return { badges, seconds, gigs, walls };
+    }
+
+    function closestAskHTML() {
+        if (!_pp) return '';
+        let best = null;
+        for (const inst of (_pp.config || {}).instruments || []) {
+            for (const p of (((_pp.instruments || {})[inst] || {}).passports || [])) {
+                if (p.badge !== 'in_progress') continue;
+                const need = Math.max(0, ((p.requirement || {}).songs || 0) - p.qualifying_count);
+                if (!best || need < best.need) best = { p, need };
+            }
+        }
+        if (!best) return '';
+        const starGl = '★'.repeat((best.p.requirement || {}).min_stars || 0);
+        if (best.need > 0) {
+            return `${esc(best.p.genre)} — ${best.need === 1 ? `one more ${starGl} song` : `${best.need} more ${starGl} songs`}`;
+        }
+        return `${esc(best.p.genre)} — one drill away`;
+    }
+
+    function renderProfileWall() {
+        const mount = document.getElementById('v3-profile-passports-mount');
+        if (!mount) return;
+        const totals = careerTotals();
+        if (!totals) { mount.innerHTML = ''; return; }
+        const shelves = totals.walls.map(({ inst, earned, opened }) => {
+            const covers = earned.map((p) =>
+                `<button class="pp-wall-cover pp-leather-${esc(inst)}" data-pp-wall-inst="${esc(inst)}" data-pp-wall-gkey="${esc(p.genre_key)}" title="${esc(p.genre)}">
+                    <span>${esc(p.genre.toUpperCase())}</span>
+                    <em>${p.badge === 'gold' ? 'GOLD' : 'BRONZE'}</em>
+                </button>`).join('');
+            const line = earned.length
+                ? covers
+                : `<span class="pp-wall-none">${opened} passport${opened === 1 ? '' : 's'} open — first stamp pending</span>`;
+            return `<div class="pp-wall-shelf"><span class="pp-wall-inst">${esc(ppLabel(inst))}</span>${line}</div>`;
+        }).join('');
+        const hours = fmtHours(totals.seconds);
+        mount.innerHTML = `<div class="bg-fb-card/80 backdrop-blur rounded-lg p-4 border border-fb-border/50 pp-wall">
+            <div class="pp-wall-head">
+                <span>Passport wall</span>
+                <span class="pp-wall-meta">${totals.badges} badge${totals.badges === 1 ? '' : 's'}${hours ? ` · ${hours} played` : ''}${totals.gigs ? ` · ${totals.gigs} gig${totals.gigs === 1 ? '' : 's'}` : ''}</span>
+            </div>
+            ${shelves}
+            <button class="pp-wall-link" data-pp-wall-career="1">Open career →</button>
+        </div>`;
+        if (!mount.dataset.ppWired) {
+            mount.dataset.ppWired = '1';
+            mount.addEventListener('click', onWallClick);
+        }
+    }
+
+    function onWallClick(e) {
+        const open = e.target.closest('[data-pp-wall-inst]');
+        if (open) {
+            // Two attributes, not a '/'-joined pair: a genre key may itself
+            // contain '/' ("drum/bass") and must round-trip intact.
+            const inst = open.dataset.ppWallInst;
+            const gkey = open.dataset.ppWallGkey;
+            lsSet(PP_INST_KEY, inst);
+            if (window.showScreen) window.showScreen('plugin-career');
+            showCareerTab('passports');
+            renderPassports();
+            openBook(inst, gkey);
+            return;
+        }
+        if (e.target.closest('[data-pp-wall-career]')) {
+            if (window.showScreen) window.showScreen('plugin-career');
+            showCareerTab('passports');
+        }
+    }
+
+    function renderDashCard() {
+        const slot = document.getElementById('v3-dash-career-slot');
+        if (!slot) return;
+        const totals = careerTotals();
+        if (!totals) return; // keep core's fallback stat card
+        const hours = fmtHours(totals.seconds);
+        const ask = closestAskHTML();
+        slot.innerHTML = `<button class="pp-dash-card" data-pp-wall-career="1">
+            <span class="pp-dash-shine" aria-hidden="true"></span>
+            <span class="pp-dash-head">Career</span>
+            <span class="pp-dash-badges">${'⚡'.repeat(Math.min(totals.badges, 5))}<b>${totals.badges}</b> badge${totals.badges === 1 ? '' : 's'}</span>
+            <span class="pp-dash-meta">${hours ? `${hours} played` : 'the stage is set'}${totals.gigs ? ` · ${totals.gigs} gig${totals.gigs === 1 ? '' : 's'}` : ''}</span>
+            ${ask ? `<span class="pp-dash-ask">closest: ${ask}</span>` : ''}
+        </button>`;
+        if (!slot.dataset.ppWired) {
+            slot.dataset.ppWired = '1';
+            slot.addEventListener('click', onWallClick);
+        }
+    }
+
+    // ── Gigs: booking poster → set runner → summary ──────────────────────
+
+    function _venueName(venueId) {
+        const v = (_state && _state.venues || []).find((x) => x.id === venueId);
+        return v ? v.name : (venueId || 'the stage');
+    }
+
+    function gigPosterHTML(prop) {
+        const bill = prop.songs.map((s, i) =>
+            `<div class="pp-poster-line"><span>${i + 1}.</span> ${esc(s.title)}${s.artist ? ` <em>${esc(s.artist)}</em>` : ''}</div>`).join('');
+        return `<div class="pp-book-wrap" data-pp-close-bg="1" role="dialog" aria-modal="true" aria-label="Gig poster">
+            <div class="pp-poster">
+                <div class="pp-poster-venue">${esc(prop.venue_name || 'The stage')}</div>
+                <div class="pp-poster-presents">presents</div>
+                <div class="pp-poster-title">${esc(prop.genre.toUpperCase())} NIGHT</div>
+                <div class="pp-poster-inst">${esc(ppLabel(prop.instrument))} · tonight</div>
+                <div class="pp-poster-bill">${bill}</div>
+                <div class="pp-poster-actions">
+                    <button class="career-btn career-btn-primary" data-pp-gig-play="1">Play the gig</button>
+                    <button class="career-btn career-btn-ghost" data-pp-gig-reroll="1">Re-roll</button>
+                    <button class="career-btn career-btn-ghost" data-pp-poster="save">Save</button>
+                    <button class="career-btn career-btn-ghost" data-pp-poster="copy">Copy</button>
+                </div>
+                <button class="pp-book-close" data-pp-close="1" aria-label="Close">✕</button>
+            </div>
+        </div>`;
+    }
+
+    async function bookGig(gkey) {
+        if (!_pp) return;
+        const inst = activeInstrument();
+        const p = (((_pp.instruments || {})[inst] || {}).passports || [])
+            .find((x) => x.genre_key === gkey);
+        if (!p) return;
+        try {
+            const res = await fetch(`${API}/gigs/propose`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ instrument: inst, genre: p.genre }),
+            });
+            if (!res.ok) return;
+            _ppGigProposal = await res.json();
+        } catch (_) { return; }
+        const overlay = $('pp-overlay');
+        if (!overlay) return;
+        _ppBook = null; // the poster replaces the book in the overlay
+        overlay.innerHTML = gigPosterHTML(_ppGigProposal);
+        overlay.classList.remove('hidden');
+        sfx('page');
+    }
+
+    // Unpack the whole set before the first note.
+    //
+    // A feedpak is a zip, and the first play of one pays for its extraction. In
+    // a set that cost landed BETWEEN songs: the player finished a number and
+    // then sat there waiting for the next one to unpack, mid-gig. The setlist is
+    // known up front, so warm it all while the poster is still on screen.
+    //
+    // Best-effort by design: a library that won't pre-extract must not stop the
+    // gig from starting — the play itself surfaces the error the same way it
+    // does outside a gig. Slow is better than blocked.
+    async function prepareGigSongs(prop, btn) {
+        const label = btn && btn.textContent;
+        if (btn) { btn.disabled = true; btn.textContent = 'Preparing set…'; }
+        // A bare `await fetch(...)` only rejects on a network ERROR — a server
+        // that accepts the connection and then never answers hangs forever, and
+        // the gig would never start. That would make this optimisation the very
+        // thing it promises never to be: the reason you cannot play. Give up
+        // waiting and let the first play extract lazily, exactly as before.
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), PREPARE_TIMEOUT_MS);
+        try {
+            await fetch(`${API}/gigs/prepare`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ songs: prop.songs.map((s) => s.filename) }),
+                signal: ctrl.signal,
+            });
+        } catch (_) {
+            // abort, offline, non-2xx — all the same: start the gig anyway.
+        } finally {
+            clearTimeout(timer);
+            if (btn) { btn.disabled = false; if (label) btn.textContent = label; }
+        }
+    }
+
+    async function startGig(btn) {
+        const prop = _ppGigProposal;
+        const q = window.feedBack && window.feedBack.playQueue;
+        if (!prop || !q || typeof q.start !== 'function' || typeof window.playSong !== 'function') return;
+
+        // Extract the setlist BEFORE the stage is borrowed and the queue starts,
+        // so a failure here leaves nothing half-applied to unwind.
+        await prepareGigSongs(prop, btn);
+        // The poster's Play could have been cancelled while we were unpacking.
+        if (_ppGigProposal !== prop) return;
+
+        // The gig BORROWS the stage: stash whatever venue/viz the user had so
+        // the set ending gives it back (unlike "Play here", which is an
+        // explicit persistent choice on the venue card).
+        let restore = null;
+        if (prop.venue_id) {
+            // Capture the restore snapshot BEFORE any write: if a later write
+            // (or setViz) throws, the stage must still be returnable.
+            try {
+                restore = {
+                    venue: localStorage.getItem(VENUE_OVERRIDE_KEY),
+                    viz: localStorage.getItem('vizSelection'),
+                };
+            } catch (_) { restore = null; }
+            try {
+                localStorage.setItem(VENUE_OVERRIDE_KEY, prop.venue_id);
+                localStorage.setItem('vizSelection', 'venue');
+                if (typeof window.setViz === 'function') window.setViz('venue');
+            } catch (_) { /* viz optional — restore stays intact */ }
+        }
+        // Push the gig's venue pack to the crowd layer NOW.
+        //
+        // crowd.setManifest(venue) is reached only through pushCrowdManifest,
+        // and pushCrowdManifest is called only from refresh() — the career
+        // tab's own reload. A gig navigates AWAY from the career tab to the
+        // player, so refresh() never runs during it, and setting the override
+        // above does nothing on its own. The result the testers saw: the venue
+        // visualization turns on (3D highway) but its crowd/stage pack never
+        // loads, so the song plays over the bare highway backdrop ("standard
+        // particles"), or over whatever venue a previous refresh() happened to
+        // leave applied. We just changed the override to this gig's venue, so
+        // re-push for it. _state is the career state the booking screen already
+        // fetched; guard for the rare null.
+        _appliedManifestVenue = null;
+        if (_state) pushCrowdManifest(_state);
+        _ppGigRun = {
+            songs: prop.songs,
+            venue_id: prop.venue_id,
+            genre: prop.genre,
+            genre_key: prop.genre_key,
+            instrument: prop.instrument,
+            idx: 0,
+            restore,
+        };
+        closeBook();
+        _ppGigProposal = null;
+        // RAW filenames: the queue itself encodes for playSong — pre-encoding
+        // double-encodes and breaks loading + the stats/gig filename join.
+        if (!q.start(prop.songs.map((s) => s.filename), { source: 'gig' })) {
+            _ppGigRun = null;
+            return;
+        }
+        renderGigStrip();
+    }
+
+    function restoreGigStage(run) {
+        const r = run && run.restore;
+        if (!r) return;
+        try {
+            if (r.venue == null) localStorage.removeItem(VENUE_OVERRIDE_KEY);
+            else localStorage.setItem(VENUE_OVERRIDE_KEY, r.venue);
+            if (r.viz && r.viz !== 'venue') {
+                localStorage.setItem('vizSelection', r.viz);
+                if (typeof window.setViz === 'function') window.setViz(r.viz);
+            }
+        } catch (_) { /* best effort */ }
+        _appliedManifestVenue = null;
+    }
+
+    function renderGigStrip() {
+        if (!_ppGigRun || !document.body || typeof document.createElement !== 'function') return;
+        let strip = document.getElementById('pp-gig-strip');
+        if (!strip) {
+            strip = document.createElement('div');
+            strip.id = 'pp-gig-strip';
+            strip.className = 'pp-gig-strip';
+            document.body.appendChild(strip);
+        }
+        const run = _ppGigRun;
+        const next = run.songs[run.idx + 1];
+        strip.innerHTML = `<b>GIG</b> · ${esc(run.genre)} at ${esc(_venueName(run.venue_id))} · set ${Math.min(run.idx + 1, run.songs.length)}/${run.songs.length}${next ? ` — next: <em>${esc(next.title)}</em>` : ' — closer!'}`;
+    }
+
+    function removeGigStrip() {
+        const strip = document.getElementById('pp-gig-strip');
+        if (strip) strip.remove();
+    }
+
+    function abandonGig() {
+        // No fail state: an abandoned set logs nothing and says nothing.
+        const run = _ppGigRun;
+        _ppGigRun = null;
+        removeGigStrip();
+        restoreGigStage(run);
+    }
+
+    function completeGig() {
+        const run = _ppGigRun;
+        _ppGigRun = null;
+        removeGigStrip();
+        restoreGigStage(run);
+        // The final song's own stats POST races this moment (both ride
+        // song:ended): wait for its stats:recorded — or a short timeout, since
+        // an UNSCORED play never emits one — so /gigs reads the set's real
+        // accuracies, not last week's.
+        const lastFile = run.songs[run.songs.length - 1].filename;
+        const sm = window.feedBack;
+        let done = false;
+        const proceed = () => {
+            if (done) return;
+            done = true;
+            if (sm && typeof sm.off === 'function') { try { sm.off('stats:recorded', onRec); } catch (_) { /* ok */ } }
+            postGig(run);
+        };
+        const onRec = (e) => {
+            const d = (e && e.detail) || {};
+            if (d.filename === lastFile) proceed();
+        };
+        if (sm && typeof sm.on === 'function') sm.on('stats:recorded', onRec);
+        setTimeout(proceed, 3500);
+    }
+
+    async function postGig(run) {
+        let gig = null;
+        try {
+            const res = await fetch(`${API}/gigs`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    instrument: run.instrument,
+                    genre: run.genre,
+                    venue_id: run.venue_id,
+                    songs: run.songs.map((s) => s.filename),
+                }),
+            });
+            if (res.ok) gig = (await res.json()).gig;
+        } catch (_) { /* summary still shows, unlogged */ }
+        showGigSummary(run, gig);
+        refreshPassports();
+    }
+
+    function showGigSummary(run, gig) {
+        if (!document.body || typeof document.createElement !== 'function') return;
+        const entries = (gig && gig.songs) || run.songs.map((s) => ({ filename: s.filename, title: s.title, accuracy: null }));
+        const encore = !!(gig && gig.encore);
+        if (encore && !reducedMotion()) {
+            const crowd = window.v3VenueCrowd;
+            if (crowd && typeof crowd.celebrate === 'function') {
+                try { crowd.celebrate(); } catch (_) { /* optional */ }
+            }
+        }
+        const el = document.createElement('div');
+        el.id = 'pp-gig-summary';
+        el.className = 'pp-ceremony-overlay';
+        el.innerHTML = `<canvas class="pp-confetti"></canvas>
+            <div class="pp-poster pp-poster-summary">
+                <div class="pp-poster-venue">${esc(_venueName(run.venue_id))}</div>
+                <div class="pp-poster-title">${esc(run.genre.toUpperCase())} NIGHT</div>
+                <div class="pp-poster-inst">${encore ? 'ENCORE! ' : ''}the set, as played</div>
+                <div class="pp-poster-bill">${entries.map((s, i) =>
+                    `<div class="pp-poster-line"><span>${i + 1}.</span> ${esc(s.title)}${s.accuracy != null ? ` <b>${Math.floor(s.accuracy * 100)}%</b>` : ''}</div>`).join('')}</div>
+                <div class="pp-poster-actions">
+                    <button class="career-btn career-btn-ghost" data-pp-poster="save">Save poster</button>
+                    <button class="career-btn career-btn-ghost" data-pp-poster="copy">Copy poster</button>
+                    <button class="career-btn career-btn-primary" data-pp-gig-done="1">Done</button>
+                </div>
+            </div>`;
+        el.addEventListener('click', (e) => {
+            if (e.target === el || e.target.closest('[data-pp-gig-done]')) {
+                el.remove();
+            } else if (e.target.closest('[data-pp-poster]')) {
+                exportGigPoster(e.target.closest('[data-pp-poster]').dataset.ppPoster,
+                    { ...run, encore, entries });
+            }
+        });
+        document.body.appendChild(el);
+        if (encore && !reducedMotion()) confettiBurst(el.querySelector('.pp-confetti'));
+    }
+
+    function drawGigPoster(data) {
+        const W = 480;
+        const H = 640;
+        const canvas = document.createElement('canvas');
+        canvas.width = W;
+        canvas.height = H;
+        const ctx = canvas.getContext('2d');
+        const bg = ctx.createLinearGradient(0, 0, 0, H);
+        bg.addColorStop(0, '#141019');
+        bg.addColorStop(1, '#241318');
+        ctx.fillStyle = bg;
+        ctx.fillRect(0, 0, W, H);
+        ctx.strokeStyle = 'rgba(217,162,83,0.5)';
+        ctx.lineWidth = 3;
+        ctx.strokeRect(16, 16, W - 32, H - 32);
+        ctx.textAlign = 'center';
+        ctx.fillStyle = 'rgba(240,226,195,0.65)';
+        ctx.font = '400 18px Georgia, serif';
+        ctx.fillText(_venueName(data.venue_id), W / 2, 76, W - 80);
+        ctx.font = '400 12px Georgia, serif';
+        ctx.fillText('P R E S E N T S', W / 2, 102);
+        ctx.fillStyle = '#d9a253';
+        ctx.font = '800 40px Georgia, serif';
+        ctx.fillText(`${data.genre.toUpperCase()}`, W / 2, 160, W - 60);
+        ctx.font = '800 26px Georgia, serif';
+        ctx.fillText('NIGHT', W / 2, 194);
+        if (data.encore) {
+            ctx.fillStyle = '#f3d179';
+            ctx.font = '700 16px Georgia, serif';
+            ctx.fillText('— E N C O R E —', W / 2, 226);
+        }
+        ctx.fillStyle = 'rgba(240,226,195,0.85)';
+        ctx.font = '400 18px Georgia, serif';
+        const entries = data.entries || data.songs || [];
+        entries.slice(0, 6).forEach((sng, i) => {
+            const acc = sng.accuracy != null ? `  ·  ${Math.floor(sng.accuracy * 100)}%` : '';
+            ctx.fillText(`${sng.title}${acc}`, W / 2, 290 + i * 44, W - 80);
+        });
+        ctx.fillStyle = 'rgba(240,226,195,0.4)';
+        ctx.font = '400 13px Georgia, serif';
+        ctx.fillText(`${ppLabel(data.instrument || 'guitar')} · fee[dB]ack career`, W / 2, H - 42);
+        return canvas;
+    }
+
+    function exportGigPoster(mode, data) {
+        exportCanvasPng(drawGigPoster(data),
+            `gig-${(data.genre_key || 'set').replace(/[^a-z0-9-]+/g, '-')}.png`, mode, 'Poster');
+    }
+
+    // Queue lifecycle: advance the strip per song; complete or abandon.
+    function onGigSongLoading() {
+        if (!_ppGigRun) return;
+        renderGigStrip();
+    }
+
+    function onGigSongEnded() {
+        if (!_ppGigRun) return;
+        const q = window.feedBack && window.feedBack.playQueue;
+        if (!q || typeof q.remaining !== 'function') return;
+        // Only OUR live queue counts: remaining()===0 is also true for a
+        // cleared/foreign queue (a manual play silently clears the gig queue,
+        // and that unrelated song's end must not log a gig).
+        if (q.source && q.source() !== 'gig') { abandonGig(); return; }
+        if (!q.remaining()) {
+            if (q.active && q.active()) completeGig();
+            else abandonGig();
+            return;
+        }
+        _ppGigRun.idx = Math.min(_ppGigRun.idx + 1, _ppGigRun.songs.length - 1);
+        renderGigStrip();
+    }
+
+    function onGigSongStop() {
+        // A deliberate quit mid-set (Escape clears the queue) abandons the
+        // gig — but the LAST song's teardown also fires song:stop after
+        // song:ended, so only abandon while songs genuinely remain.
+        if (!_ppGigRun) return;
+        const q = window.feedBack && window.feedBack.playQueue;
+        const active = q && typeof q.active === 'function' ? q.active() : false;
+        if (!active) abandonGig();
+    }
+
     function openGenre(inst, genre) {
         fetch(`${API}/passports/open`, {
             method: 'POST',
@@ -820,6 +1482,23 @@
             closeBook();
             return;
         }
+        const gigBtn = e.target.closest('[data-pp-gig]');
+        if (gigBtn) { bookGig(gigBtn.dataset.ppGig); return; }
+        if (e.target.closest('[data-pp-gig-play]')) { startGig(e.target.closest('[data-pp-gig-play]')); return; }
+        if (e.target.closest('[data-pp-gig-reroll]')) {
+            if (_ppGigProposal) bookGig(_ppGigProposal.genre_key);
+            return;
+        }
+        const posterBtn = e.target.closest('[data-pp-poster]');
+        if (posterBtn && _ppGigProposal) {
+            exportGigPoster(posterBtn.dataset.ppPoster, _ppGigProposal);
+            return;
+        }
+        const cardBtn = e.target.closest('[data-pp-card]');
+        if (cardBtn) {
+            exportPassportCard(cardBtn.dataset.ppCard);
+            return;
+        }
         const dlBtn = e.target.closest('[data-career-download]');
         const delBtn = e.target.closest('[data-career-delete]');
         const playBtn = e.target.closest('[data-career-play]');
@@ -870,6 +1549,10 @@
         if (sm && typeof sm.on === 'function') {
             // New song stats can add stars → thresholds may cross mid-session.
             sm.on('stats:recorded', () => refresh());
+            // Gig runner lifecycle (no-ops when no gig is live).
+            sm.on('song:loading', onGigSongLoading);
+            sm.on('song:ended', onGigSongEnded);
+            sm.on('song:stop', onGigSongStop);
             // Virtuoso's progress emits are the drill-state relay trigger; the
             // payload is a thin delta, so the relay reads the full localStorage
             // snapshot instead (see relayDrillState).
@@ -877,8 +1560,14 @@
         }
         showCareerTab(lsGet(PP_TAB_KEY) === 'passports' ? 'passports' : 'venues');
         document.addEventListener('keydown', (e) => {
-            if (e.key === 'Escape' && _ppBook) closeBook();
+            if (e.key !== 'Escape') return;
+            const overlay = $('pp-overlay');
+            if (_ppBook || (overlay && !overlay.classList.contains('hidden'))) closeBook();
         });
+        // Core re-renders profile/dashboard shells (innerHTML wipe) and
+        // announces the fresh mount points — same seam achievements uses.
+        document.addEventListener('v3:profile-rendered', renderProfileWall);
+        document.addEventListener('v3:dashboard-rendered', renderDashCard);
         refresh();
     }
 
@@ -886,7 +1575,11 @@
     // the badge-diff logic; nothing here touches the DOM.
     window.__careerPassportTest = {
         ppKey, ppJitter, ppLabel, detectNewBadges, seenBadges, markBadgeSeen,
-        fmtHours, ppFillFraction,
+        fmtHours, ppFillFraction, careerTotals, closestAskHTML,
+        onGigSongEnded, onGigSongStop,
+        setGigRun(r) { _ppGigRun = r; },
+        getGigRun() { return _ppGigRun; },
+        setView(v) { _pp = v; },
     };
 
     if (document.readyState === 'loading') {

plugins/career/tests/passports.test.js

@@ -150,3 +150,100 @@ test('ppFillFraction: song progress toward the bar, in-progress only', () => {
     assert.equal(ppFillFraction(p('in_progress', 3, 0)), 0);   // no bar → no fill
     assert.equal(ppFillFraction(null), 0);
 });
+
+test('careerTotals / wall + dash card stay absent without commitment', () => {
+    const w = load();
+    const t = w.__careerPassportTest;
+    // No _pp at all → null; committed-less view → null (absent-not-empty).
+    assert.equal(t.careerTotals(), null);
+    t.setView({ config: { instruments: ['guitar'] },
+        instruments: { guitar: { committed_at: null, passports: [] } } });
+    assert.equal(t.careerTotals(), null);
+    // Committed but zero passports opened: still absent (no zero-wall).
+    t.setView({ config: { instruments: ['guitar'] },
+        instruments: { guitar: { committed_at: 'x', passports: [] } } });
+    assert.equal(t.careerTotals(), null);
+    // Committed with an earned badge + hours → totals aggregate.
+    t.setView({ config: { instruments: ['guitar', 'bass'] },
+        instruments: {
+            guitar: { committed_at: 'x', passports: [
+                { badge: 'earned', seconds_total: 3600, genre: 'Blues', genre_key: 'blues' },
+                { badge: 'in_progress', seconds_total: 120, genre: 'Funk', genre_key: 'funk',
+                  qualifying_count: 4, requirement: { songs: 5, min_stars: 2 } }] },
+            bass: { committed_at: null, passports: [] },
+        } });
+    const totals = t.careerTotals();
+    assert.equal(totals.badges, 1);
+    assert.equal(totals.seconds, 3720);
+    assert.equal(totals.walls.length, 1);
+});
+
+test('gig runner lifecycle: advance on ended, abandon on dead-queue stop', () => {
+    const w = load();
+    const t = w.__careerPassportTest;
+    let remaining = 1;
+    w.feedBack = { playQueue: { remaining: () => remaining, active: () => remaining > 0 } };
+    t.setGigRun({
+        songs: [{ filename: 'a', title: 'A' }, { filename: 'b', title: 'B' }],
+        venue_id: null, genre: 'Soul', genre_key: 'soul', instrument: 'guitar', idx: 0,
+    });
+    // First song ends, one remains → the strip advances, no completion.
+    t.onGigSongEnded();
+    assert.equal(t.getGigRun().idx, 1);
+    // Stop while the queue is still active (end-of-song teardown) → run survives.
+    t.onGigSongStop();
+    assert.notEqual(t.getGigRun(), null);
+    // User quits: queue cleared → stop with a dead queue abandons (no log).
+    remaining = 0;
+    t.onGigSongStop();
+    assert.equal(t.getGigRun(), null);
+});
+
+test('a gold upgrade notifies even when the bronze moment was already seen', () => {
+    // Bronze seen under the legacy un-suffixed id; the badge then turns gold.
+    const w = load({ 'feedBack-career-badges-seen': '{"guitar/blues":1}' });
+    const t = w.__careerPassportTest;
+    const view = { instruments: { guitar: { passports: [
+        { genre_key: 'blues', genre: 'Blues', badge: 'gold' }] } } };
+    t.detectNewBadges(view);
+    assert.equal(w.notifications.length, 1);
+    assert.match(w.notifications[0].title, /Gold/);
+    // Same session: no duplicate.
+    t.detectNewBadges(view);
+    assert.equal(w.notifications.length, 1);
+    // Gold slam seen → fresh session stays silent.
+    t.markBadgeSeen('guitar', 'blues', 'gold');
+    const w2 = load({ 'feedBack-career-badges-seen': JSON.stringify(t.seenBadges()) });
+    w2.__careerPassportTest.detectNewBadges(view);
+    assert.equal(w2.notifications.length, 0);
+});
+
+test('a gold slam marks the bronze moment seen too — never both ceremonies', () => {
+    const w = load();
+    const t = w.__careerPassportTest;
+    t.markBadgeSeen('guitar', 'blues', 'gold');
+    const seen = JSON.parse(JSON.stringify(t.seenBadges()));
+    assert.equal(seen['guitar/blues@gold'], 1);
+    assert.equal(seen['guitar/blues'], 1);
+    // A later view where the badge reads 'earned' (e.g. gold state lost
+    // server-side) must not replay the bronze ceremony.
+    const view = { instruments: { guitar: { passports: [
+        { genre_key: 'blues', genre: 'Blues', badge: 'earned' }] } } };
+    const w2 = load({ 'feedBack-career-badges-seen': JSON.stringify(seen) });
+    w2.__careerPassportTest.detectNewBadges(view);
+    assert.equal(w2.notifications.length, 0);
+});
+
+test('careerTotals counts gold badges on the wall', () => {
+    const t = load().__careerPassportTest;
+    t.setView({
+        config: { instruments: ['guitar'] },
+        instruments: { guitar: { committed_at: 1, gig_count: 0, passports: [
+            { genre_key: 'blues', genre: 'Blues', badge: 'gold', seconds_total: 60 },
+            { genre_key: 'funk', genre: 'Funk', badge: 'in_progress', seconds_total: 0 },
+        ] } },
+    });
+    const totals = t.careerTotals();
+    assert.equal(totals.badges, 1);
+    assert.equal(totals.walls[0].earned[0].badge, 'gold');
+});

plugins/career/venue-packs/arena/manifest.json

@@ -0,0 +1,8 @@
+{
+    "venue": "arena",
+    "version": 1,
+    "loops": {"bored": "bored.mp4", "neutral": "neutral.mp4", "engaged": "engaged.mp4", "ecstatic": "ecstatic.mp4"},
+    "stingers": {"clap": "clap.mp4", "cheer": "cheer.mp4"},
+    "intro": {"video": "intro.mp4", "audio": "arena-ambience.mp3"},
+    "sfx": {"up": "sfx-up.mp3", "down": "sfx-down.mp3"}
+}

plugins/career/venue-packs/club/manifest.json

@@ -0,0 +1,8 @@
+{
+    "venue": "club",
+    "version": 1,
+    "loops": {"bored": "bored.mp4", "neutral": "neutral.mp4", "engaged": "engaged.mp4", "ecstatic": "ecstatic.mp4"},
+    "stingers": {"clap": "clap.mp4", "cheer": "cheer.mp4"},
+    "intro": {"video": "intro.mp4", "audio": "club-ambience.mp3"},
+    "sfx": {"up": "sfx-up.mp3", "down": "sfx-down.mp3"}
+}

plugins/folder_library/screen.js

@@ -878,6 +878,146 @@ function createFolderSurface(cfg) {
     var _dragRafId         = null;
     var _DRAG_THRESH = 5, _DRAG_ZONE = 150, _DRAG_SPEED = 50;
 
+    // ── Windowed song lists ─────────────────────────────────────────────
+    // A song list used to render EVERY song it held. On a flat 50,944-song
+    // library that is one <div> with 50,938 children and ~1.3 MILLION DOM nodes
+    // (~25 per row) — ~4.2 GB of renderer RSS, for a screen the user may not
+    // even be looking at. It also poisons unrelated code: any
+    // `document.querySelector` miss anywhere in the app must walk that whole
+    // tree, which is how song_preview's per-frame menu check ended up eating
+    // ~50% of the renderer and dropping the app to 2.7 fps (feedBack#965).
+    //
+    // So render only what is on screen. Rows are uniform height (and grid cards
+    // uniform size), so the window is pure arithmetic — no per-row observers.
+    // Off-window rows are represented by padding on the list itself rather than
+    // spacer elements: a spacer <div> would become a grid ITEM in grid view and
+    // shift the columns, whereas padding works identically for both layouts.
+    var VIRTUAL_MIN = 200;   // below this, render everything — no behaviour change
+    var VIRTUAL_BUFFER = 6;  // rows kept rendered above/below the viewport
+    var _virtualCleanups = [];
+    var _virtualLists = [];   // repaint fns, one per live windowed list
+
+    // Which slice of the list is on screen. Pure arithmetic — kept separate from
+    // the DOM so it can be tested directly (see tests/virtual_list.test.js).
+    //
+    //   top   : list's offset relative to the scroller viewport's top. NEGATIVE
+    //           once the user has scrolled the list's start above the fold.
+    //   rows  : total ROWS (grid packs `perRow` songs into one row; list view is 1)
+    //
+    // Returns the song index range [start, end) to render, plus how many ROWS of
+    // padding stand in for the songs above and below it.
+    function _visibleWindow(top, viewportH, itemH, perRow, rows, total) {
+        if (!(itemH > 0) || !(rows > 0)) return { start: 0, end: total, padRowsTop: 0, padRowsBottom: 0 };
+        var firstRow = Math.max(0, Math.floor(-top / itemH) - VIRTUAL_BUFFER);
+        var lastRow = Math.min(rows, Math.ceil((-top + viewportH) / itemH) + VIRTUAL_BUFFER);
+        // Scrolled entirely past the list (either direction): keep one row alive
+        // rather than emptying it, so the padding math stays anchored.
+        if (lastRow <= firstRow) {
+            firstRow = Math.min(firstRow, rows - 1);
+            lastRow = firstRow + 1;
+        }
+        return {
+            start: firstRow * perRow,
+            end: Math.min(total, lastRow * perRow),
+            padRowsTop: firstRow,
+            padRowsBottom: Math.max(0, rows - lastRow),
+        };
+    }
+
+    function _clearVirtualLists() {
+        _virtualCleanups.forEach(function (fn) { try { fn(); } catch (_) {} });
+        _virtualCleanups = [];
+        _virtualLists = [];
+    }
+
+    // Fill `list` with `songs`, windowed when the list is big enough to matter.
+    // `make(song)` builds one row/card.
+    function _fillSongList(list, songs, make) {
+        var sorted = _sortSongs(songs);
+        if (sorted.length <= VIRTUAL_MIN) {
+            sorted.forEach(function (s) { list.appendChild(make(s)); });
+            return;
+        }
+
+        var scroller = _getScrollEl();
+        var basePadTop = parseFloat(window.getComputedStyle(list).paddingTop) || 0;
+        var basePadBot = parseFloat(window.getComputedStyle(list).paddingBottom) || 0;
+
+        // Measure one real row once — no hardcoded row height to drift out of
+        // sync with the CSS. (The list is shown before it is populated, so this
+        // measures a laid-out row, not a zero-height one.)
+        var probe = make(sorted[0]);
+        probe.style.visibility = 'hidden';
+        list.appendChild(probe);
+        var probeRect = probe.getBoundingClientRect();
+        var rowH = probeRect.height || 44;
+        var cardW = probeRect.width || 150;
+        list.removeChild(probe);
+
+        var GRID_GAP = 12;   // matches the grid's `gap:12px`
+        var raf = 0, lastStart = -1, lastEnd = -1;
+
+        // Recomputed on EVERY paint, not captured once: a window resize changes
+        // the grid's column count, and therefore the row count and the height of
+        // the padding standing in for off-window rows. paint() runs on resize, so
+        // stale metrics would slice the wrong songs and mis-size the list.
+        function metrics() {
+            var perRow = 1, itemH = rowH;
+            if (_view === 'grid') {
+                perRow = Math.max(1, Math.floor((list.clientWidth + GRID_GAP) / (cardW + GRID_GAP)));
+                itemH = rowH + GRID_GAP;
+            }
+            return { perRow: perRow, itemH: itemH, rows: Math.ceil(sorted.length / perRow) };
+        }
+
+        function paint() {
+            raf = 0;
+            // Collapsed (display:none) or detached: nothing to paint, and don't
+            // pay for layout on every scroll tick of a section nobody can see.
+            // Forget the last window so re-showing repaints from scratch against
+            // the new position rather than short-circuiting on a stale memo.
+            if (!list.isConnected || list.offsetParent === null) {
+                lastStart = -1; lastEnd = -1;
+                return;
+            }
+            var m = metrics();
+            // Where the list sits relative to the scroller's viewport.
+            var top = list.getBoundingClientRect().top - scroller.getBoundingClientRect().top;
+            var vh = scroller.clientHeight || window.innerHeight;
+            var w = _visibleWindow(top, vh, m.itemH, m.perRow, m.rows, sorted.length);
+            if (w.start === lastStart && w.end === lastEnd) return;   // nothing moved
+            lastStart = w.start; lastEnd = w.end;
+
+            var frag = document.createDocumentFragment();
+            for (var i = w.start; i < w.end; i++) frag.appendChild(make(sorted[i]));
+            list.textContent = '';
+            list.style.paddingTop = (basePadTop + w.padRowsTop * m.itemH) + 'px';
+            list.style.paddingBottom = (basePadBot + w.padRowsBottom * m.itemH) + 'px';
+            list.appendChild(frag);
+        }
+        function schedule() { if (!raf) raf = window.requestAnimationFrame(paint); }
+
+        scroller.addEventListener('scroll', schedule, { passive: true });
+        window.addEventListener('resize', schedule);
+        // Expanding or collapsing ANY section moves every list below it. Those
+        // lists' windows are computed from their position, so they must repaint
+        // too — otherwise they keep the window from their old position and show
+        // blank padding where songs should be until the user happens to scroll.
+        _virtualLists.push(schedule);
+        _virtualCleanups.push(function () {
+            scroller.removeEventListener('scroll', schedule);
+            window.removeEventListener('resize', schedule);
+            if (raf) window.cancelAnimationFrame(raf);
+        });
+        paint();
+    }
+
+    // Re-window every live list — call after anything that can move them
+    // vertically (a folder expanding/collapsing, a section being shown).
+    function _repaintVirtualLists() {
+        _virtualLists.forEach(function (fn) { try { fn(); } catch (_) {} });
+    }
+
     function _getScrollEl() {
         var el = _treeEl();
         while (el && el !== document.documentElement) {
@@ -1159,8 +1299,8 @@ function createFolderSurface(cfg) {
 
         var _listPopulated = open;
         function _populateList() {
-            _sortSongs(folder.songs).forEach(function (s) {
-                list.appendChild(_view === 'grid' ? _songCard(s, folder.path) : _songRow(s, folder.path));
+            _fillSongList(list, folder.songs, function (s) {
+                return _view === 'grid' ? _songCard(s, folder.path) : _songRow(s, folder.path);
             });
             (folder.children || []).forEach(function (child) {
                 childrenWrap.appendChild(_folderSection(child, depth + 1));
@@ -1195,12 +1335,18 @@ function createFolderSurface(cfg) {
         hdr.addEventListener('click', function () {
             if (_query()) return;
             var nowOpen = content.style.display === 'none';
-            if (nowOpen && !_listPopulated) { _populateList(); _listPopulated = true; }
+            // Show BEFORE populating: a windowed list measures a real row and the
+            // scroller viewport, and both are zero while display:none.
             content.style.display = nowOpen ? '' : 'none';
+            if (nowOpen && !_listPopulated) { _populateList(); _listPopulated = true; }
             chev.style.transform  = nowOpen ? 'rotate(90deg)' : '';
             if (nowOpen) _openFolders.add(folder.path);
             else         _openFolders.delete(folder.path);
             _storeJSON('open', [..._openFolders]);
+            // This toggle moved everything below it — re-window the other lists,
+            // and re-window THIS one if it was already populated (its saved
+            // window was computed at its old position).
+            _repaintVirtualLists();
         });
 
         wrap.appendChild(hdr); wrap.appendChild(content);
@@ -1245,8 +1391,8 @@ function createFolderSurface(cfg) {
         }
         var _populated = _unsortedOpen;
         function _populate() {
-            _sortSongs(songs).forEach(function (s) {
-                list.appendChild(_view === 'grid' ? _songCard(s, '') : _songRow(s, ''));
+            _fillSongList(list, songs, function (s) {
+                return _view === 'grid' ? _songCard(s, '') : _songRow(s, '');
             });
         }
         if (_unsortedOpen) { _populate(); } else { list.style.display = 'none'; }
@@ -1255,10 +1401,12 @@ function createFolderSurface(cfg) {
         hdr.addEventListener('click', function () {
             if (_query()) return;
             _unsortedOpen = list.style.display === 'none';
-            if (_unsortedOpen && !_populated) { _populate(); _populated = true; }
+            // Show BEFORE populating — see the folder toggle above.
             list.style.display = _unsortedOpen ? (_view === 'grid' ? 'grid' : '') : 'none';
+            if (_unsortedOpen && !_populated) { _populate(); _populated = true; }
             chev.style.transform = _unsortedOpen ? 'rotate(90deg)' : '';
             _store(cfg.unsortedKey, String(_unsortedOpen));
+            _repaintVirtualLists();   // this toggle moved every list below it
         });
 
         wrap.appendChild(hdr); wrap.appendChild(list);
@@ -1340,6 +1488,10 @@ function createFolderSurface(cfg) {
     // ── Render ──────────────────────────────────────────────────────────
     function _render() {
         _hoveredFolder = null; // DOM is rebuilt; discard any stale reference
+        // Drop the scroll listeners of the previous render's windowed lists —
+        // their `list` nodes are about to be detached, and a surviving listener
+        // would keep painting into orphaned DOM (and leak on every re-render).
+        _clearVirtualLists();
         var treeEl = _treeEl();
         if (!treeEl) return;
         var data = _filtered();
@@ -1451,6 +1603,7 @@ function createFolderSurface(cfg) {
 
     // ── Unload (lib surface) ────────────────────────────────────────────
     function _unload() {
+        _clearVirtualLists();   // don't leave scroll listeners behind on teardown
         if (!cfg.searchInputId) return;
         var el = _el(cfg.searchInputId);
         if (el) el.style.maxWidth = '';
@@ -1554,6 +1707,8 @@ function createFolderSurface(cfg) {
         init: _init,
         onScreenChanged: _onScreenChanged,
         render: _render,
+        // Pure window arithmetic, exposed for tests (no DOM needed).
+        __test: { visibleWindow: _visibleWindow, VIRTUAL_MIN: VIRTUAL_MIN, VIRTUAL_BUFFER: VIRTUAL_BUFFER },
     };
 }
 
@@ -1656,6 +1811,7 @@ if (!window.__folderLibraryLib) {
     window.folderLibrary = {
         load:   function (force) { return _lib.load(force); },
         unload: function ()      { _lib.unload(); },
+        __test: _lib.__test,
     };
 
     // Auto-load if folder view was already active when this script was injected.

plugins/folder_library/tests/virtual_list.test.js

@@ -0,0 +1,165 @@
+// Windowed song lists (feedBack#965).
+//
+// A song list used to render EVERY song. On a flat 50,944-song library that is
+// one div with 50,938 children and ~1.3 MILLION DOM nodes (~25 per row) —
+// ~4.2 GB of renderer RSS, for a screen the user may not even be looking at. It
+// also poisoned unrelated code: any `document.querySelector` miss anywhere in
+// the app had to walk that whole tree.
+//
+// _visibleWindow is the arithmetic that decides which slice is on screen. If it
+// is wrong the list silently shows the wrong songs, or scrolls to the wrong
+// place, so it is tested directly — the DOM glue around it is not the risky bit.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+function load() {
+    const window = {
+        console,
+        document: {
+            readyState: 'complete',
+            addEventListener() {},
+            getElementById() { return null; },
+            querySelector() { return null; },
+            querySelectorAll() { return []; },
+            createElement() { return { style: {}, classList: { add() {}, remove() {}, contains() { return false; } }, addEventListener() {}, appendChild() {} }; },
+        },
+        addEventListener() {},
+        localStorage: { getItem() { return null; }, setItem() {} },
+        performance: { now: () => 0 },
+        setInterval() { return 0; },
+        clearInterval() {},
+        requestAnimationFrame() { return 0; },
+        cancelAnimationFrame() {},
+        getComputedStyle() { return { overflowY: 'visible', paddingTop: '0px', paddingBottom: '0px' }; },
+        innerHeight: 800,
+    };
+    window.window = window;
+    window.globalThis = window;
+    const ctx = vm.createContext(window);
+    vm.runInContext(fs.readFileSync(path.join(__dirname, '..', 'screen.js'), 'utf8'), ctx, { filename: 'screen.js' });
+    assert.ok(window.folderLibrary && window.folderLibrary.__test, 'plugin must expose __test');
+    return window.folderLibrary.__test;
+}
+
+const { visibleWindow, VIRTUAL_BUFFER, VIRTUAL_MIN } = load();
+
+// A flat 50k library in list view: 1 song per row, 44px rows, 800px viewport.
+const ROW = 44;
+const VH = 800;
+const TOTAL = 50938;
+
+test('the whole point: a 50k list renders a bounded window, not 50k rows', () => {
+    const w = visibleWindow(0, VH, ROW, 1, TOTAL, TOTAL);
+    const rendered = w.end - w.start;
+    assert.ok(rendered < 60, `expected a small window, got ${rendered} rows`);
+    // ~18 rows fit in 800px, plus buffer above and below.
+    assert.ok(rendered >= Math.ceil(VH / ROW), 'must at least fill the viewport');
+});
+
+test('at the top: starts at 0, all remaining rows are bottom padding', () => {
+    const w = visibleWindow(0, VH, ROW, 1, TOTAL, TOTAL);
+    assert.equal(w.start, 0);
+    assert.equal(w.padRowsTop, 0);
+    assert.equal(w.padRowsBottom, TOTAL - w.end);
+});
+
+test('scrolled into the middle: window tracks the scroll, padding adds up', () => {
+    const scrolled = 10000 * ROW;                 // row 10,000 at the fold
+    const w = visibleWindow(-scrolled, VH, ROW, 1, TOTAL, TOTAL);
+    assert.equal(w.start, (10000 - VIRTUAL_BUFFER) * 1);
+    assert.ok(w.end > w.start);
+    // The invariant that keeps the scrollbar honest: padding rows + rendered
+    // rows must account for every song, or the list changes height as you scroll.
+    assert.equal(w.padRowsTop + (w.end - w.start) + w.padRowsBottom, TOTAL);
+});
+
+test('at the very bottom: no bottom padding, end lands on the last song', () => {
+    const rows = TOTAL;
+    const scrolled = rows * ROW - VH;             // scrolled to the end
+    const w = visibleWindow(-scrolled, VH, ROW, 1, rows, TOTAL);
+    assert.equal(w.end, TOTAL);
+    assert.equal(w.padRowsBottom, 0);
+    assert.equal(w.padRowsTop + (w.end - w.start), TOTAL);
+});
+
+test('grid view: perRow songs collapse into one row', () => {
+    const perRow = 6;
+    const rows = Math.ceil(TOTAL / perRow);
+    const w = visibleWindow(0, VH, 190, perRow, rows, TOTAL);
+    assert.equal(w.start, 0);
+    assert.equal(w.start % perRow, 0, 'a window must start on a row boundary');
+    assert.ok(w.end <= TOTAL);
+    assert.ok((w.end - w.start) < 200, 'grid window must stay bounded');
+});
+
+test('scrolled far past the list: keeps one row, never a negative window', () => {
+    const w = visibleWindow(-99999999, VH, ROW, 1, TOTAL, TOTAL);
+    assert.ok(w.end > w.start, 'window must never invert');
+    assert.ok(w.start >= 0 && w.end <= TOTAL);
+    assert.equal(w.padRowsTop + (w.end - w.start) + w.padRowsBottom, TOTAL);
+});
+
+test('list not yet scrolled to (below the fold): still yields a valid window', () => {
+    const w = visibleWindow(5000, VH, ROW, 1, TOTAL, TOTAL);   // list starts below viewport
+    assert.equal(w.start, 0);
+    assert.ok(w.end > 0);
+});
+
+test('degenerate inputs fall back to rendering everything, never to a broken window', () => {
+    // Measured height of 0 (e.g. list still display:none) must not divide by zero
+    // and must not silently render an empty list.
+    const w = visibleWindow(0, VH, 0, 1, TOTAL, TOTAL);
+    assert.equal(w.start, 0);
+    assert.equal(w.end, TOTAL);
+    assert.equal(w.padRowsTop, 0);
+    assert.equal(w.padRowsBottom, 0);
+});
+
+test('small lists are below the virtualization threshold', () => {
+    assert.ok(VIRTUAL_MIN >= 100, 'threshold must be high enough that normal folders are untouched');
+});
+
+// ── the grid must be re-measured when the window resizes (CodeRabbit, #967) ──
+// perRow and rows were originally captured once at fill time. paint() also runs
+// on resize, so a narrower/wider window changed the column count while the
+// window maths still used the OLD one — slicing the wrong songs and mis-sizing
+// the padding. These pin that the geometry is a function of perRow, so a stale
+// perRow cannot silently survive.
+
+test('resizing the grid to fewer columns re-windows against the new row count', () => {
+    const total = 10000;
+    const wide = visibleWindow(0, VH, 190, 6, Math.ceil(total / 6), total);
+    const narrow = visibleWindow(0, VH, 190, 3, Math.ceil(total / 3), total);
+
+    // Same viewport, half the columns -> about half as many songs on screen.
+    assert.ok(narrow.end < wide.end, 'fewer columns must render fewer songs per screen');
+    // ...and the total must still add up, or the scrollbar lies after a resize.
+    for (const [w, perRow] of [[wide, 6], [narrow, 3]]) {
+        const rows = Math.ceil(total / perRow);
+        assert.equal(w.padRowsTop + Math.ceil((w.end - w.start) / perRow) + w.padRowsBottom, rows,
+            `rows must account for every song at perRow=${perRow}`);
+    }
+});
+
+test('a stale perRow would break the total-height invariant (the bug)', () => {
+    const total = 10000;
+    // Grid re-laid out to 3 columns, but windowed with the OLD perRow of 6:
+    // the row count no longer matches the geometry, and the padding is wrong.
+    const stalePerRow = 6, actualRows = Math.ceil(total / 3);
+    const bad = visibleWindow(0, VH, 190, stalePerRow, actualRows, total);
+    const accounted = bad.padRowsTop + Math.ceil((bad.end - bad.start) / 3) + bad.padRowsBottom;
+    assert.notEqual(accounted, actualRows,
+        'this asserts the FAILURE mode: mismatched perRow/rows must not silently look correct — ' +
+        'metrics() recomputes both together on every paint so this cannot happen in practice');
+});
+
+test('scrolled grid window always starts on a row boundary', () => {
+    const total = 10000, perRow = 4;
+    const rows = Math.ceil(total / perRow);
+    const w = visibleWindow(-5000, VH, 190, perRow, rows, total);
+    assert.equal(w.start % perRow, 0, 'a partial row would shift every card in the grid');
+});

plugins/highway_3d/screen.js

@@ -12614,8 +12614,19 @@
                         const tC = now + (dt0 + dt1) * 0.5 - BEHIND;
                         const b = laneBoundsFromAnchor(getChartAnchorAt(anchors, tC));
                         if (!b) continue;
-                        const z0 = dZ(dt0) + TS * BEHIND;
-                        const z1 = dZ(dt1) + TS * BEHIND;
+                        // The lane STOPS AT THE HIT LINE (z = 0) — issue #991. The
+                        // slice window starts BEHIND seconds in the past, so the
+                        // first slices map to positive z, i.e. past the hit line
+                        // toward the player. Nothing is ever drawn there: notes and
+                        // chord frames clamp to Math.min(0, dZ(dt)), so that strip
+                        // is lane with nothing on it. Clamp the NEAR edge only —
+                        // the far edge stays at dZ(AHEAD+BEHIND)+TS*BEHIND = -AHEAD*TS,
+                        // aligned with the note horizon, exactly as before.
+                        const z0 = Math.min(0, dZ(dt0) + TS * BEHIND);
+                        const z1 = Math.min(0, dZ(dt1) + TS * BEHIND);
+                        // Slice lies entirely past the hit line -> zero length, nothing
+                        // to draw. Skip before the arp probe so it costs nothing.
+                        if (z0 === z1) continue;
                         const arpSlice = (laneRailArpHsFlags && handShapesRails && handShapesRails.length)
                             ? arpeggioLaneOuterRailLaneSlice(
                                 dt0, dt1, now,
@@ -12764,9 +12775,13 @@
                     divMin = dMin;
                     divMax = dMax;
 
-                    // Same fix: extend to AHEAD+BEHIND so far edge = -AHEAD*TS.
-                    const laneLen = TS * (AHEAD + BEHIND);
-                    const zLane = -laneLen / 2 + TS * BEHIND;
+                    // Far edge at -AHEAD*TS (the note horizon), near edge at the
+                    // hit line (z = 0) — the lane does not run past it toward the
+                    // player, where nothing is ever drawn (#991). Spanning
+                    // AHEAD+BEHIND and shifting by +TS*BEHIND put the near edge at
+                    // +TS*BEHIND; spanning AHEAD alone keeps the same far edge.
+                    const laneLen = TS * AHEAD;
+                    const zLane = -laneLen / 2;
                     const laneOp = (HWY_LANE_STRIPE_OP_BASE + highwayIntensity * HWY_LANE_STRIPE_OP_INT)
                         * (_venueSceneOverride ? VENUE_LANE_OP_BOOST : 1);
                     mLaneOdd.opacity = laneOp;
@@ -12786,7 +12801,8 @@
                     }
 
                     if (highwayIntensity > 0.05) {
-                        const divLen = TS * (AHEAD + BEHIND);
+                        // Matches the lane above: ends at the hit line (#991).
+                        const divLen = TS * AHEAD;
                         const yPos = boardY + 0.03 * K;
                         const divOp2 = 0.02 + highwayIntensity * 0.1;
                         const divOpArp2 = Math.min(0.92, 0.16 + highwayIntensity * 0.42);
@@ -12799,7 +12815,7 @@
                         for (let f = fDivA; f <= fDivB; f++) {
                             if (hwyLaneArpOuterDividers && (f === fDivA || f === fDivB)) continue;
                             const div = pLaneDivider.get();
-                            div.position.set(xFret(f), yPos, dZ(0) - divLen * 0.5 + TS * BEHIND);
+                            div.position.set(xFret(f), yPos, -divLen * 0.5);
                             div.material = mLaneDivider;
                             div.scale.set(1, 1, divLen);
                             div.renderOrder = 2;
@@ -12818,8 +12834,10 @@
 
                 // ── Fret boundary extension lines ─────────────────────────
                 if (mLaneDividerExt && fretDividersVisible) {
-                    const extLaneLen = TS * (AHEAD + BEHIND);
-                    const extZMid = -extLaneLen / 2 + TS * BEHIND;
+                    // Same hit-line stop as the lane (#991) — otherwise these lines
+                    // would be the only floor geometry still running past it.
+                    const extLaneLen = TS * AHEAD;
+                    const extZMid = -extLaneLen / 2;
                     const extYPos = boardY + 0.03 * K;
                     mLaneDividerExt.opacity = Math.max(0.3, 0.3 + highwayIntensity * 0.15);
                     for (let f = 0; f <= NFRETS; f++) {
@@ -15388,6 +15406,41 @@
                 });
             },
 
+            // The host throttles paused frames to ~10 fps, on the assumption
+            // that a paused chart is a static picture and re-rendering it is
+            // pure waste (highway-constants._PAUSED_FRAME_INTERVAL_MS).
+            //
+            // That stopped being true when the venue landed. The venue backdrop
+            // is a PLAYING VIDEO and the crowd reacts on its own clock, and they
+            // are drawn into this same canvas as the highway — so throttling the
+            // highway throttled the whole room. Pausing the song dropped the
+            // venue, the crowd and the stage to 10 fps.
+            //
+            // Two independent sources of motion, and BOTH must keep their frames:
+            //
+            //  • a crowd video rolling on its own clock (career venue pack), and
+            //  • the venue scene's own fake-depth motion — the backdrop breathes,
+            //    the haze drifts, warmth pulses, the shimmer moves. That is
+            //    Math.sin(t) in the draw loop (see _venueApplyFakeDepthMotion),
+            //    so it only moves while we are actually given frames, and it runs
+            //    with NO pack at all.
+            //
+            // The throttle fires whenever the CHART CLOCK is stalled — which is
+            // not just a pause. A count-in and the credits/author overlay stall it
+            // exactly the same way, so the venue was stuttering there too.
+            //
+            // With no venue at all (plain 3D highway) the paused scene really is a
+            // still picture: motion mode reads 'off', we claim nothing, and the
+            // throttle still saves the GPU as #654 intended.
+            needsContinuousFrames() {
+                if (!_isReady || _ctxLost) return false;
+                for (const v of _venueCrowdVideos) {
+                    if (v && !v.paused && !v.ended && v.readyState >= 2) return true;
+                }
+                // 'off' also covers prefers-reduced-motion and "no venue scene".
+                try { return _venueEffectiveMotionMode() !== 'off'; } catch (_) { return false; }
+            },
+
             draw(bundle) {
                 if (!_isReady) return;
                 if (_ctxLost) return;   // GPU context lost (alt-tab / reset) — skip until restored

server.py

@@ -1115,7 +1115,10 @@ async def startup_status_stream(request: Request):
 @app.post("/api/rescan")
 def trigger_rescan():
     """Manually trigger a library rescan."""
-    if not scan.kick_scan():
+    # force=True: a manual Refresh must skip the directory-signature fast path —
+    # it is the escape hatch for the one change dir mtimes can't see (a pack
+    # rewritten in place under the same name).
+    if not scan.kick_scan(force=True):
         return {"message": "Scan already in progress"}
     return {"message": "Rescan started"}
 
@@ -1133,7 +1136,7 @@ def trigger_full_rescan():
         # delete_missing() prunes anything genuinely gone at the end.
         meta_db.conn.execute("UPDATE songs SET mtime = -1")
         meta_db.conn.commit()
-    if not scan.kick_scan():
+    if not scan.kick_scan(force=True):
         return {"message": "Scan already in progress"}
     return {"message": "Full rescan started"}
 

static/app.js

@@ -1334,12 +1334,25 @@ if (window.feedBack) window.feedBack.closeCurrentSong = closeCurrentSong;
 // leaving the player still leaves — and abandons the queue.
 window.feedBack.playQueue = (function () {
     let list = [], idx = -1, source = '', arrangements = null;
+    // Set true by _play() right before it drives playSong, consumed once by
+    // playSong's clear-guard. The primary "don't clear the queue I'm driving"
+    // signal is options.fromQueue, but a chain of plugin playSong wrappers
+    // (nam_tone, midi_amp, fretboard, invert_highway, tabview, ...) forward only
+    // (filename, arrangement) and silently drop the options object — so the flag
+    // never arrived and the queue cleared itself the instant its first song
+    // started (a gig/album/playlist never advanced). This flag rides beside the
+    // wrapper chain, not through it.
+    let _internalPlay = false;
     const active = () => idx >= 0 && idx < list.length;
     const hasNext = () => active() && idx < list.length - 1;
     function clear() { list = []; idx = -1; source = ''; arrangements = null; }
     function _play(i) {
         const fn = list[i];
-        // fromQueue keeps the queue from clearing itself; playSong decodeURIs.
+        // fromQueue is the in-band signal; _internalPlay is the out-of-band one
+        // that survives wrapper chains dropping the options arg. Both set; either
+        // suffices. playSong runs its clear-guard synchronously at entry, and the
+        // wrapper chain reaches it synchronously, so the flag is still set then.
+        _internalPlay = true;
         window.playSong(encodeURIComponent(fn), arrangements ? arrangements[i] : undefined, { fromQueue: true });
     }
     function start(files, opts) {
@@ -1371,6 +1384,15 @@ window.feedBack.playQueue = (function () {
     }
     return {
         start: start, advance: advance, hasNext: hasNext, active: active, clear: clear,
+        // True when the current song is a queue ADVANCE (song 2..N of a set),
+        // false for its first song or a standalone play. The venue uses this to
+        // fly in once on arrival at the set, then continue the room between
+        // songs instead of replaying the arrival flyover every track.
+        isContinuation: function () { return active() && idx > 0; },
+        // One-shot: true iff _play just kicked off this playSong. Consumed on
+        // read so a later MANUAL play still clears the queue. playSong calls this
+        // instead of trusting options.fromQueue to survive the wrapper chain.
+        _consumeInternalPlay: function () { const v = _internalPlay; _internalPlay = false; return v; },
         source: function () { return source; },
         remaining: function () { return active() ? list.length - idx - 1 : 0; },
         // What's coming, for consumers that RENDER the queue (a results
@@ -2297,11 +2319,14 @@ configureHost({
     currentFilename: () => currentFilename,
 });
 
+// `esc` is here for out-of-tree plugins only: their screen.js loads as a classic
+// script and called esc() back when app.js was one too and it was an implicit
+// global. Nothing in core reads window.esc — import it from ./js/dom.js instead.
 Object.assign(window, {
     _confirmDialog, _getArrangementNamingMode, _libraryLocalFilename, _librarySongArtUrl,
     _librarySongId, _onHeaderClick, _onNamingModeChange, _trapFocusInModal,
     changeArrangement, checkPluginUpdates, clearLibFilters, clearLoop,
-    deleteSelectedLoop, exportDiagnostics, exportSettings, filterFavorites,
+    deleteSelectedLoop, esc, exportDiagnostics, exportSettings, filterFavorites,
     filterLibrary, fullRescanLibrary, goFavPage, handleSliderInput,
     hideScanBanner, importSettings, loadPlugins, loadSavedLoop,
     loadSettings, onSectionPracticeModeChange, openEditModal, persistSetting,

static/highway.js

@@ -986,6 +986,22 @@ function createHighway() {
                 // inline arrow function.
                 function _handleAsyncInitFailure(e) {
                     if (hwState._renderer !== _installedRenderer) return;
+                    // ...and ignore a rejection from a SUPERSEDED init cycle.
+                    //
+                    // A renderer mints a fresh readyPromise on every init(), and
+                    // rejects the previous one ("superseded") when a newer init
+                    // starts. The renderer object is unchanged, so the identity
+                    // check above does not catch it — and we would tear down a
+                    // perfectly healthy renderer that is merely re-initialising.
+                    //
+                    // This is exactly what starting a gig did: setViz('venue')
+                    // installed the 3D renderer, then the queue's playSong()
+                    // re-initialised it a tick later; init #1's promise rejected,
+                    // and the gig dropped to the fallback 2D highway with the
+                    // venue gone. A superseded init is not a failed init — the
+                    // NEW cycle owns the outcome, and its own promise is what we
+                    // must judge.
+                    if (_installedRenderer.readyPromise !== rp) return;
                     console.error('renderer async init failure:', e);
                     _destroyCurrentIfInited();
                     hwState._renderer = _defaultRenderer;
@@ -1159,6 +1175,17 @@ function createHighway() {
             ' (user ' + hwState._renderScale.toFixed(2) + ' / auto ' + hwState._autoScale.toFixed(2) + ')';
     }
 
+    // Optional renderer capability: "my picture keeps moving even when the chart
+    // clock is stopped". Anything a renderer animates on its own clock (the 3D
+    // highway's venue video + crowd) has to opt out of the paused-frame throttle
+    // or it renders at 10 fps while the song is paused. Absent / throwing =
+    // false, so every existing renderer keeps the throttle unchanged.
+    function _rendererNeedsContinuousFrames() {
+        const r = hwState._renderer;
+        if (!r || typeof r.needsContinuousFrames !== 'function') return false;
+        try { return r.needsContinuousFrames() === true; } catch (_) { return false; }
+    }
+
     function draw() {
         hwState.animFrame = requestAnimationFrame(draw);
         if (!hwState.canvas || !hwState._renderer) return;
@@ -1223,7 +1250,15 @@ function createHighway() {
             const _nowP = performance.now();
             if (_nowP - hwState._chartLastAdvanceAt > _CHART_MAX_INTERP_MS) {
                 _paused = true;
-                if (_nowP - hwState._lastPausedDrawAt < _PAUSED_FRAME_INTERVAL_MS) return;
+                // ...unless the renderer says its picture is NOT static while
+                // paused. The throttle assumes a paused chart is a still frame,
+                // but a renderer can own content on a clock of its own — the 3D
+                // highway draws the venue's video backdrop and its reactive crowd
+                // into this same canvas, so throttling the highway throttled the
+                // whole room to 10 fps whenever the song was paused. Optional
+                // method: renderers that don't implement it keep the throttle.
+                if (!_rendererNeedsContinuousFrames()
+                    && _nowP - hwState._lastPausedDrawAt < _PAUSED_FRAME_INTERVAL_MS) return;
                 hwState._lastPausedDrawAt = _nowP;
             }
         }

static/js/blob-io.js

@@ -0,0 +1,28 @@
+// Blob export helpers — the download idiom that used to be duplicated in
+// settings-io.js and diagnostics-export.js, plus image-to-clipboard for
+// shareable cards/posters. A LEAF module: imports nothing. Classic-script
+// plugins reach it via dynamic import('/static/js/blob-io.js').
+
+export function downloadBlob(blob, filename) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+
+// Copy an image blob to the system clipboard. Returns true on success, false
+// when the Clipboard API is unavailable or refuses (insecure context, no user
+// gesture, permission denied) — callers fall back to downloadBlob and say so.
+export async function copyImageBlob(blob) {
+    try {
+        if (!navigator.clipboard || typeof ClipboardItem === 'undefined') return false;
+        await navigator.clipboard.write([new ClipboardItem({ [blob.type || 'image/png']: blob })]);
+        return true;
+    } catch (_) {
+        return false;
+    }
+}

static/js/diagnostics-export.js

@@ -21,6 +21,8 @@
 //      redact toggles.
 //   3. Stream the returned zip to disk.
 
+import { downloadBlob } from './blob-io.js';
+
 function _diagIncludeFromUI() {
     const v = (id) => document.getElementById(id)?.checked !== false;
     return {
@@ -265,14 +267,7 @@ export async function exportDiagnostics() {
     }
     try {
         const blob = await resp.blob();
-        const url = URL.createObjectURL(blob);
-        const a = document.createElement('a');
-        a.href = url;
-        a.download = filename;
-        document.body.appendChild(a);
-        a.click();
-        document.body.removeChild(a);
-        URL.revokeObjectURL(url);
+        downloadBlob(blob, filename);
         status.textContent = `Exported ${filename}`;
     } catch (e) {
         status.textContent = `Export failed during download: ${e.message}`;

static/js/library.js

@@ -410,6 +410,51 @@ function _applyLibraryProviderToParams(params) {
     return params;
 }
 
+// ── Instrument-aware tuning (the bass-player tuning-filter report) ───────────
+// A song's bass chart is often tuned differently from its guitar chart, so the
+// tuning facet, the `tunings` filter, the tuning sort and the row's tuning
+// badge must all speak for the instrument the player actually plays. Read the
+// host's working-tuning capability (the live selection, seeded from
+// /api/settings at boot) rather than adding another settings fetch; hosts
+// without the capability keep the guitar behaviour.
+const _LIB_PERSPECTIVES = ['guitar-lead', 'guitar-rhythm', 'bass'];
+let _libSettingsProfile = '';
+
+export function _setLibraryProfile(profileId) {
+    _libSettingsProfile = _LIB_PERSPECTIVES.includes(profileId) ? profileId : '';
+}
+
+export function _libraryInstrument() {
+    // The PROFILE is the only three-valued source (lead / rhythm / bass); the
+    // working-tuning capability knows guitar-vs-bass but not lead-vs-rhythm,
+    // so it is only the fallback.
+    if (_libSettingsProfile) return _libSettingsProfile;
+    try {
+        const wt = window.feedBack?.workingTuning;
+        if (wt && typeof wt.get === 'function') {
+            const cur = wt.get();
+            if (cur?.instrument === 'bass') return 'bass';
+        }
+    } catch { /* capability absent/erroring — lead guitar is the safe default */ }
+    return 'guitar-lead';
+}
+
+export function _libraryInstrumentLabel() {
+    const p = _libraryInstrument();
+    return p === 'bass' ? 'bass' : p === 'guitar-rhythm' ? 'rhythm' : 'lead';
+}
+
+// The tuning a row should SHOW: the bass chart's for a bass player, falling
+// back to the song (guitar-derived) tuning when the song has no bass
+// arrangement — the common case, not an edge path.
+function _rowTuningRaw(song) {
+    const p = _libraryInstrument();
+    const field = p === 'bass' ? 'bass_tuning_name'
+        : p === 'guitar-rhythm' ? 'rhythm_tuning_name' : '';
+    if (field && song[field]) return song[field];
+    return song.tuning || song.tuning_name || '';
+}
+
 export function _resetLibraryProviderViewState() {
     L.libEpoch++;
     L.currentPage = 0;
@@ -768,6 +813,8 @@ export function _applyLibFiltersToParams(params) {
     if (_libFilters.stemsLacks.length) params.set('stems_lacks', _libFilters.stemsLacks.join(','));
     if (_libFilters.lyrics !== null) params.set('has_lyrics', String(_libFilters.lyrics));
     if (_libFilters.tunings.length) params.set('tunings', _libFilters.tunings.join(','));
+    // Which instrument's tuning the `tunings` filter + the tuning sort read.
+    if (_libraryInstrument() !== 'guitar-lead') params.set('instrument', _libraryInstrument());
     return params;
 }
 
@@ -851,6 +898,7 @@ async function _renderTuningList() {
         c.innerHTML = '<div class="text-xs text-gray-500 px-2">Loading...</div>';
         try {
             const params = _applyLibraryProviderToParams(new URLSearchParams());
+            params.set('instrument', _libraryInstrument());
             const resp = await fetch(`/api/library/tuning-names?${params}`);
             if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
             const data = await resp.json();
@@ -869,6 +917,11 @@ async function _renderTuningList() {
             fetchError = e.message || 'request failed';
         }
     }
+    // NAME the perspective: silent instrument-following is the original bug in
+    // a new place — the user must be able to see which instrument these
+    // tunings describe.
+    const labelEl = document.getElementById('filter-tunings-label');
+    if (labelEl) labelEl.textContent = `Tuning (${_libraryInstrumentLabel()})`;
     c.innerHTML = '';
     if (fetchError) {
         c.innerHTML = `<div class="text-xs text-red-400 px-2">Failed to load tunings (${esc(fetchError)}). Reopen the drawer to retry.</div>`;
@@ -894,10 +947,17 @@ async function _renderTuningList() {
         const checked = _libFilters.tunings.includes(val);
         const row = document.createElement('label');
         row.className = 'tuning-row';
+        // Be honest about the fallback: songs with no bass arrangement borrow
+        // the guitar chart's tuning, and that must be visible rather than
+        // presented as a measured bass tuning.
+        const inferred = t.inferred_count || 0;
+        if (inferred) {
+            row.title = `${inferred} of ${t.count} inferred from the guitar chart (no bass arrangement)`;
+        }
         row.innerHTML =
             `<input type="checkbox" ${checked ? 'checked' : ''} class="rounded border-gray-600 bg-dark-700 text-accent">` +
             `<span class="flex-1">${esc(label)}</span>` +
-            `<span class="tuning-count">${t.count}</span>`;
+            `<span class="tuning-count">${t.count}${inferred ? ` (${inferred}~)` : ''}</span>`;
         const cb = row.querySelector('input');
         cb.onchange = () => {
             const i = _libFilters.tunings.indexOf(val);
@@ -1244,6 +1304,10 @@ export function renderGridCards(songs, containerId = 'lib-grid', mode = 'replace
         const duration = song.duration ? formatTime(song.duration) : '';
         const tuningRaw = song.tuning || song.tuning_name || '';
         const tuning = displayTuningName(tuningRaw);
+        // The BADGE follows the player's instrument; `tuning` above stays the
+        // song's guitar-derived tuning because the retune action below rewrites
+        // the chart to E Standard and must not key on the bass part.
+        const tuningBadge = displayTuningName(_rowTuningRaw(song));
         const artUrl = _librarySongArtUrl(song, providerId);
         const isLocalProvider = _isLocalLibraryProvider(providerId);
         const isSloppak = song.format === 'sloppak';
@@ -1299,7 +1363,7 @@ export function renderGridCards(songs, containerId = 'lib-grid', mode = 'replace
                 </div>
                 <div class="flex items-center flex-wrap gap-1.5 mt-3 text-xs">
                     ${(() => { const _nm = _getArrangementNamingMode(); return (song.arrangements || []).map(a => _arrangementBadgeHtml(a, _nm)).join(''); })()}
-                    ${tuning ? `<span class="px-1.5 py-0.5 rounded ${tuning === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuning)}</span>` : ''}
+                    ${tuningBadge ? `<span class="px-1.5 py-0.5 rounded ${tuningBadge === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuningBadge)}</span>` : ''}
                     ${song.has_lyrics ? `<span class="px-1.5 py-0.5 bg-purple-900/30 rounded text-purple-300">Lyrics</span>` : ''}
                     ${song.user_difficulty != null ? `<span class="px-1.5 py-0.5 bg-blue-900/30 rounded text-blue-300" title="Your difficulty rating">◆${esc(song.user_difficulty)}</span>` : ''}
                     ${duration ? `<span class="text-gray-600">${duration}</span>` : ''}
@@ -1470,6 +1534,9 @@ export async function renderTreeInto(containerId, countId, stats, letter, q, fav
                 const duration = song.duration ? formatTime(song.duration) : '';
                 const tuningRaw = song.tuning || song.tuning_name || '';
                 const tuning = displayTuningName(tuningRaw);
+                // Badge follows the player's instrument; the retune action below
+                // keeps operating on the song's guitar-derived tuning.
+                const tuningBadge = displayTuningName(_rowTuningRaw(song));
                 const isLocalProvider = _isLocalLibraryProvider(providerId);
                 const isSloppak = song.format === 'sloppak';
                 const stdRetune = isLocalProvider && localFilename && !isSloppak && tuningRaw && !song.has_estd &&
@@ -1496,8 +1563,8 @@ export async function renderTreeInto(containerId, countId, stats, letter, q, fav
                 { const _nm = _getArrangementNamingMode();
                   for (const arrangement of (song.arrangements || []))
                       html += _arrangementBadgeHtml(arrangement, _nm); }
-                if (tuning)
-                    html += `<span class="px-1.5 py-0.5 rounded ${tuning === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuning)}</span>`;
+                if (tuningBadge)
+                    html += `<span class="px-1.5 py-0.5 rounded ${tuningBadge === 'E Standard' ? 'bg-green-900/30 text-green-400' : 'bg-yellow-900/30 text-yellow-400'}">${esc(tuningBadge)}</span>`;
                 if (song.has_lyrics)
                     html += `<span class="px-1.5 py-0.5 bg-purple-900/30 rounded text-purple-300">Lyrics</span>`;
                 if (song.user_difficulty != null)

static/js/session.js

@@ -638,9 +638,18 @@ export let artAbortController = null;
 export async function playSong(filename, arrangement, options) {
     console.log('playSong called:', filename);
     // A manual (non-queue) play abandons any active play-queue, so a stale queue
-    // can't hijack the next song's end. The queue passes fromQueue to keep itself.
-    if ((!options || !options.fromQueue) && window.feedBack && window.feedBack.playQueue) {
-        window.feedBack.playQueue.clear();
+    // can't hijack the next song's end. The queue signals a play it is DRIVING
+    // two ways: options.fromQueue (in-band) and _consumeInternalPlay() (out-of-
+    // band). The out-of-band one exists because plugin playSong wrappers forward
+    // only (filename, arrangement) and drop the options object — with just the
+    // in-band flag, the queue cleared itself the instant its first song played
+    // and a gig never advanced. Consume the flag whether or not we go on to clear,
+    // so it can't leak into a later manual play.
+    const _pq = window.feedBack && window.feedBack.playQueue;
+    const _queueDriven = (options && options.fromQueue)
+        || (_pq && typeof _pq._consumeInternalPlay === 'function' && _pq._consumeInternalPlay());
+    if (!_queueDriven && _pq) {
+        _pq.clear();
     }
     if (!options || options.bridge !== false) {
         _recordPlaybackBridge('playback.window-play-song', 'window.playSong', 'legacy playSong entry point used');

static/js/settings-io.js

@@ -1,6 +1,6 @@
 // Settings backup — the export / import bundle.
 //
-// Carved verbatim out of static/app.js (R3a). A LEAF module: imports nothing.
+// Carved verbatim out of static/app.js (R3a). Imports only the blob-io leaf.
 //
 // Two entry points, both inline handlers on the Settings screen, so app.js keeps
 // re-exposing them on window. The import is two-phase (server first, atomic; then
@@ -29,6 +29,8 @@
 // phase 2; the localStorage side is best-effort merge after server
 // success. Failures are reported, never silenced.
 
+import { downloadBlob } from './blob-io.js';
+
 export async function exportSettings() {
     const status = document.getElementById('backup-status');
     status.textContent = 'Exporting...';
@@ -66,14 +68,7 @@ export async function exportSettings() {
             if (match) filename = match[1];
         }
         const blob = new Blob([JSON.stringify(bundle, null, 2)], { type: 'application/json' });
-        const url = URL.createObjectURL(blob);
-        const a = document.createElement('a');
-        a.href = url;
-        a.download = filename;
-        document.body.appendChild(a);
-        a.click();
-        document.body.removeChild(a);
-        URL.revokeObjectURL(url);
+        downloadBlob(blob, filename);
         status.textContent = `Exported ${filename}`;
     } catch (e) {
         status.textContent = `Export failed: ${e.message}`;

static/js/settings.js

@@ -18,7 +18,7 @@
 // back-import would close a cycle. player-controls keeps reading it through the host seam, and
 // app.js — the root, which imports both — wires it. That is exactly what the seam is for.
 import { hwcInitSettingsUI } from './highway-colors.js';
-import { _getArrangementNamingMode } from './library.js';
+import { _getArrangementNamingMode, _setLibraryProfile } from './library.js';
 import {
     _applyMastery, _autoplayExitEnabled, _exitConfirmEnabled, _showUpNextEnabled,
 } from './player-controls.js';
@@ -111,6 +111,10 @@ export async function loadSettings() {
     if (dlcEl) dlcEl.value = data.dlc_dir || '';
     _defaultArrangement = data.default_arrangement || '';
     _syncDefaultArrangementSelect(_defaultArrangement);
+    // Feed the library its tuning PERSPECTIVE (lead / rhythm / bass) — the
+    // tuning facet, filter, sort and badges all answer for the profile the
+    // player actually plays.
+    _setLibraryProfile(data.active_instrument_profile);
     const pathwayEl = document.getElementById('setting-instrument-pathway');
     if (pathwayEl) pathwayEl.value = _normalizeInstrumentPathway(data.pathway);
     const demucsEl = document.getElementById('demucs-server-url');

static/v3/dashboard.js

@@ -208,12 +208,17 @@
             '</div></div></div>' +
             continueCard +
             '</div>' +
-            // Stats row
+            // Stats row. The third slot belongs to the career plugin (it
+            // replaces the slot's content on v3:dashboard-rendered); the
+            // plugin-count stat is the built-in fallback when career is
+            // absent or has no state yet.
             '<div class="grid md:grid-cols-3 gap-6 mt-6">' +
             audioRoutingCard() +
             statCard(String(songCount), 'songs', 'text-fb-gold') +
+            '<div id="v3-dash-career-slot" class="grid">' +
             statCard(String(pluginCount), 'active', 'text-fb-good') +
             '</div>' +
+            '</div>' +
             recentSection +
             '</div>';
 

static/v3/index.html

@@ -326,7 +326,7 @@
                 <section>
                     <details>
                         <summary class="cursor-pointer flex items-center justify-between text-xs font-semibold uppercase tracking-wider text-gray-500 mb-2">
-                            <span>Tuning</span>
+                            <span id="filter-tunings-label">Tuning</span>
                             <span id="filter-tunings-summary" class="text-gray-600 normal-case font-normal text-xs">All tunings</span>
                         </summary>
                         <div id="filter-tunings" class="mt-3 space-y-1 max-h-64 overflow-y-auto pr-1"></div>

static/v3/profile.js

@@ -191,6 +191,10 @@
             '<div class="space-y-6">' +
             headerCard +
             bestsCard +
+            // Passport wall — rendered by the career plugin on
+            // v3:profile-rendered (absent-not-empty: nothing shows until a
+            // passport exists).
+            '<div id="v3-profile-passports-mount"></div>' +
             // Feats of Power trophy shelf — rendered by the achievements plugin
             // (earned Feats only; hidden-until-earned, so empty when none).
             '<div id="v3-profile-feats-slot"></div>' +

static/v3/songs.js

@@ -62,7 +62,7 @@
         artist: '', album: '',
         grouping: true,     // one card per song (multi-chart grouping); persisted
 
-        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] },
+        filters: { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' },
         page: 0, total: 0, loading: false, built: false, accuracy: {}, tuningNames: [], genres: [],
         artistCatalog: [], renderedHash: '',
         scrollBound: false,
@@ -120,7 +120,7 @@
     function activeFilterCount() {
         const f = state.filters;
         return f.arr_has.length + f.arr_lacks.length + f.stem_has.length + f.stem_lacks.length +
-            (f.lyrics ? 1 : 0) + f.tunings.length + (f.mastery ? f.mastery.length : 0) +
+            (f.lyrics ? 1 : 0) + (f.tuningMatch === 'playable' ? 1 : f.tunings.length) + (f.mastery ? f.mastery.length : 0) +
             (f.match ? f.match.length : 0) + (f.genre ? f.genre.length : 0) +
             (state.artist ? 1 : 0) + (state.album ? 1 : 0);
     }
@@ -280,7 +280,15 @@
         if (f.stem_has.length) p.set('stems_has', f.stem_has.join(','));
         if (f.stem_lacks.length) p.set('stems_lacks', f.stem_lacks.join(','));
         if (f.lyrics) p.set('has_lyrics', f.lyrics);
-        if (f.tunings.length) p.set('tunings', f.tunings.join(','));
+        // The two modes answer different questions, so only one filters at a
+        // time: sending both would silently intersect them.
+        if (f.tunings.length && f.tuningMatch !== 'playable') p.set('tunings', f.tunings.join(','));
+        // Which perspective the `tunings` filter + the tuning sort read.
+        if (libInstrument() !== 'guitar-lead') p.set('instrument', libInstrument());
+        // "Playable without retuning": send the player's LIVE tuning and let the
+        // server do the pitch maths (the pitch tables live in lib/tunings.py —
+        // duplicating them here is how the two drift apart).
+        applyPlayableParams(p, f);
         if (f.mastery && f.mastery.length) p.set('mastery', f.mastery.join(','));
         if (f.match && f.match.length) p.set('match', f.match.join(','));
         if (f.genre && f.genre.length) p.set('genre', f.genre.join(','));
@@ -786,6 +794,10 @@
     // so without them the chips render exactly as before. Decoration runs AFTER the
     // (sync) window paint so scrolling stays snappy; a token cancels a superseded pass.
     let _tuningDecorToken = 0;
+    // The instrument the current grid was queried/painted for, so a
+    // working-tuning change can tell a guitar<->bass SWITCH (re-query) from a
+    // retune within the same instrument (re-colour only).
+    let _lastRenderInstrument = null;
     function _applyChipMatch(chip, stateName) {
         chip.classList.remove('bg-fb-mid', 'bg-emerald-500', 'bg-amber-400');
         chip.classList.add(stateName === 'match' ? 'bg-emerald-500'
@@ -825,22 +837,31 @@
         const shown = song.display_chart ? Object.assign({}, song, song.display_chart) : song;
         // In select mode the checkbox occupies top-2 left-2, so shift the
         // tuning chip right (left-9) to avoid overlapping it.
+        // Bass players see the bass chart's tuning (guitar fallback) — the card
+        // must agree with the facet/filter or the grid contradicts the pills.
+        const shownTuning = shownTuningName(shown);
         const tuningLabel = (typeof window.displayTuningName === 'function')
-            ? window.displayTuningName(shown.tuning_name || shown.tuning)
-            : (shown.tuning_name || '');
+            ? window.displayTuningName(shownTuning)
+            : (shownTuning || '');
         let tuning = '';
         if (tuningLabel) {
             const rawOffsets = (typeof window.parseRawTuningOffsets === 'function')
-                ? (window.parseRawTuningOffsets(shown.tuning_offsets)
-                    || window.parseRawTuningOffsets(shown.tuning_name || shown.tuning))
+                ? (window.parseRawTuningOffsets(shownTuningOffsets(shown))
+                    || window.parseRawTuningOffsets(shownTuning))
                 : null;
             const targetNotes = (tuningLabel === 'Custom Tuning' && rawOffsets
                 && typeof window.displayTuningTargets === 'function')
                 ? window.displayTuningTargets(rawOffsets, { tuningName: tuningLabel })
                 : '';
-            const badgeTitle = targetNotes
+            // Mark a tuning we INFERRED from the guitar chart (this song has no
+            // bass arrangement) so a bass player isn't shown a borrowed tuning
+            // as if it were their part's. `~` keeps the chip compact; the title
+            // spells it out.
+            const inferred = shown.tuning_inferred === true;
+            const badgeTitle = (targetNotes
                 ? ('Custom Tuning: ' + targetNotes)
-                : tuningLabel;
+                : tuningLabel)
+                + (inferred ? ' — from the guitar chart (no bass arrangement)' : '');
             const pos = 'absolute top-2 ' + (state.selectMode ? 'left-9' : 'left-2');
             // Tag the chip with its offsets so decorateTuningChips() can colour it
             // green (matches your current tuning) / amber (needs a retune) after paint.
@@ -848,8 +869,14 @@
             // scores its bass tuning against the bass base pitches, not guitar — otherwise
             // a 4-string bass tuning read as guitar can false-match a guitar player.
             const chipArrs = shown.arrangements || [];
-            const chipIsBass = chipArrs.length > 0
-                && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || ''));
+            // Bass either because the chip is SHOWING the bass chart's tuning
+            // (a bass player on a song that has one), or because every
+            // arrangement is a bass part. Checked via libInstrument() rather
+            // than comparing the two names — they are EQUAL for most songs, so
+            // a value comparison would flag a guitarist's chip as bass.
+            const chipIsBass = (libInstrument() === 'bass' && !!shown.bass_tuning_name)
+                || (chipArrs.length > 0
+                    && chipArrs.every((a) => /\bbass\b/i.test((a && a.name) || '')));
             const matchAttr = (rawOffsets && rawOffsets.length)
                 ? ' data-tuning-chip data-tuning-offsets="' + esc(rawOffsets.join(',')) + '"'
                     + (chipIsBass ? ' data-tuning-bass="1"' : '') : '';
@@ -857,7 +884,7 @@
                 tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.5625rem] font-bold px-1.5 py-0.5 rounded-sm leading-tight max-w-[5.5rem] text-center"' + matchAttr + ' title="' + esc(badgeTitle) + '">'
                     + esc('Custom Tuning') + '<br><span class="font-semibold tracking-wide">' + esc(targetNotes) + '</span></span>';
             } else {
-                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + '</span>';
+                tuning = '<span class="' + pos + ' bg-fb-mid text-black text-[0.625rem] font-bold px-1.5 py-0.5 rounded-sm"' + matchAttr + ' title="' + esc(badgeTitle) + '">' + esc(tuningLabel) + (inferred ? '<span class="opacity-60"> ~</span>' : '') + '</span>';
             }
         }
         // Display-only (pointer-events-none) so a click falls through to the
@@ -2489,6 +2516,89 @@
 
     function _artistHostEl() { return document.getElementById('v3-songs-artistpage'); }
 
+    // ── Instrument-aware tuning (the bass-player tuning-filter report) ────────
+    // A song's bass chart is often in a different tuning from its guitar chart,
+    // so the tuning facet/filter/sort and the card chip must speak for the
+    // instrument the player actually plays. The host's working-tuning
+    // capability already holds the live selection (seeded from /api/settings on
+    // boot, updated when the player switches) — read it rather than adding
+    // another settings fetch. `state.settingsInstrument` is the fallback for
+    // hosts where the capability isn't mounted.
+    // Three perspectives, matching `active_instrument_profile`: lead and rhythm
+    // guitar charts can be tuned differently too, so a rhythm player hits the
+    // same bug a bassist did. The PROFILE is the only three-valued source (the
+    // working-tuning capability knows guitar-vs-bass but not lead-vs-rhythm),
+    // so it wins; the capability is the live fallback for hosts where the
+    // profile hasn't loaded.
+    const PERSPECTIVES = ['guitar-lead', 'guitar-rhythm', 'bass'];
+    function libInstrument() {
+        if (PERSPECTIVES.indexOf(state.settingsProfile) >= 0) return state.settingsProfile;
+        try {
+            const wt = window.feedBack && window.feedBack.workingTuning;
+            if (wt && typeof wt.get === 'function') {
+                const cur = wt.get();
+                if (cur && cur.instrument === 'bass') return 'bass';
+            }
+        } catch (_) { /* capability absent/erroring — fall through to settings */ }
+        return state.settingsInstrument === 'bass' ? 'bass' : 'guitar-lead';
+    }
+
+    // "Playable without retuning" mode reads the player's CURRENT tuning from
+    // the working-tuning capability (the live session state the tuner writes),
+    // not a separate setting. No capability => we cannot know the current
+    // tuning, so the mode is unavailable rather than guessed.
+    function currentWorkingTuning() {
+        try {
+            const wt = window.feedBack && window.feedBack.workingTuning;
+            if (!wt || typeof wt.get !== 'function') return null;
+            const cur = wt.get();
+            if (!cur || !Array.isArray(cur.offsets) || !cur.offsets.length) return null;
+            return cur;
+        } catch (_) { return null; }
+    }
+
+    function playableAvailable() { return !!currentWorkingTuning(); }
+
+    function applyPlayableParams(p, f) {
+        if (f.tuningMatch !== 'playable') return;
+        const cur = currentWorkingTuning();
+        if (!cur) return;
+        p.set('tuning_match', 'playable');
+        p.set('playable_offsets', cur.offsets.join(','));
+        p.set('playable_instrument', cur.instrument === 'bass' ? 'bass' : 'guitar');
+        p.set('playable_string_count', String(cur.stringCount || cur.offsets.length));
+    }
+
+    // Short human label for the perspective, for the facet/sort headers.
+    function libInstrumentLabel() {
+        const p = libInstrument();
+        return p === 'bass' ? 'bass' : p === 'guitar-rhythm' ? 'rhythm' : 'lead';
+    }
+
+    // The column a row's tuning lives in for the active perspective.
+    function perspectiveTuningField() {
+        const p = libInstrument();
+        return p === 'bass' ? 'bass_tuning_name'
+            : p === 'guitar-rhythm' ? 'rhythm_tuning_name' : '';
+    }
+
+    // The tuning a card should SHOW: bass players see the bass chart's tuning,
+    // falling back to the song (guitar-derived) tuning when the song has no
+    // bass arrangement — the common case, so the fallback is not an edge path.
+    function shownTuningName(song) {
+        const f = perspectiveTuningField();
+        if (f && song[f]) return song[f];
+        return song.tuning_name || song.tuning;
+    }
+
+    function shownTuningOffsets(song) {
+        const f = perspectiveTuningField();
+        if (f && song[f]) {
+            return song[f.replace('_name', '_offsets')] || song.tuning_offsets;
+        }
+        return song.tuning_offsets;
+    }
+
     // Sync the two Settings gates into module state (fire-and-forget — the
     // cached flags gate entry-point rendering; openArtistPage re-checks).
     function refreshArtistPageGates() {
@@ -2496,6 +2606,10 @@
             if (!cfg) return;
             state.artistPagesEnabled = cfg.artist_pages_enabled !== false;
             state.artistLinksEnabled = cfg.artist_external_links === true;
+            // Fallback instrument for hosts without the working-tuning capability.
+            state.settingsInstrument = cfg.instrument === 'bass' ? 'bass' : 'guitar';
+            // The three-valued perspective source (lead / rhythm / bass).
+            state.settingsProfile = cfg.active_instrument_profile || '';
         });
     }
 
@@ -2809,12 +2923,13 @@
         else if (s === 'has') lacksArr.push(value);
         // 'lacks' → cycles back to any (already removed)
     }
-    function triPill(group, value, label, st) {
+    function triPill(group, value, label, st, title) {
         const cls = st === 'has' ? 'bg-fb-good/30 text-fb-good border-fb-good/40'
             : st === 'lacks' ? 'bg-fb-low/30 text-fb-low border-fb-low/40'
                 : 'bg-gray-800/50 text-fb-textDim border-gray-700';
         const mark = st === 'has' ? '✓ ' : st === 'lacks' ? '✕ ' : '';
-        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '">' + mark + esc(label) + '</button>';
+        const tip = title ? ' title="' + esc(title) + '"' : '';
+        return '<button data-tri="' + group + '" data-val="' + esc(value) + '" class="px-2 py-1 rounded-md text-xs border ' + cls + '"' + tip + '>' + mark + esc(label) + '</button>';
     }
     function renderDrawer() {
         const d = document.getElementById('v3-songs-drawer');
@@ -2834,7 +2949,32 @@
             section('Match', [['review', 'To review'], ['matched', 'Matched'], ['unmatched', 'Unmatched'], ['pending', 'Not scanned']].map((it) => '<button data-match="' + it[0] + '" class="px-2 py-1 rounded-md text-xs border ' + (f.match.includes(it[0]) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + it[1] + '</button>').join('')) +
             // Genre facet — dynamic list from /api/library/genres (primary genre).
             (state.genres && state.genres.length ? section('Genre', state.genres.map((g) => '<button data-genre="' + esc(g) + '" class="px-2 py-1 rounded-md text-xs border ' + (f.genre.includes(g) ? 'bg-fb-primary text-white border-fb-primary' : 'bg-gray-800/50 text-fb-textDim border-gray-700') + '">' + esc(g) + '</button>').join('')) : '') +
-            section('Tuning', (state.tuningNames || []).map((t) => {
+            // The facet header NAMES the perspective. Silent instrument-following
+            // is the original bug in a new place: the user must be able to tell
+            // which instrument these tunings describe.
+            section('Tuning (' + libInstrumentLabel() + ')',
+                // MODE toggle. Exact match answers "which tuning is this
+                // labelled"; Playable answers "will this cost me a retune" —
+                // which is what a player actually wants. Both are offered;
+                // exact stays the default so nothing changes unasked.
+                '<div class="flex gap-1 mb-2">'
+                + [['exact', 'Exact tuning'], ['playable', 'Playable without retuning']].map((m) => {
+                    const on = (f.tuningMatch || 'exact') === m[0];
+                    const dis = m[0] === 'playable' && !playableAvailable();
+                    return '<button data-tuning-match="' + m[0] + '"'
+                        + (dis ? ' disabled' : '')
+                        + (dis ? ' title="Needs your current tuning — open the tuner first"' : '')
+                        + ' class="px-2 py-1 rounded-md text-xs border '
+                        + (on ? 'bg-fb-primary text-white border-fb-primary'
+                            : 'bg-gray-800/50 text-fb-textDim border-gray-700')
+                        + (dis ? ' opacity-40 cursor-not-allowed' : '') + '">'
+                        + esc(m[1]) + '</button>';
+                }).join('')
+                + '</div>'
+                + (f.tuningMatch === 'playable'
+                    ? '<div class="text-xs text-fb-textDim mb-2">Charts you can play in your current tuning, no retune. Songs whose lowest string sits below yours are excluded.</div>'
+                    : '')
+                + ((state.tuningNames || []).map((t) => {
                 // Filter on the server's grouping key (raw offsets for customs)
                 // so two "Custom Tuning" entries are distinct; show their target
                 // notes in the label so they're distinguishable.
@@ -2847,8 +2987,17 @@
                     const notes = offs ? window.displayTuningTargets(offs, { tuningName: t.name }) : '';
                     if (notes) label = 'Custom · ' + notes;
                 }
-                return triPill('tuning', val, label + ' (' + t.count + ')', f.tunings.includes(val) ? 'has' : 'any');
-            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>') +
+                // Be honest about the fallback: when some of a row's songs have
+                // no bass chart and are borrowing the guitar tuning, say so
+                // rather than presenting a borrowed tuning as a measured one.
+                const inf = t.inferred_count || 0;
+                const title = inf
+                    ? inf + ' of ' + t.count + ' inferred from the guitar chart (no bass arrangement)'
+                    : '';
+                const countLabel = inf ? t.count + ', ' + inf + ' inferred' : String(t.count);
+                return triPill('tuning', val, label + ' (' + countLabel + ')',
+                    f.tunings.includes(val) ? 'has' : 'any', title);
+            }).join('') || '<span class="text-xs text-fb-textDim">No tunings</span>')) +
             // Multi-chart grouping toggle (P5e) — a VIEW mode, not a filter
             // (never counted in the badge, never saved into collection rules).
             // Local provider only: it's the one that implements group=.
@@ -2878,6 +3027,11 @@
             else if (g === 'tuning') { const i = f.tunings.indexOf(v); if (i >= 0) f.tunings.splice(i, 1); else f.tunings.push(v); }
             renderDrawer();
         }));
+        d.querySelectorAll('[data-tuning-match]').forEach((b) => b.addEventListener('click', () => {
+            if (b.disabled) return;
+            f.tuningMatch = b.getAttribute('data-tuning-match');
+            renderDrawer();
+        }));
         d.querySelectorAll('[data-lyrics]').forEach((b) => b.addEventListener('click', () => { f.lyrics = b.getAttribute('data-lyrics'); renderDrawer(); }));
         d.querySelectorAll('[data-mastery]').forEach((b) => b.addEventListener('click', () => { const v = b.getAttribute('data-mastery'); const i = f.mastery.indexOf(v); if (i >= 0) f.mastery.splice(i, 1); else f.mastery.push(v); renderDrawer(); }));
         d.querySelector('[data-grouping]')?.addEventListener('click', () => {
@@ -2891,7 +3045,7 @@
         d.querySelector('[data-drawer-tidy]')?.addEventListener('click', openArtistTidyUp);
         d.querySelector('[data-drawer-close]')?.addEventListener('click', closeDrawer);
         d.querySelector('[data-drawer-clear]')?.addEventListener('click', async () => {
-            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [] };
+            state.filters = { arr_has: [], arr_lacks: [], stem_has: [], stem_lacks: [], lyrics: '', tunings: [], mastery: [], match: [], genre: [], tuningMatch: 'exact' };
             state.artist = '';
             state.album = '';
             renderDrawer();
@@ -3478,13 +3632,15 @@
         const providers = await loadProviders();
         const [, tn] = await Promise.all([
             (async () => { state.accuracy = (await jget('/api/stats/best')) || {}; })(),
-            jget('/api/library/tuning-names?provider=' + enc(state.provider)),
+            jget('/api/library/tuning-names?provider=' + enc(state.provider)
+                + '&instrument=' + enc(libInstrument())),
             loadArtistCatalog(),
             // Artist-page gates (PR-B) ride the initial fetch batch so the
             // first card paint already knows whether artist lines are links.
             refreshArtistPageGates(),
         ]);
         state.tuningNames = (tn && tn.tunings) || [];
+        _lastRenderInstrument = libInstrument();
         try { const _g = await jget('/api/library/genres?provider=' + enc(state.provider)); state.genres = (_g && _g.genres) || []; } catch (e) { state.genres = []; }
 
         const opt = (arr, sel) => arr.map(([v, l]) => '<option value="' + esc(v) + '"' + (v === sel ? ' selected' : '') + '>' + esc(l) + '</option>').join('');
@@ -3512,7 +3668,13 @@
             '<select id="v3-songs-artist" class="' + ctrl + ' max-w-[11rem]" aria-label="Artist">' + artistSelectHtml() + '</select>' +
             '<select id="v3-songs-album" class="' + ctrl + ' max-w-[11rem]" aria-label="Album"' + (state.artist ? '' : ' disabled') + '>' + albumSelectHtml() + '</select>' +
             '<div class="flex rounded-md overflow-hidden border border-gray-700"><button id="v3-songs-grid-btn" class="px-3 py-2 text-sm">▦</button><button id="v3-songs-tree-btn" class="px-3 py-2 text-sm">≣</button><button id="v3-songs-albums-btn" title="Albums" class="px-3 py-2 text-sm">💿</button><button id="v3-songs-folder-btn" class="px-3 py-2 text-sm" style="display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:2.25rem"><svg fill="currentColor" viewBox="0 0 16 16" style="width:12px;height:12px;flex-shrink:0"><path d="M1 3.5A1.5 1.5 0 012.5 2h3.086a1.5 1.5 0 011.06.44l.915.914H13.5A1.5 1.5 0 0115 4.914V12.5a1.5 1.5 0 01-1.5 1.5h-11A1.5 1.5 0 011 12.5v-9z"/></svg></button></div>' +
-            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(SORTS, state.sort) + '</select>' +
+            // Name the perspective on the SORT too, not just the filter: tuning
+            // sort orders by musical distance from standard, and for a bass
+            // player that distance is measured on the bass tuning. Unlabelled,
+            // the grid silently reorders with no visible cause.
+            '<select id="v3-songs-sort" class="' + ctrl + '">' + opt(
+                SORTS.map(([v, l]) => [v, v === 'tuning' ? l + ' (' + libInstrumentLabel() + ')' : l]),
+                state.sort) + '</select>' +
             '<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>' +
@@ -4130,6 +4292,23 @@
         // visible tuning chips against the new tuning. Cheap: re-decorates in place,
         // no re-fetch or re-paint. No-op off the Songs grid or without the capability.
         sm.on('working-tuning-changed', () => {
+            // A guitar<->bass SWITCH changes which tuning the facet, the filter,
+            // the sort and the card chip speak for, so the grid must re-query —
+            // re-colouring chips would leave the guitar tuning on screen and a
+            // guitar-keyed filter applied. A retune within one instrument still
+            // takes the cheap in-place path below.
+            const inst = libInstrument();
+            if (inst !== _lastRenderInstrument) {
+                _lastRenderInstrument = inst;
+                // A tuning selection keyed to the old instrument means nothing
+                // for the new one; clearing avoids an empty grid the user can't
+                // explain (the pills are re-rendered from the new facet).
+                state.filters.tunings = [];
+                const active = document.querySelector('.screen.active');
+                if (active && active.id === 'v3-songs') reload();
+                else _libraryDirty = true;
+                return;
+            }
             if (typeof songsActive === 'function' && !songsActive()) return;
             if (state.view !== 'grid') return;
             decorateTuningChips(_gridEl());

static/v3/venue-crowd.js

@@ -133,6 +133,11 @@
     let _lastStingerAt = -Infinity;
     let _prevStreak = 0;
     let _lastAccuracyPct = null; // from perf events; stats:recorded carries none
+    // Filename of the song song:loaded last reported. An arrangement switch
+    // re-emits song:loaded for the SAME file (changeArrangement reloads through
+    // the normal load path), and that must not be mistaken for arriving at the
+    // venue with a new song — see onSongLoaded.
+    let _lastSongFile = '';
     let _bound = false;
 
     function now() { return Date.now(); }
@@ -478,10 +483,40 @@
         }
     }
 
-    function onSongLoaded() {
+    // song:loaded for the SAME file is an arrangement switch, not an arrival at
+    // the venue. changeArrangement() reloads through the normal load path, so
+    // the event is indistinguishable from a fresh load except by filename.
+    function isArrangementSwitch(prevFile, nextFile) {
+        return !!nextFile && nextFile === prevFile;
+    }
+
+    function onSongLoaded(song) {
+        const file = String((song && song.filename) || '');
+        const sameSong = isArrangementSwitch(_lastSongFile, file);
+        _lastSongFile = file;
+
         machine.reset();
         _prevStreak = 0;
         _lastAccuracyPct = null;
+
+        // Switching arrangement is NOT arriving at the venue.
+        //
+        // changeArrangement() reloads the song through the same path as a fresh
+        // load, so highway.js emits song:loaded again — same filename, new
+        // arrangement. Treated as a new song, that replayed the arrival flyover:
+        // the camera flew in from the back of the room again mid-set, every time
+        // the player switched from lead to rhythm. The player is already on
+        // stage; the room should just carry on.
+        //
+        // So keep the video pipeline running and only re-sync the mood: the
+        // performance restarts, so the loop must follow the reset machine (a
+        // quiet crossfade), never the intro.
+        if (sameSong) {
+            if (_venueActive && _manifest && !_introActive) showLoop(machine.current, FADE_MS);
+            return;
+        }
+
+        // A genuinely different song — full teardown.
         // Abort any stinger/pending state from the previous song: its ended
         // handler must not fade back into the old song's layers.
         cancelFade();
@@ -494,7 +529,27 @@
         _loadingLoop = null;
         _fadingLoop = null;
         if (_venueActive && _manifest) {
-            if (!playIntro()) showLoop(machine.current, FADE_MS);
+            // The flyover is ARRIVING at the venue, and you arrive once. Songs
+            // 2..N of a set (a gig / album / playlist) are a NEW song but the
+            // SAME arrival — the camera should not fly in from the back of the
+            // room before every track (tester: "it showed the flyover intro
+            // again" on a gig's second song). Continue the room to the new song's
+            // loop; only a first-song / standalone arrival flies in.
+            if (_isSetContinuation()) showLoop(machine.current, FADE_MS);
+            else if (!playIntro()) showLoop(machine.current, FADE_MS);
+        }
+    }
+
+    // Is this song load a continuation of a play queue (a set already in
+    // progress), rather than an arrival? True for song 2..N of a gig/album/
+    // playlist. The queue owns the answer; treat any error / absent queue as
+    // "not a continuation" so a standalone play still flies in.
+    function _isSetContinuation() {
+        try {
+            const q = window.feedBack && window.feedBack.playQueue;
+            return !!(q && typeof q.isContinuation === 'function' && q.isContinuation());
+        } catch (_) {
+            return false;
         }
     }
 
@@ -651,6 +706,7 @@
         bindRuntime,
         getState,
         celebrate,
+        isArrangementSwitch,
     };
 
     if (root) root.v3VenueCrowd = api;

static/v3/venue-scene-3d.js

@@ -18,6 +18,30 @@
     let _lastMood = 'idle';
     let _bound = false;
 
+    // The venue belongs to the SONG player and nowhere else.
+    //
+    // isVenueViz() only answers "is Venue the selected visualization" — a global
+    // preference. It says nothing about what is on screen. Other surfaces borrow
+    // the same highway_3d renderer (Virtuoso runs its practice charts on it), so
+    // with Venue selected they inherited the venue backdrop: the crowd and the
+    // stage showed up behind a chromatic exercise. The viz picker is a
+    // preference for the player; it is not a licence to paint the venue over
+    // whatever else happens to be using the renderer.
+    //
+    // So gate on both: Venue selected AND the player screen is the one showing.
+    function isPlayerScreen() {
+        try {
+            const active = document.querySelector('.screen.active');
+            return !!active && active.id === 'player';
+        } catch (_) {
+            return false;
+        }
+    }
+
+    function shouldBeActive() {
+        return isVenueViz() && isPlayerScreen();
+    }
+
     function isVenueViz() {
         if (root && root.v3VenueViz && typeof root.v3VenueViz.isVenueVisualization === 'function') {
             const sel = root.v3VenueViz.getSelectedVizId
@@ -146,7 +170,8 @@
 
     function syncViz(vizId) {
         const id = String(vizId || '');
-        if (id === 'venue') {
+        // Venue selected is necessary but not sufficient — see shouldBeActive.
+        if (id === 'venue' && isPlayerScreen()) {
             activate();
         } else {
             deactivate();
@@ -192,12 +217,19 @@
                 if (_active) syncInstrumentPov();
             });
             sm.on('viz:renderer:ready', () => {
-                if (isVenueViz()) activate();
+                if (shouldBeActive()) activate();
                 else deactivate();
             });
             sm.on('viz:reverted', () => deactivate());
+            // Leaving the player tears the venue down; coming back rebuilds it.
+            // Without this the backdrop followed the renderer onto every other
+            // surface that borrows it (Virtuoso's practice highway).
+            sm.on('screen:changed', () => {
+                if (shouldBeActive()) activate();
+                else deactivate();
+            });
         }
-        if (isVenueViz()) activate();
+        if (shouldBeActive()) activate();
     }
 
     function getState() {
@@ -234,6 +266,8 @@
         activate,
         deactivate,
         syncViz,
+        isPlayerScreen,
+        shouldBeActive,
         onAssetsLoaded,
         onAssetsFailed,
         onPerformanceState,

tests/browser/plugin-globals-contract.spec.ts

@@ -0,0 +1,63 @@
+// The window globals are a THIRD-PARTY CONTRACT. Pin them.
+//
+// Out-of-tree plugins load their screen.js as a CLASSIC script and call these
+// as bare globals. Nothing in core reads most of them, so a call-graph scan,
+// ESLint's no-undef, and a grep all come back clean while the plugin breaks in
+// the field. This is the frontend twin of tests/test_plugin_context_contract.py
+// — same reasoning, same literal-list rule.
+//
+// This guard is retroactive: `esc` was an implicit global back when app.js was
+// a classic script, went module-scoped in a9fce29, and got carved into
+// js/dom.js in 14b4058. The re-export list at the bottom of app.js was rebuilt
+// without it, and the MIDI plugin's device list threw "esc is not defined" for
+// testers — reported as "MIDI Access denied", because the ReferenceError landed
+// in a try/catch meant for permission failures.
+//
+// WHY A LITERAL LIST AND NOT A DERIVED ONE. Deriving the expected set from
+// app.js would assert the code equals itself. The point is that a human has to
+// look at a diff and consciously agree to change the contract.
+
+import { test, expect } from '@playwright/test';
+
+const PLUGIN_GLOBALS = [
+  '_confirmDialog', '_getArrangementNamingMode', '_libraryLocalFilename', '_librarySongArtUrl',
+  '_librarySongId', '_onHeaderClick', '_onNamingModeChange', '_trapFocusInModal',
+  'changeArrangement', 'checkPluginUpdates', 'clearLibFilters', 'clearLoop',
+  'deleteSelectedLoop', 'esc', 'exportDiagnostics', 'exportSettings', 'filterFavorites',
+  'filterLibrary', 'fullRescanLibrary', 'goFavPage', 'handleSliderInput',
+  'hideScanBanner', 'importSettings', 'loadPlugins', 'loadSavedLoop',
+  'loadSettings', 'onSectionPracticeModeChange', 'openEditModal', 'persistSetting',
+  'pickDlcFolder', 'pinCurrentArrangementDefault', 'playSong', 'previewDiagnostics',
+  'previewEditArt', 'renderGridCards', 'renderTreeInto', 'rescanLibrary',
+  'retuneSong', 'saveCurrentLoop', 'saveSettings', 'seekBy',
+  'setAvOffsetMs', 'setFavView', 'setInstrumentPathway', 'setLibView',
+  'setLibraryProvider', 'setLoopEnd', 'setLoopStart', 'setMastery',
+  'setSpeed', 'setViz', 'showScreen', 'sortFavorites',
+  'sortLibrary', 'syncLibrarySong', 'toggleAllArtists', 'toggleAllFavoriteArtists',
+  'toggleLibFilters', 'togglePlay', 'toggleSectionPracticePopover', 'uiPrompt',
+  'updatePlugin', 'uploadSongs',
+  'filterFavTreeLetter', 'filterTreeLetter', 'goFavTreePage', 'goTreePage',
+];
+
+test('plugin-facing window globals are all callable', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('.screen.active', { timeout: 10000 });
+
+  const missing = await page.evaluate(
+    (names) => names.filter((n) => typeof (window as any)[n] !== 'function'),
+    PLUGIN_GLOBALS,
+  );
+
+  expect(missing, `window globals plugins depend on are missing or not functions: ${missing.join(', ')}`).toEqual([]);
+});
+
+// The plugin call site that actually broke: esc() interpolated into a template
+// string. A global that exists but doesn't escape is its own bug.
+test('window.esc escapes HTML metacharacters', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('.screen.active', { timeout: 10000 });
+
+  const escaped = await page.evaluate(() => (window as any).esc('<img src=x onerror=alert(1)>'));
+  expect(escaped).not.toContain('<img');
+  expect(escaped).toContain('&lt;');
+});

tests/js/career_plugin.test.js

@@ -51,6 +51,56 @@ test('bar venue pack ships with intro media in the plugin checkout', () => {
     }
 });
 
+test('arena venue pack ships with full media in the plugin checkout', () => {
+    const packDir = path.join(PLUGIN_DIR, 'venue-packs', 'arena');
+    const manifest = JSON.parse(fs.readFileSync(path.join(packDir, 'manifest.json'), 'utf8'));
+    assert.equal(manifest.venue, 'arena');
+    assert.deepEqual(manifest.loops, {
+        bored: 'bored.mp4', neutral: 'neutral.mp4',
+        engaged: 'engaged.mp4', ecstatic: 'ecstatic.mp4',
+    });
+    assert.deepEqual(manifest.stingers, { clap: 'clap.mp4', cheer: 'cheer.mp4' });
+    assert.deepEqual(manifest.sfx, { up: 'sfx-up.mp3', down: 'sfx-down.mp3' });
+    assert.equal(manifest.intro.video, 'intro.mp4');
+    assert.equal(manifest.intro.audio, 'arena-ambience.mp3');
+    for (const f of [
+        ...Object.values(manifest.loops),
+        ...Object.values(manifest.stingers),
+        manifest.intro.video,
+        manifest.intro.audio,
+        manifest.sfx.up,
+        manifest.sfx.down,
+    ]) {
+        const stat = fs.statSync(path.join(packDir, f));
+        assert.ok(stat.size > 0, `${f} must be present`);
+    }
+});
+
+test('club venue pack ships with full media in the plugin checkout', () => {
+    const packDir = path.join(PLUGIN_DIR, 'venue-packs', 'club');
+    const manifest = JSON.parse(fs.readFileSync(path.join(packDir, 'manifest.json'), 'utf8'));
+    assert.equal(manifest.venue, 'club');
+    assert.deepEqual(manifest.loops, {
+        bored: 'bored.mp4', neutral: 'neutral.mp4',
+        engaged: 'engaged.mp4', ecstatic: 'ecstatic.mp4',
+    });
+    assert.deepEqual(manifest.stingers, { clap: 'clap.mp4', cheer: 'cheer.mp4' });
+    assert.deepEqual(manifest.sfx, { up: 'sfx-up.mp3', down: 'sfx-down.mp3' });
+    assert.equal(manifest.intro.video, 'intro.mp4');
+    assert.equal(manifest.intro.audio, 'club-ambience.mp3');
+    for (const f of [
+        ...Object.values(manifest.loops),
+        ...Object.values(manifest.stingers),
+        manifest.intro.video,
+        manifest.intro.audio,
+        manifest.sfx.up,
+        manifest.sfx.down,
+    ]) {
+        const stat = fs.statSync(path.join(packDir, f));
+        assert.ok(stat.size > 0, `${f} must be present`);
+    }
+});
+
 test('shell promotes the career plugin into the sidebar', () => {
     const src = fs.readFileSync(SHELL_JS, 'utf8');
     assert.match(src, /key: 'career',\s*screen: 'plugin-career'/);
@@ -66,3 +116,30 @@ test('career screen pushes the crowd manifest with a base URL', () => {
     // Degrades without the crowd layer (PR1 not merged / older desktop).
     assert.match(src, /typeof crowd\.setManifest !== 'function'\) return/);
 });
+
+// feedBack#… (tester): "Venue doesn't load when starting song from passport.
+// Loads standard particles." crowd.setManifest(venue) is reached ONLY through
+// pushCrowdManifest, and pushCrowdManifest is called ONLY from refresh() (the
+// career tab's own reload). A gig navigates away from that tab, so refresh()
+// never runs during it — the venue viz turns on but its crowd/stage pack never
+// loads. startGig must push the manifest itself after setting the override.
+test('startGig pushes the crowd manifest for the gig venue', () => {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const src = fs.readFileSync(
+        path.join(__dirname, '..', '..', 'plugins', 'career', 'screen.js'), 'utf8');
+    const start = src.indexOf('async function startGig(');
+    assert.ok(start !== -1, 'startGig not found');
+    const open = src.indexOf('{', src.indexOf(')', start));
+    let depth = 1, i = open + 1;
+    while (i < src.length && depth > 0) { const ch = src[i]; if (ch === '{') depth++; else if (ch === '}') depth--; i++; }
+    const fn = src.slice(start, i);
+    // The override is set, then the manifest must be (re)pushed for it.
+    const overrideIdx = fn.search(/VENUE_OVERRIDE_KEY,\s*prop\.venue_id/);
+    const pushIdx = fn.search(/pushCrowdManifest\s*\(/);
+    assert.ok(overrideIdx !== -1, 'startGig must set the venue override');
+    assert.ok(pushIdx !== -1,
+        'startGig must push the crowd manifest — refresh() (its only other caller) ' +
+        'never runs during a gig, so the venue pack would never load');
+    assert.ok(overrideIdx < pushIdx, 'the manifest must be pushed AFTER the override is set to the gig venue');
+});

tests/js/gig_song_end.test.js

@@ -0,0 +1,98 @@
+// A gig is a SET, not a run of unrelated songs.
+//
+// Reported from a live gig: the player finished the first song and had to sit
+// through the per-song results popup before the next one would start, and then
+// wait again while that song was extracted from its feedpak zip.
+//
+// This file covers the CORE half — career pre-extracts the whole setlist before
+// the first note. The other half (note_detect must not show its per-song summary
+// inside a gig) lives in the note_detect plugin repo, which is not part of this
+// checkout: plugins/*/ is gitignored here and note_detect ships from
+// feedBack-plugin-notedetect. A test reading it from core would pass on a dev
+// box (where the plugin happens to be bundled) and fail in CI, which is worse
+// than no test.
+//
+// The pre-extraction is tested for REAL behaviour — actually unpacking zips — in
+// tests/plugins/career/test_routes.py. These are the wiring guards around it.
+
+'use strict';
+
+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, '..', '..');
+const CAREER = fs.readFileSync(path.join(ROOT, 'plugins', 'career', 'screen.js'), 'utf8');
+const CAREER_ROUTES = fs.readFileSync(path.join(ROOT, 'plugins', 'career', 'routes.py'), 'utf8');
+
+function extractBlock(src, signature) {
+    const start = src.indexOf(signature);
+    assert.ok(start !== -1, `signature '${signature}' not found`);
+    const openBrace = src.indexOf('{', start);
+    let depth = 1;
+    let i = openBrace + 1;
+    while (i < src.length && depth > 0) {
+        const ch = src[i];
+        if (ch === '{') depth++;
+        else if (ch === '}') depth--;
+        i++;
+    }
+    assert.ok(depth === 0, `unbalanced braces after '${signature}'`);
+    return src.slice(start, i);
+}
+
+test('startGig extracts the whole setlist before starting the queue', () => {
+    const fn = extractBlock(CAREER, 'async function startGig(');
+    const prepIdx = fn.search(/await\s+prepareGigSongs\s*\(/);
+    const startIdx = fn.search(/q\.start\s*\(/);
+    assert.ok(prepIdx !== -1, 'startGig must pre-extract the set');
+    assert.ok(startIdx !== -1, 'q.start not found');
+    assert.ok(prepIdx < startIdx,
+        'the set must be unpacked BEFORE the queue starts — otherwise the player ' +
+        'waits between songs, which is the bug');
+});
+
+test('the stage is only borrowed once the set is ready', () => {
+    const fn = extractBlock(CAREER, 'async function startGig(');
+    const prepIdx = fn.search(/await\s+prepareGigSongs\s*\(/);
+    const stageIdx = fn.search(/VENUE_OVERRIDE_KEY/);
+    assert.ok(prepIdx < stageIdx,
+        'a gig cancelled while unpacking must not leave the venue/viz overwritten');
+    assert.match(fn, /_ppGigProposal\s*!==\s*prop/,
+        'a proposal dismissed while unpacking must not then start a gig');
+});
+
+test('pre-extraction never blocks the gig from starting', () => {
+    const fn = extractBlock(CAREER, 'async function prepareGigSongs(');
+    assert.match(fn, /catch\s*\(/,
+        'a failed prepare must fall through to the old lazy extraction, not abort the gig');
+});
+
+test('the prepare route degrades instead of failing', () => {
+    assert.match(CAREER_ROUTES, /def prepare_gig/, 'prepare route missing');
+    assert.match(CAREER_ROUTES, /context\.get\(\s*["']get_dlc_dir["']\s*\)/,
+        'a host without the library resolvers must degrade, not 500 — pre-extraction ' +
+        'is an optimisation and can never be why a gig will not start');
+});
+
+// ── the prepare must never be able to BLOCK the gig (CodeRabbit, #971) ──────
+//
+// A bare `await fetch(...)` only rejects on a network error. A server that
+// accepts the connection and then never answers hangs forever — and the gig
+// would never start. That would make this optimisation the exact thing it
+// promises never to be: the reason you cannot play.
+
+test('the prepare fetch is bounded — a hung server cannot block the gig', () => {
+    const fn = extractBlock(CAREER, 'async function prepareGigSongs(');
+    assert.match(fn, /AbortController/, 'the request must be abortable');
+    assert.match(fn, /setTimeout\([\s\S]{0,40}abort\s*\(\s*\)/,
+        'a hung request must be aborted, not awaited forever');
+    assert.match(fn, /signal:\s*ctrl\.signal/, 'the signal must actually be passed to fetch');
+    assert.match(fn, /clearTimeout/, 'the timer must be cleared on the happy path');
+    assert.match(CAREER, /const\s+PREPARE_TIMEOUT_MS\s*=\s*\d+/, 'the ceiling must be named');
+    // The button must be restored however we leave — otherwise a timeout strands
+    // the poster on "Preparing set…" with Play disabled: unplayable.
+    assert.match(fn, /finally\s*\{[\s\S]{0,220}btn\.disabled\s*=\s*false/,
+        'the Play button must be re-enabled on EVERY path, including the abort');
+});

tests/js/highway_pause_throttle.test.js

@@ -77,3 +77,89 @@ test('throttle runs after the ready gate, before bundle/draw', () => {
     assert.ok(readyIdx < throttleIdx, 'throttle must come after the ready gate');
     assert.ok(throttleIdx < drawIdx, 'throttle must come before the renderer draw');
 });
+
+// ── The throttle must not starve a renderer that animates on its own clock ──
+//
+// The throttle assumes a paused chart is a still picture, so re-rendering it is
+// waste. That stopped being true when the venue landed: the 3D highway draws the
+// venue's VIDEO backdrop and its reactive crowd into the same canvas as the
+// notes, so capping paused frames capped the whole room — pausing the song
+// dropped the venue to ~10 fps ("everything around the highway drops fps").
+//
+// Renderers now opt out via an optional needsContinuousFrames(). Absent or
+// throwing must mean false, so every other renderer keeps the throttle.
+
+test('paused throttle defers to a renderer that needs continuous frames', () => {
+    const src = highwaySources();
+    const fn = extractBlock(src, 'function draw()');
+    assert.match(fn, /_rendererNeedsContinuousFrames\s*\(\s*\)/,
+        'the paused throttle must consult the renderer capability');
+    // The capability must GATE the early-return, not merely be called near it:
+    // the throttle only applies when the renderer does NOT need every frame.
+    assert.match(
+        fn,
+        /!\s*_rendererNeedsContinuousFrames\s*\(\s*\)[\s\S]{0,160}_PAUSED_FRAME_INTERVAL_MS[\s\S]{0,40}return;/,
+        'throttle must be skipped when the renderer needs continuous frames',
+    );
+});
+
+test('the capability probe fails closed (absent / non-function / throwing)', () => {
+    const src = highwaySources();
+    const fn = extractBlock(src, 'function _rendererNeedsContinuousFrames()');
+    assert.match(fn, /typeof\s+r\.needsContinuousFrames\s*!==\s*'function'[\s\S]{0,40}return false/,
+        'a renderer without the method must keep the throttle');
+    assert.match(fn, /catch[\s\S]{0,40}return false/,
+        'a throwing renderer must keep the throttle, not crash the draw loop');
+    assert.match(fn, /===\s*true/,
+        'only an explicit true opts out — a truthy accident must not disable the throttle');
+});
+
+test('3D highway claims continuous frames for BOTH sources of venue motion', () => {
+    const h3d = fs.readFileSync(
+        path.join(__dirname, '..', '..', 'plugins', 'highway_3d', 'screen.js'), 'utf8');
+    const fn = extractBlock(h3d, 'needsContinuousFrames()');
+    // (1) a crowd video rolling on its own clock (career venue pack)
+    assert.match(fn, /_venueCrowdVideos/, 'must key off the actual crowd video elements');
+    assert.match(fn, /\.paused/, 'a paused video is a still frame');
+    // (2) the venue scene's OWN fake-depth motion — backdrop breathe, haze drift,
+    // warmth pulse, shimmer. Math.sin(t) in the draw loop, so it only moves while
+    // we get frames, and it runs with NO pack at all. Missing this meant the venue
+    // still stuttered on pause / count-in / credits whenever no video was rolling.
+    assert.match(fn, /_venueEffectiveMotionMode\s*\(\s*\)\s*!==\s*'off'/,
+        'the venue scene animates without any video — it must claim frames too');
+    // ...and with no venue at all the paused scene IS static: the #654 GPU saving
+    // must survive, so the method has to be able to return false.
+    assert.match(fn, /return false;/, 'must fall through to false on a plain 3D highway');
+});
+
+// ── a SUPERSEDED init is not a FAILED init ──────────────────────────────────
+//
+// Starting a gig dropped the player onto the fallback 2D highway with no venue.
+//
+// setViz('venue') installs the 3D renderer, whose init is async; the gig then
+// immediately starts its play queue, and playSong() re-initialises that same
+// renderer a tick later. A renderer mints a fresh readyPromise per init() and
+// rejects the previous one with "superseded" — but highway.js only checked that
+// the RENDERER object was unchanged, which it is. So it treated a healthy
+// re-initialising renderer as a failed one, tore it down, and reverted to 2D:
+//
+//     renderer async init failure: Error: superseded
+//     viz picker: reverted to default renderer (async-init-failure)
+//
+// Reproduced and fixed against the real build (venue stays selected, scene
+// active, no viz:reverted).
+
+test('a superseded readyPromise must not revert the viz to 2D', () => {
+    const src = highwaySources();
+    const fn = extractBlock(src, 'function _handleAsyncInitFailure(e)');
+    assert.match(fn, /readyPromise\s*!==\s*rp[\s\S]{0,40}return/,
+        'a rejection from a STALE readyPromise (the renderer has since re-init\'d) must be ' +
+        'ignored — otherwise a re-initialising renderer is torn down as if it had failed');
+    // The renderer-identity check must survive too: a rejection belonging to a
+    // renderer that has since been REPLACED is also not our problem.
+    assert.match(fn, /hwState\._renderer\s*!==\s*_installedRenderer[\s\S]{0,20}return/,
+        'the renderer-identity guard must remain');
+    // ...and a genuine failure of the CURRENT init cycle must still revert.
+    assert.match(fn, /_emitVizReverted\s*\(\s*'async-init-failure'\s*\)/,
+        'a real async-init failure must still fall back to the default renderer');
+});

tests/js/play_queue_peek.test.js

@@ -49,3 +49,80 @@ test('peekNext is null after clear', () => {
     q.clear();
     assert.strictEqual(q.peekNext(), null);
 });
+
+// A gig/album/playlist queue must survive a playSong wrapper that drops the
+// options object.
+//
+// The queue tells playSong "don't clear the queue I'm driving" via
+// options.fromQueue. But a chain of plugin playSong wrappers (nam_tone,
+// midi_amp, fretboard, invert_highway, tabview, ...) forward only
+// (filename, arrangement) and silently drop the 3rd arg. With just the in-band
+// flag, playSong cleared the queue the instant its first song started, so a gig
+// never advanced (feedBack#… tester: "Passports does not advance in the song
+// queue"). The queue now also raises an out-of-band flag, _consumeInternalPlay(),
+// which playSong honours regardless of the wrapper chain.
+
+// The real clear-guard from session.js, driven against the queue.
+function clearGuard(win, options) {
+    const pq = win.feedBack && win.feedBack.playQueue;
+    const queueDriven = (options && options.fromQueue)
+        || (pq && typeof pq._consumeInternalPlay === 'function' && pq._consumeInternalPlay());
+    if (!queueDriven && pq) pq.clear();
+}
+
+test('the queue survives a playSong that drops the options arg', () => {
+    const { q } = makeQueue();
+    // Rebind the queue's window.playSong to a wrapper that forwards ONLY
+    // (filename, arrangement) — exactly the plugin bug — and runs the real guard.
+    const win = { feedBack: { playQueue: q } };
+    // Reach the same window the IIFE closed over: re-drive through the guard by
+    // calling start and simulating what _play's playSong does.
+    // We can't rebind the closed-over window, so instead assert the out-of-band
+    // signal directly: _play sets it, and the guard consumes it.
+    q.start(['a.sloppak', 'b.sloppak', 'c.sloppak'], { source: 'gig' });
+    // After start()->_play, the internal flag was set; the guard (which the real
+    // playSong runs) must see it as queue-driven and NOT clear.
+    win.feedBack.playQueue = q;
+    clearGuard(win, undefined /* wrapper dropped options */);
+    assert.strictEqual(q.active(), true, 'a dropped options arg must not clear the queue');
+    assert.strictEqual(q.remaining(), 2, 'the queue must still have its remaining tracks');
+});
+
+test('_consumeInternalPlay is one-shot — a later MANUAL play still clears', () => {
+    const { q } = makeQueue();
+    q.start(['a.sloppak', 'b.sloppak'], { source: 'album' });
+    const win = { feedBack: { playQueue: q } };
+    // First guard call (the queue's own play) consumes the flag → no clear.
+    clearGuard(win, undefined);
+    assert.strictEqual(q.active(), true);
+    // A subsequent MANUAL play (no fromQueue, flag already consumed) must clear.
+    clearGuard(win, undefined);
+    assert.strictEqual(q.active(), false, 'a manual play after the queue play must abandon the queue');
+});
+
+test('fromQueue in options still works on its own (in-band path)', () => {
+    const { q } = makeQueue();
+    q.start(['a.sloppak', 'b.sloppak'], { source: 'gig' });
+    // consume the internal flag first so ONLY options.fromQueue is under test
+    q._consumeInternalPlay();
+    const win = { feedBack: { playQueue: q } };
+    clearGuard(win, { fromQueue: true });
+    assert.strictEqual(q.active(), true, 'options.fromQueue alone must still keep the queue');
+});
+
+// isContinuation(): true for song 2..N of a set, false for the first song / a
+// standalone play. The venue uses it to fly in once on arrival, then carry the
+// room between songs instead of replaying the arrival flyover every track
+// (tester: "it showed the flyover intro again" on a gig's second song).
+test('isContinuation is false on the first song, true after advancing', () => {
+    const { q } = makeQueue();
+    assert.strictEqual(q.isContinuation(), false, 'idle queue is not a continuation');
+    q.start(['a.sloppak', 'b.sloppak', 'c.sloppak'], { source: 'gig' });
+    assert.strictEqual(q.isContinuation(), false, 'the FIRST song of a set is an arrival, not a continuation');
+    q.advance();
+    assert.strictEqual(q.isContinuation(), true, 'song 2 is a continuation — no re-flyover');
+    q.advance();
+    assert.strictEqual(q.isContinuation(), true, 'song 3 too');
+    q.clear();
+    assert.strictEqual(q.isContinuation(), false, 'a cleared queue is not a continuation');
+});

tests/js/v3_songs_tuning.test.js

@@ -67,11 +67,27 @@ test('v3 songs.js uses display helpers for album-art tuning badge', () => {
     const src = fs.readFileSync(SONGS_JS, 'utf8');
     // The card renderer's row variable was renamed song → shown when grouped
     // cards landed (the badge reads the representative chart); accept either.
-    assert.match(src, /displayTuningName\((?:song|shown)\.tuning_name \|\| (?:song|shown)\.tuning\)/);
+    // The raw read then moved behind shownTuningName() so the badge can answer
+    // for the active tuning perspective — accept that indirection too, and pin
+    // the fallback inside the helper below so this stays a real guard.
+    assert.match(
+        src,
+        /displayTuningName\((?:(?:song|shown)\.tuning_name \|\| (?:song|shown)\.tuning|shownTuning)\)/,
+    );
     assert.match(src, /displayTuningTargets/);
     assert.match(src, /parseRawTuningOffsets/);
 });
 
+test('the tuning-perspective helper still falls back to tuning_name || tuning', () => {
+    // shownTuningName() is what the badge now reads. With no perspective field
+    // set (guitar-lead, the default) it must resolve exactly what the badge
+    // used to read inline, or guitar players silently lose their tuning label.
+    const src = fs.readFileSync(SONGS_JS, 'utf8');
+    const body = src.match(/function shownTuningName\(song\)\s*\{[\s\S]*?\n {4}\}/);
+    assert.ok(body, 'shownTuningName() not found — the badge read moved again');
+    assert.match(body[0], /return song\.tuning_name \|\| song\.tuning;/);
+});
+
 test('raw offset tuning_name does not appear in rendered card HTML', () => {
     const html = renderSongCardBadge({ tuning_name: '-2 0 0 0 -2' }, helpers);
     assert.doesNotMatch(html, /-2 0 0 0 -2/);

tests/js/venue_scene_3d.test.js

@@ -208,7 +208,7 @@ test('index.html loads venue deps before venue-scene-3d', () => {
     assert.ok(vizIdx < moodIdx && moodIdx < sceneIdx);
 });
 
-test('syncViz activates only for venue visualization id', () => {
+test('syncViz activates only for venue visualization id, and only on the player', () => {
     global.h3dVenueSceneSetActive = (on) => { global._h3dActive = on; };
     global.h3dVenueSceneSetMood = (s) => { global._h3dMood = s; };
     global.h3dVenueSceneSetInstrumentPov = () => {};
@@ -216,7 +216,14 @@ test('syncViz activates only for venue visualization id', () => {
     global.v3VenueViz = venueViz;
     global.v3VenueInstrumentPov = pov;
     global.feedBack = { on() {} };
+    // The venue is scoped to the song player: selecting Venue is a preference
+    // for THAT screen, not a licence to paint the venue over anything else that
+    // borrows the highway_3d renderer (Virtuoso's practice charts did exactly
+    // that). syncViz therefore needs to know which screen is showing.
+    const onScreen = (id) => { global.document = { querySelector: (s) => (s === '.screen.active' && id ? { id } : null) }; };
+    const prevDoc = global.document;
     try {
+        onScreen('player');
         venueScene.deactivate();
         venueScene.syncViz('highway_3d');
         assert.equal(global._h3dActive, false);
@@ -224,7 +231,16 @@ test('syncViz activates only for venue visualization id', () => {
         assert.equal(global._h3dActive, true);
         assert.equal(venueScene.getState().active, true);
         assert.equal(venueScene.getState().themeId, 'small-club');
+
+        // ...and the same call OFF the player must not activate it.
+        venueScene.deactivate();
+        onScreen('virtuoso');
+        venueScene.syncViz('venue');
+        assert.equal(global._h3dActive, false,
+            'Venue selected must NOT paint the venue onto the Virtuoso highway');
+        assert.equal(venueScene.getState().active, false);
     } finally {
+        global.document = prevDoc;
         venueScene.deactivate();
         delete global.h3dVenueSceneSetActive;
         delete global.h3dVenueSceneSetMood;

tests/js/venue_scope.test.js

@@ -0,0 +1,138 @@
+// Two venue bugs reported from a live career session.
+//
+// 1. Changing arrangement mid-song replayed the venue arrival flyover. The
+//    camera flew in from the back of the room again, every time the player
+//    switched lead -> rhythm. changeArrangement() reloads the song through the
+//    normal load path, so highway.js re-emits `song:loaded` — same filename,
+//    new arrangement — and the venue could not tell that from a fresh arrival.
+//    The player is already on stage; the room should just carry on.
+//
+// 2. With Venue selected, the venue backdrop showed up on the VIRTUOSO highway.
+//    The venue was gated purely on the viz selection, which is a global
+//    preference and says nothing about what is on screen. Virtuoso borrows the
+//    same highway_3d renderer for its practice charts, so it inherited the
+//    crowd and the stage behind a chromatic exercise. The venue belongs to the
+//    song player and nowhere else.
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const crowd = require('../../static/v3/venue-crowd.js');
+
+// ── 1. arrangement switch is not an arrival ────────────────────────────────
+
+test('same filename = arrangement switch (no arrival flyover)', () => {
+    // changeArrangement() re-emits song:loaded for the song already on stage.
+    assert.equal(crowd.isArrangementSwitch('song.feedpak', 'song.feedpak'), true);
+});
+
+test('different filename = a genuinely new song (flyover is correct)', () => {
+    assert.equal(crowd.isArrangementSwitch('a.feedpak', 'b.feedpak'), false);
+});
+
+test('first load of the session is an arrival, not a switch', () => {
+    // No previous song -> the flyover must play.
+    assert.equal(crowd.isArrangementSwitch('', 'a.feedpak'), false);
+});
+
+test('a missing filename is never treated as a switch', () => {
+    // Otherwise a malformed payload would silently suppress the flyover for the
+    // rest of the session.
+    assert.equal(crowd.isArrangementSwitch('a.feedpak', ''), false);
+    assert.equal(crowd.isArrangementSwitch('a.feedpak', undefined), false);
+    assert.equal(crowd.isArrangementSwitch('', ''), false);
+});
+
+// ── 2. the venue belongs to the player screen ──────────────────────────────
+
+const scene = require('../../static/v3/venue-scene-3d.js');
+
+// Venue MUST be the selected visualization for these to mean anything: if the
+// viz were unset, shouldBeActive() would be false for the wrong reason and the
+// virtuoso assertion below would pass vacuously. Force the viz on, so the only
+// thing under test is the SCREEN gate.
+function withScreen(id, fn) {
+    const prevDoc = global.document;
+    const prevViz = global.v3VenueViz;
+    global.v3VenueViz = {
+        isVenueVisualization: (v) => String(v) === 'venue',
+        getSelectedVizId: () => 'venue',
+    };
+    global.document = {
+        querySelector(sel) {
+            if (sel !== '.screen.active') return null;
+            return id ? { id } : null;
+        },
+    };
+    try { return fn(); } finally { global.document = prevDoc; global.v3VenueViz = prevViz; }
+}
+
+test('guard: with Venue selected AND on the player, the venue IS active', () => {
+    // If this ever fails, every "not active" test below is vacuous.
+    withScreen('player', () => {
+        assert.equal(scene.shouldBeActive(), true,
+            'the screen gate must not break the normal case');
+    });
+});
+
+test('venue is active on the player screen', () => {
+    withScreen('player', () => {
+        assert.equal(scene.isPlayerScreen(), true);
+    });
+});
+
+test('venue is NOT active on the virtuoso screen (the bug)', () => {
+    withScreen('virtuoso', () => {
+        assert.equal(scene.isPlayerScreen(), false,
+            'Virtuoso borrows the same highway_3d renderer — the venue backdrop ' +
+            'must not follow it there');
+        assert.equal(scene.shouldBeActive(), false,
+            'selecting Venue is a preference for the PLAYER; it is not a licence ' +
+            'to paint the venue over whatever else is using the renderer');
+    });
+});
+
+test('venue is not active on any other screen either', () => {
+    for (const id of ['v3-home', 'plugin-folder_library', 'settings', 'career']) {
+        withScreen(id, () => {
+            assert.equal(scene.shouldBeActive(), false, `venue must not be active on ${id}`);
+        });
+    }
+});
+
+test('no active screen at all is not the player', () => {
+    withScreen(null, () => {
+        assert.equal(scene.isPlayerScreen(), false);
+    });
+});
+
+test('a throwing document does not take the venue down with it', () => {
+    const prev = global.document;
+    global.document = { querySelector() { throw new Error('detached'); } };
+    try {
+        assert.equal(scene.isPlayerScreen(), false, 'must fail closed, not throw');
+    } finally {
+        global.document = prev;
+    }
+});
+
+// The arrival flyover must NOT replay for songs 2..N of a set. onSongLoaded
+// consults the play queue: a continuation (gig/album/playlist song 2+) carries
+// the room over with a loop crossfade, only an arrival plays the intro.
+test('a set continuation carries the room over instead of re-flying-in', () => {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const src = fs.readFileSync(path.join(__dirname, '..', '..', 'static', 'v3', 'venue-crowd.js'), 'utf8');
+    const start = src.indexOf('function onSongLoaded(');
+    const open = src.indexOf('{', src.indexOf(')', start));
+    let depth = 1, i = open + 1;
+    while (i < src.length && depth > 0) { const ch = src[i]; if (ch === '{') depth++; else if (ch === '}') depth--; i++; }
+    const fn = src.slice(start, i);
+    const contIdx = fn.search(/_isSetContinuation\s*\(\s*\)/);
+    const introIdx = fn.search(/playIntro\s*\(/);
+    assert.ok(contIdx !== -1, 'onSongLoaded must consult the set-continuation signal');
+    assert.ok(introIdx !== -1, 'the intro must still exist for a real arrival');
+    assert.ok(contIdx < introIdx, 'the continuation check must gate the flyover — a set song 2+ must not fly in');
+});

tests/plugins/career/conftest.py

@@ -26,7 +26,7 @@ class FakeMetaDb:
         self.conn.execute(
             """CREATE TABLE song_stats (
                    filename TEXT, arrangement TEXT, best_accuracy REAL,
-                   last_played_at TEXT,
+                   last_accuracy REAL, last_played_at TEXT,
                    seconds_total REAL NOT NULL DEFAULT 0
                )"""
         )
@@ -38,10 +38,12 @@ class FakeMetaDb:
         )
 
     def add(self, filename, arrangement, best_accuracy, in_library=True,
-            genre="", arrangements=None, last_played_at=None, seconds_total=0):
-        self.conn.execute("INSERT INTO song_stats VALUES (?, ?, ?, ?, ?)",
-                          (filename, arrangement, best_accuracy, last_played_at,
-                           seconds_total))
+            genre="", arrangements=None, last_played_at=None, seconds_total=0,
+            last_accuracy=None):
+        self.conn.execute("INSERT INTO song_stats VALUES (?, ?, ?, ?, ?, ?)",
+                          (filename, arrangement, best_accuracy,
+                           last_accuracy if last_accuracy is not None else best_accuracy,
+                           last_played_at, seconds_total))
         if in_library:
             self.conn.execute(
                 "INSERT INTO songs SELECT ?, ?, ?, ?, ? WHERE NOT EXISTS "

tests/plugins/career/test_passports.py

@@ -208,3 +208,267 @@ def test_drill_state_merge_is_gained_only(client, meta_db):
     p = _passport(client)
     assert p["drills"]["cleared"] == ["blues_shuffle"]
     assert p["badge"] == "earned"
+
+
+def test_genre_families_inherit_drills(client, meta_db):
+    # 'death metal' has no exact entry — it inherits the metal family's drill.
+    for i in range(5):
+        meta_db.add(f"dm{i}.feedpak", 0, 0.9, genre="Death Metal", arrangements=LEAD)
+    _open(client, "guitar", "Death Metal")
+    p = _passport(client, "guitar", "death metal")
+    assert p["drills"]["required"] == ["melodic_metal_gallop"]
+    assert p["badge"] == "in_progress"
+    # 'metalcore' (single word) matches by substring, no alias needed.
+    _open(client, "guitar", "Metalcore")
+    assert _passport(client, "guitar", "metalcore")["drills"]["required"] == \
+        ["melodic_metal_gallop"]
+    # 'blues rock' resolves by family LIST ORDER: blues comes before rock.
+    _open(client, "guitar", "Blues Rock")
+    assert _passport(client, "guitar", "blues rock")["drills"]["required"] == \
+        ["blues_shuffle"]
+    # A genre outside every family stays songs-only.
+    _open(client, "guitar", "Reggae")
+    assert _passport(client, "guitar", "reggae")["drills"]["required"] == []
+    # Exact per-genre entries still beat the family (the shipped 'metal' entry
+    # IS the exact entry for genre key 'metal').
+    _open(client, "guitar", "Metal")
+    assert _passport(client, "guitar", "metal")["drills"]["required"] == \
+        ["melodic_metal_gallop"]
+
+
+def test_family_drills_stay_per_instrument(client, meta_db):
+    # Family inheritance must not leak guitar drills onto other instruments.
+    keys_arr = [{"type": "lead", "name": "Keys"}]
+    for i in range(5):
+        meta_db.add(f"kdm{i}.feedpak", 0, 0.9, genre="Death Metal", arrangements=keys_arr)
+    _open(client, "keys", "Death Metal")
+    p = _passport(client, "keys", "death metal")
+    assert p["drills"]["required"] == []
+    assert p["badge"] == "earned"
+
+
+def test_nearest_invitations_order_and_exclusions(client, meta_db):
+    # Non-qualifying songs sorted by distance to the QUALIFYING bar;
+    # qualifying songs never appear; capped at 3.
+    meta_db.add("q.feedpak", 0, 0.80, genre="Soul", arrangements=LEAD)      # qualifies
+    meta_db.add("close.feedpak", 0, 0.74, genre="Soul", arrangements=LEAD)  # 1% to 2★
+    meta_db.add("mid.feedpak", 0, 0.70, genre="Soul", arrangements=LEAD)    # 5% to 2★
+    meta_db.add("far.feedpak", 0, 0.30, genre="Soul", arrangements=LEAD)    # 30% to 1★
+    meta_db.add("far2.feedpak", 0, 0.25, genre="Soul", arrangements=LEAD)
+    _open(client, "guitar", "Soul")
+    p = _passport(client, "guitar", "soul")
+    names = [s["filename"] for s in p["nearest"]]
+    assert names == ["close.feedpak", "mid.feedpak", "far.feedpak"]
+    assert all(s["next_star_at"] is not None for s in p["nearest"])
+    assert "q.feedpak" not in names
+
+
+def test_nearest_targets_the_qualifying_bar_not_next_star(client, meta_db):
+    # A 0★ song 1% from its NEXT star is farther from the ★★ badge bar than
+    # a 1★ song 5% from it — nearest must rank by the badge bar.
+    meta_db.add("one_star.feedpak", 0, 0.70, genre="Soul", arrangements=LEAD)   # 5% to bar
+    meta_db.add("zero_star.feedpak", 0, 0.59, genre="Soul", arrangements=LEAD)  # 1% to next ★, 16% to bar
+    _open(client, "guitar", "Soul")
+    p = _passport(client, "guitar", "soul")
+    assert [s["filename"] for s in p["nearest"]] == ["one_star.feedpak", "zero_star.feedpak"]
+    assert all(s["bar_at"] == 0.75 for s in p["nearest"])
+# ── Gigs ──────────────────────────────────────────────────────────────────────
+
+def test_gig_propose_mixes_owned_and_stakes(client, meta_db):
+    for i in range(4):
+        meta_db.add(f"own{i}.feedpak", 0, 0.85, genre="Soul", arrangements=LEAD)
+    meta_db.add("stake.feedpak", 0, 0.70, genre="Soul", arrangements=LEAD)
+    meta_db.add_song_only("fresh.feedpak", genre="Soul")
+    res = client.post("/api/plugins/career/gigs/propose",
+                      json={"instrument": "guitar", "genre": "Soul", "size": 4})
+    assert res.status_code == 200
+    gig = res.json()
+    files = [s["filename"] for s in gig["songs"]]
+    assert len(files) == 4
+    assert "stake.feedpak" in files          # a near-bar song gives the set stakes
+    assert gig["venue_id"] == "bar"          # 9 stars < 50: the dive bar
+
+    # A young passport (nothing played) still gets a playable set from the
+    # library's unplayed genre songs.
+    res2 = client.post("/api/plugins/career/gigs/propose",
+                       json={"instrument": "guitar", "genre": "Ska"})
+    assert res2.status_code == 404           # no ska in the library at all
+    meta_db.add_song_only("ska1.feedpak", genre="Ska")
+    res3 = client.post("/api/plugins/career/gigs/propose",
+                       json={"instrument": "guitar", "genre": "Ska"})
+    assert [s["filename"] for s in res3.json()["songs"]] == ["ska1.feedpak"]
+
+
+def test_gig_log_computes_encore_and_surfaces_in_passports(client, meta_db):
+    for i in range(2):
+        meta_db.add(f"s{i}.feedpak", 0, 0.9, genre="Soul", arrangements=LEAD,
+                    last_accuracy=0.9)
+    _open(client, "guitar", "Soul")
+    res = client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul", "venue_id": "bar",
+        "songs": ["s0.feedpak", "s1.feedpak"]})
+    assert res.status_code == 200
+    gig = res.json()["gig"]
+    assert gig["encore"] is True             # avg 0.9 ≥ 0.75
+    assert gig["songs"][0]["accuracy"] == 0.9
+    view = client.get("/api/plugins/career/passports").json()
+    assert view["instruments"]["guitar"]["gig_count"] == 1
+    p = _passport(client, "guitar", "soul")
+    assert len(p["gigs"]) == 1 and p["gigs"][0]["encore"] is True
+
+
+def test_gig_log_validation_and_no_fail_state(client):
+    # Unknown venue / bad songs shapes are rejected; nothing is ever logged
+    # as a failed gig — the endpoint only appends completed sets.
+    assert client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul", "venue_id": "nope",
+        "songs": ["x"]}).status_code == 400
+    assert client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul", "songs": []}).status_code == 400
+    assert client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul",
+        "songs": ["f"] * 9}).status_code == 400
+
+
+def test_gig_accuracy_reads_newest_row_and_encore_needs_full_set(client, meta_db):
+    # Newest row wins: a stale higher accuracy on another arrangement must
+    # not inflate the gig log.
+    meta_db.add("dual.feedpak", 1, 0.95, genre="Soul", arrangements=BASS,
+                last_accuracy=0.95, last_played_at="2026-06-01T00:00:00")
+    meta_db.add("dual.feedpak", 0, 0.60, genre="Soul", arrangements=LEAD,
+                last_accuracy=0.60, last_played_at="2026-07-14T00:00:00")
+    res = client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul", "songs": ["dual.feedpak"]})
+    assert res.json()["gig"]["songs"][0]["accuracy"] == 0.6
+
+    # A set with an unscored song never earns the encore off one good song.
+    meta_db.add("scored.feedpak", 0, 0.9, genre="Soul", arrangements=LEAD,
+                last_accuracy=0.9, last_played_at="2026-07-14T00:01:00")
+    res2 = client.post("/api/plugins/career/gigs", json={
+        "instrument": "guitar", "genre": "Soul",
+        "songs": ["scored.feedpak", "ghost.feedpak"]})
+    assert res2.json()["gig"]["encore"] is False
+
+
+def test_gig_propose_backfills_from_surplus_qualifying(client, meta_db):
+    # Mature passport: plenty of qualifying songs, nothing near the bar,
+    # nothing unplayed — the set still fills to size.
+    for i in range(8):
+        meta_db.add(f"own{i}.feedpak", 0, 0.9, genre="Ska", arrangements=LEAD)
+    res = client.post("/api/plugins/career/gigs/propose",
+                      json={"instrument": "guitar", "genre": "Ska", "size": 5})
+    assert len(res.json()["songs"]) == 5
+
+
+def test_gig_propose_backfill_offset_survives_stakes(client, meta_db):
+    # 4 qualifying + 1 near-bar stake, size 5: the stake must not shift the
+    # qualifying backfill window past eligible songs.
+    for i in range(4):
+        meta_db.add(f"q{i}.feedpak", 0, 0.9, genre="Reggae", arrangements=LEAD)
+    meta_db.add("near.feedpak", 0, 0.7, genre="Reggae", arrangements=LEAD)
+    res = client.post("/api/plugins/career/gigs/propose",
+                      json={"instrument": "guitar", "genre": "Reggae", "size": 5})
+    files = [s["filename"] for s in res.json()["songs"]]
+    assert len(files) == 5 and len(set(files)) == 5
+    assert "near.feedpak" in files
+
+
+# ── Gold rung ─────────────────────────────────────────────────────────────────
+
+def test_gold_upgrades_bronze_via_family_style_artifact(client, meta_db):
+    # Bronze earned on 'death metal' (family: metal); a metal gold artifact
+    # from the jam verifier upgrades it — bronze-only stays 'earned' elsewhere.
+    for i in range(5):
+        meta_db.add(f"dm{i}.feedpak", 0, 0.9, genre="Death Metal", arrangements=LEAD)
+    career_routes._state["passports_content"]["genres"]["metal"] = {}  # no drill gate for this test
+    _open(client, "guitar", "Death Metal")
+    client.post("/api/plugins/career/drill-state", json={"byNode": {}})
+    assert _passport(client, "guitar", "death metal")["badge"] == "earned"
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"metal": {"at": 1, "verifier": "comb", "inKeyPct": 0.9}}})
+    assert _passport(client, "guitar", "death metal")["badge"] == "gold"
+
+
+def test_gold_without_bronze_stays_in_progress(client, meta_db):
+    meta_db.add("one.feedpak", 0, 0.9, genre="Soul", arrangements=LEAD)
+    _open(client, "guitar", "Soul")
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"soul": {"at": 1, "verifier": "comb"}}})
+    assert _passport(client, "guitar", "soul")["badge"] == "in_progress"
+
+
+def test_gold_merge_is_gained_only(client, meta_db):
+    for i in range(5):
+        meta_db.add(f"s{i}.feedpak", 0, 0.9, genre="Soul", arrangements=LEAD)
+    _open(client, "guitar", "Soul")
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"soul": {"at": 1, "verifier": "comb"}}})
+    assert _passport(client, "guitar", "soul")["badge"] == "gold"
+    # A stale relay without the artifact never un-mints.
+    client.post("/api/plugins/career/drill-state", json={"byNode": {}})
+    assert _passport(client, "guitar", "soul")["badge"] == "gold"
+    # And a different artifact for the same style never overwrites the first —
+    # asserted against the PERSISTED snapshot (the view doesn't expose
+    # artifact contents), so a last-write-wins regression can't stay green.
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"soul": {"at": 999, "verifier": "yin"}}})
+    _, _, gold = career_routes._drill_by_node()
+    assert gold["soul"] == {"at": 1, "verifier": "comb"}
+
+
+def test_gold_matches_raw_style_id_through_family(client, meta_db):
+    # Virtuoso mints under raw STYLE_PALETTES ids ('punk', not 'rock'): a
+    # 'punk rock' passport (family rock) must go gold from a 'punk' artifact.
+    for i in range(5):
+        meta_db.add(f"pk{i}.feedpak", 0, 0.9, genre="Punk Rock", arrangements=LEAD)
+    career_routes._state["passports_content"]["genres"]["rock"] = {}  # no drill gate
+    _open(client, "guitar", "Punk Rock")
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"punk": {"at": 1, "verifier": "comb"}}})
+    assert _passport(client, "guitar", "punk rock")["badge"] == "gold"
+
+
+def test_gold_intake_rejects_junk(client, meta_db):
+    # A non-dict goldImprov is a relay bug: loud 400, never a silent drop.
+    res = client.post("/api/plugins/career/drill-state",
+                      json={"byNode": {}, "goldImprov": ["metal"]})
+    assert res.status_code == 400
+    # Evidence-free artifacts (no verifier) never mint.
+    for i in range(5):
+        meta_db.add(f"j{i}.feedpak", 0, 0.9, genre="Soul", arrangements=LEAD)
+    _open(client, "guitar", "Soul")
+    client.post("/api/plugins/career/drill-state", json={
+        "byNode": {}, "goldImprov": {"soul": {}}})
+    assert _passport(client, "guitar", "soul")["badge"] == "earned"
+    # An oversized goldImprov is bounded BEFORE the merge, like byNode.
+    blob = {f"s{i}": {"verifier": "comb", "pad": "x" * 4096} for i in range(200)}
+    res = client.post("/api/plugins/career/drill-state",
+                      json={"byNode": {}, "goldImprov": blob})
+    assert res.status_code == 413
+
+
+def test_gig_includes_songs_played_on_another_instrument(client, meta_db):
+    # feedBack#… (tester): "Metalcore says 137 songs, only shows 1 in the gig list".
+    # A song played on a DIFFERENT instrument's arrangement has a stats row, so it
+    # was excluded from the unplayed filler — and its played bucket is that other
+    # instrument's, not this passport's — so it fell into a gap and could never be
+    # gigged. A guitar passport with a library of bass-played metalcore got a 404.
+    for i in range(137):
+        meta_db.add(f"mc{i}.feedpak", 0, 0.80, genre="Metalcore", arrangements=BASS)
+    res = client.post("/api/plugins/career/gigs/propose",
+                      json={"instrument": "guitar", "genre": "Metalcore", "size": 4})
+    assert res.status_code == 200, "a full library of the genre must never 404"
+    assert len(res.json()["songs"]) == 4, "the gig must fill from the library, not the gap"
+
+
+def test_gig_reroll_changes_the_set(client, meta_db):
+    # feedBack#… (tester): "Passport re-roll does not change songs". A set drawn
+    # from the filler used to be the library's first N in table order, every time.
+    for i in range(40):
+        meta_db.add_song_only(f"un{i}.feedpak", genre="Metalcore")
+    sets = set()
+    for _ in range(5):
+        r = client.post("/api/plugins/career/gigs/propose",
+                        json={"instrument": "guitar", "genre": "Metalcore", "size": 4})
+        sets.add(tuple(sorted(s["filename"] for s in r.json()["songs"])))
+    assert len(sets) > 1, "re-roll must be able to produce a different set"

tests/plugins/career/test_routes.py

@@ -121,12 +121,17 @@ def test_pack_file_serving_and_traversal_guard(client):
 
 
 def test_state_reports_installed_and_delete_removes(client):
+    # All three venues now ship bundled, so deleting the downloaded copy
+    # falls back to the bundled pack: installed stays True by design
+    # (downloaded packs override bundled ones, never replace them).
     _install_fake_pack("club")
     state = client.get("/api/plugins/career/state").json()
     assert {v["id"]: v["installed"] for v in state["venues"]}["club"] is True
     assert client.delete("/api/plugins/career/packs/club").status_code == 200
     state = client.get("/api/plugins/career/state").json()
-    assert {v["id"]: v["installed"] for v in state["venues"]}["club"] is False
+    assert {v["id"]: v["installed"] for v in state["venues"]}["club"] is True
+    # the downloaded override itself is gone
+    assert not (career_routes._venue_dir("club") / "manifest.json").exists()
 
 
 def test_download_worker_end_to_end(client, tmp_path):
@@ -169,3 +174,176 @@ def test_double_download_409s(client, monkeypatch):
     career_routes._state["downloads"]["bar"] = {"status": "running"}
     assert client.post("/api/plugins/career/packs/bar/download").status_code == 409
     assert client.delete("/api/plugins/career/packs/bar").status_code == 409
+
+
+# ── gig pre-extraction (the wait between songs) ─────────────────────────────
+#
+# A feedpak is a zip: the first play of one pays for its extraction into
+# sloppak_cache. Inside a set that cost landed BETWEEN songs — the player
+# finished a number and then sat waiting for the next one to unpack, mid-gig.
+# The setlist is known up front, so extract it all while the poster is up.
+
+def _career_client_with_library(tmp_path, meta_db, dlc, cache):
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    import routes as career_routes
+    app = FastAPI()
+    career_routes.setup(app, {
+        "config_dir": str(tmp_path),
+        "meta_db": meta_db,
+        "get_dlc_dir": lambda: dlc,
+        "get_sloppak_cache_dir": lambda: cache,
+    })
+    return TestClient(app)
+
+
+def _write_feedpak(dlc, name, title="T"):
+    """A minimal but REAL feedpak zip, so resolve_source_dir genuinely unpacks."""
+    import json as _json
+    import zipfile as _zip
+    p = dlc / name
+    with _zip.ZipFile(p, "w") as z:
+        z.writestr("manifest.json", _json.dumps({"title": title, "artist": "A", "arrangements": []}))
+    return p
+
+
+def test_gig_prepare_extracts_every_song_up_front(tmp_path, meta_db):
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    for n in ("one.feedpak", "two.feedpak", "three.feedpak"):
+        _write_feedpak(dlc, n)
+
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+    before = list(cache.iterdir())
+    assert before == [], "nothing unpacked yet"
+
+    res = client.post("/api/plugins/career/gigs/prepare",
+                      json={"songs": ["one.feedpak", "two.feedpak", "three.feedpak"]})
+    assert res.status_code == 200
+    body = res.json()
+    assert body["ok"] is True
+    assert body["prepared"] == 3, body
+    assert body["failed"] == []
+    # The point of the whole exercise: the set is on disk BEFORE the first note.
+    assert len(list(cache.iterdir())) == 3, "every song of the set must be unpacked"
+
+
+def test_gig_prepare_is_idempotent_on_a_warm_cache(tmp_path, meta_db):
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    _write_feedpak(dlc, "one.feedpak")
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+
+    first = client.post("/api/plugins/career/gigs/prepare", json={"songs": ["one.feedpak"]}).json()
+    second = client.post("/api/plugins/career/gigs/prepare", json={"songs": ["one.feedpak"]}).json()
+    assert first["prepared"] == second["prepared"] == 1
+    assert len(list(cache.iterdir())) == 1, "a re-prepare must not duplicate the unpack"
+
+
+def test_one_bad_feedpak_does_not_stop_the_set(tmp_path, meta_db):
+    # A corrupt pak in the setlist must not block the gig: the play itself will
+    # surface the error exactly as it does outside a gig. Slow beats blocked.
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    _write_feedpak(dlc, "good.feedpak")
+    (dlc / "bad.feedpak").write_bytes(b"not a zip at all")
+
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+    body = client.post("/api/plugins/career/gigs/prepare",
+                       json={"songs": ["good.feedpak", "bad.feedpak"]}).json()
+    assert body["ok"] is True, "a bad pak must not fail the whole prepare"
+    assert body["prepared"] == 1
+    assert body["failed"] == ["bad.feedpak"]
+
+
+def test_gig_prepare_degrades_without_a_library(tmp_path, meta_db, client):
+    # The stock fixture's context has no dlc/cache resolvers. That must be a
+    # graceful no-op, not a 500 — pre-extraction is an optimisation and can
+    # never be the reason a gig won't start.
+    res = client.post("/api/plugins/career/gigs/prepare", json={"songs": ["x.feedpak"]})
+    assert res.status_code == 200
+    assert res.json()["prepared"] == 0
+
+
+def test_gig_prepare_empty_setlist(tmp_path, meta_db, client):
+    res = client.post("/api/plugins/career/gigs/prepare", json={"songs": []})
+    assert res.status_code == 200
+    assert res.json() == {"ok": True, "prepared": 0, "failed": []}
+
+
+def test_prepare_rejects_a_non_list_songs_value(tmp_path, meta_db, client):
+    # A str is iterable: without the list check, "abc" would prepare three
+    # one-character "songs".
+    for bad in ("abc", 42, {"a": 1}, None):
+        res = client.post("/api/plugins/career/gigs/prepare", json={"songs": bad})
+        assert res.status_code == 200
+        assert res.json()["prepared"] == 0
+
+
+def test_prepare_ignores_non_string_and_blank_entries(tmp_path, meta_db):
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    _write_feedpak(dlc, "good.feedpak")
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+    body = client.post("/api/plugins/career/gigs/prepare",
+                       json={"songs": ["good.feedpak", "", "   ", 7, None, {"x": 1}]}).json()
+    assert body["prepared"] == 1
+    assert body["failed"] == []
+
+
+def test_prepare_caps_the_setlist(tmp_path, meta_db):
+    # This endpoint unpacks zips — an arbitrary caller must not be able to ask for
+    # unbounded work.
+    #
+    # The first version of this test asserted `prepared == 0` against a fixture
+    # with NO library: the endpoint exits before extraction there, so it passed
+    # whether or not the cap existed. Give it a real library, ask for far more than
+    # the cap, and assert the endpoint only ever considered MAX_GIG_SONGS of them.
+    import routes as career_routes
+    assert career_routes.MAX_GIG_SONGS <= 64
+
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+
+    n = career_routes.MAX_GIG_SONGS + 50
+    # None of these exist, so every song the endpoint LOOKS AT lands in `failed`.
+    # That makes `failed` an exact count of how many it considered.
+    body = client.post("/api/plugins/career/gigs/prepare",
+                       json={"songs": [f"missing{i}.feedpak" for i in range(n)]}).json()
+    assert body["prepared"] == 0
+    assert len(body["failed"]) == career_routes.MAX_GIG_SONGS, (
+        f"the endpoint must consider at most MAX_GIG_SONGS "
+        f"({career_routes.MAX_GIG_SONGS}), not all {n}"
+    )
+
+
+def test_prepare_refuses_to_escape_the_library(tmp_path, meta_db):
+    # resolve_source_dir() does a bare `dlc_root / filename` with no containment
+    # guard, so a crafted path would walk straight out of the library. Every
+    # filename must go through _resolve_dlc_path first.
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    (tmp_path / "outside.feedpak").write_bytes(b"secret")
+    client = _career_client_with_library(tmp_path, meta_db, dlc, cache)
+
+    for evil in ("../outside.feedpak", "..\\outside.feedpak",
+                 "a/../../outside.feedpak", "/etc/passwd", "C:/Windows/x.feedpak"):
+        body = client.post("/api/plugins/career/gigs/prepare",
+                           json={"songs": [evil]}).json()
+        assert body["prepared"] == 0, f"{evil!r} must never be prepared"
+        assert body["failed"] == [evil]
+    # Nothing outside the library may have been unpacked.
+    assert list(cache.iterdir()) == []

tests/test_feedpak_extension.py

@@ -137,6 +137,81 @@ def test_background_scan_discovers_both_suffixes(tmp_path, scan_server):
     assert "ignore.zip" not in seen
 
 
+# ── 2b. directory-signature fast path (skip the full re-stat) ────────────────
+
+def test_dir_signature_fast_path_skips_unchanged_tree(tmp_path, scan_server):
+    """After a full scan records the library-dir signature, a second scan with
+    an unchanged tree takes the fast path and does NOT re-glob/extract — but a
+    forced scan (manual Refresh) always does the full pass, and a new song
+    (which bumps the dir mtime) reverts to a full pass on its own."""
+    import unittest.mock as mock
+
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    (dlc / "a.feedpak").write_bytes(b"")
+    (tmp_path / "config.json").write_text('{"dlc_dir": "%s"}' % dlc)
+
+    scan = importlib.import_module("scan")
+    seen: list[str] = []
+
+    def mock_extract(f, dlc_dir):
+        seen.append(f.name)
+        return {"title": f.name, "artist": "", "album": ""}
+
+    with mock.patch("scan_worker._extract_meta_for_file", new=mock_extract):
+        # 1) first pass: full scan, extracts a.feedpak (+ seeded builtins),
+        #    records the signature
+        scan.background_scan()
+        assert "a.feedpak" in seen
+        assert scan._dir_signature_file().exists()
+
+        # 2) unchanged tree: fast path — no glob, no extraction at all
+        seen.clear()
+        scan.background_scan()
+        assert seen == []
+        assert scan.status()["stage"] == "complete"
+
+        # 3) a new song bumps the dlc mtime → signature mismatch → full pass
+        #    picks it up on its own (no manual Refresh needed for adds)
+        (dlc / "b.feedpak").write_bytes(b"")
+        seen.clear()
+        scan.background_scan()
+        assert "b.feedpak" in seen
+
+        # 4) force=True (Refresh) bypasses the fast path even on a settled tree:
+        #    with the signature now current, a plain scan skips, a forced one lists
+        seen.clear()
+        scan.background_scan()          # fast path
+        assert seen == []
+        forced_listed = []
+        real_delete_missing = scan.appstate.meta_db.delete_missing
+        def _spy(files):
+            forced_listed.append(set(files))
+            return real_delete_missing(files)
+        with mock.patch.object(scan.appstate.meta_db, "delete_missing", new=_spy):
+            scan.background_scan(force=True)
+        assert forced_listed, "force=True must run the full listing pass"
+
+
+def test_dir_signature_tracks_directory_form_song_own_dir(tmp_path):
+    """A directory-form song (loose folder / directory bundle) records its OWN
+    directory in the signature, so an in-place file change inside it — which
+    bumps that folder's mtime but not its parent's — invalidates the fast path.
+    A file-form sloppak (a plain .feedpak zip) is not a dir and adds nothing."""
+    scan = importlib.import_module("scan")
+    dlc = tmp_path / "dlc"
+    (dlc / "packs").mkdir(parents=True)
+    loose = dlc / "packs" / "my_loose_song"   # directory-form song
+    loose.mkdir()
+    zipped = dlc / "packs" / "zipped.feedpak"  # file-form song
+    zipped.write_bytes(b"")
+
+    rels = scan._library_dirs([loose, zipped], dlc)
+    assert "packs/my_loose_song" in rels, "directory-form song must track its own dir"
+    assert "packs" in rels and "." in rels
+    assert "packs/zipped.feedpak" not in rels, "a file-form sloppak is not a tracked dir"
+
+
 # ── 3. POST /api/songs/upload gate (endpoint) ────────────────────────────────
 
 @pytest.fixture()

tests/test_library_tuning_instrument.py

@@ -0,0 +1,721 @@
+"""Instrument-aware tuning in the library (the KwasimodoZAZA bass report).
+
+A song's BASS chart is often tuned differently from its guitar chart, but the
+library indexed exactly one guitar-first tuning per song — so a bass player
+filtering "Drop D" got songs whose GUITAR is in Drop D, and playlists built
+that way were wrong.
+
+These tests round-trip through the real extractors, the real scanner
+derivation, the real SQLite schema/migration, and the real HTTP surface. The
+only thing stubbed is metadata EXTRACTION in the scan tests (the production
+process pool can't reach an in-process mock) — never the code under test.
+
+Real-library notes, all confirmed against actual pack contents:
+
+* Bass arrangements usually store SIX-element offset arrays even when the
+  chart is a 4-string part — slots 4-5 are PADDING (no bass chart in the
+  corpus references string index 4 or 5). So bass offsets are truncated to 4
+  before naming or grouping. The feedpak spec has no string-count field, so 4
+  is a documented default, not a read value.
+* AC/DC "Girls Got Rhythm" stores [5,5,5,5,4,4] — every string up a fourth,
+  which no bassist plays. That is BAD DATA, and it must never be NAMED, or the
+  library sends a player to retune to a tuning that does not exist.
+* Covet "Shibuya" (custom guitar tuning, dead-standard bass) is the headline
+  regression: the tester's bug in a single song.
+"""
+
+import importlib
+import json
+import sys
+
+import pytest
+import yaml
+from fastapi.testclient import TestClient
+
+import sloppak as sloppak_mod
+from scan_worker import _extract_meta_for_file
+from tunings import (
+    PERSPECTIVES, bass_offsets_are_plausible, bass_tuning_key, bass_tuning_name,
+    chart_is_playable_in, normalize_bass_offsets, perspective_tuning_key,
+    tuning_name,
+)
+
+
+# ── Fixtures ─────────────────────────────────────────────────────────────────
+
+@pytest.fixture()
+def server_mod(tmp_path, monkeypatch):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+    sys.modules.pop("server", None)
+    mod = importlib.import_module("server")
+    yield mod
+    conn = getattr(getattr(mod, "meta_db", None), "conn", None)
+    if conn is not None:
+        getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+        conn.close()
+
+
+@pytest.fixture()
+def client(server_mod):
+    c = TestClient(server_mod.app)
+    try:
+        yield c
+    finally:
+        c.close()
+
+
+def _pack(root, name, arrangements):
+    """A directory-form pack whose manifest carries per-arrangement tunings."""
+    d = root / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(yaml.safe_dump({
+        "title": name, "artist": "A", "duration": 100,
+        "arrangements": arrangements, "stems": [],
+    }), encoding="utf-8")
+    return d
+
+
+def _put(server_mod, *, filename, title, tuning_name_="E Standard",
+         tuning_sort_key=0, tuning_offsets="0 0 0 0 0 0",
+         bass_tuning_name="", bass_tuning_sort_key=0, bass_tuning_offsets="",
+         bass_tuning_key=""):
+    server_mod.meta_db.put(filename, 1.0, 1, {
+        "title": title, "artist": "A", "album": "A - LP", "year": "2010",
+        "duration": 200.0, "tuning": tuning_name_, "arrangements": [],
+        "has_lyrics": False, "format": "sloppak", "stem_ids": [],
+        "tuning_name": tuning_name_,
+        "tuning_sort_key": tuning_sort_key,
+        "tuning_offsets": tuning_offsets,
+        "bass_tuning_name": bass_tuning_name,
+        "bass_tuning_sort_key": bass_tuning_sort_key,
+        "bass_tuning_offsets": bass_tuning_offsets,
+        "bass_tuning_key": bass_tuning_key,
+    })
+
+
+# ── 1. Extraction: sloppak ───────────────────────────────────────────────────
+
+def test_sloppak_extract_indexes_both_tunings_when_they_differ(tmp_path):
+    """The reported case: guitar down a step, bass in standard. BOTH must be
+    indexed — previously only the guitar tuning survived."""
+    d = _pack(tmp_path, "differ.sloppak", [
+        {"name": "Lead", "tuning": [-2, 0, 0, -1, -2, 0]},
+        {"name": "Bass", "tuning": [0, 0, 0, 0, 0, 0]},
+    ])
+    meta = sloppak_mod.extract_meta(d)
+    assert meta["tuning_offsets"] == [-2, 0, 0, -1, -2, 0]
+    assert meta["bass_tuning_offsets"] == [0, 0, 0, 0, 0, 0]
+
+
+def test_sloppak_extract_leaves_bass_absent_without_bass_arrangement(tmp_path):
+    """No bass chart → None, NOT a copy of the guitar tuning. The library
+    falls back explicitly, so 'no bass part' stays distinguishable."""
+    d = _pack(tmp_path, "nobass.sloppak", [
+        {"name": "Lead", "tuning": [-2, -2, -2, -2, -2, -2]},
+        {"name": "Rhythm", "tuning": [-2, -2, -2, -2, -2, -2]},
+    ])
+    meta = sloppak_mod.extract_meta(d)
+    assert meta["tuning_offsets"] == [-2, -2, -2, -2, -2, -2]
+    assert meta["bass_tuning_offsets"] is None
+
+
+def test_sloppak_extract_bass_wins_over_guitar_first_ordering(tmp_path):
+    """The bass entry is listed FIRST in the manifest; the song tuning must
+    still be the guitar's while the bass column takes the bass entry — the two
+    selections are independent, not 'first wins'."""
+    d = _pack(tmp_path, "order.sloppak", [
+        {"name": "Bass", "tuning": [-4, -4, -4, -4, -4, -4]},
+        {"name": "Lead", "tuning": [0, 0, 0, 0, 0, 0]},
+    ])
+    meta = sloppak_mod.extract_meta(d)
+    assert meta["tuning_offsets"] == [0, 0, 0, 0, 0, 0]
+    assert meta["bass_tuning_offsets"] == [-4, -4, -4, -4, -4, -4]
+
+
+def test_sloppak_extract_ignores_bass_arrangement_without_a_tuning(tmp_path):
+    """A bass chart that authors no tuning gives us nothing to index; the
+    column stays empty rather than defaulting to a wrong all-zeros."""
+    d = _pack(tmp_path, "untuned.sloppak", [
+        {"name": "Lead", "tuning": [-2, -2, -2, -2, -2, -2]},
+        {"name": "Bass"},
+    ])
+    assert sloppak_mod.extract_meta(d)["bass_tuning_offsets"] is None
+
+
+def test_sloppak_extract_falls_back_to_an_alt_bass_chart(tmp_path):
+    """Only a "Bass 2" chart exists. Using it beats reporting the guitar
+    tuning as the player's bass tuning."""
+    d = _pack(tmp_path, "altbass.sloppak", [
+        {"name": "Lead", "tuning": [0, 0, 0, 0, 0, 0]},
+        {"name": "Bass 2", "tuning": [-2, 0, 0, 0, 0, 0]},
+    ])
+    assert sloppak_mod.extract_meta(d)["bass_tuning_offsets"] == [-2, 0, 0, 0, 0, 0]
+
+
+# ── 2. Scanner derivation (name / sort key / offsets string) ─────────────────
+
+def test_scan_worker_derives_bass_columns_like_the_guitar_ones(tmp_path):
+    """Guitar columns keep all six strings; bass columns are TRUNCATED to the
+    bass's four (the stored tail is padding — see tunings.normalize_bass_offsets)."""
+    d = _pack(tmp_path, "derive.sloppak", [
+        {"name": "Lead", "tuning": [-2, -2, -2, -2, -2, -2]},
+        {"name": "Bass", "tuning": [0, 0, 0, 0, 0, 0]},
+    ])
+    meta = _extract_meta_for_file(d)
+    assert meta["tuning_name"] == "D Standard"
+    assert meta["tuning_sort_key"] == -12
+    assert meta["tuning_offsets"] == "-2 -2 -2 -2 -2 -2"
+    assert meta["bass_tuning_name"] == "E Standard"
+    assert meta["bass_tuning_sort_key"] == 0
+    assert meta["bass_tuning_offsets"] == "0 0 0 0"
+    # Canonical key = absolute open pitches of a 4-string bass in standard.
+    assert meta["bass_tuning_key"] == "bass:28:33:38:43"
+
+
+def test_bass_padding_is_truncated_before_naming_and_grouping(tmp_path):
+    """The padded tail must never reach the namer or the group key: a bass
+    stored six-wide and the same tuning stored four-wide must produce
+    IDENTICAL indexed columns."""
+    six = _extract_meta_for_file(_pack(tmp_path, "six.sloppak", [
+        {"name": "Bass", "tuning": [-2, 0, 0, 0, 0, 0]}]))
+    four = _extract_meta_for_file(_pack(tmp_path, "four.sloppak", [
+        {"name": "Bass", "tuning": [-2, 0, 0, 0]}]))
+    for col in ("bass_tuning_name", "bass_tuning_offsets",
+                "bass_tuning_sort_key", "bass_tuning_key"):
+        assert six[col] == four[col], col
+    assert six["bass_tuning_name"] == "Drop D"
+
+
+def test_scan_worker_bass_columns_empty_without_a_bass_arrangement(tmp_path):
+    """Empty string, never None: '' is the indexed 'we looked, no bass chart'
+    state, while NULL means 'never extracted' and triggers a re-scan."""
+    d = _pack(tmp_path, "nobass2.sloppak", [{"name": "Lead", "tuning": [0] * 6}])
+    meta = _extract_meta_for_file(d)
+    assert meta["bass_tuning_name"] == ""
+    assert meta["bass_tuning_sort_key"] == 0
+    assert meta["bass_tuning_offsets"] == ""
+
+
+def test_implausible_bass_tuning_is_never_named(tmp_path):
+    """Real library data, and it is BAD DATA: AC/DC "Girls Got Rhythm" stores
+    a bass tuning of [5,5,5,5,4,4] — every string up a perfect fourth, which
+    no bassist plays (roughly double string tension), on a song whose guitar
+    chart is dead standard.
+
+    Truncation alone would leave [5,5,5,5] = "all strings up a 4th", which the
+    namer WOULD happily name. Naming it would send a player off to retune to a
+    tuning that does not exist, so the plausibility guard must refuse: bassists
+    tune down, essentially never up."""
+    d = _pack(tmp_path, "weird.sloppak", [
+        {"name": "Lead", "tuning": [0, 0, 0, 0, 0, 0]},
+        {"name": "Bass", "tuning": [5, 5, 5, 5, 4, 4]},
+    ])
+    meta = _extract_meta_for_file(d)
+    assert meta["bass_tuning_name"] == "Custom Tuning"
+    assert meta["bass_tuning_offsets"] == "5 5 5 5"
+    assert meta["bass_tuning_sort_key"] == 20
+
+
+@pytest.mark.parametrize("offsets", [
+    [5, 5, 5, 5], [5, 5, 5, 5, 4, 4], [2, 2, 2, 2], [12, 12, 12, 12],
+])
+def test_up_tuned_bass_offsets_are_refused_by_the_guard(offsets):
+    """Anything above +1 semitone is data we do not trust. Note the namer
+    ALONE would name several of these ([2,2,2,2] -> "F# Standard"), which is
+    exactly the retune-to-nowhere the guard exists to prevent."""
+    norm = normalize_bass_offsets(offsets)
+    assert bass_offsets_are_plausible(norm) is False
+    assert bass_tuning_name(norm) == "Custom Tuning"
+
+
+@pytest.mark.parametrize("offsets,expected", [
+    ([0, 0, 0, 0], "E Standard"),        # standard
+    ([-1, -1, -1, -1], "Eb Standard"),   # down a semitone
+    ([-2, 0, 0, 0], "Drop D"),           # drop
+    ([1, 1, 1, 1], "F Standard"),        # +1 is the plausible ceiling, still named
+])
+def test_plausible_bass_tunings_are_still_named(offsets, expected):
+    """The guard must not over-fire: real down-tunings, standard, and the +1
+    ceiling all keep their names."""
+    assert bass_tuning_name(offsets) == expected
+
+
+# ── 3. Storage round-trip + the pre-migration re-extract marker ──────────────
+
+def test_put_get_round_trips_the_bass_columns(server_mod):
+    _put(server_mod, filename="rt.sloppak", title="RT",
+         tuning_name_="D Standard", tuning_sort_key=-12,
+         tuning_offsets="-2 -2 -2 -2 -2 -2",
+         bass_tuning_name="E Standard", bass_tuning_offsets="0 0 0 0 0 0")
+    got = server_mod.meta_db.get("rt.sloppak", 1.0, 1)
+    assert got["tuning_name"] == "D Standard"
+    assert got["bass_tuning_name"] == "E Standard"
+    assert got["bass_tuning_offsets"] == "0 0 0 0 0 0"
+
+
+def test_put_never_writes_null_bass_columns(server_mod):
+    """A freshly-scanned row is by definition extracted, so even a song with
+    no bass chart stores '' — otherwise it would look pre-migration forever
+    and the scanner would re-extract it on every single pass."""
+    _put(server_mod, filename="fresh.sloppak", title="Fresh")
+    row = server_mod.meta_db.conn.execute(
+        "SELECT bass_tuning_name FROM songs WHERE filename = 'fresh.sloppak'").fetchone()
+    assert row[0] == ""
+    assert server_mod.meta_db.get("fresh.sloppak", 1.0, 1)["bass_tuning_name"] == ""
+
+
+def test_pre_migration_row_reads_back_as_null(server_mod):
+    """A row written before the columns existed (simulated with raw SQL that
+    omits them) reads back None — the marker the scanner keys its re-extract
+    on. If this ever became '' the backfill would silently never run."""
+    server_mod.meta_db.conn.execute(
+        "INSERT INTO songs (filename, mtime, size, title, artist, album, year, "
+        "duration, tuning, arrangements, has_lyrics, format, stem_count, "
+        "stem_ids, tuning_name, tuning_sort_key, tuning_offsets) "
+        "VALUES ('old.sloppak', 1.0, 1, 'Old', 'A', 'A - LP', '2010', 200.0, "
+        "'E Standard', '[]', 0, 'sloppak', 0, '[]', 'E Standard', 0, '0 0 0 0 0 0')")
+    server_mod.meta_db.conn.commit()
+    got = server_mod.meta_db.get("old.sloppak", 1.0, 1)
+    assert got["bass_tuning_name"] is None
+    # Same for the canonical key: coalescing this to '' would make the
+    # scanner's re-extract check unfireable and strand the backfill.
+    assert got["bass_tuning_key"] is None
+
+
+def test_a_row_missing_only_the_canonical_key_still_re_extracts(server_mod):
+    """A row scanned by an EARLIER build of this feature has bass_tuning_name
+    but no bass_tuning_key. It must still be re-queued, or its custom tunings
+    would group on the old serialization-dependent key forever."""
+    _put(server_mod, filename="halfway.sloppak", title="Halfway",
+         bass_tuning_name="Drop D", bass_tuning_offsets="-2 0 0 0")
+    server_mod.meta_db.conn.execute(
+        "UPDATE songs SET bass_tuning_key = NULL WHERE filename = 'halfway.sloppak'")
+    server_mod.meta_db.conn.commit()
+    cached = server_mod.meta_db.get("halfway.sloppak", 1.0, 1)
+    assert cached["bass_tuning_name"] == "Drop D"
+    assert cached["bass_tuning_key"] is None   # → the scanner re-queues it
+
+
+# ── 4. The migration actually backfills (the highest-risk gap) ───────────────
+
+@pytest.fixture()
+def scan_server(tmp_path, monkeypatch, isolate_logging, reset_scan_state):
+    """Server with the background scan forced in-process (see
+    test_feedpak_extension.py::scan_server — the production spawn pool can't
+    reach an in-process mock)."""
+    import concurrent.futures
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+    monkeypatch.delenv("DLC_DIR", raising=False)
+    sys.modules.pop("server", None)
+    mod = importlib.import_module("server")
+    import scan as scan_mod
+    monkeypatch.setattr(
+        scan_mod, "_make_scan_executor",
+        lambda: concurrent.futures.ThreadPoolExecutor(max_workers=4),
+    )
+    yield mod
+    conn = getattr(getattr(mod, "meta_db", None), "conn", None)
+    if conn is not None:
+        getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+        conn.close()
+
+
+def test_existing_library_backfills_bass_tuning_on_next_scan(tmp_path, scan_server):
+    """END TO END for every CURRENT user: a settled library whose rows predate
+    the bass columns must re-extract on the next scan.
+
+    Both guards are exercised together — the row-level "bass column is NULL →
+    re-queue" AND the tree-signature fast path, which on an unchanged library
+    would otherwise skip the listing pass entirely and strand the backfill.
+    Then a second scan must NOT re-extract (the backfill converges, it doesn't
+    re-scan the whole library every launch).
+    """
+    import unittest.mock as mock
+
+    dlc = tmp_path / "dlc"
+    dlc.mkdir()
+    (dlc / "song.feedpak").write_bytes(b"")
+    # json.dumps, not %s: a Windows path interpolated raw produces invalid JSON
+    # escapes (\U, \d), the config silently fails to parse, and the scan then
+    # reports "no DLC folder configured" and extracts nothing.
+    (tmp_path / "config.json").write_text(
+        json.dumps({"dlc_dir": str(dlc)}), encoding="utf-8")
+
+    scan = importlib.import_module("scan")
+    seen: list[str] = []
+
+    def mock_extract(f, dlc_dir):
+        seen.append(f.name)
+        return {"title": f.name, "artist": "A", "album": "",
+                "bass_tuning_name": "Drop D", "bass_tuning_sort_key": -2,
+                "bass_tuning_offsets": "-2 0 0 0 0 0"}
+
+    with mock.patch("scan_worker._extract_meta_for_file", new=mock_extract):
+        scan.background_scan()
+        assert "song.feedpak" in seen
+
+        # Simulate the pre-migration state: the row exists and is otherwise
+        # fresh (mtime/size match), but its bass columns were never extracted.
+        scan.appstate.meta_db.conn.execute(
+            "UPDATE songs SET bass_tuning_name = NULL, bass_tuning_sort_key = NULL, "
+            "bass_tuning_offsets = NULL")
+        scan.appstate.meta_db.conn.commit()
+
+        seen.clear()
+        scan.background_scan()
+        assert "song.feedpak" in seen, (
+            "a row with NULL bass columns must re-extract — otherwise no "
+            "existing library ever gets the bass tuning")
+
+        row = scan.appstate.meta_db.conn.execute(
+            "SELECT bass_tuning_name, bass_tuning_offsets FROM songs "
+            "WHERE filename = 'song.feedpak'").fetchone()
+        assert row == ("Drop D", "-2 0 0 0 0 0")
+
+        # Converged: the fast path is back and nothing re-extracts.
+        seen.clear()
+        scan.background_scan()
+        assert seen == []
+
+
+# ── 5. The facet endpoint ────────────────────────────────────────────────────
+
+@pytest.fixture()
+def facet_seeded(server_mod):
+    """Three shapes, matching the real library's distribution:
+      differ   — guitar D Standard, bass E Standard   (the bug)
+      match    — both Drop D                          (common)
+      nobass   — guitar Drop D, no bass chart         (fallback, common)
+    """
+    _put(server_mod, filename="differ.sloppak", title="Differ",
+         tuning_name_="D Standard", tuning_sort_key=-12,
+         tuning_offsets="-2 -2 -2 -2 -2 -2",
+         bass_tuning_name="E Standard", bass_tuning_sort_key=0,
+         bass_tuning_offsets="0 0 0 0 0 0")
+    _put(server_mod, filename="match.sloppak", title="Match",
+         tuning_name_="Drop D", tuning_sort_key=-2, tuning_offsets="-2 0 0 0 0 0",
+         bass_tuning_name="Drop D", bass_tuning_sort_key=-2,
+         bass_tuning_offsets="-2 0 0 0 0 0")
+    _put(server_mod, filename="nobass.sloppak", title="NoBass",
+         tuning_name_="Drop D", tuning_sort_key=-2, tuning_offsets="-2 0 0 0 0 0")
+
+
+def _facet(client, **kw):
+    return {t["name"]: t["count"]
+            for t in client.get("/api/library/tuning-names", params=kw).json()["tunings"]}
+
+
+def test_facet_defaults_to_the_guitar_tuning(client, facet_seeded):
+    assert _facet(client) == {"D Standard": 1, "Drop D": 2}
+
+
+def test_facet_bass_groups_by_bass_tuning_with_guitar_fallback(client, facet_seeded):
+    """differ counts under its BASS tuning (E Standard), match under Drop D,
+    and nobass — having no bass chart — falls back to its guitar Drop D rather
+    than vanishing from the facet."""
+    assert _facet(client, instrument="bass") == {"E Standard": 1, "Drop D": 2}
+
+
+def test_facet_ignores_an_unknown_instrument(client, facet_seeded):
+    """An unknown value must not silently change filter semantics."""
+    assert _facet(client, instrument="theremin") == _facet(client)
+
+
+# ── 6. The filter: the actual reported bug ───────────────────────────────────
+
+def _files(client, **kw):
+    return {s["filename"] for s in client.get("/api/library", params=kw).json()["songs"]}
+
+
+def test_bass_filter_excludes_a_song_whose_only_match_is_its_guitar_tuning(
+        client, facet_seeded):
+    """THE BUG. Filtering bass "D Standard" must NOT return `differ` — its
+    D Standard is the GUITAR chart; its bass is in E Standard."""
+    assert _files(client, tunings="D Standard") == {"differ.sloppak"}
+    assert _files(client, tunings="D Standard", instrument="bass") == set()
+
+
+def test_bass_filter_returns_songs_by_their_bass_tuning(client, facet_seeded):
+    """…and the converse: bass "E Standard" finds `differ`, which the guitar
+    filter would never return."""
+    assert _files(client, tunings="E Standard") == set()
+    assert _files(client, tunings="E Standard", instrument="bass") == {"differ.sloppak"}
+
+
+def test_bass_filter_keeps_songs_without_a_bass_arrangement_via_fallback(
+        client, facet_seeded):
+    """The most common shape. `nobass` has no bass chart, so it must still be
+    reachable under its guitar tuning instead of disappearing for bass users —
+    and the facet's count for that pill must equal what the filter returns."""
+    got = _files(client, tunings="Drop D", instrument="bass")
+    assert got == {"match.sloppak", "nobass.sloppak"}
+    assert _facet(client, instrument="bass")["Drop D"] == len(got)
+
+
+def test_custom_bass_tunings_stay_distinct_under_their_offsets(client, server_mod):
+    """Two unnameable bass tunings both label "Custom Tuning"; the facet keys
+    them on raw offsets so selecting one doesn't drag in the other. Uses the
+    real [5,5,5,5,4,4] shape from the library."""
+    _put(server_mod, filename="c1.sloppak", title="C1",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=28,
+         bass_tuning_offsets="5 5 5 5 4 4")
+    _put(server_mod, filename="c2.sloppak", title="C2",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=-7,
+         bass_tuning_offsets="-3 -1 -1 -1 -1 0")
+    keys = [t["key"] for t in client.get(
+        "/api/library/tuning-names", params={"instrument": "bass"}).json()["tunings"]
+        if t["name"] == "Custom Tuning"]
+    assert sorted(keys) == sorted(["5 5 5 5 4 4", "-3 -1 -1 -1 -1 0"])
+    assert _files(client, tunings="5 5 5 5 4 4", instrument="bass") == {"c1.sloppak"}
+
+
+def test_stats_facet_counts_agree_with_the_bass_filter(client, facet_seeded):
+    """The A–Z rail / count surface must apply the same instrument-aware
+    predicate as the grid, or the header count contradicts the results."""
+    body = client.get("/api/library/stats", params={
+        "tunings": "Drop D", "instrument": "bass"}).json()
+    assert body["total_songs"] == 2
+
+
+# ── 7. Sort ──────────────────────────────────────────────────────────────────
+
+def test_tuning_sort_respects_the_instrument(client, facet_seeded):
+    """Tuning sort is musical distance from E Standard. For a bass player that
+    distance must be measured on the BASS tuning: `differ` is the furthest
+    song by guitar (D Standard, |−12|) but the nearest by bass (E Standard, 0),
+    so it moves from last to first."""
+    def order(**kw):
+        return [s["filename"] for s in client.get(
+            "/api/library", params={"sort": "tuning", **kw}).json()["songs"]]
+
+    guitar = order()
+    assert guitar[-1] == "differ.sloppak"
+    bass = order(instrument="bass")
+    assert bass[0] == "differ.sloppak"
+
+
+# ── 8. Song payload ──────────────────────────────────────────────────────────
+
+# ── 9. Real-library offset SHAPES ────────────────────────────────────────────
+# Measured across the 59-pack test library: bass offset lists are NOT reliably
+# 4 or reliably 6 — 41 store six elements, 1 stores four. Two six-element ones
+# diverge in the tail (AC/DC "Girls Got Rhythm" [5,5,5,5,4,4]; Intervals
+# "Libra" [-2,0,0,0,0,0]). Nothing may crash or mislabel on any of them.
+
+@pytest.mark.parametrize("offsets,expected", [
+    ([0, 0, 0, 0], "E Standard"),                 # four-element (the 1 outlier)
+    ([0, 0, 0, 0, 0, 0], "E Standard"),           # six-element all-equal (39 of them)
+    ([-1, -1, -1, -1], "Eb Standard"),            # four-element, down a semitone
+    ([5, 5, 5, 5, 4, 4], "Custom Tuning"),        # AC/DC — divergent tail
+    ([-2, 0, 0, 0, 0, 0], "Drop D"),              # Intervals — drop + trailing zeros
+    ([0, 0, 0, 0, 0], "Custom Tuning"),           # five: no naming convention → custom
+])
+def test_real_library_bass_offset_shapes_name_without_crashing(offsets, expected):
+    assert tuning_name(offsets) == expected
+
+
+@pytest.mark.parametrize("offsets", [
+    [0, 0, 0, 0], [0, 0, 0, 0, 0, 0], [5, 5, 5, 5, 4, 4], [-2, 0, 0, 0, 0, 0],
+])
+def test_real_library_bass_offset_shapes_survive_extraction(tmp_path, offsets):
+    """Each shape must round-trip the real extractor + scanner derivation,
+    landing on the NORMALIZED (truncated, plausibility-checked) columns."""
+    norm = normalize_bass_offsets(offsets)
+    d = _pack(tmp_path, "shape.sloppak", [
+        {"name": "Lead", "tuning": [0, 0, 0, 0, 0, 0]},
+        {"name": "Bass", "tuning": offsets},
+    ])
+    meta = _extract_meta_for_file(d)
+    assert meta["bass_tuning_name"] == bass_tuning_name(norm)
+    assert meta["bass_tuning_offsets"] == " ".join(str(o) for o in norm)
+    assert meta["bass_tuning_sort_key"] == sum(norm)
+    assert meta["bass_tuning_key"] == bass_tuning_key(norm)
+
+
+def test_named_bass_tunings_group_across_serialization_lengths(client, server_mod):
+    """The length question does NOT fragment NAMED tunings: a bass stored as
+    four elements and one stored as six both name "E Standard", and the facet
+    groups by name — so they land in ONE row with a combined count. This is the
+    common case (40 of the 42 bass arrangements in the real library)."""
+    _put(server_mod, filename="four.sloppak", title="Four",
+         bass_tuning_name=tuning_name([0, 0, 0, 0]), bass_tuning_offsets="0 0 0 0")
+    _put(server_mod, filename="six.sloppak", title="Six",
+         bass_tuning_name=tuning_name([0, 0, 0, 0, 0, 0]),
+         bass_tuning_offsets="0 0 0 0 0 0")
+    assert _facet(client, instrument="bass") == {"E Standard": 2}
+    assert _files(client, tunings="E Standard", instrument="bass") == {
+        "four.sloppak", "six.sloppak"}
+
+
+def test_drop_d_bass_groups_across_serialization_lengths(client, server_mod):
+    """Same for the Intervals shape: [-2,0,0,0,0,0] and [-2,0,0,0] both name
+    "Drop D", so trailing zeros can't split a named tuning into two rows."""
+    _put(server_mod, filename="d6.sloppak", title="D6",
+         bass_tuning_name=tuning_name([-2, 0, 0, 0, 0, 0]),
+         bass_tuning_sort_key=-2, bass_tuning_offsets="-2 0 0 0 0 0")
+    _put(server_mod, filename="d4.sloppak", title="D4",
+         bass_tuning_name=tuning_name([-2, 0, 0, 0]),
+         bass_tuning_sort_key=-2, bass_tuning_offsets="-2 0 0 0")
+    assert _facet(client, instrument="bass") == {"Drop D": 2}
+
+
+def test_equivalent_custom_bass_tunings_group_into_one_facet_row(client, server_mod):
+    """Two CUSTOM bass tunings that are the same physical tuning must be ONE
+    facet row, however they were serialized. They group on canonical PITCHES
+    (bass_tuning_key), so the offsets string no longer fragments them —
+    previously this produced two rows with split counts."""
+    key = bass_tuning_key([-3, -1, -1, -1])
+    _put(server_mod, filename="c6.sloppak", title="C6",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=-6,
+         bass_tuning_offsets="-3 -1 -1 -1", bass_tuning_key=key)
+    _put(server_mod, filename="c4.sloppak", title="C4",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=-6,
+         bass_tuning_offsets="-3 -1 -1 -1", bass_tuning_key=key)
+    rows = client.get("/api/library/tuning-names",
+                      params={"instrument": "bass"}).json()["tunings"]
+    customs = [t for t in rows if t["name"] == "Custom Tuning"]
+    assert len(customs) == 1 and customs[0]["count"] == 2
+    assert _files(client, tunings=customs[0]["key"], instrument="bass") == {
+        "c6.sloppak", "c4.sloppak"}
+
+
+def test_canonical_key_is_pitch_not_serialization(tmp_path):
+    """The property that makes the grouping robust: two serializations of one
+    tuning yield the same key, and two genuinely different tunings do not."""
+    assert bass_tuning_key(normalize_bass_offsets([-2, 0, 0, 0, 0, 0])) == \
+        bass_tuning_key(normalize_bass_offsets([-2, 0, 0, 0]))
+    assert bass_tuning_key([-2, 0, 0, 0]) != bass_tuning_key([-3, 0, 0, 0])
+    # Absolute open pitches of a standard 4-string bass (E1 A1 D2 G2).
+    assert bass_tuning_key([0, 0, 0, 0]) == "bass:28:33:38:43"
+
+
+def test_custom_bass_facet_row_selects_exactly_what_it_counted(client, server_mod):
+    """Whatever the grouping rule, the invariant that must NEVER break: every
+    facet row's count equals the number of songs its own key returns. This is
+    what makes the seam safe to change — a normalization that merged rows but
+    not the filter would fail here."""
+    _put(server_mod, filename="x6.sloppak", title="X6",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=28,
+         bass_tuning_offsets="5 5 5 5 4 4")
+    _put(server_mod, filename="x4.sloppak", title="X4",
+         bass_tuning_name="Custom Tuning", bass_tuning_sort_key=20,
+         bass_tuning_offsets="5 5 5 5")
+    _put(server_mod, filename="plain.sloppak", title="Plain",
+         bass_tuning_name="E Standard", bass_tuning_offsets="0 0 0 0 0 0")
+    for row in client.get("/api/library/tuning-names",
+                          params={"instrument": "bass"}).json()["tunings"]:
+        got = _files(client, tunings=row["key"], instrument="bass")
+        assert len(got) == row["count"], (
+            f"facet row {row['key']!r} counted {row['count']} but selects {len(got)}")
+
+
+# ── 10. THE HEADLINE REGRESSION ──────────────────────────────────────────────
+
+def test_covet_shibuya_is_findable_by_a_bassist(tmp_path, server_mod, client):
+    """Covet - "Shibuya" (Effloresce): the guitar is in a custom tuning
+    [-2,0,0,-1,-2,0] while the bass is dead standard. This is the tester's bug
+    in one song — a bassist filtering "E Standard" never saw it, because the
+    library only knew the guitar's custom tuning.
+
+    Round-tripped through the REAL extractor and scanner derivation, not
+    hand-written columns, so it covers the whole chain."""
+    d = _pack(tmp_path, "shibuya.sloppak", [
+        {"name": "Lead", "tuning": [-2, 0, 0, -1, -2, 0]},
+        {"name": "Bass", "tuning": [0, 0, 0, 0, 0, 0]},
+    ])
+    meta = _extract_meta_for_file(d)
+    server_mod.meta_db.put("shibuya.sloppak", 1.0, 1, {
+        **meta, "title": "Shibuya", "artist": "Covet", "album": "Effloresce"})
+
+    # The guitar chart really is a custom tuning…
+    assert meta["tuning_name"] == "Custom Tuning"
+    # …and the bass chart really is standard.
+    assert meta["bass_tuning_name"] == "E Standard"
+
+    # Before the fix a bassist filtering E Standard got nothing.
+    assert _files(client, tunings="E Standard") == set()
+    assert _files(client, tunings="E Standard", instrument="bass") == {"shibuya.sloppak"}
+
+    # And it appears in the bass facet under E Standard, as a REAL bass chart
+    # (not an inferred fallback).
+    row = next(t for t in client.get(
+        "/api/library/tuning-names", params={"instrument": "bass"}).json()["tunings"]
+        if t["name"] == "E Standard")
+    assert row["count"] == 1 and row["inferred_count"] == 0
+
+
+# ── 11. Provenance: the fallback must be honest, never silent ────────────────
+
+def test_facet_reports_how_many_rows_are_inferred_from_the_guitar_chart(
+        client, facet_seeded):
+    """The fallback keeps no-bass-chart songs visible (a third of a real
+    library), but the UI must be able to say so. `nobass` has no bass chart and
+    rides under the guitar's Drop D; `match` has a real one."""
+    rows = {t["name"]: t for t in client.get(
+        "/api/library/tuning-names", params={"instrument": "bass"}).json()["tunings"]}
+    assert rows["Drop D"]["count"] == 2
+    assert rows["Drop D"]["inferred_count"] == 1      # nobass only
+    assert rows["E Standard"]["inferred_count"] == 0  # differ has a real bass chart
+
+
+def test_guitar_facet_reports_no_inferred_rows(client, facet_seeded):
+    """Guitar is never a fallback perspective, so nothing is ever inferred."""
+    rows = client.get("/api/library/tuning-names").json()["tunings"]
+    assert all(t["inferred_count"] == 0 for t in rows)
+
+
+def test_song_rows_mark_an_inferred_tuning(client, facet_seeded):
+    """A bass player's row must be distinguishable: native bass chart vs
+    borrowed from the guitar. Without this the card silently presents a guitar
+    tuning as the bass tuning — the original bug in a new place."""
+    rows = {s["filename"]: s for s in client.get(
+        "/api/library", params={"instrument": "bass"}).json()["songs"]}
+    assert rows["differ.sloppak"]["tuning_inferred"] is False
+    assert rows["nobass.sloppak"]["tuning_inferred"] is True
+    assert rows["differ.sloppak"]["tuning_perspective"] == "bass"
+
+
+def test_guitar_rows_carry_no_bass_perspective_fields(client, facet_seeded):
+    """The guitar payload is untouched — no perspective/inferred keys at all."""
+    row = client.get("/api/library").json()["songs"][0]
+    assert "tuning_inferred" not in row and "tuning_perspective" not in row
+
+
+def test_arrangements_has_bass_is_the_real_bass_chart_lever(server_mod, client):
+    """'Only songs with a real bass chart' is the EXISTING `arrangements_has`
+    filter — no new filter, no "confirmed tunings" checkbox. It composes with
+    the tuning filter, so a bassist who wants to exclude inferred rows already
+    can, and it is already expressible in a saved collection rule."""
+    def put_with_arrs(fn, arrs, **kw):
+        server_mod.meta_db.put(fn, 1.0, 1, {
+            "title": fn, "artist": "A", "album": "A - LP", "year": "2010",
+            "duration": 200.0, "tuning": "Drop D", "arrangements": arrs,
+            "has_lyrics": False, "format": "sloppak", "stem_ids": [],
+            "tuning_name": "Drop D", "tuning_sort_key": -2,
+            "tuning_offsets": "-2 0 0 0 0 0", **kw})
+
+    put_with_arrs("withbass.sloppak",
+                  [{"index": 0, "name": "Lead"}, {"index": 1, "name": "Bass"}],
+                  bass_tuning_name="Drop D", bass_tuning_sort_key=-2,
+                  bass_tuning_offsets="-2 0 0 0",
+                  bass_tuning_key=bass_tuning_key([-2, 0, 0, 0]))
+    put_with_arrs("nobass.sloppak", [{"index": 0, "name": "Lead"}])
+
+    # Both are reachable under the bass Drop D pill (the fallback keeps the
+    # no-bass-chart song visible)…
+    assert _files(client, tunings="Drop D", instrument="bass") == {
+        "withbass.sloppak", "nobass.sloppak"}
+    # …and the existing arrangements_has lever narrows to real bass charts.
+    assert _files(client, tunings="Drop D", instrument="bass",
+                  arrangements_has="Bass") == {"withbass.sloppak"}
+
+
+def test_song_rows_carry_the_bass_tuning_for_the_client(client, facet_seeded):
+    """The card renders the bass tuning client-side, so the row must ship it —
+    and ship '' (not the guitar value) when there is no bass chart, so the
+    client's fallback stays the client's decision."""
+    rows = {s["filename"]: s for s in client.get("/api/library").json()["songs"]}
+    assert rows["differ.sloppak"]["tuning_name"] == "D Standard"
+    assert rows["differ.sloppak"]["bass_tuning_name"] == "E Standard"
+    assert rows["differ.sloppak"]["bass_tuning_offsets"] == "0 0 0 0 0 0"
+    assert rows["nobass.sloppak"]["bass_tuning_name"] == ""

tests/test_library_tuning_perspectives.py

@@ -0,0 +1,294 @@
+"""The three-valued tuning PERSPECTIVE, and "playable without retuning".
+
+Two behaviours that extend the bass tuning fix (see
+test_library_tuning_instrument.py):
+
+1. `active_instrument_profile` has three values (guitar-lead / guitar-rhythm /
+   bass), so the tuning perspective must too. Lead and rhythm charts can be
+   tuned differently, which is the identical bug a bassist hit, inside guitar.
+
+2. Exact tuning match answers "which tuning is this labelled". A player
+   actually wants "will this cost me a retune". Both are offered; exact stays
+   the default.
+
+Everything round-trips through the real extractor, the real scanner
+derivation, the real schema and the real HTTP surface.
+"""
+
+import importlib
+import sys
+
+import pytest
+import yaml
+from fastapi.testclient import TestClient
+
+from scan_worker import _extract_meta_for_file
+from tunings import (
+    PERSPECTIVES, bass_tuning_key, chart_is_playable_in, perspective_tuning_key,
+)
+
+
+@pytest.fixture()
+def server_mod(tmp_path, monkeypatch):
+    monkeypatch.setenv("CONFIG_DIR", str(tmp_path))
+    sys.modules.pop("server", None)
+    mod = importlib.import_module("server")
+    yield mod
+    conn = getattr(getattr(mod, "meta_db", None), "conn", None)
+    if conn is not None:
+        getattr(sys.modules.get("server"), "_join_background_db_threads", lambda: None)()
+        conn.close()
+
+
+@pytest.fixture()
+def client(server_mod):
+    c = TestClient(server_mod.app)
+    try:
+        yield c
+    finally:
+        c.close()
+
+
+def _pack(root, name, arrangements):
+    d = root / name
+    d.mkdir(parents=True)
+    (d / "manifest.yaml").write_text(yaml.safe_dump({
+        "title": name, "artist": "A", "duration": 100,
+        "arrangements": arrangements, "stems": [],
+    }), encoding="utf-8")
+    return d
+
+
+def _files(client, **kw):
+    return {s["filename"] for s in client.get("/api/library", params=kw).json()["songs"]}
+
+
+# ── 1. The same bug WITHIN guitar: lead vs rhythm ────────────────────────────
+
+def test_rhythm_chart_tuning_is_indexed_separately(tmp_path):
+    """A song whose LEAD is in E standard but whose RHYTHM is in Drop D must
+    index both — through the real extractor + scanner derivation."""
+    d = _pack(tmp_path, "split.sloppak", [
+        {"name": "Lead", "tuning": [0, 0, 0, 0, 0, 0]},
+        {"name": "Rhythm", "tuning": [-2, 0, 0, 0, 0, 0]},
+    ])
+    meta = _extract_meta_for_file(d)
+    assert meta["tuning_name"] == "E Standard"        # song-level = guitar-first
+    assert meta["rhythm_tuning_name"] == "Drop D"     # the rhythm chart's own
+    assert meta["rhythm_tuning_offsets"] == "-2 0 0 0 0 0"
+    assert meta["rhythm_tuning_low_pitch"] == 38      # low D
+
+
+def test_rhythm_offsets_are_not_truncated(tmp_path):
+    """Only BASS truncates (its arrays are padded). A 7-string guitar array is
+    real data — cutting it to 6 would invent a tuning the chart doesn't have."""
+    d = _pack(tmp_path, "seven.sloppak", [
+        {"name": "Rhythm", "tuning": [-2, -2, -2, -2, -2, -2, -2]},
+    ])
+    meta = _extract_meta_for_file(d)
+    assert meta["rhythm_tuning_offsets"] == "-2 -2 -2 -2 -2 -2 -2"
+
+
+def test_no_rhythm_arrangement_leaves_the_columns_empty(tmp_path):
+    d = _pack(tmp_path, "leadonly.sloppak", [{"name": "Lead", "tuning": [0] * 6}])
+    meta = _extract_meta_for_file(d)
+    assert meta["rhythm_tuning_name"] == ""
+    assert meta["rhythm_tuning_key"] == ""
+
+
+def _put(server_mod, fn, **kw):
+    base = dict(title=fn, artist="A", album="LP", year="2010", duration=200.0,
+                tuning="E Standard", arrangements=[], has_lyrics=False,
+                format="sloppak", stem_ids=[], tuning_name="E Standard",
+                tuning_sort_key=0, tuning_offsets="0 0 0 0 0 0",
+                tuning_low_pitch=40)
+    base.update(kw)
+    server_mod.meta_db.put(fn, 1.0, 1, base)
+
+
+@pytest.fixture()
+def rhythm_seeded(server_mod):
+    """Both songs are E Standard by LEAD. One has a Drop D rhythm chart; the
+    other has no rhythm chart at all (so it falls back + is marked inferred)."""
+    _put(server_mod, "rdiffer.sloppak",
+         rhythm_tuning_name="Drop D", rhythm_tuning_sort_key=-2,
+         rhythm_tuning_offsets="-2 0 0 0 0 0",
+         rhythm_tuning_key=perspective_tuning_key(
+             [-2, 0, 0, 0, 0, 0], PERSPECTIVES["guitar-rhythm"]),
+         rhythm_tuning_low_pitch=38)
+    _put(server_mod, "rnone.sloppak")
+
+
+def test_rhythm_filter_excludes_a_lead_only_tuning_match(client, rhythm_seeded):
+    """THE WITHIN-GUITAR BUG. Filtering rhythm "E Standard" must not return
+    rdiffer — that is its LEAD tuning; its rhythm chart is in Drop D."""
+    assert _files(client, tunings="E Standard") == {"rdiffer.sloppak", "rnone.sloppak"}
+    # rnone has no rhythm chart, so it falls back to its lead tuning and stays.
+    assert _files(client, tunings="E Standard", instrument="guitar-rhythm") == {
+        "rnone.sloppak"}
+    assert _files(client, tunings="Drop D", instrument="guitar-rhythm") == {
+        "rdiffer.sloppak"}
+    # …and Drop D finds nothing from the lead perspective.
+    assert _files(client, tunings="Drop D") == set()
+
+
+def test_rhythm_perspective_marks_inferred_rows(client, rhythm_seeded):
+    rows = {s["filename"]: s for s in client.get(
+        "/api/library", params={"instrument": "guitar-rhythm"}).json()["songs"]}
+    assert rows["rdiffer.sloppak"]["tuning_inferred"] is False
+    assert rows["rnone.sloppak"]["tuning_inferred"] is True
+    assert rows["rdiffer.sloppak"]["tuning_perspective"] == "guitar-rhythm"
+
+
+def test_rhythm_facet_reports_inferred_portion(client, rhythm_seeded):
+    rows = {t["name"]: t for t in client.get(
+        "/api/library/tuning-names",
+        params={"instrument": "guitar-rhythm"}).json()["tunings"]}
+    assert rows["Drop D"]["count"] == 1 and rows["Drop D"]["inferred_count"] == 0
+    assert rows["E Standard"]["count"] == 1 and rows["E Standard"]["inferred_count"] == 1
+
+
+def test_facet_row_selects_exactly_what_it_counted_for_rhythm(client, rhythm_seeded):
+    """The invariant that must hold for EVERY perspective."""
+    for row in client.get("/api/library/tuning-names",
+                          params={"instrument": "guitar-rhythm"}).json()["tunings"]:
+        got = _files(client, tunings=row["key"], instrument="guitar-rhythm")
+        assert len(got) == row["count"], row["key"]
+
+
+def test_guitar_lead_is_byte_identical_to_the_legacy_default(client, rhythm_seeded):
+    """The majority path must not regress: the default payload gains no keys,
+    and the legacy two-valued vocabulary still resolves to it."""
+    default = client.get("/api/library").json()
+    explicit = client.get("/api/library", params={"instrument": "guitar-lead"}).json()
+    legacy = client.get("/api/library", params={"instrument": "guitar"}).json()
+    assert default == explicit == legacy
+    row = default["songs"][0]
+    assert "tuning_inferred" not in row and "tuning_perspective" not in row
+
+
+def test_unknown_perspective_falls_back_to_lead(client, rhythm_seeded):
+    """An unrecognised value must never silently change filter semantics."""
+    assert client.get("/api/library", params={"instrument": "kazoo"}).json() == \
+        client.get("/api/library").json()
+
+
+def test_tuning_sort_respects_the_rhythm_perspective(client, rhythm_seeded):
+    """Sort is musical distance from standard. rdiffer is 0 away by lead but
+    -2 by rhythm, so the perspective changes its position."""
+    def order(**kw):
+        return [s["filename"] for s in client.get(
+            "/api/library", params={"sort": "tuning", **kw}).json()["songs"]]
+    assert order()[0] == "rdiffer.sloppak"                            # tie → filename
+    assert order(instrument="guitar-rhythm")[0] == "rnone.sloppak"    # 0 beats -2
+
+
+# ── 2. "Playable without retuning" ───────────────────────────────────────────
+
+@pytest.mark.parametrize("your_low,chart_low,expected", [
+    (23, 28, True),     # 5-string bass (low B) plays a 4-string standard chart
+    (23, 26, True),     # …and a drop-D chart: the low D is fretted on the B string
+    (28, 26, False),    # 4-string standard CANNOT reach a drop-D chart's low D
+    (28, 28, True),     # identical tuning
+    (40, 38, False),    # guitar standard vs a drop-D chart
+    (38, 40, True),     # a drop-D guitar covers a standard chart
+    (None, 28, False),  # unknown chart pitch is never claimed playable
+    (28, None, False),
+])
+def test_playability_rule(your_low, chart_low, expected):
+    """The core comparison as a property: your lowest open string vs the
+    chart's lowest required pitch. Unknown => not playable (conservative)."""
+    assert chart_is_playable_in(chart_low, your_low) is expected
+
+
+@pytest.fixture()
+def pitched(server_mod):
+    _put(server_mod, "std.sloppak", tuning_low_pitch=40)
+    _put(server_mod, "dropd.sloppak", tuning="Drop D", tuning_name="Drop D",
+         tuning_offsets="-2 0 0 0 0 0", tuning_sort_key=-2, tuning_low_pitch=38)
+    _put(server_mod, "dropc.sloppak", tuning="Drop C", tuning_name="Drop C",
+         tuning_offsets="-4 -2 -2 -2 -2 -2", tuning_sort_key=-14, tuning_low_pitch=36)
+
+
+def _playable(client, offsets, instrument="guitar", sc=6, **kw):
+    return {s["filename"] for s in client.get("/api/library", params={
+        "tuning_match": "playable", "playable_offsets": offsets,
+        "playable_instrument": instrument, "playable_string_count": str(sc), **kw,
+    }).json()["songs"]}
+
+
+def test_playable_from_standard_excludes_lower_tuned_charts(client, pitched):
+    """In E standard you can play the standard chart, but the drop-D and
+    drop-C charts need a retune — exactly what the tester wants surfaced."""
+    assert _playable(client, "0,0,0,0,0,0") == {"std.sloppak"}
+
+
+def test_playable_from_drop_c_covers_everything_above_it(client, pitched):
+    """Tuned DOWN to drop C, every higher-tuned chart is reachable by fretting
+    — the dominant real case this feature exists for."""
+    assert _playable(client, "-4,-2,-2,-2,-2,-2") == {
+        "std.sloppak", "dropd.sloppak", "dropc.sloppak"}
+
+
+def test_playable_is_a_mode_not_a_replacement_for_exact(client, pitched):
+    """Exact match still works untouched, and returns something DIFFERENT from
+    playable — they answer different questions."""
+    exact = {s["filename"] for s in client.get(
+        "/api/library", params={"tunings": "Drop D"}).json()["songs"]}
+    assert exact == {"dropd.sloppak"}
+    assert _playable(client, "-2,0,0,0,0,0") == {"std.sloppak", "dropd.sloppak"}
+
+
+def test_playable_excludes_rows_with_no_indexed_pitch(client, server_mod, pitched):
+    """Conservative by construction: a chart whose low pitch we could not
+    compute is EXCLUDED, never assumed playable. Wrongly claiming playability
+    costs a mid-practice retune — the failure this feature prevents."""
+    _put(server_mod, "unknown.sloppak", tuning_low_pitch=None)
+    assert "unknown.sloppak" not in _playable(client, "-4,-2,-2,-2,-2,-2")
+    # …but it is still reachable normally, so it isn't lost from the library.
+    assert any(s["filename"] == "unknown.sloppak"
+               for s in client.get("/api/library").json()["songs"])
+
+
+def test_malformed_playable_tuning_applies_no_filter(client, pitched):
+    """A tuning we cannot resolve must not silently claim everything is
+    playable OR that nothing is — it applies no filter at all."""
+    everything = {s["filename"] for s in client.get("/api/library").json()["songs"]}
+    assert _playable(client, "not,a,tuning") == everything
+    assert _playable(client, "") == everything
+    # A string count that disagrees with the offsets is equally unusable.
+    assert _playable(client, "0,0,0,0", instrument="guitar", sc=6) == everything
+
+
+def test_playable_respects_the_bass_perspective(client, server_mod):
+    """A 5-string bass (low B) can play a 4-string standard bass chart. The
+    comparison must run on the BASS tuning — this song's GUITAR chart is tuned
+    far lower, so reading the wrong column would flip the answer."""
+    _put(server_mod, "bassy.sloppak",
+         tuning="Custom Tuning", tuning_name="Custom Tuning",
+         tuning_offsets="-4 -2 -2 -1 -2 0", tuning_sort_key=-11,
+         tuning_low_pitch=36,
+         bass_tuning_name="E Standard", bass_tuning_sort_key=0,
+         bass_tuning_offsets="0 0 0 0",
+         bass_tuning_key=bass_tuning_key([0, 0, 0, 0]),
+         bass_tuning_low_pitch=28)
+    # 5-string bass low B (23) <= the chart low E (28) → playable.
+    got = {s["filename"] for s in client.get("/api/library", params={
+        "tuning_match": "playable", "playable_offsets": "0,0,0,0,0",
+        "playable_instrument": "bass", "playable_string_count": "5",
+        "instrument": "bass"}).json()["songs"]}
+    assert got == {"bassy.sloppak"}
+    # A 4-string bass tuned UP a semitone (low F, 29) cannot reach the low E.
+    got_up = {s["filename"] for s in client.get("/api/library", params={
+        "tuning_match": "playable", "playable_offsets": "1,1,1,1",
+        "playable_instrument": "bass", "playable_string_count": "4",
+        "instrument": "bass"}).json()["songs"]}
+    assert got_up == set()
+
+
+def test_playable_and_stats_agree(client, pitched):
+    """The count surface must apply the same predicate as the grid."""
+    body = client.get("/api/library/stats", params={
+        "tuning_match": "playable", "playable_offsets": "0,0,0,0,0,0",
+        "playable_instrument": "guitar", "playable_string_count": "6"}).json()
+    assert body["total_songs"] == 1

tests/test_loosefolder.py

@@ -302,3 +302,44 @@ def test_extract_meta_uses_lead_tuning_when_bass_sorts_first(tmp_path):
 
     meta = loosefolder.extract_meta(tmp_path)
     assert meta["tuning_offsets"] == [0, 0, 0, 0, 0, 0]
+    # …and the bass chart's OWN tuning is indexed alongside it, so a bass
+    # player's library filter isn't answered with the guitar tuning.
+    assert meta["bass_tuning_offsets"] == [-4, -4, -4, -4, 0, 0]
+
+
+def test_extract_meta_bass_tuning_absent_without_bass_arrangement(tmp_path):
+    """A folder with no bass chart leaves the bass tuning EMPTY (None) rather
+    than echoing the guitar tuning — the library then falls back explicitly,
+    and 'no bass part' stays distinguishable from 'bass part in E Standard'."""
+    (tmp_path / "audio.wem").write_bytes(b"\0")
+    (tmp_path / "lead.xml").write_text(_LEAD_STD_XML, encoding="utf-8")
+
+    meta = loosefolder.extract_meta(tmp_path)
+    assert meta["tuning_offsets"] == [0, 0, 0, 0, 0, 0]
+    assert meta["bass_tuning_offsets"] is None
+
+
+def test_extract_meta_bass_tuning_matches_guitar_is_still_indexed(tmp_path):
+    """The COMMON case: bass and guitar in the same tuning. The bass column
+    must still be populated — an empty one would be read as 'no bass chart'."""
+    (tmp_path / "audio.wem").write_bytes(b"\0")
+    _write_min_xml(tmp_path / "lead.xml", arrangement="Lead")
+    _write_min_xml(tmp_path / "bass.xml", arrangement="Bass")
+
+    meta = loosefolder.extract_meta(tmp_path)
+    assert meta["bass_tuning_offsets"] == [0, 0, 0, 0, 0, 0]
+
+
+def test_extract_meta_manifest_tuning_does_not_become_the_bass_tuning(tmp_path):
+    """A manifest `tuning_offsets` overrides the SONG tuning but says nothing
+    about which chart it describes, so it must never be mistaken for the bass
+    part's tuning — with no bass chart the bass column stays empty."""
+    (tmp_path / "audio.wem").write_bytes(b"\0")
+    (tmp_path / "lead.xml").write_text(_LEAD_STD_XML, encoding="utf-8")
+    (tmp_path / "manifest.json").write_text(json.dumps({
+        "tuning_offsets": [-2, -2, -2, -2, -2, -2],
+    }), encoding="utf-8")
+
+    meta = loosefolder.extract_meta(tmp_path)
+    assert meta["tuning_offsets"] == [-2, -2, -2, -2, -2, -2]
+    assert meta["bass_tuning_offsets"] is None

tests/test_lyrics_transcribe_remote.py

@@ -0,0 +1,201 @@
+"""The remote transcription REQUEST — the thing that was never tested and never worked.
+
+`transcribe_vocals_remote()` POSTed the vocal stem to `/align`. That endpoint is *forced
+alignment*: "here are the lyrics, tell me when each word is sung". Its `text` field is required,
+and we have no lyrics — transcribing them is the entire point. So the server rejected every
+request with a 422 from FastAPI's validation layer, before its handler ever ran, and remote
+transcription had never worked for anybody (feedBack-plugin-stem-splitter#17).
+
+Nothing caught it because every test of this module tested the *mapper* — `_whisperx_to_sloppak`,
+fed a hand-written dict. The mapper was always fine. The request was never exercised, and the
+request was the bug.
+
+So these tests assert the request: which endpoint, and how `language` is carried. Both are
+invisible to a mapper test, and both are wrong in ways that fail quietly rather than loudly.
+"""
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from lyrics_transcribe import transcribe_vocals_remote
+
+_ALIGNED = {
+    "segments": [{
+        "start": 1.0, "end": 2.0, "text": "hello world",
+        "words": [
+            {"word": "hello", "start": 1.0, "end": 1.4, "score": 0.9},
+            {"word": "world", "start": 1.5, "end": 2.0, "score": 0.9},
+        ],
+    }]
+}
+
+
+class _Resp:
+    def __init__(self, status=200, payload=None, text=""):
+        self.status_code = status
+        self._payload = payload if payload is not None else _ALIGNED
+        self.text = text
+
+    def json(self):
+        return self._payload
+
+
+@pytest.fixture
+def vocals(tmp_path: Path) -> Path:
+    p = tmp_path / "vocals.ogg"
+    p.write_bytes(b"not really ogg, we never decode it here")
+    return p
+
+
+def _post_call(vocals: Path, resp: _Resp, **kw):
+    with mock.patch("requests.post", return_value=resp) as post:
+        out = transcribe_vocals_remote(vocals, "http://server:7865", **kw)
+    return post.call_args, out
+
+
+def test_it_posts_to_transcribe_not_align(vocals):
+    """THE regression. /align requires `text`; we have none, so it 422s every time."""
+    call, out = _post_call(vocals, _Resp())
+
+    url = call.args[0]
+    assert url.endswith("/transcribe"), (
+        f"posted to {url!r} — /align is forced alignment and its `text` field is required, so "
+        f"this request is rejected with a 422 before the server's handler ever runs"
+    )
+    assert "/align" not in url
+    assert out, "a successful transcription must return syllables"
+
+
+def test_the_language_hint_is_a_form_field_not_a_query_param(vocals):
+    """The server reads `language` with Form(""). Sent as a query param it is silently ignored —
+    so an explicit hint does nothing, Whisper's auto-detection quietly decides instead, and the
+    wrong wav2vec2 aligner gets loaded. It "works", it's just wrong: the failure mode that hides
+    for months."""
+    call, _ = _post_call(vocals, _Resp(), language="es")
+
+    assert (call.kwargs.get("data") or {}).get("language") == "es", (
+        "the language hint must ride in the form body — the server reads Form('language'), and "
+        "a query param is dropped without a word"
+    )
+    assert "language" not in (call.kwargs.get("params") or {})
+
+
+def test_no_language_sends_no_hint(vocals):
+    # Absent is not the empty string: "" would pin detection to a language named "".
+    call, _ = _post_call(vocals, _Resp())
+    assert not (call.kwargs.get("data") or {})
+
+
+def test_the_file_is_sent_as_a_multipart_upload(vocals):
+    call, _ = _post_call(vocals, _Resp())
+    files = call.kwargs.get("files") or {}
+    assert "file" in files, "the server reads File('file')"
+    assert files["file"][0] == "vocals.ogg"
+
+
+def test_an_api_key_is_sent_as_a_bearer_token(vocals):
+    call, _ = _post_call(vocals, _Resp(), api_key="secret")
+    assert (call.kwargs.get("headers") or {})["Authorization"] == "Bearer secret"
+
+
+def test_an_instrumental_is_an_answer_not_a_crash(vocals):
+    # The server returns 200 + no segments for a stem with no singing in it. That is a valid
+    # answer ("this song has no vocals"), and it must not read as a failure.
+    _, out = _post_call(vocals, _Resp(payload={"segments": [], "language": "en"}))
+    assert out == []
+
+
+def test_a_server_error_surfaces_the_whole_body(vocals):
+    """The error body IS the diagnosis. A 422's JSON names the field it rejected; a 500's
+    traceback answers on its last line. The old 300-char cap decapitated both — which is how
+    this bug stayed invisible: the message explaining it was inside the part that got cut."""
+    tb = "Traceback (most recent call last):\n" + ("  File x, line 1\n" * 40) + \
+         "RuntimeError: CUDA out of memory"
+    assert len(tb) > 300 and "CUDA out of memory" not in tb[:300]
+
+    with pytest.raises(RuntimeError) as exc:
+        _post_call(vocals, _Resp(status=500, text=tb))
+    assert "CUDA out of memory" in str(exc.value)
+
+
+def test_truncation_keeps_the_exception_line_not_just_the_header():
+    """A traceback's ANSWER is its last line. Head-only truncation throws it away.
+
+    This is the same mistake as the 300-char cap, one level up: cutting off precisely the part
+    the function exists to preserve. A 4000-char window that contains "Traceback (most recent
+    call last)" and none of the exception is a window onto nothing."""
+    from lyrics_transcribe import _MAX_ERR_BODY, _err_body
+
+    frames = "".join(f'  File "/app/server.py", line {i}, in run\n    step()\n'
+                     for i in range(2000))          # far over the cap on its own
+    tb = "Traceback (most recent call last):\n" + frames + \
+         "RuntimeError: CUDA out of memory. Tried to allocate 2.20 GiB"
+
+    body = _err_body(_Resp(text=tb))
+    assert len(body) <= _MAX_ERR_BODY
+    assert "CUDA out of memory" in body, (
+        "the exception line is the diagnosis — a truncation that drops it keeps the part that "
+        "says work was happening and discards the part that says what went wrong"
+    )
+    assert "Traceback (most recent call last)" in body, "the head is context worth keeping too"
+    assert "truncated" in body
+
+
+def test_the_cap_is_a_bound_not_a_suggestion():
+    """The truncation marker must fit INSIDE _MAX_ERR_BODY, not be appended past it.
+
+    Otherwise the cap is advisory, and the callers who trust it — a log line, a job record
+    persisted to disk and re-read on every load — are the ones that get surprised."""
+    from lyrics_transcribe import _MAX_ERR_BODY, _err_body
+
+    body = _err_body(_Resp(text="x" * 500_000))
+    assert len(body) <= _MAX_ERR_BODY, (
+        f"body is {len(body)} chars, over the {_MAX_ERR_BODY} cap it claims to enforce"
+    )
+    assert "truncated" in body and "500000" in body
+
+
+def test_trailing_whitespace_is_not_content():
+    # A 300-char JSON body followed by 3900 blanks is not a long body, and cutting real content
+    # to make room for whitespace would be a silly way to lose the diagnosis.
+    from lyrics_transcribe import _err_body
+
+    payload = '{"detail":"nope"}'
+    assert _err_body(_Resp(text=payload + " " * 8000)) == payload
+
+
+def test_a_404_explains_that_the_server_is_too_old(vocals):
+    """A bare "404" sends someone hunting for a typo in their URL. The real answer is that their
+    server predates the endpoint, and only we can know that."""
+    with pytest.raises(RuntimeError) as exc:
+        _post_call(vocals, _Resp(status=404, text='{"detail":"Not Found"}'))
+    msg = str(exc.value)
+    assert "404" in msg
+    assert "/transcribe" in msg
+    assert "predates" in msg or "Update the server" in msg
+
+
+class TestEverythingFailsAsRuntimeError:
+    """The docstring promises one failure mode: RuntimeError. The caller
+    (`_maybe_transcribe_lyrics`) catches exactly that so one song's failed lyrics don't take down
+    the batch around it. A transport error escaping as requests.RequestException walks straight
+    past that handler — turning "this song's lyrics failed" into "the whole batch died"."""
+
+    def test_a_connection_failure(self, vocals):
+        import requests
+        with mock.patch("requests.post",
+                        side_effect=requests.ConnectionError("name resolution failed")):
+            with pytest.raises(RuntimeError, match="could not reach"):
+                transcribe_vocals_remote(vocals, "http://nope:7865")
+
+    def test_a_timeout(self, vocals):
+        import requests
+        with mock.patch("requests.post", side_effect=requests.Timeout("timed out")):
+            with pytest.raises(RuntimeError, match="could not reach"):
+                transcribe_vocals_remote(vocals, "http://server:7865")
+
+    def test_an_unreadable_stem(self, tmp_path):
+        missing = tmp_path / "gone.ogg"      # never created
+        with pytest.raises(RuntimeError, match="could not read"):
+            transcribe_vocals_remote(missing, "http://server:7865")

tests/test_resolved_root_cache.py

@@ -0,0 +1,103 @@
+"""The library root must be resolved ONCE, not on every path check.
+
+`Path.resolve()` lstats every component of a path. `_resolve_dlc_path` and
+`safe_join` run once per song / art fetch / scanned row, and both used to
+re-resolve their root every single call.
+
+Measured on a real 50,944-song library sitting on an NTFS-3G (FUSE) mount:
+~23,500 stat/lstat calls per second, re-walking the same three parent
+directories, pinning a core of the server. Every stat crosses into userspace on
+FUSE, so the constant re-resolution — not the work itself — was the cost.
+
+These tests pin the fix (root resolved once) AND that caching it did not weaken
+containment, which is the thing that matters: `safe_join` is the zip-slip guard.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from dlc_paths import _resolve_dlc_path
+from safepath import resolved_root, safe_join
+
+
+@pytest.fixture(autouse=True)
+def _clear_cache():
+    resolved_root.cache_clear()
+    yield
+    resolved_root.cache_clear()
+
+
+def test_dlc_root_is_resolved_once_across_many_lookups(tmp_path):
+    """The regression: 500 lookups must not mean 500 root resolutions."""
+    (tmp_path / "a.feedpak").write_bytes(b"x")
+
+    for i in range(500):
+        assert _resolve_dlc_path(tmp_path, f"song{i}.feedpak") is not None
+
+    info = resolved_root.cache_info()
+    assert info.misses == 1, (
+        f"the library root must be resolved ONCE, not per call "
+        f"(got {info.misses} resolutions for 500 lookups)"
+    )
+    assert info.hits == 499
+
+
+def test_safe_join_resolves_its_root_once_too(tmp_path):
+    for i in range(200):
+        assert safe_join(tmp_path, f"asset{i}.png") is not None
+    assert resolved_root.cache_info().misses == 1
+
+
+def test_a_different_root_is_a_different_cache_entry(tmp_path):
+    other = tmp_path / "other"
+    other.mkdir()
+    _resolve_dlc_path(tmp_path, "a.feedpak")
+    _resolve_dlc_path(other, "a.feedpak")
+    assert resolved_root.cache_info().misses == 2, "switching library dir must re-resolve"
+
+
+# ── containment must be unchanged (the part that matters) ───────────────────
+
+@pytest.mark.parametrize("evil", [
+    "../etc/passwd",
+    "..\\etc\\passwd",
+    "a/../../etc/passwd",
+    "/etc/passwd",
+    "C:/Windows/system.ini",
+    "",
+])
+def test_resolve_dlc_path_still_rejects_escapes(tmp_path, evil):
+    assert _resolve_dlc_path(tmp_path, evil) is None
+
+
+@pytest.mark.parametrize("evil", [
+    "../outside.txt",
+    "..\\outside.txt",
+    "a/../../outside.txt",
+    "",
+])
+def test_safe_join_still_rejects_escapes(tmp_path, evil):
+    assert safe_join(tmp_path, evil) is None
+
+
+def test_safe_join_still_follows_symlinks_out(tmp_path):
+    """safe_join's candidate resolution is the zip-slip defence and is NOT cached:
+    a symlink pointing outside the root must still be refused."""
+    outside = tmp_path.parent / "outside_secret"
+    outside.mkdir(exist_ok=True)
+    (outside / "secret.txt").write_text("x")
+
+    root = tmp_path / "root"
+    root.mkdir()
+    (root / "escape").symlink_to(outside)
+
+    assert safe_join(root, "escape/secret.txt") is None, (
+        "a symlink escaping the root must still be rejected — caching the ROOT "
+        "must not disable resolution of the CANDIDATE"
+    )
+
+
+def test_in_library_paths_still_resolve(tmp_path):
+    assert _resolve_dlc_path(tmp_path, "sub/song.feedpak") == tmp_path / "sub" / "song.feedpak"
+    assert safe_join(tmp_path, "art/cover.png") == (tmp_path / "art" / "cover.png").resolve()

tests/test_song_info_stems.py

@@ -0,0 +1,140 @@
+"""`/api/song/{f}?stems=1` — the playable stem list, for preloading.
+
+The stems plugin could only learn its stem list from the highway's WS `ready`,
+which arrives once the highway is already up. So it decoded the stems and then
+copied the whole song's PCM to its audio worklet with the player on screen —
+half a gigabyte of memcpy in one frame, ~700 ms, which froze the venue video.
+
+Given the list at `song:loading` it can do all of that BEFORE the highway
+appears, behind the loading overlay where a stall costs nothing.
+
+The safety property these tests exist for: the REST payload must be the SAME
+list the WS builds. If they disagree, the plugin preloads one graph and then
+throws it away and rebuilds another — strictly worse than not preloading. So
+they are pinned against each other, not just against a snapshot.
+"""
+
+import zipfile
+
+import yaml
+
+import sloppak
+
+
+def _pak(tmp_path, stems, full=None, name="song.feedpak", original_audio=None):
+    manifest = {
+        "title": "T", "artist": "A", "duration": 10.0,
+        "arrangements": [],
+        "stems": stems + ([full] if full else []),
+    }
+    if original_audio:
+        # The deprecated pre-1.15.0 shape: the mixdown lives outside `stems`.
+        manifest["original_audio"] = original_audio
+    p = tmp_path / name
+    with zipfile.ZipFile(p, "w") as z:
+        # Real packs carry manifest.yaml — a JSON manifest is not read at all.
+        z.writestr("manifest.yaml", yaml.safe_dump(manifest))
+        # _legacy_full_mix only returns a path that actually EXISTS on disk.
+        if original_audio:
+            z.writestr(original_audio, b"\0" * 16)
+    return p
+
+
+def _payload(tmp_path, pak):
+    from routers.song import _playable_stems_payload
+    import appstate
+    cache = tmp_path / "cache"
+    cache.mkdir(exist_ok=True)
+    appstate.sloppak_cache_dir = cache
+    return _playable_stems_payload(pak.name, tmp_path)
+
+
+def _ws_payload(tmp_path, pak):
+    """Rebuild the WS `ready` stems payload exactly as ws_highway.py does."""
+    from urllib.parse import quote
+    cache = tmp_path / "cache"
+    cache.mkdir(exist_ok=True)
+    loaded = sloppak.load_song(pak.name, tmp_path, cache)
+    q = quote(pak.name, safe="")
+    return {
+        "stems": [
+            {"id": s["id"], "url": f"/api/sloppak/{q}/file/{quote(s['file'])}",
+             "default": s["default"]}
+            for s in loaded.stems
+        ],
+        "full_mix_url": f"/api/sloppak/{q}/file/{quote(loaded.full_mix)}" if loaded.full_mix else None,
+    }
+
+
+def test_default_resolution_is_shared_with_load_song():
+    assert sloppak.stem_default_on(True) is True
+    assert sloppak.stem_default_on(False) is False
+    assert sloppak.stem_default_on("off") is False
+    assert sloppak.stem_default_on("false") is False
+    assert sloppak.stem_default_on("0") is False
+    assert sloppak.stem_default_on("no") is False
+    assert sloppak.stem_default_on("on") is True
+    assert sloppak.stem_default_on(1) is True
+
+
+def test_rest_matches_the_ws_for_a_reserved_full_stem(tmp_path):
+    pak = _pak(tmp_path,
+               [{"id": "guitar", "file": "stems/guitar.ogg"},
+                {"id": "vocals", "file": "stems/vocals.ogg", "default": "off"}],
+               full={"id": "full", "file": "stems/full.ogg"},
+               name="Iron Maiden - Phantom.feedpak")
+    rest = _payload(tmp_path, pak)
+    assert rest == _ws_payload(tmp_path, pak)
+    assert [s["id"] for s in rest["stems"]] == ["guitar", "vocals"], "the mixdown is not a layer"
+    assert rest["full_mix_url"].endswith("stems/full.ogg")
+    assert rest["stems"][1]["default"] is False
+
+
+def test_rest_matches_the_ws_for_a_LEGACY_original_audio_pack(tmp_path):
+    """The one CodeRabbit caught, and the one that matters most in practice.
+
+    load_song falls back to the DEPRECATED `original_audio:` key when a pack has
+    no reserved `full` stem — which is every pack written before feedpak 1.15.0,
+    i.e. most of a real library. My first version of this payload reimplemented
+    the full-mix rule from extract_meta and silently returned None for them: REST
+    would say "no full mix" while the WS said there was one. The plugin would then
+    preload a graph WITHOUT the pristine mix and, because the signature still
+    matched, never rebuild — unity playback silently downgraded to the lossy
+    recombination.
+
+    The payload now calls load_song itself, so this cannot drift. Pinned anyway.
+    """
+    pak = _pak(tmp_path, [
+        {"id": "guitar", "file": "stems/guitar.ogg"},
+        {"id": "bass", "file": "stems/bass.ogg"},
+    ], name="Legacy Pack.feedpak", original_audio="original/full.ogg")
+
+    rest = _payload(tmp_path, pak)
+    assert rest == _ws_payload(tmp_path, pak)
+    assert rest["full_mix_url"] is not None, (
+        "a pre-1.15.0 pack's full mix must survive — dropping it downgrades unity "
+        "playback to the lossy stem recombination, silently"
+    )
+    assert rest["full_mix_url"].endswith("original/full.ogg")
+
+
+def test_rest_matches_the_ws_for_a_single_full_pack(tmp_path):
+    # Its ONE stem IS the mixdown: nothing to be pristine against, so `full` stays
+    # the sole playable stem and no separate mixdown is surfaced.
+    pak = _pak(tmp_path, [{"id": "full", "file": "stems/full.ogg"}], name="Single.feedpak")
+    rest = _payload(tmp_path, pak)
+    assert rest == _ws_payload(tmp_path, pak)
+    assert [s["id"] for s in rest["stems"]] == ["full"]
+    assert rest["full_mix_url"] is None
+
+
+def test_a_broken_pack_yields_an_empty_list_not_an_error(tmp_path):
+    # Preloading is an optimisation: an unreadable pack must fall back to the
+    # normal WS-driven path, never break the song-info request.
+    from routers.song import _playable_stems_payload
+    import appstate
+    cache = tmp_path / "cache"
+    cache.mkdir()
+    appstate.sloppak_cache_dir = cache
+    (tmp_path / "bad.feedpak").write_bytes(b"not a zip")
+    assert _playable_stems_payload("bad.feedpak", tmp_path) == {"stems": [], "full_mix_url": None}

tests/test_tunings.py

@@ -4,10 +4,15 @@ import pytest
 
 from tunings import (
     DEFAULT_TUNINGS,
+    PERSPECTIVES,
     TUNING_PRESET_MIDIS,
     _valid_tuning_for_key,
     apply_flat_instrument_patch_to_profiles,
+    normalize_offsets,
     open_midis_to_freqs,
+    perspective_low_pitch,
+    perspective_tuning_key,
+    perspective_tuning_name,
     settings_with_instrument_profiles,
     tuning_midis_from_offsets,
     tuning_name,
@@ -214,7 +219,11 @@ def test_settings_profiles_migrate_legacy_flat_bass_selection():
     })
     assert settings["active_instrument_profile"] == "bass"
     assert settings["instrument_profiles"]["bass"]["string_count"] == 6
-    assert settings["instrument_profiles"]["bass"]["tuning"] == "C Standard"
+    # The legacy 6-string-bass name migrates to the corrected one: the
+    # pitches [19,24,29,34,39,44] sound lowest G, and extended-range bass is
+    # named off its actual lowest string. Same tuning, right label — and the
+    # alias is what keeps this profile VALID rather than rejected.
+    assert settings["instrument_profiles"]["bass"]["tuning"] == "G Standard"
     assert settings["reference_pitch"] == 432
     assert settings["pathway"] == "practice"
     assert settings["instrument_profiles"]["bass"]["pathway"] == "practice"
@@ -279,3 +288,97 @@ def test_freqs_to_midis_rejects_garbage():
     assert freqs_to_midis([float("inf")]) is None      # non-finite
     assert freqs_to_midis([float("-inf")]) is None     # non-finite
     assert freqs_to_midis([]) == []                    # vacuously fine
+
+
+# ── Extended-range BASS naming (feedBack: 6-string bass read as guitar) ──────
+# A 6-string bass has SIX offsets exactly like a 6-string guitar, but its
+# lowest string is B, not E. `tuning_name` gated its guitar ladder on
+# `len(offsets) == 6` alone, so a bass got guitar names: an all-zeros bass
+# read "E Standard" (it is Standard/B) and a whole-step-down bass read
+# "D Standard" (it is A Standard). Reported from a real Sleep Token chart
+# tuned A0 D1 G1 C2 F2 A#2; the player called it A standard and was right.
+# Convention (bass- and guitar-pedagogy seats, 2026-07-18): name extended
+# range by the ACTUAL lowest string, matching the 7-string guitar presets.
+
+def test_bass_perspective_keeps_proven_six_string_tuning_but_truncates_padding():
+    bass = PERSPECTIVES["bass"]
+
+    # Legacy four-string Rocksmith data pads its unused tail with zeroes.
+    assert normalize_offsets([-2, -2, -2, -2, 0, 0], bass) == [-2] * 4
+
+    # A uniform non-zero six-string tuning cannot be that padding shape.
+    extended = normalize_offsets([-2] * 6, bass)
+    assert extended == [-2] * 6
+    assert perspective_tuning_name(extended, bass) == "A Standard"
+    assert perspective_tuning_key(extended, bass) == "bass:21:26:31:36:41:46"
+    assert perspective_low_pitch(extended, bass) == 21
+
+
+BASS_STANDARD_CASES = [
+    # 4-string bass is E-A-D-G — the guitar ladder's low four, names unchanged.
+    ([0, 0, 0, 0], "E Standard"),
+    ([-1, -1, -1, -1], "Eb Standard"),
+    ([-2, -2, -2, -2], "D Standard"),
+    # 5-string adds a low B → the B ladder.
+    ([0] * 5, "Standard"),
+    ([-1] * 5, "Bb Standard"),
+    ([-2] * 5, "A Standard"),
+    ([-3] * 5, "G# Standard"),
+    ([-4] * 5, "G Standard"),
+    # 6-string: same names, extra top string.
+    ([0] * 6, "Standard"),
+    ([-1] * 6, "Bb Standard"),
+    ([-2] * 6, "A Standard"),
+    ([-3] * 6, "G# Standard"),
+    ([-4] * 6, "G Standard"),
+]
+
+
+@pytest.mark.parametrize("offsets,expected", BASS_STANDARD_CASES)
+def test_bass_standard_tunings(offsets, expected):
+    assert tuning_name(offsets, is_bass=True) == expected
+
+
+def test_six_offsets_alone_do_not_imply_a_guitar():
+    """The regression the bug report came from."""
+    sleep_token = [-2] * 6           # A0 D1 G1 C2 F2 A#2
+    assert tuning_name(sleep_token, is_bass=True) == "A Standard"
+    # ...and the identical offsets on a guitar keep the guitar name.
+    assert tuning_name(sleep_token) == "D Standard"
+    # A STANDARD 6-string bass is not "E Standard" either.
+    assert tuning_name([0] * 6, is_bass=True) == "Standard"
+    assert tuning_name([0] * 6) == "E Standard"
+
+
+def test_bass_drop_tunings_name_the_resulting_low_string():
+    # 5-string B standard, low string dropped a whole step → A.
+    assert tuning_name([-2, 0, 0, 0, 0], is_bass=True) == "Drop A"
+    # 4-string E standard → D.
+    assert tuning_name([-2, 0, 0, 0], is_bass=True) == "Drop D"
+
+
+def test_bass_presets_are_named_off_their_lowest_string():
+    """Every bass preset's name must match the note its low string sounds."""
+    names = ["C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"]
+    alt = {"Ab": "G#", "G#": "Ab", "Bb": "A#", "A#": "Bb", "Eb": "D#", "D#": "Eb"}
+    for key in ("bass-4", "bass-5", "bass-6"):
+        for name, midis in TUNING_PRESET_MIDIS[key].items():
+            if not name.endswith("Standard") or name == "Standard":
+                continue
+            root = name.rsplit(" ", 1)[0]
+            low = names[midis[0] % 12]
+            assert root in (low, alt.get(low)), (
+                f"{key} {name!r} lowest string sounds {low}"
+            )
+
+
+def test_superseded_bass_names_migrate_instead_of_being_rejected():
+    """Renaming must not invalidate saved profiles (both pedagogy seats)."""
+    for key in ("bass-5", "bass-6"):
+        assert _valid_tuning_for_key(key, "D Standard") == "A Standard"
+        assert _valid_tuning_for_key(key, "C Standard") == "G Standard"
+        # Current names still pass straight through.
+        assert _valid_tuning_for_key(key, "A Standard") == "A Standard"
+    # The rename must not leak into other instruments.
+    assert _valid_tuning_for_key("guitar-6", "D Standard") == "D Standard"
+    assert _valid_tuning_for_key("bass-4", "D Standard") == "D Standard"