feat(v3): flag library songs by working-tuning match (working-tuning PR 6) (#668)

* feat(v3): flag library songs by working-tuning match (working-tuning PR 6)

Each song's tuning chip in the v3 library grid is now coloured by whether your
CURRENT working tuning covers it: green = play it now, amber = needs a retune
(with a matching tooltip). Uses the tuner plugin's coverageReport (async), so it
runs as a post-paint decoration pass — chips render instantly, then colour a tick
later; a token cancels a superseded pass so scrolling stays snappy. Re-flags on
working-tuning-changed (retune / instrument swap / reset), no re-fetch.

Fully feature-detected: without the tuner coverage API + the host workingTuning
state, the chips render exactly as before. v3-only, single file (static/v3/songs.js).

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

* fix(tuner/library): correct bass matching + memoize player tuning (PR #668 review)

Review fixes for working-tuning PR 6 (library tuning-match chips):

- Bass songs were scored against the guitar tuning. The chip passed no arrangement
  to coverageReport, so isBassArrangement fell back to guitar — a 4-string bass
  drop-D read as guitar could FALSE-MATCH a drop-D guitar player (green). songCard
  now flags a bass-only song (every arrangement name matches /\bbass\b/) with
  data-tuning-bass, and decorateTuningChips passes arrangement 'Bass'/'Lead' so
  coverage uses the right base pitches. Mixed guitar+bass songs → guitar (the
  song-level tuning is the guitar one); least-wrong given one tuning per song.

- Per-chip /api/settings fetch storm. coverageReport()→_playerTuning() fetched
  /api/settings once per visible chip per grid paint (~60). _playerTuning is now
  memoized (the player's tuning is song-independent) so all callers share one read;
  invalidated on instrument:changed / working-tuning-changed, with a 3s TTL so a
  settings write that doesn't emit an event still heals. A transient fetch failure
  is NOT cached (next read retries) — else one hiccup would freeze coverage.

Tests: player tuning shared across songs (one fetch); transient-failure retry
(fails without the fix). The prior #680 dedup test updated for the memoized behavior.

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

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: byrongamatos <xasiklas@gmail.com>

plugins/tuner/screen.js

@@ -189,7 +189,32 @@
         return { isBass, sc, key: (isBass ? 'bass' : 'guitar') + '-' + sc };
     }
 
-    async function _playerTuning() {
+    // Memoize the player's tuning: it depends only on /api/settings + the working
+    // tuning, which change on instrument:changed / working-tuning-changed (NOT per song).
+    // Without this, a consumer that evaluates coverage for many items at once — the
+    // library's per-song tuning-match chips — would fire one /api/settings fetch PER item
+    // per paint. Cache the promise so they all share one read; invalidate on the events
+    // that change the answer, AND expire after a short TTL so a settings write that
+    // doesn't emit an event (e.g. the input-setup flow) still heals within seconds.
+    let _playerTuningPromise = null;
+    let _playerTuningAt = 0;
+    const _PLAYER_TUNING_TTL_MS = 3000;
+    function _playerTuning() {
+        const now = (typeof Date !== 'undefined' && Date.now) ? Date.now() : 0;
+        if (!_playerTuningPromise || (now - _playerTuningAt) > _PLAYER_TUNING_TTL_MS) {
+            _playerTuningAt = now;
+            const p = _computePlayerTuning();
+            _playerTuningPromise = p;
+            // Never pin a transient failure: if the read yields null (or rejects), drop
+            // the cache so the next call retries. A real result stays until invalidation/TTL.
+            p.then((r) => { if (r == null && _playerTuningPromise === p) _playerTuningPromise = null; },
+                () => { if (_playerTuningPromise === p) _playerTuningPromise = null; });
+        }
+        return _playerTuningPromise;
+    }
+    function _invalidatePlayerTuning() { _playerTuningPromise = null; }
+
+    async function _computePlayerTuning() {
         const u = window._tunerUtils;
         if (!u) return null;
         // Instrument IDENTITY (which instrument is selected) + the static fallback
@@ -408,10 +433,12 @@
         // switches instrument. Drop the cached selection so a publish-on-clear can't write
         // to the previously-selected instrument's slot; the next coverage read re-resolves
         // it. Until then _publishWorkingTuning skips (safe — no mis-slotted write).
-        window.feedBack.on('instrument:changed', () => { _state._playerSelected = null; _invalidateCoverageCache(); });
+        window.feedBack.on('instrument:changed', () => {
+            _state._playerSelected = null; _invalidatePlayerTuning(); _invalidateCoverageCache();
+        });
         // A retune (working tuning published on a tuner clear) changes coverage for the
-        // current song — drop the cached report so a re-evaluation recomputes it.
-        window.feedBack.on('working-tuning-changed', _invalidateCoverageCache);
+        // current song — drop the cached player tuning + report so a re-evaluation recomputes.
+        window.feedBack.on('working-tuning-changed', () => { _invalidatePlayerTuning(); _invalidateCoverageCache(); });
     }
 
     // ── Player sync helpers ───────────────────────────────────────────