@k-l-lambda/lilylet 0.1.65 → 0.1.67

package/lib/lilylet/abcDecoder.js

@@ -4,8 +4,35 @@
  * Converts ABC notation files to Lilylet's internal LilyletDoc format.
  */
 import parse from "../abc/parser.js";
-import { Phonet, Accidental, Clef, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, } from "./types.js";
+import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, } from "./types.js";
 // ============ Constants ============
+// NotaGen catalog tags appear as leading single-% comments in ABC files,
+// in the order: period, composer, instrumentation. They are mapped to
+// Lilylet metadata: period -> genre, instrumentation -> instrument.
+const NOTAGEN_PERIOD_SET = new Set([
+    "Baroque", "Classical", "Romantic",
+]);
+const NOTAGEN_INSTRUMENTATION_SET = new Set([
+    "Art Song", "Chamber", "Choral", "Keyboard", "Orchestral", "Vocal-Orchestral",
+]);
+const NOTAGEN_COMPOSER_SET = new Set([
+    "Bach, Johann Sebastian", "Bartok, Bela", "Beethoven, Ludwig van", "Berlioz, Hector",
+    "Bizet, Georges", "Boulanger, Lili", "Boulton, Harold", "Brahms, Johannes",
+    "Burgmuller, Friedrich", "Butterworth, George", "Chaminade, Cecile", "Chausson, Ernest",
+    "Chopin, Frederic", "Corelli, Arcangelo", "Cornelius, Peter", "Debussy, Claude",
+    "Dvorak, Antonin", "Faisst, Clara", "Faure, Gabriel", "Franz, Robert",
+    "Gonzaga, Chiquinha", "Grandval, Clemence de", "Grieg, Edvard", "Handel, George Frideric",
+    "Haydn, Joseph", "Hensel, Fanny", "Holmes, Augusta Mary Anne", "Jaell, Marie",
+    "Kinkel, Johanna", "Kralik, Mathilde", "Lang, Josephine", "Lehmann, Liza",
+    "Liszt, Franz", "Mayer, Emilie", "Medtner, Nikolay", "Mendelssohn, Felix",
+    "Mozart, Wolfgang Amadeus", "Munktell, Helena", "Paradis, Maria Theresia von",
+    "Parratt, Walter", "Prokofiev, Sergey", "Rachmaninoff, Sergei", "Ravel, Maurice",
+    "Reichardt, Louise", "Saint-Georges, Joseph Bologne", "Saint-Saens, Camille",
+    "Satie, Erik", "Scarlatti, Domenico", "Schroter, Corona", "Schubert, Franz",
+    "Schumann, Clara", "Schumann, Robert", "Scriabin, Aleksandr", "Shostakovich, Dmitry",
+    "Sibelius, Jean", "Smetana, Bedrich", "Tchaikovsky, Pyotr", "Viardot, Pauline",
+    "Vivaldi, Antonio", "Warlock, Peter", "Wolf, Hugo", "Zumsteeg, Emilie",
+]);
 const ABC_PHONET_MAP = {
     "C": Phonet.c, "D": Phonet.d, "E": Phonet.e, "F": Phonet.f, "G": Phonet.g, "A": Phonet.a, "B": Phonet.b,
     "c": Phonet.c, "d": Phonet.d, "e": Phonet.e, "f": Phonet.f, "g": Phonet.g, "a": Phonet.a, "b": Phonet.b,
@@ -237,13 +264,28 @@ const convertKeySignature = (abcKey) => {
  * Convert ABC clef string to Lilylet Clef
  */
 const convertClef = (clefStr) => {
-    switch (clefStr?.toLowerCase()) {
-        case "treble": return Clef.treble;
-        case "bass": return Clef.bass;
+    // 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.
+    const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
+    const base = shift ? shift[1] : clefStr;
+    let resolved;
+    switch (base?.toLowerCase()) {
+        case "treble":
+            resolved = "treble";
+            break;
+        case "bass":
+            resolved = "bass";
+            break;
         case "alto":
-        case "tenor": return Clef.alto;
+        case "tenor":
+            resolved = "alto";
+            break;
         default: return undefined;
     }
+    if (shift)
+        resolved += (shift[2] === "-" ? "_" : "^") + shift[3];
+    return resolved;
 };
 /**
  * Convert ABC barline to Lilylet barline style
@@ -267,11 +309,41 @@ const convertBarline = (bar) => {
             return "|";
     }
 };
-/**
- * Parse %%score layout to determine voice→(part, staff) mapping.
- * {(...) | (...)} = one part with two staves
- * (...) = voices sharing one staff
- */
+// All voice numbers under a node, flattened.
+const collectScoreVoices = (node) => {
+    if (typeof node === "string") {
+        const v = parseInt(node, 10);
+        return isNaN(v) ? [] : [v];
+    }
+    const voices = [];
+    for (const item of node.items || []) {
+        voices.push(...collectScoreVoices(item));
+    }
+    return voices;
+};
+// Expand a node into a list of parts; each part is a list of staves; each staff is a list of voices.
+const scoreNodeToParts = (node) => {
+    if (typeof node === "string") {
+        const v = parseInt(node, 10);
+        return isNaN(v) ? [] : [[[v]]];
+    }
+    if (node.bound === "square") {
+        // each child is its own part
+        const parts = [];
+        for (const child of node.items || []) {
+            parts.push(...scoreNodeToParts(child));
+        }
+        return parts;
+    }
+    if (node.bound === "curly") {
+        // one part, each child is a separate staff (grand staff)
+        const staves = (node.items || []).map(child => collectScoreVoices(child)).filter(s => s.length > 0);
+        return staves.length > 0 ? [staves] : [];
+    }
+    // arc or no bound: one part, all voices on a single staff
+    const voices = collectScoreVoices(node);
+    return voices.length > 0 ? [[voices]] : [];
+};
 const parseScoreLayout = (headers) => {
     const layoutHeader = headers.find((h) => h.staffLayout);
     if (!layoutHeader)
@@ -279,86 +351,15 @@ const parseScoreLayout = (headers) => {
     const layout = layoutHeader.staffLayout;
     const voiceMap = new Map();
     let partIndex = 0;
-    for (const group of layout) {
-        if (group.bound === "curly") {
-            // Curly braces = one instrument/part with multiple staves
-            let staffInPart = 1;
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart });
+    for (const top of layout) {
+        for (const part of scoreNodeToParts(top)) {
+            part.forEach((staff, staffIdx) => {
+                for (const voice of staff) {
+                    voiceMap.set(voice, { partIndex, staffInPart: staffIdx + 1 });
                 }
-                else if (item.items) {
-                    const sg = item;
-                    for (const subItem of sg.items) {
-                        if (typeof subItem === "string") {
-                            voiceMap.set(parseInt(subItem), { partIndex, staffInPart });
-                        }
-                        else if (subItem.items) {
-                            for (const leaf of subItem.items) {
-                                if (typeof leaf === "string") {
-                                    voiceMap.set(parseInt(leaf), { partIndex, staffInPart });
-                                }
-                            }
-                        }
-                    }
-                    staffInPart++;
-                }
-            }
-            partIndex++;
-        }
-        else if (group.bound === "arc" || !group.bound) {
-            // Arc or plain = voices sharing a staff in same part
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart: 1 });
-                }
-                else if (item.items) {
-                    for (const subItem of item.items) {
-                        if (typeof subItem === "string") {
-                            voiceMap.set(parseInt(subItem), { partIndex, staffInPart: 1 });
-                        }
-                    }
-                }
-            }
+            });
             partIndex++;
         }
-        else {
-            // Square bracket or unknown - treat each item as separate part
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart: 1 });
-                    partIndex++;
-                }
-                else if (item.items) {
-                    const sg = item;
-                    if (sg.bound === "curly") {
-                        let staffInPart = 1;
-                        for (const subItem of sg.items) {
-                            if (typeof subItem === "string") {
-                                voiceMap.set(parseInt(subItem), { partIndex, staffInPart });
-                            }
-                            else if (subItem.items) {
-                                for (const leaf of subItem.items) {
-                                    if (typeof leaf === "string") {
-                                        voiceMap.set(parseInt(leaf), { partIndex, staffInPart });
-                                    }
-                                }
-                                staffInPart++;
-                            }
-                        }
-                        partIndex++;
-                    }
-                    else {
-                        for (const subItem of sg.items) {
-                            if (typeof subItem === "string") {
-                                voiceMap.set(parseInt(subItem), { partIndex, staffInPart: 1 });
-                            }
-                        }
-                        partIndex++;
-                    }
-                }
-            }
-        }
     }
     return voiceMap.size > 0 ? voiceMap : null;
 };
@@ -790,8 +791,17 @@ const decodeTune = (tune) => {
         }
     }
     for (const h of headers) {
-        if (h.comment)
+        const comment = h.comment;
+        if (typeof comment === "string") {
+            const value = comment.trim();
+            if (!metadata.genre && NOTAGEN_PERIOD_SET.has(value))
+                metadata.genre = value;
+            else if (!metadata.instrument && NOTAGEN_INSTRUMENTATION_SET.has(value))
+                metadata.instrument = value;
+            else if (!metadata.composer && NOTAGEN_COMPOSER_SET.has(value))
+                metadata.composer = value;
             continue;
+        }
         if (h.staffLayout)
             continue;
         const header = h;

package/lib/lilylet/meiEncoder.js

@@ -44,6 +44,40 @@ const CLEF_SHAPES = {
     F: { shape: "F", line: 4 },
     C: { shape: "C", line: 3 },
 };
+// Resolve a clef string into MEI shape/line plus optional octave displacement.
+// Octave transposition follows the LilyPond convention: a "_8"/"_15" suffix lowers
+// the sounding pitch by one/two octaves (the small 8/15 is drawn below the clef),
+// and "^8"/"^15" raises it (drawn above). MEI encodes this as dis ("8" | "15")
+// and dis.place ("below" | "above").
+const resolveClef = (clefStr) => {
+    const match = clefStr.match(/^(.*?)([_^])(8|15)$/);
+    const base = match ? match[1] : clefStr;
+    const clefInfo = CLEF_SHAPES[base] || CLEF_SHAPES.treble;
+    if (!match)
+        return { shape: clefInfo.shape, line: clefInfo.line };
+    return {
+        shape: clefInfo.shape,
+        line: clefInfo.line,
+        dis: match[3],
+        disPlace: match[2] === "^" ? "above" : "below",
+    };
+};
+// Attributes for a standalone <clef> element (mid-measure clef change).
+const clefElementAttrs = (clefStr) => {
+    const c = resolveClef(clefStr);
+    let attrs = `shape="${c.shape}" line="${c.line}"`;
+    if (c.dis)
+        attrs += ` dis="${c.dis}" dis.place="${c.disPlace}"`;
+    return attrs;
+};
+// Attributes for a <staffDef> clef (clef.* namespace).
+const staffDefClefAttrs = (clefStr) => {
+    const c = resolveClef(clefStr);
+    let attrs = `clef.shape="${c.shape}" clef.line="${c.line}"`;
+    if (c.dis)
+        attrs += ` clef.dis="${c.dis}" clef.dis.place="${c.disPlace}"`;
+    return attrs;
+};
 // Lilylet duration division to MEI dur
 // division: 1=whole, 2=half, 4=quarter, 8=eighth, etc.
 const DURATIONS = {
@@ -128,7 +162,9 @@ const encodePitch = (pitch, keyFifths = 0, ottavaShift = 0, measureAccidentals)
     // Lilylet octave: 0 = middle C octave (C4), positive = higher, negative = lower
     // When ottava is active, the source pitch is the sounding pitch, but we need to output the written pitch
     // For 8va up (ottavaShift=1), written pitch is one octave lower than sounding
-    const oct = 4 + pitch.octave - ottavaShift;
+    const soundingOct = 4 + pitch.octave;
+    const oct = soundingOct - ottavaShift;
+    const octGes = ottavaShift !== 0 ? soundingOct : undefined;
     // Get the accidental implied by the key signature for this note
     const keyAccidentals = getKeyAccidentals(keyFifths);
     const keyAccid = keyAccidentals[pitch.phonet];
@@ -189,7 +225,7 @@ const encodePitch = (pitch, keyFifths = 0, ottavaShift = 0, measureAccidentals)
             measureAccidentals.set(pitchKey, 'n');
         }
     }
-    return { pname: pitch.phonet, oct, accid, accidGes };
+    return { pname: pitch.phonet, oct, octGes, accid, accidGes };
 };
 // Convert tremolo division to stem.mod value
 const tremoloToStemMod = (division) => {
@@ -209,6 +245,8 @@ const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteI
     }
     if (pitch.accid)
         attrs += ` accid="${pitch.accid}"`;
+    if (pitch.octGes !== undefined)
+        attrs += ` oct.ges="${pitch.octGes}"`;
     if (pitch.accidGes)
         attrs += ` accid.ges="${pitch.accidGes}"`;
     if (!inChord && dots > 0)
@@ -616,8 +654,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
                 const effectiveStaffNum = effectiveStaff ?? layerStaffNum;
                 if (effectiveStaffNum === layerStaffNum) {
                     const clefIndent = beamOpen ? baseIndent + '    ' : baseIndent;
-                    const clefInfo = CLEF_SHAPES[ctx.clef] || CLEF_SHAPES.treble;
-                    xml += `${clefIndent}<clef xml:id="${generateId('clef')}" shape="${clefInfo.shape}" line="${clefInfo.line}" />\n`;
+                    xml += `${clefIndent}<clef xml:id="${generateId('clef')}" ${clefElementAttrs(ctx.clef)} />\n`;
                 }
                 activeClef = ctx.clef;
                 endingClef = ctx.clef;
@@ -655,6 +692,8 @@ const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measur
         let attrs = `xml:id="${generateId('note')}" pname="${pitch.pname}" oct="${pitch.oct}" dur="${noteDur}"`;
         if (pitch.accid)
             attrs += ` accid="${pitch.accid}"`;
+        if (pitch.octGes !== undefined)
+            attrs += ` oct.ges="${pitch.octGes}"`;
         if (pitch.accidGes)
             attrs += ` accid.ges="${pitch.accidGes}"`;
         result += `${indent}    <note ${attrs} />\n`;
@@ -666,6 +705,8 @@ const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measur
             let attrs = `xml:id="${generateId('note')}" pname="${pitch.pname}" oct="${pitch.oct}"`;
             if (pitch.accid)
                 attrs += ` accid="${pitch.accid}"`;
+            if (pitch.octGes !== undefined)
+                attrs += ` oct.ges="${pitch.octGes}"`;
             if (pitch.accidGes)
                 attrs += ` accid.ges="${pitch.accidGes}"`;
             result += `${indent}        <note ${attrs} />\n`;
@@ -678,6 +719,8 @@ const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measur
         let attrs = `xml:id="${generateId('note')}" pname="${pitch.pname}" oct="${pitch.oct}" dur="${noteDur}"`;
         if (pitch.accid)
             attrs += ` accid="${pitch.accid}"`;
+        if (pitch.octGes !== undefined)
+            attrs += ` oct.ges="${pitch.octGes}"`;
         if (pitch.accidGes)
             attrs += ` accid.ges="${pitch.accidGes}"`;
         result += `${indent}    <note ${attrs} />\n`;
@@ -689,6 +732,8 @@ const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measur
             let attrs = `xml:id="${generateId('note')}" pname="${pitch.pname}" oct="${pitch.oct}"`;
             if (pitch.accid)
                 attrs += ` accid="${pitch.accid}"`;
+            if (pitch.octGes !== undefined)
+                attrs += ` oct.ges="${pitch.octGes}"`;
             if (pitch.accidGes)
                 attrs += ` accid.ges="${pitch.accidGes}"`;
             result += `${indent}        <note ${attrs} />\n`;
@@ -1002,8 +1047,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 if (ctx.clef && ctx.clef !== currentClef) {
                     const layerStaff = voice.staff || 1;
                     if (currentStaff === layerStaff) {
-                        const clefInfo = CLEF_SHAPES[ctx.clef] || CLEF_SHAPES.treble;
-                        xml += `${currentIndent}<clef xml:id="${generateId('clef')}" shape="${clefInfo.shape}" line="${clefInfo.line}" />\n`;
+                        xml += `${currentIndent}<clef xml:id="${generateId('clef')}" ${clefElementAttrs(ctx.clef)} />\n`;
                     }
                     currentClef = ctx.clef;
                 }
@@ -1568,8 +1612,7 @@ const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent, meterSymbol
             for (let ls = 1; ls <= info.maxStaff; ls++) {
                 const globalStaff = info.staffOffset + ls;
                 const clef = info.clefs[ls] || Clef.treble;
-                const clefInfo = CLEF_SHAPES[clef] || CLEF_SHAPES.treble;
-                xml += `${indent}            <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" clef.shape="${clefInfo.shape}" clef.line="${clefInfo.line}" />\n`;
+                xml += `${indent}            <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
             }
             xml += `${indent}        </staffGrp>\n`;
         }
@@ -1577,8 +1620,7 @@ const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent, meterSymbol
             // Single staff part
             const globalStaff = info.staffOffset + 1;
             const clef = info.clefs[1] || Clef.treble;
-            const clefInfo = CLEF_SHAPES[clef] || CLEF_SHAPES.treble;
-            xml += `${indent}        <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" clef.shape="${clefInfo.shape}" clef.line="${clefInfo.line}" />\n`;
+            xml += `${indent}        <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
         }
     }
     xml += `${indent}    </staffGrp>\n`;

package/lib/lilylet/serializer.js

@@ -286,7 +286,7 @@ const serializeContextChange = (event) => {
     const parts = [];
     // Clef
     if (event.clef) {
-        parts.push('\\clef "' + CLEF_MAP[event.clef] + '"');
+        parts.push('\\clef "' + (CLEF_MAP[event.clef] ?? event.clef) + '"');
     }
     // Key signature
     if (event.key) {
@@ -549,7 +549,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     const voiceClef = allStaffClefs?.[voice.staff] || findVoiceClef(voice);
     const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
     if (voiceClef && !clefAlreadyEmitted) {
-        parts.push('\\clef "' + CLEF_MAP[voiceClef] + '"');
+        parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? voiceClef) + '"');
         if (emittedClefs)
             emittedClefs[voice.staff] = voiceClef;
     }
@@ -572,7 +572,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 // Emit target staff clef if the event carries one or allStaffClefs knows it
                 const ctxClef = ctx.clef || allStaffClefs?.[activeStaff];
                 if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
-                    parts.push('\\clef "' + CLEF_MAP[ctxClef] + '"');
+                    parts.push('\\clef "' + (CLEF_MAP[ctxClef] ?? ctxClef) + '"');
                     if (emittedClefs)
                         emittedClefs[activeStaff] = ctxClef;
                 }
@@ -596,7 +596,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 // Emit the target staff's clef if it differs from what was last emitted for this staff
                 const targetClef = allStaffClefs?.[activeStaff];
                 if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
-                    parts.push('\\clef "' + CLEF_MAP[targetClef] + '"');
+                    parts.push('\\clef "' + (CLEF_MAP[targetClef] ?? targetClef) + '"');
                     if (emittedClefs)
                         emittedClefs[activeStaff] = targetClef;
                 }
@@ -651,11 +651,15 @@ const serializePart = (part, currentStaff, isGrandStaff = false, measureContext,
     }
     const voiceStrs = [];
     let staff = currentStaff;
+    // A part is a grand staff only if its voices span more than one staff.
+    // Only then do we force \staff on every voice; single-staff parts emit \staff
+    // solely when the staff actually changes (e.g. resetting after a prior grand staff).
+    const partIsGrandStaff = new Set(part.voices.map(v => v.staff)).size > 1;
     for (let i = 0; i < part.voices.length; i++) {
         const voice = part.voices[i];
         // Pass measureContext to all voices, isFirstVoice for key/time
         const isFirstVoice = isFirstPart && i === 0;
-        const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, clefsByStaff, emittedClefs);
+        const { str, newStaff } = serializeVoice(voice, staff, partIsGrandStaff, measureContext, isFirstVoice, clefsByStaff, emittedClefs);
         voiceStrs.push(str);
         staff = newStaff;
     }
@@ -664,7 +668,7 @@ const serializePart = (part, currentStaff, isGrandStaff = false, measureContext,
 };
 // Serialize a measure, tracking staff state across parts
 // Always output key/time at start of each measure
-const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false, currentKey, currentTime, staffClefs, emittedClefs) => {
+const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false, currentKey, currentTime, partStaffClefs, partEmittedClefs) => {
     const parts = [];
     // Build measure context for all voices (key/time)
     // Key and time are written to first voice, clef to all voices based on staff
@@ -673,12 +677,14 @@ const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false,
         key: currentKey,
         time: currentTime,
     };
-    // Pass staffClefs to parts for per-voice clef lookup
-    const clefsByStaff = staffClefs || {};
+    // Per-part clef state: each part has its own staff→clef maps so that distinct
+    // parts sharing staff number 1 do not clobber each other's clefs.
+    const clefsFor = (pi) => partStaffClefs?.[pi] || {};
+    const emittedFor = (pi) => partEmittedClefs?.[pi] || (partEmittedClefs ? (partEmittedClefs[pi] = {}) : {});
     // Parts
     let staff = currentStaff;
     if (measure.parts.length === 1) {
-        const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff, emittedClefs);
+        const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsFor(0), emittedFor(0));
         if (partStr) {
             parts.push(partStr);
         }
@@ -690,7 +696,7 @@ const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false,
         for (let i = 0; i < measure.parts.length; i++) {
             const part = measure.parts[i];
             // Pass measureContext to all parts, isFirstPart to first part only
-            const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff, emittedClefs);
+            const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsFor(i), emittedFor(i));
             if (str) {
                 partStrs.push(str);
             }
@@ -722,6 +728,12 @@ const serializeMetadata = (metadata) => {
     if (metadata.lyricist) {
         lines.push('[lyricist "' + escapeString(metadata.lyricist) + '"]');
     }
+    if (metadata.genre) {
+        lines.push('[genre "' + escapeString(metadata.genre) + '"]');
+    }
+    if (metadata.instrument) {
+        lines.push('[instrument "' + escapeString(metadata.instrument) + '"]');
+    }
     if (metadata.autoBeam) {
         lines.push('[auto-beam "' + escapeString(metadata.autoBeam) + '"]');
     }
@@ -749,8 +761,11 @@ export const serializeLilyletDoc = (doc) => {
     let currentStaff = 1; // Parser starts at staff 1
     let currentKey;
     let currentTime;
-    const staffClefs = {}; // Track clef per staff
-    const emittedClefs = {}; // Track which clefs have been output
+    // Clefs are tracked per part (each part is an independent instrument). Voice `staff`
+    // numbers are staff-within-part, so distinct parts may both use staff 1 — keying clef
+    // state by staff alone would conflate them. Outer key = part index, inner key = staff.
+    const partStaffClefs = {};
+    const partEmittedClefs = {};
     for (let i = 0; i < doc.measures.length; i++) {
         const measure = doc.measures[i];
         // Update current key/time if measure has them
@@ -760,8 +775,9 @@ export const serializeLilyletDoc = (doc) => {
         if (measure.timeSig) {
             currentTime = measure.timeSig;
         }
-        // Collect clefs from this measure's voices
-        for (const part of measure.parts) {
+        // Collect clefs from this measure's voices, per part
+        measure.parts.forEach((part, pi) => {
+            const staffClefs = partStaffClefs[pi] || (partStaffClefs[pi] = {});
             for (const voice of part.voices) {
                 let clefActiveStaff = voice.staff;
                 for (const event of voice.events) {
@@ -776,8 +792,8 @@ export const serializeLilyletDoc = (doc) => {
                     }
                 }
             }
-        }
-        const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs, emittedClefs);
+        });
+        const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, partStaffClefs, partEmittedClefs);
         // Always include measure, even if empty (use space rest for empty measures)
         measureStrs.push(measureStr || 's1');
         currentStaff = newStaff;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -36,6 +36,9 @@
     "test:abc": "tsx ./tests/abc-decoder.ts",
     "test:roundtrip": "tsx ./tests/lilypond-roundtrip.ts",
     "test:abc-svg": "tsx ./tests/abc-abcjs-svg.ts",
+    "train:bpe": "tsx ./tools/trainBpeTokenizer.ts",
+    "build:manual-tokenizer": "tsx ./tools/buildManualTokenizer.ts",
+    "test:bpe": "tsx ./tests/unit/bpeTokenizer.test.ts",
     "build:tests": "tsc -p tsconfig.tests.json; cp source/lilylet/grammar.jison.js lib-tests/source/lilylet/ && cp source/abc/grammar.jison.js lib-tests/source/abc/ && node tools/fixEsmExtensions.cjs lib-tests && ln -sfn ../../tests/assets lib-tests/tests/assets",
     "test:roundtrip:compiled": "node lib-tests/tests/lilypond-roundtrip.js",
     "ts": "tsx"

package/source/abc/abc.jison

@@ -229,6 +229,7 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <key_signature>"treble"				return 'TREBLE';
 <key_signature>"bass"				return 'BASS';
 <key_signature>"tenor"				return 'TENOR';
+<key_signature>"alto"				return 'ALTO';
 <key_signature>"none"				return 'NAME';
 <key_signature>"Dor"				return 'NAME';
 <key_signature>"Phr"				return 'NAME';
@@ -256,14 +257,16 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 <comment>[^\n]+						{ return 'COMMENT'; }
 <comment>\n							{ this.popState(); }
 <spec_comment_name>[ \t]+			{}
-<spec_comment_name>"score"			{ this.popState(); this.pushState('spec_comment'); return 'SCORE'; }
-<spec_comment_name>"staves"			{ this.popState(); this.pushState('spec_comment'); return 'SCORE'; }
+<spec_comment_name>"score"			{ this.popState(); this.pushState('spec_comment'); this._scoreDepth = 0; return 'SCORE'; }
+<spec_comment_name>"staves"			{ this.popState(); this.pushState('spec_comment'); this._scoreDepth = 0; return 'SCORE'; }
 <spec_comment_name>[\w]+			{ this.popState(); this.pushState('spec_comment_skip'); }
 <spec_comment_name>\n				{ this.popState(); this.popState(); }
 <spec_comment>[ \t]+				{}
-<spec_comment>[(){}\[\]|]			return yytext
+<spec_comment>[([{]				{ this._scoreDepth = (this._scoreDepth || 0) + 1; return yytext; }
+<spec_comment>[)\]}]				{ this._scoreDepth = (this._scoreDepth || 0) - 1; return yytext; }
+<spec_comment>[|]					return yytext
 <spec_comment>[\w]+					return 'NN'
-<spec_comment>\n					{ this.popState(); this.popState(); return 'LAYOUT_END'; }
+<spec_comment>\n					{ if (this._scoreDepth > 0) { /* layout continues on next line */ } else { this.popState(); this.popState(); return 'LAYOUT_END'; } }
 <spec_comment_skip>[^\n]+			{}
 <spec_comment_skip>\n				{ this.popState(); this.popState(); }
 
@@ -399,6 +402,7 @@ staff_shift
 key_signature
 	: key_root							-> $1
 	| NAME								-> key(null, $1)
+	| clef								-> $1
 	;
 
 key_root
@@ -412,6 +416,11 @@ clef
 	: TREBLE							-> clef($1)
 	| BASS								-> clef($1)
 	| TENOR								-> clef($1)
+	| ALTO								-> clef($1)
+	| TREBLE plus_minus_number			-> clef($1 + ($2 < 0 ? '-' : '+') + Math.abs($2))
+	| BASS plus_minus_number			-> clef($1 + ($2 < 0 ? '-' : '+') + Math.abs($2))
+	| TENOR plus_minus_number			-> clef($1 + ($2 < 0 ? '-' : '+') + Math.abs($2))
+	| ALTO plus_minus_number			-> clef($1 + ($2 < 0 ? '-' : '+') + Math.abs($2))
 	;
 
 sharp_or_flat
@@ -460,8 +469,11 @@ voice_exp
 	: number							-> voice($1)
 	| number NAME						-> voice($1, $2)
 	| number NAME assigns				-> voice($1, $2, $3)
+	| number NAME plus_minus_number		-> voice($1, $2 + ($3 < 0 ? '-' : '+') + Math.abs($3))
+	| number NAME plus_minus_number assigns	-> voice($1, $2 + ($3 < 0 ? '-' : '+') + Math.abs($3), $4)
 	| NAME								-> voice(1, $1)
 	| NAME assigns						-> voice(1, $1, $2)
+	| NAME plus_minus_number assigns	-> voice(1, $1, $3)
 	| upper_phonet number				-> voice(1, $1 + String($2))
 	| upper_phonet number assigns		-> voice(1, $1 + String($2), $3)
 	| upper_phonet number NAME			-> voice(1, $1 + String($2))
@@ -524,6 +536,7 @@ bar
 	| ':' '|' '|' ':'					-> ':|:'
 	| '|' '|'							-> '||'
 	| '|' ']'							-> '|]'
+	| '|' ']' ':'						-> '|]'
 	| ':' '|' ']'						-> ':|]'
 	| '|' N								-> '|' + $2
 	| ':' '|' N							-> ':|' + $2
@@ -586,6 +599,8 @@ articulation_content
 	| a									-> articulation($1)
 	| "^"								-> articulation($1)
 	| fingering_numbers					-> ({fingering: Number($1)})
+	| '(' fingering_numbers ')'			-> ({fingering: Number($2)})
+	| '(' fingering_numbers				-> ({fingering: Number($2)})
 	| tremolo							-> ({tremolo: $1})
 	| tremolo '-'						-> ({tremolo: $1})	// unknown meaning of '-'?
 	;