@k-l-lambda/lilylet 0.1.73 → 0.1.75

package/source/lilylet/musicXmlDecoder.ts

@@ -25,6 +25,7 @@ import {
 	HairpinType,
 	PedalType,
 	NavigationMarkType,
+	Placement,
 	BarlineEvent,
 	HarmonyEvent,
 	TupletEvent,
@@ -68,6 +69,7 @@ import {
 	createFraction,
 	TYPE_TO_DIVISION,
 } from './musicXmlUtils';
+import { measureLayoutFromPart } from './measureLayoutFromXml';
 
 // ============ Spanner Tracker ============
 
@@ -141,38 +143,53 @@ class SpannerTracker {
  * Collects notes between tuplet start and stop to create TupletEvent.
  */
 class TupletTracker {
-	// Map from tuplet number to collected events and ratio
+	// Map from tuplet number to collected events and ratio. Each tuplet is bound to
+	// the voice (and staff) it started in: a tuplet belongs to one voice, so events
+	// from OTHER voices must not be swallowed into it (multi-voice piano scores
+	// interleave voices, and a voice-1 tuplet would otherwise eat voice-2 notes).
 	private activeTuplets: Map<number, {
 		events: (NoteEvent | RestEvent)[];
 		ratio?: Fraction;
+		voice: number;
+		staff: number;
 	}> = new Map();
 
 	/**
-	 * Start a new tuplet group
+	 * Start a new tuplet group, bound to the voice/staff it starts in.
 	 */
-	startTuplet(number: number = 1): void {
-		this.activeTuplets.set(number, { events: [] });
+	startTuplet(number: number = 1, voice: number = 1, staff: number = 1): void {
+		this.activeTuplets.set(number, { events: [], voice, staff });
 	}
 
 	/**
-	 * Add an event to active tuplet(s)
-	 * Returns true if the event was added to at least one tuplet
+	 * Add an event to the innermost active tuplet of the SAME voice.
+	 * Returns true if the event was added.
+	 *
+	 * Nested tuplets share the doc model's flat TupletEvent (which can't hold a
+	 * nested TupletEvent), so an event must go to exactly ONE tuplet or it would be
+	 * emitted twice — once per enclosing tuplet — inflating the pitch count. We pick
+	 * the most-recently-started same-voice tuplet (the innermost): when the inner one
+	 * closes, later events fall back to the still-open outer one.
 	 */
-	addEvent(event: NoteEvent | RestEvent): boolean {
+	addEvent(event: NoteEvent | RestEvent, voice: number): boolean {
 		if (this.activeTuplets.size === 0) return false;
 
-		// Add to all active tuplets (in case of nested tuplets)
+		// Innermost = last-inserted entry for this voice (Map preserves insertion order).
+		let target: { events: (NoteEvent | RestEvent)[]; ratio?: Fraction; voice: number; staff: number } | undefined;
 		for (const [, tuplet] of this.activeTuplets) {
-			// Set ratio from first event's duration.tuplet
-			// convertDuration already stores Lilylet ratio semantics (normalNotes/actualNotes)
-			if (!tuplet.ratio && event.duration.tuplet) {
-				tuplet.ratio = { ...event.duration.tuplet };
-			}
-			// Store event without tuplet info in duration (it's handled at TupletEvent level)
-			const cleanEvent = { ...event, duration: { ...event.duration } };
-			delete cleanEvent.duration.tuplet;
-			tuplet.events.push(cleanEvent);
+			if (tuplet.voice === voice) target = tuplet;
+		}
+		if (!target) return false;
+
+		// Set ratio from first event's duration.tuplet
+		// convertDuration already stores Lilylet ratio semantics (normalNotes/actualNotes)
+		if (!target.ratio && event.duration.tuplet) {
+			target.ratio = { ...event.duration.tuplet };
 		}
+		// Store event without tuplet info in duration (it's handled at TupletEvent level)
+		const cleanEvent = { ...event, duration: { ...event.duration } };
+		delete cleanEvent.duration.tuplet;
+		target.events.push(cleanEvent);
 		return true;
 	}
 
@@ -199,10 +216,37 @@ class TupletTracker {
 	}
 
 	/**
-	 * Check if any tuplet is active
+	 * Check if a tuplet is active for the given voice. A tuplet only swallows notes
+	 * of its OWN voice, so the per-note "are we in a tuplet?" check must be scoped to
+	 * the note's voice — otherwise a voice-1 tuplet would divert voice-2 notes.
 	 */
-	isActive(): boolean {
-		return this.activeTuplets.size > 0;
+	isActive(voice?: number): boolean {
+		if (voice === undefined) return this.activeTuplets.size > 0;
+		for (const [, t] of this.activeTuplets) if (t.voice === voice) return true;
+		return false;
+	}
+
+	/**
+	 * Force-close every still-open tuplet and return them with their owning
+	 * voice/staff. Called at measure end: a tuplet is a within-measure time
+	 * modification and MUST NOT leak across the bar line. A source file missing a
+	 * <tuplet type="stop"> (corpus reality — e.g. 库劳 Op.20) would otherwise leave
+	 * the tuplet open forever, swallowing every following note in that voice for the
+	 * rest of the piece. Flushing here bounds the damage to the one measure.
+	 */
+	flushAll(): Array<{ event: TupletEvent; voice: number; staff: number }> {
+		const out: Array<{ event: TupletEvent; voice: number; staff: number }> = [];
+		for (const [, tuplet] of this.activeTuplets) {
+			if (tuplet.events.length === 0) continue;
+			const ratio = tuplet.ratio || { numerator: 2, denominator: 3 };
+			out.push({
+				event: { type: 'tuplet', ratio, events: tuplet.events },
+				voice: tuplet.voice,
+				staff: tuplet.staff,
+			});
+		}
+		this.activeTuplets.clear();
+		return out;
 	}
 
 	/**
@@ -423,6 +467,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 	const isChord = hasElement(noteEl, 'chord');
 	const isRest = hasElement(noteEl, 'rest');
 	const isGrace = hasElement(noteEl, 'grace');
+	const restEl = isRest ? noteEl.getElementsByTagName('rest')[0] : undefined;
 
 	let pitch: MusicXmlPitch | undefined;
 	const pitchEl = noteEl.getElementsByTagName('pitch')[0];
@@ -435,6 +480,18 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 	const typeText = getElementText(noteEl, 'type');
 	const dotCount = getElements(noteEl, 'dot').length;
 
+	// Whole-measure rest detection. Two forms in the wild:
+	//  (a) <rest measure="yes"> — explicit.
+	//  (b) a `type="whole"` rest whose <duration> is NOT a whole note (e.g. 72 ticks
+	//      in 3/4 at divisions=24) — the conventional "centred whole rest = whole
+	//      bar" notation. In both cases the rest fills the measure, so flag it and
+	//      let encoders emit <mRest>/R instead of rounding the bare duration to a
+	//      power-of-two division (which over/under-fills non-2^n meters).
+	const isMeasureRest = !!restEl && (
+		getAttribute(restEl, 'measure') === 'yes' ||
+		(typeText === 'whole' && durationVal > 0 && durationVal !== divisions * 4)
+	);
+
 	// Time modification (tuplets)
 	let timeModification: { actualNotes: number; normalNotes: number } | undefined;
 	const timeModEl = noteEl.getElementsByTagName('time-modification')[0];
@@ -463,14 +520,15 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		notations = parseNotations(notationsEl);
 	}
 
-	// Fingering
-	let fingering: number | undefined;
+	// Fingering — a note may carry several <fingering> (one per chord member).
+	let fingerings: number[] | undefined;
 	const technicalEl = noteEl.getElementsByTagName('technical')[0];
 	if (technicalEl) {
-		const fingeringText = getElementText(technicalEl, 'fingering');
-		if (fingeringText) {
-			fingering = parseInt(fingeringText, 10);
-		}
+		const fingeringEls = getElements(technicalEl, 'fingering');
+		const parsed = fingeringEls
+			.map(el => parseInt(el.textContent?.trim() || '', 10))
+			.filter(n => Number.isFinite(n));
+		if (parsed.length > 0) fingerings = parsed;
 	}
 
 	// Beams - direct children of note, not in notations
@@ -488,6 +546,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		isChord,
 		isRest,
 		isGrace,
+		isMeasureRest,
 		pitch,
 		duration: {
 			divisions: durationVal,
@@ -499,7 +558,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		staff,
 		stem: stem as any,
 		notations,
-		fingering,
+		fingerings,
 		beams,
 	};
 };
@@ -572,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;
@@ -664,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 };
 		}
 	}
 
@@ -797,12 +876,13 @@ const notationsToMarks = (
 	if (notations.slurs) {
 		for (const slur of notations.slurs) {
 			if (slur.type === 'start') {
-				marks.push({ markType: 'slur', start: true });
+				marks.push({ markType: 'slur', start: true, number: slur.number });
 				spannerTracker.startSlur(slur.number);
 			} else if (slur.type === 'stop') {
-				if (spannerTracker.stopSlur(slur.number)) {
-					marks.push({ markType: 'slur', start: false });
-				}
+				// Carry the MusicXML number so the encoder can pair cross-voice slurs
+				// (start in one voice, stop in another — common in piano scores).
+				spannerTracker.stopSlur(slur.number);
+				marks.push({ markType: 'slur', start: false, number: slur.number });
 			}
 		}
 	}
@@ -1002,6 +1082,45 @@ const directionToMarks = (
 		marks.push({ markType: 'navigation', type: NavigationMarkType.segno });
 	}
 
+	// Words (text directions: "dolce", "espr.", "cresc.", "con forza", ...).
+	// 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. 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)) {
+			const placement = direction.placement === 'above' ? Placement.above
+				: 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;
 };
 
@@ -1013,10 +1132,61 @@ 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
 }
 
+/**
+ * Decompose a tick gap (from <forward>) into invisible spacer rests.
+ *
+ * lilylet's doc model is a flat per-voice event sequence with no absolute tick
+ * anchor (currentPosition is unused for placement), so a <forward> that skips
+ * time inside a voice must be materialised as filler or the following notes slide
+ * earlier and the bar decodes short. Invisible rests (`s` / MEI <space>) are the
+ * right carrier. The gap may not be a single note value (e.g. 1.5 quarters), so
+ * emit a greedy sequence of power-of-two (optionally dotted) spacers.
+ */
+const forwardGapToRests = (gapTicks: number, divisions: number): RestEvent[] => {
+	const rests: RestEvent[] = [];
+	let remaining = gapTicks;
+	const quarterTicks = divisions; // ticks per quarter note
+	// Largest representable spacer first; division 1=whole..128. dotted adds half.
+	const candidates: { division: number; dots: number; q: number }[] = [];
+	for (const division of [1, 2, 4, 8, 16, 32, 64, 128]) {
+		const baseQ = 4 / division;           // quarter notes for this value
+		candidates.push({ division, dots: 0, q: baseQ });
+		candidates.push({ division, dots: 1, q: baseQ * 1.5 });
+	}
+	candidates.sort((a, b) => b.q - a.q);
+	let guard = 0;
+	while (remaining > 0.0001 && guard++ < 64) {
+		const c = candidates.find(c => c.q * quarterTicks <= remaining + 0.0001);
+		if (!c) break;
+		rests.push({ type: 'rest', duration: { division: c.division, dots: c.dots }, invisible: true });
+		remaining -= c.q * quarterTicks;
+	}
+	return rests;
+};
+
+/**
+ * Total time a TupletEvent advances the voice, in voiceTracker duration units.
+ * Sum the inner note/rest values then apply the tuplet ratio (triplet etc.).
+ */
+const tupletAdvanceDuration = (tupletEvent: TupletEvent, divisions: number): number => {
+	let total = 0;
+	for (const evt of tupletEvent.events) {
+		const d = (evt as NoteEvent | RestEvent).duration;
+		if (d) total += (4 / d.division) * divisions;
+	}
+	return total * tupletEvent.ratio.numerator / tupletEvent.ratio.denominator;
+};
+
 /**
  * Convert a MusicXML measure to Lilylet events, grouped by voice
  */
@@ -1030,14 +1200,33 @@ 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();
 
 	// Pending marks from directions (to attach to next note), per voice
 	const pendingMarks: Map<number, Mark[]> = new Map();
-	// Pending context changes (tempo, ottava) to insert before next note
-	const pendingContextChanges: ContextChange[] = [];
+	// Accumulated <forward> ticks waiting for the next note, whose <voice> tells us
+	// which voice the gap belongs to. Flushed as invisible rests before that note,
+	// or onto currentVoice at a <backup>/measure end (a trailing gap in this voice).
+	let pendingForward = 0;
+	// Pending context changes (tempo, ottava) to insert before next note. Each may
+	// carry a target staff: an ottava (<octave-shift>) start and its stop both name
+	// the same <staff>, but in piano scores the stop direction often follows a
+	// <backup> so the *next note* is on the other staff. Routing the change to a
+	// note on its own staff keeps the 8va span's start and end in the same MEI
+	// 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)) {
@@ -1069,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 });
+						}
 					}
 				}
 			}
@@ -1078,28 +1290,55 @@ 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)
 			voiceTracker.getOrCreateVoice(voiceNum, staffNum);
 
+			// Flush an accumulated <forward> gap as invisible rests into THIS note's
+			// voice (the forward had no voice of its own; it belongs to the voice that
+			// follows). Skip while inside a tuplet — a forward there is unusual and the
+			// tuplet tracker owns timing.
+			if (pendingForward > 0 && !tupletTracker.isActive(voiceNum)) {
+				for (const r of forwardGapToRests(pendingForward, voiceTracker.getDivisions())) {
+					voiceTracker.addEvent(voiceNum, r, 0, staffNum);
+				}
+			}
+			pendingForward = 0;
+
 			// Check for tuplet start BEFORE processing the note
 			const tupletNotation = note.notations?.tuplet;
 			if (tupletNotation?.type === 'start') {
-				tupletTracker.startTuplet(tupletNotation.number);
+				tupletTracker.startTuplet(tupletNotation.number, voiceNum, staffNum);
 			}
 
-			// Add any pending context changes before the note (tempo, ottava)
+			// Add any pending context changes before the note (tempo, ottava).
+			// A staff-tagged change (ottava) only flushes onto a note on the SAME
+			// staff so its 8va span stays in one layer; others (tempo) flush anywhere.
 			if (pendingContextChanges.length > 0) {
-				for (const ctx of pendingContextChanges) {
-					voiceTracker.addEvent(voiceNum, ctx, 0, staffNum);
+				const remaining: { ctx: ContextChange; staff?: number }[] = [];
+				for (const pc of pendingContextChanges) {
+					if (pc.staff === undefined || pc.staff === staffNum) {
+						voiceTracker.addEvent(voiceNum, pc.ctx, 0, staffNum);
+					} else {
+						remaining.push(pc);  // wait for a note on the matching staff
+					}
 				}
-				pendingContextChanges.length = 0;  // Clear
+				pendingContextChanges.length = 0;
+				pendingContextChanges.push(...remaining);
 			}
 
-			// Get pending marks for this voice
-			const marks: Mark[] = pendingMarks.get(voiceNum) || [];
-			pendingMarks.delete(voiceNum);
+			// Get pending marks for this voice. Rests can't hold marks (RestEvent has
+			// no `marks` field), so do NOT consume them on a rest — leave them queued
+			// for the next real note or the end-of-measure flush. Otherwise a pedal/
+			// hairpin stop that lands just before a rest (common in piano scores:
+			// `<pedal stop/>` followed by rests filling the voice) is silently dropped.
+			const marks: Mark[] = note.isRest ? [] : (pendingMarks.get(voiceNum) || []);
+			if (!note.isRest) pendingMarks.delete(voiceNum);
 
 			if (note.isRest) {
 				// Rest event
@@ -1116,12 +1355,26 @@ const convertMeasure = (
 					duration,
 				};
 
+				// Whole-measure rest: mark it so encoders emit <mRest>/R and downstream
+				// duration math uses the measure length, not the power-of-two rounding
+				// of the bare <duration> (which over/under-fills non-2^n meters like 3/4).
+				if (note.isMeasureRest) {
+					restEvent.fullMeasure = true;
+				}
+
+				// A rest can host a fermata (grand pause / held silence). Convert it
+				// so the encoder can emit <fermata startid="#rest">; without this the
+				// 3-of-4 fermatas that sit on rests in typical piano scores are lost.
+				if (note.notations?.fermata) {
+					restEvent.marks = [{ markType: 'ornament', type: 'fermata' as any }];
+				}
+
 				// Grace notes don't advance time
 				const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
 
 				// Check if we're in a tuplet
-				if (tupletTracker.isActive()) {
-					tupletTracker.addEvent(restEvent);
+				if (tupletTracker.isActive(voiceNum)) {
+					tupletTracker.addEvent(restEvent, voiceNum);
 				} else {
 					voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
 				}
@@ -1133,9 +1386,11 @@ const convertMeasure = (
 				const notationMarks = notationsToMarks(note.notations, spannerTracker, [lilyletPitch]);
 				marks.push(...notationMarks);
 
-				// Add fingering
-				if (note.fingering !== undefined && note.fingering >= 1 && note.fingering <= 5) {
-					marks.push({ markType: 'fingering', finger: note.fingering });
+				// Add fingerings (one per chord member; MEI emits a <fing> each)
+				if (note.fingerings) {
+					for (const finger of note.fingerings) {
+						if (finger >= 0 && finger <= 9) marks.push({ markType: 'fingering', finger });
+					}
 				}
 
 				// Handle chord: merge with previous note in same voice
@@ -1196,8 +1451,8 @@ const convertMeasure = (
 				const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
 
 				// Check if we're in a tuplet
-				if (tupletTracker.isActive()) {
-					tupletTracker.addEvent(noteEvent);
+				if (tupletTracker.isActive(voiceNum)) {
+					tupletTracker.addEvent(noteEvent, voiceNum);
 				} else {
 					voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
 				}
@@ -1207,16 +1462,7 @@ const convertMeasure = (
 			if (tupletNotation?.type === 'stop') {
 				const tupletEvent = tupletTracker.stopTuplet(tupletNotation.number);
 				if (tupletEvent) {
-					// Calculate total duration of tuplet for voiceTracker
-					let totalDuration = 0;
-					for (const evt of tupletEvent.events) {
-						if ((evt as NoteEvent | RestEvent).duration) {
-							// Convert division to duration units (quarter = 1)
-							totalDuration += (4 / (evt as NoteEvent | RestEvent).duration.division) * voiceTracker.getDivisions();
-						}
-					}
-					// Apply tuplet ratio to get actual duration
-					totalDuration = totalDuration * tupletEvent.ratio.numerator / tupletEvent.ratio.denominator;
+					const totalDuration = tupletAdvanceDuration(tupletEvent, voiceTracker.getDivisions());
 					voiceTracker.addEvent(voiceNum, tupletEvent, totalDuration, staffNum);
 				}
 			}
@@ -1226,7 +1472,9 @@ const convertMeasure = (
 			// Handle context changes (tempo, ottava)
 			const contextChange = directionToContextChange(direction, ottavaTracker);
 			if (contextChange) {
-				pendingContextChanges.push(contextChange);
+				// Tag ottava changes with their staff so they reach the right layer.
+				const staff = contextChange.ottava !== undefined ? direction.staff : undefined;
+				pendingContextChanges.push({ ctx: contextChange, staff });
 			}
 
 			// Handle marks (dynamics, hairpins, etc.)
@@ -1237,16 +1485,29 @@ const convertMeasure = (
 				pendingMarks.set(currentVoice, [...existing, ...marks]);
 			}
 		} else if (tagName === 'backup') {
+			// A <forward> with no note after it (before this backup) is cursor
+			// positioning, not a content gap — drop it rather than materialise filler
+			// (the common `backup N / forward N` measure-end idiom would otherwise
+			// double the bar). Only note→forward→note gaps become invisible rests.
+			pendingForward = 0;
 			const duration = getElementInt(child, 'duration') || 0;
 			voiceTracker.backup(duration);
 		} else if (tagName === 'forward') {
 			const duration = getElementInt(child, 'duration') || 0;
 			voiceTracker.forward(duration);
+			pendingForward += duration;  // materialised as invisible rests only if a note follows in-voice
 		} else if (tagName === 'barline') {
 			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);
@@ -1263,6 +1524,74 @@ const convertMeasure = (
 		}
 	}
 
+	// A <forward> at the very end of the measure with no following note is cursor
+	// positioning (e.g. the `backup N / forward N` idiom), not a content gap — drop
+	// it. Only forwards consumed by a following note become invisible spacer rests.
+	pendingForward = 0;
+
+	// Force-close any tuplet still open at the bar line. A tuplet is a within-measure
+	// time modification and cannot span a bar; a source file missing its
+	// <tuplet type="stop"> (corpus reality) would otherwise keep the tuplet open for
+	// the rest of the piece, diverting every following note in that voice into the
+	// zombie tuplet — the multi-voice block-drop bug (库劳 Op.20 m15→end empty).
+	// Flush each leftover tuplet onto its owning voice so the damage is bounded to
+	// this measure. Done before the pendingMarks flush so trailing marks still find
+	// the (now-emitted) tuplet's notes as the voice's last events.
+	for (const { event, voice, staff } of tupletTracker.flushAll()) {
+		const totalDuration = tupletAdvanceDuration(event, voiceTracker.getDivisions());
+		voiceTracker.addEvent(voice, event, totalDuration, staff);
+	}
+
+	// Flush leftover pending marks. Post-positioned directions — hairpin/pedal
+	// stops, and any direction after the last note of its voice (common after a
+	// <backup> in piano scores) — never reached a following note in the loop above.
+	// They belong on the note they trail, so attach them to the last NoteEvent of
+	// the voice. pendingMarks is per-measure, so without this they would be lost
+	// at the next measure (the pedal/hairpin "stop" loss). Rests carry no marks, so
+	// search backward for the last actual note; fall back across voices if needed.
+	if (pendingMarks.size > 0) {
+		const allVoices = voiceTracker.getVoices();
+		const findLastNote = (voiceNum: number): NoteEvent | undefined => {
+			const vs = allVoices.get(voiceNum);
+			if (!vs) return undefined;
+			for (let i = vs.events.length - 1; i >= 0; i--) {
+				const ev = vs.events[i];
+				if (ev.type === 'note') return ev as NoteEvent;
+			}
+			return undefined;
+		};
+		for (const [voiceNum, marks] of pendingMarks) {
+			if (marks.length === 0) continue;
+			let target = findLastNote(voiceNum);
+			// Voice had no note (e.g. direction-only or rest-only): attach to the
+			// last note of any voice so the marking is not silently dropped.
+			if (!target) {
+				for (const vn of allVoices.keys()) {
+					target = findLastNote(vn);
+					if (target) break;
+				}
+			}
+			if (target) target.marks = [...(target.marks || []), ...marks];
+		}
+		pendingMarks.clear();
+	}
+
+	// Flush leftover staff-tagged context changes (ottava) whose matching-staff note
+	// never appeared this measure: append to a voice on the target staff so the span
+	// continues into / closes in the right layer rather than being dropped.
+	if (pendingContextChanges.length > 0) {
+		const voices = voiceTracker.getVoices();
+		for (const pc of pendingContextChanges) {
+			let voiceNum: number | undefined;
+			for (const [vn, vs] of voices) {
+				if (vs.staff === pc.staff) { voiceNum = vn; break; }
+			}
+			if (voiceNum === undefined) voiceNum = voices.keys().next().value;
+			if (voiceNum !== undefined) voiceTracker.addEvent(voiceNum, pc.ctx, 0, pc.staff);
+		}
+		pendingContextChanges.length = 0;
+	}
+
 	// Build voice map from tracker
 	const voiceMap = new Map<number, { events: Event[]; staff: number }>();
 	for (const [voiceNum, voiceState] of voiceTracker.getVoices()) {
@@ -1272,7 +1601,7 @@ const convertMeasure = (
 		});
 	}
 
-	return { voiceMap, key, timeSig, barline, harmonies, clefs };
+	return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
 };
 
 /**
@@ -1290,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;
@@ -1332,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);
 			}
@@ -1339,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) {
@@ -1362,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,
@@ -1384,7 +1773,37 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 /**
  * Decode MusicXML string to LilyletDoc
  */
-export const decode = (xmlString: string): LilyletDoc => {
+/**
+ * Decode raw MusicXML bytes (or a string) into a clean UTF-8/UTF-16-correct
+ * JS string. MuseScore/Finale/Sibelius frequently export `.xml` as UTF-16 LE
+ * with a BOM; reading those as UTF-8 yields mojibake and a failed parse.
+ *
+ * Detection order: byte-order mark → declared `encoding="..."` in the XML
+ * prolog → default UTF-8. A leading BOM is always stripped (xmldom chokes on a
+ * U+FEFF before `<?xml`).
+ */
+export const readXmlString = (input: string | Uint8Array): string => {
+	if (typeof input === 'string')
+		return input.charCodeAt(0) === 0xFEFF ? input.slice(1) : input;
+
+	const bytes = input;
+	if (bytes.length >= 2 && bytes[0] === 0xFF && bytes[1] === 0xFE)
+		return new TextDecoder('utf-16le').decode(bytes.subarray(2));
+	if (bytes.length >= 2 && bytes[0] === 0xFE && bytes[1] === 0xFF)
+		return new TextDecoder('utf-16be').decode(bytes.subarray(2));
+	if (bytes.length >= 3 && bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF)
+		return new TextDecoder('utf-8').decode(bytes.subarray(3));
+
+	// No BOM: peek the prolog (as latin1 so every byte maps 1:1) for a declared encoding.
+	const head = new TextDecoder('latin1').decode(bytes.subarray(0, 256));
+	const enc = /encoding\s*=\s*['"]([^'"]+)['"]/i.exec(head)?.[1]?.toLowerCase();
+	if (enc && /utf-?16/.test(enc))
+		return new TextDecoder('utf-16le').decode(bytes); // BOM-less UTF-16 → assume LE (Windows)
+	return new TextDecoder('utf-8').decode(bytes);
+};
+
+export const decode = (input: string | Uint8Array): LilyletDoc => {
+	const xmlString = readXmlString(input);
 	const parser = new DOMParser();
 	const doc = parser.parseFromString(xmlString, 'application/xml');
 
@@ -1466,6 +1885,14 @@ export const decode = (xmlString: string): 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;
 	}
@@ -1478,8 +1905,8 @@ export const decode = (xmlString: string): LilyletDoc => {
  */
 export const decodeFile = async (filePath: string): Promise<LilyletDoc> => {
 	const fs = await import('fs/promises');
-	const content = await fs.readFile(filePath, 'utf-8');
-	return decode(content);
+	const buf = await fs.readFile(filePath); // raw bytes; readXmlString sniffs the encoding
+	return decode(buf);
 };
 
 export default {