@k-l-lambda/lilylet 0.1.74 → 0.1.75

package/lib/lilylet/meiEncoder.js

@@ -1,6 +1,7 @@
 import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType, } from "./types.js";
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { gmProgramOf } from "./gmInstruments.js";
+import { parseMeasureLayout, expandMeasureLayout, collectVoltaSpans } from "./measureLayout.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -641,6 +642,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
     const effectiveStaff = currentStaff ?? layerStaff;
     // Collect control event info from notes inside tuplet
     let firstNoteId = null;
+    let lastNoteId = null; // last note/rest id — anchors an ottava span end
     const slurStarts = [];
     const slurEnds = [];
     const dynamics = [];
@@ -675,6 +677,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             xml += result.xml;
             if (!firstNoteId)
                 firstNoteId = result.elementId;
+            lastNoteId = result.elementId;
             // Collect slur info
             if (result.slurStart)
                 slurStarts.push(result.elementId);
@@ -714,6 +717,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
             const restResult = restEventToMEI(e, restIndent, keyFifths, ottavaShift, measureAccidentals);
             xml += restResult.xml;
+            lastNoteId = restResult.elementId;
             if (restResult.fermata)
                 fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
         }
@@ -736,7 +740,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
         xml += `${baseIndent}</beam>\n`;
     }
     xml += `${indent}</tuplet>\n`;
-    return { xml, firstNoteId, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios, pedals, fingerings, markups, endingClef };
+    return { xml, firstNoteId, lastNoteId, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios, pedals, fingerings, markups, endingClef };
 };
 // Convert TremoloEvent to MEI (fingered tremolo - alternating between two notes)
 const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measureAccidentals) => {
@@ -866,6 +870,43 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     let currentOttavaShift = initialOctave?.shift || 0; // Track current ottava shift for pitch encoding
     let lastNoteId = null; // Track last note id for ending ottava spans
     let ottavaExplicitlyClosed = false; // Track if ottava was explicitly closed by \ottava #0
+    // ── Ottava span anchoring (shared by note / rest / tuplet cases) ──
+    // Originally the open/extend/close logic lived ONLY in `case 'note'`, so an
+    // ottava span running over a tuplet run (ubiquitous in etudes) or over rests
+    // was never opened — the whole span vanished (No.26 10→0, No.20 7→0). These
+    // helpers let any event type anchor a span. Mirror the note-case ordering:
+    // the caller updates lastNoteId to the event's first emitted id, THEN calls
+    // these.
+    // Apply a pending ottava's pitch shift before the event's notes are encoded.
+    const applyPendingOttavaShift = () => {
+        if (pendingOttava !== null && pendingOttava !== 0)
+            currentOttavaShift = pendingOttava;
+    };
+    // Extend a carried (endToken) span's end to this event's last emitted id.
+    const extendOttavaEnd = (lastId) => {
+        if (currentOctave?.endToken)
+            octaveEndReplacements[currentOctave.endToken] = lastId;
+    };
+    // Open the pending ottava span on `anchorId` (the event's FIRST emitted id),
+    // closing any open span of a different value first; or resolve a continued span.
+    const applyOttavaAnchor = (anchorId) => {
+        if (pendingOttava !== null && pendingOttava !== 0) {
+            const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
+            const disPlace = pendingOttava > 0 ? 'above' : 'below';
+            if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
+                octaves.push({ dis: currentOctave.dis, disPlace: currentOctave.disPlace, startId: currentOctave.startId, endId: anchorId });
+                currentOctave = null;
+            }
+            if (!currentOctave)
+                currentOctave = { dis, disPlace, startId: anchorId };
+            pendingOttava = null;
+        }
+        else if (currentOctave?.continued) {
+            if (!currentOctave.endToken)
+                currentOctave.startId = anchorId;
+            currentOctave.continued = false;
+        }
+    };
     // Track slur spans - slurs must be encoded as control events in MEI.
     // A single slot can't hold the overlapping/concurrent slurs that piano writing
     // produces (measured up to 3 open at once per voice); a new start while one was
@@ -957,9 +998,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 // Check if this note should have tie="t" (matches pending tie)
                 const tieEnd = pendingTiePitches.length > 0 && pitchesMatch(pendingTiePitches, noteEvent.pitches);
                 // If there's a pending ottava, apply it BEFORE encoding the note
-                if (pendingOttava !== null && pendingOttava !== 0) {
-                    currentOttavaShift = pendingOttava; // Apply the shift for this note
-                }
+                applyPendingOttavaShift();
                 // For cross-staff notation: set note's staff to currentStaff if different from voice.staff
                 const effectiveNoteEvent = currentStaff !== voice.staff
                     ? { ...noteEvent, staff: currentStaff }
@@ -967,41 +1006,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals);
                 xml += result.xml;
                 lastNoteId = result.elementId;
-                if (currentOctave?.endToken) {
-                    octaveEndReplacements[currentOctave.endToken] = result.elementId;
-                }
+                extendOttavaEnd(result.elementId);
                 // Flush any pending markups onto this note
                 flushPendingMarkups(result.elementId);
                 // Flush any pending leading dynamics onto this note
                 flushPendingDynamics(result.elementId);
                 // If there's a pending ottava, start the span on this note
-                if (pendingOttava !== null && pendingOttava !== 0) {
-                    const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
-                    const disPlace = pendingOttava > 0 ? 'above' : 'below';
-                    // Close existing span first if it has a different value
-                    if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
-                        if (lastNoteId) {
-                            octaves.push({
-                                dis: currentOctave.dis,
-                                disPlace: currentOctave.disPlace,
-                                startId: currentOctave.startId,
-                                endId: lastNoteId,
-                            });
-                        }
-                        currentOctave = null;
-                    }
-                    // Start new span if we don't already have one with the same value
-                    if (!currentOctave) {
-                        currentOctave = { dis, disPlace, startId: result.elementId };
-                    }
-                    pendingOttava = null;
-                }
-                else if (currentOctave?.continued) {
-                    if (!currentOctave.endToken) {
-                        currentOctave.startId = result.elementId;
-                    }
-                    currentOctave.continued = false;
-                }
+                applyOttavaAnchor(result.elementId);
                 // Update pending tie pitches
                 if (result.hasTieStart) {
                     pendingTiePitches = result.pitches;
@@ -1101,23 +1112,39 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
             case 'rest': {
                 // For cross-staff notation: pass staff number if different from voice's home staff
                 const restCrossStaff = currentStaff !== (voice.staff || 1) ? currentStaff : undefined;
+                // A pending ottava shift applies to a rest's gestural octave too.
+                applyPendingOttavaShift();
                 const restResult = restEventToMEI(event, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
                 xml += restResult.xml;
+                lastNoteId = restResult.elementId;
+                // An ottava span may open on, run through, or close at a rest (e.g. a
+                // span that starts just before LH rests). Anchor it like a note.
+                extendOttavaEnd(restResult.elementId);
+                applyOttavaAnchor(restResult.elementId);
                 // Fermata over a rest (held silence) — emit as a control event on the rest.
                 if (restResult.fermata)
                     fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
                 // A leading dynamic/markup attaches to the next event, which may be this rest
                 flushPendingMarkups(restResult.elementId);
                 flushPendingDynamics(restResult.elementId);
-                lastNoteId = restResult.elementId;
                 break;
             }
             case 'tuplet':
             case 'times': {
                 // Tuplet can be nested inside beam in MEI: <beam><tuplet>...</tuplet></beam>
                 // Pass beamElementOpen to tuplet so it knows not to create its own beam
+                // A pending ottava shift applies to the tuplet's notes' written octave.
+                applyPendingOttavaShift();
                 const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
                 xml += tupletResult.xml;
+                // An ottava span can open on, run through, or close at a tuplet (common
+                // in etudes where the 8va covers a whole tuplet run). Anchor the span on
+                // the tuplet's FIRST note and let its LAST note close/extend it — without
+                // this the entire span was dropped (start/close lived only in case 'note').
+                if (tupletResult.firstNoteId)
+                    applyOttavaAnchor(tupletResult.firstNoteId);
+                if (tupletResult.lastNoteId)
+                    extendOttavaEnd(tupletResult.lastNoteId);
                 // Propagate clef change from inside the tuplet to the parent tracker
                 if (tupletResult.endingClef) {
                     currentClef = tupletResult.endingClef;
@@ -1126,7 +1153,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 if (tupletResult.firstNoteId) {
                     flushPendingMarkups(tupletResult.firstNoteId);
                     flushPendingDynamics(tupletResult.firstNoteId);
-                    lastNoteId = tupletResult.firstNoteId;
+                    lastNoteId = tupletResult.lastNoteId ?? tupletResult.firstNoteId;
                 }
                 // Process slur ends first (to close open slurs, LIFO), then starts.
                 for (const endId of tupletResult.slurEnds) {
@@ -1185,8 +1212,22 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                             currentOctave = null;
                             ottavaExplicitlyClosed = true; // Mark that we explicitly closed the span
                         }
-                        // Note: if no lastNoteId (e.g., at measure start), keep currentOctave alive
-                        // It may be continued by a subsequent ottava command with the same value
+                        else if (currentOctave && currentOctave.emitted) {
+                            // Stop landed at measure START (no note yet in this layer) but the
+                            // span was carried+emitted in a PREVIOUS measure: it genuinely ends
+                            // here. Its deferred endToken was already resolved to the correct
+                            // last note by extendOttavaEnd as the span ran through prior measures
+                            // (or by the staff-level carry's endFallbackId), so DON'T rewrite it
+                            // here — just clear the slot and mark closed, so a later same-value
+                            // ottava opens a NEW span instead of folding into this one.
+                            // Without this, sequential cross-measure spans collapse into one
+                            // (No.57: 18 spans → 8).
+                            currentOctave = null;
+                            ottavaExplicitlyClosed = true;
+                        }
+                        // Note: if no lastNoteId and not yet emitted (e.g., open+close at
+                        // measure start with no notes), keep currentOctave alive — it may be
+                        // continued by a subsequent ottava command with the same value.
                         currentOttavaShift = 0; // Reset the shift (will be restored if continued)
                     }
                     else {
@@ -1525,8 +1566,10 @@ const BARLINE_TO_MEI = {
 };
 // Encode a measure
 // encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
-const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, ottavaState, keyFifths = 0, partInfos = [], clefState = {}, octaveEndReplacements = {}) => {
+const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, ottavaState, keyFifths = 0, partInfos = [], clefState = {}, octaveEndReplacements = {}, measureIds) => {
     const measureId = generateId("measure");
+    if (measureIds)
+        measureIds.push(measureId);
     let staffContent = ''; // Build staff content first, then add measure tag with barline
     const allHairpins = [];
     const allPedals = [];
@@ -2246,6 +2289,36 @@ const encode = (doc, options = {}) => {
     mei += `${indent}${indent}${indent}${indent}<score xml:id="${generateId("score")}">\n`;
     mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol, doc.metadata?.staves, doc.metadata?.instruments);
     mei += `${indent}${indent}${indent}${indent}${indent}<section xml:id="${generateId("section")}">\n`;
+    // Splice point for an <expansion> element (must be the FIRST child of
+    // <section>, but its plist needs the measure ids collected during the loop
+    // below — so remember where to insert it and build it afterwards).
+    const expansionInsertPos = mei.length;
+    const measureIds = [];
+    // Volta (1st/2nd-ending) house brackets. The measure-layout directive already
+    // encodes which measures form each alternate; <expansion> replays them but does
+    // NOT draw the 1./2. brackets. So derive each alternate's contiguous measure
+    // span and wrap that run of <measure>s in an <ending n="N"> container (verovio's
+    // own MusicXML import does the same). Keyed by the 1-based measure index where
+    // an ending opens / closes.
+    const endingOpenAt = new Map(); // measure index → ending number
+    const endingCloseAt = new Set(); // measure index after which </ending> closes
+    if (doc.metadata?.measureLayout) {
+        try {
+            const spans = collectVoltaSpans(parseMeasureLayout(doc.metadata.measureLayout));
+            for (const s of spans) {
+                // Only wrap a contiguous ascending run (a house is always adjacent bars).
+                const lo = s.measures[0];
+                const hi = s.measures[s.measures.length - 1];
+                const contiguous = s.measures.every((m, k) => m === lo + k);
+                if (contiguous) {
+                    endingOpenAt.set(lo, s.number);
+                    endingCloseAt.add(hi);
+                }
+            }
+        }
+        catch { /* malformed layout → no house brackets, expansion path handles the rest */ }
+    }
+    let endingOpen = false; // whether an <ending> is currently open in the output
     // Track tie state across measures for cross-measure ties
     const tieState = {};
     // Track slur state across measures for cross-measure slurs
@@ -2352,8 +2425,55 @@ const encode = (doc, options = {}) => {
                 mei += `${sd}</scoreDef>\n`;
             }
         }
-        mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements);
+        const mIndex = mi + 1;
+        const mIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+        // Open an <ending> house bracket if this measure starts an alternate.
+        const openNum = endingOpenAt.get(mIndex);
+        if (openNum !== undefined && !endingOpen) {
+            const lendsym = openNum === 1 ? ' lendsym="angledown"' : '';
+            mei += `${mIndent}<ending xml:id="${generateId('ending')}" n="${openNum}"${lendsym}>\n`;
+            endingOpen = true;
+        }
+        const measureIndent = endingOpen ? `${mIndent}${indent}` : mIndent;
+        mei += encodeMeasure(measure, mIndex, measureIndent, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements, measureIds);
+        // Close the <ending> after the measure that ends this alternate.
+        if (endingOpen && endingCloseAt.has(mIndex)) {
+            mei += `${mIndent}</ending>\n`;
+            endingOpen = false;
+        }
     });
+    // Defensive: never leave an <ending> unclosed at the end of the section.
+    if (endingOpen) {
+        mei += `${indent}${indent}${indent}${indent}${indent}${indent}</ending>\n`;
+        endingOpen = false;
+    }
+    // Emit an <expansion> describing playback order from the measure-layout
+    // directive ([measures "..."]). Verovio's expand="…" consumes its plist to
+    // unfold repeats for MIDI/time-map output. Inserted as the first child of
+    // <section>; ids were collected in the measure loop above.
+    if (doc.metadata?.measureLayout) {
+        try {
+            const layout = parseMeasureLayout(doc.metadata.measureLayout);
+            const order = expandMeasureLayout(layout);
+            const refs = [];
+            for (const idx of order) {
+                const id = measureIds[idx - 1]; // 1-based index into notated measures
+                if (id === undefined) {
+                    console.warn(`[measures] index ${idx} out of range (only ${measureIds.length} measures); skipping`);
+                    continue;
+                }
+                refs.push(`#${id}`);
+            }
+            if (refs.length > 0) {
+                const expIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+                const expXml = `${expIndent}<expansion xml:id="${generateId("expansion")}" plist="${refs.join(" ")}" />\n`;
+                mei = mei.slice(0, expansionInsertPos) + expXml + mei.slice(expansionInsertPos);
+            }
+        }
+        catch (err) {
+            console.warn(`[measures] failed to parse "${doc.metadata.measureLayout}": ${err.message}`);
+        }
+    }
     mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;
     mei += `${indent}${indent}${indent}${indent}</score>\n`;
     mei += `${indent}${indent}${indent}</mdiv>\n`;

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';