@k-l-lambda/lilylet 0.1.71 → 0.1.73

package/lib/source/lilylet/musicXmlDecoder.js

@@ -1,1195 +0,0 @@
-/**
- * MusicXML to Lilylet Decoder
- *
- * Converts MusicXML files to Lilylet's internal LilyletDoc format.
- * 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 { 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 ============
-/**
- * Track spanners (slurs, ties, wedges) by number attribute.
- * This fixes the musicxml2ly bug where nested slurs aren't handled correctly.
- */
-class SpannerTracker {
-    slurs = new Map(); // number → is active
-    wedges = new Map(); // number → type
-    ties = new Map(); // pitch key → is active
-    // Slur tracking
-    startSlur(number = 1) {
-        this.slurs.set(number, true);
-    }
-    stopSlur(number = 1) {
-        const wasActive = this.slurs.has(number);
-        this.slurs.delete(number);
-        return wasActive;
-    }
-    isSlurActive(number = 1) {
-        return this.slurs.has(number);
-    }
-    // Wedge (hairpin) tracking
-    startWedge(type, number = 1) {
-        this.wedges.set(number, type);
-    }
-    stopWedge(number = 1) {
-        const type = this.wedges.get(number);
-        this.wedges.delete(number);
-        return type;
-    }
-    // Tie tracking (by pitch)
-    pitchKey(pitch) {
-        return `${pitch.phonet}${pitch.accidental || ''}${pitch.octave}`;
-    }
-    startTie(pitch) {
-        this.ties.set(this.pitchKey(pitch), true);
-    }
-    stopTie(pitch) {
-        const key = this.pitchKey(pitch);
-        const wasActive = this.ties.has(key);
-        this.ties.delete(key);
-        return wasActive;
-    }
-    isTieActive(pitch) {
-        return this.ties.has(this.pitchKey(pitch));
-    }
-    // Reset all trackers (for new part)
-    reset() {
-        this.slurs.clear();
-        this.wedges.clear();
-        this.ties.clear();
-    }
-}
-// ============ Tuplet Tracker ============
-/**
- * Track tuplet groups by number attribute.
- * Collects notes between tuplet start and stop to create TupletEvent.
- */
-class TupletTracker {
-    // Map from tuplet number to collected events and ratio
-    activeTuplets = new Map();
-    /**
-     * Start a new tuplet group
-     */
-    startTuplet(number = 1) {
-        this.activeTuplets.set(number, { events: [] });
-    }
-    /**
-     * Add an event to active tuplet(s)
-     * Returns true if the event was added to at least one tuplet
-     */
-    addEvent(event) {
-        if (this.activeTuplets.size === 0)
-            return false;
-        // Add to all active tuplets (in case of nested tuplets)
-        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);
-        }
-        return true;
-    }
-    /**
-     * Stop a tuplet group and return the TupletEvent
-     */
-    stopTuplet(number = 1) {
-        const tuplet = this.activeTuplets.get(number);
-        if (!tuplet || tuplet.events.length === 0) {
-            this.activeTuplets.delete(number);
-            return undefined;
-        }
-        this.activeTuplets.delete(number);
-        // Default ratio if not set (shouldn't happen normally)
-        const ratio = tuplet.ratio || { numerator: 2, denominator: 3 };
-        return {
-            type: 'tuplet',
-            ratio,
-            events: tuplet.events,
-        };
-    }
-    /**
-     * Check if any tuplet is active
-     */
-    isActive() {
-        return this.activeTuplets.size > 0;
-    }
-    /**
-     * Reset tracker
-     */
-    reset() {
-        this.activeTuplets.clear();
-    }
-}
-class VoiceTracker {
-    voices = new Map();
-    currentPosition = 0;
-    divisions = 1;
-    staves = 1;
-    currentStaff = new Map();
-    setDivisions(div) {
-        this.divisions = div;
-    }
-    getDivisions() {
-        return this.divisions;
-    }
-    setStaves(n) {
-        this.staves = n;
-    }
-    getStaves() {
-        return this.staves;
-    }
-    getOrCreateVoice(voiceNum, staff = 1) {
-        if (!this.voices.has(voiceNum)) {
-            this.voices.set(voiceNum, {
-                events: [],
-                staff,
-            });
-            this.currentStaff.set(voiceNum, staff);
-        }
-        const voice = this.voices.get(voiceNum);
-        // Update staff if specified
-        if (staff > 0) {
-            voice.staff = staff;
-        }
-        return voice;
-    }
-    addEvent(voiceNum, event, duration, staff = 1) {
-        const voice = this.getOrCreateVoice(voiceNum, staff);
-        const prevStaff = this.currentStaff.get(voiceNum) || 1;
-        if (staff > 0 && staff !== prevStaff) {
-            voice.events.push({ type: 'context', staff });
-            this.currentStaff.set(voiceNum, staff);
-        }
-        voice.events.push(event);
-        voice.lastEvent = event;
-        this.currentPosition += duration;
-    }
-    getLastEvent(voiceNum) {
-        const voice = this.voices.get(voiceNum);
-        return voice?.lastEvent;
-    }
-    backup(duration) {
-        this.currentPosition -= duration;
-        // Note: Negative position is OK - it just means we're going back
-        // to write a different voice
-    }
-    forward(duration) {
-        this.currentPosition += duration;
-    }
-    getCurrentPosition() {
-        return this.currentPosition;
-    }
-    getVoices() {
-        return this.voices;
-    }
-    getVoiceNumbers() {
-        return Array.from(this.voices.keys()).sort((a, b) => a - b);
-    }
-    reset() {
-        this.voices.clear();
-        this.currentPosition = 0;
-        this.currentStaff.clear();
-    }
-}
-// ============ XML Parsing Functions ============
-/**
- * Parse <pitch> element to MusicXmlPitch (raw data)
- */
-const parsePitchRaw = (pitchEl) => {
-    const step = getElementText(pitchEl, 'step');
-    const octave = getElementInt(pitchEl, 'octave');
-    const alter = getElementInt(pitchEl, 'alter');
-    if (!step || octave === undefined) {
-        return undefined;
-    }
-    return { step, alter, octave };
-};
-/**
- * Convert MusicXmlPitch to Lilylet Pitch
- */
-const musicXmlPitchToLilylet = (xmlPitch) => {
-    return convertPitch(xmlPitch.step, xmlPitch.alter, xmlPitch.octave);
-};
-/**
- * Parse <notations> element
- */
-const parseNotations = (notationsEl) => {
-    const result = {};
-    // Ties
-    const tieEls = getElements(notationsEl, 'tied');
-    if (tieEls.length > 0) {
-        result.ties = tieEls.map(el => ({
-            type: getAttribute(el, 'type'),
-        }));
-    }
-    // Slurs
-    const slurEls = getElements(notationsEl, 'slur');
-    if (slurEls.length > 0) {
-        result.slurs = slurEls.map(el => ({
-            type: getAttribute(el, 'type'),
-            number: getAttributeNumber(el, 'number') || 1,
-        }));
-    }
-    // Articulations
-    const articulationsEl = notationsEl.getElementsByTagName('articulations')[0];
-    if (articulationsEl) {
-        const articulations = [];
-        for (const child of getChildElements(articulationsEl)) {
-            articulations.push(child.tagName);
-        }
-        if (articulations.length > 0) {
-            result.articulations = articulations;
-        }
-    }
-    // Ornaments
-    const ornamentsEl = notationsEl.getElementsByTagName('ornaments')[0];
-    if (ornamentsEl) {
-        const ornaments = [];
-        for (const child of getChildElements(ornamentsEl)) {
-            ornaments.push(child.tagName);
-        }
-        if (ornaments.length > 0) {
-            result.ornaments = ornaments;
-        }
-    }
-    // Fermata
-    if (hasElement(notationsEl, 'fermata')) {
-        result.fermata = true;
-    }
-    // Arpeggiate
-    if (hasElement(notationsEl, 'arpeggiate')) {
-        result.arpeggiate = true;
-    }
-    // Tremolo
-    const tremoloEl = notationsEl.getElementsByTagName('tremolo')[0];
-    if (tremoloEl) {
-        const tremoloType = getAttribute(tremoloEl, 'type') || 'single';
-        const tremoloValue = parseInt(tremoloEl.textContent || '3', 10);
-        result.tremolo = { type: tremoloType, value: tremoloValue };
-    }
-    // Tuplet
-    const tupletEl = notationsEl.getElementsByTagName('tuplet')[0];
-    if (tupletEl) {
-        result.tuplet = {
-            type: getAttribute(tupletEl, 'type'),
-            number: getAttributeNumber(tupletEl, 'number') || 1,
-        };
-    }
-    return result;
-};
-/**
- * Parse <note> element
- */
-const parseNote = (noteEl, divisions) => {
-    const isChord = hasElement(noteEl, 'chord');
-    const isRest = hasElement(noteEl, 'rest');
-    const isGrace = hasElement(noteEl, 'grace');
-    let pitch;
-    const pitchEl = noteEl.getElementsByTagName('pitch')[0];
-    if (pitchEl) {
-        pitch = parsePitchRaw(pitchEl);
-    }
-    // Duration
-    const durationVal = getElementInt(noteEl, 'duration') || 0;
-    const typeText = getElementText(noteEl, 'type');
-    const dotCount = getElements(noteEl, 'dot').length;
-    // Time modification (tuplets)
-    let timeModification;
-    const timeModEl = noteEl.getElementsByTagName('time-modification')[0];
-    if (timeModEl) {
-        const actual = getElementInt(timeModEl, 'actual-notes');
-        const normal = getElementInt(timeModEl, 'normal-notes');
-        if (actual && normal) {
-            timeModification = { actualNotes: actual, normalNotes: normal };
-        }
-    }
-    const duration = convertDuration(divisions, durationVal, typeText, dotCount, timeModification);
-    // Voice and staff
-    const voice = getElementInt(noteEl, 'voice') || 1;
-    const staff = getElementInt(noteEl, 'staff');
-    // Stem direction
-    const stemText = getElementText(noteEl, 'stem');
-    const stem = stemText ? convertStemDirection(stemText) : undefined;
-    // Notations
-    let notations;
-    const notationsEl = noteEl.getElementsByTagName('notations')[0];
-    if (notationsEl) {
-        notations = parseNotations(notationsEl);
-    }
-    // Fingering
-    let fingering;
-    const technicalEl = noteEl.getElementsByTagName('technical')[0];
-    if (technicalEl) {
-        const fingeringText = getElementText(technicalEl, 'fingering');
-        if (fingeringText) {
-            fingering = parseInt(fingeringText, 10);
-        }
-    }
-    // Beams - direct children of note, not in notations
-    // We only care about primary beam (number="1") for begin/end
-    let beams;
-    const beamEls = getElements(noteEl, 'beam');
-    if (beamEls.length > 0) {
-        beams = beamEls.map(el => ({
-            type: (el.textContent?.trim() || 'continue'),
-            number: getAttributeNumber(el, 'number') || 1,
-        }));
-    }
-    return {
-        isChord,
-        isRest,
-        isGrace,
-        pitch,
-        duration: {
-            divisions: durationVal,
-            type: typeText,
-            dots: dotCount,
-            timeModification,
-        },
-        voice,
-        staff,
-        stem: stem,
-        notations,
-        fingering,
-        beams,
-    };
-};
-/**
- * Parse <attributes> element
- */
-const parseAttributes = (attrEl) => {
-    const result = {};
-    // Divisions
-    const divisions = getElementInt(attrEl, 'divisions');
-    if (divisions !== undefined) {
-        result.divisions = divisions;
-    }
-    // Key
-    const keyEl = attrEl.getElementsByTagName('key')[0];
-    if (keyEl) {
-        const fifths = getElementInt(keyEl, 'fifths');
-        const mode = getElementText(keyEl, 'mode');
-        if (fifths !== undefined) {
-            result.key = { fifths, mode };
-        }
-    }
-    // Time
-    const timeEl = attrEl.getElementsByTagName('time')[0];
-    if (timeEl) {
-        const beats = getElementInt(timeEl, 'beats');
-        const beatType = getElementInt(timeEl, 'beat-type');
-        if (beats !== undefined && beatType !== undefined) {
-            result.time = { beats, beatType };
-        }
-    }
-    // Clefs - handle multiple clefs for different staves
-    const clefEls = getElements(attrEl, 'clef');
-    if (clefEls.length > 0) {
-        result.clefs = [];
-        for (const clefEl of clefEls) {
-            const sign = getElementText(clefEl, 'sign');
-            const line = getElementInt(clefEl, 'line');
-            const octaveChange = getElementInt(clefEl, 'clef-octave-change');
-            const staffNum = getAttributeNumber(clefEl, 'number') || 1;
-            if (sign) {
-                result.clefs.push({
-                    staff: staffNum,
-                    clef: { sign, line, clefOctaveChange: octaveChange },
-                });
-            }
-        }
-    }
-    // Staves
-    const staves = getElementInt(attrEl, 'staves');
-    if (staves !== undefined) {
-        result.staves = staves;
-    }
-    return result;
-};
-/**
- * Parse <direction> element
- */
-const parseDirection = (dirEl) => {
-    const result = {};
-    result.placement = getAttribute(dirEl, 'placement');
-    result.staff = getElementInt(dirEl, 'staff');
-    const dirTypeEl = dirEl.getElementsByTagName('direction-type')[0];
-    if (!dirTypeEl) {
-        return result;
-    }
-    // Dynamics
-    const dynamicsEl = dirTypeEl.getElementsByTagName('dynamics')[0];
-    if (dynamicsEl) {
-        const dynamics = [];
-        for (const child of getChildElements(dynamicsEl)) {
-            dynamics.push({ type: child.tagName });
-        }
-        if (dynamics.length > 0) {
-            result.dynamics = dynamics;
-        }
-    }
-    // Wedge (hairpin)
-    const wedgeEl = dirTypeEl.getElementsByTagName('wedge')[0];
-    if (wedgeEl) {
-        const type = getAttribute(wedgeEl, 'type');
-        const number = getAttributeNumber(wedgeEl, 'number');
-        if (type) {
-            result.wedge = { type, number };
-        }
-    }
-    // Pedal
-    const pedalEl = dirTypeEl.getElementsByTagName('pedal')[0];
-    if (pedalEl) {
-        const type = getAttribute(pedalEl, 'type');
-        const line = getAttribute(pedalEl, 'line') === 'yes';
-        if (type) {
-            result.pedal = { type, line };
-        }
-    }
-    // Metronome
-    const metronomeEl = dirTypeEl.getElementsByTagName('metronome')[0];
-    if (metronomeEl) {
-        const beatUnit = getElementText(metronomeEl, 'beat-unit');
-        const beatUnitDot = hasElement(metronomeEl, 'beat-unit-dot');
-        const perMinute = getElementInt(metronomeEl, 'per-minute');
-        if (beatUnit && perMinute !== undefined) {
-            result.metronome = { beatUnit, beatUnitDot, perMinute };
-        }
-    }
-    // Words
-    const wordsEls = getElements(dirTypeEl, 'words');
-    if (wordsEls.length > 0) {
-        result.words = wordsEls.map(el => ({
-            text: el.textContent || '',
-            fontStyle: getAttribute(el, 'font-style'),
-            fontWeight: getAttribute(el, 'font-weight'),
-        }));
-    }
-    // Octave shift
-    const octaveShiftEl = dirTypeEl.getElementsByTagName('octave-shift')[0];
-    if (octaveShiftEl) {
-        const type = getAttribute(octaveShiftEl, 'type');
-        const size = getAttributeNumber(octaveShiftEl, 'size');
-        if (type) {
-            result.octaveShift = { type, size };
-        }
-    }
-    // Coda and Segno
-    if (hasElement(dirTypeEl, 'coda')) {
-        result.coda = true;
-    }
-    if (hasElement(dirTypeEl, 'segno')) {
-        result.segno = true;
-    }
-    return result;
-};
-/**
- * Parse <barline> element
- */
-const parseBarline = (barlineEl) => {
-    const result = {};
-    result.location = getAttribute(barlineEl, 'location');
-    result.barStyle = getElementText(barlineEl, 'bar-style');
-    const repeatEl = barlineEl.getElementsByTagName('repeat')[0];
-    if (repeatEl) {
-        const direction = getAttribute(repeatEl, 'direction');
-        if (direction) {
-            result.repeat = { direction };
-        }
-    }
-    const endingEl = barlineEl.getElementsByTagName('ending')[0];
-    if (endingEl) {
-        const type = getAttribute(endingEl, 'type');
-        const number = getAttribute(endingEl, 'number') || '1';
-        if (type) {
-            result.ending = { type, number };
-        }
-    }
-    return result;
-};
-/**
- * Parse <harmony> element
- */
-const parseHarmony = (harmonyEl) => {
-    const rootEl = harmonyEl.getElementsByTagName('root')[0];
-    if (!rootEl) {
-        return undefined;
-    }
-    const rootStep = getElementText(rootEl, 'root-step');
-    const rootAlter = getElementInt(rootEl, 'root-alter');
-    if (!rootStep) {
-        return undefined;
-    }
-    const kind = getElementText(harmonyEl, 'kind') || 'major';
-    const result = {
-        root: { step: rootStep, alter: rootAlter },
-        kind,
-    };
-    const bassEl = harmonyEl.getElementsByTagName('bass')[0];
-    if (bassEl) {
-        const bassStep = getElementText(bassEl, 'bass-step');
-        const bassAlter = getElementInt(bassEl, 'bass-alter');
-        if (bassStep) {
-            result.bass = { step: bassStep, alter: bassAlter };
-        }
-    }
-    return result;
-};
-/**
- * Parse metadata from score header
- */
-const parseMetadata = (doc) => {
-    const metadata = {};
-    // Work title
-    const workTitleEl = doc.getElementsByTagName('work-title')[0];
-    if (workTitleEl?.textContent) {
-        metadata.title = workTitleEl.textContent.trim();
-    }
-    // Movement title (fallback for title)
-    const movementTitleEl = doc.getElementsByTagName('movement-title')[0];
-    if (movementTitleEl?.textContent && !metadata.title) {
-        metadata.title = movementTitleEl.textContent.trim();
-    }
-    // Identification (composer, arranger, lyricist)
-    const identificationEl = doc.getElementsByTagName('identification')[0];
-    if (identificationEl) {
-        const creators = getElements(identificationEl, 'creator');
-        for (const creator of creators) {
-            const type = getAttribute(creator, 'type');
-            const text = creator.textContent?.trim();
-            if (text) {
-                if (type === 'composer') {
-                    metadata.composer = text;
-                }
-                else if (type === 'arranger') {
-                    metadata.arranger = text;
-                }
-                else if (type === 'lyricist' || type === 'poet') {
-                    metadata.lyricist = text;
-                }
-            }
-        }
-    }
-    return Object.keys(metadata).length > 0 ? metadata : {};
-};
-// ============ Conversion Functions ============
-/**
- * Convert MusicXML notations to Lilylet marks
- */
-const notationsToMarks = (notations, spannerTracker, pitches) => {
-    const marks = [];
-    if (!notations) {
-        return marks;
-    }
-    // Ties
-    if (notations.ties) {
-        for (const tie of notations.ties) {
-            if (tie.type === 'start') {
-                marks.push({ markType: 'tie', start: true });
-                // Track tie for each pitch
-                for (const p of pitches) {
-                    spannerTracker.startTie(p);
-                }
-            }
-            // Note: tie stop doesn't need an explicit mark in Lilylet
-        }
-    }
-    // Slurs
-    if (notations.slurs) {
-        for (const slur of notations.slurs) {
-            if (slur.type === 'start') {
-                marks.push({ markType: 'slur', start: true });
-                spannerTracker.startSlur(slur.number);
-            }
-            else if (slur.type === 'stop') {
-                if (spannerTracker.stopSlur(slur.number)) {
-                    marks.push({ markType: 'slur', start: false });
-                }
-            }
-        }
-    }
-    // Articulations
-    if (notations.articulations) {
-        for (const artName of notations.articulations) {
-            const artType = convertArticulation(artName);
-            if (artType) {
-                marks.push({ markType: 'articulation', type: artType });
-            }
-        }
-    }
-    // Ornaments
-    if (notations.ornaments) {
-        for (const ornName of notations.ornaments) {
-            const ornType = convertOrnament(ornName);
-            if (ornType) {
-                marks.push({ markType: 'ornament', type: ornType });
-            }
-        }
-    }
-    // Fermata
-    if (notations.fermata) {
-        marks.push({ markType: 'ornament', type: 'fermata' });
-    }
-    // Arpeggiate
-    if (notations.arpeggiate) {
-        marks.push({ markType: 'ornament', type: 'arpeggio' });
-    }
-    return marks;
-};
-// Common tempo words that should be converted to \tempo
-const TEMPO_WORDS = new Set([
-    // Very slow
-    'largo', 'larghetto', 'grave', 'lento', 'adagio',
-    // Slow
-    'andante', 'andantino',
-    // Moderate
-    'moderato', 'allegretto',
-    // Fast
-    'allegro', 'vivace', 'presto', 'prestissimo',
-    // Other tempo indications
-    'tempo', 'a tempo', 'tempo i', 'tempo primo',
-    // With modifiers (partial matches)
-]);
-/**
- * Check if text is a tempo word
- */
-const isTempoWord = (text) => {
-    const lower = text.toLowerCase().trim();
-    // Check exact match
-    if (TEMPO_WORDS.has(lower))
-        return true;
-    // Check if starts with tempo word (e.g., "Allegro moderato", "Andante con moto")
-    for (const word of TEMPO_WORDS) {
-        if (lower.startsWith(word))
-            return true;
-    }
-    return false;
-};
-/**
- * Convert direction to context change (tempo, ottava)
- */
-const directionToContextChange = (direction, ottavaTracker) => {
-    // Metronome → Tempo (may combine with words)
-    if (direction.metronome) {
-        const { beatUnit, beatUnitDot, perMinute } = direction.metronome;
-        const division = TYPE_TO_DIVISION[beatUnit] || 4;
-        // Check if there's accompanying tempo text
-        let tempoText;
-        if (direction.words && direction.words.length > 0) {
-            const text = direction.words[0].text.trim();
-            if (isTempoWord(text)) {
-                tempoText = text;
-            }
-        }
-        return {
-            type: 'context',
-            tempo: {
-                text: tempoText,
-                beat: {
-                    division,
-                    dots: beatUnitDot ? 1 : 0,
-                },
-                bpm: perMinute,
-            },
-        };
-    }
-    // Words alone that are tempo indications → Tempo (text only)
-    if (direction.words && direction.words.length > 0 && !direction.metronome) {
-        const text = direction.words[0].text.trim();
-        if (isTempoWord(text)) {
-            return {
-                type: 'context',
-                tempo: {
-                    text,
-                },
-            };
-        }
-    }
-    // Octave shift → Ottava
-    if (direction.octaveShift) {
-        const { type, size = 8 } = direction.octaveShift;
-        let ottava;
-        if (type === 'stop') {
-            ottava = 0;
-            ottavaTracker.current = 0;
-        }
-        else if (type === 'down') {
-            // 8va = 1, 15ma = 2 (type="down" means written notes sound higher)
-            ottava = size === 15 ? 2 : 1;
-            ottavaTracker.current = ottava;
-        }
-        else if (type === 'up') {
-            // 8vb = -1, 15mb = -2 (type="up" means written notes sound lower)
-            ottava = size === 15 ? -2 : -1;
-            ottavaTracker.current = ottava;
-        }
-        else {
-            return undefined;
-        }
-        return {
-            type: 'context',
-            ottava,
-        };
-    }
-    return undefined;
-};
-/**
- * Convert direction to marks
- */
-const directionToMarks = (direction, spannerTracker) => {
-    const marks = [];
-    // Dynamics
-    if (direction.dynamics) {
-        for (const dyn of direction.dynamics) {
-            const dynType = convertDynamic(dyn.type);
-            if (dynType) {
-                marks.push({ markType: 'dynamic', type: dynType });
-            }
-        }
-    }
-    // Wedge (hairpin)
-    if (direction.wedge) {
-        const { type, number = 1 } = direction.wedge;
-        if (type === 'crescendo') {
-            marks.push({ markType: 'hairpin', type: HairpinType.crescendoStart });
-            spannerTracker.startWedge('crescendo', number);
-        }
-        else if (type === 'diminuendo') {
-            marks.push({ markType: 'hairpin', type: HairpinType.diminuendoStart });
-            spannerTracker.startWedge('diminuendo', number);
-        }
-        else if (type === 'stop') {
-            const wedgeType = spannerTracker.stopWedge(number);
-            if (wedgeType === 'crescendo') {
-                marks.push({ markType: 'hairpin', type: HairpinType.crescendoEnd });
-            }
-            else if (wedgeType === 'diminuendo') {
-                marks.push({ markType: 'hairpin', type: HairpinType.diminuendoEnd });
-            }
-            else {
-                // Unknown wedge type, default to crescendo end
-                marks.push({ markType: 'hairpin', type: HairpinType.crescendoEnd });
-            }
-        }
-    }
-    // Pedal
-    if (direction.pedal) {
-        const pedalType = convertPedal(direction.pedal.type);
-        if (pedalType) {
-            marks.push({ markType: 'pedal', type: pedalType });
-        }
-    }
-    // Coda
-    if (direction.coda) {
-        marks.push({ markType: 'navigation', type: NavigationMarkType.coda });
-    }
-    // Segno
-    if (direction.segno) {
-        marks.push({ markType: 'navigation', type: NavigationMarkType.segno });
-    }
-    return marks;
-};
-/**
- * Convert a MusicXML measure to Lilylet events, grouped by voice
- */
-const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker) => {
-    let key;
-    let timeSig;
-    let barline;
-    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
-    const pendingContextChanges = [];
-    let currentVoice = 1; // Track current voice for directions
-    // Process all children in order
-    for (const child of getChildElements(measureEl)) {
-        const tagName = child.tagName;
-        if (tagName === 'attributes') {
-            const attrs = parseAttributes(child);
-            if (attrs.divisions !== undefined) {
-                voiceTracker.setDivisions(attrs.divisions);
-            }
-            if (attrs.staves !== undefined) {
-                voiceTracker.setStaves(attrs.staves);
-            }
-            // Key signature
-            if (attrs.key) {
-                key = convertKeySignature(attrs.key.fifths, attrs.key.mode);
-            }
-            // Time signature
-            if (attrs.time) {
-                timeSig = createFraction(attrs.time.beats, attrs.time.beatType);
-            }
-            // Clefs - store by staff number
-            if (attrs.clefs) {
-                for (const clefEntry of attrs.clefs) {
-                    const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
-                    if (clef) {
-                        clefs.set(clefEntry.staff, { type: 'context', clef });
-                    }
-                }
-            }
-        }
-        else if (tagName === 'note') {
-            const note = parseNote(child, voiceTracker.getDivisions());
-            const voiceNum = note.voice;
-            const staffNum = note.staff || 1;
-            currentVoice = 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);
-            // Check for tuplet start BEFORE processing the note
-            const tupletNotation = note.notations?.tuplet;
-            if (tupletNotation?.type === 'start') {
-                tupletTracker.startTuplet(tupletNotation.number);
-            }
-            // Add any pending context changes before the note (tempo, ottava)
-            if (pendingContextChanges.length > 0) {
-                for (const ctx of pendingContextChanges) {
-                    voiceTracker.addEvent(voiceNum, ctx, 0, staffNum);
-                }
-                pendingContextChanges.length = 0; // Clear
-            }
-            // Get pending marks for this voice
-            const marks = pendingMarks.get(voiceNum) || [];
-            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);
-                const restEvent = {
-                    type: 'rest',
-                    duration,
-                };
-                // 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);
-                }
-                else {
-                    voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
-                }
-            }
-            else if (note.pitch) {
-                // Note or chord - convert MusicXmlPitch to Lilylet Pitch
-                const lilyletPitch = musicXmlPitchToLilylet(note.pitch);
-                // 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 });
-                }
-                // Handle chord: merge with previous note in same voice
-                if (note.isChord) {
-                    const lastEvent = voiceTracker.getLastEvent(voiceNum);
-                    if (lastEvent && lastEvent.type === 'note') {
-                        lastEvent.pitches.push(lilyletPitch);
-                        // Merge marks
-                        if (marks.length > 0) {
-                            lastEvent.marks = [...(lastEvent.marks || []), ...marks];
-                        }
-                        continue; // Don't create a new event
-                    }
-                }
-                const duration = convertDuration(voiceTracker.getDivisions(), note.duration.divisions, note.duration.type, note.duration.dots, note.duration.timeModification);
-                const noteEvent = {
-                    type: 'note',
-                    pitches: [lilyletPitch],
-                    duration,
-                    grace: note.isGrace || undefined,
-                    staff: staffNum > 1 ? staffNum : undefined, // Only include if cross-staff
-                    stemDirection: note.stem ? convertStemDirection(note.stem) : undefined,
-                };
-                // Add single tremolo
-                if (note.notations?.tremolo?.type === 'single') {
-                    // Convert tremolo value (number of beams) to division
-                    // 1 beam = 8th, 2 beams = 16th, 3 beams = 32nd
-                    noteEvent.tremolo = Math.pow(2, note.notations.tremolo.value + 2);
-                }
-                // Add beam marks - only care about primary beam (number=1)
-                if (note.beams) {
-                    const primaryBeam = note.beams.find(b => b.number === 1);
-                    if (primaryBeam) {
-                        if (primaryBeam.type === 'begin') {
-                            marks.push({ markType: 'beam', start: true });
-                        }
-                        else if (primaryBeam.type === 'end') {
-                            marks.push({ markType: 'beam', start: false });
-                        }
-                        // 'continue' doesn't need a mark
-                    }
-                }
-                if (marks.length > 0) {
-                    noteEvent.marks = marks;
-                }
-                // 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);
-                }
-                else {
-                    voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
-                }
-            }
-            // Check for tuplet stop AFTER processing the note
-            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;
-                    voiceTracker.addEvent(voiceNum, tupletEvent, totalDuration, staffNum);
-                }
-            }
-        }
-        else if (tagName === 'direction') {
-            const direction = parseDirection(child);
-            // Handle context changes (tempo, ottava)
-            const contextChange = directionToContextChange(direction, ottavaTracker);
-            if (contextChange) {
-                pendingContextChanges.push(contextChange);
-            }
-            // Handle marks (dynamics, hairpins, etc.)
-            const marks = directionToMarks(direction, spannerTracker);
-            if (marks.length > 0) {
-                // Store marks to attach to next note in current voice
-                const existing = pendingMarks.get(currentVoice) || [];
-                pendingMarks.set(currentVoice, [...existing, ...marks]);
-            }
-        }
-        else if (tagName === 'backup') {
-            const duration = getElementInt(child, 'duration') || 0;
-            voiceTracker.backup(duration);
-        }
-        else if (tagName === 'forward') {
-            const duration = getElementInt(child, 'duration') || 0;
-            voiceTracker.forward(duration);
-        }
-        else if (tagName === 'barline') {
-            const barlineData = parseBarline(child);
-            const style = convertBarlineStyle(barlineData.barStyle, barlineData.repeat?.direction);
-            if (style && style !== '|') {
-                barline = { type: 'barline', style };
-            }
-        }
-        else if (tagName === 'harmony') {
-            const harmonyData = parseHarmony(child);
-            if (harmonyData) {
-                const text = convertHarmonyToText(harmonyData.root.step, harmonyData.root.alter, harmonyData.kind, harmonyData.bass?.step, harmonyData.bass?.alter);
-                harmonies.push({ type: 'harmony', text });
-            }
-        }
-    }
-    // Build voice map from tracker
-    const voiceMap = new Map();
-    for (const [voiceNum, voiceState] of voiceTracker.getVoices()) {
-        voiceMap.set(voiceNum, {
-            events: voiceState.events,
-            staff: voiceState.staff,
-        });
-    }
-    return { voiceMap, key, timeSig, barline, harmonies, clefs };
-};
-/**
- * Convert a MusicXML part to Lilylet measures
- */
-const convertPart = (partEl) => {
-    const measures = [];
-    const voiceTracker = new VoiceTracker();
-    const spannerTracker = new SpannerTracker();
-    const ottavaTracker = { current: 0 };
-    const tupletTracker = new TupletTracker();
-    let lastKey;
-    let lastTimeSig;
-    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
-    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);
-        // Update running key/time
-        if (key)
-            lastKey = key;
-        if (timeSig)
-            lastTimeSig = timeSig;
-        // Build voices from voice map, sorted by voice number
-        const voiceNumbers = Array.from(voiceMap.keys()).sort((a, b) => a - b);
-        const voices = [];
-        // Track which staves have had clef added (for this measure)
-        const staffsWithClef = new Set();
-        for (const voiceNum of voiceNumbers) {
-            const voiceData = voiceMap.get(voiceNum);
-            const events = [];
-            // Add clef at start of first voice for each staff
-            // For first measure: always add initial clef
-            // For subsequent measures: add clef if there's a clef change
-            if (!staffsWithClef.has(voiceData.staff)) {
-                const clef = clefs.get(voiceData.staff);
-                if (clef) {
-                    // Check if this is a clef change (not first measure) or initial clef (first measure)
-                    if (isFirstMeasure) {
-                        events.push(clef);
-                        lastClefs.set(voiceData.staff, clef);
-                    }
-                    else {
-                        // Only add if it's different from the last clef for this staff
-                        const lastClef = lastClefs.get(voiceData.staff);
-                        const isSameClef = lastClef &&
-                            lastClef.clef === clef.clef;
-                        if (!isSameClef) {
-                            events.push(clef);
-                            lastClefs.set(voiceData.staff, clef);
-                        }
-                    }
-                }
-                staffsWithClef.add(voiceData.staff);
-            }
-            // Add voice events
-            events.push(...voiceData.events);
-            // Add harmonies and barline to first voice only
-            if (voiceNum === voiceNumbers[0]) {
-                for (const h of harmonies) {
-                    events.push(h);
-                }
-                if (barline) {
-                    events.push(barline);
-                }
-            }
-            voices.push({
-                staff: voiceData.staff,
-                events,
-            });
-        }
-        // If no voices found, create an empty one
-        if (voices.length === 0) {
-            voices.push({ staff: lastVoiceStaff, events: [] });
-        }
-        else {
-            lastVoiceStaff = voices[0].staff || 1;
-        }
-        const measure = {
-            parts: [{
-                    voices,
-                }],
-        };
-        // Only include key/time if they changed
-        if (key)
-            measure.key = key;
-        if (timeSig)
-            measure.timeSig = timeSig;
-        measures.push(measure);
-        isFirstMeasure = false;
-    }
-    return { measures };
-};
-// ============ Main Decoder Function ============
-/**
- * Decode MusicXML string to LilyletDoc
- */
-export const decode = (xmlString) => {
-    const parser = new DOMParser();
-    const doc = parser.parseFromString(xmlString, 'application/xml');
-    // Check for parsing errors
-    const parseError = doc.getElementsByTagName('parsererror')[0];
-    if (parseError) {
-        throw new Error(`XML parsing error: ${parseError.textContent}`);
-    }
-    // Get root element
-    const root = doc.documentElement;
-    if (!root || (root.tagName !== 'score-partwise' && root.tagName !== 'score-timewise')) {
-        throw new Error(`Invalid MusicXML: expected score-partwise or score-timewise, got ${root?.tagName}`);
-    }
-    // Parse metadata
-    const metadata = parseMetadata(doc);
-    // Parse <part-list> to get part names
-    const partNames = new Map();
-    const partListEl = doc.getElementsByTagName('part-list')[0];
-    if (partListEl) {
-        const scorePartEls = getElements(partListEl, 'score-part');
-        for (const sp of scorePartEls) {
-            const id = getAttribute(sp, 'id');
-            const name = getElementText(sp, 'part-name');
-            if (id && name) {
-                partNames.set(id, name);
-            }
-        }
-    }
-    // Get parts
-    const partEls = getDirectChildren(root, 'part');
-    if (partEls.length === 0) {
-        throw new Error('No parts found in MusicXML');
-    }
-    // Convert all parts
-    const allPartResults = [];
-    for (const partEl of partEls) {
-        const partId = getAttribute(partEl, 'id') || undefined;
-        const { measures } = convertPart(partEl);
-        const name = partId ? partNames.get(partId) : undefined;
-        allPartResults.push({ measures, name, partId });
-    }
-    // Merge parts: combine into multi-part measures
-    const numMeasures = Math.max(...allPartResults.map(p => p.measures.length));
-    const mergedMeasures = [];
-    for (let mi = 0; mi < numMeasures; mi++) {
-        const parts = [];
-        for (const partResult of allPartResults) {
-            const sourceMeasure = partResult.measures[mi];
-            if (sourceMeasure && sourceMeasure.parts.length > 0) {
-                const part = sourceMeasure.parts[0];
-                if (partResult.name) {
-                    part.name = partResult.name;
-                }
-                parts.push(part);
-            }
-            else {
-                // Empty part placeholder
-                parts.push({ voices: [{ staff: 1, events: [] }] });
-            }
-        }
-        // Use key/timeSig from the first part's measure (they should be consistent)
-        const firstPartMeasure = allPartResults[0].measures[mi];
-        const measure = { parts };
-        if (firstPartMeasure?.key)
-            measure.key = firstPartMeasure.key;
-        if (firstPartMeasure?.timeSig)
-            measure.timeSig = firstPartMeasure.timeSig;
-        mergedMeasures.push(measure);
-    }
-    const result = {
-        measures: mergedMeasures,
-    };
-    if (Object.keys(metadata).length > 0) {
-        result.metadata = metadata;
-    }
-    return result;
-};
-/**
- * Decode MusicXML file to LilyletDoc
- */
-export const decodeFile = async (filePath) => {
-    const fs = await import('fs/promises');
-    const content = await fs.readFile(filePath, 'utf-8');
-    return decode(content);
-};
-export default {
-    decode,
-    decodeFile,
-};