@k-l-lambda/lilylet 0.1.74 → 0.1.75

package/source/lilylet/meiEncoder.ts

@@ -29,6 +29,7 @@ import {
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
+import { parseMeasureLayout, expandMeasureLayout, collectVoltaSpans } from "./measureLayout";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -748,6 +749,7 @@ const restEventToMEI = (event: RestEvent, indent: string, keyFifths: number = 0,
 interface TupletEventResult {
 	xml: string;
 	firstNoteId: string | null;  // ID of first note in tuplet (for attaching pending markups)
+	lastNoteId: string | null;   // ID of last note/rest in tuplet (for closing/extending ottava spans)
 	slurStarts: string[];  // Note IDs that start slurs
 	slurEnds: string[];    // Note IDs that end slurs
 	dynamics: DynamRef[];
@@ -794,6 +796,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 
 	// Collect control event info from notes inside tuplet
 	let firstNoteId: string | null = null;
+	let lastNoteId: string | null = null;  // last note/rest id — anchors an ottava span end
 	const slurStarts: string[] = [];
 	const slurEnds: string[] = [];
 	const dynamics: DynamRef[] = [];
@@ -833,6 +836,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			xml += result.xml;
 
 			if (!firstNoteId) firstNoteId = result.elementId;
+			lastNoteId = result.elementId;
 
 			// Collect slur info
 			if (result.slurStart) slurStarts.push(result.elementId);
@@ -863,6 +867,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
 			const restResult = restEventToMEI(e as RestEvent, restIndent, keyFifths, ottavaShift, measureAccidentals);
 			xml += restResult.xml;
+			lastNoteId = restResult.elementId;
 			if (restResult.fermata) fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
 		} else if (e.type === 'context') {
 			const ctx = e as ContextChange;
@@ -885,7 +890,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 	}
 
 	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 };
 };
 
 
@@ -1143,6 +1148,39 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	let lastNoteId: string | null = null;  // Track last note id for ending ottava spans
 	let ottavaExplicitlyClosed: boolean = 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 = (): void => {
+		if (pendingOttava !== null && pendingOttava !== 0) currentOttavaShift = pendingOttava;
+	};
+	// Extend a carried (endToken) span's end to this event's last emitted id.
+	const extendOttavaEnd = (lastId: string): void => {
+		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: string): void => {
+		if (pendingOttava !== null && pendingOttava !== 0) {
+			const dis: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
+			const disPlace: 'above' | 'below' = 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
@@ -1248,9 +1286,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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
@@ -1260,9 +1296,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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);
@@ -1271,32 +1305,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				flushPendingDynamics(result.elementId);
 
 				// If there's a pending ottava, start the span on this note
-				if (pendingOttava !== null && pendingOttava !== 0) {
-					const dis: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
-					const disPlace: 'above' | 'below' = 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) {
@@ -1394,23 +1403,38 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 			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 as RestEvent, 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 as TupletEvent, 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 as Clef;
@@ -1420,7 +1444,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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.
@@ -1482,9 +1506,22 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 							}
 							currentOctave = null;
 							ottavaExplicitlyClosed = true;  // Mark that we explicitly closed the span
+						} 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 (e.g., at measure start), keep currentOctave alive
-						// It may be continued by a subsequent ottava command with the same value
+						// 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 {
 						// Check if this continues an existing span (same value)
@@ -1866,8 +1903,9 @@ const BARLINE_TO_MEI: Record<string, string> = {
 
 // Encode a measure
 // encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
-const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, ottavaState: OttavaState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}, octaveEndReplacements: Record<string, string> = {}): string => {
+const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, ottavaState: OttavaState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}, octaveEndReplacements: Record<string, string> = {}, measureIds?: string[]): string => {
 	const measureId = generateId("measure");
+	if (measureIds) measureIds.push(measureId);
 	let staffContent = '';  // Build staff content first, then add measure tag with barline
 	const allHairpins: HairpinSpan[] = [];
 	const allPedals: PedalMark[] = [];
@@ -2700,6 +2738,33 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 	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: string[] = [];
+
+	// 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<number, number>();   // measure index → ending number
+	const endingCloseAt = new Set<number>();           // 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: TieState = {};
@@ -2810,8 +2875,53 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 				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: string[] = [];
+			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 as Error).message}`);
+		}
+	}
 
 	mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;
 	mei += `${indent}${indent}${indent}${indent}</score>\n`;

package/source/lilylet/musicXmlDecoder.ts

@@ -69,6 +69,7 @@ import {
 	createFraction,
 	TYPE_TO_DIVISION,
 } from './musicXmlUtils';
+import { measureLayoutFromPart } from './measureLayoutFromXml';
 
 // ============ Spanner Tracker ============
 
@@ -630,6 +631,25 @@ const parseDirection = (dirEl: Element): MusicXmlDirection => {
 	result.placement = getAttribute(dirEl, 'placement') as 'above' | 'below' | undefined;
 	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: NonNullable<MusicXmlDirection['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;
@@ -722,7 +742,8 @@ const parseBarline = (barlineEl: Element): MusicXmlBarline => {
 	if (repeatEl) {
 		const direction = getAttribute(repeatEl, 'direction') as 'forward' | 'backward';
 		if (direction) {
-			result.repeat = { direction };
+			const times = getAttributeNumber(repeatEl, 'times');
+			result.repeat = times !== undefined ? { direction, times } : { direction };
 		}
 	}
 
@@ -1065,7 +1086,10 @@ const directionToMarks = (
 	// 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)) {
@@ -1073,6 +1097,27 @@ const directionToMarks = (
 				: 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 });
 		}
 	}
 
@@ -1087,6 +1132,12 @@ interface MeasureConversionResult {
 	key?: KeySignature;
 	timeSig?: Fraction;
 	barline?: BarlineEvent;
+	// A `location="left"` repeat (e.g. forward-repeat `.|:`) belongs at the FRONT
+	// of this measure, but lilylet models a `\bar` as the END bar of its measure.
+	// So it is carried back onto the PREVIOUS measure's trailing barline by
+	// convertPart (dropped if this is the first measure — a leading `|:` at the
+	// very start of the piece is conventionally omitted).
+	leadingBarline?: BarlineEvent;
 	harmonies: HarmonyEvent[];
 	clefs: Map<number, ContextChange>;  // staff number → clef context
 }
@@ -1149,6 +1200,7 @@ const convertMeasure = (
 	let key: KeySignature | undefined;
 	let timeSig: Fraction | undefined;
 	let barline: BarlineEvent | undefined;
+	let leadingBarline: BarlineEvent | undefined;
 	const harmonies: HarmonyEvent[] = [];
 	const clefs: Map<number, ContextChange> = new Map();
 
@@ -1166,6 +1218,15 @@ const convertMeasure = (
 	// layer (otherwise the encoder can't pair them and drops the span).
 	const pendingContextChanges: { ctx: ContextChange; staff?: number }[] = [];
 	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: Map<number, number> = new Map();
+	const staffHasNotes: Set<number> = new Set();
 
 	// Process all children in order
 	for (const child of getChildElements(measureEl)) {
@@ -1197,7 +1258,30 @@ const convertMeasure = (
 				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 } as ContextChange, 0, staff);
+							} else {
+								clefs.set(staff, { type: 'context', clef });
+							}
+						} else {
+							clefs.set(staff, { type: 'context', clef });
+						}
 					}
 				}
 			}
@@ -1206,6 +1290,10 @@ const convertMeasure = (
 			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)
@@ -1412,7 +1500,14 @@ const convertMeasure = (
 			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') {
 			const harmonyData = parseHarmony(child);
@@ -1506,7 +1601,7 @@ const convertMeasure = (
 		});
 	}
 
-	return { voiceMap, key, timeSig, barline, harmonies, clefs };
+	return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
 };
 
 /**
@@ -1524,12 +1619,30 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 	let isFirstMeasure = true;
 	let lastVoiceStaff = 1;  // Track last known primary voice staff for empty measure fallback
 	const lastClefs: Map<number, ContextChange> = 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: Map<number, ContextChange> = 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;
@@ -1566,6 +1679,22 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 							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 as ContextChange).clef === (pending as ContextChange).clef;
+					if (!isSameClef) {
+						events.push(pending);
+						lastClefs.set(voiceData.staff, pending);
+					}
+					pendingInitialClefs.delete(voiceData.staff);
 				}
 				staffsWithClef.add(voiceData.staff);
 			}
@@ -1573,6 +1702,22 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			// 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 as ContextChange;
+						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) {
@@ -1596,6 +1741,16 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			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: Measure = {
 			parts: [{
 				voices,
@@ -1730,6 +1885,14 @@ export const decode = (input: string | Uint8Array): LilyletDoc => {
 		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/source/lilylet/musicXmlTypes.ts

@@ -124,6 +124,17 @@ export interface MusicXmlDirection {
 	octaveShift?: MusicXmlOctaveShift;
 	coda?: boolean;
 	segno?: boolean;
+	// Navigation jumps from the <sound> sibling inside <direction>. Present when
+	// the score carries D.C./D.S./Coda/Fine playback semantics; drives the
+	// performance-order (measure-layout) derivation, not a notational glyph.
+	sound?: {
+		dacapo?: boolean;          // <sound dacapo="yes"> — da capo
+		dalsegno?: string;         // <sound dalsegno="N"> — dal segno (target segno id)
+		segno?: string;            // <sound segno="N"> — marks a segno point
+		coda?: string;             // <sound coda="N"> — marks a coda point
+		tocoda?: string;           // <sound tocoda="N"> — "to coda" jump
+		fine?: boolean;            // <sound fine="yes"> — Fine (stop point on D.C./D.S.)
+	};
 }
 
 // ============ Barline Types ============
@@ -133,6 +144,7 @@ export interface MusicXmlBarline {
 	barStyle?: string;          // regular, light-light, light-heavy, heavy-light, heavy-heavy, etc.
 	repeat?: {
 		direction: 'forward' | 'backward';
+		times?: number;          // <repeat times="N"> — repeat count (default 2 for backward)
 	};
 	ending?: {
 		type: 'start' | 'stop' | 'discontinue';