@pepperhorn/chordl-core 0.3.0

package/dist/progression/progression-resolver.js

@@ -0,0 +1,135 @@
+import { MAX_EXAMPLES } from "../config";
+import { resolveChord } from "../resolver/chord-resolver";
+import { resolveProgression, tokenizeProgression } from "./roman-numeral";
+import { findTemplate } from "./form-templates";
+import { findVoicing, voicingPitchClasses, mapToVoicingQuality, queryVoicings, inferStyle, } from "@pepperhorn/chordl-voicings";
+/**
+ * A set of contrasting styles to auto-cycle through when no style hint is given.
+ * Ordered by musical diversity.
+ */
+const CONTRASTING_STYLES = [
+    "Rootless Type A",
+    "Drop 2",
+    "Shell",
+    "Quartal",
+    "Spread",
+    "4-Note Closed",
+    "Rootless Type B",
+    "Upper Structure",
+    "Drop 2+4",
+];
+/**
+ * Given a style hint, return variations within that family.
+ * e.g. "Bill Evans" → [Rootless Type A, Rootless Type B, Shell]
+ */
+function getStyleVariations(styleHint) {
+    const primary = inferStyle(styleHint);
+    if (!primary)
+        return CONTRASTING_STYLES.slice(0, MAX_EXAMPLES);
+    const variations = [primary];
+    // Add related styles
+    if (primary === "Rootless Type A") {
+        variations.push("Rootless Type B", "Shell");
+    }
+    else if (primary === "Rootless Type B") {
+        variations.push("Rootless Type A", "Shell");
+    }
+    else if (primary === "Shell") {
+        variations.push("Rootless Type A", "Drop 2");
+    }
+    else if (primary === "Drop 2") {
+        variations.push("Drop 2+4", "Shell");
+    }
+    else if (primary === "Drop 2+4") {
+        variations.push("Drop 2", "Spread");
+    }
+    else if (primary === "Quartal") {
+        variations.push("Upper Structure", "Rootless Type A");
+    }
+    else if (primary === "Upper Structure") {
+        variations.push("Quartal", "Spread");
+    }
+    else if (primary === "Spread") {
+        variations.push("Drop 2", "4-Note Closed");
+    }
+    else if (primary === "4-Note Closed") {
+        variations.push("Spread", "Drop 2");
+    }
+    return variations.slice(0, MAX_EXAMPLES);
+}
+/**
+ * Voice a single chord symbol using a specific voicing style.
+ * Falls back to plain resolution if no voicing matches.
+ */
+function voiceChord(symbol, style) {
+    const resolved = resolveChord(symbol);
+    const quality = mapToVoicingQuality(resolved.type, resolved.notes);
+    let notes = resolved.notes;
+    let voicingStyle;
+    if (quality && style) {
+        const matches = queryVoicings({ quality, style });
+        if (matches.length > 0) {
+            const pcs = voicingPitchClasses(resolved.root, matches[0]);
+            if (pcs.length > 0) {
+                notes = pcs;
+                voicingStyle = style;
+            }
+        }
+    }
+    // Fallback: try any voicing for this quality
+    if (!voicingStyle && quality) {
+        const voicing = findVoicing(quality);
+        if (voicing) {
+            const pcs = voicingPitchClasses(resolved.root, voicing);
+            if (pcs.length > 0) {
+                notes = pcs;
+                voicingStyle = voicing.tags.style;
+            }
+        }
+    }
+    return {
+        symbol,
+        root: resolved.root,
+        notes,
+        voicingStyle,
+    };
+}
+/**
+ * Resolve a progression request into multiple voicing examples.
+ */
+export function resolveProgressionRequest(req) {
+    const numExamples = Math.min(req.numExamples ?? MAX_EXAMPLES, MAX_EXAMPLES);
+    // Try form template first
+    const template = findTemplate(req.progression);
+    let numerals;
+    let progressionName;
+    if (template) {
+        numerals = template.numerals;
+        progressionName = template.name;
+    }
+    else {
+        numerals = tokenizeProgression(req.progression);
+        progressionName = numerals.join("-");
+    }
+    // Resolve roman numerals to chord symbols in the key
+    const chords = resolveProgression(numerals, req.key);
+    // Determine voicing styles for each example
+    const styles = req.styleHint
+        ? getStyleVariations(req.styleHint)
+        : CONTRASTING_STYLES.slice(0, numExamples);
+    const examples = [];
+    for (let i = 0; i < numExamples; i++) {
+        const style = styles[i % styles.length];
+        const voicedChords = chords.map((c) => voiceChord(c.symbol, style));
+        examples.push({
+            label: `Example ${i + 1} — ${style}`,
+            chords: voicedChords,
+        });
+    }
+    return {
+        progressionName,
+        key: req.key,
+        examples,
+    };
+}
+//# sourceMappingURL=progression-resolver.js.map

package/dist/progression/progression-resolver.js.map

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

package/dist/progression/roman-numeral.d.ts

@@ -0,0 +1,14 @@
+interface RomanNumeralChord {
+    root: string;
+    symbol: string;
+    degree: number;
+}
+/**
+ * Resolve a roman numeral progression in a given key.
+ */
+export declare function resolveProgression(numerals: string[], key: string): RomanNumeralChord[];
+/**
+ * Parse a progression string like "ii-V-I" or "ii V7 Imaj7" into tokens.
+ */
+export declare function tokenizeProgression(input: string): string[];
+export {};

package/dist/progression/roman-numeral.js

@@ -0,0 +1,78 @@
+import { Note } from "tonal";
+import { spellWithPreference } from "../engine/note-spelling";
+const ROMAN_TO_SEMITONE = {
+    i: 0, ii: 2, iii: 4, iv: 5, v: 7, vi: 9, vii: 11,
+};
+/**
+ * Parse a single roman numeral token like "ii", "V7", "bIII", "#ivø7", "viio7"
+ */
+function parseRomanToken(token) {
+    // Alternation order matters: "iv" before "i" (otherwise "i" matches first
+    // in "iv"), "vi{1,2}" before "v" (otherwise "v" matches first in "vi").
+    // "i{1,3}" handles i, ii, iii. Suffix group (.*) captures quality markers.
+    const re = /^([#b]?)(iv|vi{1,2}|i{1,3}|v)(.*)/i;
+    const m = token.match(re);
+    if (!m)
+        return null;
+    const accidental = m[1];
+    const numeral = m[2];
+    const suffix = m[3];
+    const lower = numeral.toLowerCase();
+    const base = ROMAN_TO_SEMITONE[lower];
+    if (base === undefined)
+        return null;
+    let semitones = base;
+    if (accidental === "b")
+        semitones -= 1;
+    if (accidental === "#")
+        semitones += 1;
+    semitones = ((semitones % 12) + 12) % 12;
+    const isMinor = numeral === numeral.toLowerCase();
+    let quality = "";
+    if (suffix) {
+        let norm = suffix
+            .replace(/^°7/, "dim7")
+            .replace(/^°/, "dim")
+            .replace(/^ø7?/, "m7b5")
+            .replace(/^Δ7?/, "maj7");
+        if (isMinor && !norm.startsWith("m") && !norm.startsWith("dim") && !norm.startsWith("M")) {
+            quality = "m" + norm;
+        }
+        else {
+            quality = norm;
+        }
+    }
+    else {
+        quality = isMinor ? "m" : "";
+    }
+    return { semitones, quality, hasFlat: accidental === "b" };
+}
+/**
+ * Resolve a roman numeral progression in a given key.
+ */
+export function resolveProgression(numerals, key) {
+    const keyMidi = Note.midi(`${key}4`);
+    if (keyMidi == null)
+        throw new Error(`Invalid key: ${key}`);
+    return numerals.map((token) => {
+        const parsed = parseRomanToken(token);
+        if (!parsed)
+            throw new Error(`Can't parse roman numeral: "${token}"`);
+        const rootMidi = keyMidi + parsed.semitones;
+        const rootNote = Note.pitchClass(Note.fromMidi(rootMidi));
+        const root = spellWithPreference(rootNote, key, parsed.hasFlat);
+        const symbol = root + parsed.quality;
+        return { root, symbol, degree: parsed.semitones };
+    });
+}
+/**
+ * Parse a progression string like "ii-V-I" or "ii V7 Imaj7" into tokens.
+ */
+export function tokenizeProgression(input) {
+    return input
+        .split(/[\s\-–—→>]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+// preferredEnharmonic is now spellWithPreference from note-spelling.ts
+//# sourceMappingURL=roman-numeral.js.map

package/dist/progression/roman-numeral.js.map

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

package/dist/resolver/auto-layout.d.ts

@@ -0,0 +1,20 @@
+import type { WhiteNote } from "../types";
+/** Check if a white-key index (mod 7) has a sharp. */
+export declare function whiteIdxHasSharp(idx: number): boolean;
+export interface LayoutOptions {
+    padding?: number;
+    startingNote?: string;
+    spanFrom?: string;
+    spanTo?: string;
+}
+export interface LayoutResult {
+    startFrom: WhiteNote;
+    size: number;
+    /** Relative octave where the lowest chord note sits (for octave-qualified highlights). */
+    chordOctave: number;
+    /** True when the left edge was extended for black-key context (crop half a key). */
+    clipLeft?: boolean;
+    /** True when the right edge was extended for black-key context (crop half a key). */
+    clipRight?: boolean;
+}
+export declare function calculateLayout(notes: string[], options?: LayoutOptions): LayoutResult;

package/dist/resolver/auto-layout.js

@@ -0,0 +1,195 @@
+import { WHITE_NOTE_ORDER } from "../engine/svg-constants";
+import { normalizeToSharps } from "../engine/note-spelling";
+// White notes that have a sharp (black key to their right)
+const HAS_SHARP = new Set(["C", "D", "F", "G", "A"]);
+/** Check if a white-key index (mod 7) has a sharp. */
+export function whiteIdxHasSharp(idx) {
+    return HAS_SHARP.has(WHITE_NOTE_ORDER[((idx % 7) + 7) % 7]);
+}
+// Map a note to its nearest white key (the white key it sits on or just below)
+function nearestWhiteKey(note) {
+    const normalized = normalizeToSharps(note);
+    const base = normalized.replace("#", "");
+    return base;
+}
+// Count white keys from one white note to another (inclusive of start, exclusive of end)
+function whiteKeySpan(from, to) {
+    const fromIdx = WHITE_NOTE_ORDER.indexOf(from);
+    let toIdx = WHITE_NOTE_ORDER.indexOf(to);
+    if (toIdx < fromIdx)
+        toIdx += 7;
+    return toIdx - fromIdx;
+}
+/**
+ * Ensure the visible keyboard range doesn't cut through the middle of a
+ * black-key group, making orientation difficult.
+ *
+ * Piano keys form repeating groups:
+ * - 2-group: C(0), D(1), E(2)       — black keys C#, D#
+ * - 3-group: F(3), G(4), A(5), B(6) — black keys F#, G#, A#
+ *
+ * Rule: if the keyboard starts or ends in the INTERIOR of a group
+ * (not at its boundary), extend outward to the nearest group boundary.
+ * Starting/ending at a group boundary (C, F, E, B) is fine — the edge
+ * itself provides enough orientation context.
+ */
+function ensureFullBlackKeyGroups(startIdx, endIdx) {
+    // Determine which position within a group the start/end falls
+    // Group boundaries: C(0)=start of 2-group, F(3)=start of 3-group
+    // Interior: D(1), E(2) are interior of 2-group; G(4), A(5) are interior of 3-group
+    // B(6) is the end of the 3-group — a boundary, fine to start/end on
+    const startMod = ((startIdx % 7) + 7) % 7;
+    const endMod = ((endIdx % 7) + 7) % 7;
+    // Fix left edge: if we start in the interior of a group, extend left to group start.
+    // Group boundaries (OK to start on): C(0), F(3), E(2)→end of 2-group, B(6)→end of 3-group
+    // Interior (confusing): D(1), G(4), A(5)
+    if (startMod === 1)
+        startIdx -= 1; // D → extend to C
+    if (startMod === 4)
+        startIdx -= 1; // G → extend to F
+    if (startMod === 5)
+        startIdx -= 2; // A → extend to F
+    // Fix right edge: if we end in the interior of a group, extend right to group end.
+    // Group boundaries (OK to end on): E(2), B(6), C(0)→start of 2-group, F(3)→start of 3-group
+    // Interior (confusing): D(1), G(4), A(5)
+    if (endMod === 1)
+        endIdx += 1; // D → extend to E
+    if (endMod === 4)
+        endIdx += 2; // G → extend to B
+    if (endMod === 5)
+        endIdx += 1; // A → extend to B
+    return { startIdx, endIdx };
+}
+export function calculateLayout(notes, options = {}) {
+    const { padding = 1, startingNote, spanFrom, spanTo } = options;
+    // Explicit starting note: anchor the keyboard there
+    if (startingNote) {
+        const anchorKey = nearestWhiteKey(startingNote);
+        let startIdx = WHITE_NOTE_ORDER.indexOf(anchorKey) - padding;
+        // Black-key context: extend left edge if it has a sharp
+        let clipLeft = false;
+        if (whiteIdxHasSharp(startIdx)) {
+            startIdx -= 1;
+            clipLeft = true;
+        }
+        const start = WHITE_NOTE_ORDER[((startIdx % 7) + 7) % 7];
+        // Size the keyboard to fit all notes with padding on the right
+        if (notes.length > 0) {
+            const whiteKeys = notes.map(nearestWhiteKey);
+            // Treat notes as ascending from the anchor: each note at or below
+            // the previous wraps into the next octave (matches voicing rotation).
+            const anchorWhiteIdx = WHITE_NOTE_ORDER.indexOf(anchorKey);
+            const indices = [];
+            for (const w of whiteKeys) {
+                let idx = WHITE_NOTE_ORDER.indexOf(w);
+                if (indices.length === 0) {
+                    // First note: place relative to anchor (must be >= anchor)
+                    while (idx < anchorWhiteIdx)
+                        idx += 7;
+                }
+                else {
+                    // Subsequent notes: must be above the previous
+                    const lastIdx = indices[indices.length - 1];
+                    while (idx <= lastIdx)
+                        idx += 7;
+                }
+                indices.push(idx);
+            }
+            const maxIdx = Math.max(...indices);
+            let endIdx = maxIdx + padding;
+            // Black-key context: extend right edge if it lands on a sharp key
+            let clipRight = false;
+            if (whiteIdxHasSharp(endIdx)) {
+                endIdx += 1;
+                clipRight = true;
+            }
+            // Ensure full black-key groups are visible
+            const expanded = ensureFullBlackKeyGroups(startIdx, endIdx);
+            startIdx = expanded.startIdx;
+            endIdx = expanded.endIdx;
+            const finalStart = WHITE_NOTE_ORDER[((startIdx % 7) + 7) % 7];
+            let span = endIdx - startIdx + 1;
+            // chordOctave: count C crossings from start to the anchor note
+            const anchorIdx = WHITE_NOTE_ORDER.indexOf(anchorKey);
+            const startNoteIdx = WHITE_NOTE_ORDER.indexOf(finalStart);
+            const rawSteps = ((anchorIdx - startNoteIdx) % 7 + 7) % 7;
+            // Only add a full octave if the modular distance is 0 (anchor == start)
+            // AND there is padding (meaning the anchor is actually one octave away)
+            const stepsToAnchor = rawSteps === 0 && padding > 0 ? 7 : rawSteps;
+            let chordOctave = 0;
+            for (let i = 1; i <= stepsToAnchor; i++) {
+                if (WHITE_NOTE_ORDER[(startNoteIdx + i) % 7] === "C")
+                    chordOctave++;
+            }
+            return { startFrom: finalStart, size: Math.max(span, notes.length + 2), chordOctave, clipLeft, clipRight };
+        }
+        return { startFrom: start, size: 8, chordOctave: 0, clipLeft };
+    }
+    if (spanFrom && spanTo) {
+        const from = nearestWhiteKey(spanFrom);
+        const to = nearestWhiteKey(spanTo);
+        const span = whiteKeySpan(from, to);
+        return {
+            startFrom: from,
+            size: span === 0 ? 8 : span + 1,
+            chordOctave: 0,
+        };
+    }
+    if (notes.length === 0) {
+        return { startFrom: "C", size: 8, chordOctave: 0 };
+    }
+    // Treat notes as an ascending sequence: each note that is at or below
+    // the previous one (in white-key index) wraps into the next octave.
+    const whiteKeys = notes.map(nearestWhiteKey);
+    const ascending = [];
+    for (const w of whiteKeys) {
+        let idx = WHITE_NOTE_ORDER.indexOf(w);
+        if (ascending.length > 0) {
+            const lastIdx = ascending[ascending.length - 1];
+            while (idx <= lastIdx)
+                idx += 7;
+        }
+        ascending.push(idx);
+    }
+    const minAsc = ascending[0];
+    const maxAsc = ascending[ascending.length - 1];
+    let startIdx = minAsc - padding;
+    let endIdx = maxAsc + padding;
+    // Black-key context padding: if an edge white key has a sharp, extend by 1
+    // so the neighboring black key is visible, giving orientation landmarks.
+    let clipLeft = false;
+    let clipRight = false;
+    if (whiteIdxHasSharp(startIdx)) {
+        startIdx -= 1;
+        clipLeft = true;
+    }
+    if (whiteIdxHasSharp(endIdx)) {
+        endIdx += 1;
+        clipRight = true;
+    }
+    // Ensure full black-key groups are visible for keyboard orientation.
+    // If we can see part of the 3-group (F-B) or 2-group (C-E), show all of it.
+    const expanded = ensureFullBlackKeyGroups(startIdx, endIdx);
+    startIdx = expanded.startIdx;
+    endIdx = expanded.endIdx;
+    const startNote = WHITE_NOTE_ORDER[((startIdx % 7) + 7) % 7];
+    const keyCount = endIdx - startIdx + 1;
+    // Calculate which relative octave the chord notes live in.
+    // Count how many times we cross C going from startNote to the first chord note.
+    const actualPadding = minAsc - startIdx;
+    const startNoteIdx = WHITE_NOTE_ORDER.indexOf(startNote);
+    let chordOctave = 0;
+    for (let i = 1; i <= actualPadding; i++) {
+        const noteIdx = (startNoteIdx + i) % 7;
+        if (WHITE_NOTE_ORDER[noteIdx] === "C")
+            chordOctave++;
+    }
+    return {
+        startFrom: startNote,
+        size: Math.max(keyCount, notes.length + 2),
+        chordOctave,
+        clipLeft,
+        clipRight,
+    };
+}
+//# sourceMappingURL=auto-layout.js.map

package/dist/resolver/auto-layout.js.map

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

package/dist/resolver/chord-resolver.d.ts

@@ -0,0 +1,8 @@
+export interface ResolvedChord {
+    notes: string[];
+    root: string;
+    type: string;
+    /** Tonal interval names when available (e.g. ["1P", "3M", "5P", "7M"]) */
+    intervals?: string[];
+}
+export declare function resolveChord(chordName: string, inversion?: number): ResolvedChord;

package/dist/resolver/chord-resolver.js

@@ -0,0 +1,172 @@
+import { Chord, Note } from "tonal";
+/**
+ * Simplify a note name via Tonal without forcing sharp spelling.
+ * Tonal's simplify already respects musical context (e.g. Bb stays Bb).
+ */
+function simplifyNote(note) {
+    const simplified = Note.simplify(note);
+    return simplified || note;
+}
+// Alteration tokens we can strip and re-apply as intervals
+const ALTERATION_RE = /([#b](?:5|9|11|13)|add(?:9|11|13|b9|#9|b13|#11))$/;
+const ALTERATION_TO_INTERVAL = {
+    "#5": "5A",
+    "b5": "5d",
+    "#9": "2A",
+    "b9": "2m",
+    "#11": "4A",
+    "b11": "4d",
+    "#13": "6A",
+    "b13": "6m",
+    "add9": "2M",
+    "add11": "4P",
+    "add13": "6M",
+    "addb9": "2m",
+    "add#9": "2A",
+    "add#11": "4A",
+    "addb13": "6m",
+};
+// Try to resolve by stripping trailing alterations one at a time,
+// then transposing the root by those intervals to get extra notes
+function resolveWithFallback(chordName) {
+    // Extract root note
+    const rootMatch = chordName.match(/^([A-G][#b]?)/);
+    if (!rootMatch)
+        return null;
+    const root = rootMatch[1];
+    let suffix = chordName.slice(root.length);
+    const extraIntervals = [];
+    // Strip alterations from the end until Tonal recognizes the base
+    let attempts = 0;
+    while (suffix && attempts < 5) {
+        const match = suffix.match(ALTERATION_RE);
+        if (!match)
+            break;
+        const token = match[1];
+        const interval = ALTERATION_TO_INTERVAL[token];
+        if (!interval)
+            break;
+        extraIntervals.unshift(interval);
+        suffix = suffix.slice(0, -token.length);
+        attempts++;
+        const chord = Chord.get(root + suffix);
+        if (!chord.empty) {
+            let notes = chord.notes.map(simplifyNote);
+            // Add extra notes from stripped alterations
+            for (const ivl of extraIntervals) {
+                const extra = Note.transpose(root, ivl);
+                if (extra) {
+                    const normalized = simplifyNote(extra);
+                    // Replace if same degree already exists, otherwise add
+                    if (!notes.includes(normalized)) {
+                        notes.push(normalized);
+                    }
+                }
+            }
+            return { notes, root: simplifyNote(root), type: chord.type + " (extended)" };
+        }
+    }
+    return null;
+}
+// Normalize chord symbols that Tonal doesn't recognize into equivalents
+function normalizeChordName(name) {
+    // Extract root note first
+    const rootMatch = name.match(/^([A-G][#b]?)/i);
+    if (!rootMatch)
+        return name;
+    const root = rootMatch[1];
+    let suffix = name.slice(root.length);
+    // m7sus is special — handled by buildSpecialChord, don't normalize it away
+    // Cmaug → Cm#5 (minor augmented)
+    suffix = suffix.replace(/^maug$/i, "m#5");
+    // Cm6/9 → Cm6add9 (Tonal doesn't know m6/9 but knows the notes)
+    // Actually build it manually below via special handling
+    // CmMaj → CmM (Tonal recognizes mM but not mmaj for some roots)
+    // Dbmmaj7 → DbmMaj7 — ensure proper casing
+    suffix = suffix.replace(/mmaj/i, "mMaj");
+    // omit3 → remove, we'll handle it post-resolution
+    // Keep it for now, handle in resolveChord
+    return root + suffix;
+}
+// Special chord builders for symbols Tonal can't handle at all
+function buildSpecialChord(name) {
+    const rootMatch = name.match(/^([A-G][#b]?)/i);
+    if (!rootMatch)
+        return null;
+    const root = rootMatch[1];
+    const suffix = name.slice(root.length);
+    // X7omit3 → root, 5th, b7 (no 3rd)
+    if (/^7omit3$/i.test(suffix)) {
+        return {
+            notes: [root, Note.transpose(root, "5P"), Note.transpose(root, "7m")].map(simplifyNote),
+            root: simplifyNote(root),
+            type: "7omit3",
+        };
+    }
+    // Xm7sus / Xm7sus4 → root, m3, P4, m7
+    if (/^m7sus4?$/i.test(suffix)) {
+        return {
+            notes: [
+                root,
+                Note.transpose(root, "3m"),
+                Note.transpose(root, "4P"),
+                Note.transpose(root, "7m"),
+            ].map(simplifyNote),
+            root: simplifyNote(root),
+            type: "m7sus4",
+        };
+    }
+    // Xm6/9 → root, m3, 5, 6, 9
+    if (/^m6\/9$/i.test(suffix)) {
+        return {
+            notes: [
+                root,
+                Note.transpose(root, "3m"),
+                Note.transpose(root, "5P"),
+                Note.transpose(root, "6M"),
+                Note.transpose(root, "2M"),
+            ].map(simplifyNote),
+            root: simplifyNote(root),
+            type: "m6/9",
+        };
+    }
+    return null;
+}
+export function resolveChord(chordName, inversion) {
+    chordName = normalizeChordName(chordName);
+    const chord = Chord.get(chordName);
+    let notes;
+    let root;
+    let type;
+    let intervals;
+    // Try special chord builders first (omit3, m6/9, etc.)
+    const special = buildSpecialChord(chordName);
+    if (special) {
+        notes = special.notes;
+        root = special.root;
+        type = special.type;
+    }
+    else if (!chord.empty) {
+        notes = chord.notes.map(simplifyNote);
+        root = simplifyNote(chord.tonic ?? notes[0]);
+        type = chord.type;
+        intervals = chord.intervals;
+    }
+    else {
+        // Fallback: strip trailing alterations and reapply as intervals
+        const fallback = resolveWithFallback(chordName);
+        if (!fallback) {
+            throw new Error(`Unknown chord: "${chordName}"`);
+        }
+        notes = fallback.notes;
+        root = fallback.root;
+        type = fallback.type;
+    }
+    // Apply inversion: rotate notes array
+    if (inversion && inversion > 0) {
+        const rotation = inversion % notes.length;
+        notes = [...notes.slice(rotation), ...notes.slice(0, rotation)];
+    }
+    return { notes, root, type, intervals };
+}
+//# sourceMappingURL=chord-resolver.js.map

package/dist/resolver/chord-resolver.js.map

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