fix(chords): keep retuned shapes inside the diagram, carry tuning in links

Addresses review feedback on #23.

Retuning could stretch a shape past the four frets Chord.svelte draws, so
fingers rendered off the end of the neck. Uneven string shifts pull a grip
apart, and a voicing that leaned on an open string high up the neck has to
fret it once the tuning drops - chords-db's open G spans frets 2-7 in Drop
C, and a C sus voicing spans 1-9 in Half Step Down. Those are unplayable as
a single grip rather than merely badly framed, so drop them the way shapes
running off the end of the neck are already dropped.

Standard tuning is unaffected (0 of 2818 positions). Half Step Down loses
8.3%, Drop D 7.9%, Drop C 15.5% - all redundant alternates, leaving no chord
in any tuning without a diagram.

FRET_WINDOW is exported and Chord.svelte takes its frets default from it, so
the window the chart draws cannot drift from the one shapes are fitted into.

Chord links also dropped the selected tuning, so clicking a Drop D chord
landed on the chord page in Standard and drew different shapes than the ones
just played. Thread the tuning name through ScaleChords to Chord and encode
it into the href.

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

Author: caged

src/frets/chordFingerings.enharmonics.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import { Mode, Note, Scale } from "tonal";
 import {
   CHORDS_DB_TUNING,
+  FRET_WINDOW,
   getChordVariations,
 } from "./chordFingerings.js";
 
@@ -200,6 +201,43 @@ describe("tuning-aware fingerings", () => {
     }
   });
 
+  // Retuning can stretch a shape past the window Chord.svelte draws, which
+  // renders fingers off the end of the neck. Worst observed before the fix was
+  // a C sus voicing spanning frets 1-9 in Half Step Down, because the open G
+  // string it leaned on had to be fretted once the tuning dropped.
+  it("never emits a fret past the diagram window", () => {
+    for (const [, tuning] of Object.entries(TUNINGS)) {
+      for (const [, , chordName] of allTriads()) {
+        for (const position of getChordVariations(chordName, tuning)
+          .positions) {
+          for (const [, fret] of position.fingers) {
+            if (typeof fret === "number") {
+              expect(fret).toBeLessThanOrEqual(FRET_WINDOW);
+            }
+          }
+        }
+      }
+    }
+  });
+
+  it("keeps every retuned shape within a hand's span", () => {
+    // Open strings ride above the nut and cost no reach, so only fretted
+    // notes count toward the span.
+    for (const [, tuning] of Object.entries(TUNINGS)) {
+      for (const [, , chordName] of allTriads()) {
+        for (const position of getChordVariations(chordName, tuning)
+          .positions) {
+          const fretted = position.fingers
+            .map(([, fret]) => fret)
+            .filter((fret) => typeof fret === "number" && fret > 0);
+          if (fretted.length < 2) continue;
+          const span = Math.max(...fretted) - Math.min(...fretted) + 1;
+          expect(span).toBeLessThanOrEqual(FRET_WINDOW);
+        }
+      }
+    }
+  });
+
   // Seven-string support is a known gap: convertToSVGuitarFormat hardcodes a
   // six-string reversal (6 - i). Rather than emit wrong shapes we fall back to
   // the standard-tuning fingerings.

src/frets/chordFingerings.js

@@ -35,6 +35,13 @@ const CHROMA_TO_DB_KEY = [
 /** Highest fret we consider a fingering playable at. */
 const MAX_FRET = 24;
 
+/**
+ * How many frets a chord diagram spans. Exported so `Chord.svelte` draws the
+ * same window that `retunePosition` fits shapes into — if the two drift, the
+ * chart renders fingers past the end of the neck it drew.
+ */
+export const FRET_WINDOW = 4;
+
 /**
  * Get fingering positions for a chord using the chords-db library
  *
@@ -195,7 +202,17 @@ function retunePosition(position, offsets, tuning) {
   const fretted = absolute.filter((fret) => fret > 0);
   const highest = fretted.length ? Math.max(...fretted) : 0;
   const lowest = fretted.length ? Math.min(...fretted) : 0;
-  const newBaseFret = highest <= 4 || !fretted.length ? 1 : lowest;
+
+  // Retuning can stretch a shape past the diagram. Uneven string shifts pull
+  // the grip apart, and a voicing that leaned on an open string high up the
+  // neck now has to fret it — chords-db's open G in Drop C spans frets 2-7,
+  // and C sus voicings can span nine. Those are unplayable as a single grip,
+  // not merely badly framed, so drop them the way out-of-range shapes are
+  // dropped above. Open strings ride above the nut and cost no reach, so only
+  // fretted notes count toward the span.
+  if (fretted.length && highest - lowest + 1 > FRET_WINDOW) return null;
+
+  const newBaseFret = highest <= FRET_WINDOW || !fretted.length ? 1 : lowest;
 
   const toRelative = (fret) => (fret <= 0 ? fret : fret - newBaseFret + 1);
 

src/lib/Chord.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { getChordVariations } from "../frets/chordFingerings.js";
+  import { getChordVariations, FRET_WINDOW } from "../frets/chordFingerings.js";
   import { tunings } from "$lib";
   import { getContext, onMount } from "svelte";
   import { SVGuitarChord } from "svguitar";
@@ -8,7 +8,8 @@
     chordName,
     position = 0,
     tuning = tunings.get("Standard"),
-    frets = 4,
+    tuningName = null,
+    frets = FRET_WINDOW,
   } = $props();
 
   const { player } = getContext("app");
@@ -23,6 +24,13 @@
   const variations = $derived(getChordVariations(chordName, tuning));
   const chordData = $derived(variations?.positions?.[position] ?? null);
 
+  // Carry the tuning into the link, or the chord page falls back to Standard
+  // and shows different shapes than the ones just clicked.
+  const chordHref = $derived(
+    `/chords/${encodeURIComponent(chordName)}` +
+      (tuningName ? `?tuning=${encodeURIComponent(tuningName)}` : ""),
+  );
+
   // Colors based on color scheme
   const chordColor = $derived(isDarkMode ? "#e5e7eb" : "#333");
 
@@ -90,7 +98,7 @@
     bind:clientHeight={height}
     bind:this={el}
     data-chord={chordName}
-    href="/chords/{encodeURIComponent(chordName)}"
+    href={chordHref}
     title="View all positions for {chordName}"
     class="w-full h-full flex">
   </a>

src/lib/ScaleChords.svelte

@@ -2,7 +2,7 @@
   import { Mode } from "tonal";
   import Chord from "$lib/Chord.svelte";
 
-  let { scale, tuning } = $props();
+  let { scale, tuning, tuningName = null } = $props();
 
   // Chord names are passed through as Mode.triads spells them — enharmonic
   // normalisation happens in the chords-db lookup, so Cb/Fb/E#/B# and the
@@ -23,7 +23,7 @@
   {#each chords as chord}
     <div
       class="bg-gray-50 border border-transparent hover:bg-gray-100 hover:border-gray-200 transition-all dark:bg-blue-900/20 dark:border dark:border-blue-900/50 dark:hover:bg-blue-900/40 rounded">
-      <Chord chordName={chord} {tuning} />
+      <Chord chordName={chord} {tuning} {tuningName} />
     </div>
   {/each}
 </div>

src/routes/+page.svelte

@@ -116,6 +116,6 @@
 
 {#if triads.length > 0}
   <div class="relative px-5 dark:border-blue-900">
-    <ScaleChords scale={scaleObj} tuning={tunings.get(tuning)} />
+    <ScaleChords scale={scaleObj} tuning={tunings.get(tuning)} tuningName={tuning} />
   </div>
 {/if}

src/routes/chords/[chord]/+page.svelte

@@ -40,7 +40,7 @@
           <div class="absolute top-2 right-2 text-xs text-blue-500">
             Position {idx + 1}
           </div>
-          <Chord {chordName} position={idx} tuning={tuningObj} />
+          <Chord {chordName} position={idx} tuning={tuningObj} tuningName={tuning} />
         </div>
       {/each}
     </div>