@k-l-lambda/lilylet 0.1.73 → 0.1.75

package/lib/lilylet/musicXmlDecoder.js

@@ -5,8 +5,9 @@
  * Improves upon musicxml2ly by properly tracking spanners (slurs, ties, wedges) by number attribute.
  */
 import { DOMParser } from '@xmldom/xmldom';
-import { HairpinType, NavigationMarkType, } from "./types.js";
+import { HairpinType, NavigationMarkType, Placement, } from "./types.js";
 import { getElementText, getElementInt, getElements, getDirectChildren, getChildElements, getAttribute, getAttributeNumber, hasElement, convertPitch, convertDuration, convertKeySignature, convertClef, convertStemDirection, convertArticulation, convertOrnament, convertDynamic, convertPedal, convertBarlineStyle, convertHarmonyToText, createFraction, TYPE_TO_DIVISION, } from "./musicXmlUtils.js";
+import { measureLayoutFromPart } from "./measureLayoutFromXml.js";
 // ============ Spanner Tracker ============
 /**
  * Track spanners (slurs, ties, wedges) by number attribute.
@@ -66,33 +67,47 @@ 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).
     activeTuplets = new Map();
     /**
-     * Start a new tuplet group
+     * Start a new tuplet group, bound to the voice/staff it starts in.
      */
-    startTuplet(number = 1) {
-        this.activeTuplets.set(number, { events: [] });
+    startTuplet(number = 1, voice = 1, staff = 1) {
+        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) {
+    addEvent(event, voice) {
         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;
         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;
     }
     /**
@@ -114,10 +129,40 @@ 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) {
+        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() {
-        return this.activeTuplets.size > 0;
+    flushAll() {
+        const out = [];
+        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;
     }
     /**
      * Reset tracker
@@ -290,6 +335,7 @@ const parseNote = (noteEl, divisions) => {
     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;
     const pitchEl = noteEl.getElementsByTagName('pitch')[0];
     if (pitchEl) {
@@ -299,6 +345,15 @@ const parseNote = (noteEl, divisions) => {
     const durationVal = getElementInt(noteEl, 'duration') || 0;
     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;
     const timeModEl = noteEl.getElementsByTagName('time-modification')[0];
@@ -322,14 +377,16 @@ const parseNote = (noteEl, divisions) => {
     if (notationsEl) {
         notations = parseNotations(notationsEl);
     }
-    // Fingering
-    let fingering;
+    // Fingering — a note may carry several <fingering> (one per chord member).
+    let fingerings;
     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
     // We only care about primary beam (number="1") for begin/end
@@ -345,6 +402,7 @@ const parseNote = (noteEl, divisions) => {
         isChord,
         isRest,
         isGrace,
+        isMeasureRest,
         pitch,
         duration: {
             divisions: durationVal,
@@ -356,7 +414,7 @@ const parseNote = (noteEl, divisions) => {
         staff,
         stem: stem,
         notations,
-        fingering,
+        fingerings,
         beams,
     };
 };
@@ -419,6 +477,31 @@ const parseDirection = (dirEl) => {
     const result = {};
     result.placement = getAttribute(dirEl, 'placement');
     result.staff = getElementInt(dirEl, 'staff');
+    // Navigation jumps live on the <sound> child of <direction> (a sibling of
+    // <direction-type>). Parse it first, before the no-direction-type early return,
+    // so a sound-only direction still contributes its jump semantics.
+    const soundEl = dirEl.getElementsByTagName('sound')[0];
+    if (soundEl) {
+        const sound = {};
+        if (getAttribute(soundEl, 'dacapo') === 'yes')
+            sound.dacapo = true;
+        if (getAttribute(soundEl, 'fine') === 'yes')
+            sound.fine = true;
+        const dalsegno = getAttribute(soundEl, 'dalsegno');
+        if (dalsegno)
+            sound.dalsegno = dalsegno;
+        const segno = getAttribute(soundEl, 'segno');
+        if (segno)
+            sound.segno = segno;
+        const coda = getAttribute(soundEl, 'coda');
+        if (coda)
+            sound.coda = coda;
+        const tocoda = getAttribute(soundEl, 'tocoda');
+        if (tocoda)
+            sound.tocoda = tocoda;
+        if (Object.keys(sound).length > 0)
+            result.sound = sound;
+    }
     const dirTypeEl = dirEl.getElementsByTagName('direction-type')[0];
     if (!dirTypeEl) {
         return result;
@@ -500,7 +583,8 @@ const parseBarline = (barlineEl) => {
     if (repeatEl) {
         const direction = getAttribute(repeatEl, 'direction');
         if (direction) {
-            result.repeat = { direction };
+            const times = getAttributeNumber(repeatEl, 'times');
+            result.repeat = times !== undefined ? { direction, times } : { direction };
         }
     }
     const endingEl = barlineEl.getElementsByTagName('ending')[0];
@@ -613,13 +697,14 @@ const notationsToMarks = (notations, spannerTracker, pitches) => {
     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 });
             }
         }
     }
@@ -802,8 +887,90 @@ const directionToMarks = (direction, spannerTracker) => {
     if (direction.segno) {
         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;
 };
+/**
+ * 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, divisions) => {
+    const rests = [];
+    let remaining = gapTicks;
+    const quarterTicks = divisions; // ticks per quarter note
+    // Largest representable spacer first; division 1=whole..128. dotted adds half.
+    const candidates = [];
+    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, divisions) => {
+    let total = 0;
+    for (const evt of tupletEvent.events) {
+        const d = evt.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
  */
@@ -811,13 +978,32 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
     let key;
     let timeSig;
     let barline;
+    let leadingBarline;
     const harmonies = [];
     const clefs = new Map();
     // Pending marks from directions (to attach to next note), per voice
     const pendingMarks = new Map();
-    // Pending context changes (tempo, ottava) to insert before next note
+    // 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 = [];
     let currentVoice = 1; // Track current voice for directions
+    // Mid-measure clef support: a staff can change clef partway through a measure
+    // (common in scale/arpeggio études where the LH crosses up). Such a clef arrives
+    // in an <attributes> block AFTER notes on that staff. We must attach it inline at
+    // that point on the staff's currently-active voice, not collapse it into the
+    // measure-start `clefs` map (which keeps only one clef per staff and emits it at
+    // the bar start). Track the last voice that added a note on each staff, and which
+    // staves already have notes this measure.
+    const lastVoiceOnStaff = new Map();
+    const staffHasNotes = new Set();
     // Process all children in order
     for (const child of getChildElements(measureEl)) {
         const tagName = child.tagName;
@@ -842,7 +1028,32 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
                 for (const clefEntry of attrs.clefs) {
                     const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
                     if (clef) {
-                        clefs.set(clefEntry.staff, { type: 'context', clef });
+                        const staff = clefEntry.staff;
+                        if (staffHasNotes.has(staff)) {
+                            // Mid-measure clef change: this staff already has notes in this
+                            // measure, so the clef takes effect HERE, not at the bar start.
+                            // Append it inline on the staff's currently-active voice via
+                            // addEvent (which inserts a staff-switch context if that voice is
+                            // currently positioned on another staff — e.g. a cross-staff
+                            // voice — so the clef binds to `staff`, not the voice's current
+                            // staff). Zero duration: a clef does not advance time.
+                            const vNum = lastVoiceOnStaff.get(staff);
+                            if (vNum !== undefined) {
+                                // Tag the clef context with its staff explicitly. In a
+                                // cross-staff voice (where notes interleave staves) a bare
+                                // clef is ambiguous and is dropped/misplaced by the serializer;
+                                // the explicit staff makes it self-describing (serializer emits
+                                // `\staff "N" \clef ...`). addEvent still inserts a leading
+                                // staff switch when the voice is currently on another staff.
+                                voiceTracker.addEvent(vNum, { type: 'context', staff, clef }, 0, staff);
+                            }
+                            else {
+                                clefs.set(staff, { type: 'context', clef });
+                            }
+                        }
+                        else {
+                            clefs.set(staff, { type: 'context', clef });
+                        }
                     }
                 }
             }
@@ -852,24 +1063,52 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             const voiceNum = note.voice;
             const staffNum = note.staff || 1;
             currentVoice = voiceNum;
+            // Record that this staff now has notes this measure and which voice is
+            // active on it, so a subsequent mid-measure <clef> attaches inline here.
+            staffHasNotes.add(staffNum);
+            lastVoiceOnStaff.set(staffNum, voiceNum);
             // Ensure voice exists with correct staff tracking (needed for cross-staff tuplets
             // where notes go to tupletTracker but voice must be initialized for staff detection)
             voiceTracker.getOrCreateVoice(voiceNum, staffNum);
+            // 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 = [];
+                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 = 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 = note.isRest ? [] : (pendingMarks.get(voiceNum) || []);
+            if (!note.isRest)
+                pendingMarks.delete(voiceNum);
             if (note.isRest) {
                 // Rest event
                 const duration = convertDuration(voiceTracker.getDivisions(), note.duration.divisions, note.duration.type, note.duration.dots, note.duration.timeModification);
@@ -877,11 +1116,23 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
                     type: 'rest',
                     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' }];
+                }
                 // 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);
@@ -893,9 +1144,12 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
                 // Get marks from notations
                 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
                 if (note.isChord) {
@@ -943,8 +1197,8 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
                 // 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(noteEvent);
+                if (tupletTracker.isActive(voiceNum)) {
+                    tupletTracker.addEvent(noteEvent, voiceNum);
                 }
                 else {
                     voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
@@ -954,16 +1208,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             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.duration) {
-                            // Convert division to duration units (quarter = 1)
-                            totalDuration += (4 / evt.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);
                 }
             }
@@ -973,7 +1218,9 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             // 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.)
             const marks = directionToMarks(direction, spannerTracker);
@@ -984,18 +1231,32 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             }
         }
         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') {
@@ -1006,6 +1267,80 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             }
         }
     }
+    // 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) => {
+            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;
+            }
+            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;
+            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();
     for (const [voiceNum, voiceState] of voiceTracker.getVoices()) {
@@ -1014,7 +1349,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             staff: voiceState.staff,
         });
     }
-    return { voiceMap, key, timeSig, barline, harmonies, clefs };
+    return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
 };
 /**
  * Convert a MusicXML part to Lilylet measures
@@ -1030,10 +1365,27 @@ const convertPart = (partEl) => {
     let isFirstMeasure = true;
     let lastVoiceStaff = 1; // Track last known primary voice staff for empty measure fallback
     const lastClefs = new Map(); // Track last clef per staff
+    // Initial clef per staff declared in the FIRST <attributes> block. A staff whose
+    // first voice does not appear until a later measure (e.g. an accompaniment staff
+    // silent for the opening bars) would otherwise lose its initial clef — it is only
+    // declared in measure 1's attributes, where that staff has no voice to attach it
+    // to. We hold these and flush each onto the staff's FIRST appearing voice.
+    const pendingInitialClefs = new Map();
     const measureEls = getDirectChildren(partEl, 'measure');
     for (const measureEl of measureEls) {
         voiceTracker.reset();
-        const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+        const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+        // A forward-repeat (or any `location="left"`) barline belongs at the END of
+        // the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.
+        // Append it to the previous measure's first voice; if this is the first
+        // measure there is no previous one, so a leading repeat at the very start of
+        // the piece is conventionally dropped.
+        if (leadingBarline && measures.length > 0) {
+            const prevVoices = measures[measures.length - 1].parts[0]?.voices;
+            if (prevVoices && prevVoices.length > 0) {
+                prevVoices[0].events.push(leadingBarline);
+            }
+        }
         // Update running key/time
         if (key)
             lastKey = key;
@@ -1068,11 +1420,45 @@ const convertPart = (partEl) => {
                             lastClefs.set(voiceData.staff, clef);
                         }
                     }
+                    pendingInitialClefs.delete(voiceData.staff);
+                }
+                else if (pendingInitialClefs.has(voiceData.staff)) {
+                    // This staff's clef was declared in an earlier measure where the staff
+                    // had no voice to carry it (its first appearance is delayed, or it is
+                    // an intermittently-empty cross-staff passage). This measure declares
+                    // no clef of its own — emit the carried-forward pending clef if it
+                    // differs from the clef last in effect for this staff.
+                    const pending = pendingInitialClefs.get(voiceData.staff);
+                    const lastClef = lastClefs.get(voiceData.staff);
+                    const isSameClef = lastClef &&
+                        lastClef.clef === pending.clef;
+                    if (!isSameClef) {
+                        events.push(pending);
+                        lastClefs.set(voiceData.staff, pending);
+                    }
+                    pendingInitialClefs.delete(voiceData.staff);
                 }
                 staffsWithClef.add(voiceData.staff);
             }
             // Add voice events
             events.push(...voiceData.events);
+            // A mid-measure clef change was appended inline to this voice's events (it
+            // does not pass through the measure-start `clefs` map). Scan for the LAST
+            // clef per staff in this voice and update lastClefs, so the next measure's
+            // dedup compares against the clef actually in effect — otherwise a later
+            // measure restating the pre-change clef would be wrongly suppressed.
+            {
+                let scanStaff = voiceData.staff;
+                for (const ev of voiceData.events) {
+                    if (ev.type === 'context') {
+                        const c = ev;
+                        if (c.staff != null)
+                            scanStaff = c.staff;
+                        if (c.clef)
+                            lastClefs.set(scanStaff, { type: 'context', clef: c.clef });
+                    }
+                }
+            }
             // Add harmonies and barline to first voice only
             if (voiceNum === voiceNumbers[0]) {
                 for (const h of harmonies) {
@@ -1094,6 +1480,16 @@ const convertPart = (partEl) => {
         else {
             lastVoiceStaff = voices[0].staff || 1;
         }
+        // Carry forward any clef declared this measure for a staff that had NO voice to
+        // attach it to (an intermittently-empty staff — e.g. cross-staff passages where
+        // the LH is written entirely on the upper staff for several bars). Remember it
+        // as pending so it is emitted when that staff next reappears; otherwise the clef
+        // (and any change it represents) is lost when this measure's `clefs` map is
+        // discarded. Generalizes the first-measure seeding above to every measure.
+        for (const [staff, clef] of clefs) {
+            if (!staffsWithClef.has(staff))
+                pendingInitialClefs.set(staff, clef);
+        }
         const measure = {
             parts: [{
                     voices,
@@ -1113,7 +1509,34 @@ const convertPart = (partEl) => {
 /**
  * Decode MusicXML string to LilyletDoc
  */
-export const decode = (xmlString) => {
+/**
+ * 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) => {
+    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) => {
+    const xmlString = readXmlString(input);
     const parser = new DOMParser();
     const doc = parser.parseFromString(xmlString, 'application/xml');
     // Check for parsing errors
@@ -1185,6 +1608,14 @@ export const decode = (xmlString) => {
     const result = {
         measures: mergedMeasures,
     };
+    // Derive the performance order (repeats / voltas / D.C. / D.S. / Coda / Fine)
+    // from the first part's barline + <sound> navigation markup → measure-layout
+    // string. The MEI encoder turns this into an <expansion> that verovio unfolds
+    // for MIDI. Repeat markup is part-global; the first part carries it. Never
+    // throws (returns undefined when there is nothing to unfold).
+    const measureLayout = measureLayoutFromPart(partEls[0]);
+    if (measureLayout)
+        metadata.measureLayout = measureLayout;
     if (Object.keys(metadata).length > 0) {
         result.metadata = metadata;
     }
@@ -1195,8 +1626,8 @@ export const decode = (xmlString) => {
  */
 export const decodeFile = async (filePath) => {
     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 {
     decode,