@k-l-lambda/lilylet 0.1.74 → 0.1.76

package/lib/lilylet/musicXmlDecoder.js

@@ -7,6 +7,7 @@
 import { DOMParser } from '@xmldom/xmldom';
 import { HairpinType, NavigationMarkType, Placement, } from "./types.js";
 import { getElementText, getElementInt, getElements, getDirectChildren, getChildElements, getAttribute, getAttributeNumber, hasElement, convertPitch, convertDuration, convertKeySignature, convertClef, convertStemDirection, convertArticulation, convertOrnament, convertDynamic, convertPedal, convertBarlineStyle, convertHarmonyToText, createFraction, TYPE_TO_DIVISION, } from "./musicXmlUtils.js";
+import { measureLayoutFromPart } from "./measureLayoutFromXml.js";
 // ============ Spanner Tracker ============
 /**
  * Track spanners (slurs, ties, wedges) by number attribute.
@@ -476,6 +477,31 @@ const parseDirection = (dirEl) => {
     const result = {};
     result.placement = getAttribute(dirEl, 'placement');
     result.staff = getElementInt(dirEl, 'staff');
+    // Navigation jumps live on the <sound> child of <direction> (a sibling of
+    // <direction-type>). Parse it first, before the no-direction-type early return,
+    // so a sound-only direction still contributes its jump semantics.
+    const soundEl = dirEl.getElementsByTagName('sound')[0];
+    if (soundEl) {
+        const sound = {};
+        if (getAttribute(soundEl, 'dacapo') === 'yes')
+            sound.dacapo = true;
+        if (getAttribute(soundEl, 'fine') === 'yes')
+            sound.fine = true;
+        const dalsegno = getAttribute(soundEl, 'dalsegno');
+        if (dalsegno)
+            sound.dalsegno = dalsegno;
+        const segno = getAttribute(soundEl, 'segno');
+        if (segno)
+            sound.segno = segno;
+        const coda = getAttribute(soundEl, 'coda');
+        if (coda)
+            sound.coda = coda;
+        const tocoda = getAttribute(soundEl, 'tocoda');
+        if (tocoda)
+            sound.tocoda = tocoda;
+        if (Object.keys(sound).length > 0)
+            result.sound = sound;
+    }
     const dirTypeEl = dirEl.getElementsByTagName('direction-type')[0];
     if (!dirTypeEl) {
         return result;
@@ -557,7 +583,8 @@ const parseBarline = (barlineEl) => {
     if (repeatEl) {
         const direction = getAttribute(repeatEl, 'direction');
         if (direction) {
-            result.repeat = { direction };
+            const times = getAttributeNumber(repeatEl, 'times');
+            result.repeat = times !== undefined ? { direction, times } : { direction };
         }
     }
     const endingEl = barlineEl.getElementsByTagName('ending')[0];
@@ -864,7 +891,10 @@ const directionToMarks = (direction, spannerTracker) => {
     // Tempo words ("Allegro", "a tempo", ...) are consumed separately as a tempo
     // ContextChange by directionToContextChange, so skip those here to avoid
     // double-emitting; everything else becomes a markup mark → MEI <dir>. Metronome
-    // directions are tempo too, never markup.
+    // directions are tempo too, never markup. Navigation text ("D.C. al Fine",
+    // "To Coda", "Fine", "D.S. al Coda") is NOT a tempo word, so it flows here as a
+    // markup glyph — the jump SEMANTICS are captured separately as measure-layout.
+    let emittedWords = false;
     if (direction.words && direction.words.length > 0 && !direction.metronome) {
         const text = direction.words.map(w => w.text).join('').trim();
         if (text && !isTempoWord(text)) {
@@ -872,6 +902,26 @@ const directionToMarks = (direction, spannerTracker) => {
                 : direction.placement === 'below' ? Placement.below
                     : undefined;
             marks.push({ markType: 'markup', content: text, placement });
+            emittedWords = true;
+        }
+    }
+    // A <sound> navigation with NO visible <words> (e.g. a bare <sound tocoda=>):
+    // synthesize the conventional glyph text so the score still shows the marking.
+    // Segno/coda GLYPHS (the symbols, via <direction-type><segno|coda>) are already
+    // emitted above as NavigationMark; only the textual D.C./D.S./Fine/To-Coda need
+    // synthesizing, and only when the engraver left them implicit.
+    if (!emittedWords && direction.sound && !direction.coda && !direction.segno) {
+        const s = direction.sound;
+        const label = s.dacapo ? (s.fine ? 'D.C. al Fine' : 'D.C.')
+            : s.dalsegno ? (s.fine ? 'D.S. al Fine' : 'D.S. al Coda')
+                : s.tocoda ? 'To Coda'
+                    : s.fine ? 'Fine'
+                        : undefined;
+        if (label) {
+            const placement = direction.placement === 'above' ? Placement.above
+                : direction.placement === 'below' ? Placement.below
+                    : undefined;
+            marks.push({ markType: 'markup', content: label, placement });
         }
     }
     return marks;
@@ -928,6 +978,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
     let key;
     let timeSig;
     let barline;
+    let leadingBarline;
     const harmonies = [];
     const clefs = new Map();
     // Pending marks from directions (to attach to next note), per voice
@@ -944,6 +995,15 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
     // layer (otherwise the encoder can't pair them and drops the span).
     const pendingContextChanges = [];
     let currentVoice = 1; // Track current voice for directions
+    // Mid-measure clef support: a staff can change clef partway through a measure
+    // (common in scale/arpeggio études where the LH crosses up). Such a clef arrives
+    // in an <attributes> block AFTER notes on that staff. We must attach it inline at
+    // that point on the staff's currently-active voice, not collapse it into the
+    // measure-start `clefs` map (which keeps only one clef per staff and emits it at
+    // the bar start). Track the last voice that added a note on each staff, and which
+    // staves already have notes this measure.
+    const lastVoiceOnStaff = new Map();
+    const staffHasNotes = new Set();
     // Process all children in order
     for (const child of getChildElements(measureEl)) {
         const tagName = child.tagName;
@@ -968,7 +1028,32 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
                 for (const clefEntry of attrs.clefs) {
                     const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
                     if (clef) {
-                        clefs.set(clefEntry.staff, { type: 'context', clef });
+                        const staff = clefEntry.staff;
+                        if (staffHasNotes.has(staff)) {
+                            // Mid-measure clef change: this staff already has notes in this
+                            // measure, so the clef takes effect HERE, not at the bar start.
+                            // Append it inline on the staff's currently-active voice via
+                            // addEvent (which inserts a staff-switch context if that voice is
+                            // currently positioned on another staff — e.g. a cross-staff
+                            // voice — so the clef binds to `staff`, not the voice's current
+                            // staff). Zero duration: a clef does not advance time.
+                            const vNum = lastVoiceOnStaff.get(staff);
+                            if (vNum !== undefined) {
+                                // Tag the clef context with its staff explicitly. In a
+                                // cross-staff voice (where notes interleave staves) a bare
+                                // clef is ambiguous and is dropped/misplaced by the serializer;
+                                // the explicit staff makes it self-describing (serializer emits
+                                // `\staff "N" \clef ...`). addEvent still inserts a leading
+                                // staff switch when the voice is currently on another staff.
+                                voiceTracker.addEvent(vNum, { type: 'context', staff, clef }, 0, staff);
+                            }
+                            else {
+                                clefs.set(staff, { type: 'context', clef });
+                            }
+                        }
+                        else {
+                            clefs.set(staff, { type: 'context', clef });
+                        }
                     }
                 }
             }
@@ -978,6 +1063,10 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             const voiceNum = note.voice;
             const staffNum = note.staff || 1;
             currentVoice = voiceNum;
+            // Record that this staff now has notes this measure and which voice is
+            // active on it, so a subsequent mid-measure <clef> attaches inline here.
+            staffHasNotes.add(staffNum);
+            lastVoiceOnStaff.set(staffNum, voiceNum);
             // Ensure voice exists with correct staff tracking (needed for cross-staff tuplets
             // where notes go to tupletTracker but voice must be initialized for staff detection)
             voiceTracker.getOrCreateVoice(voiceNum, staffNum);
@@ -1159,7 +1248,15 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             const barlineData = parseBarline(child);
             const style = convertBarlineStyle(barlineData.barStyle, barlineData.repeat?.direction);
             if (style && style !== '|') {
-                barline = { type: 'barline', style };
+                // A `location="left"` barline (forward repeat at the measure front)
+                // is carried back onto the previous measure's end bar by convertPart;
+                // everything else is this measure's own trailing end bar.
+                if (barlineData.location === 'left') {
+                    leadingBarline = { type: 'barline', style };
+                }
+                else {
+                    barline = { type: 'barline', style };
+                }
             }
         }
         else if (tagName === 'harmony') {
@@ -1252,7 +1349,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             staff: voiceState.staff,
         });
     }
-    return { voiceMap, key, timeSig, barline, harmonies, clefs };
+    return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
 };
 /**
  * Convert a MusicXML part to Lilylet measures
@@ -1268,10 +1365,27 @@ const convertPart = (partEl) => {
     let isFirstMeasure = true;
     let lastVoiceStaff = 1; // Track last known primary voice staff for empty measure fallback
     const lastClefs = new Map(); // Track last clef per staff
+    // Initial clef per staff declared in the FIRST <attributes> block. A staff whose
+    // first voice does not appear until a later measure (e.g. an accompaniment staff
+    // silent for the opening bars) would otherwise lose its initial clef — it is only
+    // declared in measure 1's attributes, where that staff has no voice to attach it
+    // to. We hold these and flush each onto the staff's FIRST appearing voice.
+    const pendingInitialClefs = new Map();
     const measureEls = getDirectChildren(partEl, 'measure');
     for (const measureEl of measureEls) {
         voiceTracker.reset();
-        const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+        const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+        // A forward-repeat (or any `location="left"`) barline belongs at the END of
+        // the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.
+        // Append it to the previous measure's first voice; if this is the first
+        // measure there is no previous one, so a leading repeat at the very start of
+        // the piece is conventionally dropped.
+        if (leadingBarline && measures.length > 0) {
+            const prevVoices = measures[measures.length - 1].parts[0]?.voices;
+            if (prevVoices && prevVoices.length > 0) {
+                prevVoices[0].events.push(leadingBarline);
+            }
+        }
         // Update running key/time
         if (key)
             lastKey = key;
@@ -1306,11 +1420,45 @@ const convertPart = (partEl) => {
                             lastClefs.set(voiceData.staff, clef);
                         }
                     }
+                    pendingInitialClefs.delete(voiceData.staff);
+                }
+                else if (pendingInitialClefs.has(voiceData.staff)) {
+                    // This staff's clef was declared in an earlier measure where the staff
+                    // had no voice to carry it (its first appearance is delayed, or it is
+                    // an intermittently-empty cross-staff passage). This measure declares
+                    // no clef of its own — emit the carried-forward pending clef if it
+                    // differs from the clef last in effect for this staff.
+                    const pending = pendingInitialClefs.get(voiceData.staff);
+                    const lastClef = lastClefs.get(voiceData.staff);
+                    const isSameClef = lastClef &&
+                        lastClef.clef === pending.clef;
+                    if (!isSameClef) {
+                        events.push(pending);
+                        lastClefs.set(voiceData.staff, pending);
+                    }
+                    pendingInitialClefs.delete(voiceData.staff);
                 }
                 staffsWithClef.add(voiceData.staff);
             }
             // Add voice events
             events.push(...voiceData.events);
+            // A mid-measure clef change was appended inline to this voice's events (it
+            // does not pass through the measure-start `clefs` map). Scan for the LAST
+            // clef per staff in this voice and update lastClefs, so the next measure's
+            // dedup compares against the clef actually in effect — otherwise a later
+            // measure restating the pre-change clef would be wrongly suppressed.
+            {
+                let scanStaff = voiceData.staff;
+                for (const ev of voiceData.events) {
+                    if (ev.type === 'context') {
+                        const c = ev;
+                        if (c.staff != null)
+                            scanStaff = c.staff;
+                        if (c.clef)
+                            lastClefs.set(scanStaff, { type: 'context', clef: c.clef });
+                    }
+                }
+            }
             // Add harmonies and barline to first voice only
             if (voiceNum === voiceNumbers[0]) {
                 for (const h of harmonies) {
@@ -1332,6 +1480,16 @@ const convertPart = (partEl) => {
         else {
             lastVoiceStaff = voices[0].staff || 1;
         }
+        // Carry forward any clef declared this measure for a staff that had NO voice to
+        // attach it to (an intermittently-empty staff — e.g. cross-staff passages where
+        // the LH is written entirely on the upper staff for several bars). Remember it
+        // as pending so it is emitted when that staff next reappears; otherwise the clef
+        // (and any change it represents) is lost when this measure's `clefs` map is
+        // discarded. Generalizes the first-measure seeding above to every measure.
+        for (const [staff, clef] of clefs) {
+            if (!staffsWithClef.has(staff))
+                pendingInitialClefs.set(staff, clef);
+        }
         const measure = {
             parts: [{
                     voices,
@@ -1450,6 +1608,14 @@ export const decode = (input) => {
     const result = {
         measures: mergedMeasures,
     };
+    // Derive the performance order (repeats / voltas / D.C. / D.S. / Coda / Fine)
+    // from the first part's barline + <sound> navigation markup → measure-layout
+    // string. The MEI encoder turns this into an <expansion> that verovio unfolds
+    // for MIDI. Repeat markup is part-global; the first part carries it. Never
+    // throws (returns undefined when there is nothing to unfold).
+    const measureLayout = measureLayoutFromPart(partEls[0]);
+    if (measureLayout)
+        metadata.measureLayout = measureLayout;
     if (Object.keys(metadata).length > 0) {
         result.metadata = metadata;
     }

package/lib/lilylet/musicXmlTypes.d.ts

@@ -120,12 +120,21 @@ export interface MusicXmlDirection {
     octaveShift?: MusicXmlOctaveShift;
     coda?: boolean;
     segno?: boolean;
+    sound?: {
+        dacapo?: boolean;
+        dalsegno?: string;
+        segno?: string;
+        coda?: string;
+        tocoda?: string;
+        fine?: boolean;
+    };
 }
 export interface MusicXmlBarline {
     location?: 'left' | 'right' | 'middle';
     barStyle?: string;
     repeat?: {
         direction: 'forward' | 'backward';
+        times?: number;
     };
     ending?: {
         type: 'start' | 'stop' | 'discontinue';

package/lib/lilylet/serializer.js

@@ -5,6 +5,44 @@
  * Uses relative pitch mode matching the parser's behavior.
  */
 import { StemDirection, } from "./types.js";
+import { parseMeasureLayout } from "./measureLayout.js";
+// Walk a measure-layout AST, recording the FIRST measure index of each alternate
+// ending (1st/2nd house) → its ending number, for the `% volta N` serializer
+// comment convention. Only the alternates of a VoltaMLayout produce labels.
+const collectVoltaLabels = (layout, out) => {
+    const firstIndexOf = (node) => {
+        switch (node.kind) {
+            case "single": return node.measure;
+            case "block": return node.seq.length ? firstIndexOf(node.seq[0]) : undefined;
+            case "volta": return node.body.length ? firstIndexOf(node.body[0]) : undefined;
+            case "aba": return firstIndexOf(node.main);
+        }
+    };
+    const walk = (node) => {
+        switch (node.kind) {
+            case "block":
+                node.seq.forEach(walk);
+                break;
+            case "aba":
+                walk(node.main);
+                node.rest.forEach(walk);
+                break;
+            case "volta":
+                node.body.forEach(walk);
+                if (node.alternates) {
+                    node.alternates.forEach((alt, ai) => {
+                        const first = alt.length ? firstIndexOf(alt[0]) : undefined;
+                        if (first !== undefined && !out.has(first))
+                            out.set(first, ai + 1);
+                        alt.forEach(walk);
+                    });
+                }
+                break;
+            default: break;
+        }
+    };
+    walk(layout);
+};
 const PHONETS = "cdefgab";
 /**
  * Calculate the octave markers needed to serialize a pitch in relative mode.
@@ -369,10 +407,20 @@ const serializeTupletEvent = (event, env) => {
         }
         else if (e.type === 'context') {
             const ctx = e;
+            // A context event inside a tuplet may carry several components at once
+            // (e.g. staff + clef). Emit each present one — previously only staff and
+            // stemDirection were handled, so a clef/ottava change inside a tuplet was
+            // silently dropped on serialization.
             if (ctx.staff != null) {
                 parts.push(' \\staff "' + ctx.staff + '"');
             }
-            else if (ctx.stemDirection != null) {
+            if (ctx.clef != null) {
+                parts.push(' \\clef "' + (CLEF_MAP[ctx.clef] ?? ctx.clef) + '"');
+            }
+            if (ctx.ottava != null) {
+                parts.push(' \\ottava #' + ctx.ottava);
+            }
+            if (ctx.stemDirection != null) {
                 if (ctx.stemDirection === StemDirection.up)
                     parts.push(' \\stemUp');
                 else if (ctx.stemDirection === StemDirection.down)
@@ -459,7 +507,7 @@ const serializeEvent = (event, env, prevDuration, suppressGracePrefix = false) =
         case 'markup': {
             const mk = event;
             const prefix = mk.placement === 'above' ? '^' : mk.placement === 'below' ? '_' : '';
-            return { str: `${prefix}\\markup "${mk.content}"`, newEnv: env };
+            return { str: `${prefix}\\markup "${escapeString(mk.content)}"`, newEnv: env };
         }
         case 'dynamic': {
             const dynStr = DYNAMIC_MAP[event.dynamicType];
@@ -511,6 +559,32 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     // context{staff} events before this index are skipped in the main loop.
     let effectiveInitialStaff = voice.staff;
     let leadStaffScanEnd = 0;
+    // Staff of the first MUSICAL event (note/rest/...), honouring an explicit
+    // note.staff. If it differs from the home staff, the first inline staff switch
+    // would emit a `\staff "X"` that the parser mistakes for the LEADING staff (it
+    // binds home to the first `\staff` before any music), relocating the voice and
+    // any leading clef. We then force an explicit home-staff anchor up front. This
+    // scan is independent of leadStaffScanEnd because a leading clef/key stops that
+    // scan before the first note is reached.
+    let firstMusicalStaff = null;
+    {
+        let scanStaff = voice.staff;
+        for (const e of voice.events) {
+            if (e.type === 'context') {
+                const ctx = e;
+                if (ctx.staff != null)
+                    scanStaff = ctx.staff;
+                continue;
+            }
+            if (e.type === 'pitchReset')
+                continue;
+            if (e.type === 'note')
+                firstMusicalStaff = e.staff ?? scanStaff;
+            else
+                firstMusicalStaff = scanStaff;
+            break;
+        }
+    }
     for (let i = 0; i < voice.events.length; i++) {
         const e = voice.events[i];
         if (e.type === 'pitchReset') {
@@ -538,10 +612,19 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
         // visible position; a staff switch after it must not be hoisted ahead of it.
         break;
     }
-    // Output staff command if voice staff differs from current parser staff,
-    // or always output if it's a grand staff score for clarity.
-    // Use effectiveInitialStaff so carry-over replaces the default emission.
-    if (isGrandStaff || effectiveInitialStaff !== currentStaff) {
+    // Output staff command if the voice's initial staff is not what the PARSER will
+    // assume. The parser (lilylet.jison voice()) assigns every voice with no leading
+    // `\staff` directive to staff 1 unconditionally — it does NOT carry staff across
+    // voices or measures. So we must emit `\staff "N"` whenever effectiveInitialStaff
+    // is not 1, even if the cross-measure carry (currentStaff) happens to match it
+    // (e.g. a whole measure sitting on staff 2 after a prior staff-2 measure — without
+    // this, the round-trip would silently relocate that voice, and its leading clef,
+    // to staff 1). Also emit when it differs from the carry (resets after grand staff)
+    // or always in a grand-staff part for clarity. Finally, force an anchor when the
+    // first note switches staff via note.staff (otherwise that inline `\staff` would
+    // be read as the leading staff and rebind the voice's home).
+    const firstNoteSwitches = firstMusicalStaff != null && firstMusicalStaff !== effectiveInitialStaff;
+    if (isGrandStaff || effectiveInitialStaff !== 1 || effectiveInitialStaff !== currentStaff || firstNoteSwitches) {
         parts.push('\\staff "' + effectiveInitialStaff + '"');
     }
     // Output key/time signatures after \staff (for first voice only)
@@ -568,7 +651,17 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     // Prefer this voice's leading clef (a clef before any music); fall back to the
     // carry-in clef from previous measures. A clef that first appears mid-voice is NOT
     // hoisted here — it is emitted inline at its position.
-    const voiceClef = findVoiceClef(voice) ?? allStaffClefs?.[voice.staff];
+    //
+    // The carry-in fallback (`allStaffClefs[staff]`) is the clef state at the START of
+    // the measure and is NOT updated mid-measure, whereas `emittedClefs` IS. So a voice
+    // with no clef of its own must only use the fallback to ESTABLISH a staff that has
+    // not been emitted yet — never to "restate" it once any sibling voice has already
+    // emitted/changed this staff's clef this measure, because the fallback would then be
+    // stale and would wrongly revert that sibling's change (e.g. v1 moves staff 2 to
+    // treble, then v2 with no clef must not re-emit the carried-in bass).
+    const ownClef = findVoiceClef(voice);
+    const carryClef = allStaffClefs?.[voice.staff];
+    const voiceClef = ownClef ?? (emittedClefs?.[voice.staff] === undefined ? carryClef : undefined);
     const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
     if (voiceClef && !clefAlreadyEmitted) {
         parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? voiceClef) + '"');
@@ -591,7 +684,8 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 activeStaff = ctx.staff;
                 parts.push('\\staff "' + activeStaff + '"');
                 // Emit target staff clef if the event carries one or allStaffClefs knows it
-                const ctxClef = ctx.clef || allStaffClefs?.[activeStaff];
+                const ctxClef = ctx.clef ||
+                    (emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined);
                 if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
                     parts.push('\\clef "' + (CLEF_MAP[ctxClef] ?? ctxClef) + '"');
                     if (emittedClefs)
@@ -618,7 +712,7 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
                 activeStaff = effectiveStaff;
                 parts.push('\\staff "' + activeStaff + '"');
                 // Emit the target staff's clef if it differs from what was last emitted for this staff
-                const targetClef = allStaffClefs?.[activeStaff];
+                const targetClef = emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined;
                 if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
                     parts.push('\\clef "' + (CLEF_MAP[targetClef] ?? targetClef) + '"');
                     if (emittedClefs)
@@ -747,7 +841,12 @@ const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false,
 };
 // Escape string for serialization (quotes and backslashes)
 const escapeString = (str) => {
-    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
 };
 // Serialize metadata
 const serializeMetadata = (metadata) => {
@@ -776,6 +875,9 @@ const serializeMetadata = (metadata) => {
     if (metadata.staves) {
         lines.push('[staves "' + escapeString(metadata.staves) + '"]');
     }
+    if (metadata.measureLayout) {
+        lines.push('[measures "' + escapeString(metadata.measureLayout) + '"]');
+    }
     if (metadata.instruments) {
         for (const [key, instr] of Object.entries(metadata.instruments)) {
             let line = '[instrument-' + key + ' "' + escapeString(instr.name) + '"';
@@ -856,9 +958,26 @@ export const serializeLilyletDoc = (doc) => {
         measureStrs.push(measureStr || 's1');
         currentStaff = newStaff;
     }
-    // Join measures with bar, measure number comment, and double newline
+    // Volta house-label comments (non-binding convention, like the `% n` measure
+    // index): if a measure-layout directive is present, mark the first measure of
+    // each alternate ending with a `% volta N` comment. Derived from the layout
+    // AST; purely cosmetic, never parsed back.
+    const voltaLabels = new Map(); // 1-based measure index → ending number
+    if (doc.metadata?.measureLayout) {
+        try {
+            const layout = parseMeasureLayout(doc.metadata.measureLayout);
+            collectVoltaLabels(layout, voltaLabels);
+        }
+        catch { /* ignore malformed layout */ }
+    }
+    // Join measures with bar, measure number comment, and double newline. A
+    // `% volta N` label (if any) is prepended on its own line before the measure.
     const measuresOutput = measureStrs
-        .map((m, i) => m + ' | %' + (i + 1))
+        .map((m, i) => {
+        const label = voltaLabels.get(i + 1);
+        const prefix = label !== undefined ? '% volta ' + label + '\n' : '';
+        return prefix + m + ' | %' + (i + 1);
+    })
         .join('\n\n');
     parts.push(measuresOutput);
     return parts.join('\n');

package/lib/lilylet/types.d.ts

@@ -242,6 +242,7 @@ export interface Metadata {
     instrument?: string;
     genre?: string;
     staves?: string;
+    measureLayout?: string;
     instruments?: {
         [key: string]: InstrumentName;
     };

package/lib/measureLayout.d.ts

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

package/lib/measureLayout.js

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

package/lib/measureLayoutFromXml.d.ts

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

package/lib/measureLayoutFromXml.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "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",
@@ -40,11 +40,14 @@
     "test:decoder": "tsx ./tests/lilypondDecoder.ts",
     "test:abc": "tsx ./tests/abc-decoder.ts",
     "test:roundtrip": "tsx ./tests/lilypond-roundtrip.ts",
+    "test:lyl-roundtrip": "tsx ./tests/lyl-roundtrip.ts",
     "test:abc-svg": "tsx ./tests/abc-abcjs-svg.ts",
     "train:bpe": "tsx ./tools/trainBpeTokenizer.ts",
     "build:manual-tokenizer": "tsx ./tools/buildManualTokenizer.ts",
     "build:browser-bundle": "esbuild tools/browserBundle.ts --bundle --format=iife --platform=browser --minify --outfile=dist/lilylet.bundle.js",
     "test:bpe": "tsx ./tests/unit/bpeTokenizer.test.ts",
+    "test:measures": "tsx ./tests/unit/measureLayout.test.ts",
+    "test:measures-xml": "tsx ./tests/unit/measureLayoutFromXml.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"
@@ -70,7 +73,7 @@
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
-    "verovio": "^5.7.0",
+    "verovio": "^6.2.0",
     "yargs": "^17.7.2"
   },
   "dependencies": {