@pepperhorn/chordl-guitar 0.2.0 → 0.3.1

package/dist/experience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience.js","sourceRoot":"","sources":["../src/experience.ts"],"names":[],"mappings":"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"}

package/dist/guitarPosition.d.ts

@@ -0,0 +1,33 @@
+import type { ChordsDbPosition } from "./instruments.js";
+import type { GuitarReview } from "./voicingReview.js";
+import type { ToneOptions, GeneratedPosition } from "./voicingGenerator.js";
+export interface SpelledChord {
+    /** Root, spelled: "C", "F#", "Bb". */
+    root: string;
+    /** Chord tones, spelled; letters decide degrees (D# is #9, Eb is b3). */
+    pitchClasses: string[];
+    /** Slash bass, spelled. Omit (or equal the root) for root position. */
+    bass?: string;
+}
+export interface LibraryPosition extends ChordsDbPosition {
+    generated: false;
+    source: "chords-db" | "power-chord";
+    /** chords-db suffix the shape came from. */
+    suffix?: string;
+    review: GuitarReview;
+}
+export type GuitarPosition = LibraryPosition | GeneratedPosition;
+/** The chords-db suffix carrying exactly this chord, or null. */
+export declare function chordsDbSuffixFor(chord: SpelledChord): string | null;
+/**
+ * Every chords-db six-string position that spells the chord (see
+ * `positionSpellsChord`), in chords-db's order — the alternatives elsewhere on
+ * the neck. The first is the one `guitarPositionFor` prints. Empty when
+ * chords-db has no entry for the chord or none of its positions spells it.
+ */
+export declare function guitarLibraryPositionsFor(chord: SpelledChord, options?: ToneOptions): LibraryPosition[];
+/**
+ * The best guitar position for a spelled chord, or null if none is playable
+ * under the generator's constraints.
+ */
+export declare function guitarPositionFor(chord: SpelledChord, options?: ToneOptions): GuitarPosition | null;

package/dist/guitarPosition.js

@@ -0,0 +1,115 @@
+/**
+ * One guitar position for any spelled chord: chords-db when it has a shape
+ * that actually spells the chord, the regular power-chord shape for "5", and
+ * the voicing generator for everything else.
+ *
+ * chords-db is checked, not trusted blindly: its first C9 position has no b7
+ * and one of its C13 positions stacks the 11 on the major 3rd. A position is
+ * taken only if `positionSpellsChord` accepts it under the same rule table the
+ * generator obeys; otherwise the next position is tried, then the generator.
+ */
+import guitarDb from "./generated/guitar.slim.json" with { type: "json" };
+import { powerChordPosition } from "./powerChords.js";
+import { analyzeChordTones, generateGuitarVoicings, positionSpellsChord, } from "./voicingGenerator.js";
+import { reviewGuitarPosition } from "./voicingReview.js";
+const GUITAR_DB = guitarDb;
+// chords-db suffix → pitch classes above the root (the chord's definition, not
+// any one position's subset).
+const DB_SUFFIX_PCS = {
+    major: [0, 4, 7], minor: [0, 3, 7], dim: [0, 3, 6], dim7: [0, 3, 6, 9],
+    sus2: [0, 2, 7], sus4: [0, 5, 7], "7sus4": [0, 5, 7, 10], aug: [0, 4, 8],
+    "6": [0, 4, 7, 9], "69": [0, 2, 4, 7, 9], "7": [0, 4, 7, 10], "7b5": [0, 4, 6, 10],
+    aug7: [0, 4, 8, 10], "9": [0, 2, 4, 7, 10], "9b5": [0, 2, 4, 6, 10], aug9: [0, 2, 4, 8, 10],
+    "7b9": [0, 1, 4, 7, 10], "7#9": [0, 3, 4, 7, 10], "11": [0, 2, 4, 5, 7, 10],
+    "9#11": [0, 2, 4, 6, 7, 10], "13": [0, 2, 4, 7, 9, 10], maj7: [0, 4, 7, 11],
+    maj7b5: [0, 4, 6, 11], "maj7#5": [0, 4, 8, 11], maj9: [0, 2, 4, 7, 11],
+    maj11: [0, 2, 4, 5, 7, 11], maj13: [0, 2, 4, 7, 9, 11], m6: [0, 3, 7, 9],
+    m69: [0, 2, 3, 7, 9], m7: [0, 3, 7, 10], m7b5: [0, 3, 6, 10], m9: [0, 2, 3, 7, 10],
+    m11: [0, 2, 3, 5, 7, 10], mmaj7: [0, 3, 7, 11], mmaj7b5: [0, 3, 6, 11],
+    mmaj9: [0, 2, 3, 7, 11], mmaj11: [0, 2, 3, 5, 7, 11], add9: [0, 2, 4, 7], madd9: [0, 2, 3, 7],
+};
+const DB_KEY_BY_PC = ["C", "Csharp", "D", "Eb", "E", "F", "Fsharp", "G", "Ab", "A", "Bb", "B"];
+const LETTER_PC = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+function pcOf(note) {
+    let v = LETTER_PC[note.charAt(0).toUpperCase()];
+    for (const ch of note.slice(1))
+        v += ch === "#" ? 1 : ch === "b" ? -1 : 0;
+    return ((v % 12) + 12) % 12;
+}
+const sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+function relativeSet(chord) {
+    const r = pcOf(chord.root);
+    return [...new Set([chord.root, ...chord.pitchClasses].map((n) => (pcOf(n) - r + 12) % 12))];
+}
+function isSlash(chord) {
+    return chord.bass !== undefined && pcOf(chord.bass) !== pcOf(chord.root);
+}
+/** The chords-db suffix carrying exactly this chord, or null. */
+export function chordsDbSuffixFor(chord) {
+    const set = relativeSet(chord);
+    const entries = GUITAR_DB.chords[DB_KEY_BY_PC[pcOf(chord.root)]] ?? [];
+    if (isSlash(chord)) {
+        const quality = sameSet(set, [0, 4, 7]) ? "" : sameSet(set, [0, 3, 7]) ? "m" : null;
+        if (quality === null)
+            return null;
+        const bassPc = pcOf(chord.bass);
+        const hit = entries.find((e) => e.suffix.startsWith(`${quality}/`) && e.suffix.indexOf("/") === quality.length &&
+            pcOf(e.suffix.slice(quality.length + 1)) === bassPc);
+        return hit ? hit.suffix : null;
+    }
+    for (const [suffix, pcs] of Object.entries(DB_SUFFIX_PCS)) {
+        if (sameSet(set, pcs) && entries.some((e) => e.suffix === suffix))
+            return suffix;
+    }
+    return null;
+}
+/**
+ * Every chords-db six-string position that spells the chord (see
+ * `positionSpellsChord`), in chords-db's order — the alternatives elsewhere on
+ * the neck. The first is the one `guitarPositionFor` prints. Empty when
+ * chords-db has no entry for the chord or none of its positions spells it.
+ */
+export function guitarLibraryPositionsFor(chord, options = {}) {
+    // The written bass (even one equal to the root) stays in the analysis: it is
+    // what stops rootless level 3 from dropping the root. Only suffix lookup and
+    // the power-chord template treat a root bass as root position.
+    const analysis = analyzeChordTones(chord.root, chord.pitchClasses, chord.bass, options);
+    const suffix = chordsDbSuffixFor(chord);
+    if (!suffix)
+        return [];
+    const entry = GUITAR_DB.chords[DB_KEY_BY_PC[pcOf(chord.root)]].find((e) => e.suffix === suffix);
+    return entry.positions
+        .filter((p) => positionSpellsChord(p, analysis))
+        .map((p) => ({
+        ...p, generated: false, source: "chords-db", suffix,
+        review: reviewGuitarPosition(p, analysis, { level: options.level, origin: "chords-db" }),
+    }));
+}
+/**
+ * The best guitar position for a spelled chord, or null if none is playable
+ * under the generator's constraints.
+ */
+export function guitarPositionFor(chord, options = {}) {
+    const library = guitarLibraryPositionsFor(chord, options)[0];
+    if (library)
+        return library;
+    const analysis = analyzeChordTones(chord.root, chord.pitchClasses, chord.bass, options);
+    if (!isSlash(chord) && sameSet(relativeSet(chord), [0, 7])) {
+        const pos = powerChordPosition(pcOf(chord.root), { stringSet: "E" });
+        if (pos)
+            return {
+                ...pos, generated: false, source: "power-chord",
+                review: reviewGuitarPosition(pos, analysis, { level: options.level, origin: "template:power-chord" }),
+            };
+    }
+    const p = generateGuitarVoicings(chord.pitchClasses, { ...options, root: chord.root, bass: chord.bass, limit: 1 })[0];
+    if (!p)
+        return null;
+    if (chordsDbSuffixFor(chord)) {
+        p.review = reviewGuitarPosition(p, analysis, {
+            level: options.level, origin: "search", dbPositionRejected: true,
+        });
+    }
+    return p;
+}
+//# sourceMappingURL=guitarPosition.js.map

package/dist/guitarPosition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guitarPosition.js","sourceRoot":"","sources":["../src/guitarPosition.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,9 +2,12 @@ export { INSTRUMENTS, dbPositionToChord } from "./instruments.js";
 export type { InstrumentId, InstrumentConfig, ChordsDb, ChordsDbEntry, ChordsDbPosition, } from "./instruments.js";
 export { lookupGuitarChord, hasGuitarChord } from "./chordLookup.js";
 export type { GuitarChordResult } from "./chordLookup.js";
-export { GUITAR_TOP3_PRESETS, lookupTop3Chord } from "./staticPresets.js";
+export { GUITAR_TOP3_PRESETS, lookupTop3Chord, findTop3Preset, TOP3_UNRESOLVED, } from "./staticPresets.js";
 export type { StaticPreset } from "./staticPresets.js";
-export { positionToMidi, rootPitchClass } from "./pitch.js";
+export type { Top3Source } from "./top3Generated.js";
+export { positionToMidi, positionToSoundingStrings, rootPitchClass } from "./pitch.js";
+export type { SoundingString } from "./pitch.js";
+export { toDbSuffix, splitLabel } from "./chordNames.js";
 export { positionFacts, duplicateVoicingMap } from "./voicingFacts.js";
 export type { Inversion, PositionFacts } from "./voicingFacts.js";
 export { matchesShapeClass, canonicalPositionIndex, selectVoicings, SHAPE_CLASS_LADDER, } from "./voicingSelect.js";
@@ -12,3 +15,11 @@ export type { ShapeClass, CanonicalOptions, VoicingChoice, SelectVoicingsOptions
 export { powerChordPosition, powerChordShape } from "./powerChords.js";
 export type { PowerChordStringSet, PowerChordOptions } from "./powerChords.js";
 export { bassShapeFor, violinShapeFor, violinCoverage } from "./generatedShapes.js";
+export { EXPERIENCE_LADDER, levelForFacts, levelForTop3, selectForExperience, selectForResult, } from "./experience.js";
+export type { ExperienceLevel, ExperienceQuery, ExperienceSelection, } from "./experience.js";
+export { generateGuitarVoicings, analyzeChordTones, positionSpellsChord, fingeringFor, VOICING_RULES, } from "./voicingGenerator.js";
+export type { GeneratedPosition, GenerateOptions, ToneOptions, ChordTone, ChordToneAnalysis, Fingering, ToneRole, VoicingRule, } from "./voicingGenerator.js";
+export { guitarPositionFor, guitarLibraryPositionsFor, chordsDbSuffixFor } from "./guitarPosition.js";
+export type { GuitarPosition, LibraryPosition, SpelledChord } from "./guitarPosition.js";
+export { reviewGuitarPosition } from "./voicingReview.js";
+export type { GuitarReview, ReasonCode, TeachingLevel, ReviewOptions } from "./voicingReview.js";

package/dist/index.js

@@ -5,10 +5,15 @@
 // rendering. Based on pepperhorn/frames.
 export { INSTRUMENTS, dbPositionToChord } from "./instruments.js";
 export { lookupGuitarChord, hasGuitarChord } from "./chordLookup.js";
-export { GUITAR_TOP3_PRESETS, lookupTop3Chord } from "./staticPresets.js";
-export { positionToMidi, rootPitchClass } from "./pitch.js";
+export { GUITAR_TOP3_PRESETS, lookupTop3Chord, findTop3Preset, TOP3_UNRESOLVED, } from "./staticPresets.js";
+export { positionToMidi, positionToSoundingStrings, rootPitchClass } from "./pitch.js";
+export { toDbSuffix, splitLabel } from "./chordNames.js";
 export { positionFacts, duplicateVoicingMap } from "./voicingFacts.js";
 export { matchesShapeClass, canonicalPositionIndex, selectVoicings, SHAPE_CLASS_LADDER, } from "./voicingSelect.js";
 export { powerChordPosition, powerChordShape } from "./powerChords.js";
 export { bassShapeFor, violinShapeFor, violinCoverage } from "./generatedShapes.js";
+export { EXPERIENCE_LADDER, levelForFacts, levelForTop3, selectForExperience, selectForResult, } from "./experience.js";
+export { generateGuitarVoicings, analyzeChordTones, positionSpellsChord, fingeringFor, VOICING_RULES, } from "./voicingGenerator.js";
+export { guitarPositionFor, guitarLibraryPositionsFor, chordsDbSuffixFor } from "./guitarPosition.js";
+export { reviewGuitarPosition } from "./voicingReview.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,yCAAyC;AAEzC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AASlE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,yCAAyC;AAEzC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AASlE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGvF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGvE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEpF,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAOzB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,aAAa,GACd,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/instruments.js

@@ -72,7 +72,15 @@ export const INSTRUMENTS = {
  */
 export function dbPositionToChord(pos, stringCount, title) {
     const fingers = [];
-    const barreFrets = new Set(pos.barres);
+    const barreContacts = pos.barres.map(fret => {
+        const atFret = pos.frets.flatMap((f, i) => f === fret ? [i] : []);
+        const repeated = atFret.find(i => pos.fingers[i] > 0 &&
+            atFret.filter(j => pos.fingers[j] === pos.fingers[i]).length > 1);
+        // A mini-barre can share a fret with another finger. Older database
+        // entries without finger labels retain their fret-based bounds.
+        return repeated === undefined ? atFret : atFret.filter(i => pos.fingers[i] === pos.fingers[repeated]);
+    });
+    const covered = new Set(barreContacts.flat());
     pos.frets.forEach((fret, dbIdx) => {
         // chords-db lists strings low→high; svguitar numbers strings high→low.
         const stringNum = stringCount - dbIdx;
@@ -85,16 +93,14 @@ export function dbPositionToChord(pos, stringCount, title) {
             return;
         }
         // Skip strings covered by a barre — the barre draws them.
-        if (barreFrets.has(fret))
+        if (covered.has(dbIdx))
             return;
         const fingerNum = pos.fingers[dbIdx];
         const text = fingerNum && fingerNum > 0 ? String(fingerNum) : undefined;
         fingers.push(text ? [stringNum, fret, text] : [stringNum, fret]);
     });
-    const barres = pos.barres.map((fret) => {
-        const playingIdxs = pos.frets
-            .map((f, i) => (f === fret ? i : -1))
-            .filter((i) => i >= 0);
+    const barres = pos.barres.map((fret, index) => {
+        const playingIdxs = barreContacts[index];
         const stringNums = playingIdxs.map((i) => stringCount - i);
         const fromString = Math.max(...stringNums);
         const toString = Math.min(...stringNums);

package/dist/instruments.js.map

@@ -1 +1 @@
-{"version":3,"file":"instruments.js","sourceRoot":"","sources":["../src/instruments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instruments.js","sourceRoot":"","sources":["../src/instruments.ts"],"names":[],"mappings":"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"}

package/dist/pitch.d.ts

@@ -7,6 +7,12 @@
  * no midi field at all, so derivation is required regardless.
  */
 import type { ChordsDbPosition } from "./instruments.js";
+export interface SoundingString {
+    /** Zero-based physical string index in low-to-high instrument order. */
+    stringIndex: number;
+    midi: number;
+}
+export declare function positionToSoundingStrings(pos: ChordsDbPosition, openMidi: number[]): SoundingString[];
 /**
  * Sounding MIDI pitches for a chords-db position.
  *

package/dist/pitch.js

@@ -1,3 +1,18 @@
+export function positionToSoundingStrings(pos, openMidi) {
+    const out = [];
+    pos.frets.forEach((fret, stringIndex) => {
+        if (fret === -1)
+            return;
+        const open = openMidi[stringIndex];
+        if (open === undefined)
+            return;
+        out.push({
+            stringIndex,
+            midi: fret === 0 ? open : open + pos.baseFret + fret - 1,
+        });
+    });
+    return out;
+}
 /**
  * Sounding MIDI pitches for a chords-db position.
  *
@@ -14,16 +29,7 @@
  * @returns sounding pitches only, in chords-db string order
  */
 export function positionToMidi(pos, openMidi) {
-    const out = [];
-    pos.frets.forEach((fret, i) => {
-        if (fret === -1)
-            return;
-        const open = openMidi[i];
-        if (open === undefined)
-            return;
-        out.push(fret === 0 ? open : open + pos.baseFret + fret - 1);
-    });
-    return out;
+    return positionToSoundingStrings(pos, openMidi).map(({ midi }) => midi);
 }
 const PITCH_CLASSES = {
     C: 0, "B#": 0,

package/dist/pitch.js.map

@@ -1 +1 @@
-{"version":3,"file":"pitch.js","sourceRoot":"","sources":["../src/pitch.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAqB,EAAE,QAAkB;IACtE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QAC5B,IAAI,IAAI,KAAK,CAAC,CAAC;YAAE,OAAO;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,aAAa,GAA2B;IAC5C,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACX,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IAChB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;CACd,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACtC,CAAC"}
+{"version":3,"file":"pitch.js","sourceRoot":"","sources":["../src/pitch.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,yBAAyB,CACvC,GAAqB,EACrB,QAAkB;IAElB,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QACtC,IAAI,IAAI,KAAK,CAAC,CAAC;YAAE,OAAO;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,WAAW;YACX,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,QAAQ,GAAG,IAAI,GAAG,CAAC;SACzD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAqB,EAAE,QAAkB;IACtE,OAAO,yBAAyB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,aAAa,GAA2B;IAC5C,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACX,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACd,CAAC,EAAE,CAAC;IACJ,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IAChB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;CACd,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACtC,CAAC"}

package/dist/staticPresets.d.ts

@@ -1,16 +1,72 @@
 import type { Chord } from "svguitar";
+import { TOP3_UNRESOLVED } from "./top3Generated.js";
+import type { Top3Source } from "./top3Generated.js";
+import type { ExperienceLevel } from "./experience.js";
 export interface StaticPreset {
     key: string;
     suffix: string;
     chord: Chord;
+    /**
+     * Where the shape came from: a hand-authored beginner preset, a window taken
+     * from a stored chords-db voicing, or one built from the chord's pitch classes.
+     */
+    source?: Top3Source;
+    /** How hard the shape is to play. Derived; see src/experience.ts. */
+    level: ExperienceLevel;
+    /**
+     * True when the shape is playable but not a faithful spelling — it drops the
+     * root, or its three notes also name another chord. A caller may present these
+     * differently; nothing here treats them as second class.
+     */
+    approximate?: boolean;
 }
 /**
- * Hand-authored beginner voicings on the top three strings (G B E).
+ * Where a shape's diagram window starts, and its frets within that window.
  *
- * chords-db has no three-string voicings, so these cannot be derived — the table
- * is the sole source. Every entry is checked against pitch-class arithmetic by
- * staticPresets.test.ts, because a wrong shape is unrecoverable once printed.
+ * The generated table stores absolute frets, measured from the nut. Two thirds
+ * of it sits past the drawn window, so a diagram has to say which window it is:
+ *
+ *   - within `DIAGRAM_FRETS` of the nut, the window is the nut. Frets stay as
+ *     they are, and open strings are drawn as open strings.
+ *   - anything higher slides. The window starts at the shape's lowest fretted
+ *     fret and each fret becomes `f - position + 1`.
+ *
+ * -1 and 0 are sentinels and are never offset. A slid window never carries a 0:
+ * the generator does not emit a shape that mixes an open string with a note past
+ * the window, because no window could show both.
+ */
+export declare function top3Window(frets: readonly number[]): {
+    position: number;
+    frets: number[];
+};
+/**
+ * Beginner voicings on the top three strings (G B E), for all 12 roots.
+ *
+ * Generated — see src/top3Generated.ts and scripts/build-top3.mjs for how each
+ * shape was chosen, and docs/superpowers/specs/2026-09-07-guitar-top3-generated-voicings-design.md
+ * for why. Every entry is checked against pitch-class arithmetic, and against
+ * every other entry, by staticPresets.test.ts: a wrong shape is unrecoverable
+ * once printed, and a shape that duplicates another chord's is a wrong shape.
+ *
+ * This replaces twenty hand-authored entries that covered 7 of 12 roots and, in
+ * five cases, dropped the root — which made `Am7` print C major, `Fmaj7` print
+ * A minor and `Dm7` print F major.
  */
 export declare const GUITAR_TOP3_PRESETS: StaticPreset[];
-/** Look up a top-3 shape. Returns null rather than guessing at an unknown chord. */
+/**
+ * Find a preset by any spelling of its root and any alias of its quality.
+ *
+ * Suffixes go through the same `toDbSuffix` the six-string lookup uses, because
+ * the table is keyed with chords-db's own suffix names — so `ø`, `M7`, `°7`,
+ * `sus` and `6/9` resolve here exactly as they do there, rather than through a
+ * second, smaller copy of that knowledge.
+ */
+export declare function findTop3Preset(key: string, suffix: string): StaticPreset | null;
+/**
+ * Look up a top-3 shape. Returns null rather than guessing at an unknown chord.
+ *
+ * A null here is a fact, not a gap: the altered dominants in `TOP3_UNRESOLVED`
+ * need four notes to exist, and three strings cannot carry them.
+ */
 export declare function lookupTop3Chord(key: string, suffix: string): Chord | null;
+export { TOP3_UNRESOLVED };

package/dist/staticPresets.js

@@ -1,48 +1,109 @@
+import { INSTRUMENTS } from "./instruments.js";
+import { rootPitchClass } from "./pitch.js";
+import { toDbSuffix } from "./chordNames.js";
+import { TOP3_GENERATED, TOP3_UNRESOLVED } from "./top3Generated.js";
 /** Strings 4-6 are always muted for top-3 voicings. */
 const MUTED_LOW = [[4, "x"], [5, "x"], [6, "x"]];
-function top3(key, suffix, g, b, e) {
-    const finger = (s, [fret, label]) => label ? [s, fret, label] : [s, fret];
+/** How many frets a `guitar-top3` diagram draws. */
+const DIAGRAM_FRETS = INSTRUMENTS["guitar-top3"].frets;
+/**
+ * Where a shape's diagram window starts, and its frets within that window.
+ *
+ * The generated table stores absolute frets, measured from the nut. Two thirds
+ * of it sits past the drawn window, so a diagram has to say which window it is:
+ *
+ *   - within `DIAGRAM_FRETS` of the nut, the window is the nut. Frets stay as
+ *     they are, and open strings are drawn as open strings.
+ *   - anything higher slides. The window starts at the shape's lowest fretted
+ *     fret and each fret becomes `f - position + 1`.
+ *
+ * -1 and 0 are sentinels and are never offset. A slid window never carries a 0:
+ * the generator does not emit a shape that mixes an open string with a note past
+ * the window, because no window could show both.
+ */
+export function top3Window(frets) {
+    const fretted = frets.filter((f) => f > 0);
+    const highest = fretted.length ? Math.max(...fretted) : 0;
+    if (highest <= DIAGRAM_FRETS)
+        return { position: 1, frets: [...frets] };
+    const position = Math.min(...fretted);
+    return { position, frets: frets.map((f) => (f > 0 ? f - position + 1 : f)) };
+}
+/**
+ * One generated row → an svguitar shape, in the window it is drawn in.
+ *
+ * The table lists frets low → high as [G, B, E], which is chords-db's string
+ * order. svguitar numbers strings from the highest pitch, so those same three
+ * are svguitar 3, 2 and 1. This is the relabelling, and it is the only one:
+ * `dbPositionToChord` remains the single function that inverts string order.
+ */
+function toPreset(entry) {
+    const finger = (stringNo, fret, label) => (label ? [stringNo, fret, label] : [stringNo, fret]);
+    const window = top3Window(entry.frets);
     return {
-        key,
-        suffix,
+        key: entry.key,
+        suffix: entry.suffix,
         chord: {
-            fingers: [finger(3, g), finger(2, b), finger(1, e), ...MUTED_LOW],
+            fingers: [
+                finger(3, window.frets[0], entry.fingers[0]),
+                finger(2, window.frets[1], entry.fingers[1]),
+                finger(1, window.frets[2], entry.fingers[2]),
+                ...MUTED_LOW,
+            ],
             barres: [],
+            position: window.position,
         },
+        source: entry.source,
+        level: entry.level,
+        ...(entry.approximate ? { approximate: true } : {}),
     };
 }
 /**
- * Hand-authored beginner voicings on the top three strings (G B E).
+ * Beginner voicings on the top three strings (G B E), for all 12 roots.
+ *
+ * Generated — see src/top3Generated.ts and scripts/build-top3.mjs for how each
+ * shape was chosen, and docs/superpowers/specs/2026-09-07-guitar-top3-generated-voicings-design.md
+ * for why. Every entry is checked against pitch-class arithmetic, and against
+ * every other entry, by staticPresets.test.ts: a wrong shape is unrecoverable
+ * once printed, and a shape that duplicates another chord's is a wrong shape.
+ *
+ * This replaces twenty hand-authored entries that covered 7 of 12 roots and, in
+ * five cases, dropped the root — which made `Am7` print C major, `Fmaj7` print
+ * A minor and `Dm7` print F major.
+ */
+export const GUITAR_TOP3_PRESETS = TOP3_GENERATED.map(toPreset);
+/**
+ * Indexed by pitch class, not by spelling.
+ *
+ * The table stores roots as chords-db spells them — `C#` and `F#`, but `Eb`,
+ * `Ab` and `Bb` — which is not what a user types, and matching the string meant
+ * `Db`, `D#`, `G#` and `A#` reached nothing at all. A pitch class has no
+ * spelling, so `rootPitchClass` — the package's one root parser, which already
+ * knows every enharmonic down to `Cb` and `B#` — resolves both sides.
+ */
+const BY_PITCH_CLASS = new Map(GUITAR_TOP3_PRESETS.map((p) => [`${rootPitchClass(p.key)} ${p.suffix}`, p]));
+/**
+ * Find a preset by any spelling of its root and any alias of its quality.
+ *
+ * Suffixes go through the same `toDbSuffix` the six-string lookup uses, because
+ * the table is keyed with chords-db's own suffix names — so `ø`, `M7`, `°7`,
+ * `sus` and `6/9` resolve here exactly as they do there, rather than through a
+ * second, smaller copy of that knowledge.
+ */
+export function findTop3Preset(key, suffix) {
+    const pc = rootPitchClass(key);
+    if (pc === null)
+        return null;
+    return BY_PITCH_CLASS.get(`${pc} ${toDbSuffix(suffix)}`) ?? null;
+}
+/**
+ * Look up a top-3 shape. Returns null rather than guessing at an unknown chord.
  *
- * chords-db has no three-string voicings, so these cannot be derived — the table
- * is the sole source. Every entry is checked against pitch-class arithmetic by
- * staticPresets.test.ts, because a wrong shape is unrecoverable once printed.
+ * A null here is a fact, not a gap: the altered dominants in `TOP3_UNRESOLVED`
+ * need four notes to exist, and three strings cannot carry them.
  */
-export const GUITAR_TOP3_PRESETS = [
-    top3("C", "major", [0], [1, "1"], [0]),
-    top3("G", "major", [0], [0], [3, "3"]),
-    top3("D", "major", [2, "1"], [3, "3"], [2, "2"]),
-    top3("A", "major", [2, "1"], [2, "2"], [0]),
-    top3("E", "minor", [0], [0], [0]),
-    top3("A", "minor", [2, "2"], [1, "1"], [0]),
-    top3("D", "minor", [2, "2"], [3, "3"], [1, "1"]),
-    top3("E", "major", [1, "1"], [0], [0]),
-    top3("C", "7", [3, "3"], [1, "1"], [0]),
-    top3("G", "7", [0], [0], [1, "1"]),
-    top3("B", "minor", [4, "3"], [3, "2"], [2, "1"]),
-    top3("F", "major", [2, "2"], [1, "1"], [1, "1"]),
-    top3("D", "7", [2, "2"], [1, "1"], [2, "3"]),
-    top3("E", "7", [1, "1"], [3, "3"], [0]),
-    top3("A", "7", [0], [2, "2"], [0]),
-    top3("A", "m7", [0], [1, "1"], [0]),
-    top3("D", "m7", [2, "2"], [1, "1"], [1, "1"]),
-    top3("E", "m7", [0], [3, "3"], [0]),
-    top3("F", "maj7", [2, "2"], [1, "1"], [0]),
-    top3("G", "minor", [3, "1"], [3, "2"], [3, "3"]),
-];
-/** Look up a top-3 shape. Returns null rather than guessing at an unknown chord. */
 export function lookupTop3Chord(key, suffix) {
-    const hit = GUITAR_TOP3_PRESETS.find((p) => p.key === key && p.suffix === suffix);
-    return hit ? hit.chord : null;
+    return findTop3Preset(key, suffix)?.chord ?? null;
 }
+export { TOP3_UNRESOLVED };
 //# sourceMappingURL=staticPresets.js.map

package/dist/staticPresets.js.map

@@ -1 +1 @@
-{"version":3,"file":"staticPresets.js","sourceRoot":"","sources":["../src/staticPresets.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"staticPresets.js","sourceRoot":"","sources":["../src/staticPresets.ts"],"names":[],"mappings":"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"}