@pepperhorn/chordl-core 0.3.1 → 0.4.0

package/dist/parser/natural-language.js

@@ -1,4 +1,45 @@
-const FILLER_WORDS = /\b(show\s+me|draw|display|render|please|a|an|the|with|that|this|me|of)\b/gi;
+import { resolveChord } from "../resolver/chord-resolver.js";
+// Filler runs in two passes, and the order is load-bearing.
+//
+// The articles "a"/"an" are also the note A, and by the time filler is stripped
+// every modifier has already been cut out — so "A with note names" arrives as
+// "A ", and so does "a compact". The residual cannot tell them apart, because
+// the article's own noun is one of the things that was deleted.
+//
+// So the article pass decides on evidence the stripping cannot destroy: the
+// character after it, the capital letter the user typed, and where the token
+// sat in the original input. See `stripArticles`.
+const FILLER_WORDS = /\b(show\s+me|draw|display|render|please|the|with|that|this|me|of)\b/gi;
+const ARTICLE_RE = /\b(an?)\b/gi;
+/** An article at the very end of the *original* input is the note A: "a", "an A". */
+const ARTICLE_AT_INPUT_END = /\ban?(?=[#/]|\s*$)/i;
+/**
+ * Remove English articles without eating the note A.
+ *
+ * Three things say "this is the note, not an article", none of which an earlier
+ * `.replace` can have invented:
+ *
+ *  - what follows is `#` or `/` — only a root can be ("A#dim", "A/C#");
+ *  - the token is a capital `A`, which is how a chord is written and not how an
+ *    article is ("A minor", "A with note names", "A in second inversion");
+ *  - the article ends the original input ("a", "show me an A").
+ *
+ * Anything else is an article, including one left trailing because its noun was
+ * stripped — "in a compact layout" must not resolve to the chord A.
+ */
+function stripArticles(text, input) {
+    const bareArticleAtEnd = ARTICLE_AT_INPUT_END.test(input);
+    return text.replace(ARTICLE_RE, (token, _g, offset, whole) => {
+        const rest = whole.slice(offset + token.length);
+        if (/^[#/]/.test(rest))
+            return token;
+        if (token === "A")
+            return token;
+        if (/^\s*$/.test(rest) && bareArticleAtEnd)
+            return token;
+        return "";
+    });
+}
 const FORMAT_RE = /\b(compact|exact|full)\b/i;
 const FORMAT_FULL_RE = /\bfull\s+(?:layout|height|size|keys?)\b/i;
 // "size 80" / "size 80%" / "size 0.8" / "size xl" / "keys xl"
@@ -51,7 +92,7 @@ const FINGERING_RE = /(?:with\s+)?finger(?:ing|s)?\s+([\dxX\-](?:[,\s\-]*[\dxX\-
 const VALID_FINGERING = new Set(["0", "1", "2", "3", "4", "5", "-", "x"]);
 // "custom fingering "A0,A1,A2"" / "fingering "G3-G0-E1"" / "fingering xl "1-2-3"" / "fingering "1-2-3" 2xl"
 // Quoted strings after "fingering" or "custom fingering" are treated as free-form labels.
-const CUSTOM_FINGERING_RE = /(?:with\s+)?(?:custom\s+)?finger(?:ing|s)?\s+(?:(?:in\s+)?(base|lg|xl|2xl)\s+)?[""]([^""]+)[""](?:\s+(?:in\s+)?(base|lg|xl|2xl))?/i;
+const CUSTOM_FINGERING_RE = /(?:with\s+)?(?:custom\s+)?finger(?:ing|s)?\s+(?:(?:in\s+)?(base|lg|xl|2xl)\s+)?["“”']([^"“”']+)["“”'](?:\s+(?:in\s+)?(base|lg|xl|2xl))?/i;
 // "with fingerings" / "show fingering" / "with fingering in xl" / "fingering 2xl" (no explicit numbers → auto)
 // Negative lookahead: don't match when followed by digits (explicit fingering like "1 2 3 5")
 const AUTO_FINGERING_RE = /(?:with\s+)?(?:show\s+)?finger(?:ings?|s)?(?:\s+(?:in\s+)?(base|lg|xl|2xl)|\s+(base|lg|xl|2xl))?(?!\s+\d)(?:\s|$)/i;
@@ -69,20 +110,134 @@ const UNAMBIGUOUS_SCALE_TYPES = [
     "major\\s+pentatonic", "minor\\s+pentatonic", "pentatonic",
     "blues", "whole\\s+tone", "bebop", "diminished",
 ];
-// Scale patterns: "D major scale", "C blues", "A dorian", etc.
+// Scale patterns: "D major scale", "C blues", "A dorian", "Dm harmonic minor".
 // For "major"/"minor" alone, require the trailing word "scale" to avoid chord collision.
-const SCALE_UNAMBIGUOUS_RE = new RegExp(`([A-Ga-g][#b]?)\\s+(${UNAMBIGUOUS_SCALE_TYPES.join("|")})(?:\\s+scale)?`, "i");
-const SCALE_EXPLICIT_RE = /([A-Ga-g][#b]?)\s+(major|minor)\s+scale/i;
+//
+// The root must not be preceded by a letter, or the trailing "c" of
+// "harmonic"/"melodic" is read as a root note and "dm harmonic minor" resolves
+// to C minor. An optional chord-quality marker may sit between the root and the
+// scale type, so shorthand roots ("dm", "f#m", "dmaj") work the same as bare
+// ones — the named scale type wins, the marker is only there to be absorbed.
+const ROOT = "(?<![A-Za-z#b])([A-Ga-g][#b]?)";
+const QUALITY_MARKER = "(?:\\s*(?:maj|min|m|M)\\b)?";
+const SCALE_UNAMBIGUOUS_RE = new RegExp(`${ROOT}${QUALITY_MARKER}\\s+(${UNAMBIGUOUS_SCALE_TYPES.join("|")})(?:\\s+scale)?`, "i");
+const SCALE_EXPLICIT_RE = new RegExp(`${ROOT}${QUALITY_MARKER}\\s+(major|minor)\\s+scale`, "i");
+// Chord-shorthand scales: "dm scale", "d maj scale", "dmaj scale", "d scale".
+// Only the major/minor markers — anything richer stays a chord. The word
+// "scale" is required, so a bare "Dm" is still a chord.
+// The quality marker is matched case-insensitively but read case-sensitively,
+// since "M" means major and "m" means minor.
+const SCALE_SHORTHAND_RE = /(?<![A-Za-z#b])([A-Ga-g][#b]?)\s*(major|maj|minor|min|M|m)?\s+scale\b/i;
+/** Resolve a shorthand quality marker to a scale type. Absent marker = major. */
+function shorthandScaleType(marker) {
+    if (!marker)
+        return "major";
+    if (marker === "M")
+        return "major";
+    if (marker === "m")
+        return "minor";
+    return marker.toLowerCase().startsWith("min") ? "minor" : "major";
+}
 // "ascending" / "descending" for melodic minor
 const DIRECTION_RE = /\b(ascending|descending)\b/i;
 // "in N octaves" / "N octaves" — works for both scales and arpeggios
 const OCTAVES_RE = /\b(?:in\s+)?(\d+)\s+octaves?\b/i;
-// "with degrees" / "with degrees in xl" / "with note names and degrees in lg"
-const DEGREE_DISPLAY_RE = /\bwith\s+(?:note\s+names?\s+and\s+)?degrees?(?:\s+(?:in\s+)?(base|lg|xl|2xl))?\b/i;
-const DEGREE_ONLY_RE = /\bwith\s+degrees?(?:\s+(?:in\s+)?(base|lg|xl|2xl))?\b/i;
-const NAMES_AND_DEGREES_RE = /\bwith\s+note\s+names?\s+and\s+degrees?(?:\s+(?:in\s+)?(base|lg|xl|2xl))?\b/i;
+// "degrees" anywhere — combined with note names if present, standalone otherwise.
+// The literal word "degree(s)" isn't used by any other parser rule
+// (bass-degree / starting-degree use "5th", "9th", etc.), so a broad match is safe.
+/*
+ * Two forms, because only one of them is unambiguous.
+ *
+ * "degrees in lg" names the degrees' own size and always keeps it. "degrees lg"
+ * is a bare size between two keywords, and NOTE_NAMES_RE accepts exactly that
+ * shape in front of its own keyword ("lg note names") — so in "degrees 2xl note
+ * names" the size belongs to what follows it, not to what precedes it. Without
+ * the lookahead the degrees clause swallowed it and the note names silently
+ * fell back to the default.
+ */
+const DEGREES_KEYWORD_RE = /\bdegrees?(?:\s+(?:in\s+(base|lg|xl|2xl)|(base|lg|xl|2xl)(?!\s+(?:midi\s+)?note\s*names?)))?\b/i;
 // "with heading" / "with a heading" / "show heading"
 const HEADING_RE = /\b(?:with\s+)?(?:a\s+)?(?:show\s+)?heading\b/i;
+// All recognized hand/clef phrases — long forms before shorthand to ensure
+// the longest alternative is matched first under JS regex alternation.
+const HAND_CLEF_PATTERN = "left\\s+hand|right\\s+hand|bottom\\s+hand|top\\s+hand|bass\\s+clef|treble\\s+clef|l\\.?h\\.?|r\\.?h\\.?|lh|rh|left|right|bottom|top|bass|treble";
+// 2+ note tokens separated by spaces/commas/dashes; "and" allowed between tokens.
+// Single-letter notes (A-G) plus optional accidental (#/b) and optional single-digit octave.
+const NOTE_LIST_PATTERN = "[A-Ga-g][#b]?\\d?(?:[\\s,\\-]+(?:and\\s+)?[A-Ga-g][#b]?\\d?)+";
+// After the explicit "notes" keyword, a token may be a run-together sequence
+// of notes with no separators ("cdefgabc", "EbGbBb", "E4G4C5"). The trailing
+// lookahead stops the run at any non-note word ("and", "in", "with", ...)
+// while still allowing a run to end in an accidental ("C#").
+const NOTE_RUN_PATTERN = "(?:[A-Ga-g][#b]?\\d?)+(?![A-Za-z0-9])";
+// "with notes C E G" / "notes E4 G4 C5" / "notes cdefgabc" — optional
+// trailing "in <hand|clef>".
+const NOTES_GROUP_RE = new RegExp(`(?:with\\s+|and\\s+)?notes\\s+(${NOTE_RUN_PATTERN}(?:[\\s,\\-]+${NOTE_RUN_PATTERN})*)(?:\\s+in\\s+(?:the\\s+)?(${HAND_CLEF_PATTERN}))?`, "gi");
+// "notes in lh Eb Gb Bb" / "notes in the right hand D F A" — prefix form.
+const NOTES_GROUP_PREFIX_RE = new RegExp(`(?:with\\s+|and\\s+)?notes\\s+in\\s+(?:the\\s+)?(${HAND_CLEF_PATTERN})\\s+(${NOTE_RUN_PATTERN}(?:[\\s,\\-]+${NOTE_RUN_PATTERN})*)`, "gi");
+// "lh Eb Gb Bb" / "lh: Eb Gb Bb" / "left Eb Gb Bb" / "bass clef C E G"
+// Hand keyword first, no "notes" word. Optional colon between hand and notes.
+const HAND_PREFIX_BARE_RE = new RegExp(`\\b(${HAND_CLEF_PATTERN})\\s*(?::\\s*|\\s+)(${NOTE_LIST_PATTERN})`, "gi");
+// "Eb Gb Bb in lh" / "Eb Gb Bb lh" / "(Eb Gb Bb) lh" — notes first, hand after.
+// "in" is optional. Surrounding parens optional. Requires 2+ notes to avoid
+// swallowing chord symbols like "G7 in lh".
+const NOTES_BARE_HAND_RE = new RegExp(`\\(?\\b(${NOTE_LIST_PATTERN})\\b\\)?\\s*(?:in\\s+(?:the\\s+)?)?(${HAND_CLEF_PATTERN})\\b`, "gi");
+// Single bare note + hand variants. Restricted to [A-G][#b]? with no octave
+// digit and no chord-quality suffix — that way "G7 in lh" / "Bb7 in lh" stay
+// chord symbols (no \b between letter and digit), but "Bb in lh" works.
+const SINGLE_NOTE_PATTERN = "[A-Ga-g][#b]?";
+// "lh Bb" / "lh: Bb" / "left Bb" / "bass clef C" — hand keyword + single note.
+// Lookahead requires the note to be followed by whitespace, comma, semicolon,
+// or end-of-string so "lh G7" doesn't absorb G as a note.
+const HAND_PREFIX_SINGLE_RE = new RegExp(`\\b(${HAND_CLEF_PATTERN})\\s*(?::\\s*|\\s+)(${SINGLE_NOTE_PATTERN})(?=[\\s,;]|$)`, "gi");
+// "Bb in lh" / "Bb lh" / "(Bb) lh" — single bare note + hand.
+const NOTE_BARE_HAND_SINGLE_RE = new RegExp(`\\(?\\b(${SINGLE_NOTE_PATTERN})\\b\\)?\\s*(?:in\\s+(?:the\\s+)?)?(${HAND_CLEF_PATTERN})\\b`, "gi");
+// A chord symbol following a hand keyword: "rh Cmaj7", "lh: Bbm7b5",
+// "left hand Am", "bass clef G7/B". Deliberately permissive — the token is
+// validated by actually resolving it as a chord, so junk never becomes a group.
+const CHORD_TOKEN_PATTERN = "[A-Ga-g][#b]?[A-Za-z0-9#b\\u00b0\\u00f8+\\-/]*";
+// "rh Cmaj7 lh Dm7" — hand keyword + chord symbol(s). The trailing group
+// captures any further chord tokens so "rh Cmaj7 Dm7" can drop the second one:
+// only the first chord after a hand keyword is used.
+const HAND_PREFIX_CHORD_RE = new RegExp(`\\b(${HAND_CLEF_PATTERN})\\s*(?::\\s*|\\s+)(${CHORD_TOKEN_PATTERN})((?:\\s+${CHORD_TOKEN_PATTERN})*)`, "gi");
+// A plain pitch class ("C", "Eb") — the single-note pass already claims those.
+// Tokens carrying a digit ("G7", "C9") read as chords here, matching how
+// "G7 in lh" / "Bb7 in lh" are treated elsewhere in this parser; an
+// octave-qualified note needs the explicit "notes" keyword ("notes G7 in lh").
+const BARE_NOTE_TOKEN_RE = /^[A-Ga-g][#b]?$/;
+/**
+ * Resolve a token as a chord symbol, or undefined when it isn't one.
+ * Bare pitches are rejected so "lh Bb" stays a single-note assignment.
+ */
+function chordTokenNotes(token) {
+    if (BARE_NOTE_TOKEN_RE.test(token))
+        return undefined;
+    try {
+        const { notes } = resolveChord(token);
+        return notes.length > 0 ? notes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// "Eb Gb Bb // Db Eb F Gb" — polychord-style "top over bottom" (rh then lh).
+const POLYCHORD_SLASH_RE = new RegExp(`(${NOTE_LIST_PATTERN})\\s*\\/\\/\\s*(${NOTE_LIST_PATTERN})`, "gi");
+// "Eb Gb Bb; Db Eb F Gb" — semicolon separator; reading order (lh then rh).
+const SEMI_SEP_RE = new RegExp(`(${NOTE_LIST_PATTERN})\\s*;\\s*(${NOTE_LIST_PATTERN})`, "gi");
+/** Normalize a captured hand/clef phrase to (hand, clef) tuple. */
+function parseHandOrClef(raw) {
+    if (!raw)
+        return {};
+    const h = raw.toLowerCase().replace(/[\s.:]/g, "");
+    if (h === "bassclef" || h === "bass")
+        return { clef: "bass", hand: "lh" };
+    if (h === "trebleclef" || h === "treble")
+        return { clef: "treble", hand: "rh" };
+    if (h === "lefthand" || h === "bottomhand" || h === "lh" || h === "left" || h === "bottom")
+        return { hand: "lh" };
+    if (h === "righthand" || h === "tophand" || h === "rh" || h === "right" || h === "top")
+        return { hand: "rh" };
+    return {};
+}
 // "boomwhacker" / "with boomwhacker theme" / "crf theme" / "rainbow"
 const THEME_RE = /\b(?:(?:with\s+)?(?:the\s+)?)?(?:(boomwhacker|boomwhackers|crf|rainbow)\s*(?:theme|colors?|colours?)?)\b/i;
 const THEME_MAP = {
@@ -105,7 +260,12 @@ const QUALITY_WORDS = {
     eleventh: "11",
     thirteenth: "13",
 };
-const CHORD_RE = /([A-Ga-g][#b]?)\s*(maj|min|m|aug|dim|sus|add|dom|M|°|ø|[0-9#b/]+)*/i;
+// Slash-bass is captured as its own group (any note letter, not just B) rather
+// than folded into the quality-suffix class — the old catch-all `[0-9#b/]+`
+// let '/' bleed into the flat-symbol 'b', so only B/Bb bass notes round-tripped.
+// `\/[0-9]+` stays in the quality group so "6/9"-style suffixes (slash
+// followed by digits, not a bass letter) aren't mistaken for a slash bass.
+const CHORD_RE = /([A-Ga-g][#b]?)\s*(maj|min|m|aug|dim|sus|add|dom|M|°|ø|\/[0-9]+|[0-9#b]+)*(\/[A-Ga-g][#b]?)?/i;
 function capitalizeNote(note) {
     return note.charAt(0).toUpperCase() + note.slice(1);
 }
@@ -182,8 +342,16 @@ export function parseChordDescription(input) {
         const isDown = direction === "down" || direction === "lower";
         result.bassOctaveShift = isDown ? -count : count;
     }
+    /*
+     * Note-name sizes are read from the input with the degrees clause taken out.
+     * NOTE_NAMES_RE accepts a size *before* the keyword ("xl note names"), so in
+     * "with degrees in base note names in 2xl" it read the degrees' own "base" as
+     * the note-name size. Two clauses that each carry a size must not be able to
+     * read each other's.
+     */
+    const sizeSource = input.replace(DEGREES_KEYWORD_RE, " ");
     // Extract "midi note names" / "with midi names" (check before regular note names)
-    const midiNamesMatch = input.match(MIDI_NAMES_RE);
+    const midiNamesMatch = sizeSource.match(MIDI_NAMES_RE);
     if (midiNamesMatch) {
         result.showNoteNames = true;
         result.noteNameMode = "midi";
@@ -191,7 +359,7 @@ export function parseChordDescription(input) {
     }
     // Extract "with note names" / "note names in xl" / "xl note names"
     if (!midiNamesMatch) {
-        const noteNamesMatch = input.match(NOTE_NAMES_RE);
+        const noteNamesMatch = sizeSource.match(NOTE_NAMES_RE);
         if (noteNamesMatch) {
             result.showNoteNames = true;
             // Size can be in group 1 (before "note names"), 2 (after), or 3 ("name the notes in xl")
@@ -206,7 +374,13 @@ export function parseChordDescription(input) {
     // Check custom fingering FIRST ("custom fingering A0,A1,A2")
     const customFingerMatch = input.match(CUSTOM_FINGERING_RE);
     if (customFingerMatch) {
-        result.customFingering = customFingerMatch[2].split(/[,\-\s]+/).filter(Boolean);
+        // Comma-separated lists split ONLY on commas/spaces so "-" placeholders
+        // survive as positional blanks ("1,-,3"); dash-separated lists keep the
+        // documented "D2-D1-D0-D1" behavior.
+        const raw = customFingerMatch[2];
+        result.customFingering = (raw.includes(",")
+            ? raw.split(/[,\s]+/)
+            : raw.split(/[\-\s]+/)).filter(Boolean);
         result.fingeringSize = toTextSize(customFingerMatch[1]) ?? toTextSize(customFingerMatch[3]);
     }
     // Check auto fingering ("with fingering", "fingering 2xl", "fingering in xl")
@@ -271,27 +445,217 @@ export function parseChordDescription(input) {
     if (HEADING_RE.test(input)) {
         result.showHeading = true;
     }
+    // Extract explicit notes group(s) — supports one or more "with notes ... [in <hand/clef>]"
+    // segments separated by "and" / "with". Paired example:
+    //   "notes C E G in bass clef and notes B D F in treble clef"
+    const groups = [];
+    // Explode a run-together token ("cdefgabc", "EbGbBb", "E4G4C5") into
+    // individual notes. In runs, a lowercase 'b' binds as a flat only after
+    // an UPPERCASE letter ("EbGbBb") — in lowercase runs like "cdefgabc"
+    // every letter is its own note, so 'b' stays the note B.
+    const explodeNoteRun = (token) => {
+        const out = [];
+        let i = 0;
+        while (i < token.length) {
+            const letter = token[i];
+            if (!/[A-Ga-g]/.test(letter))
+                return [token]; // not a pure note run
+            i++;
+            let accidental = "";
+            if (token[i] === "#") {
+                accidental = "#";
+                i++;
+            }
+            else if (token[i] === "b" && letter === letter.toUpperCase()) {
+                accidental = "b";
+                i++;
+            }
+            let octave = "";
+            if (/\d/.test(token[i] ?? "")) {
+                octave = token[i];
+                i++;
+            }
+            out.push(letter.toUpperCase() + accidental + octave);
+        }
+        return out;
+    };
+    const normalizeTokens = (raw) => raw
+        .split(/[\s,\-]+/)
+        .filter(Boolean)
+        .flatMap((t) => {
+        // Single-note tokens keep their exact old handling ("eb5" → Eb5,
+        // "bb" → Bb) — run explosion applies only to longer sequences.
+        const nm = t.match(/^([A-Ga-g])([#b])?(\d)?$/);
+        if (nm)
+            return [nm[1].toUpperCase() + (nm[2] ?? "") + (nm[3] ?? "")];
+        return explodeNoteRun(t);
+    });
+    // Note-group extraction runs in priority order. Each pass strips its matches
+    // from `residual` so later (looser) passes can't re-consume the same notes.
+    let residual = input;
+    // Hand-prefixed chord phrases actually consumed by pass 4d, so the chord-name
+    // pass below strips exactly those (and not look-alikes it rejected).
+    const handChordMatches = [];
+    const stripFromResidual = (match) => {
+        residual = residual.replace(match, " ");
+    };
+    const pushGroup = (tokens, hand, clef, chord) => {
+        const g = { notes: tokens };
+        if (hand)
+            g.hand = hand;
+        if (clef)
+            g.clef = clef;
+        if (chord)
+            g.chord = chord;
+        groups.push(g);
+    };
+    // 1. "notes in <hand> <notes>" (prefix with explicit "notes" keyword)
+    NOTES_GROUP_PREFIX_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(NOTES_GROUP_PREFIX_RE)]) {
+        const tokens = normalizeTokens(m[2]);
+        if (tokens.length === 0)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[1]);
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 2. "notes <notes> [in <hand>]" (suffix with explicit "notes" keyword)
+    NOTES_GROUP_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(NOTES_GROUP_RE)]) {
+        const tokens = normalizeTokens(m[1]);
+        if (tokens.length === 0)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[2]);
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 3. "lh Eb Gb Bb" / "lh: Eb Gb Bb" / "left Eb Gb Bb" / "bass clef C E G"
+    //    Hand keyword first, no "notes" word required.
+    HAND_PREFIX_BARE_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(HAND_PREFIX_BARE_RE)]) {
+        const tokens = normalizeTokens(m[2].replace(/\band\b/gi, " "));
+        if (tokens.length < 2)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[1]);
+        if (!hand && !clef)
+            continue;
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 4. "Eb Gb Bb in lh" / "Eb Gb Bb lh" / "(Eb Gb Bb) lh" — bare notes + hand.
+    NOTES_BARE_HAND_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(NOTES_BARE_HAND_RE)]) {
+        const tokens = normalizeTokens(m[1].replace(/\band\b/gi, " "));
+        if (tokens.length < 2)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[2]);
+        if (!hand && !clef)
+            continue;
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 4b. "lh Bb" / "lh: Bb" / "left Bb" — single bare note after hand keyword.
+    // Runs AFTER the multi-note passes so a 3-note group is preferred where
+    // both could match. Anything left here is a genuine single-note assignment.
+    HAND_PREFIX_SINGLE_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(HAND_PREFIX_SINGLE_RE)]) {
+        const tokens = normalizeTokens(m[2]);
+        if (tokens.length === 0)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[1]);
+        if (!hand && !clef)
+            continue;
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 4c. "Bb in lh" / "Bb lh" / "(Bb) lh" — single bare note before hand keyword.
+    NOTE_BARE_HAND_SINGLE_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(NOTE_BARE_HAND_SINGLE_RE)]) {
+        const tokens = normalizeTokens(m[1]);
+        if (tokens.length === 0)
+            continue;
+        const { hand, clef } = parseHandOrClef(m[2]);
+        if (!hand && !clef)
+            continue;
+        pushGroup(tokens, hand, clef);
+        stripFromResidual(m[0]);
+    }
+    // 4d. "rh Cmaj7 lh Dm7" — hand keyword + chord symbol. Runs after every
+    // bare-note pass so note lists still win; whatever is left here is a chord.
+    // Only the first chord after a hand keyword is used — trailing chords are
+    // dropped (and removed from the residual so they don't become the chord name).
+    HAND_PREFIX_CHORD_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(HAND_PREFIX_CHORD_RE)]) {
+        const { hand, clef } = parseHandOrClef(m[1]);
+        if (!hand && !clef)
+            continue;
+        const notes = chordTokenNotes(m[2]);
+        if (!notes)
+            continue;
+        pushGroup(notes, hand, clef, m[2]);
+        // Drop the run of extra chord tokens that directly follows, stopping at
+        // the first token that isn't a chord so unrelated text survives.
+        let extras = m[3] ?? "";
+        while (extras.length > 0) {
+            const next = extras.match(/^\s+(\S+)/);
+            if (!next || !chordTokenNotes(next[1]))
+                break;
+            extras = extras.slice(next[0].length);
+        }
+        const consumed = m[0].slice(0, m[0].length - extras.length);
+        handChordMatches.push(consumed);
+        stripFromResidual(consumed);
+    }
+    // 5. "Eb Gb Bb // Db Eb F Gb" — polychord-style "top over bottom" (rh, lh).
+    POLYCHORD_SLASH_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(POLYCHORD_SLASH_RE)]) {
+        const top = normalizeTokens(m[1].replace(/\band\b/gi, " "));
+        const bottom = normalizeTokens(m[2].replace(/\band\b/gi, " "));
+        if (top.length < 2 || bottom.length < 2)
+            continue;
+        pushGroup(top, "rh");
+        pushGroup(bottom, "lh");
+        stripFromResidual(m[0]);
+    }
+    // 6. "Eb Gb Bb; Db Eb F Gb" — semicolon separator; reading order (lh, rh).
+    SEMI_SEP_RE.lastIndex = 0;
+    for (const m of [...residual.matchAll(SEMI_SEP_RE)]) {
+        const first = normalizeTokens(m[1].replace(/\band\b/gi, " "));
+        const second = normalizeTokens(m[2].replace(/\band\b/gi, " "));
+        if (first.length < 2 || second.length < 2)
+            continue;
+        pushGroup(first, "lh");
+        pushGroup(second, "rh");
+        stripFromResidual(m[0]);
+    }
+    if (groups.length > 0) {
+        result.notesGroups = groups;
+    }
     // Extract color theme
     const themeMatch = input.match(THEME_RE);
     if (themeMatch) {
         result.colorTheme = THEME_MAP[themeMatch[1].toLowerCase()] ?? themeMatch[1].toLowerCase();
     }
-    // Extract degree display mode (before scale detection, since it applies to both)
-    const namesDegMatch = input.match(NAMES_AND_DEGREES_RE);
-    const degOnlyMatch = input.match(DEGREE_ONLY_RE);
-    if (namesDegMatch) {
-        result.showNoteNames = true;
-        result.noteNameMode = "pitch-class+degree";
-        const sz = toTextSize(namesDegMatch[1]);
-        if (sz)
-            result.noteNameSize = sz;
-    }
-    else if (degOnlyMatch) {
-        result.showNoteNames = true;
-        result.noteNameMode = "degree";
-        const sz = toTextSize(degOnlyMatch[1]);
+    // Degrees keyword is independent — combines with whichever note names are
+    // already detected, otherwise stands alone as degree-only mode. Midi names
+    // combine too: "midi note names with degrees" is a real request for two rows,
+    // and skipping the clause there dropped both the mode and the degree size, so
+    // the degrees the user asked for were silently never drawn.
+    const degMatch = input.match(DEGREES_KEYWORD_RE);
+    if (degMatch) {
+        if (result.showNoteNames) {
+            result.noteNameMode = result.noteNameMode === "midi" ? "midi+degree" : "pitch-class+degree";
+        }
+        else {
+            result.showNoteNames = true;
+            result.noteNameMode = "degree";
+        }
+        // Its own field. Writing it to noteNameSize meant the second size in
+        // "note names in xl with degrees in lg" overwrote the first, and both rows
+        // came out at lg — the note names silently demoted to the degrees' size.
+        const sz = toTextSize(degMatch[1]) ?? toTextSize(degMatch[2]);
         if (sz)
-            result.noteNameSize = sz;
+            result.degreeSize = sz;
     }
     // Extract scale direction
     const dirMatch = input.match(DIRECTION_RE);
@@ -301,10 +665,12 @@ export function parseChordDescription(input) {
     // Extract octave count (used by both scales and arpeggios)
     const octavesMatch = input.match(OCTAVES_RE);
     const octaveCount = octavesMatch ? parseInt(octavesMatch[1], 10) : undefined;
-    // Detect scales — check BEFORE chord extraction
+    // Detect scales — check BEFORE chord extraction. Spelled-out forms first,
+    // then chord shorthand ("dm scale"), so "d minor scale" keeps its own path.
     const scaleUnambig = input.match(SCALE_UNAMBIGUOUS_RE);
     const scaleExplicit = input.match(SCALE_EXPLICIT_RE);
     const scaleMatch = scaleUnambig || scaleExplicit;
+    const scaleShorthand = scaleMatch ? null : input.match(SCALE_SHORTHAND_RE);
     if (scaleMatch) {
         const scaleRoot = capitalizeNote(scaleMatch[1]);
         const scaleType = scaleMatch[2].toLowerCase().replace(/\s+/g, " ").trim();
@@ -312,6 +678,12 @@ export function parseChordDescription(input) {
         result.scaleName = `${scaleRoot} ${scaleType}`;
         result.scaleOctaves = octaveCount ?? 1;
     }
+    else if (scaleShorthand) {
+        const scaleRoot = capitalizeNote(scaleShorthand[1]);
+        result.isScale = true;
+        result.scaleName = `${scaleRoot} ${shorthandScaleType(scaleShorthand[2])}`;
+        result.scaleOctaves = octaveCount ?? 1;
+    }
     else if (octaveCount) {
         // Not a scale but has "N octaves" → arpeggio mode for chord
         result.chordOctaves = octaveCount;
@@ -325,8 +697,11 @@ export function parseChordDescription(input) {
     else if (startMatch) {
         result.startingNote = capitalizeNote(startMatch[1]);
     }
-    // Strip extracted patterns and filler for chord name extraction
-    let cleaned = input
+    // Strip extracted patterns and filler for chord name extraction. Chord
+    // phrases already claimed by a hand go first — they're plain substrings of
+    // the input, so removing them here keeps them out of the chord name.
+    let cleaned = handChordMatches
+        .reduce((text, phrase) => text.replace(phrase, " "), input)
         .replace(FORMAT_FULL_RE, "")
         .replace(FORMAT_RE, "")
         .replace(SIZE_NAME_RE, "")
@@ -339,6 +714,11 @@ export function parseChordDescription(input) {
         .replace(PADDING_RE, "")
         .replace(CHORD_OCTAVE_RE, "")
         .replace(BASS_OCTAVE_RE, "")
+        // Before NOTE_NAMES_RE, which matches the "note names" half on its own and
+        // would leave "midi" behind. The leftover word is not inert: CHORD_RE's
+        // quality class contains `m`, so "C midi" parsed as Cm, and an A root lost
+        // to FILLER_WORDS let the extractor find its root in the `d` of "midi".
+        .replace(MIDI_NAMES_RE, "")
         .replace(NOTE_NAMES_RE, "")
         .replace(CUSTOM_FINGERING_RE, "")
         .replace(FINGERING_RE, "")
@@ -350,14 +730,25 @@ export function parseChordDescription(input) {
         .replace(OVER_BASS_NOTE_RE, "")
         .replace(STARTING_DEGREE_RE, "")
         .replace(STARTING_NOTE_RE, "")
-        .replace(NAMES_AND_DEGREES_RE, "")
-        .replace(DEGREE_DISPLAY_RE, "")
+        .replace(DEGREES_KEYWORD_RE, "")
         .replace(DIRECTION_RE, "")
         .replace(OCTAVES_RE, "")
         .replace(SCALE_UNAMBIGUOUS_RE, "")
         .replace(SCALE_EXPLICIT_RE, "")
+        .replace(SCALE_SHORTHAND_RE, "")
+        // A loose "midi" is itself the request for midi note names (see the
+        // fallback above), so it has to leave with the rest of the request.
+        .replace(/\bmidi\b/gi, "")
         .replace(/\bscale\b/gi, "")
         .replace(HEADING_RE, "")
+        .replace(NOTES_GROUP_PREFIX_RE, "")
+        .replace(NOTES_GROUP_RE, "")
+        .replace(HAND_PREFIX_BARE_RE, "")
+        .replace(NOTES_BARE_HAND_RE, "")
+        .replace(HAND_PREFIX_SINGLE_RE, "")
+        .replace(NOTE_BARE_HAND_SINGLE_RE, "")
+        .replace(POLYCHORD_SLASH_RE, "")
+        .replace(SEMI_SEP_RE, "")
         .replace(THEME_RE, "")
         .replace(/\btheme\b/gi, "")
         .replace(/\bcolou?rs?\b/gi, "")
@@ -373,6 +764,9 @@ export function parseChordDescription(input) {
         .replace(/\bin\b/gi, "")
         .replace(/\s+/g, " ")
         .trim();
+    // Last, so the article test is asked of text that is finished — and of the
+    // original input, which still knows what the article was standing in front of.
+    cleaned = stripArticles(cleaned, input).replace(/\s+/g, " ").trim();
     // Replace word-based accidentals before chord extraction
     cleaned = cleaned
         .replace(/\bsharp\b/gi, "#")
@@ -396,9 +790,11 @@ export function parseChordDescription(input) {
         const chordMatch = cleaned.match(CHORD_RE);
         if (chordMatch) {
             const root = capitalizeNote(chordMatch[1]);
-            const fullMatch = chordMatch[0];
-            const afterRoot = fullMatch.slice(chordMatch[1].length);
-            result.chordName = root + afterRoot.trim();
+            const afterRoot = chordMatch[0]
+                .slice(chordMatch[1].length)
+                .trim()
+                .replace(/\/([A-Ga-g])/, (_m, letter) => `/${letter.toUpperCase()}`);
+            result.chordName = root + afterRoot;
         }
     }
     return result;