@k-l-lambda/lilylet 0.1.73 → 0.1.74

package/lib/lilylet/musicXmlDecoder.js

@@ -5,7 +5,7 @@
  * 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";
 // ============ Spanner Tracker ============
 /**
@@ -66,33 +66,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 +128,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 +334,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 +344,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 +376,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 +401,7 @@ const parseNote = (noteEl, divisions) => {
         isChord,
         isRest,
         isGrace,
+        isMeasureRest,
         pitch,
         duration: {
             divisions: durationVal,
@@ -356,7 +413,7 @@ const parseNote = (noteEl, divisions) => {
         staff,
         stem: stem,
         notations,
-        fingering,
+        fingerings,
         beams,
     };
 };
@@ -613,13 +670,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 +860,67 @@ 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.
+    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;
 };
+/**
+ * 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
  */
@@ -815,7 +932,16 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
     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
     // Process all children in order
@@ -855,21 +981,45 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             // 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 +1027,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 +1055,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 +1108,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 +1119,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 +1129,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,12 +1142,18 @@ 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);
@@ -1006,6 +1170,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()) {
@@ -1113,7 +1351,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
@@ -1195,8 +1460,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,

package/lib/lilylet/musicXmlTypes.d.ts

@@ -71,13 +71,14 @@ export interface MusicXmlNote {
     isChord: boolean;
     isRest: boolean;
     isGrace: boolean;
+    isMeasureRest?: boolean;
     pitch?: MusicXmlPitch;
     duration: MusicXmlDuration;
     voice: number;
     staff?: number;
     stem?: MusicXmlStemDirection;
     notations?: MusicXmlNotations;
-    fingering?: number;
+    fingerings?: number[];
     beams?: {
         type: 'begin' | 'continue' | 'end';
         number: number;

package/lib/lilylet/types.d.ts

@@ -126,6 +126,7 @@ export interface Tie {
 export interface Slur {
     markType: 'slur';
     start: boolean;
+    number?: number;
 }
 export interface Beam {
     markType: 'beam';
@@ -176,6 +177,7 @@ export interface RestEvent {
     invisible?: boolean;
     fullMeasure?: boolean;
     pitch?: Pitch;
+    marks?: Mark[];
 }
 export interface ContextChange {
     type: 'context';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.73",
+  "version": "0.1.74",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -34,6 +34,7 @@
     "prepublishOnly": "npm run build:grammar && npm run build",
     "test": "tsx ./tests/parser.ts",
     "test:mei": "tsx ./tests/mei.ts",
+    "test:mei-diff": "tsx ./tests/musicxml-mei-diff.ts",
     "test:mei-hashes": "tsx ./tests/computeMeiHashes.ts",
     "test:partial": "tsx ./tests/unit/partialWarning.test.ts",
     "test:decoder": "tsx ./tests/lilypondDecoder.ts",