@k-l-lambda/lilylet 0.1.69 → 0.1.71

package/lib/abc/abc.d.ts

@@ -74,6 +74,7 @@ declare namespace ABC {
     export interface StaffGroup {
         items: (StaffGroup | string)[];
         bound?: 'arc' | 'square' | 'curly';
+        barThruAfter?: boolean;
     }
     export interface StaffLayout {
         staffLayout: StaffGroup[];

package/lib/abc/grammar.jison.js

@@ -95,7 +95,7 @@ break;
 case 4:
 this.$ = tune($$[$0-1], $$[$0]);
 break;
-case 11: case 12: case 13: case 14: case 16: case 20: case 67: case 101: case 104: case 105: case 106: case 107: case 136: case 137: case 163: case 164: case 222:
+case 11: case 12: case 13: case 14: case 16: case 67: case 101: case 104: case 105: case 106: case 107: case 136: case 137: case 163: case 164: case 222:
 this.$ = $$[$0-1];
 break;
 case 15:
@@ -104,6 +104,9 @@ break;
 case 17:
 this.$ = ({staffLayout: $$[$0]});
 break;
+case 20:
+ if ($$[$0-1].length) $$[$0-1][$$[$0-1].length - 1].barThruAfter = true; this.$ = $$[$0-1]; 
+break;
 case 21:
 this.$ = staffGroup([$$[$0]]);
 break;

package/lib/gmInstruments.d.ts

@@ -0,0 +1 @@
+export * from "./lilylet/gmInstruments.js";

package/lib/gmInstruments.js

@@ -0,0 +1 @@
+export * from "./lilylet/gmInstruments.js";

package/lib/lilylet/abcDecoder.js

@@ -5,6 +5,7 @@
  */
 import parse from "../abc/parser.js";
 import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
+import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 // ============ Constants ============
 // NotaGen catalog tags appear as leading single-% comments in ABC files,
 // in the order: period, composer, instrumentation. They are mapped to
@@ -335,6 +336,9 @@ const convertClef = (clefStr) => {
     // Split off an optional ABC octave shift suffix: "treble-8", "bass+8", "treble-15".
     // ABC: "-N" lowers the sounding pitch (small N drawn below), "+N" raises it.
     // LilyPond/Lilylet: "_N" = below, "^N" = above. Translate the sign accordingly.
+    // (Only octave amounts 8/15 are handled here; the Lilylet "_N"/"^N" clef suffix
+    // itself accepts arbitrary diatonic intervals — see meiEncoder.resolveClef — and a
+    // voice's transpose= property is folded into the same suffix via transposeClefSuffix.)
     const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
     const base = shift ? shift[1] : clefStr;
     let resolved;
@@ -355,6 +359,31 @@ const convertClef = (clefStr) => {
         resolved += (shift[2] === "-" ? "_" : "^") + shift[3];
     return resolved;
 };
+/**
+ * Fold an ABC voice `transpose=N` property (a written→sounding shift in
+ * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
+ * diatonic interval number. ABC carries only semitones, so the diatonic
+ * interval is approximated by the nearest scale-step count
+ * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
+ * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
+ * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
+ * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
+ * nearest-interval approximation otherwise.
+ */
+const transposeClefSuffix = (clef, semitones) => {
+    if (!clef || !semitones)
+        return clef;
+    // A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
+    // stacking another shift on top is not meaningful for ABC sources.
+    if (/[_^]\d+$/.test(clef))
+        return clef;
+    const steps = Math.round((semitones * 7) / 12);
+    if (steps === 0)
+        return clef;
+    const num = Math.abs(steps) + 1;
+    const suffix = (steps < 0 ? "_" : "^") + num;
+    return (clef + suffix);
+};
 /**
  * Convert ABC barline to Lilylet barline style
  */
@@ -431,6 +460,158 @@ const parseScoreLayout = (headers) => {
     }
     return voiceMap.size > 0 ? voiceMap : null;
 };
+/**
+ * Translate an ABC %%score layout into the equivalent lilylet staves expression.
+ *
+ * The two models differ in their leaf unit: ABC %%score is VOICE-leaf (an arc `( … )`
+ * collapses several voices onto one staff), whereas lilylet staves is STAFF-leaf. So
+ * each ABC staff becomes exactly one lilylet staff id, named (per spec) by the FIRST
+ * voice token inside its arc.
+ *
+ * Bracket mapping (ABC → lilylet):
+ *   ( … )  arc    → one staff leaf (id = first voice)         e.g. (1 3) → "1"
+ *   bare   leaf   → one staff leaf (id = that voice)          e.g. 7     → "7"
+ *   { … }  curly  → brace (grand staff)                       → { … }
+ *   [ … ]  square → bracket (orchestral)                      → < … >
+ *
+ * Conjunction between two siblings: a trailing `|` in %%score means barlines run through
+ * the two staves, mapped to the solid conjunction `-`; otherwise the blank `,` is used.
+ */
+const abcLayoutToStaves = (layout) => {
+    // First voice token under a node (the staff's lilylet id).
+    const firstVoice = (node) => {
+        if (typeof node === "string")
+            return node;
+        for (const item of node.items || []) {
+            const v = firstVoice(item);
+            if (v !== null)
+                return v;
+        }
+        return null;
+    };
+    // A node is a single staff (an arc, or a bare leaf) iff it has no curly/square nesting.
+    const isStaffLeaf = (node) => {
+        if (typeof node === "string")
+            return true;
+        if (node.bound === "curly" || node.bound === "square")
+            return false;
+        // arc or unbounded: a staff only if every descendant is too (no nested groups)
+        return (node.items || []).every(isStaffLeaf);
+    };
+    // A square group maps to lilylet Bracket `<>` at the TOP level, but to lilylet Square
+    // `[]` when nested inside another group — e.g. ABC `[[1 2] 3 | 4]` → `<[1,2]3-4>`.
+    // A curly group always maps to Brace `{}`. `nested` is false for a top-level entry.
+    const emit = (node, nested) => {
+        if (isStaffLeaf(node))
+            return firstVoice(node) || "";
+        const group = node;
+        const open = group.bound === "curly" ? "{" : (group.bound === "square" && nested) ? "[" : "<";
+        const close = group.bound === "curly" ? "}" : (group.bound === "square" && nested) ? "]" : ">";
+        const items = group.items || [];
+        let inner = "";
+        items.forEach((item, i) => {
+            inner += emit(item, true);
+            if (i < items.length - 1) {
+                // A Blank separator (',') is only needed between two bare staff leaves; a
+                // grouped neighbour's bracket already delimits the slot, so suppress it there
+                // (giving `[1,2]3` not `[1,2],3`). A Solid join ('-', barThru) is always kept.
+                const next = items[i + 1];
+                if (item.barThruAfter)
+                    inner += "-";
+                else if (isStaffLeaf(item) && isStaffLeaf(next))
+                    inner += ",";
+            }
+        });
+        return `${open}${inner}${close}`;
+    };
+    const tops = layout.map((top, i) => {
+        let s = emit(top, false);
+        // A bare top-level staff leaf (e.g. the `9` in `[ … ] 9 [ … ]`) still occupies a slot;
+        // emit() already yields its id with no wrapper, which is the desired output.
+        return { s, barThru: !!top.barThruAfter, isLast: i === layout.length - 1 };
+    });
+    let out = "";
+    tops.forEach((t, i) => {
+        out += t.s;
+        if (i < tops.length - 1)
+            out += t.barThru ? " - " : " ";
+    });
+    out = out.trim();
+    return out.length > 0 ? out : null;
+};
+/**
+ * Translate ABC voice instrument names (V:n nm="…" snm="…") into a lilylet `instruments`
+ * map keyed by staff-layout group key.
+ *
+ * ABC names sit on individual voices; lilylet staves are staff-leaf (an arc's first voice
+ * is the staff id). So we first collect a per-staff name from the staff-id voice. Then,
+ * per the user's rule: if a GROUP carries an instrument only on its first staff and the
+ * rest of the group is unnamed, the name belongs to the whole group — hoist it to the
+ * group key and drop it from the leaf. This matches engraving convention (one bracketed
+ * section, e.g. "Violini", named once for the group rather than on its top staff).
+ *
+ * `voiceInstr` maps an ABC voice number to its {name, shortName}. The layout's staff ids
+ * are arc-first voice numbers, so a staff id "5" looks up voice 5's name.
+ */
+const abcInstrumentsToLilylet = (stavesCode, voiceInstr) => {
+    const layout = parseStaffLayout(stavesCode);
+    const result = {};
+    // Per-staff instrument, keyed by staff id (the arc-first voice number as a string).
+    const staffInstr = new Map();
+    for (const id of layout.staffIds) {
+        const v = parseInt(id, 10);
+        if (!isNaN(v) && voiceInstr.has(v))
+            staffInstr.set(id, voiceInstr.get(v));
+    }
+    // First staff id under a group (in layout order).
+    const firstStaffId = (group) => {
+        if (group.staff)
+            return group.staff;
+        for (const sub of group.subs || []) {
+            const id = firstStaffId(sub);
+            if (id !== undefined)
+                return id;
+        }
+        return undefined;
+    };
+    // All staff ids under a group except the first.
+    const restStaffIds = (group) => {
+        const all = [];
+        const collect = (g) => {
+            if (g.staff)
+                all.push(g.staff);
+            (g.subs || []).forEach(collect);
+        };
+        collect(group);
+        return all.slice(1);
+    };
+    // Walk groups top-down; hoist a first-staff-only name onto the group, else keep leaves.
+    const walk = (group) => {
+        const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
+        if (isLeaf) {
+            // A plain leaf keeps its own name (assigned in the flush pass below).
+            return;
+        }
+        const first = firstStaffId(group);
+        const firstInstr = first !== undefined ? staffInstr.get(first) : undefined;
+        const rest = restStaffIds(group);
+        const restNamed = rest.some(id => staffInstr.has(id));
+        // Group with a real grouping symbol, named only on its first staff → hoist.
+        const hasSymbol = group.type !== StaffGroupType.Default;
+        if (hasSymbol && firstInstr && !restNamed && group.key !== undefined) {
+            result[group.key] = firstInstr;
+            staffInstr.delete(first); // consumed by the group
+            return; // children below the hoisted name carry nothing
+        }
+        for (const sub of group.subs || [])
+            walk(sub);
+    };
+    walk(layout.group);
+    // Flush any per-staff names that weren't hoisted onto a group.
+    for (const [id, instr] of staffInstr)
+        result[id] = instr;
+    return Object.keys(result).length > 0 ? result : null;
+};
 // ============ Marks/Decorations Conversion ============
 const convertArticulationMark = (artName) => {
     switch (artName) {
@@ -984,7 +1165,17 @@ const decodeTune = (tune, options = {}) => {
                         properties: voiceValue?.properties,
                     });
                     if (clefStr) {
-                        const clef = convertClef(clefStr);
+                        let clef = convertClef(clefStr);
+                        // Fold a voice transpose= (semitones) into the clef suffix so it
+                        // survives to MEI as trans.diat/trans.semi (transposing instruments
+                        // like "Clarinet transpose=-2", "Horn transpose=-9").
+                        const transposeRaw = voiceValue?.properties?.transpose;
+                        const transposeSemi = typeof transposeRaw === "number"
+                            ? transposeRaw
+                            : (transposeRaw != null ? Number(transposeRaw) : NaN);
+                        if (clef && Number.isFinite(transposeSemi) && transposeSemi !== 0) {
+                            clef = transposeClefSuffix(clef, transposeSemi);
+                        }
                         if (clef)
                             voiceClefs.set(voiceId, clef);
                     }
@@ -995,6 +1186,39 @@ const decodeTune = (tune, options = {}) => {
     }
     // Parse score layout
     const scoreLayout = parseScoreLayout(headers);
+    // Translate the ABC %%score layout into a lilylet staves expression (staff-leaf model).
+    const layoutHeader = headers.find((h) => h.staffLayout);
+    if (layoutHeader) {
+        const staves = abcLayoutToStaves(layoutHeader.staffLayout);
+        if (staves)
+            metadata.staves = staves;
+        // Translate per-voice nm/snm into a lilylet instruments map. Collect names by ABC
+        // voice number (the staff id is the arc-first voice), then let abcInstrumentsToLilylet
+        // apply the first-staff-only → whole-group hoisting rule.
+        if (metadata.staves) {
+            const voiceInstr = new Map();
+            for (const [vid, config] of voiceConfigs) {
+                const props = config.properties;
+                if (!props)
+                    continue;
+                const name = props.nm ?? props.name;
+                if (typeof name !== "string" || !name.length)
+                    continue;
+                const v = typeof vid === "number" ? vid : parseInt(String(vid), 10);
+                if (isNaN(v))
+                    continue;
+                const short = props.snm ?? props.sname;
+                voiceInstr.set(v, typeof short === "string" && short.length
+                    ? { name, shortName: short }
+                    : { name });
+            }
+            if (voiceInstr.size > 0) {
+                const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
+                if (instruments)
+                    metadata.instruments = instruments;
+            }
+        }
+    }
     // Group measures by voice
     // ABC measures contain BarPatches, each with a voice control V:n
     const measures = body.measures;

package/lib/lilylet/gmInstruments.d.ts

@@ -0,0 +1 @@
+export declare const gmProgramOf: (name: string | undefined | null) => number | undefined;

package/lib/lilylet/gmInstruments.js

@@ -0,0 +1,295 @@
+// General MIDI program lookup: instrument name → GM program number (0–127).
+//
+// Verovio's MIDI export honors ONLY the numeric `@midi.instrnum` on an MEI
+// <instrDef> (the GM-name attribute `@midi.instrname` is parsed but never used
+// for MIDI). lilylet already carries human instrument names (from ABC voice
+// names, MusicXML part names, etc.) in metadata.instruments; this table maps
+// those names to GM programs so the MEI encoder can emit <instrDef midi.instrnum>
+// and multi-instrument scores get distinct timbres instead of all-piano.
+//
+// The name set is seeded from the notagen dataset (Piano, Violins, Viola,
+// Violoncellos, Oboe, Horn, Flute, Clarinet, Bassoon, Violin, Trombone,
+// Timpani, Voice, Bass, Trumpet, Harp, Contrabasses, Vocal, Organ, …) plus
+// common GM aliases, then matched through a normalizer that handles plurals
+// ("Violins" → violin) and trailing part numbers ("Violin I", "Horn 2").
+// Normalized name → GM program (0-based). Keys are lowercase, singular,
+// whitespace-collapsed. Plural/number variants are resolved by the normalizer.
+const GM_PROGRAMS = {
+    // Piano (0–7)
+    "piano": 0,
+    "acoustic grand piano": 0,
+    "grand piano": 0,
+    "bright acoustic piano": 1,
+    "electric piano": 4,
+    "harpsichord": 6,
+    "clavichord": 7,
+    "clavi": 7,
+    // Chromatic percussion (8–15)
+    "celesta": 8,
+    "glockenspiel": 9,
+    "music box": 10,
+    "vibraphone": 11,
+    "marimba": 12,
+    "xylophone": 13,
+    "tubular bells": 14,
+    "dulcimer": 15,
+    // Organ (16–23)
+    "organ": 19,
+    "hammond organ": 16,
+    "percussive organ": 17,
+    "rock organ": 18,
+    "church organ": 19,
+    "pipe organ": 19,
+    "reed organ": 20,
+    "accordion": 21,
+    "harmonica": 22,
+    // Guitar (24–31)
+    "guitar": 24,
+    "acoustic guitar": 24,
+    "nylon guitar": 24,
+    "steel guitar": 25,
+    "electric guitar": 27,
+    "guitarre": 24, // fr./de. guitar
+    "gitarre": 24, // de.
+    "chitarra": 24, // it.
+    // Bass (32–39) — orchestral "Bass" means double bass (Contrabass, 43); the
+    // electric/acoustic bass-guitar programs live here but are not the default.
+    "acoustic bass": 32,
+    "electric bass": 33,
+    "fretless bass": 35,
+    "basso": 43, // it. bass → double bass
+    "basse": 43, // fr.
+    "bassi": 43, // it. pl.
+    "bas": 43, // de./nl. abbrev
+    // Strings (40–47)
+    "violin": 40,
+    "viola": 41,
+    "cello": 42,
+    "violoncello": 42,
+    "contrabass": 43,
+    "double bass": 43,
+    "bass": 43,
+    "tremolo strings": 44,
+    "pizzicato strings": 45,
+    "harp": 46,
+    "orchestral harp": 46,
+    "timpani": 47,
+    // Ensemble (48–55)
+    "strings": 48,
+    "string ensemble": 48,
+    "string orchestra": 48,
+    "synth strings": 50,
+    "voice": 52,
+    "vocal": 52,
+    "voices": 52,
+    "choir": 52,
+    "choir aahs": 52,
+    "soprano": 52,
+    "alto": 52,
+    "tenor": 52,
+    "bass voice": 52,
+    "orchestra hit": 55,
+    // Brass (56–63)
+    "trumpet": 56,
+    "trombone": 57,
+    "tuba": 58,
+    "muted trumpet": 59,
+    "horn": 60,
+    "french horn": 60,
+    "brass": 61,
+    "brass section": 61,
+    // Reed (64–71)
+    "soprano sax": 64,
+    "alto sax": 65,
+    "tenor sax": 66,
+    "baritone sax": 67,
+    "saxophone": 66,
+    "sax": 66,
+    "oboe": 68,
+    "english horn": 69,
+    "cor anglais": 69,
+    "bassoon": 70,
+    "clarinet": 71,
+    // Pipe (72–79)
+    "piccolo": 72,
+    "flute": 73,
+    "recorder": 74,
+    "pan flute": 75,
+    // --- Foreign-language names, abbreviations and common spelling variants,
+    // harvested from the notagen corpus. Mapped to the nearest GM program.
+    // Keyboard
+    "pianoforte": 0,
+    "fortepiano": 0,
+    "klavier": 0,
+    "keyboard": 0,
+    "cembalo": 6, // it. harpsichord
+    "clavicembalo": 6,
+    "harpichord": 6, // misspelling
+    "organo": 19, // it. organ
+    "orgel": 19, // de. organ
+    // Strings (it./de./fr./variants)
+    "violino": 40,
+    "violini": 40,
+    "violine": 40, // de.
+    "violinen": 40,
+    "violon": 40, // fr.
+    "violons": 40,
+    "violn": 40, // abbrev/OCR variant
+    "violno": 40, // OCR variant
+    "viole": 41, // it. violas (also fr. "viole")
+    "bratsche": 41, // de. viola
+    "celli": 42,
+    "violoncelli": 42,
+    "violoncelle": 42, // fr.
+    "violoncelles": 42,
+    "violonchelo": 42, // es.
+    "soloncello": 42, // OCR variant of violoncello
+    "gambe": 42, // fr. viola da gamba
+    "gamba": 42, // viola da gamba ≈ cello
+    "viola da gamba": 42,
+    "contrabasso": 43, // it.
+    "contrabassi": 43,
+    "contrabbasso": 43, // it.
+    "contra-basso": 43,
+    "contrabajo": 43, // es.
+    "kontrabass": 43, // de.
+    "kontrabasse": 43, // de. pl.
+    "kontrabasso": 43,
+    "contrebasse": 43, // fr.
+    "violone": 43, // large bass viol ≈ contrabass
+    "arpa": 46, // it./es. harp
+    "harfe": 46, // de. harp
+    "pauken": 47, // de. timpani
+    // Voice (it./de./fr.)
+    "canto": 52, // it.
+    "coro": 52, // it. choir
+    "chorus": 52,
+    "chorale": 52,
+    "sopran": 52, // de.
+    "contralto": 52, // it. alto
+    "tenore": 52, // it.
+    "tenori": 52,
+    "gesang": 52, // de. voice
+    "singstimme": 52, // de. voice
+    "voce": 52, // it.
+    "voix": 52, // fr.
+    "chanto": 52, // OCR variant of canto
+    "women": 52, // women's voices
+    "contra-fagotto": 70, // hyphenated contrabassoon ≈ bassoon
+    // Brass
+    "tromboni": 57, // it. trombones
+    "posaune": 57, // de. trombone
+    "posaunen": 57,
+    "trombe": 56, // it. trumpets
+    "tromba": 56, // it. trumpet
+    "trompete": 56, // de. trumpet
+    "trompeten": 56,
+    "trompette": 56, // fr. trumpet
+    "cornetto": 56, // historical cornett ≈ trumpet
+    "cornettino": 56,
+    "corno": 60, // it. horn
+    "corni": 60, // it. horns
+    // Reed (it./de./fr.)
+    "oboi": 68, // it. oboes
+    "oboen": 68, // de.
+    "hautbois": 68, // fr. oboe
+    "corno inglese": 69, // it. english horn
+    "inglese": 69, // "corno inglese" trailing word fallback also covers it
+    "ingles": 69, // es. variant
+    "fagotto": 70, // it. bassoon
+    "fagotti": 70,
+    "fagott": 70, // de.
+    "fagotte": 70, // de. pl.
+    "fagot": 70, // es.
+    "basson": 70, // fr. bassoon
+    "bassons": 70,
+    "contrafagotto": 70, // it. contrabassoon ≈ bassoon timbre
+    "contrabassoon": 70,
+    "klarinette": 71, // de. clarinet
+    "clarinetto": 71, // it.
+    "clarinetti": 71,
+    "clarinette": 71, // fr.
+    // Pipe (it./de.)
+    "flauto": 73, // it. flute
+    "flauti": 73, // it. flutes
+    "flote": 73, // de. Flöte (diacritics stripped by the normalizer)
+    "floten": 73, // de. Flöten
+    "traverso": 73, // baroque transverse flute
+    "flauto traverso": 73,
+};
+// Normalize an instrument name for lookup: lowercase, turn literal "\n" escapes
+// and real newlines into spaces, strip diacritics (Flöte→flote, Hautböis→...),
+// drop a trailing part designator (roman numeral or arabic number — "Violin I",
+// "Horn 2", "Oboe II"), collapse whitespace.
+const normalizeInstrumentName = (raw) => {
+    let s = raw.toLowerCase().trim();
+    s = s.replace(/\\n/g, " "); // literal backslash-n escape → space
+    s = s.normalize("NFD").replace(/[̀-ͯ]/g, ""); // strip diacritics
+    s = s.replace(/\s+/g, " ").trim();
+    s = s.replace(/\s+(?:[ivx]+|\d+)\.?$/i, "").trim();
+    return s;
+};
+// Choral single-letter voice-part abbreviations → "Voice" (GM 52). Matched ONLY
+// against the whole name, never per-word: a bare "S"/"A"/"T"/"B" staff label in a
+// chorale means Soprano/Alto/Tenor/Bass, but the same letters appear as key
+// designators in "Clarinet in B", "Horn in F", "Trumpet in C" — so these must not
+// enter GM_PROGRAMS where the word-scan would misread them.
+const SATB_VOICE = {
+    "s": 52,
+    "a": 52,
+    "t": 52,
+    "b": 52,
+};
+// Look up a single normalized name: exact match, else de-pluralized
+// ("violins"→violin, "violoncellos"→violoncello, "contrabasses"→contrabass),
+// else with a trailing attached part-number stripped ("violin1"→violin,
+// "violino2"→violino).
+const lookupNormalized = (norm) => {
+    if (norm in GM_PROGRAMS)
+        return GM_PROGRAMS[norm];
+    // Try "-es" before "-s".
+    if (norm.endsWith("es")) {
+        const sing = norm.slice(0, -2);
+        if (sing in GM_PROGRAMS)
+            return GM_PROGRAMS[sing];
+    }
+    if (norm.endsWith("s")) {
+        const sing = norm.slice(0, -1);
+        if (sing in GM_PROGRAMS)
+            return GM_PROGRAMS[sing];
+    }
+    // Attached trailing digits ("violin1", "violino2"): strip and retry.
+    const deNum = norm.replace(/\d+$/, "");
+    if (deNum !== norm && deNum in GM_PROGRAMS)
+        return GM_PROGRAMS[deNum];
+    return undefined;
+};
+// Resolve an instrument name to a GM program number (0–127), or undefined if no
+// confident match (caller then omits <instrDef>, leaving Verovio's default).
+//
+// Match priority: the full normalized string first (including the SATB
+// single-letter voice abbreviations), then individual words from the last toward
+// the first. Multi-word names ("Singstimme Voice", "First Violins", "Solo Flute")
+// usually put the instrument at the end, so the trailing word is tried before
+// earlier qualifier words. Each word attempt runs through the de-plural path
+// (lookupNormalized); SATB letters are intentionally NOT part of the word scan.
+export const gmProgramOf = (name) => {
+    if (!name)
+        return undefined;
+    const norm = normalizeInstrumentName(name);
+    const direct = lookupNormalized(norm);
+    if (direct !== undefined)
+        return direct;
+    // Whole-name-only: a lone S/A/T/B is a chorale voice part.
+    if (norm in SATB_VOICE)
+        return SATB_VOICE[norm];
+    const words = norm.split(" ");
+    if (words.length > 1) {
+        for (let i = words.length - 1; i >= 0; i--) {
+            const hit = lookupNormalized(words[i]);
+            if (hit !== undefined)
+                return hit;
+        }
+    }
+    return undefined;
+};