@k-l-lambda/lilylet 0.1.73 → 0.1.74

package/source/lilylet/musicXmlDecoder.ts

@@ -25,6 +25,7 @@ import {
 	HairpinType,
 	PedalType,
 	NavigationMarkType,
+	Placement,
 	BarlineEvent,
 	HarmonyEvent,
 	TupletEvent,
@@ -141,38 +142,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 +215,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(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.
 	 */
-	isActive(): boolean {
-		return this.activeTuplets.size > 0;
+	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 +466,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 +479,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 +519,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 +545,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		isChord,
 		isRest,
 		isGrace,
+		isMeasureRest,
 		pitch,
 		duration: {
 			divisions: durationVal,
@@ -499,7 +557,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		staff,
 		stem: stem as any,
 		notations,
-		fingering,
+		fingerings,
 		beams,
 	};
 };
@@ -797,12 +855,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 +1061,21 @@ 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.
+	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 });
+		}
+	}
+
 	return marks;
 };
 
@@ -1017,6 +1091,51 @@ interface MeasureConversionResult {
 	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
  */
@@ -1035,8 +1154,17 @@ const convertMeasure = (
 
 	// 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
 
 	// Process all children in order
@@ -1083,23 +1211,46 @@ const convertMeasure = (
 			// 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 +1267,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 +1298,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 +1363,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 +1374,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 +1384,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,11 +1397,17 @@ 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);
@@ -1263,6 +1429,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()) {
@@ -1384,7 +1618,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');
 
@@ -1478,8 +1742,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 {

package/source/lilylet/musicXmlTypes.ts

@@ -69,13 +69,14 @@ export interface MusicXmlNote {
 	isChord: boolean;           // Has <chord/> tag
 	isRest: boolean;            // Has <rest/> tag
 	isGrace: boolean;           // Has <grace/> tag
+	isMeasureRest?: boolean;    // <rest measure="yes"> — fills the whole measure
 	pitch?: MusicXmlPitch;
 	duration: MusicXmlDuration;
 	voice: number;              // Voice number (1-based)
 	staff?: number;             // Staff number (for cross-staff)
 	stem?: MusicXmlStemDirection;
 	notations?: MusicXmlNotations;
-	fingering?: number;         // 1-5
+	fingerings?: number[];      // one per chord member; a single note has at most one
 	beams?: { type: 'begin' | 'continue' | 'end'; number: number }[];
 }
 

package/source/lilylet/types.ts

@@ -157,6 +157,7 @@ export interface Tie {
 export interface Slur {
 	markType: 'slur';
 	start: boolean;
+	number?: number;	// MusicXML slur number, for pairing cross-voice/overlapping slurs (encoder hint only)
 }
 
 export interface Beam {
@@ -223,6 +224,7 @@ export interface RestEvent {
 	invisible?: boolean;		// space rest (s)
 	fullMeasure?: boolean;	// full measure rest (R)
 	pitch?: Pitch;					// positioned rest (e.g., g'\rest)
+	marks?: Mark[];					// control-event marks a rest can host (e.g. fermata over a rest / grand pause)
 }
 
 export interface ContextChange {